fix(cockpit): point docsPath at docs pages that actually exist - #918
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
blove
enabled auto-merge (squash)
September 1, 2026 03:53
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Every cockpit capability declared `docsPath` in a five-segment shape, `/docs/<product>/core-capabilities/<topic>/overview/<lang>`. The website serves docs on a three-segment route, `/docs/<library>/<section>/<slug>`, so every one of those URLs 404s — and has for as long as the field has existed. Nothing caught it because the only assertion was a regex over the shape the code itself generated, never a check against a real route, and the field was never rendered anywhere, so no link ever visibly broke. - `libs/cockpit-registry/src/lib/docs-links.ts` holds the cockpit -> docs mapping as a table, not a formula: the two trees do not share a naming scheme, which is what made a formula wrong in the first place. Empty string is the documented "no published page yet" sentinel, carried by the seven deep-agents entries (the website has no deep-agents library). - All 83 per-example descriptors and the generated ag-ui-dev deps are rewritten from that table. - `apps/cockpit/src/lib/docs-links.spec.ts` checks every mapped path against the website's real content tree and its real nav config, checks every descriptor agrees with the table, and pins the sentinel list, so a docs rename breaks a test instead of a link. - The per-product matrix specs had no test target at all, which is how their assertion drifted; they now run under `nx test cockpit`. - The header renders a "Read docs" link where the path resolves. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
blove
force-pushed
the
blove/cockpit-docspath-wire
branch
from
September 1, 2026 03:55
fa6a4b7 to
1cc662a
Compare
Contributor
blove
added a commit
that referenced
this pull request
Sep 1, 2026
`cockpit/deep-agents/footprint.spec.ts` and `libs/cockpit-docs/src/lib/docs-bundle.spec.ts` were executed by nothing: no vitest project included the first, and `cockpit-docs` had no `test` target at all. Both are wired in here, following #916 (give the orphan a target) and #918 (glob out-of-project cockpit specs into `nx test cockpit`). Wiring surfaced three further gaps, all fixed: - `cockpit-docs` and `cockpit-registry` were both unreachable. `nx test` does not walk `^test`, and the `library` job runs a hardcoded LIBS list that excludes them, so cockpit-registry's three specs had never run either. The cockpit job now uses `nx run-many` over all three projects. - The footprint specs resolved paths from `process.cwd()`, which under `nx test cockpit` is `apps/cockpit`. Left as-is they would have asserted against `apps/cockpit/cockpit/...` and passed vacuously. They now resolve from `import.meta.url`. - `cockpit/<product>/*.spec.ts` sits outside every project root, so `nx affected` attributes it to the untagged `root` project and a PR touching only those specs skipped the job that runs them. ci-scope now maps them onto the cockpit scope by path. The website `.mdx` assertions in all three footprint specs asserted the five-segment docs shape #918 deleted — the one docs-links.ts records as having "produced a URL that 404s for every product". They are removed, not weakened: that coupling is a table checked against the website's real content tree by apps/cockpit/src/lib/docs-links.spec.ts. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
blove
added a commit
that referenced
this pull request
Sep 1, 2026
`cockpit/deep-agents/footprint.spec.ts` and `libs/cockpit-docs/src/lib/docs-bundle.spec.ts` were executed by nothing: no vitest project included the first, and `cockpit-docs` had no `test` target at all. Both are wired in here, following #916 (give the orphan a target) and #918 (glob out-of-project cockpit specs into `nx test cockpit`). Wiring surfaced three further gaps, all fixed: - `cockpit-docs` and `cockpit-registry` were both unreachable. `nx test` does not walk `^test`, and the `library` job runs a hardcoded LIBS list that excludes them, so cockpit-registry's three specs had never run either. The cockpit job now uses `nx run-many` over all three projects. - The footprint specs resolved paths from `process.cwd()`, which under `nx test cockpit` is `apps/cockpit`. Left as-is they would have asserted against `apps/cockpit/cockpit/...` and passed vacuously. They now resolve from `import.meta.url`. - `cockpit/<product>/*.spec.ts` sits outside every project root, so `nx affected` attributes it to the untagged `root` project and a PR touching only those specs skipped the job that runs them. ci-scope now maps them onto the cockpit scope by path. The website `.mdx` assertions in all three footprint specs asserted the five-segment docs shape #918 deleted — the one docs-links.ts records as having "produced a URL that 404s for every product". They are removed, not weakened: that coupling is a table checked against the website's real content tree by apps/cockpit/src/lib/docs-links.spec.ts. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
blove
added a commit
that referenced
this pull request
Sep 1, 2026
#936) `cockpit/deep-agents/footprint.spec.ts` and `libs/cockpit-docs/src/lib/docs-bundle.spec.ts` were executed by nothing: no vitest project included the first, and `cockpit-docs` had no `test` target at all. Both are wired in here, following #916 (give the orphan a target) and #918 (glob out-of-project cockpit specs into `nx test cockpit`). Wiring surfaced three further gaps, all fixed: - `cockpit-docs` and `cockpit-registry` were both unreachable. `nx test` does not walk `^test`, and the `library` job runs a hardcoded LIBS list that excludes them, so cockpit-registry's three specs had never run either. The cockpit job now uses `nx run-many` over all three projects. - The footprint specs resolved paths from `process.cwd()`, which under `nx test cockpit` is `apps/cockpit`. Left as-is they would have asserted against `apps/cockpit/cockpit/...` and passed vacuously. They now resolve from `import.meta.url`. - `cockpit/<product>/*.spec.ts` sits outside every project root, so `nx affected` attributes it to the untagged `root` project and a PR touching only those specs skipped the job that runs them. ci-scope now maps them onto the cockpit scope by path. The website `.mdx` assertions in all three footprint specs asserted the five-segment docs shape #918 deleted — the one docs-links.ts records as having "produced a URL that 404s for every product". They are removed, not weakened: that coupling is a table checked against the website's real content tree by apps/cockpit/src/lib/docs-links.spec.ts. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The finding
Every cockpit capability declared
docsPathin a five-segment shape —/docs/<product>/core-capabilities/<topic>/overview/<lang>. The website serves docs on a three-segment route,/docs/[library]/[section]/[slug]. Every one of those URLs 404s, for every product:Two things kept it invisible: the field was rendered nowhere, so no link ever visibly broke; and the only assertion was a regex over the shape the generator itself produced, never a check against a real route.
What this does
Maps it.
libs/cockpit-registry/src/lib/docs-links.tsholds the cockpit → docs mapping as a table, not a formula. The two trees do not share a naming scheme — that mismatch is exactly what made a formula wrong. Cross-library links are expected (an AG-UI demo whose best page lives underchatlinks tochat).Sentinel. Empty string (
NO_COCKPIT_DOCS_LINK) means "no published page yet". Sevendeep-agentsentries carry it — the website has nodeep-agentslibrary. Those render no link rather than a bad one. The sentinel list is pinned in a test, so a rename cannot silently blank a real link.Rewrites consumers. All 83 per-example descriptors (cockpit examples are standalone, so each carries its own literal) and the 9 generated
deployments/ag-ui-dev/deps/*copies. Generator re-run; drift check clean and idempotent.Renders it. A "Read docs" link in the cockpit capability header, on
--ds-*tokens,target="_blank". Labelled "Read docs" rather than "Docs" so it does not collide with the existing Docs mode tab.Guards it.
apps/cockpit/src/lib/docs-links.spec.tsderives the set of valid docs routes two ways — the.mdxfiles on disk and the website'sdocsConfignav — and requires every mapped path in both. It also checks every descriptor on disk agrees with the table, and that no five-segment path survives anywhere.Makes the matrix specs run.
cockpit/*/matrix.spec.tshad no test target at all — that is how the stale assertion survived. They now run undernx test cockpit. Doing so surfaced a second piece of the same rot: the LangGraph slice assertedcodeAssetPaths.length === 1while examples had grown to 2+.Mapping
Lives in
libs/cockpit-registry/src/lib/docs-links.ts, commented per non-obvious choice. 35 distinct targets; all 35 verified 200 on production threadplane.ai.Judgement calls worth a look:
langgraph/durable-execution/docs/langgraph/guides/persistencelanggraph/client-tools,ag-ui/client-tools/docs/chat/guides/client-toolsag-ui/streaming/docs/ag-ui/reference/event-mappingrender/computed-functions/docs/render/api/provide-render$computedresolves against thefunctionsmap registered thererender/repeat-loops/docs/render/guides/specsspec-renderingchat/timeline/docs/chat/components/chat-tracechat-timelinepage yet; the trace row is the primitive it rendersdeep-agents/*(7)deep-agentsdocs library existsVerification
nx test cockpit— 33 files, 214 tests green (baseline 30/209; +6 guard, matrix specs newly running)nx test cockpit-registry,nx test cockpit-shellgreen;nx lint0 errors;nx build cockpitgreenGuard mutation evidence
Every guard was mutation-tested and restored:
/docs/langgraph/guides/streaming-renamedresolveDocsUrlalways returnsnull<a>to be null🤖 Generated with Claude Code