Skip to content

chore: sweep bare issue refs from source comments; enforce in eslint - #600

Merged
goosewobbler merged 1 commit into
docs/comment-refs-as-linksfrom
chore/573-comment-ref-sweep
Jul 21, 2026
Merged

goosewobbler merged 1 commit into
docs/comment-refs-as-linksfrom
chore/573-comment-ref-sweep

Conversation

@goosewobbler

@goosewobbler goosewobbler commented Jul 21, 2026 •

Copy link
Copy Markdown
Owner

Completes #573 — the codebase sweep + enforcement, the deterministic counterpart to the AGENTS.md rework (#598) and the lint rules (#599). Stacked on #599 (needs its local/no-bare-issue-refs rule to flip to error); base retargets to main once #599 lands.

What changed

  • Dropped ~237 bare #NNN provenance citations from packages/*/src comments. Every one was a standalone origin tag (the issue a piece of code came from) — the comment reads fine without it and git history is the canonical trace. None were load-bearing (until #X / remove when #X), so none needed converting to URLs.
  • Flipped local/no-bare-issue-refs → error, scoped to packages/*/src. Test comments legitimately reference mock issue/PR data (fixture numbers, and even external-repo PRs like #224/#225 from wdio-desktop-mobile), so a releasekit-issue URL would be wrong there — the rule doesn't enforce test comments.
  • Exempted three ref-parsing files whose #NNN are format examples, not citations: changelogRefs.ts, conventional-changelog.ts, commitParser.ts.
  • Opportunistically dropped ~55 provenance refs from test comments too (cleanup, even though the rule doesn't enforce them).

Done via three parallel per-package triage passes + one test-comment pass, all applying the same drop-vs-link criteria.

Verification

  • Comment-only — confirmed the entire diff touches only comments (the sole non-comment changes are the two intentional eslint.config.js edits).
  • eslint packages/**/*.ts → 0 errors; pnpm typecheck → 15/15; biome check clean (8 pre-existing warnings).
  • Test failures in a full run (templates, sync-tags, pipeline fixture) are pre-existing/environmental — they fail identically on the base with these changes stashed.

Release

Touches packages/*/src, so — per commitParser's "every merged change is surfaced" logic — this should drive a natural standing-PR 0.41.2 once the stack merges.

🤖 Generated with Claude Code

Greptile Summary

This PR enforces linked issue references in production source comments. The main changes are:

  • Removes bare issue-number provenance tags from package comments.
  • Promotes local/no-bare-issue-refs from a warning to an error.
  • Limits enforcement to packages/**/src/**/*.ts.
  • Exempts three parsing files whose bare references are format examples.

Confidence Score: 5/5

This looks safe to merge.

  • No blocking issues found in the changed code.

Important Files Changed

Filename Overview
eslint.config.js Scopes comment-reference enforcement to production package sources and changes violations to errors.
packages/core/src/changelogRefs.ts Exempts issue-reference examples used to document rendered formats.
packages/notes/src/input/conventional-changelog.ts Exempts bare issue tokens used as parser and regular-expression examples.
packages/version/src/changelog/commitParser.ts Exempts issue-reference examples used by commit parsing logic.

Reviews (2): Last reviewed commit: "chore(573): sweep bare issue refs from s..." | Re-trigger Greptile

Base automatically changed from chore/comment-ref-lint to docs/comment-refs-as-links July 21, 2026 00:52
@goosewobbler goosewobbler changed the title chore(573): sweep bare issue refs from source comments; enforce in eslint chore: sweep bare issue refs from source comments; enforce in eslint Jul 21, 2026
…eslint

Complete the #573 comment-ref cleanup and turn on enforcement:
- Dropped ~237 bare #NNN provenance citations from packages/*/src comments
  (all were standalone origin tags; none load-bearing, so none needed URLs).
