mirror of
https://github.com/coder/coder.git
synced 2026-09-21 20:51:01 +08:00
Nick VigilanteandCoder
6c95a618b4
## Summary Replaces 9 stale docs paths and 2 stale doc anchors in `site/src/`, and adds a TS/TSX audit script (`site/scripts/audit-docs-paths.mjs`) plus unit tests that scan the codebase for paths that resolve via `coder.com/redirects.json`. ### Redirect-target updates (9) Each of these paths' `/docs/...` source matches a Next.js redirect rule, so requests today produce a 302 on `coder.com`. The audit script identifies them by cross-referencing against `redirects.json`. - Five update product-code references to `/ai-coder/ai-bridge` (renamed to `/ai-coder/ai-gateway` in v2.33). - One updates a commented-out reference to `/templates#template-filtering` in `TemplatesFilter.tsx`. - Three update notification-template mock data in `testHelpers/entities.ts` that pointed at the renamed `/docs/templates/schedule`. ### Anchor-only updates (2) These paths are still live on `coder.com` (no redirect), but their `#fragment` no longer matches a heading on the destination page. Fragments are evaluated client-side and never sent to the server, so the audit script does not catch them. Found and verified manually against the current docs. - `AuditFilter.tsx`: `/admin/security/audit-logs#filtering-logs` → `/admin/security/audit-logs#how-to-filter-audit-logs`. The current heading is `## How to Filter Audit Logs` in [`docs/admin/security/audit-logs.md`](https://github.com/coder/coder/blob/main/docs/admin/security/audit-logs.md). - `UserAuthSettingsPageView.tsx`: drops the stale `#openid-connect` anchor; the path itself (`/admin/users/oidc-auth`) is unchanged. The page H1 is now `# OpenID Connect`, so the bare path lands at the same place the anchor used to. None are user-visible label changes; only the doc target URLs change. ## Audit script `site/scripts/audit-docs-paths.mjs` cross-references TS/TSX docs-URL references against `coder.com/redirects.json` and reports anything that resolves via a redirect (which means stale source). It catches four forms: - `docs("/...")` / `docs('/...')` / `` docs(`/...`) `` - `` docs(`/.../${expr}/...`) `` (literal prefix, flagged as dynamic) - `"https://coder.com/docs/..."` and other quoted forms - `](https://coder.com/docs/...)` and `](/docs/...)` markdown-link forms The full audit (26 findings: 9 in `coder/coder/site/`, 17 in `coder/coder.com/src/`) lives in [DOCS-253 on Linear](https://linear.app/codercom/issue/DOCS-253) rather than being committed to the repo. Re-run locally with: ```bash node site/scripts/audit-docs-paths.mjs \ --redirects=/path/to/coder.com/redirects.json \ --roots=/path/to/coder/site/src,/path/to/coder.com/src ``` Default output goes to `docs/.audit/redirects-audit-YYYY-MM-DD.md`, which is gitignored. ## Tests `site/scripts/audit-docs-paths.test.mjs` has 59 cases covering the four regexes, `matchRedirect` (exact, `:path*`, `:slug(.*)`, miss), `findMatchingRedirect`, `stripQueryAndFragment`, `literalPrefix`, `extractReferences` end-to-end with line numbers and multi-line `docs()` calls, `buildReport` (empty input, repo grouping and sort order, fragment annotation, unclassified section), `walk` against a real temp filesystem (recursion, extension filter, `SKIP_DIRS` pruning, missing/file inputs, seeded results), and `runCli` (missing-root warning, real-but-empty root). Run with `pnpm exec vitest run scripts/audit-docs-paths.test.mjs --project=unit` from `site/`. ## Notes - User-visible "AI Bridge" label text is not changed here. Renaming the product surface from "AI Bridge" to "AI Gateway" is tracked separately by the AI Governance team in AIGOV-233. - A vitest assertion that no literal path in `site/src/` resolves via a redirect will land in a follow-up PR (DOCS-257), so future drift fails fast in CI. - A generated `DocsPath` type for the `docs()` helper is planned in DOCS-254. - The `/docs/templates/schedule` drift in `entities.ts` also appears in `coderd/notifications/testdata/*.golden` test fixtures and in historical SQL migrations under `coderd/database/migrations/`. Those are tracked under DOCS-256 (A2: non-TS audit) and not in scope here. ## Related work - Linear: DOCS-253 (this PR), parent DOCS-209. - Companion redirect rule on the coder.com side: coder/coder.com#826. - Companion fixes for the 17 coder.com findings: coder/coder.com#876 (supersedes the closed coder/coder.com#827, which was made redundant by coder/coder.com#832). <details> <summary>Implementation plan (Linear DOCS-209)</summary> | Phase | Scope | Linear | Status | |---|---|---|---| | D | Versioned redirect for `/docs/@v2.33.x/ai-coder/ai-bridge` in `coder.com/redirects.json` | DOCS-255 | coder/coder.com#826 open | | A1 | TS/TSX audit + autofix in `coder/coder/site/` | DOCS-253 | This PR | | A1 follow-up | Same autofix in `coder/coder.com/src/` (3 remaining findings after coder/coder.com#832) | DOCS-281 | coder/coder.com#876 open | | A2 | Non-TS audit in `coder/coder` (Go, comments, markdown) | DOCS-256 | Backlog | | A3 | code-server audit | DOCS-252 | Backlog | | B | vitest assertion against `redirects.json` | DOCS-257 | Blocked by A1 | | C | Generated `DocsPath` type | DOCS-254 | Blocked by B | </details> --- Generated by Coder Agent on behalf of @nickvigilante. --------- Co-authored-by: Coder <coder@users.noreply.github.com>