Skip to content

chore: purge code comments repo-wide, add comment ratchet - #14796

Merged
dylanjeffers merged 2 commits into
mainfrom
chore/comment-purge
Nov 21, 2026
Merged

dylanjeffers merged 2 commits into
mainfrom
chore/comment-purge

Conversation

@dylanjeffers

@dylanjeffers dylanjeffers commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Removes every non-exempt code comment from the apps repo and adds a CI ratchet so new ones fail. This PR now contains the folded stack: #14802 (web), #14806 (mobile) and #14811 (all remaining packages).

Result

Ratchet

  • npm run lint:comments (scripts/comment-ratchet.cjs) runs in .github/workflows/comments.yml. .comment-baseline.json is now {}, so any new non-exempt comment fails CI.
  • Exempt:
    • tool directives (eslint-disable, @ts-*, prettier-ignore, @format, bundler pragmas, globals, test-env pragmas)
    • @deprecated
    • JSDoc type annotations in plain JS
    • generator "DO NOT EDIT" headers
    • public-API JSDoc in sdk, harmony, fixed-decimal and spl
    • examples/, vendored public/ and *.min.js, and generated SDK code
  • Policy: ADR 0001. The /delete-comment skill (.claude/skills/delete-comment/) repeats the process.

Verification

Each pass was compared against a pristine checkout of its base:

  • tsc and lint: identical error sets for every touched package.
  • Tests: identical results for common, web and sdk.
  • Directive counts: identical repo-wide.
  • Mobile jest couldn't run locally (stale shared node_modules). It runs in this PR's CI now that the stack targets main.

Deploy note

Merging deploys identity-service and embed automatically. Both changes are comment-only. Web and mobile go out with the next gate and OTA as usual.

🤖 Generated with Claude Code

Deletes all 2,490 non-exempt comment blocks in packages/common.
Decision records move to docs/adr/0002-0009. Excuses are tracked in
#14793, #14794 and #14795. Tautologies and stale comments are gone.

Adds scripts/comment-ratchet.cjs with a per-file budget in
.comment-baseline.json, CI in .github/workflows/comments.yml, ADR 0001
for the policy, and the /delete-comment skill to repeat this per path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@changeset-bot

changeset-bot Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 60e57c6

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@socket-security

socket-security Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Dependency limit exceeded — report not shown.

This pull request scan exceeded the 10,000-dependency limit applied to this scan, so the results are incomplete and may be inaccurate. To avoid reporting false positives, Socket has not posted a report.

Upgrade your plan to raise the dependency limit and get complete reports, or view the partial scan in the dashboard.

Socket is always free for open source. If this is a public open source project under an OSI-approved license, contact us to request a free Business plan upgrade.

dylanjeffers added a commit that referenced this pull request Nov 21, 2026
Stacked on #14806 → #14802 → #14796. Merge in that order.

## What

The last `/delete-comment` pass. It covers every package not yet purged:
libs, identity-service, protocol-dashboard, sdk (non-public internals),
harmony, embed, es-indexer, commands, create-audius-app, migrate-tool,
docs, fixed-decimal, spl, eth, eslint-config-audius, distro and
`svgo.config.js`. **After this PR the repo has zero non-exempt comments
and `.comment-baseline.json` is `{}`.**

| Category | Blocks | Lines | Action |
| --- | ---: | ---: | --- |
| Tautology | 2,312 | 4,391 | deleted |
| Stale | 122 | 324 | deleted |
| Excuse | 107 | 167 | deleted, filed as #14807 (libs), #14808
(identity-service), #14809 (protocol-dashboard), #14810
(sdk/harmony/embed/tooling) |
| Decision record | 353 | 884 | deleted, moved into
`docs/adr/0028`–`0033` (one per package group) |

Net effect on code: **−5,762 / +281 lines**.

### Bugs found and confirmed in source

