Skip to content

Tighten blog comments that are inaccurate, rot-prone, or exceed AGENTS.md "one short line max" #68

Closed

Description

@thiras

AGENTS.md states comments should default to "one short line max." Several comments added in #61 deviate — some are also factually wrong or contain references that will rot.

Inaccurate

  • `components/site/Chrome.tsx:8-12` — claims a bare `#section` from `/blog/foo/` would resolve to `/blog/#section`. It actually resolves to `/blog/foo/#section` (fragment-only hrefs resolve against the current URL, not the parent path). The leading-slash point is correct; just fix the example.
  • `lib/blog.ts:16-19` (`Slug` brand) — claims two constructor sites, `parseSlug` and `parseEntry`. Only `parseSlug` holds the `as Slug` cast; `parseEntry` is a strict consumer that throws on null. Rephrase: "The only constructor site is `parseSlug`; `parseEntry` consumes it and throws on null."

Rot risk / over-long

  • `app/blog/page.tsx:14-21` — 8-line metadata block uses "previously left every blog route sharing a blank card." "Previously" relative to what? Tighten to 1–2 lines and drop the framing. Suggested: "`openGraph` shallow-replaces in Next 16, so re-pass `images` from `parent` or the root og image is dropped. Twitter `images` is set explicitly because the og→twitter fallback only fires at final resolution, not through `ResolvingMetadata`."
  • `lib/blog.ts:7-11` (`SLUG_RE`) — 5 lines; drops the `js/stored-xss` CodeQL rule ID which will rot when the rule is renamed or the scanner changes. Keep the invariant claim; drop the rule reference.
  • `lib/blog.ts:107-112` (memoise / "2N+3") — count is correct (verified: 3 `listPosts` callsites + 2 `getPost` callsites). 6 lines; trim the parentheticals enumerating callsites.
  • `lib/blog.ts:125-131` (sort tie-break) — 7 lines; drop the HFS+ aside (irrelevant on modern macOS = APFS).

Found during PR review of #61.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Fields

    Priority

    None yet

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions