An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): integration checks catch more doc mistakes and stop flagging an overlay pattern Core uses (#7778)
Joey37d990debad2
diff --git a/.changeset/cli-integration-check-doc-gaps.md b/.changeset/cli-integration-check-doc-gaps.mdnew file mode 100644index 0000000000..86bb880a92--- /dev/null+++ b/.changeset/cli-integration-check-doc-gaps.md@@ -0,0 +1,14 @@+---+'@astryxdesign/cli': patch+---++[feat] `astryx doctor integration` and `astryx integration check` catch more doc mistakes, and stop flagging one pattern Core itself uses.++@josephfarina++- A `docsZh` or `docsDense` overlay may set `name` and `displayName`, as Core's own docs do; both are ignored when the doc renders, so `--strict` no longer fails on them.+- `doctor integration components` reports a documented `default` that differs from the literal default the component writes in its props destructuring (`size = 'md'`) as `default_mismatch`. Quotes and spacing are ignored; where either side's default is not a literal, the prop is listed as not compared.+- `doctor integration validate` warns, each with a fix, on a prop documented twice (`duplicate_prop`), a `propDescriptions` key that matches no prop entry's name as written (`unknown_translated_prop`), a section with no content (`empty_section`), two sections of one topic with the same key (`duplicate_section_key`, whose fix names the key the second one is already served at), and a `.doc.zh.mjs` or `.doc.dense.mjs` overlay beside no topic file (`orphan_doc_overlay`).+- A topic that takes the route of one of Astryx's own docs is named by its topic name, not an internal id, with the rename to make. A link written as a bare name (`{@link deploying}`) gives the exact link to write, or says no topic has that name.+- When a doc is missing several required fields, each finding's message names only its own field.+- `doctor integration validate` prints each issue's fix and file in text output, as JSON already carries them.diff --git a/docs/architecture/cli-surface.md b/docs/architecture/cli-surface.mdindex 78e74e7ef9..fa4fabca6f 100644--- a/docs/architecture/cli-surface.md+++ b/docs/architecture/cli-surface.md@@ -179,7 +179,9 @@ and remains available through explicit Core package selection.integration's roots hold, and each translation a descriptor carries, againstthe type `@astryxdesign/cli/authoring` publishes for that kind in anintegration, as the TypeScript the project installs checks a value written- with that type. It MUST warn about every unknown field, missing required+ with that type; a component or hook translation MAY carry `name` and+ `displayName`, which are ignored at render. It MUST warn about every unknown+ field, missing requiredfield, and value outside its field's type, naming the field and the changethat fixes it, including a field the compiler reaches only once an earlierunknown field is gone. A value the loader accepts and the CLI reads MUST@@ -189,7 +191,7 @@ and remains available through explicit Core package selection.MUST stay unchanged. Without the project's TypeScript it MUST say that thedescriptors were not type-checked and why, and MUST NOT report a pass.- **INV37 — Every item source has its descriptor.** `astryx doctor integration- validate` MUST warn on a PascalCase `.tsx` at the top of the components root+validate` MUST warn on a PascalCase `.tsx` at the top of the components rootwith no same-stem component doc (`source_without_component_doc`), and on a`.tsx` at the top of the templates root with no same-stem template doc(`source_without_template_doc`). Test, spec and story files (`.test`,@@ -210,7 +212,10 @@ and remains available through explicit Core package selection.copied passage, where two topics repeat 10 or more words word for word (arun of mostly function words, or one that three or more topics share, is nota copy), and fluff, a listed padding phrase or a topic whose share of content- words is under the published floor. Its exit codes and JSON shape are a compatibility+ words is under the published floor; it also fails on doc structure a reader+ silently drops: a prop documented twice, an overlay key that names no prop,+ two sections with one key, an overlay beside no topic, and an empty section.+ Its exit codes and JSON shape are a compatibilitycontract for the builds that run it, from the first stable release thatships `integration check`: from then on, a new check, or a new failure code,MAY join it only in a minor release that names the addition, and a change@@ -743,7 +748,11 @@ reader. So these doc-quality findings fail `--strict` by owner decision, asthe one exception to DEC-7. A copied passage (a run of identical words, afterthe filters for function-word runs and for boilerplate that three or moretopics share) and a listed padding phrase (outside code and quotes) are exact-matches. The density floor is a threshold, not a contradiction. The phrase+matches. The density floor is a threshold, not a contradiction, and a section+with no content is fluff, its limiting case. Doc structure a reader silently+drops fails `--strict` as doc quality too: a prop documented twice, an overlay+key that names no prop, two sections with one key, and an overlay beside no+topic. The phraselist and the floor are published in the check's docs, and every findingnames the phrase, or the measured density and the floor, so its fix ismechanical. Each is a warning, so `integration check --strict` fails on it and@@ -767,36 +776,36 @@ the destination.## Verification-| Invariant | Evidence | Failure signal |-| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |-| INV1 | `clients/cli/commands/interactive-guard.test.mjs` | The subprocess hangs: `signal === 'SIGTERM'` and `status === null`. |-| INV2 | `clients/cli/commands/json-contract.test.mjs` | `--json` stdout does not parse, or parses to a shape outside the two. |-| INV3 | `foundation/response/error-codes.test.mjs` | A shipped code disappears, or an envelope carries an unregistered one. |-| INV4 | `clients/cli/formatters/index.test.mjs`, type tests | `emit` accepts a bare string, or output varies between pipe and TTY. |-| INV6 | `pnpm check:cli-structure` | A command's file or its doc is missing, or sits at the wrong path. |-| INV8 | `clients/cli/cli-exit-codes.test.mjs` | The same condition exits differently with and without `--json`. |-| INV14 | `foundation/integrations/autolink.test.mjs`, `foundation/config/project.test.mjs` | An undeclared package contributes, or configured/local precedence changes. |-| INV15 | `api/integration/add-contribution.test.mjs`, `clients/cli/commands/integration-authoring.test.mjs` | Dry-run/write paths differ, a writer clobbers bytes, or the new contribution is not discoverable. |-| INV16 | `foundation/integrations/manifest-writer.test.mjs`, `api/integration/add-contribution.test.mjs` | A writer invents package policy, replaces an author entry, or local bytes lose precedence. |-| INV17 | `api/integration/pack-check.test.mjs` | Lifecycle output, packed files, identities, or public imports diverge without failing the gate. |-| INV18 | `api/integration/validate-integration.test.mjs`, `api/theme/integration-themes.test.mjs` | Diagnostics mutate files, or a selected broken theme package is reported as merely unknown. |-| INV19 | `clients/cli/commands/integration-real-world.test.mjs` | A CLI-authored theme, nested palette, or guides fail across pack, install, list, add, and build. |-| INV20 | `pnpm check:cli-structure` checks that each subject has a `FunctionDoc`, typedefs, and a test; per-function coverage and leaf layout are checked in review | A subject or exported function lacks its `FunctionDoc`, typedefs, or tests, or an operation sits outside its subject. |-| INV21 | Review of imports under `api/**`; no mechanical check yet | A module other than a subject's adapter reads or writes files, contacts the network, starts a subprocess, loads the project, or runs discovery. |-| INV22 | Review of imports under `clients/cli/commands/**`; the docs drift harness checks each `CommandDoc` against the live command | A handler reaches the environment itself, an executable command's `CommandDoc` names no `fn`, or a non-command file sits in the directory. |-| INV23 | `clients/cli/formatters/index.test.mjs` for the kit; review of handlers; no mechanical check yet | A handler pads, aligns, or draws text itself, or a block kind is missing from the help "Output format" list. |-| INV24 | `api/integration/add-contribution.test.mjs`, `api/integration/add-theme.test.mjs`, `foundation/discovery/theme-discovery.test.mjs` | New authoring emits an untyped or non-`.doc.mjs` item, adding one item edits a shared file, or an item catalog becomes authoritative. |-| INV25 | `foundation/discovery/cli-self-docs.test.mjs`, `api/doctor/doctor.test.mjs` | A CLI doc with no namespace, a namespace no topic reads, or no section in its topic passes doctor. |-| INV28 | `test/inv28-package-provenance.test.mjs`, `clients/cli/commands/text-json-parity.test.mjs`, `cli-api-types-verify` | A result about one artifact has no envelope `package`, a listed artifact has no `package`, or text omits the package the envelope names. |-| INV29 | `api/doctor/doctor.test.mjs` (configured-integrations: not installed, no manifest, manifest throws; self-named authored package, direct and through a symlinked `node_modules` or `cwd`; provider-conflict set-aside; an astryx.config that imports but cannot load the project → failed `config` check) | A configured integration that cannot load leaves `doctor` at exit 0, or an installed-but-unnamed one fails it |-| INV30 | `foundation/runtime/package-set.test.mjs`, `foundation/runtime/hosted-runtime.test.mjs` | A run resolves from two roots; a root contributes an integration inside a project, including an `@astryxdesign/*` package that ships an integration manifest; a run the starting copy answers resolves from a root other than the one that holds it, or is announced as a fallback when that copy is the release `spec:AST-081` FR2 names; a run another named release answers resolves from a root whose CLI is not that release, from one that lacks a version the project would install, or from a later root when an earlier one qualifies; a hosted run installs a release, or a named-release run with no qualifying root does not fall back as FR2 says; a lookup consults a root before the project's own install, or with no set active; an approved integration resolves from another root or skips its validation; a root's config is read; a run writes into a package root or outside the places `spec:AST-081` FR7 names; the host entry's result lacks a resolved package or its source; or a project check judges the package set. |-| INV31 | `foundation/agent-docs/agent-docs.test.mjs`, `foundation/agent-docs/agent-docs.path-safety.test.mjs`, `clients/cli/commands/init.behavior.test.mjs`, `api/init/remove/remove.test.mjs`, `clients/cli/commands/doctor.test.mjs` | A layout test finds the block missing from a file INV31 names or present in a file it excludes, a managed import of a block-less `AGENTS.md` passes doctor, agent docs land in the home folder or in a settings folder outside a project, or `--remove-agents` leaves a block at the project root or in the working folder. |-| INV32 | `test/cli-strict-guard.test.mjs` lists every command offering `--strict` and every command whose exit depends on warnings; `api/integration/check/check.test.mjs` compares a strict run with the default run | A second command offers `--strict`, a command exits 1 on a warning alone without `--strict`, or a strict run reports a finding the default run does not or outside the command's issue format. |-| INV33 | `foundation/discovery/prop-drift.test.mjs`, `foundation/discovery/type-text.test.mjs`, `clients/cli/commands/doctor-integration.test.mjs`, `test/core-prop-docs.test.mjs` | A removed or renamed prop or a changed union passes unreported, a missing compiler reads as a pass, or a table that leaves out `ref`, `key`, `xstyle`, `className`, `style`, `data-testid`, or an `@internal` prop draws a warning. |-| INV34 | `foundation/discovery/doc-types.test.mjs`, `clients/cli/commands/doctor-integration.test.mjs`, `test/core-doc-types.test.mjs` | An unknown, missing, or mistyped field passes unreported, or a missing compiler reads as a pass. |-| INV35 | `api/integration/check/check.test.mjs`, `clients/cli/commands/integration-check.test.mjs`, `test/integration-check-failures.test.mjs`, `api/search/search.integration-check.test.mjs`, `foundation/discovery/prop-drift.test.mjs`, `foundation/discovery/type-match.test.mjs`, `foundation/discovery/doc-types.test.mjs`, `api/integration/authoring-checks.test.mjs` | The default exit differs from a check's own, a warning or a skipped comparison passes `--strict`, text and JSON exit differently, a new failing finding is added without the list changing, a search for ci does not find the command first, a finding is reported on a doc the code does not contradict (for a type, one TypeScript accepts), or a copied passage or a fluff finding passes `--strict`, or a function-word run or shared boilerplate is reported as a copy. |-| INV36 | `api/gap-report/gap-report.test.mjs`, `clients/cli/commands/gap-report.test.mjs` | A run without `--to` reaches an `issuesUrl` the handlers did not choose, `--to` runs a handler or files on GitHub without `--confirm-public`, an unknown `--to` sends anything, or the destinations list or its line telling the agent to ask the person is missing while a destination exists. |-| INV37 | `api/integration/validate-integration.test.mjs`, `api/integration/validate-integration-fixes.test.mjs`, `api/integration/pack-check.test.mjs` | A top-level source with no doc passes `--strict` (a dotted template id such as `landing.page` included), or a test, spec or story file or a subfolder helper is flagged. |+| Invariant | Evidence | Failure signal |+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| INV1 | `clients/cli/commands/interactive-guard.test.mjs` | The subprocess hangs: `signal === 'SIGTERM'` and `status === null`. |+| INV2 | `clients/cli/commands/json-contract.test.mjs` | `--json` stdout does not parse, or parses to a shape outside the two. |+| INV3 | `foundation/response/error-codes.test.mjs` | A shipped code disappears, or an envelope carries an unregistered one. |+| INV4 | `clients/cli/formatters/index.test.mjs`, type tests | `emit` accepts a bare string, or output varies between pipe and TTY. |+| INV6 | `pnpm check:cli-structure` | A command's file or its doc is missing, or sits at the wrong path. |+| INV8 | `clients/cli/cli-exit-codes.test.mjs` | The same condition exits differently with and without `--json`. |+| INV14 | `foundation/integrations/autolink.test.mjs`, `foundation/config/project.test.mjs` | An undeclared package contributes, or configured/local precedence changes. |+| INV15 | `api/integration/add-contribution.test.mjs`, `clients/cli/commands/integration-authoring.test.mjs` | Dry-run/write paths differ, a writer clobbers bytes, or the new contribution is not discoverable. |+| INV16 | `foundation/integrations/manifest-writer.test.mjs`, `api/integration/add-contribution.test.mjs` | A writer invents package policy, replaces an author entry, or local bytes lose precedence. |+| INV17 | `api/integration/pack-check.test.mjs` | Lifecycle output, packed files, identities, or public imports diverge without failing the gate. |+| INV18 | `api/integration/validate-integration.test.mjs`, `api/theme/integration-themes.test.mjs` | Diagnostics mutate files, or a selected broken theme package is reported as merely unknown. |+| INV19 | `clients/cli/commands/integration-real-world.test.mjs` | A CLI-authored theme, nested palette, or guides fail across pack, install, list, add, and build. |+| INV20 | `pnpm check:cli-structure` checks that each subject has a `FunctionDoc`, typedefs, and a test; per-function coverage and leaf layout are checked in review | A subject or exported function lacks its `FunctionDoc`, typedefs, or tests, or an operation sits outside its subject. |+| INV21 | Review of imports under `api/**`; no mechanical check yet | A module other than a subject's adapter reads or writes files, contacts the network, starts a subprocess, loads the project, or runs discovery. |+| INV22 | Review of imports under `clients/cli/commands/**`; the docs drift harness checks each `CommandDoc` against the live command | A handler reaches the environment itself, an executable command's `CommandDoc` names no `fn`, or a non-command file sits in the directory. |+| INV23 | `clients/cli/formatters/index.test.mjs` for the kit; review of handlers; no mechanical check yet | A handler pads, aligns, or draws text itself, or a block kind is missing from the help "Output format" list. |+| INV24 | `api/integration/add-contribution.test.mjs`, `api/integration/add-theme.test.mjs`, `foundation/discovery/theme-discovery.test.mjs` | New authoring emits an untyped or non-`.doc.mjs` item, adding one item edits a shared file, or an item catalog becomes authoritative. |+| INV25 | `foundation/discovery/cli-self-docs.test.mjs`, `api/doctor/doctor.test.mjs` | A CLI doc with no namespace, a namespace no topic reads, or no section in its topic passes doctor. |+| INV28 | `test/inv28-package-provenance.test.mjs`, `clients/cli/commands/text-json-parity.test.mjs`, `cli-api-types-verify` | A result about one artifact has no envelope `package`, a listed artifact has no `package`, or text omits the package the envelope names. |+| INV29 | `api/doctor/doctor.test.mjs` (configured-integrations: not installed, no manifest, manifest throws; self-named authored package, direct and through a symlinked `node_modules` or `cwd`; provider-conflict set-aside; an astryx.config that imports but cannot load the project → failed `config` check) | A configured integration that cannot load leaves `doctor` at exit 0, or an installed-but-unnamed one fails it |+| INV30 | `foundation/runtime/package-set.test.mjs`, `foundation/runtime/hosted-runtime.test.mjs` | A run resolves from two roots; a root contributes an integration inside a project, including an `@astryxdesign/*` package that ships an integration manifest; a run the starting copy answers resolves from a root other than the one that holds it, or is announced as a fallback when that copy is the release `spec:AST-081` FR2 names; a run another named release answers resolves from a root whose CLI is not that release, from one that lacks a version the project would install, or from a later root when an earlier one qualifies; a hosted run installs a release, or a named-release run with no qualifying root does not fall back as FR2 says; a lookup consults a root before the project's own install, or with no set active; an approved integration resolves from another root or skips its validation; a root's config is read; a run writes into a package root or outside the places `spec:AST-081` FR7 names; the host entry's result lacks a resolved package or its source; or a project check judges the package set. |+| INV31 | `foundation/agent-docs/agent-docs.test.mjs`, `foundation/agent-docs/agent-docs.path-safety.test.mjs`, `clients/cli/commands/init.behavior.test.mjs`, `api/init/remove/remove.test.mjs`, `clients/cli/commands/doctor.test.mjs` | A layout test finds the block missing from a file INV31 names or present in a file it excludes, a managed import of a block-less `AGENTS.md` passes doctor, agent docs land in the home folder or in a settings folder outside a project, or `--remove-agents` leaves a block at the project root or in the working folder. |+| INV32 | `test/cli-strict-guard.test.mjs` lists every command offering `--strict` and every command whose exit depends on warnings; `api/integration/check/check.test.mjs` compares a strict run with the default run | A second command offers `--strict`, a command exits 1 on a warning alone without `--strict`, or a strict run reports a finding the default run does not or outside the command's issue format. |+| INV33 | `foundation/discovery/prop-drift.test.mjs`, `foundation/discovery/doc-consistency.test.mjs`, `foundation/discovery/type-text.test.mjs`, `clients/cli/commands/doctor-integration.test.mjs`, `test/core-prop-docs.test.mjs` | A removed or renamed prop or a changed union passes unreported, a missing compiler reads as a pass, or a table that leaves out `ref`, `key`, `xstyle`, `className`, `style`, `data-testid`, or an `@internal` prop draws a warning. |+| INV34 | `foundation/discovery/doc-types.test.mjs`, `foundation/discovery/doc-consistency.test.mjs`, `clients/cli/commands/doctor-integration.test.mjs`, `test/core-doc-types.test.mjs` | An unknown, missing, or mistyped field passes unreported, or a missing compiler reads as a pass. |+| INV35 | `api/integration/check/check.test.mjs`, `clients/cli/commands/integration-check.test.mjs`, `test/integration-check-failures.test.mjs`, `api/search/search.integration-check.test.mjs`, `foundation/discovery/prop-drift.test.mjs`, `foundation/discovery/type-match.test.mjs`, `foundation/discovery/doc-types.test.mjs`, `api/integration/authoring-checks.test.mjs` | The default exit differs from a check's own, a warning or a skipped comparison passes `--strict`, text and JSON exit differently, a new failing finding is added without the list changing, a search for ci does not find the command first, a finding is reported on a doc the code does not contradict (for a type, one TypeScript accepts), or a copied passage or a fluff finding passes `--strict`, or a function-word run or shared boilerplate is reported as a copy. |+| INV36 | `api/gap-report/gap-report.test.mjs`, `clients/cli/commands/gap-report.test.mjs` | A run without `--to` reaches an `issuesUrl` the handlers did not choose, `--to` runs a handler or files on GitHub without `--confirm-public`, an unknown `--to` sends anything, or the destinations list or its line telling the agent to ask the person is missing while a destination exists. |+| INV37 | `api/integration/validate-integration.test.mjs`, `api/integration/validate-integration-fixes.test.mjs`, `api/integration/pack-check.test.mjs` | A top-level source with no doc passes `--strict` (a dotted template id such as `landing.page` included), or a test, spec or story file or a subfolder helper is flagged. |## Open questionsdiff --git a/packages/cli/README.md b/packages/cli/README.mdindex e4cd4c7772..6a7344d5c6 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -475,10 +475,10 @@ Every response has a `type` discriminant. The full set is below (generated from| `version` | The CLI version, for `astryx --version --json`: {version}. || `doctor` | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and an optional fix, always present on warn and fail) plus a `summary` of counts per status. || `integration.add` | A contribution-writer receipt: kind, name, optional root {path, created}, integration-manifest path, every affected project-relative path, written, and dryRun. |-| `integration.pack-check` | The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}]. |-| `integration.validate` | The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}. When the manifest loads, docTypes checks each doc against its published authoring type: status (checked \| skipped), reason, typescript, docs, findings (all warnings, each naming the field and a fix), unchecked, and fixtures (test fixture docs not checked). |+| `integration.pack-check` | The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message, fix?, file?, line?}] (the issues validation finds in the source and, prefixed packed_, in the packed tree, with the fix and the place when the check knows them). |+| `integration.validate` | The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message, fix?, file?, line?} (fix: the change that resolves it; file and line: where, relative to the package). When the manifest loads, docTypes checks each doc against its published authoring type: status (checked \| skipped), reason, typescript, docs, findings (all warnings, each naming the field and a fix), unchecked, and fixtures (test fixture docs not checked). || `integration.template-conflicts` | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}. |-| `integration.component-conflicts` | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command. When the manifest loads and declares a components root, propDrift compares documented props with the TypeScript props: status (checked \| skipped), reason, typescript, components, typesCompared, typesSkipped, findings (all warnings), unchecked, typesNotCompared, and propsNotChecked. |+| `integration.component-conflicts` | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command. When the manifest loads and declares a components root, propDrift compares documented props with the TypeScript props: status (checked \| skipped), reason, typescript, components, typesCompared, typesSkipped, findings (all warnings; a default_mismatch carries docDefault, codeDefault, and a fix), unchecked, typesNotCompared, and propsNotChecked. || `integration.doc-conflicts` | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`). copiedPassages lists each pair of topics that repeat 10 or more words of prose word for word: topic, section, otherTopic, otherOwner (package \| core), words, passages, owner (the topic that should keep the text), text (the passage as the topic writes it), line (where the copy starts in the topic to change, or null), and message (the exact replacement); each is also a copied_passage warning in issues. fluff lists padding phrases and low-density topics: topic, kind (phrase \| density), phrase, section, file, line, density, and message (what to cut or write instead); each is also a doc_fluff warning in issues. || `integration.check` | Every source check of an integration package in one result: validated (false when no integration manifest was found, so nothing was checked), the package name and version, strict, and checks, one entry per check (validate, components, templates, docs), each with check, errors, warnings, skipped, failed, and response, the envelope that check returns on its own. The totals are errors, warnings, and skipped; unchecked counts what the checks could not compare. With --strict, failures lists each warning and each piece of skipped work again as an error, in the issue format the checks use; it is empty without --strict. failed decides the exit code. |diff --git a/packages/cli/api/docs/_adapter.mjs b/packages/cli/api/docs/_adapter.mjsindex 51d82e81d7..d784cf3832 100644--- a/packages/cli/api/docs/_adapter.mjs+++ b/packages/cli/api/docs/_adapter.mjs@@ -433,7 +433,16 @@ async function docFinder(catalog, fromProvider) {const identities = identitiesOf(await projectTree(catalog));return async target => {const parsed = parseLinkTarget(target);- if ('error' in parsed) return {problem: parsed.error};+ if ('error' in parsed)+ return {+ problem: bareLinkHint(+ parsed.error,+ target,+ catalog,+ identities,+ fromProvider,+ ),+ };let provider;try {provider = normalizeProviderId(parsed.provider ?? fromProvider);@@ -442,7 +451,9 @@ async function docFinder(catalog, fromProvider) {problem: `"${target}" names "${parsed.provider}", which is not a provider id: an npm package name, or the \`providerId\` its manifest declares`,};}- const node = identities.get(identityKey(provider, parsed.kind, parsed.name));+ const node = identities.get(+ identityKey(provider, parsed.kind, parsed.name),+ );if (node) {return {link: {@@ -531,6 +542,45 @@ async function docFinder(catalog, fromProvider) {};}+/**+ * What a link written as a bare name (`{@link deploying}`) should say+ * instead: the exact target to write when a topic or tree doc has that+ * name, or that none does.+ * @param {string} error the parse error+ * @param {string} target the target as written+ * @param {DocsCatalog} catalog+ * @param {Map<string, any>} identities+ * @param {string} fromProvider+ * @returns {string}+ */+function bareLinkHint(error, target, catalog, identities, fromProvider) {+ const name = typeof target === 'string' ? target.trim() : '';+ if (!name || name.includes(':') || /\s/.test(name)) return error;+ /** @param {string} provider */+ const normal = provider => {+ try {+ return normalizeProviderId(provider);+ } catch {+ return provider;+ }+ };+ const from = normal(fromProvider);+ /** @param {string} provider @param {string} kind @param {string} named */+ const written = (provider, kind, named) =>+ `{@link ${normal(provider) === from ? '' : `${provider}:`}${kind}:${named}}`;+ const entry = catalog.resolve(name);+ if (entry) {+ return `${error}. "${name}" is a topic: write \`${written(entry.providerId ?? entry.package, 'generic', entry.name)}\`.`;+ }+ const node = [...identities.values()].find(+ each => String(each.name).toLowerCase() === name.toLowerCase(),+ );+ if (node) {+ return `${error}. "${name}" is a ${node.kind === 'generic' ? 'topic' : `${node.kind} doc`}: write \`${written(node.providerId, node.kind, node.name)}\`.`;+ }+ return `${error}, and no topic is named "${name}". Link a doc that exists, as \`{@link generic:<topic>}\` (\`astryx docs\` lists the topics), or remove the link.`;+}+/** The doc kinds no docs tree holds: components and templates. */const CONTRIBUTED_KINDS = new Set(['component', 'page', 'block']);@@ -1136,7 +1186,8 @@ export async function topicLinks(catalog, entry) {const tree = await projectTree(catalog);const node = tree.get(entry.tree ? (entry.route ?? entry.name) : entry.name);const placed =- node && (entry.tree ? node.kind === 'generic' : node.ref?.flatTopic === entry.name);+ node &&+ (entry.tree ? node.kind === 'generic' : node.ref?.flatTopic === entry.name);return placed ? placeLinks(tree, node) : {up: topicUp(entry)};}@@ -1159,7 +1210,8 @@ export async function resolveDocsArgument(topic, {cwd} = {}) {const tree = await projectTree(catalog);const owner = nameOwner(tree, catalog, topic);if (owner == null) return {kind: 'unknown', catalog};- if (owner.kind === 'topic') return {kind: 'topic', catalog, entry: owner.entry};+ if (owner.kind === 'topic')+ return {kind: 'topic', catalog, entry: owner.entry};return treeArgument(catalog, tree, owner.node);}@@ -1359,7 +1411,10 @@ export async function integrationDocTypes(integration, cwd) {if (report.status !== 'checked' || unread.length === 0) return report;// A root its reader cannot read serves no doc; say so rather than skip it.const rel = (/** @type {string} */ file) =>- path.relative(packageDir ?? cwd, file).split(path.sep).join('/') || '.';+ path+ .relative(packageDir ?? cwd, file)+ .split(path.sep)+ .join('/') || '.';return {...report,unchecked: [diff --git a/packages/cli/api/docs/integration-tree.test.mjs b/packages/cli/api/docs/integration-tree.test.mjsindex d9be801204..6b7df74941 100644--- a/packages/cli/api/docs/integration-tree.test.mjs+++ b/packages/cli/api/docs/integration-tree.test.mjs@@ -569,4 +569,26 @@ describe('integration docs in the docs tree', () => {expect(check.status).toBe('warn');expect(check.message).toContain('both have the route "cli"');}, SLOW);++ it('says what to write for a link that names a doc by its bare name, and when no doc has that name', async () => {+ scaffold({+ ...kit(),+ 'bare.doc.mjs': guide('bare', {+ sections: [+ {+ title: 'Overview',+ content: [{type: 'prose', text: 'Read {@link deploy}, then {@link nosuchtopic}.'}],+ },+ ],+ }),+ });+ const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});+ const graph = result.data.issues.filter(issue => issue.code === 'invalid_doc_graph').map(issue => issue.message);+ expect(graph).toEqual(+ expect.arrayContaining([+ expect.stringContaining('"deploy" is a topic: write `{@link generic:deploy}`.'),+ expect.stringContaining('no topic is named "nosuchtopic"'),+ ]),+ );+ }, SLOW);});diff --git a/packages/cli/api/integration/integrationComponentConflicts.doc.mjs b/packages/cli/api/integration/integrationComponentConflicts.doc.mjsindex dd89de00df..fd70d3b5b4 100644--- a/packages/cli/api/integration/integrationComponentConflicts.doc.mjs+++ b/packages/cli/api/integration/integrationComponentConflicts.doc.mjs@@ -63,7 +63,7 @@ export const doc = {{type: 'integration.component-conflicts',description:- "`validated` (false when no integration manifest was found, so nothing was inspected), integration identity, structural and replaces issues, and Core component-name conflicts with package-qualified commands. An active replacement that keeps the Core name it replaces is not a conflict. When the manifest loads and declares a components root, `propDrift` holds the props comparison: `status` (`checked` | `skipped`), `reason` when skipped, `typescript`, `components` compared, `typesCompared` (documented prop types judged), `typesSkipped` (why none was, with a TypeScript older than 4.8), `findings` ({component, prop, kind: `not_in_code` | `not_in_doc` | `required_mismatch` | `type_mismatch`, severity: `warning`, message, doc, source, docType?, codeType?, docRequired?, codeRequired?}), `unchecked` ({component, doc, reason}), `typesNotCompared` ({component, doc, reason, props}: every other documented prop type, grouped by why it was not judged: not a form the check judges exactly (a doc type that does not parse, or a prop a mapped type builds from keys the check cannot trace, included), a field the prop's variants give different types, a standard prop such as `className`, or a prop declared outside the package), and `propsNotChecked` when a mapped type builds props from keys the check cannot trace to the package ({component, doc, reason, props}: no warning is drawn for those props).",+ "`validated` (false when no integration manifest was found, so nothing was inspected), integration identity, structural and replaces issues, and Core component-name conflicts with package-qualified commands. An active replacement that keeps the Core name it replaces is not a conflict. When the manifest loads and declares a components root, `propDrift` holds the props comparison: `status` (`checked` | `skipped`), `reason` when skipped, `typescript`, `components` compared, `typesCompared` (documented prop types judged), `typesSkipped` (why none was, with a TypeScript older than 4.8), `findings` ({component, prop, kind: `not_in_code` | `not_in_doc` | `required_mismatch` | `type_mismatch` | `default_mismatch`, severity: `warning`, message, doc, source, docType?, codeType?, docRequired?, codeRequired?, docDefault?, codeDefault?, fix?}), `unchecked` ({component, doc, reason}), `typesNotCompared` ({component, doc, reason, props}: every other documented prop type, grouped by why it was not judged: not a form the check judges exactly (a doc type that does not parse, or a prop a mapped type builds from keys the check cannot trace, included), a field the prop's variants give different types, a standard prop such as `className`, or a prop declared outside the package), and `propsNotChecked` when a mapped type builds props from keys the check cannot trace to the package ({component, doc, reason, props}: no warning is drawn for those props).",},],examples: [diff --git a/packages/cli/api/integration/pack-check.mjs b/packages/cli/api/integration/pack-check.mjsindex 4098ad45f2..d3d2bde375 100644--- a/packages/cli/api/integration/pack-check.mjs+++ b/packages/cli/api/integration/pack-check.mjs@@ -1539,6 +1539,10 @@ export async function integrationPackCheck(options = {}) {code: `packed_${issue.code}`,severity: issue.severity,message: `Packed: ${issue.message}`,+ // The packed tree keeps the package's own paths.+ ...(issue.fix != null ? {fix: issue.fix} : {}),+ ...(issue.file != null ? {file: issue.file} : {}),+ ...(issue.line != null ? {line: issue.line} : {}),});}diff --git a/packages/cli/api/integration/validate-integration.mjs b/packages/cli/api/integration/validate-integration.mjsindex 6169a1fd26..c340b0d8d8 100644--- a/packages/cli/api/integration/validate-integration.mjs+++ b/packages/cli/api/integration/validate-integration.mjs@@ -35,6 +35,7 @@ import * as fs from 'node:fs';import * as path from 'node:path';import {assertWithin} from '../../foundation/fs/path-safety.mjs';import {integrationDocTypes} from '../docs/_adapter.mjs';+import {integrationDocConsistency} from '../../foundation/discovery/doc-consistency.mjs';import {THEME_SLUG_RE,unreadThemeFolders,@@ -332,6 +333,22 @@ async function validateAtPackageDir(issues.push(...(await validateLoadedIntegration(loaded)));if (loaded.themes && !rootProblem(loaded.themes))issues.push(...unreadThemeFolderIssues(packageDir, loaded));+ // What the docs say that no reader serves: a prop listed twice, an+ // overlay's text for a prop the doc lacks, an empty or unreachable section,+ // and an overlay of no topic.+ issues.push(+ ...(await integrationDocConsistency(+ {+ components:+ loaded.components && !rootProblem(loaded.components)+ ? loaded.components+ : undefined,+ docs:+ loaded.docs && !rootProblem(loaded.docs) ? loaded.docs : undefined,+ },+ packageDir,+ )),+ );if (scanUnreachable) {issues.push(...(await findUnreachableContributionIssues(packageDir, loaded)),@@ -476,9 +493,17 @@ export async function validateIntegration(pkg, options = {}) {validated: result.found,name: result.found ? (result.name ?? null) : null,version: result.found ? (result.version ?? null) : null,- issues: result.reason === 'no_package_json'- ? [{code: 'no_package', severity: 'error', message: 'No package.json found. Run this command inside a package directory.'}]- : result.issues,+ issues:+ result.reason === 'no_package_json'+ ? [+ {+ code: 'no_package',+ severity: 'error',+ message:+ 'No package.json found. Run this command inside a package directory.',+ },+ ]+ : result.issues,...(docTypes ? {docTypes} : {}),},};diff --git a/packages/cli/api/integration/validate-integration.test.mjs b/packages/cli/api/integration/validate-integration.test.mjsindex c5c78bd2f1..3620b4f8c0 100644--- a/packages/cli/api/integration/validate-integration.test.mjs+++ b/packages/cli/api/integration/validate-integration.test.mjs@@ -80,6 +80,28 @@ describe('validate-integration API', () => {expect(errors).toBe(0);});+ it('warns, with a fix and the file, on docs no reader can serve', async () => {+ const pkgDir = path.join(tmpDir, 'pkg');+ writePackage(pkgDir, {+ manifest: `export default { docs: './docs' };\n`,+ });+ fs.mkdirSync(path.join(pkgDir, 'docs'), {recursive: true});+ fs.writeFileSync(+ path.join(pkgDir, 'docs', 'ghost.doc.zh.mjs'),+ "export default {title: 'ghost'};\n",+ );++ const result = await validateLocalIntegration(pkgDir);++ expect(byCode(result.issues, 'orphan_doc_overlay')).toEqual([+ expect.objectContaining({+ severity: 'warning',+ file: 'docs/ghost.doc.zh.mjs',+ fix: expect.stringContaining('Delete docs/ghost.doc.zh.mjs'),+ }),+ ]);+ });+it('reports an unknown manifest key as a warning, and still loads the rest', async () => {// The manifest used to be parsed with a strict schema, so a single unknown// key failed the parse — and an integration whose manifest fails to parse@@ -623,7 +645,10 @@ describe('integration diagnostics are read-only', () => {'components/Orphan.doc.mjs',"export default {type: 'component', name: 'Orphan', props: []};\n",);- write('templates/dash.doc.mjs', "export default {type: 'page', name: 'Dash'};\n");+ write(+ 'templates/dash.doc.mjs',+ "export default {type: 'page', name: 'Dash'};\n",+ );write('docs/theme.doc.mjs',"export default {type: 'generic', name: 'theme', title: 'Theme', description: 'x', sections: [{title: 'A', content: [{type: 'prose', text: 'x'}]}]};\n",@@ -644,7 +669,9 @@ describe('integration diagnostics are read-only', () => {path.join(consumer, 'package.json'),JSON.stringify({name: 'consumer'}),);- writeDiagnosedPackage(path.join(consumer, 'node_modules', '@acme', 'widgets'));+ writeDiagnosedPackage(+ path.join(consumer, 'node_modules', '@acme', 'widgets'),+ );const before = {pkg: snapshot(pkgDir), consumer: snapshot(consumer)};const local = await validateIntegration(undefined, {cwd: pkgDir});@@ -661,9 +688,13 @@ describe('integration diagnostics are read-only', () => {}expect(summarizeIssues(local.data.issues).errors).toBeGreaterThan(0);- expect(byCode(local.data.issues, 'unreachable_contribution')).toHaveLength(1);+ expect(byCode(local.data.issues, 'unreachable_contribution')).toHaveLength(+ 1,+ );expect(summarizeIssues(installed.data.issues).errors).toBeGreaterThan(0);- expect({pkg: snapshot(pkgDir), consumer: snapshot(consumer)}).toEqual(before);+ expect({pkg: snapshot(pkgDir), consumer: snapshot(consumer)}).toEqual(+ before,+ );});});@@ -685,7 +716,9 @@ describe('validated separates "checked and clean" from "never checked"', () => {expect(validate.data.issues).toEqual([]);const templates = await integrationTemplateConflicts(undefined, {cwd: dir});- const components = await integrationComponentConflicts(undefined, {cwd: dir});+ const components = await integrationComponentConflicts(undefined, {+ cwd: dir,+ });const docs = await integrationDocConflicts(undefined, {cwd: dir});expect(templates.data.validated).toBe(false);expect(components.data.validated).toBe(false);@@ -701,7 +734,9 @@ describe('validated separates "checked and clean" from "never checked"', () => {expect(validate.data.name).toBe('@acme/widgets');const templates = await integrationTemplateConflicts(undefined, {cwd: dir});- const components = await integrationComponentConflicts(undefined, {cwd: dir});+ const components = await integrationComponentConflicts(undefined, {+ cwd: dir,+ });const docs = await integrationDocConflicts(undefined, {cwd: dir});expect(templates.data.validated).toBe(true);expect(components.data.validated).toBe(true);@@ -773,8 +808,12 @@ describe('unreadable folders are reported, never fatal', () => {expect(byCode(result.issues, 'unreadable_root').map(issue => issue.message),).toEqual([- expect.stringMatching(/^Declared codemods root cannot be read \(EACCES\)/),- expect.stringMatching(/^Declared themes root cannot be read \(EACCES\)/),+ expect.stringMatching(+ /^Declared codemods root cannot be read \(EACCES\)/,+ ),+ expect.stringMatching(+ /^Declared themes root cannot be read \(EACCES\)/,+ ),]);},);diff --git a/packages/cli/api/integration/validateIntegration.doc.mjs b/packages/cli/api/integration/validateIntegration.doc.mjsindex d991a29d7c..928e18f894 100644--- a/packages/cli/api/integration/validateIntegration.doc.mjs+++ b/packages/cli/api/integration/validateIntegration.doc.mjs@@ -62,7 +62,7 @@ export const doc = {{type: 'integration.validate',description:- 'The result envelope: `data.validated`, false when nothing was validated — with no `package.json` at all, `data.issues` carries one `no_package` error-severity issue so the command exits 1; with a `package.json` but no integration manifest, `data.issues` is empty, which means "not looked at", not "healthy"; `data.name` and `data.version` of the validated package (both null when `data.validated` is false; `data.name` is `(local package)` when the local package.json has no readable name), plus `data.issues`, an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}. When the manifest loads, `data.docTypes` holds the doc type check: `status` (`checked` | `skipped`), `reason` when skipped, `typescript`, `docs` (doc values checked), `findings` ({doc, line, export, type, field, problem: `unknown_field` | `missing_field` | `wrong_type`, severity: `warning`, message, fix}), `unchecked` ({doc, reason}: a doc that could not be fully checked, or a root its reader cannot read), and `fixtures` when the components or docs root holds test fixture docs under `__tests__`: how many, none of them checked.',+ 'The result envelope: `data.validated`, false when nothing was validated — with no `package.json` at all, `data.issues` carries one `no_package` error-severity issue so the command exits 1; with a `package.json` but no integration manifest, `data.issues` is empty, which means "not looked at", not "healthy"; `data.name` and `data.version` of the validated package (both null when `data.validated` is false; `data.name` is `(local package)` when the local package.json has no readable name), plus `data.issues`, an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message, fix?, file?, line?}: `fix` is the change that resolves the issue, and `file` and `line` where it is, relative to the package, when the check knows them. When the manifest loads, `data.docTypes` holds the doc type check: `status` (`checked` | `skipped`), `reason` when skipped, `typescript`, `docs` (doc values checked), `findings` ({doc, line, export, type, field, problem: `unknown_field` | `missing_field` | `wrong_type`, severity: `warning`, message, fix}), `unchecked` ({doc, reason}: a doc that could not be fully checked, or a root its reader cannot read), and `fixtures` when the components or docs root holds test fixture docs under `__tests__`: how many, none of them checked.',},],examples: [diff --git a/packages/cli/assets/docs/tree/check-the-props.doc.mjs b/packages/cli/assets/docs/tree/check-the-props.doc.mjsindex 3fb3ef6a12..5ac047d1c2 100644--- a/packages/cli/assets/docs/tree/check-the-props.doc.mjs+++ b/packages/cli/assets/docs/tree/check-the-props.doc.mjs@@ -96,6 +96,11 @@ docType: boolean"The documented `type` differs from the code's, where both read exactly",'Copy the type from the source, or fix the code. The next section says which types are judged',],+ [+ '`default_mismatch`',+ "The documented `default` differs from the literal default the component writes in its props destructuring, such as `size = 'md'`",+ 'Copy the default from the source, quoted as code: `default: "\'md\'"`. Quotes and spacing are ignored, and a default that is not a literal on either side (a constant, a call, prose) is not compared',+ ],],},],diff --git a/packages/cli/assets/docs/tree/checks.doc.mjs b/packages/cli/assets/docs/tree/checks.doc.mjsindex 52e817a4db..062601cb32 100644--- a/packages/cli/assets/docs/tree/checks.doc.mjs+++ b/packages/cli/assets/docs/tree/checks.doc.mjs@@ -32,13 +32,13 @@ export const docs = {'`npx astryx doctor integration validate`','The manifest loads, each root holds contributions the CLI can read, and each doc matches its authoring type','A declared root is missing (`missing_root`), a contribution does not load (`invalid_doc`, `invalid_component`, `invalid_theme`), or two templates in the package replace one Core id (`ambiguous_template_replacement`)',- "The manifest has a key this CLI does not know (`unknown_manifest_key`), or a doc field does not match the doc's authoring type: a field the type does not have, a missing required field, or a value outside the field's type. It checks docs with your installed `typescript`, or, where that is missing or has no JavaScript compiler API (TypeScript 7), with an installed `@typescript/typescript6`; without either, it prints `[skip] Docs not type-checked`. With no `astryx.integration.mjs` it prints a hint and exits 0",+ "The manifest has a key this CLI does not know (`unknown_manifest_key`), or a doc field does not match the doc's authoring type: a field the type does not have, a missing required field, or a value outside the field's type. It also warns on what no reader can serve: a prop listed twice (`duplicate_prop`), a `propDescriptions` key that names no documented prop (`unknown_translated_prop`), a section with no content (`empty_section`), two sections of a topic with one key (`duplicate_section_key`), or a `.doc.zh.mjs` or `.doc.dense.mjs` overlay beside no topic file (`orphan_doc_overlay`). It checks docs with your installed `typescript`, or, where that is missing or has no JavaScript compiler API (TypeScript 7), with an installed `@typescript/typescript6`; without either, it prints `[skip] Docs not type-checked`. With no `astryx.integration.mjs` it prints a hint and exits 0",],['`npx astryx doctor integration components`',"No component name clashes with a Core component, each `replaces` names one Core component, and each component doc's props match the component's TypeScript props",'Core is not installed (`core_not_found`). In a package that declares the CLI range that turns replacement on, a `replaces` target is missing (`missing_component_replacement_target`) or invalid (`invalid_component_replacement`), or two components replace one Core component (`ambiguous_component_replacement`)',- 'A name clashes with Core, a component sets `replaces` in a package without that range (`inactive_component_replacement`, plus any missing, invalid, or duplicate `replaces` reported as a warning), or a documented prop differs from the code: it is missing there (`not_in_code`), the doc omits a prop the package declares (`not_in_doc`), or its `required` (`required_mismatch`) or type (`type_mismatch`) disagrees. It reads props with your installed `typescript`; without it, it prints `[skip] Props not compared`',+ 'A name clashes with Core, a component sets `replaces` in a package without that range (`inactive_component_replacement`, plus any missing, invalid, or duplicate `replaces` reported as a warning), or a documented prop differs from the code: it is missing there (`not_in_code`), the doc omits a prop the package declares (`not_in_doc`), or its `required` (`required_mismatch`), type (`type_mismatch`), or literal `default` (`default_mismatch`) disagrees. It reads props with your installed `typescript`; without it, it prints `[skip] Props not compared`',],['`npx astryx doctor integration templates`',diff --git a/packages/cli/authoring/doctypes/component/type.ts b/packages/cli/authoring/doctypes/component/type.tsindex 13c6a58f4b..5c223a6feb 100644--- a/packages/cli/authoring/doctypes/component/type.ts+++ b/packages/cli/authoring/doctypes/component/type.ts@@ -273,6 +273,14 @@ export interface ComponentRef {* Used by both `docsZh` (Chinese translation) and `docsDense` (compressed format).*/export interface ComponentTranslationDoc {+ /** Optional exact name from the base doc. Allowed so an overlay can say+ * which component it translates; the overlay renders through the base+ * doc, so this field is ignored at render time. */+ name?: string;+ /** Optional translated displayName. Allowed so the displayName backfill+ * codemod (which adds `displayName` next to every `name:` field) does not+ * break translation overlays. Ignored at render time. */+ displayName?: string;/** Compressed/translated component description. */description?: string;/** Prop descriptions keyed by prop name. Only include props that have descriptions. */diff --git a/packages/cli/authoring/doctypes/hook/type.ts b/packages/cli/authoring/doctypes/hook/type.tsindex c20c394b41..0291a2cccf 100644--- a/packages/cli/authoring/doctypes/hook/type.ts+++ b/packages/cli/authoring/doctypes/hook/type.ts@@ -68,6 +68,10 @@ export interface HookDoc extends AuthoredDocGraphFields {* Translation overlay for hook documentation.*/export interface HookTranslationDoc {+ /** Optional exact name from the base doc. Ignored at render time. */+ name?: string;+ /** Optional translated displayName. Ignored at render time. */+ displayName?: string;/** Compressed/translated description. */description?: string;/** Param descriptions keyed by param name. */diff --git a/packages/cli/clients/cli/commands/doctor-integration.test.mjs b/packages/cli/clients/cli/commands/doctor-integration.test.mjsindex 4762d05a4b..f03795bddf 100644--- a/packages/cli/clients/cli/commands/doctor-integration.test.mjs+++ b/packages/cli/clients/cli/commands/doctor-integration.test.mjs@@ -210,6 +210,51 @@ describe('doctor integration — command', () => {expect(process.exitCode).toBeUndefined();});+ it('validate prints the fix and the file an issue carries, and JSON carries the same issue', async () => {+ writeDocIntegration({name: 'deploying'});+ fs.writeFileSync(+ path.join(tmpDir, 'docs', 'ghost.doc.zh.mjs'),+ "export default {title: 'ghost'};\n",+ );+ process.chdir(tmpDir);++ await createProgram().parseAsync([+ 'node',+ 'astryx',+ 'doctor',+ 'integration',+ 'validate',+ ]);+ const output = logCalls.join('\n');+ expect(output).toContain('orphan_doc_overlay');+ expect(output).toMatch(+ /fix:\s+Delete docs\/ghost\.doc\.zh\.mjs, or add the topic it translates/,+ );+ expect(output).toMatch(/file:\s+docs\/ghost\.doc\.zh\.mjs/);+ expect(output).toMatch(/line:\s+1\b/);++ logCalls = [];+ await createProgram().parseAsync([+ 'node',+ 'astryx',+ '--json',+ 'doctor',+ 'integration',+ 'validate',+ ]);+ const parsed = JSON.parse(logCalls.join('\n'));+ expect(parsed.data.issues).toEqual([+ {+ code: 'orphan_doc_overlay',+ severity: 'warning',+ message: expect.stringContaining('docs/ghost.doc.zh.mjs'),+ fix: expect.stringContaining('Delete docs/ghost.doc.zh.mjs'),+ file: 'docs/ghost.doc.zh.mjs',+ line: 1,+ },+ ]);+ });+it('validate warns about each doc field that does not match its authoring type, and still exits 0', async () => {writeIntegration({id: 'hero', name: 'Hero', type: 'block'});process.chdir(tmpDir);@@ -1060,12 +1105,13 @@ describe('doctor integration — command', () => {"{name: 'elevation', type: 'number', description: 'Shadow.'}","{name: 'size', type: 'string', description: 'Size.'}","{name: 'meta', type: '{id: string; extra?: number}', description: 'Data.'}",+ "{name: 'gap', type: 'number', description: 'Gap.', default: '8'}",].join(', ')}]};\n`,);// `key` is a prop a doc never needs, though the component declares it.fs.writeFileSync(path.join(tmpDir, 'components', 'AcmeBadge.tsx'),- "export function AcmeBadge(props: {label: string; tone?: 'neutral' | 'info'; size?: number; meta?: {id: string}; key?: string}) { return null; }\n",+ "export function AcmeBadge({gap = 4}: {label: string; tone?: 'neutral' | 'info'; size?: number; meta?: {id: string}; gap?: number; key?: string}) { return null; }\n",);fs.writeFileSync(path.join(tmpDir, 'components', 'AcmeLonely.doc.mjs'),@@ -1094,6 +1140,7 @@ describe('doctor integration — command', () => {expect(report.findings.map(f => `${f.prop} ${f.kind}`)).toEqual(['elevation not_in_code',+ 'gap default_mismatch','label required_mismatch','size type_mismatch','tone not_in_doc',diff --git a/packages/cli/clients/cli/commands/doctor.mjs b/packages/cli/clients/cli/commands/doctor.mjsindex ea7387de0a..c204f47c89 100644--- a/packages/cli/clients/cli/commands/doctor.mjs+++ b/packages/cli/clients/cli/commands/doctor.mjs@@ -92,7 +92,7 @@ function issueBlocks(issues) {return [section('Integration issues'),records(issues, {- fields: ['severity', 'code', 'message'],+ fields: ['severity', 'code', 'message', 'fix', 'file', 'line'],format: {severity: statusToken},}),];@@ -189,7 +189,7 @@ function printIntegrationValidation(data) {...(data.issues.length > 0? [records(data.issues, {- fields: ['severity', 'code', 'message'],+ fields: ['severity', 'code', 'message', 'fix', 'file', 'line'],format: {severity: statusToken},}),]@@ -287,6 +287,9 @@ function propDriftBlocks(report, failed) {'codeType','docRequired','codeRequired',+ 'docDefault',+ 'codeDefault',+ 'fix',],format: {severity: statusToken},}),diff --git a/packages/cli/clients/cli/commands/integration-authoring.test.mjs b/packages/cli/clients/cli/commands/integration-authoring.test.mjsindex eacc098bbd..1d3b780774 100644--- a/packages/cli/clients/cli/commands/integration-authoring.test.mjs+++ b/packages/cli/clients/cli/commands/integration-authoring.test.mjs@@ -147,6 +147,52 @@ describe('integration authoring CLI', () => {);});+ it("verify carries each issue's fix, file, and line in JSON and prints them in text", async () => {+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ `${JSON.stringify({+ name: '@acme/widgets',+ version: '1.0.0',+ files: ['astryx.integration.mjs', 'docs'],+ })}\n`,+ );+ fs.writeFileSync(+ path.join(tmpDir, 'astryx.integration.mjs'),+ "export default {docs: './docs'};\n",+ );+ fs.mkdirSync(path.join(tmpDir, 'docs'));+ fs.writeFileSync(+ path.join(tmpDir, 'docs', 'deploying.doc.mjs'),+ "export const docs = {type: 'generic', name: 'deploying', title: 'Deploying', description: 'How to deploy.', sections: [{title: 'Overview', content: [{type: 'prose', text: 'Ship it.'}]}]};\n",+ );+ fs.writeFileSync(+ path.join(tmpDir, 'docs', 'ghost.doc.zh.mjs'),+ "export default {title: 'ghost'};\n",+ );++ const json = parseEnvelope(+ (await runCli(['integration', 'verify', '--json'], tmpDir)).stdout,+ );+ const orphans = json.data.issues.filter(issue =>+ issue.code.endsWith('orphan_doc_overlay'),+ );+ expect(orphans.map(issue => issue.code).sort()).toEqual([+ 'orphan_doc_overlay',+ 'packed_orphan_doc_overlay',+ ]);+ for (const issue of orphans) {+ expect(issue).toMatchObject({+ file: 'docs/ghost.doc.zh.mjs',+ line: 1,+ fix: expect.stringContaining('Delete docs/ghost.doc.zh.mjs'),+ });+ }++ const text = (await runCli(['integration', 'verify'], tmpDir)).stdout;+ expect(text).toContain('file: docs/ghost.doc.zh.mjs:1');+ expect(text).toContain(`fix: ${orphans[0].fix}`);+ });+it('keeps `integration pack --check` as a deprecated alias of `integration verify`', async () => {// The old spelling runs the same check: the same JSON, the same exit code.const verify = await runCli(['integration', 'verify', '--json'], tmpDir);diff --git a/packages/cli/clients/cli/commands/integration.mjs b/packages/cli/clients/cli/commands/integration.mjsindex c0ebf13f3f..d2ef87e705 100644--- a/packages/cli/clients/cli/commands/integration.mjs+++ b/packages/cli/clients/cli/commands/integration.mjs@@ -79,10 +79,16 @@ async function verifyPackage(program) {if (issues.length > 0) {blocks.push(list(- issues.map(- issue =>- `[${issue.severity === 'error' ? 'fail' : 'warn'}] ${issue.message}`,- ),+ issues.map(issue => [+ `[${issue.severity === 'error' ? 'fail' : 'warn'}] ${issue.message}`,+ // Every field the JSON issue carries.+ ...(issue.file != null+ ? [+ `file: ${issue.file}${issue.line != null ? `:${issue.line}` : ''}`,+ ]+ : []),+ ...(issue.fix != null ? [`fix: ${issue.fix}`] : []),+ ]),),);}diff --git a/packages/cli/foundation/discovery/doc-consistency.mjs b/packages/cli/foundation/discovery/doc-consistency.mjsnew file mode 100644index 0000000000..4ce5dbea22--- /dev/null+++ b/packages/cli/foundation/discovery/doc-consistency.mjs@@ -0,0 +1,513 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file What an integration's docs say that no reader can serve, read from+ * the docs alone, with no compiler.+ *+ * Component docs:+ * - `duplicate_prop`: a prop table lists one prop twice, so a reader sees it+ * twice and the two entries can disagree;+ * - `unknown_translated_prop`: a `docsZh`/`docsDense` overlay's+ * `propDescriptions` key matches no prop entry's `name` as written (an+ * overlay applies by the entry's whole name, `value / onChange` included),+ * so its text is dropped when the overlay is laid over the doc.+ *+ * Topics (the docs root):+ * - `empty_section`: a section with no content, which reads as a bare title;+ * - `duplicate_section_key`: two sections of one topic whose keys (their+ * `id`, else the key their title derives) collide, so the later one is+ * served only at a suffixed key nobody wrote; the fix names that key;+ * - `orphan_doc_overlay`: a `{topic}.doc.zh.mjs` or `{topic}.doc.dense.mjs`+ * file beside no `{topic}.doc.mjs`, which ships and is never read.+ *+ * Every finding is a warning with a fix ready to paste.+ *+ * @input A loaded integration (its roots) and the package directory.+ * @output AstryxIntegrationIssue warnings, each with a `fix` and a `file`.+ * @position Run by `astryx doctor integration validate`, so+ * `astryx integration check --strict` fails on them.+ */++import * as fs from 'node:fs';+import * as path from 'node:path';+import {sectionKeyProblems, withSectionKeys} from './docs-section-key.mjs';+import {importDocModule} from '../doc-compiler/import.mjs';+import {OVERLAY_LANGUAGES} from '../doc-compiler/read.mjs';++/**+ * @typedef {import('../integrations/issue').AstryxIntegrationIssue} Issue+ */++/**+ * The codes this check raises.+ * @typedef {'duplicate_prop' | 'unknown_translated_prop' | 'empty_section' | 'duplicate_section_key' | 'orphan_doc_overlay'} DocConsistencyProblem+ */++const TOPIC_SUFFIXES = ['.doc.ts', '.doc.mjs', '.doc.js'];++/**+ * @param {DocConsistencyProblem} code+ * @param {string} message+ * @param {string} fix+ * @param {string} file relative to the package+ * @param {number} [line] 1-based, where the check can locate it+ * @returns {Issue}+ */+function finding(code, message, fix, file, line) {+ return {+ code,+ severity: 'warning',+ message,+ fix,+ file,+ ...(line != null ? {line} : {}),+ };+}++/**+ * The 1-based line of the `nth` match of `pattern` in `text` at or after+ * `from`, or undefined.+ * @param {string} text+ * @param {RegExp} pattern a global pattern+ * @param {number} [nth]+ * @param {number} [from]+ * @returns {number | undefined}+ */+function lineOf(text, pattern, nth = 0, from = 0) {+ if (!text) return undefined;+ const matches = [...text.slice(from).matchAll(pattern)];+ const match = matches[Math.min(nth, matches.length - 1)];+ if (match?.index == null) return undefined;+ return text.slice(0, from + match.index).split('\n').length;+}++/** @param {string} file */+function readText(file) {+ try {+ return fs.readFileSync(file, 'utf8');+ } catch {+ return '';+ }+}++/** @param {string} value */+function escapeRe(value) {+ return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');+}++/**+ * A pattern for `name: '<value>'` in any quote style.+ * @param {string} value+ */+function namePattern(value) {+ return new RegExp(`\\bname['"]?\\s*:\\s*(['"\`])${escapeRe(value)}\\1`, 'g');+}++/**+ * The names one prop entry documents: `a / b` names two.+ * @param {any} prop+ * @returns {string[]}+ */+function namesOf(prop) {+ if (!prop || typeof prop.name !== 'string') return [];+ return prop.name+ .split(/\s+\/\s+/)+ .map((/** @type {string} */ name) => name.trim())+ .filter(Boolean);+}++/**+ * Each prop table a component doc holds: its own `props`, and each+ * `components` entry's, with where it sits.+ * @param {any} doc+ * @returns {Array<{at: string, owner: string, props: any[]}>}+ */+function propTablesOf(doc) {+ /** @type {Array<{at: string, owner: string, props: any[]}>} */+ const tables = [];+ if (!doc || typeof doc !== 'object') return tables;+ if (Array.isArray(doc.props)) {+ tables.push({at: 'props', owner: String(doc.name ?? ''), props: doc.props});+ }+ if (Array.isArray(doc.components)) {+ doc.components.forEach(+ (/** @type {any} */ entry, /** @type {number} */ i) => {+ if (entry && Array.isArray(entry.props)) {+ tables.push({+ at: `components[${i}].props`,+ owner: String(entry.name ?? ''),+ props: entry.props,+ });+ }+ },+ );+ }+ return tables;+}++/**+ * The closest name to `name` among `names`, when one is near enough to be a+ * typo of it.+ * @param {string} name+ * @param {Iterable<string>} names+ * @returns {string | undefined}+ */+function closest(name, names) {+ let best;+ let bestDistance = Infinity;+ for (const candidate of names) {+ const distance = editDistance(name.toLowerCase(), candidate.toLowerCase());+ if (distance < bestDistance) {+ best = candidate;+ bestDistance = distance;+ }+ }+ return best != null &&+ bestDistance <= Math.max(2, Math.floor(name.length / 3))+ ? best+ : undefined;+}++/** @param {string} a @param {string} b */+function editDistance(a, b) {+ const row = Array.from({length: b.length + 1}, (_, j) => j);+ for (let i = 1; i <= a.length; i++) {+ let previous = row[0];+ row[0] = i;+ for (let j = 1; j <= b.length; j++) {+ const kept = row[j];+ row[j] = Math.min(+ row[j] + 1,+ row[j - 1] + 1,+ previous + (a[i - 1] === b[j - 1] ? 0 : 1),+ );+ previous = kept;+ }+ }+ return row[b.length];+}++/**+ * Problems in one component doc module.+ * @param {Record<string, any>} mod+ * @param {string} file relative to the package+ * @param {string} [text] the file's source, to locate each finding's line+ * @returns {Issue[]}+ */+export function componentDocProblems(mod, file, text = '') {+ /** @type {Issue[]} */+ const issues = [];+ const doc = mod?.default ?? mod?.docs;+ if (!doc || typeof doc !== 'object') return issues;+ const tables = propTablesOf(doc);++ // A prop documented twice: doc structure the reader silently drops+ // (architecture:cli-surface DEC-8).+ /** @type {Map<string, number>} entries of each name seen so far, file-wide */+ const seenNames = new Map();+ for (const {at, owner, props} of tables) {+ /** @type {Map<string, number>} */+ const first = new Map();+ props.forEach((/** @type {any} */ prop, /** @type {number} */ i) => {+ for (const name of namesOf(prop)) {+ const whole = typeof prop.name === 'string' ? prop.name : name;+ const nth = seenNames.get(whole) ?? 0;+ seenNames.set(whole, nth + 1);+ const earlier = first.get(name);+ if (earlier == null) {+ first.set(name, i);+ continue;+ }+ issues.push(+ finding(+ 'duplicate_prop',+ `${owner ? `${owner}'s ` : ''}prop "${name}" is documented twice: ${at}[${earlier}] and ${at}[${i}].`,+ `In ${file}, delete ${at}[${i}] (the second "${name}" entry), keeping what it adds in ${at}[${earlier}].`,+ file,+ lineOf(text, namePattern(whole), nth),+ ),+ );+ }+ });+ }++ // An overlay key that names no prop entry: doc structure the reader+ // silently drops (architecture:cli-surface DEC-8).+ for (const exportName of ['docsZh', 'docsDense']) {+ const overlay = mod?.[exportName];+ if (!overlay || typeof overlay !== 'object') continue;+ /** @type {Array<{at: string, descriptions: unknown, props: any[] | undefined, owner: string}>} */+ const checks = [+ {+ at: `${exportName}.propDescriptions`,+ descriptions: overlay.propDescriptions,+ props: Array.isArray(doc.props) ? doc.props : undefined,+ owner: String(doc.name ?? ''),+ },+ ];+ if (Array.isArray(overlay.components) && Array.isArray(doc.components)) {+ overlay.components.forEach(+ (/** @type {any} */ entry, /** @type {number} */ i) => {+ if (!entry || typeof entry !== 'object') return;+ const base =+ doc.components.find(+ (/** @type {any} */ c) => c?.name === entry.name,+ ) ?? doc.components[i];+ checks.push({+ at: `${exportName}.components[${i}].propDescriptions`,+ descriptions: entry.propDescriptions,+ props: Array.isArray(base?.props) ? base.props : undefined,+ owner: String(base?.name ?? entry.name ?? ''),+ });+ },+ );+ }+ const exportAt = Math.max(+ 0,+ text.search(new RegExp(`\\b${exportName}\\b\\s*=`)),+ );+ for (const {at, descriptions, props, owner} of checks) {+ if (!props || !descriptions || typeof descriptions !== 'object') continue;+ // An overlay applies by the entry's whole name, as written.+ const known = new Set(+ props+ .map(prop => (typeof prop?.name === 'string' ? prop.name : null))+ .filter(name => name != null),+ );+ /** @type {Map<string, string>} each name an entry documents, to its whole name */+ const wholeOf = new Map();+ for (const prop of props) {+ for (const each of namesOf(prop)) wholeOf.set(each, prop.name);+ }+ for (const key of Object.keys(descriptions)) {+ if (known.has(key)) continue;+ const part = closest(key, [...wholeOf.keys(), ...known]);+ const near = part == null ? undefined : (wholeOf.get(part) ?? part);+ issues.push(+ finding(+ 'unknown_translated_prop',+ `${at} names "${key}", but no prop entry of ${owner || 'the doc'} is named "${key}" (an overlay matches an entry's whole name), so that text is never shown.`,+ near+ ? `In ${file}, rename the key "${key}" in ${at} to "${near}".`+ : `In ${file}, remove "${key}" from ${at}, or document the prop "${key}" first.`,+ file,+ lineOf(+ text,+ new RegExp(`(['"\`]?)${escapeRe(key)}\\1\\s*:`, 'g'),+ 0,+ exportAt,+ ),+ ),+ );+ }+ }+ }+ return issues;+}++/**+ * Every file under a folder whose name passes `test`, skipping+ * `node_modules`, `.git` and `__tests__`.+ * @param {string} dir+ * @param {(name: string) => boolean} test+ * @returns {string[]}+ */+function filesUnder(dir, test) {+ /** @type {string[]} */+ const found = [];+ /** @param {string} folder */+ const walk = folder => {+ /** @type {fs.Dirent[]} */+ let entries;+ try {+ entries = fs.readdirSync(folder, {withFileTypes: true});+ } catch {+ return;+ }+ for (const entry of entries) {+ if (['node_modules', '.git', '__tests__'].includes(entry.name)) continue;+ const full = path.join(folder, entry.name);+ if (entry.isDirectory()) walk(full);+ else if (test(entry.name)) found.push(full);+ }+ };+ walk(dir);+ return found.sort();+}++/**+ * Problems in one topic doc.+ * @param {any} doc+ * @param {string} file relative to the package+ * @param {string} [text] the file's source, to locate each finding's line+ * @returns {Issue[]}+ */+export function topicDocProblems(doc, file, text = '') {+ /** @type {Issue[]} */+ const issues = [];+ if (!doc || typeof doc !== 'object' || doc.type === 'namespace') {+ return issues;+ }+ const name = String(doc.name ?? '');+ const sections = Array.isArray(doc.sections) ? doc.sections : [];+ // A section with no content is fluff, the limiting case of the density+ // floor (architecture:cli-surface DEC-8).+ let empties = 0;+ sections.forEach((/** @type {any} */ section, /** @type {number} */ i) => {+ if (Array.isArray(section?.content) && section.content.length === 0) {+ const nth = empties++;+ const title =+ typeof section.title === 'string' ? ` "${section.title}"` : '';+ issues.push(+ finding(+ 'empty_section',+ `Topic "${name}" section${title} (sections[${i}]) has no content, so it reads as a bare title.`,+ `In ${file}, give sections[${i}] content, such as content: [{type: 'prose', text: '…'}], or delete the section.`,+ file,+ lineOf(text, /\bcontent['"]?\s*:\s*\[\s*\]/g, nth),+ ),+ );+ }+ });+ // Two sections with one key: doc structure the reader silently drops+ // (architecture:cli-surface DEC-8).+ for (const problem of sectionKeyProblems(sections)) {+ const collision =+ /^sections\[(\d+)\]: the key "([^"]+)" is already used by sections\[(\d+)\]/.exec(+ problem,+ );+ if (!collision) continue;+ const [, later, key, earlier] = collision;+ // A later section that writes its own `id` is an invalid doc, which docs+ // discovery reports (sectionKeyErrors); only a derived key is served at a+ // suffix.+ if (sections[Number(later)]?.id != null) continue;+ let served = `${key}-2`;+ try {+ served = withSectionKeys({sections}).sections[Number(later)].id ?? served;+ } catch {+ // Keep the first suffix withSectionKeys tries.+ }+ const laterTitle = sections[Number(later)]?.title;+ const laterLine =+ typeof laterTitle === 'string'+ ? lineOf(+ text,+ new RegExp(+ `\\btitle['"]?\\s*:\\s*(['"\`])${escapeRe(laterTitle)}\\1`,+ 'g',+ ),+ sections+ .slice(0, Number(later))+ .filter((/** @type {any} */ each) => each?.title === laterTitle)+ .length,+ )+ : undefined;+ const titleOf = (/** @type {string} */ i) =>+ typeof sections[Number(i)]?.title === 'string'+ ? ` "${sections[Number(i)].title}"`+ : '';+ issues.push(+ finding(+ 'duplicate_section_key',+ `Topic "${name}": sections[${earlier}]${titleOf(earlier)} and sections[${later}]${titleOf(later)} both have the key "${key}", so \`astryx docs ${name} ${key}\` opens only sections[${earlier}]; sections[${later}] is served at "${served}", a key no one wrote.`,+ `In ${file}, give sections[${later}] its own title, or write the key it is already served at: id: '${served}'.`,+ file,+ laterLine,+ ),+ );+ }+ return issues;+}++/**+ * Check an integration's component docs and topics.+ * @param {{components?: string, docs?: string}} integration absolute roots+ * @param {string} packageDir+ * @returns {Promise<Issue[]>}+ */+export async function integrationDocConsistency(integration, packageDir) {+ /** @type {Issue[]} */+ const issues = [];+ const rel = (/** @type {string} */ file) =>+ path.relative(packageDir, file).split(path.sep).join('/');++ /** @type {string[]} */+ const componentDocs = [];+ if (integration.components) {+ componentDocs.push(+ ...filesUnder(integration.components, name =>+ TOPIC_SUFFIXES.some(suffix => name.endsWith(suffix)),+ ),+ );+ }+ for (const docPath of componentDocs.sort()) {+ let mod;+ try {+ mod = await importDocModule(docPath);+ } catch {+ // A doc that does not load is reported by the checks that load it.+ continue;+ }+ issues.push(...componentDocProblems(mod, rel(docPath), readText(docPath)));+ }++ const docsDir = integration.docs;+ if (docsDir && fs.existsSync(docsDir)) {+ const topicFiles = filesUnder(docsDir, name =>+ TOPIC_SUFFIXES.some(suffix => name.endsWith(suffix)),+ );+ /** @type {Array<{file: string, doc: any}>} */+ const topics = [];+ for (const file of topicFiles) {+ try {+ const mod = await importDocModule(file);+ topics.push({file, doc: mod?.docs ?? mod?.default});+ } catch {+ // Reported by docs discovery.+ }+ }+ for (const {file, doc} of topics) {+ issues.push(...topicDocProblems(doc, rel(file), readText(file)));+ }++ // An overlay beside no topic file: doc structure the reader silently drops+ // (architecture:cli-surface DEC-8).+ // An overlay is read beside the topic file of its stem.+ for (const overlay of filesUnder(docsDir, name =>+ OVERLAY_LANGUAGES.some(lang => name.endsWith(`.doc.${lang}.mjs`)),+ )) {+ const base = path.basename(overlay);+ const lang = /** @type {string} */ (+ OVERLAY_LANGUAGES.find(each => base.endsWith(`.doc.${each}.mjs`))+ );+ const stem = base.slice(0, -`.doc.${lang}.mjs`.length);+ const dir = path.dirname(overlay);+ if (+ TOPIC_SUFFIXES.some(suffix =>+ fs.existsSync(path.join(dir, `${stem}${suffix}`)),+ )+ ) {+ continue;+ }+ const topicNames = topics+ .filter(({file}) => path.dirname(file) === dir)+ .map(({file}) =>+ path.basename(file).replace(/\.doc\.(ts|mjs|js)$/, ''),+ );+ const near = closest(stem, topicNames);+ issues.push(+ finding(+ 'orphan_doc_overlay',+ `${rel(overlay)} overlays a topic file ${stem}.doc.mjs that does not exist, so it ships and is never read.`,+ near+ ? `Rename ${rel(overlay)} to ${rel(path.join(dir, `${near}.doc.${lang}.mjs`))}, the overlay of ${near}.doc.mjs.`+ : `Delete ${rel(overlay)}, or add the topic it translates as ${rel(path.join(dir, `${stem}.doc.mjs`))}.`,+ rel(overlay),+ 1,+ ),+ );+ }+ }+ return issues;+}diff --git a/packages/cli/foundation/discovery/doc-consistency.test.mjs b/packages/cli/foundation/discovery/doc-consistency.test.mjsnew file mode 100644index 0000000000..9674c0752b--- /dev/null+++ b/packages/cli/foundation/discovery/doc-consistency.test.mjs@@ -0,0 +1,347 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file What an integration's docs say that no reader serves: a prop listed+ * twice, an overlay's text for a prop the doc lacks, an empty section, two+ * sections with one key, and an overlay of no topic. Each is a warning with a+ * fix; a replaces/extends target is never reported.+ */++import * as fs from 'node:fs';+import * as os from 'node:os';+import * as path from 'node:path';+import {afterEach, beforeEach, describe, expect, it} from 'vitest';+import {integrationDocConsistency} from './doc-consistency.mjs';++/** @type {string} */+let pkg;++beforeEach(() => {+ pkg = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-doc-consistency-'));+});++afterEach(() => {+ fs.rmSync(pkg, {recursive: true, force: true});+});++/** @param {string} rel @param {string} text */+function write(rel, text) {+ const file = path.join(pkg, rel);+ fs.mkdirSync(path.dirname(file), {recursive: true});+ fs.writeFileSync(file, text);+}++const WIDGET = {+ type: 'component',+ name: 'Widget',+ displayName: 'Widget',+ props: [+ {name: 'label', type: 'string', description: 'Text.', required: true},+ {name: 'size', type: "'sm' | 'md'", description: 'Size.'},+ ],+};++/** @param {object} [fields] */+const topic = (fields = {}) => ({+ type: 'generic',+ name: 'deploying',+ title: 'Deploying',+ description: 'How to deploy.',+ sections: [{title: 'Overview', content: [{type: 'prose', text: 'Ship it.'}]}],+ ...fields,+});++function check() {+ return integrationDocConsistency(+ {+ components: path.join(pkg, 'components'),+ docs: path.join(pkg, 'docs'),+ },+ pkg,+ );+}++describe('integrationDocConsistency', () => {+ it('passes docs a reader serves whole, overlays with a name included', async () => {+ write(+ 'components/Widget.doc.mjs',+ `export default ${JSON.stringify(WIDGET)};\nexport const docsZh = {name: 'Widget', displayName: '小部件', propDescriptions: {label: '文本'}};\n`,+ );+ write(+ 'docs/deploying.doc.mjs',+ `export const docs = ${JSON.stringify(topic())};\n`,+ );+ write(+ 'docs/deploying.doc.zh.mjs',+ "export const docsZh = {title: '部署'};\n",+ );+ write(+ 'docs/more.doc.mjs',+ `export const docs = ${JSON.stringify(topic({name: 'more', extends: 'deploying'}))};\n`,+ );++ expect(await check()).toEqual([]);+ });++ it('names a prop documented twice and an overlay key that names no prop, with the fix', async () => {+ write(+ 'components/Widget.doc.mjs',+ `export default ${JSON.stringify({+ ...WIDGET,+ props: [+ ...WIDGET.props,+ {name: 'label', type: 'string', description: 'Again.'},+ ],+ })};\nexport const docsDense = {propDescriptions: {labell: 'txt', nothinglike: 'x'}};\n`,+ );++ const issues = await check();++ expect(issues.map(issue => issue.code)).toEqual([+ 'duplicate_prop',+ 'unknown_translated_prop',+ 'unknown_translated_prop',+ ]);+ expect(issues.every(issue => issue.severity === 'warning')).toBe(true);+ expect(issues[0]).toMatchObject({+ message: `Widget's prop "label" is documented twice: props[0] and props[2].`,+ fix: 'In components/Widget.doc.mjs, delete props[2] (the second "label" entry), keeping what it adds in props[0].',+ file: 'components/Widget.doc.mjs',+ });+ expect(issues[1].fix).toBe(+ 'In components/Widget.doc.mjs, rename the key "labell" in docsDense.propDescriptions to "label".',+ );+ expect(issues[2].fix).toBe(+ 'In components/Widget.doc.mjs, remove "nothinglike" from docsDense.propDescriptions, or document the prop "nothinglike" first.',+ );+ });++ it("matches an overlay key against each prop entry's whole name, as the overlay applies it", async () => {+ write(+ 'components/Field.doc.mjs',+ `export default ${JSON.stringify({+ type: 'component',+ name: 'Field',+ props: [+ {+ name: 'value / onChange',+ type: 'string / (v: string) => void',+ description: 'Controlled pair.',+ },+ {name: 'label', type: 'string', description: 'Text.'},+ ],+ })};\nexport const docsZh = {propDescriptions: {'value / onChange': '受控', value: '值', label: '文本'}};\n`,+ );++ const issues = await check();++ expect(issues).toEqual([+ expect.objectContaining({+ code: 'unknown_translated_prop',+ message: expect.stringContaining(+ 'docsZh.propDescriptions names "value"',+ ),+ fix: 'In components/Field.doc.mjs, rename the key "value" in docsZh.propDescriptions to "value / onChange".',+ }),+ ]);+ });++ it("checks a sub-component overlay's keys against that sub-component's props", async () => {+ write(+ 'components/Group.doc.mjs',+ `export default ${JSON.stringify({+ type: 'component',+ name: 'Group',+ components: [+ {+ name: 'GroupItem',+ props: [{name: 'value', type: 'string', description: 'V.'}],+ },+ ],+ })};\nexport const docsZh = {components: [{name: 'GroupItem', description: '项', propDescriptions: {valu: '值'}}]};\n`,+ );++ const issues = await check();++ expect(issues).toEqual([+ expect.objectContaining({+ code: 'unknown_translated_prop',+ message: expect.stringContaining(+ 'docsZh.components[0].propDescriptions names "valu", but no prop entry of GroupItem',+ ),+ }),+ ]);+ });++ it('names an empty section and two sections whose keys collide, however their titles are written', async () => {+ write(+ 'docs/deploying.doc.mjs',+ `export const docs = ${JSON.stringify(+ topic({+ sections: [+ {title: 'Overview', content: [{type: 'prose', text: 'One.'}]},+ {title: 'Next steps', content: []},+ {title: 'overview!', content: [{type: 'prose', text: 'Two.'}]},+ ],+ }),+ )};\n`,+ );++ const issues = await check();++ expect(issues.map(issue => issue.code)).toEqual([+ 'empty_section',+ 'duplicate_section_key',+ ]);+ expect(issues[0].fix).toContain('give sections[1] content');+ expect(issues[1]).toMatchObject({+ message:+ 'Topic "deploying": sections[0] "Overview" and sections[2] "overview!" both have the key "overview", so `astryx docs deploying overview` opens only sections[0]; sections[2] is served at "overview-2", a key no one wrote.',+ fix: "In docs/deploying.doc.mjs, give sections[2] its own title, or write the key it is already served at: id: 'overview-2'.",+ });+ });++ it('leaves a collision whose later section writes its own id to docs discovery, which reports it as an invalid doc', async () => {+ write(+ 'docs/deploying.doc.mjs',+ `export const docs = ${JSON.stringify(+ topic({+ sections: [+ {title: 'Overview', content: [{type: 'prose', text: 'One.'}]},+ {+ id: 'overview',+ title: 'More',+ content: [{type: 'prose', text: 'Two.'}],+ },+ ],+ }),+ )};\n`,+ );++ expect(await check()).toEqual([]);+ });++ it('never reports a replaces or extends target: it may be a topic of an integration the consumer installs', async () => {+ write(+ 'docs/deploying.doc.mjs',+ `export const docs = ${JSON.stringify(topic({replaces: 'theem'}))};\n`,+ );+ write(+ 'docs/more.doc.mjs',+ `export const docs = ${JSON.stringify(topic({name: 'more', extends: 'other-kit-guide'}))};\n`,+ );++ expect(await check()).toEqual([]);+ });++ it('names an overlay file beside no topic file', async () => {+ write(+ 'docs/deploying.doc.mjs',+ `export const docs = ${JSON.stringify(topic())};\n`,+ );+ write('docs/ghost.doc.zh.mjs', "export default {title: '幽灵'};\n");+ write('docs/deployng.doc.dense.mjs', "export default {title: 'x'};\n");++ const issues = await check();++ expect(issues).toEqual([+ expect.objectContaining({+ code: 'orphan_doc_overlay',+ file: 'docs/deployng.doc.dense.mjs',+ fix: 'Rename docs/deployng.doc.dense.mjs to docs/deploying.doc.dense.mjs, the overlay of deploying.doc.mjs.',+ }),+ expect.objectContaining({+ code: 'orphan_doc_overlay',+ file: 'docs/ghost.doc.zh.mjs',+ message:+ 'docs/ghost.doc.zh.mjs overlays a topic file ghost.doc.mjs that does not exist, so it ships and is never read.',+ fix: 'Delete docs/ghost.doc.zh.mjs, or add the topic it translates as docs/ghost.doc.mjs.',+ }),+ ]);+ });++ it('names the file, the line, and a paste-ready fix for each finding', async () => {+ write(+ 'components/Widget.doc.mjs',+ [+ 'export default {',+ " type: 'component',",+ " name: 'Widget',",+ ' props: [',+ " {name: 'label', type: 'string', description: 'Text.'},",+ " {name: 'size', type: 'string', description: 'Size.'},",+ " {name: 'label', type: 'string', description: 'Again.'},",+ ' ],',+ '};',+ 'export const docsZh = {',+ ' propDescriptions: {',+ " size: '尺寸',",+ " labell: '文本',",+ ' },',+ '};',+ '',+ ].join('\n'),+ );+ write(+ 'docs/deploying.doc.mjs',+ [+ 'export const docs = {',+ " type: 'generic',",+ " name: 'deploying',",+ " title: 'Deploying',",+ " description: 'How to deploy.',",+ ' sections: [',+ " {title: 'Overview', content: [{type: 'prose', text: 'One.'}]},",+ " {title: 'Empty', content: []},",+ " {title: 'Overview', content: [{type: 'prose', text: 'Two.'}]},",+ ' ],',+ '};',+ '',+ ].join('\n'),+ );+ write('docs/ghost.doc.zh.mjs', "export default {title: 'ghost'};\n");++ const issues = await check();+ const at = issues.map(({code, file, line, fix}) => ({+ code,+ file,+ line,+ fix,+ }));++ expect(at).toEqual([+ {+ code: 'duplicate_prop',+ file: 'components/Widget.doc.mjs',+ line: 7,+ fix: 'In components/Widget.doc.mjs, delete props[2] (the second "label" entry), keeping what it adds in props[0].',+ },+ {+ code: 'unknown_translated_prop',+ file: 'components/Widget.doc.mjs',+ line: 13,+ fix: 'In components/Widget.doc.mjs, rename the key "labell" in docsZh.propDescriptions to "label".',+ },+ {+ code: 'empty_section',+ file: 'docs/deploying.doc.mjs',+ line: 8,+ fix: "In docs/deploying.doc.mjs, give sections[1] content, such as content: [{type: 'prose', text: '…'}], or delete the section.",+ },+ {+ code: 'duplicate_section_key',+ file: 'docs/deploying.doc.mjs',+ line: 9,+ fix: "In docs/deploying.doc.mjs, give sections[2] its own title, or write the key it is already served at: id: 'overview-2'.",+ },+ {+ code: 'orphan_doc_overlay',+ file: 'docs/ghost.doc.zh.mjs',+ line: 1,+ fix: 'Delete docs/ghost.doc.zh.mjs, or add the topic it translates as docs/ghost.doc.mjs.',+ },+ ]);+ // The duplicate section's key is in its message, beside its line.+ expect(issues[3].message).toContain('both have the key "overview"');+ });+});diff --git a/packages/cli/foundation/discovery/doc-types.mjs b/packages/cli/foundation/discovery/doc-types.mjsindex 9dd5604ec5..e379332c9b 100644--- a/packages/cli/foundation/discovery/doc-types.mjs+++ b/packages/cli/foundation/discovery/doc-types.mjs@@ -827,16 +827,23 @@ function findingsFor(ts, diagnostic, astPath, where) {named != null && /^[A-Za-z_$][\w$]*$/.test(named)? named: where.typeName;+ // One diagnostic can list several missing fields; each finding's message+ // names only its own field, so two findings never share one message.+ const source = /^Type '(.*)' is missing the following properties/.exec(+ leaf,+ )?.[1];return missing.map(name => {- const field = formatPath([- ...parts,- unquote(/** @type {string} */ (name)),- ]);+ const key = unquote(/** @type {string} */ (name));+ const field = formatPath([...parts, key]);+ const message =+ missing.length > 1+ ? `Property '${key}' is missing${source == null ? '' : ` in type '${source}'`} but required in type '${ownerType}'.`+ : leaf;return {...base,field,problem: /** @type {const} */ ('missing_field'),- message: shorten(leaf),+ message: shorten(message),fix: `Add \`${field}\`: ${shorten(ownerType)} requires it.`,};});diff --git a/packages/cli/foundation/discovery/doc-types.test.mjs b/packages/cli/foundation/discovery/doc-types.test.mjsindex 965a78a1b5..ca3f7ad51c 100644--- a/packages/cli/foundation/discovery/doc-types.test.mjs+++ b/packages/cli/foundation/discovery/doc-types.test.mjs@@ -565,7 +565,7 @@ describe('checkDocTypes', () => {'components/Badge.doc.mjs',[`export default ${JSON.stringify(COMPONENT)};`,- "export const docsDense = {name: 'Badge', description: 'count chip'};",+ "export const docsDense = {name: 'Badge', displayName: 'Badge', summary: 'chip', description: 'count chip'};",`export const docsZh = ${JSON.stringify({...COMPONENT, displayName: undefined, keyword: []})};`,'',].join('\n'),@@ -575,12 +575,56 @@ describe('checkDocTypes', () => {expect(report.docs).toBe(3);expect(summary(report)).toEqual([- 'components/Badge.doc.mjs docsDense name unknown_field',+ 'components/Badge.doc.mjs docsDense summary unknown_field','components/Badge.doc.mjs docsZh keyword unknown_field',]);expect(report.findings[0].type).toBe('ComponentTranslationDoc');});+ it('allows a translation overlay to name its component, as Core overlays do', async () => {+ withTypeScript();+ write(+ 'components/Badge.doc.mjs',+ [+ `export default ${JSON.stringify(COMPONENT)};`,+ "export const docsZh = {name: 'Badge', displayName: '徽章', description: '计数'};",+ "export const docsDense = {name: 'Badge', displayName: 'Badge', description: 'count chip'};",+ '',+ ].join('\n'),+ );++ const report = await check([['components/Badge.doc.mjs', 'components']]);++ expect(summary(report)).toEqual([]);+ });++ it('gives each field TypeScript reports missing together a message naming only that field', async () => {+ withTypeScript();+ write(+ 'components/Badge.doc.mjs',+ [+ 'export default {',+ " type: 'component',",+ " name: 'Badge',",+ " props: [{name: 'label', type: 'string', description: 'Text.'}],",+ '};',+ '',+ ].join('\n'),+ );++ const report = await check([['components/Badge.doc.mjs', 'components']]);+ const missing = report.findings.filter(f => f.problem === 'missing_field');++ expect(missing.length).toBeGreaterThan(1);+ expect(new Set(missing.map(f => f.message)).size).toBe(missing.length);+ for (const finding of missing) {+ const others = missing.filter(f => f !== finding).map(f => f.field);+ expect(finding.message).toContain(`'${finding.field}'`);+ for (const other of others)+ expect(finding.message).not.toContain(`'${other}'`);+ }+ });+it('checks a template, a docs topic by its stamp, a topic overlay, and a theme', async () => {withTypeScript();write(diff --git a/packages/cli/foundation/discovery/prop-drift.mjs b/packages/cli/foundation/discovery/prop-drift.mjsindex 5a9f2b3b29..2be419511a 100644--- a/packages/cli/foundation/discovery/prop-drift.mjs+++ b/packages/cli/foundation/discovery/prop-drift.mjs@@ -31,7 +31,11 @@* each);* - `type_mismatch`: for a prop declared in the package, the documented type* differs from the code's where both sides read exactly (type-match.mjs- * states the rules); every other type is listed as not compared.+ * states the rules); every other type is listed as not compared;+ * - `default_mismatch`: the doc's `default` and the literal default the+ * component writes in its props parameter's destructuring (`size = 'md'`)+ * differ, quotes and whitespace aside; where both write a default and+ * either is not a literal, it is listed under `typesNotCompared`.** @input Component records (name, docPath, sourcePath), or prop tables, the* package root, and the directories to resolve `typescript` from.@@ -58,7 +62,7 @@ import {} from './unresolved-references.mjs';/**- * @typedef {'not_in_code' | 'not_in_doc' | 'required_mismatch' | 'type_mismatch'} PropDriftKind+ * @typedef {'not_in_code' | 'not_in_doc' | 'required_mismatch' | 'type_mismatch' | 'default_mismatch'} PropDriftKind*//**@@ -74,6 +78,9 @@ import {* @property {string} [codeType] the type as the source declares it* @property {boolean} [docRequired]* @property {boolean} [codeRequired]+ * @property {string} [docDefault] the documented default, as written+ * @property {string} [codeDefault] the literal default the code writes+ * @property {string} [fix] what to change, ready to paste*//**@@ -89,8 +96,10 @@ import {* @property {string} doc the doc file, relative to the package root* @property {string} reason why: not a form the check judges exactly, a* field the prop's variants give different types, a standard prop- * (`className`, `style`, …), or a prop declared outside the package- * @property {string[]} props documented props whose types were not compared+ * (`className`, `style`, …), a prop declared outside the package, or a+ * default that is not a literal on one side+ * @property {string[]} props documented props whose types, or defaults, were+ * not compared*//**@@ -149,6 +158,15 @@ const SKIP_TAGS = new Set(['internal']);const NOT_EXACT = 'not a form the check judges exactly';/** A field documented with one variant's type, where they differ. */const VARIANTS = "the prop's variants give this field different types";++/** A default the code writes that is not a literal (a constant, a call). */+const NOT_LITERAL = Symbol('not a literal');++/** Why a documented default was not compared with the code's. */+const CODE_DEFAULT_NOT_LITERAL =+ 'its default in the code is not a literal, so the documented default was not compared';+const DOC_DEFAULT_NOT_LITERAL =+ "its documented default is not a literal, so it was not compared with the code's";/** @type {(name: string, code?: CodeProp) => string} why a prop is not judged */const outside = (name, code) =>code?.untraced@@ -252,7 +270,7 @@ function ownFileTest(root) {* @param {import('./unresolved-references.mjs').UnresolvedReference | null} ambient* what the program's other roots cannot resolve, which any component may* use- * @returns {{ok: true, props: Map<string, CodeProp>, accepts: (name: string) => any} | {ok: false, reason: string}}+ * @returns {{ok: true, props: Map<string, CodeProp>, accepts: (name: string) => any, defaults?: Map<string, string | number | boolean | null | symbol>} | {ok: false, reason: string}}*/function readCodeProps(ts,@@ -580,7 +598,118 @@ function readCodeProps(/** The index signatures of the props type that take this name. */const accepts = (/** @type {string} */ name) =>indexesFor(ts, checker, members, name);- return {ok: true, props, accepts};+ return {ok: true, props, accepts, defaults: literalDefaults(ts, symbol)};+}++/**+ * The defaults a component writes in its props parameter's destructuring+ * (`{size = 'md'}`), by prop name, each as its value: a string, number,+ * boolean, or null, or NOT_LITERAL for any other default (a constant, a call,+ * an object), which is listed as not compared.+ * @param {any} ts+ * @param {any} symbol the component+ * @returns {Map<string, string | number | boolean | null | symbol>}+ */+function literalDefaults(ts, symbol) {+ /** @type {Map<string, string | number | boolean | null | symbol>} */+ const out = new Map();+ /** @param {any} node @param {number} depth @returns {any} */+ const fnOf = (node, depth) => {+ if (!node || depth > 4) return null;+ if (+ ts.isFunctionDeclaration(node) ||+ ts.isArrowFunction(node) ||+ ts.isFunctionExpression(node)+ ) {+ return node;+ }+ if (ts.isVariableDeclaration(node))+ return fnOf(node.initializer, depth + 1);+ if (+ ts.isParenthesizedExpression(node) ||+ ts.isAsExpression(node) ||+ (ts.isSatisfiesExpression && ts.isSatisfiesExpression(node))+ ) {+ return fnOf(node.expression, depth + 1);+ }+ // `forwardRef(function …)`, `memo(…)`: the function they wrap.+ if (ts.isCallExpression(node)) {+ for (const argument of node.arguments) {+ const found = fnOf(argument, depth + 1);+ if (found) return found;+ }+ }+ return null;+ };+ const fn = fnOf(symbol?.valueDeclaration, 0);+ const pattern = fn?.parameters?.[0]?.name;+ if (!pattern || !ts.isObjectBindingPattern(pattern)) return out;+ for (const element of pattern.elements) {+ if (element.dotDotDotToken || !element.initializer) continue;+ const key = element.propertyName ?? element.name;+ if (!(+ ts.isIdentifier(key) ||+ ts.isStringLiteral(key) ||+ ts.isNumericLiteral(key)+ )) {+ continue;+ }+ const value = literalValue(ts, element.initializer);+ out.set(key.text, value === undefined ? NOT_LITERAL : value);+ }+ return out;+}++/**+ * A literal expression's value, or undefined for anything else.+ * @param {any} ts+ * @param {any} node+ * @returns {string | number | boolean | null | undefined}+ */+function literalValue(ts, node) {+ if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {+ return node.text;+ }+ if (ts.isNumericLiteral(node)) return Number(node.text);+ if (+ ts.isPrefixUnaryExpression(node) &&+ node.operator === ts.SyntaxKind.MinusToken &&+ ts.isNumericLiteral(node.operand)+ ) {+ return -Number(node.operand.text);+ }+ if (node.kind === ts.SyntaxKind.TrueKeyword) return true;+ if (node.kind === ts.SyntaxKind.FalseKeyword) return false;+ if (node.kind === ts.SyntaxKind.NullKeyword) return null;+ return undefined;+}++/**+ * A documented default as a literal value: a quoted string (quotes of any+ * kind, whitespace around it ignored), a number, `true`, `false`, or+ * `null`; undefined for prose or an expression, which is never compared.+ * @param {unknown} written+ * @returns {string | number | boolean | null | undefined}+ */+function documentedDefault(written) {+ if (typeof written === 'number' || typeof written === 'boolean') {+ return written;+ }+ if (written === null) return null;+ if (typeof written !== 'string') return undefined;+ const text = written.trim();+ const quoted = /^(['"`])([^'"`]*)\1$/.exec(text);+ if (quoted) return quoted[2];+ if (/^-?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(text)) return Number(text);+ if (text === 'true') return true;+ if (text === 'false') return false;+ if (text === 'null') return null;+ return undefined;+}++/** @param {string | number | boolean | null} value */+function defaultText(value) {+ return typeof value === 'string' ? `'${value}'` : String(value);}/**@@ -1952,6 +2081,42 @@ export function comparePropTables(tables, options) {codeRequired: code.required,});}+ // A literal default the code writes in its props destructuring and a+ // literal the doc writes must agree; where both write a default and+ // either is not a literal, the default is listed as not compared.+ const codeDefault = read.defaults?.get(propName);+ const docWrites =+ entries.length === 1 &&+ raw.default !== undefined &&+ raw.default !== '';+ const docDefault = docWrites+ ? documentedDefault(raw.default)+ : undefined;+ if (codeDefault !== undefined && docWrites) {+ if (codeDefault === NOT_LITERAL) {+ skip(CODE_DEFAULT_NOT_LITERAL, propName);+ } else if (docDefault === undefined) {+ skip(DOC_DEFAULT_NOT_LITERAL, propName);+ }+ }+ if (+ codeDefault !== undefined &&+ codeDefault !== NOT_LITERAL &&+ docDefault !== undefined &&+ codeDefault !== docDefault+ ) {+ const shown = defaultText(+ /** @type {string | number | boolean | null} */ (codeDefault),+ );+ findings.push({+ ...base,+ kind: 'default_mismatch',+ message: `"${propName}" is documented with default ${String(raw.default).trim()}, but the code defaults it to ${shown}.`,+ fix: `In ${table.doc}, set the "${propName}" prop's default to the code's: default: ${JSON.stringify(shown)}.`,+ docDefault: String(raw.default),+ codeDefault: shown,+ });+ }if (!code.own && typeof entry.type === 'string') {skip(outside(propName, code), propName);}diff --git a/packages/cli/foundation/discovery/prop-drift.test.mjs b/packages/cli/foundation/discovery/prop-drift.test.mjsindex 53a4e6caa6..547b83f335 100644--- a/packages/cli/foundation/discovery/prop-drift.test.mjs+++ b/packages/cli/foundation/discovery/prop-drift.test.mjs@@ -366,6 +366,71 @@ export function Badge(props: BadgeProps) { return null; }`,).toMatchObject({docRequired: false, codeRequired: true});});+ it('compares a documented default with a literal default in the props destructuring, quotes and whitespace aside, and skips any other default', async () => {+ withTypeScript();+ const widget = component(+ 'Widget',+ `const SIZE = 'md';+export interface WidgetProps { size?: 'sm' | 'md'; tone?: string; count?: number; open?: boolean; label?: string; gap?: number; mode?: string }+export function Widget({size = 'md', tone = "info", count = -2, open = false, label = SIZE, gap = 4, mode}: WidgetProps) { return null; }`,+ {+ props: [+ prop('size', "'sm' | 'md'", {default: "'sm'"}),+ prop('tone', 'string', {default: ' "info" '}),+ prop('count', 'number', {default: '-2'}),+ prop('open', 'boolean', {default: 'true'}),+ prop('label', 'string', {default: "'x'"}),+ prop('gap', 'number', {default: 'the theme gap'}),+ prop('mode', 'string', {default: "'a'"}),+ ],+ },+ );+ const forwarded = component(+ 'Forwarded',+ `declare function forwardRef<T>(render: T): T;+export const Forwarded = forwardRef(function Forwarded({variant = 'solid'}: {variant?: string}) { return null; });`,+ {props: [prop('variant', 'string', {default: "'ghost'"})]},+ );++ const report = await compare([widget, forwarded]);++ expect(kinds(report)).toEqual([+ 'Forwarded.variant default_mismatch',+ 'Widget.open default_mismatch',+ 'Widget.size default_mismatch',+ ]);+ // A default that is not a literal on either side is listed, not skipped.+ expect(report.typesNotCompared).toEqual(+ expect.arrayContaining([+ expect.objectContaining({+ component: 'Widget',+ reason: expect.stringContaining(+ 'default in the code is not a literal',+ ),+ props: ['label'],+ }),+ expect.objectContaining({+ component: 'Widget',+ reason: expect.stringContaining(+ 'documented default is not a literal',+ ),+ props: ['gap'],+ }),+ ]),+ );+ expect(report.typesNotCompared.flatMap(entry => entry.props)).not.toContain(+ 'mode',+ );+ expect(report.findings.find(f => f.prop === 'size')).toMatchObject({+ severity: 'warning',+ message:+ "\"size\" is documented with default 'sm', but the code defaults it to 'md'.",+ fix: 'In components/Widget.doc.mjs, set the "size" prop\'s default to the code\'s: default: "\'md\'".',+ docDefault: "'sm'",+ codeDefault: "'md'",+ });+ });+it("judges a field, a name an index signature takes, and a prop declared in another file by the type's name where the prop is declared, not by the name the type was declared with", async () => {withTypeScript();const dir = path.join(pkg, 'components');diff --git a/packages/cli/foundation/doc-compiler/doc-loads.test.mjs b/packages/cli/foundation/doc-compiler/doc-loads.test.mjsindex d2b27c180b..72135b0571 100644--- a/packages/cli/foundation/doc-compiler/doc-loads.test.mjs+++ b/packages/cli/foundation/doc-compiler/doc-loads.test.mjs@@ -256,6 +256,10 @@ const RUNNERS = {runs: "the CLI's own guides and the package's topics, to compare their prose for passages two topics repeat",sites: ['builtinGuideFiles', 'loadTopicModule'],},+ 'foundation/discovery/doc-consistency.mjs': {+ runs: "a package's component docs and topics, to read the props, overlays, sections, and replaces/extends they declare",+ sites: ['importDocModule ×2'],+ },'foundation/discovery/doc-fluff.mjs': {runs: "the CLI's own guides, to measure the median share of content words a topic's density is compared with",sites: ['builtinGuideFiles'],diff --git a/packages/cli/foundation/doc-compiler/tree.mjs b/packages/cli/foundation/doc-compiler/tree.mjsindex 6ba428c548..c70a3f6022 100644--- a/packages/cli/foundation/doc-compiler/tree.mjs+++ b/packages/cli/foundation/doc-compiler/tree.mjs@@ -242,7 +242,8 @@ export function buildDocsTree({namespaces, docs, topics = []}) {// without case, as topic names do, so `CLI` claims `cli`.const cliRoutes = new Set(topics.length > 0 ? [UNORGANIZED] : []);for (const topic of topics) {- if (topic.provider === CLI_PROVIDER) cliRoutes.add(topic.name.toLowerCase());+ if (topic.provider === CLI_PROVIDER)+ cliRoutes.add(topic.name.toLowerCase());}// Every other name a topic answers to (the topics it replaced, directly or// through a chain) is that topic's route too: `astryx docs <name>` opens the@@ -375,6 +376,34 @@ export function buildDocsTree({namespaces, docs, topics = []}) {return false;}const taken = byFoldedRoute.get(folded);+ if (+ taken &&+ taken.provider === CLI_PROVIDER &&+ node.provider !== CLI_PROVIDER &&+ !node.generated+ ) {+ // Astryx's own doc keeps its route: name both docs as an author knows+ // them, never by their ids, and say what to change.+ const what = (/** @type {TreeNode} */ n) =>+ n.kind === 'namespace'+ ? 'namespace'+ : n.kind === 'generic'+ ? 'topic'+ : `${n.kind} doc`;+ const scope = String(node.provider).split('/').pop() ?? '';+ const suggestion = `${+ scope+ .replace(/[^a-z0-9]+/gi, '-')+ .replace(/^-|-$/g, '')+ .toLowerCase() || 'my'+ }-${node.name.toLowerCase()}`;+ report(+ 'duplicate_route',+ at,+ `The ${what(node)} "${node.name}" from ${node.provider} and Astryx's own ${what(taken)} "${taken.name}" both have the route "${node.route}", so \`astryx docs ${node.route}\` cannot open both. Fix: rename "${node.name}" (its \`name\` and its file), such as \`name: '${suggestion}'\`${node.route.includes('/') ? ', or place it elsewhere' : ''}.`,+ );+ return false;+ }if (taken) {report('duplicate_route',diff --git a/packages/cli/foundation/doc-compiler/tree.test.mjs b/packages/cli/foundation/doc-compiler/tree.test.mjsindex 372c143844..bd651d6c2a 100644--- a/packages/cli/foundation/doc-compiler/tree.test.mjs+++ b/packages/cli/foundation/doc-compiler/tree.test.mjs@@ -171,6 +171,13 @@ describe('buildDocsTree', () => {['duplicate_route', expect.stringContaining('takes the route "UNORGANIZED", which the CLI\'s own docs keep')],]),);+ // It names both docs as their authors know them, never by artifact id,+ // and says what to change.+ const taken = problems(tree).find(([, message]) => message.includes('route "CLI"'))?.[1];+ expect(taken).toBe(+ `The topic "CLI" from ${P} and Astryx's own namespace "cli" both have the route "CLI", so \`astryx docs CLI\` cannot open both. Fix: rename "CLI" (its \`name\` and its file), such as \`name: 'kit-cli'\`.`,+ );+ expect(taken).not.toContain('astryx:artifact');expect(tree.getFolded('THEME')?.provider).toBe(CLI);// A CLI topic whose own name has capitals keeps its route against a// lowercase namespace, although namespaces go into the tree first.diff --git a/packages/cli/foundation/integrations/issue.ts b/packages/cli/foundation/integrations/issue.tsindex 533ece5b17..1979ff5630 100644--- a/packages/cli/foundation/integrations/issue.ts+++ b/packages/cli/foundation/integrations/issue.ts@@ -15,4 +15,10 @@ export interface AstryxIntegrationIssue {code: string;severity: 'warning' | 'error';message: string;+ /** What to change, ready to paste, when the check knows it. */+ fix?: string;+ /** The file the issue is in, relative to the package. */+ file?: string;+ /** The 1-based line in `file`, when the check can locate it. */+ line?: number;}diff --git a/packages/cli/foundation/response/response-types.doc.mjs b/packages/cli/foundation/response/response-types.doc.mjsindex 698cf722be..f841481cb7 100644--- a/packages/cli/foundation/response/response-types.doc.mjs+++ b/packages/cli/foundation/response/response-types.doc.mjs@@ -328,12 +328,12 @@ export const doc = {{value: 'integration.pack-check',description:- 'The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}].',+ 'The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message, fix?, file?, line?}] (the issues validation finds in the source and, prefixed packed_, in the packed tree, with the fix and the place when the check knows them).',},{value: 'integration.validate',description:- 'The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning | error, message}. When the manifest loads, docTypes checks each doc against its published authoring type: status (checked | skipped), reason, typescript, docs, findings (all warnings, each naming the field and a fix), unchecked, and fixtures (test fixture docs not checked).',+ 'The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning | error, message, fix?, file?, line?} (fix: the change that resolves it; file and line: where, relative to the package). When the manifest loads, docTypes checks each doc against its published authoring type: status (checked | skipped), reason, typescript, docs, findings (all warnings, each naming the field and a fix), unchecked, and fixtures (test fixture docs not checked).',},{value: 'integration.template-conflicts',@@ -343,7 +343,7 @@ export const doc = {{value: 'integration.component-conflicts',description:- 'validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command. When the manifest loads and declares a components root, propDrift compares documented props with the TypeScript props: status (checked | skipped), reason, typescript, components, typesCompared, typesSkipped, findings (all warnings), unchecked, typesNotCompared, and propsNotChecked.',+ 'validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command. When the manifest loads and declares a components root, propDrift compares documented props with the TypeScript props: status (checked | skipped), reason, typescript, components, typesCompared, typesSkipped, findings (all warnings; a default_mismatch carries docDefault, codeDefault, and a fix), unchecked, typesNotCompared, and propsNotChecked.',},{value: 'integration.doc-conflicts',diff --git a/packages/cli/test/core-doc-types.known-drift.json b/packages/cli/test/core-doc-types.known-drift.jsonindex 701015b4fa..b05d0e1e1e 100644--- a/packages/cli/test/core-doc-types.known-drift.json+++ b/packages/cli/test/core-doc-types.known-drift.json@@ -1,194 +1,62 @@[- "packages/core/src/AlertDialog/useImperativeAlertDialog.doc.mjs docsDense name unknown_field",- "packages/core/src/Avatar/AvatarStatusDot.doc.mjs docsDense displayName unknown_field","packages/core/src/Avatar/AvatarStatusDot.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Avatar/AvatarStatusDot.doc.mjs docsDense name unknown_field",- "packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs docsDense displayName unknown_field","packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs docsDense name unknown_field",- "packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs docsZh displayName unknown_field","packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs docsZh name unknown_field",- "packages/core/src/Breadcrumbs/BreadcrumbItem.doc.mjs docsDense displayName unknown_field","packages/core/src/Breadcrumbs/BreadcrumbItem.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Breadcrumbs/BreadcrumbItem.doc.mjs docsDense name unknown_field",- "packages/core/src/Chat/ChatComposer.doc.mjs docsDense displayName unknown_field",- "packages/core/src/Chat/ChatComposer.doc.mjs docsDense name unknown_field",- "packages/core/src/Chat/ChatComposer.doc.mjs docsZh displayName unknown_field",- "packages/core/src/Chat/ChatComposer.doc.mjs docsZh name unknown_field",- "packages/core/src/Chat/ChatComposerDrawer.doc.mjs docsDense displayName unknown_field","packages/core/src/Chat/ChatComposerDrawer.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Chat/ChatComposerDrawer.doc.mjs docsDense name unknown_field",- "packages/core/src/Chat/ChatComposerDrawer.doc.mjs docsZh displayName unknown_field","packages/core/src/Chat/ChatComposerDrawer.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/Chat/ChatComposerDrawer.doc.mjs docsZh name unknown_field",- "packages/core/src/Chat/ChatComposerInput.doc.mjs docsDense displayName unknown_field","packages/core/src/Chat/ChatComposerInput.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Chat/ChatComposerInput.doc.mjs docsDense name unknown_field",- "packages/core/src/Chat/ChatComposerInput.doc.mjs docsZh displayName unknown_field","packages/core/src/Chat/ChatComposerInput.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/Chat/ChatComposerInput.doc.mjs docsZh name unknown_field",- "packages/core/src/Chat/ChatComposerTokenElement.doc.mjs docsDense displayName unknown_field","packages/core/src/Chat/ChatComposerTokenElement.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Chat/ChatComposerTokenElement.doc.mjs docsDense name unknown_field",- "packages/core/src/Chat/ChatComposerTokenElement.doc.mjs docsZh displayName unknown_field","packages/core/src/Chat/ChatComposerTokenElement.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/Chat/ChatComposerTokenElement.doc.mjs docsZh name unknown_field",- "packages/core/src/Chat/ChatLayout.doc.mjs docsDense displayName unknown_field",- "packages/core/src/Chat/ChatLayout.doc.mjs docsDense name unknown_field",- "packages/core/src/Chat/ChatLayout.doc.mjs docsZh displayName unknown_field",- "packages/core/src/Chat/ChatLayout.doc.mjs docsZh name unknown_field",- "packages/core/src/Chat/ChatLayoutScrollButton.doc.mjs docsDense displayName unknown_field","packages/core/src/Chat/ChatLayoutScrollButton.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Chat/ChatLayoutScrollButton.doc.mjs docsDense name unknown_field",- "packages/core/src/Chat/ChatLayoutScrollButton.doc.mjs docsZh displayName unknown_field","packages/core/src/Chat/ChatLayoutScrollButton.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/Chat/ChatLayoutScrollButton.doc.mjs docsZh name unknown_field",- "packages/core/src/Chat/ChatMessage.doc.mjs docsDense displayName unknown_field",- "packages/core/src/Chat/ChatMessage.doc.mjs docsDense name unknown_field",- "packages/core/src/Chat/ChatMessage.doc.mjs docsZh displayName unknown_field",- "packages/core/src/Chat/ChatMessage.doc.mjs docsZh name unknown_field",- "packages/core/src/Chat/ChatMessageBubble.doc.mjs docsDense displayName unknown_field","packages/core/src/Chat/ChatMessageBubble.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Chat/ChatMessageBubble.doc.mjs docsDense name unknown_field",- "packages/core/src/Chat/ChatMessageBubble.doc.mjs docsZh displayName unknown_field","packages/core/src/Chat/ChatMessageBubble.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/Chat/ChatMessageBubble.doc.mjs docsZh name unknown_field",- "packages/core/src/Chat/ChatMessageList.doc.mjs docsDense displayName unknown_field","packages/core/src/Chat/ChatMessageList.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Chat/ChatMessageList.doc.mjs docsDense name unknown_field",- "packages/core/src/Chat/ChatMessageList.doc.mjs docsZh displayName unknown_field","packages/core/src/Chat/ChatMessageList.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/Chat/ChatMessageList.doc.mjs docsZh name unknown_field",- "packages/core/src/Chat/ChatMessageMetadata.doc.mjs docsDense displayName unknown_field",- "packages/core/src/Chat/ChatMessageMetadata.doc.mjs docsDense name unknown_field",- "packages/core/src/Chat/ChatMessageMetadata.doc.mjs docsZh displayName unknown_field",- "packages/core/src/Chat/ChatMessageMetadata.doc.mjs docsZh name unknown_field",- "packages/core/src/Chat/ChatSendButton.doc.mjs docsDense displayName unknown_field","packages/core/src/Chat/ChatSendButton.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Chat/ChatSendButton.doc.mjs docsDense name unknown_field",- "packages/core/src/Chat/ChatSendButton.doc.mjs docsZh displayName unknown_field","packages/core/src/Chat/ChatSendButton.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/Chat/ChatSendButton.doc.mjs docsZh name unknown_field",- "packages/core/src/Chat/ChatSystemMessage.doc.mjs docsDense displayName unknown_field",- "packages/core/src/Chat/ChatSystemMessage.doc.mjs docsDense name unknown_field",- "packages/core/src/Chat/ChatSystemMessage.doc.mjs docsZh displayName unknown_field",- "packages/core/src/Chat/ChatSystemMessage.doc.mjs docsZh name unknown_field","packages/core/src/Chat/ChatSystemMessage.doc.mjs docsZh theming unknown_field",- "packages/core/src/Chat/ChatTokenizedText.doc.mjs docsDense displayName unknown_field","packages/core/src/Chat/ChatTokenizedText.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Chat/ChatTokenizedText.doc.mjs docsDense name unknown_field",- "packages/core/src/Chat/ChatTokenizedText.doc.mjs docsZh displayName unknown_field","packages/core/src/Chat/ChatTokenizedText.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/Chat/ChatTokenizedText.doc.mjs docsZh name unknown_field","packages/core/src/Chat/ChatTokenizedText.doc.mjs docsZh theming unknown_field",- "packages/core/src/CheckboxList/CheckboxListItem.doc.mjs docsDense displayName unknown_field","packages/core/src/CheckboxList/CheckboxListItem.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/CheckboxList/CheckboxListItem.doc.mjs docsDense name unknown_field",- "packages/core/src/Collapsible/CollapsibleGroup.doc.mjs docsDense displayName unknown_field","packages/core/src/Collapsible/CollapsibleGroup.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Collapsible/CollapsibleGroup.doc.mjs docsDense name unknown_field",- "packages/core/src/CommandPalette/CommandPaletteEmpty.doc.mjs docsDense displayName unknown_field","packages/core/src/CommandPalette/CommandPaletteEmpty.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/CommandPalette/CommandPaletteEmpty.doc.mjs docsDense name unknown_field",- "packages/core/src/CommandPalette/CommandPaletteEmpty.doc.mjs docsZh displayName unknown_field","packages/core/src/CommandPalette/CommandPaletteEmpty.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/CommandPalette/CommandPaletteEmpty.doc.mjs docsZh name unknown_field",- "packages/core/src/CommandPalette/CommandPaletteFooter.doc.mjs docsDense displayName unknown_field","packages/core/src/CommandPalette/CommandPaletteFooter.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/CommandPalette/CommandPaletteFooter.doc.mjs docsDense name unknown_field",- "packages/core/src/CommandPalette/CommandPaletteFooter.doc.mjs docsZh displayName unknown_field","packages/core/src/CommandPalette/CommandPaletteFooter.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/CommandPalette/CommandPaletteFooter.doc.mjs docsZh name unknown_field",- "packages/core/src/CommandPalette/CommandPaletteGroup.doc.mjs docsDense displayName unknown_field","packages/core/src/CommandPalette/CommandPaletteGroup.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/CommandPalette/CommandPaletteGroup.doc.mjs docsDense name unknown_field",- "packages/core/src/CommandPalette/CommandPaletteGroup.doc.mjs docsZh displayName unknown_field","packages/core/src/CommandPalette/CommandPaletteGroup.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/CommandPalette/CommandPaletteGroup.doc.mjs docsZh name unknown_field",- "packages/core/src/CommandPalette/CommandPaletteInput.doc.mjs docsDense displayName unknown_field","packages/core/src/CommandPalette/CommandPaletteInput.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/CommandPalette/CommandPaletteInput.doc.mjs docsDense name unknown_field",- "packages/core/src/CommandPalette/CommandPaletteInput.doc.mjs docsZh displayName unknown_field","packages/core/src/CommandPalette/CommandPaletteInput.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/CommandPalette/CommandPaletteInput.doc.mjs docsZh name unknown_field",- "packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs docsDense displayName unknown_field","packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs docsDense name unknown_field",- "packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs docsZh displayName unknown_field","packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs docsZh name unknown_field",- "packages/core/src/CommandPalette/CommandPaletteList.doc.mjs docsDense displayName unknown_field","packages/core/src/CommandPalette/CommandPaletteList.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/CommandPalette/CommandPaletteList.doc.mjs docsDense name unknown_field",- "packages/core/src/CommandPalette/CommandPaletteList.doc.mjs docsZh displayName unknown_field","packages/core/src/CommandPalette/CommandPaletteList.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/CommandPalette/CommandPaletteList.doc.mjs docsZh name unknown_field","packages/core/src/ComplexSelector/ComplexSelector.doc.mjs docsDense category unknown_field",- "packages/core/src/ComplexSelector/ComplexSelector.doc.mjs docsDense displayName unknown_field","packages/core/src/ComplexSelector/ComplexSelector.doc.mjs docsDense group unknown_field",- "packages/core/src/ComplexSelector/ComplexSelector.doc.mjs docsDense name unknown_field",- "packages/core/src/ContextMenu/ContextMenuItem.doc.mjs docsDense displayName unknown_field","packages/core/src/ContextMenu/ContextMenuItem.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/ContextMenu/ContextMenuItem.doc.mjs docsDense name unknown_field",- "packages/core/src/Dialog/DialogHeader.doc.mjs docsDense displayName unknown_field","packages/core/src/Dialog/DialogHeader.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Dialog/DialogHeader.doc.mjs docsDense name unknown_field",- "packages/core/src/Dialog/useImperativeDialog.doc.mjs docsDense name unknown_field",- "packages/core/src/Drawer/DrawerHeader.doc.mjs docsDense displayName unknown_field","packages/core/src/Drawer/DrawerHeader.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Drawer/DrawerHeader.doc.mjs docsDense name unknown_field",- "packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs docsDense displayName unknown_field","packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs docsDense name unknown_field",- "packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs docsZh displayName unknown_field","packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs docsZh name unknown_field",- "packages/core/src/DropdownMenu/DropdownMenuDivider.doc.mjs docsDense displayName unknown_field","packages/core/src/DropdownMenu/DropdownMenuDivider.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/DropdownMenu/DropdownMenuDivider.doc.mjs docsDense name unknown_field",- "packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs docsDense displayName unknown_field","packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs docsDense name unknown_field",- "packages/core/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs docsDense displayName unknown_field","packages/core/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs docsDense name unknown_field",- "packages/core/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs docsZh displayName unknown_field","packages/core/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs docsZh name unknown_field",- "packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs docsDense displayName unknown_field","packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs docsDense name unknown_field",- "packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs docsZh displayName unknown_field","packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs docsZh name unknown_field",- "packages/core/src/DropdownMenu/DropdownMenuSubMenu.doc.mjs docsDense displayName unknown_field","packages/core/src/DropdownMenu/DropdownMenuSubMenu.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/DropdownMenu/DropdownMenuSubMenu.doc.mjs docsDense name unknown_field",- "packages/core/src/Field/FieldLabel.doc.mjs docsDense displayName unknown_field","packages/core/src/Field/FieldLabel.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Field/FieldLabel.doc.mjs docsDense name unknown_field",- "packages/core/src/Grid/GridSpan.doc.mjs docsDense displayName unknown_field","packages/core/src/Grid/GridSpan.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Grid/GridSpan.doc.mjs docsDense name unknown_field",- "packages/core/src/InputGroup/InputGroupText.doc.mjs docsDense displayName unknown_field","packages/core/src/InputGroup/InputGroupText.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/InputGroup/InputGroupText.doc.mjs docsDense name unknown_field",- "packages/core/src/Layout/LayoutContent.doc.mjs docsDense displayName unknown_field","packages/core/src/Layout/LayoutContent.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Layout/LayoutContent.doc.mjs docsDense name unknown_field",- "packages/core/src/Layout/LayoutFooter.doc.mjs docsDense displayName unknown_field","packages/core/src/Layout/LayoutFooter.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Layout/LayoutFooter.doc.mjs docsDense name unknown_field",- "packages/core/src/Layout/LayoutHeader.doc.mjs docsDense displayName unknown_field","packages/core/src/Layout/LayoutHeader.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Layout/LayoutHeader.doc.mjs docsDense name unknown_field",- "packages/core/src/Layout/LayoutPanel.doc.mjs docsDense displayName unknown_field","packages/core/src/Layout/LayoutPanel.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Layout/LayoutPanel.doc.mjs docsDense name unknown_field",- "packages/core/src/List/ListItem.doc.mjs docsDense displayName unknown_field","packages/core/src/List/ListItem.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/List/ListItem.doc.mjs docsDense name unknown_field","packages/core/src/Markdown/Markdown.doc.mjs docsZh theming.targets[1].description unknown_field","packages/core/src/Markdown/Markdown.doc.mjs docsZh theming.targets[2].description unknown_field","packages/core/src/Markdown/Markdown.doc.mjs docsZh theming.targets[3].description unknown_field",@@ -197,110 +65,28 @@"packages/core/src/Markdown/Markdown.doc.mjs docsZh theming.targets[6].description unknown_field","packages/core/src/Markdown/Markdown.doc.mjs docsZh theming.targets[7].description unknown_field","packages/core/src/Markdown/Markdown.doc.mjs docsZh theming.targets[8].description unknown_field",- "packages/core/src/MetadataList/MetadataListItem.doc.mjs docsDense displayName unknown_field","packages/core/src/MetadataList/MetadataListItem.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/MetadataList/MetadataListItem.doc.mjs docsDense name unknown_field",- "packages/core/src/MetadataList/MetadataListItem.doc.mjs docsZh displayName unknown_field","packages/core/src/MetadataList/MetadataListItem.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/MetadataList/MetadataListItem.doc.mjs docsZh name unknown_field",- "packages/core/src/RadioList/RadioListItem.doc.mjs docsDense displayName unknown_field","packages/core/src/RadioList/RadioListItem.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/RadioList/RadioListItem.doc.mjs docsDense name unknown_field",- "packages/core/src/SegmentedControl/SegmentedControlItem.doc.mjs docsDense displayName unknown_field","packages/core/src/SegmentedControl/SegmentedControlItem.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/SegmentedControl/SegmentedControlItem.doc.mjs docsDense name unknown_field",- "packages/core/src/SegmentedControl/SegmentedControlItem.doc.mjs docsZh displayName unknown_field","packages/core/src/SegmentedControl/SegmentedControlItem.doc.mjs docsZh isHiddenFromOverview unknown_field",- "packages/core/src/SegmentedControl/SegmentedControlItem.doc.mjs docsZh name unknown_field",- "packages/core/src/Selector/SelectorOption.doc.mjs docsDense displayName unknown_field","packages/core/src/Selector/SelectorOption.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Selector/SelectorOption.doc.mjs docsDense name unknown_field",- "packages/core/src/SideNav/SideNavCollapseButton.doc.mjs docsDense displayName unknown_field","packages/core/src/SideNav/SideNavCollapseButton.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/SideNav/SideNavCollapseButton.doc.mjs docsDense name unknown_field",- "packages/core/src/SideNav/SideNavHeading.doc.mjs docsDense displayName unknown_field","packages/core/src/SideNav/SideNavHeading.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/SideNav/SideNavHeading.doc.mjs docsDense name unknown_field",- "packages/core/src/SideNav/SideNavItem.doc.mjs docsDense displayName unknown_field","packages/core/src/SideNav/SideNavItem.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/SideNav/SideNavItem.doc.mjs docsDense name unknown_field",- "packages/core/src/SideNav/SideNavSection.doc.mjs docsDense displayName unknown_field","packages/core/src/SideNav/SideNavSection.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/SideNav/SideNavSection.doc.mjs docsDense name unknown_field",- "packages/core/src/TabList/Tab.doc.mjs docsDense displayName unknown_field","packages/core/src/TabList/Tab.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/TabList/Tab.doc.mjs docsDense name unknown_field",- "packages/core/src/TabList/TabMenu.doc.mjs docsDense displayName unknown_field","packages/core/src/TabList/TabMenu.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/TabList/TabMenu.doc.mjs docsDense name unknown_field",- "packages/core/src/Table/TableBody.doc.mjs docsDense displayName unknown_field","packages/core/src/Table/TableBody.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Table/TableBody.doc.mjs docsDense name unknown_field",- "packages/core/src/Table/TableCell.doc.mjs docsDense displayName unknown_field","packages/core/src/Table/TableCell.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Table/TableCell.doc.mjs docsDense name unknown_field",- "packages/core/src/Table/TableFooter.doc.mjs docsDense displayName unknown_field","packages/core/src/Table/TableFooter.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Table/TableFooter.doc.mjs docsDense name unknown_field",- "packages/core/src/Table/TableHeader.doc.mjs docsDense displayName unknown_field","packages/core/src/Table/TableHeader.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Table/TableHeader.doc.mjs docsDense name unknown_field",- "packages/core/src/Table/TableHeaderCell.doc.mjs docsDense displayName unknown_field","packages/core/src/Table/TableHeaderCell.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Table/TableHeaderCell.doc.mjs docsDense name unknown_field",- "packages/core/src/Table/TableRow.doc.mjs docsDense displayName unknown_field","packages/core/src/Table/TableRow.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Table/TableRow.doc.mjs docsDense name unknown_field",- "packages/core/src/Table/TableSelectionToolbar.doc.mjs docsDense displayName unknown_field",- "packages/core/src/Table/TableSelectionToolbar.doc.mjs docsDense name unknown_field",- "packages/core/src/Table/useTableColumnResize.doc.mjs docsDense displayName unknown_field",- "packages/core/src/Table/useTableColumnResize.doc.mjs docsDense name unknown_field",- "packages/core/src/Table/useTableColumnSettings.doc.mjs docsDense displayName unknown_field",- "packages/core/src/Table/useTableColumnSettings.doc.mjs docsDense name unknown_field",- "packages/core/src/Table/useTableFilterState.doc.mjs docsDense displayName unknown_field","packages/core/src/Table/useTableFilterState.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Table/useTableFilterState.doc.mjs docsDense name unknown_field",- "packages/core/src/Table/useTableFiltering.doc.mjs docsDense displayName unknown_field","packages/core/src/Table/useTableFiltering.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Table/useTableFiltering.doc.mjs docsDense name unknown_field",- "packages/core/src/Table/useTablePagination.doc.mjs docsDense displayName unknown_field",- "packages/core/src/Table/useTablePagination.doc.mjs docsDense name unknown_field",- "packages/core/src/Table/useTableSelection.doc.mjs docsDense displayName unknown_field",- "packages/core/src/Table/useTableSelection.doc.mjs docsDense name unknown_field",- "packages/core/src/Table/useTableSelectionState.doc.mjs docsDense displayName unknown_field",- "packages/core/src/Table/useTableSelectionState.doc.mjs docsDense name unknown_field",- "packages/core/src/Table/useTableSortable.doc.mjs docsDense displayName unknown_field",- "packages/core/src/Table/useTableSortable.doc.mjs docsDense name unknown_field",- "packages/core/src/Table/useTableStickyColumns.doc.mjs docsDense displayName unknown_field",- "packages/core/src/Table/useTableStickyColumns.doc.mjs docsDense name unknown_field",- "packages/core/src/Table/useTableTreeData.doc.mjs docsDense displayName unknown_field",- "packages/core/src/Table/useTableTreeData.doc.mjs docsDense name unknown_field",- "packages/core/src/Table/useTableTreeState.doc.mjs docsDense displayName unknown_field",- "packages/core/src/Table/useTableTreeState.doc.mjs docsDense name unknown_field",- "packages/core/src/Text/Heading.doc.mjs docsDense displayName unknown_field",- "packages/core/src/Text/Heading.doc.mjs docsDense name unknown_field",- "packages/core/src/ToggleButton/ToggleButtonGroup.doc.mjs docsDense displayName unknown_field",- "packages/core/src/ToggleButton/ToggleButtonGroup.doc.mjs docsDense name unknown_field",- "packages/core/src/ToggleButton/ToggleButtonGroup.doc.mjs docsZh displayName unknown_field",- "packages/core/src/ToggleButton/ToggleButtonGroup.doc.mjs docsZh name unknown_field",- "packages/core/src/TopNav/TopNavHeading.doc.mjs docsDense displayName unknown_field","packages/core/src/TopNav/TopNavHeading.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/TopNav/TopNavHeading.doc.mjs docsDense name unknown_field",- "packages/core/src/TopNav/TopNavItem.doc.mjs docsDense displayName unknown_field","packages/core/src/TopNav/TopNavItem.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/TopNav/TopNavItem.doc.mjs docsDense name unknown_field",- "packages/core/src/TopNav/TopNavMegaMenu.doc.mjs docsDense displayName unknown_field",- "packages/core/src/TopNav/TopNavMegaMenu.doc.mjs docsDense name unknown_field",- "packages/core/src/TopNav/TopNavMegaMenuFeaturedCard.doc.mjs docsDense displayName unknown_field",- "packages/core/src/TopNav/TopNavMegaMenuFeaturedCard.doc.mjs docsDense name unknown_field",- "packages/core/src/TopNav/TopNavMegaMenuItem.doc.mjs docsDense displayName unknown_field","packages/core/src/TopNav/TopNavMegaMenuItem.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/TopNav/TopNavMegaMenuItem.doc.mjs docsDense name unknown_field",- "packages/core/src/TopNav/TopNavMenu.doc.mjs docsDense displayName unknown_field",- "packages/core/src/TopNav/TopNavMenu.doc.mjs docsDense name unknown_field",- "packages/core/src/Typeahead/BaseTypeahead.doc.mjs docsDense displayName unknown_field",- "packages/core/src/Typeahead/BaseTypeahead.doc.mjs docsDense isHiddenFromOverview unknown_field",- "packages/core/src/Typeahead/BaseTypeahead.doc.mjs docsDense name unknown_field",- "packages/core/src/Typeahead/TypeaheadItem.doc.mjs docsDense displayName unknown_field",- "packages/core/src/Typeahead/TypeaheadItem.doc.mjs docsDense name unknown_field"+ "packages/core/src/Typeahead/BaseTypeahead.doc.mjs docsDense isHiddenFromOverview unknown_field"]diff --git a/packages/cli/test/integration-check-failures.json b/packages/cli/test/integration-check-failures.jsonindex d92f4bcf40..da3c4d83d3 100644--- a/packages/cli/test/integration-check-failures.json+++ b/packages/cli/test/integration-check-failures.json@@ -17,10 +17,14 @@"component_name_conflict","copied_passage","core_not_found",+ "default_mismatch","doc_fluff","doc_types_skipped","duplicate_doc",+ "duplicate_prop","duplicate_provider",+ "duplicate_section_key",+ "empty_section","inactive_component_replacement","integration_error","invalid_agent_docs",@@ -47,6 +51,7 @@"no_package","not_in_code","not_in_doc",+ "orphan_doc_overlay","package_not_found","prop_drift_skipped","prop_types_skipped",@@ -59,6 +64,7 @@"type_mismatch","unknown_field","unknown_manifest_key",+ "unknown_translated_prop","unreachable_contribution","unreachable_scan_truncated","unread_theme_folder",