- Flipped local/no-bare-issue-refs from warn to error, scoped to packages/*/src
  — test comments legitimately reference mock issue/PR data (fixture numbers,
  external-repo PRs), so they aren't enforced.
- Exempted the three ref-parsing files whose #NNN are format examples, not
  citations: changelogRefs.ts, conventional-changelog.ts, commitParser.ts.
- Also dropped ~55 provenance refs from test comments (opportunistic cleanup).

All edits are comment-only (verified); eslint/typecheck/biome clean. The only
failing tests are pre-existing/environmental integration cases (templates,
sync-tags, pipeline fixture) that fail identically on the base.

Stacked on #599; touches packages/*/src so it drives a natural standing-PR release.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K6CmYRXTZQYs4MNo6AETxT
@goosewobbler
goosewobbler force-pushed the chore/573-comment-ref-sweep branch from d9e2db6 to 2aa40ed Compare July 21, 2026 01:10
@goosewobbler
goosewobbler merged commit c0150aa into docs/comment-refs-as-links Jul 21, 2026
4 checks passed
@goosewobbler
goosewobbler deleted the chore/573-comment-ref-sweep branch July 21, 2026 01:12
goosewobbler added a commit that referenced this pull request Jul 21, 2026
…into tooling (#598)

* docs(agents): slim AGENTS.md to non-derivable context; move test-title rule to eslint

Rework AGENTS.md around "keep only what an agent can't derive by exploring"
(auto-generated / comprehensive context files hurt agent performance):
- Cut tech-stack, monorepo tree, verification-gate, coding-standards, testing,
  and doc-table sections — all derivable from the tree / package.json / configs,
  or already enforced by tooling.
- Keep the load-bearing release invariants, the never-hand-edit generated files,
  and a pointer to architecture / ADRs.
- Move "every it/test title starts with should" into a vitest/valid-title eslint
  rule and fix the one straggler.

This supersedes the comment-ref codification (#573) that was on this branch; the
remaining #573 work (ref linkification/removal, custom comment-ref lint) and the
other deterministic replacements (pre-push hook, commitlint) move to follow-ups.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K6CmYRXTZQYs4MNo6AETxT

* chore(config): make generated files self-guarding; drop the AGENTS.md prose

Replace the "never hand-edit generated files" AGENTS.md section with deterministic
guards that fire when someone touches the file, not on every request:
- releasekit.schema.json now carries a `$comment` banner (it lacked one; the config
  docs already had theirs), so it self-documents the moment it's opened.
- docs/configuration.md gains a CI check (`docs:check`, mirroring `schema:check`) so
  a hand-edit fails the build — it previously had only the banner, no enforcement.

Both generated files now have banner (discovery) + CI check (enforcement), so the
global AGENTS.md instruction is redundant and removed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K6CmYRXTZQYs4MNo6AETxT

* chore(lint): enforce comment + test-title issue-ref conventions in eslint (#599)

The #573 comment convention becomes deterministic instead of prose (see #598):
- Custom `local/no-bare-issue-refs` eslint rule flags bare `#NNN` in comments
  (link as a full URL or drop it). Set to `warn` for now — the ~330 existing
  source-comment refs are swept in a follow-up, then it flips to `error`.
- `vitest/valid-title` gains `mustNotMatch: #\d`, so test titles carry no issue
  refs; stripped the refs from the ~50 existing titles.
- Removed a dead `eslint-disable @typescript-eslint/no-explicit-any` directive
  (that plugin was never installed) now that eslint lints package sources.

Stacked on #598 (builds on its valid-title rule). The source-comment sweep +
flip-to-error is the separate #573 PR, which touches packages/*/src.


Claude-Session: https://claude.ai/code/session_01K6CmYRXTZQYs4MNo6AETxT

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore: sweep bare issue refs from source comments; enforce in eslint (#600)

Complete the #573 comment-ref cleanup and turn on enforcement:
- Dropped ~237 bare #NNN provenance citations from packages/*/src comments
  (all were standalone origin tags; none load-bearing, so none needed URLs).
- Flipped local/no-bare-issue-refs from warn to error, scoped to packages/*/src
  — test comments legitimately reference mock issue/PR data (fixture numbers,
  external-repo PRs), so they aren't enforced.
- Exempted the three ref-parsing files whose #NNN are format examples, not
  citations: changelogRefs.ts, conventional-changelog.ts, commitParser.ts.
- Also dropped ~55 provenance refs from test comments (opportunistic cleanup).

All edits are comment-only (verified); eslint/typecheck/biome clean. The only
failing tests are pre-existing/environmental integration cases (templates,
sync-tags, pipeline fixture) that fail identically on the base.

Stacked on #599; touches packages/*/src so it drives a natural standing-PR release.


Claude-Session: https://claude.ai/code/session_01K6CmYRXTZQYs4MNo6AETxT

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore(ci): regenerate examples-smoke.yml to match the example templates

The committed smoke workflow had setup-node@v7 (bumped on the generated file)
while the source templates it is generated from are at @v6 — so
examples:smoke:check failed on every PR. Regenerate to match the source; no
template or consumer change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K6CmYRXTZQYs4MNo6AETxT

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Upgrade kept issue-reference comments to explicit hyperlinks (// see <url>)

1 participant