These are listed first in the issues:
- `libs` `CreatorNode._makeRequestV2`: dereferences the optional
`storageNodeSelector` in its catch block, so a failed request throws a
TypeError that hides the real error (#14807).
- `libs` `Web3Manager`: there is no identity fallback when the discovery
relay returns null, so `parseLogs` throws (#14807).
- `protocol-dashboard` `ServiceTable`: calls a hook inside `renderRow`
behind an `eslint-disable` (#14809).
- `commands` `aao.ts`: block and unblock post to two different discovery
hostnames (#14810).
- `identity-service`: three old migration `down` steps reference the
deleted `Notification` model (low impact, #14808).

### Fixes to the earlier PRs in this stack

- Restores the 17 `@deprecated` JSDoc blocks that #14796, #14802 and
#14806 removed from common, web and mobile. TypeScript and editors read
the tag, so it is now exempt.
- Exempts generator "DO NOT EDIT" headers, since
`generateServicesConfig.ts` rewrites them.

## Verification

Compared against a pristine checkout of #14806:
- `tsc --noEmit` in all 13 packages with a tsconfig: identical error set
(146 pre-existing, from local dependency drift in protocol-dashboard,
commands, sdk and fixed-decimal).
- `lint` in every package with a lint script: no new errors.
- `sdk` vitest: same result (1 pre-existing failing file, 31 passing).
- Repo-wide directive counts are identical before and after
(`@ts-ignore`, `@ts-expect-error`, `eslint-disable`, `prettier-ignore`,
`@format`, `globals`, `@deprecated`, `@__PURE__`, `webpackChunkName`,
`istanbul`).
- `npm run lint:comments` passes with an empty baseline.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
dylanjeffers added a commit that referenced this pull request Nov 21, 2026
Stacked on #14802, which is stacked on #14796. Merge those first.

## What

Runs `/delete-comment` on `packages/mobile`. All 2,405 non-exempt
comment blocks are handled:

| Category | Blocks | Lines | Action |
| --- | ---: | ---: | --- |
| Tautology | 1,660 | 3,138 | deleted |
| Stale | 59 | 208 | deleted |
| Excuse | 82 | 138 | deleted, filed as #14803
(components/harmony-native), #14804 (screens), #14805
(store/services/app shell) |
| Decision record | 604 | 1,936 | deleted, moved into
`docs/adr/0020`–`0027` |

Net effect on `packages/mobile`: **−5,592 / +186 lines** across 597
files.

### Bugs found and confirmed in source

These are listed first in the issues:
- `ScreenPrimaryContent`: `skeleton || Platform.OS === 'ios'` skips the
fade on iOS and animates on Android, the opposite of its own rationale,
which says Android native shadows don't follow the animation (#14803).
- `processTrackFile`: `if (type && ...)` lets an undefined MIME type
through, although the comment said it is rejected (#14804).
- `useExploreSectionTracking`: ignores `sectionName` and records no
impressions (#14804).
- `EditCoinDetailsScreen`: logs `e instanceof Error` (a boolean) instead
of the error (#14804).

### Ratchet change

`@format` and JSDoc type annotations in plain JS files (e.g. `@type
{import('metro-config').MetroConfig}`) are now exempt, because
TypeScript reads them. The baseline is lowered; 2,902 comments / 5,792
lines remain repo-wide.

## Verification

Compared against a pristine checkout of #14802:
- `tsc --noEmit`: identical error set (52 pre-existing, from local
dependency drift).
- `eslint src`: identical (6 pre-existing).
- Directive counts in `packages/mobile` are identical (`@ts-ignore`,
`@ts-expect-error`, `eslint-disable`, `prettier-ignore`, `@format`,
`globals`, `worklet`).
- Jest was **not** run locally: the shared `node_modules` predates
`react-native-worklets`, so the jest resolver fails on both base and
branch. CI's mobile job installs fresh and covers it.

## What's left

libs (1,170 blocks), then identity-service, protocol-dashboard, sdk
non-JSDoc and the small packages.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Stacked on #14796 (merge that first; this PR then retargets to `main`).

## What

Runs `/delete-comment` on `packages/web`. All 3,422 non-exempt comment
blocks are handled:

| Category | Blocks | Lines | Action |
| --- | ---: | ---: | --- |
| Tautology | 2,443 | 3,933 | deleted |
| Stale | 145 | 446 | deleted |
| Excuse | 99 | 242 | deleted, filed as #14798 (components), #14799
(pages), #14800 (store/services/app shell), #14801 (e2e/scripts/build) |
| Decision record | 735 | 2,121 | deleted, moved into
`docs/adr/0010`–`0019`, each with a permalink to the original line |

Net effect on `packages/web`: **−7,014 / +209 lines** across 852 files.
The +209 are lines that had a trailing comment.

One excuse is a live bug: in `GrowingCoverPhoto.tsx` the expression
`(Math.max(...), 60) * 2` is a comma expression, so the spring tension
is always 120. It's at the top of #14799.

### Ratchet changes

Classifying web exposed exemption gaps, now fixed in
`scripts/comment-ratchet.cjs` and documented in ADR 0001:
- Vendored files under `public/` and `*.min.js` are no longer scanned.
- `/* globals X */` (plural) is treated as a directive.
- `examples/` directories are exempt: their comments are tutorial text
for SDK users.

The baseline is lowered to match (5,334 comments / 11,360 lines left
repo-wide).

## Verification

Compared against a pristine checkout of #14796:
- `tsc --noEmit`: no new errors (21 pre-existing, mostly SDK drift in
`common`).
- `eslint src`: no new errors.
- `vitest run`: same set (16 files fail on the base too, 28 pass, 1
skipped).
- Directive counts in `packages/web` are identical before and after
(`@ts-ignore`, `@ts-expect-error`, `eslint-disable`, `prettier-ignore`,
`@vite-ignore`, `globals`).

## What's left

mobile (2,443 blocks), libs (1,170), then identity-service,
protocol-dashboard, sdk non-JSDoc and the small packages.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@dylanjeffers dylanjeffers changed the title chore: purge comments from packages/common, add comment ratchet chore: purge code comments repo-wide, add comment ratchet Nov 21, 2026
@dylanjeffers
dylanjeffers merged commit 2a495b7 into main Nov 21, 2026
34 checks passed
@dylanjeffers
dylanjeffers deleted the chore/comment-purge branch November 21, 2026 16:15
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.

1 participant