Repository navigation
fix(cli): doc links to a component, page, or block resolve - #7668
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
meta-cla
Bot
added
the
CLA Signed
|
AI review status for this pull request.
|
PR Analysis Report📚 Storybook Preview🧪 Sandbox PreviewNo new or modified components detected. Bundle Size SummaryNo component packages changed. Accessibility AuditStatus: No accessibility violations detected. Visual Regression40 of 478 shot(s) changed. A change here is a question, not a failure: check whether the after is the
and 20 more. Generated by PR Enrichment workflow | Storybook | Sandbox | View full report |
![astracat-bot[bot]](https://avatars.githubusercontent.com/in/4796231?s=60&v=4){kind=small}
There was a problem hiding this comment.
This restores the doc-link behavior the CLI surface spec already requires, and the new tests show it, but one case needs a fix before approval. A link to a Core component reads as astryx component <Name> with no --package, so in an app where an integration replaces that component the command opens the replacement, and where another package ships a component of the same name it fails with ERR_AMBIGUOUS_COMPONENT. Please add --package @astryxdesign/core whenever the bare name would not open Core's component (or always), consider the same rule for Core template links, and add a regression test for both cases.
[Automated review]
| route: null, | ||
| title: entry?.displayName ?? name, | ||
| summary: entry?.description ?? doc?.description ?? '', | ||
| command: `astryx component ${name}${record.package === CORE_PACKAGE ? '' : ` --package ${record.package}`}`, |
There was a problem hiding this comment.
A Core component link drops --package here, so {@link @astryxdesign/core:component:SideNav} reads as astryx component SideNav. In an app where an opted-in integration replaces SideNav, that command opens the replacement (AST-035 FR11), and where another package ships a component with the same name it fails with ERR_AMBIGUOUS_COMPONENT. Emit --package @astryxdesign/core unless the bare name opens this record (or always), and add a regression test for both cases; the template branch below builds Core commands the same way.
A doc link to a component, page, or block (`{@link component:AcmeButton}`,
`{@link @astryxdesign/core:component:Button}`, `{@link block:acme-card}`)
is a link kind the CLI accepts, yet it always warned that it named no doc,
for every provider, because the docs tree holds no component or template
docs. Links now find them among the component and template records
`astryx component` and `astryx template` read, in an app and in
`doctor integration docs` for one package, and read as that command:
`astryx component AcmeButton --package @acme/widgets`. A link to Core's
own component or template adds `--package @astryxdesign/core` only where
the bare name would open something else: a replacement, or another
package's component or template with the same name. A link that names no
doc still says so, and its hint searches the right type. The links
guide no longer tells authors to avoid these links.
3953a08 to
74ee9af
Compare
There was a problem hiding this comment.
This restores doc links to components, pages, and blocks as the CLI surface spec requires, and the earlier --package concern is fixed: Core links now open Core's component or template even under a replacement or a same-name component, with regression tests, and I found nothing that blocks approval. One narrow case you may want to close here or in a follow-up: in an app, a link to an integration's own template whose id is also a Core template id, and which another package's replacement hides from default discovery, still prints as written and draws a "names no doc" warning, because Project builds integration template records from the default view rather than the package-scoped view that --package reads.
[Automated review]
| ...(await discoverCoreTemplates()) | ||
| .filter(isPageOrBlock) | ||
| .map(template => linkable(template, CORE_PACKAGE)), | ||
| .../** @type {any[]} */ (await this.templates()) |
There was a problem hiding this comment.
Non-blocking: these records come from this.templates(), the default view, which drops an integration template whose id is also a Core id when another package's replacement takes that id (or its own same-id replacement loses precedence). A link to it from that package's docs, such as {@link page:ai-chat}, then prints as written and astryx doctor warns that it names no doc, although astryx template ai-chat --type page --package <pkg> still opens it (AST-035 FR3). Building these records from the package-scoped view that --package reads (as packageContributions does), and taking replaces only from the active replacements, would close it.
User impact
Integration authors can link a component or a template from a guide:
{@link component:AcmeButton},{@link block:acme-card}, or another provider's, such as{@link @astryxdesign/core:component:Button}. The CLI acceptscomponent,pageandblockas link kinds, but today every such link fails:astryx doctor integration docswarns that the link "names no doc". It does this for the package's own components and templates, and for Core's.astryx docs <topic>prints the raw{@link …}syntax.astryx search <name> --type doc, can't find a component or a template.After this change, each link reads as the command that opens its target, and the check stops warning:
astryx component AcmeButton --package @acme/widgetsastryx template acme-card --type block --package @acme/widgetsastryx component Buttonfor a Core componentProblem and solution fit
astryx integration check --strict(feat(cli): integration check runs every source check for a package's build, with --strict #7665) would turn it into a build failure. The links guide even tells authors not to write these links.The fix: links of these three kinds now find their target among the component and template records that
astryx componentandastryx templateread.doctor integration docs, the records are Core's plus the package's own.Expected behavior and authority
foundation/doc-compiler/links.mjslistscomponent,pageandblockamongLINK_KINDS.{@link [<provider>:]<kind>:<name>}"prints the command that opens it", and that Doctor warns only on a link that names no doc.architecture:cli-surfaceINV27 (current): "A link between docs names its target by doc identity and is resolved on every read; Doctor warns on one that names no doc." AST-047 FR9 (draft) adds that a link reads as the command that opens its doc.Smallest restoration
api/docs/_adapter.mjs:doctor integration docsreads Core's records and the package's own;--type componentor--type template.foundation/discovery/docs-discovery.mjs: the docs catalog carries those records, loaded on first use.foundation/config/project.mjs: an app's catalog gets the project's records.foundation/doc-compiler/links.mjs: a resolved link'sroutemay be null, because no docs route opens a component.assets/docs/tree/links.doc.mjs: the links guide names the three kinds and drops "A link to a component or a template does not resolve".No command, option, export or JSON field changes.
Evidence
Before, on main: an Acme package's guide links its own
AcmeButton, itsacme-cardblock, and Core'sButton.astryx doctor integration docswarns three times:In an app that configures the package,
astryx docs using-widgetsprintsStart with {@link component:AcmeButton} or {@link block:acme-card}, built on {@link @astryxdesign/core:component:Button}.After, on the same package:
doctor integration docsreports[ok] The docs tree and every link in these docs check out.Start with `astryx component AcmeButton --package @acme/widgets` or `astryx template acme-card --type block --package @acme/widgets`, built on `astryx component Button`.Unchanged paths:
--type componentor--type templatefor those kinds.Regression tests:
doctor-integration.test.mjs(own and Core component, block, Core page, and one link that names nothing) andapi/docs/integrationDocs.test.mjs(a read in an app; and Core links in an app where an integration replacesButtonand ships a page with a Core page's id, which select Core, beside a plain Core component and block, which stay short). Both fail on main.The commands are real: in that app,
astryx component Buttonopens the replacement and--package @astryxdesign/coreopens Core's; the bare page id isERR_AMBIGUOUS_TEMPLATE, and--package @astryxdesign/coreopens Core's.Since the first automated review
--package @astryxdesign/coreonly where the bare name would open something else. That happens when an integration replaces it, or when another package ships a component, or a template of its kind, with the same name. Plain Core links stay short (astryx component Badge). An app's reads use its own active replacements and records.doctor integration docs, which checks one package alone, treats the package's declaredreplacesas taking the name.Merge order
This PR stands alone on main. Merge it before #7665 (
integration check), or in the same release: until it lands,integration check --strictfails every package that links its own components. It adds no finding, so it can also ship later as a patch. The rest of the set: #7663 and #7667 (prop names, required flags and types) and #7664 (doc types).Overlap with open PRs
docs(cli): make the integration guides and Authoring Reference match the CLI #7263 (expected to merge first) edits the same bullets in
assets/docs/tree/links.doc.mjs. It addsschemaandenumto the kinds and keeps main's "A link to a component or a template does not resolve" sentence, which this PR makes false. After docs(cli): make the integration guides and Authoring Reference match the CLI #7263 merges, this PR rebases with this resolution:genericfor a topic or guide,namespacefor a docs section,commandorfunctionfor a CLI command or API function,schemaorenumfor a schema or a fixed set of values,componentfor a component, andpageorblockfor a template."If this PR merges first, docs(cli): make the integration guides and Authoring Reference match the CLI #7263 takes the same resolution.
No conflict with feat(cli): install once, run anywhere — every copy hands a project's run to the release its Core matches #7649, spec(AST-039, cli-surface): integration docs are found by their documented names and checked in one command #7658, feat(cli): a component doc can name a differently named export of the file beside it #7659, fix(cli): integration verify reads exports with the reader discovery uses #7660, docs(cli): import each Core export from the path
astryx componentprints #7623, fix(cli): init writes agent docs every agent reads, at the project root, never in the home folder #7497, or the other four PRs in this set.Scope
Testing
On main fbc03f7 with this branch: copyright, sync-exports, the published
./apitype check,readme:check, the four CLI typechecks (strict, json-api, authoring-contract, template-docs),check:changesets,check:cli-structure,check:repo, eslint on the changed files, prettier on the new files, and the fullpnpm vitest run --project nodesuite: 10,222 tests pass. The 21 failures are in the npm pack, packed real-world package, theme resolution and CSS graph tests, plus one browser accessibility test that is flaky there, which fail the same way on current main on the same machine (they need a package registry it doesn't reach).