2 Commits

Author	SHA1	Message	Date
filip131311	b232114422	docs: audit every comment in src against the code it describes (#931) ... Audits every comment in `src/` and `scripts/` against the code it describes. **462 files, 57 commits, net −8,194 lines.** Comment text only — the whole branch is code-identical to `main`. ## Method One subagent per file, strictly sequential. Scope was `src/` + `scripts/` (459 files); three more files were added at the end because they carried dead references of the same kind — two test headers citing design docs that do not exist, and `publish-npm.yml` citing a retired workflow. Each agent verified every comment — line, block, JSDoc, file header, trailing — against the surrounding code and the rest of the repo, following identifiers, paths, tool ids, config keys, env vars and issue links to see whether they still exist and still behave as described. Rules: - **A false or misleading comment is deleted, not reworded.** If a claim could not be confirmed by reading the source, it went. That is why the deletion count is so much larger than the rewrite count. - Survivors are cut to the shortest form carrying something the code does not already say. Restatement, preamble, hedging, changelog prose and ASCII banners are gone; the non-obvious *why* stays. - Preserved byte-identical: license headers, pragmas and directives (`@ts-*`, `eslint-disable`, shebangs, `/// <reference>`), JSDoc tag tokens, everything inside a string or template literal, and the sole comment inside an otherwise empty block (ESLint `no-empty` counts a comment-bearing block as non-empty). ## Verification Every file passed two independent gates before being recorded as done: 1. `comments-only` — the required check. 2. A second comment-stripping comparator with a proper mode stack, written for this pass because `comments-only`'s flat scanner desyncs on nested template literals and quote-bearing regex literals and then reports comment lines as code changes. Two files hit that false FAIL (`utils/android-profiler/pipeline/index.ts`, `scripts/extract-tools.mjs`); in both the "changed code" it printed was literally `//` lines, and the second checker confirmed the code was byte-identical. After the last file, all 462 changed files were re-checked against `main` with the same comparator, rather than trusting any agent's self-report. **459 code-identical; 2 are non-code (`.svg`, `.md`); 1 intentional.** The intentional one is `packages/argent/scripts/bundle-tools.cjs`: the changed template literal *is* the comment header of the file it generates, `packages/native-devtools-android/src/bundled-meta.ts`. Fixing only the generated file would have been reverted by the next build, so the generator changed too — and it has been verified to reproduce the committed generated file byte-for-byte. ## Representative false claims removed Not wording nits — statements a reader would have acted on: - **Reversed directions.** `proxyStart`'s JSDoc had the tunnel backwards (it is a reverse tunnel: the host binds first and the simulator dials in). A `paste()` doc had the pasteboard copy direction reversed. - **Contradicted by the code below it.** A timeout budget multiplied by three where the probes run concurrently — the same comment said so six lines later. A "warn once" that warns on every call. A "binary search" that is a linear scan. - **Named things that do not exist.** A `vega-fast-cli` binary, a `finish-recording.ts`, a `publish-next.yml` workflow, two `profiler-react19-*.md` design docs, a `DebuggerTarget.ts`, a commit hash git does not know, two tool ids, an `ensureEnv` cycle. - **Wrong by construction.** "Welford accumulators" across four files where the code keeps naive `n`/`sum`/`sumSq`; `sum`/`sumSq` documented over `actualDuration` when reduce sums `selfDuration`; a strict-mode halving written `n/2` where the code ceils; field docs listing enum values the producers never emit. - **Guarantees the code does not make.** A validation matrix claiming to cover "EVERY tool" that skips flagless ones; a Pareto cutoff that `slice(0, 20)` makes inert; an idempotence claim where the real rule is at-or-ahead; a capability note describing a clean 400 the shape-based device resolver can never produce. - **Unverifiable assertions** about prebuilt binaries, external CLIs and the cloud SDK — deleted rather than kept as folklore, since nothing in the repo can confirm them. - **Stale numbers**: invented Android tool versions, hard-coded tool counts and description lengths that had drifted. ## Review A Fable agent reviewed both halves adversarially for over-deletion, misread code, `no-empty` hazards and byte-identity violations. Second-half verdict: **SHIP**, with two one-line restores, both applied in the final commit — the `npm view ""` rationale behind a blank-token guard, and the note that `argent-mcp` keeps a copy of `SECRET_PLACEHOLDER_MARKER` it cannot import. ## Code issues surfaced but deliberately not fixed This pass changes comments only. Eight genuine findings are logged for a follow-up: 1. `telemetry/src/consent.ts` — a non-ENOENT read error returns null and falls through to the default-on path, so file errors *can* silently flip telemetry on. 2. `chromium-server/navigation.ts` — `navigate()` is reachable from `POST /api/navigate` with only a `typeof === "string"` check; open-url's schema is a bare `z.string()`, so the "already validated by zod" premise never held. 3. `http.ts` — `constantTimeEqual` returns early on a length mismatch, so the auth token's length is observable. 4. `describe/index.ts:~114` — the ios-remote branch passes `{ isTvOs: false }` unconditionally, so a remote tvOS simulator takes the iOS ax-service path, though `isRemoteTvOsSimulator` exists and shake/paste do use it. 5. `devices/boot-device.ts` — `-crash-report-mode never` is passed unconditionally *and* appended again by the feature-detecting path, so every emulator spawn passes it twice. 6. `react-profiler/pipeline/04-rank.ts` — `PARETO_THRESHOLD_PCT` is dead: `slice(0, 20)` always wins. 7. `reaped-sessions.ts` — a user-facing hint string tells the agent that `react-profiler-start { force: true }` disposes the debugger and profiler session; it does not. Left byte-identical because it is a string literal, not a comment. 8. `utils/simctl-backend.ts` — `localSimctl` is exported with no importers anywhere. ## Docs No documentation change is needed: this pass touches only source comments, and no user-facing capability, tool, CLI flag, config key or flow-file behaviour changed. --------- Co-authored-by: filip131311 <f.kaminski2000@gmail.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-24 12:16:20 +02:00
Kacper Kapuściak	5e81136096	docs: generate an Open Graph card for every page at build time (#889) ... ## What Every docs page now gets its own Open Graph card, rendered during the build. The card is `static/img/og-background.png` with a frosted glass panel in the middle: a 920x400 rounded rectangle with a 32px radius, the background blurred behind it (`backdrop-filter: blur(60px)`, an SVG `feGaussianBlur` of stdDeviation 30) and tinted with `#C3D3E033`. The white Argent logo sits centred on the panel, with the page title centred underneath in DM Sans Medium at `#FFFFFF`. Before, every page shared one static `img/logo-icon.png`. ## How `plugins/og-image/index.js` is a Docusaurus plugin with a `postBuild` hook. It: 1. Renders the background and the frosted panel once. That part is the same on every card, so it is reused as a bitmap and only the logo and the title are rendered per page. 2. Reads each built page's `<title>`, strips the ` | Argent` suffix, and lays out the logo and the title with satori. Long titles wrap and stay centred. 3. Rasterises the result with resvg into `build/img/og/<route>.png`. 4. Rewrites the `og:image` and `twitter:image` tags of that page to the new absolute URL, and adds `og:image:width` / `og:image:height`. Satori embeds every glyph as a path, so resvg needs no font lookup. DM Sans Medium is vendored in `scripts/og-assets/` (with its OFL license), so CI renders the cards exactly as a local build does. Layout, colours and blur are constants at the top of the plugin. Pages with no title of their own get a card with the logo alone. That covers the home page, whose title is the site title the logo already shows, and the search page, whose title the Algolia search theme renders as `[object Object]`. The shared `@swmansion/t-rex-ui` theme points doc pages at `img/og/<title>.png` and hardcodes a "React Native Reanimated" fallback. The plugin overwrites those tags after the build, so the naming is route based and consistent across doc pages, the home page, search and 404. ## Verification Against a clean `npx docusaurus build`, checked for all 20 built pages: the tag is an absolute site URL, the target exists in `build/`, it is a valid PNG at 1200x630, `twitter:image` matches `og:image`, the width/height tags are 1200/630, and `twitter:card` is `summary_large_image`. No unreferenced cards. Serving the production build over HTTP, every card URL returns `HTTP 200` with `content-type: image/png`. `npm run typecheck`, `npm run build`, and the root `npm run format` and `npm run lint` all pass. ## Notes - The cards add ~16MB to a 65MB build, about 845KB each. The background is a photograph and resvg only emits PNG. Re-encoding as JPEG would bring that down to roughly 2MB at the cost of a `sharp` dependency, if the deploy size becomes a concern. - New `packages/docs` dependencies: `satori` and `@resvg/resvg-js`. Both record all platform binaries in the lockfile, including `linux-x64-gnu` for the CI runner. - The branch also carries a `docs: update favicon` commit, which replaces `static/img/favicon.png`. ## Docs No user facing docs change: this is build internals. The build step is documented for contributors in `packages/docs/CLAUDE.md`. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01JovgRQBFngBsHnUYSoRF56	2026-08-21 16:31:57 +02:00