An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): integration check flags component names that do not resolve: a doc name its import does not export, and a block naming no component (#7783)
Joeyeff0b72ac27b
diff --git a/.changeset/cli-component-doc-name-check.md b/.changeset/cli-component-doc-name-check.mdnew file mode 100644index 0000000000..863499a3e2--- /dev/null+++ b/.changeset/cli-component-doc-name-check.md@@ -0,0 +1,12 @@+---+'@astryxdesign/cli': patch+---++[feat] `astryx doctor integration validate` and `astryx integration check` check the component names a package's docs and blocks give, and list what they find as notes beside validate's issues, each with its fix. Nothing counts a note and `integration check --strict` does not fail on them; they become failing warnings in the next minor release:++- `doc_name_mismatch` lists a component doc whose `name` is not the name the component is listed under when the module its printed import names (the doc's `import`, the published subpath, or the package root) provably does not export that name, so `astryx component` would print a broken import. The `Fix:` proposes the file name when that module exports it, otherwise the component it exports. A name that module's exports cannot prove or rule out (a re-export from another package, `export =`, a destructured binding, a namespace, an import that resolves to no file, or, when no import can be resolved, a source that only exports a default) is listed as not checked, with the reason, in validate's new `docNames` report.+- `unknown_block_component` lists a name a template's `exampleFor` or `componentsUsed` gives that neither the package nor Core has (every doc `astryx component` resolves in Core counts) and the template does not import it. Imports the template's local helpers make count too, including through a barrel such as `parts/index.ts`. A name is judged only where the template reaches components solely through named imports and re-exports from Core, React, StyleX, local helpers read in full, or the package's own name (followed through its `exports` like a helper): anything else (an import from another package, which may render other components, any `default` binding (other than React's or StyleX's), a namespace import, an alias of or member read off an imported binding, a component held in a variable, `require()`, a dynamic `import()`, a file that does not parse cleanly, or a local module this check cannot read), and, without Core installed, any name only Core could resolve, is listed as not checked in validate's new `blockComponents` report.++`integration check --strict` does not fail on anything listed as not checked.++@josephfarinadiff --git a/packages/cli/README.md b/packages/cli/README.mdindex 21f488aea7..705d497a60 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -470,69 +470,69 @@ Every response has a `type` discriminant. The full set is below (generated from<!-- BEGIN GENERATED: response-types -->-| Type | What `data` carries |-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |-| `init.run` | The install receipt: the `mode` (`default` \| `features`), the features run, agent-doc files written, any soft `docsError`, whether theme guidance was emitted, the template outcome (`workflow` \| `created` \| `skipped`) plus its path, and whether the next-steps were emitted. |-| `init.remove` | The removal receipt — returned when --remove-agents is set: `data.removed` is true when a managed agent-docs block was found and removed, and false when there was none to remove. |-| `init.user` | The computer-level agent text receipt — returned when --user is set: `data.files`, one `{path, action, reason?}` per path acted on, the skill file first and then each link to its folder (action `written` \| `linked` \| `unchanged` \| `removed` \| `absent` \| `kept`; `reason` only on `kept`: `edited` when a person changed the text, `not-astryx` when Astryx did not write it), `data.command` (the command the text names), and `data.warnings`. |-| `component.list` | The component catalog grouped by component group (each component's group field): `detail` (the level: names \| compact \| full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries ({name, package, description, import}), or a full ComponentDoc per entry with its package. |-| `component.batch` | The component specialization of the shared `BatchResponse` and `BatchRow` types. An explicit programmatic selector array, or two or more CLI selectors, returns one ordered receipt: `count` plus `results`, one row per selector including duplicates. Every row carries `selector` and `status` (found \| not_found \| ambiguous \| error). A found row carries `result`, the same {type, data} response as one selector. An ambiguous row carries `code`, `error`, and `candidates` ({package, component, kind, installed}). Other failed rows carry `code`, `error`, and optional `suggestions` ({name, reason}). |-| `component.detail` | One component's authored ComponentDoc plus ownership fields (package, the owner; import, the specifier; sourceAvailable, whether source exists) and parentDoc (present when the component is documented inside another component's doc, naming that doc). The envelope's package names the same owner. |-| `component.detail.props` | Just one component's props table (ComponentPropDoc[]). The envelope's package names the npm package that owns the component. |-| `component.detail.source` | One component's source file, as {component, source}. The envelope's package names the npm package that owns the component. |-| `component.detail.showcase` | One component's showcase example, as {component, aspectRatio, source}. The envelope's package names the npm package that owns the component. |-| `component.detail.blocks` | One component's example blocks, as {component, showcase, examples, related} of BlockEntry ({name, package, displayName, description, isShowcase, category}); each block names the package that owns it, and the envelope's package names the component's owner. |-| `docs.list` | All reference-doc topics as DocsListEntry[] ({topic, description, package, replaces?}), in read order; meta.namespaces lists the docs tree's top-level namespaces, and meta.notLoaded each package whose docs did not load. |-| `docs.detail` | One topic's full ReferenceDoc (the JSON read of a topic, --full, --dense, or a topic with one section), with token-ref blocks inlined and each section naming the package that wrote it, plus links ({up, previous, next}: the commands that open the level it sits in and its neighbors there). |-| `docs.index` | One topic's section index, the text read of a topic with more than one section (and --index): the topic's name, title, and description, plus sections, each {id, title, package, summary} (pass the id as the section argument; package is the npm package that wrote the section; summary is the section's one-line summary), and links ({up, previous, next}: the commands that open the level it sits in and its neighbors there). |-| `docs.detail.section` | One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open its topic index and the sections before and after it). The envelope's package names the npm package that wrote the section. |-| `docs.node` | One node of the docs tree, read by its route: its id, kind, package, title, summary, and breadcrumb, plus a namespace's slots with their children (one level down, each naming its package) or a typed doc's content, and links ({up, previous, next, related}: the commands that open its parent, its neighbors, and the docs it names). |-| `blog.list` | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL. |-| `blog.detail` | One post's metadata plus the feed URL and the post's full plaintext body. |-| `discover.list` | What the project has, the integrations it loads and the official packages it declares, official packages first (name, category, components, version, a list per other kind they add, and latest when a source knows it); meta.available lists what the project could add, the official packages first, each with the command that adds it, and meta.sources reports each source, the official list last; when it lists no integration it carries meta.configured to tell "nothing configured" from "nothing discovered". |-| `discover.detail` | One package, for an @scope/name or @scope/name@version query: what the shown version adds, whether the project has it, and, when a source knows the package, its versions, latest release, and the command that adds it. |-| `discover.detail.doc` | The validated ComponentDoc for one installed component, for an @scope/name/Component query. |-| `discover.item` | One item that is not an installed component, for an @scope/name/<item> query: its kind, name, package, version, and whether the project has the package. |-| `discover.search` | The echoed query plus every matching item and package across all packages, each with its kind and whether the project has it, even when only one matches; total is set when --limit cut the list. |-| `search` | The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, package, score, reason, description, command} (package is the npm package that owns the result), plus import (components, hooks), title, parent (the command that opens the level above), and, for a hit on one section, section (docs), or displayName and kind (templates). When a search with no `type` could not obtain @astryxdesign/core, `meta.partial` is {skipped, reason}: the domains it skipped (component, hook, template) and why. |-| `build.help` | The how-to-build-a-page playbook, emitted when no query is given: `playbook: true`, a title, the ordered steps (title, commands, optional returns), the on-system rules, and related lookups. Commands are bare subcommands for the caller to render with its own invocation. |-| `build.kit` | The template to start from and its kit: query, hasResults, matchCount (never a cap), directMatch, start {name, package, command, basis, reason, alternatives, ...} (the start and each alternative name the package that owns the template), pages (search's closest templates), blocks and domain as SearchResultEntry[] (each naming its package), frame and foundation (Core component names), and hint {reason, commands} when thin. |-| `swizzle.list` | The names of swizzlable components discoverable from cwd's @astryxdesign/core. The envelope's package is @astryxdesign/core. |-| `swizzle.copy` | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and, when the owner has an issues URL, feedback ({issuesUrl, ghCommand?}): where to report the gap that led to swizzling. The envelope's package names the same owning package. |-| `gap-report.categories` | The fixed gap category values and human-readable labels; when a loaded integration names its own issues URL, meta.destinations lists every destination ({to, default, issuesUrl}) and meta.ask tells an agent to ask the person. |-| `gap-report.file` | An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project \| integration \| fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals; without --to, when a loaded integration names its own issues URL, destinations and ask as on gap-report.categories. |-| `template.list` | The effective discovered TemplateListEntry[] for pages and blocks. A winning replacement entry includes optional `replaces`, naming the Core id omitted from the default list. |-| `template.show` | The resolved template's source, exactly as a copy writes it, plus its description, kind, the component names it composes, and demoMediaReplaced (how many Astryx demo media references were replaced with placeholders for you to swap for your own media). |-| `template.skeleton` | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes. The envelope's package names the npm package that owns the template. |-| `template.copy` | A scaffold receipt: template id, output directory, written file name, file count, demoMediaReplaced (how many Astryx demo media references were replaced with placeholders), notes (setup notes naming what the template needs that the project lacks — missing packages, missing StyleX compiler; empty when satisfied), missingPackages (external package names the template imports that are not in the project), and installCommand (a ready-to-run install command with the detected package manager and workspace version ranges; null when nothing is missing, or when several lockfiles leave the package manager undetermined). The envelope's package names the npm package that owns the template. |-| `template.cdn` | A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not. `exists` when a file was already there, which is a success. |-| `hook.list` | The hook catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry. The envelope's package is @astryxdesign/core, the only package that ships hooks. |-| `hook.detail` | One hook's full authored HookDoc. The envelope's package is @astryxdesign/core. |-| `hook.detail.params` | Just one hook's parameters table (HookParamDoc[]). The envelope's package is @astryxdesign/core. |-| `theme.build` | A theme build receipt: name, tokenCount and componentCount (override counts), sizeKB, the written outputs {css, cssDts, js, dts, and variantsDts when applicable}, warnings (defects to fix), and notices (advisories about a correct theme, such as a named font it does not load). |-| `theme.build.check` | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing. |-| `theme.build.batch` | Several themes built in one invocation: `count` plus one {file, receipt} per theme in argument order, where receipt is that theme's theme.build (or theme.build.check) envelope, or null when it produced no CSS. |-| `theme.list` | Every bundled, installed package, and local theme as a ThemeListEntry[]. Each entry has slug, displayName, description, maintained, owner package or local root, source, added, and default fields. Optional meta.unmigratedCopies names earlier descriptor-less copies, their missing descriptor, and the upgrade command; those copies are not data entries. |-| `theme.app` | The app theme record after add, remove, or use. It includes every added theme and its built imports, the default slug, generated module path, and the command change. After add, the envelope package names the npm package that owns the added theme; a local theme has none. |-| `theme.eject` | A local source-fork receipt with the resolved slug, displayName, source theme maintained flag, source-selector package, outputDir, source entry, exportName, and every file written, including the descriptor. The written local descriptor always uses maintained: false. |-| `theme.template` | A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not. `exists` when a file was already there, which is a success. |-| `theme.targets` | The whole themeable surface: the echoed filter, componentCount, and targets, one per theming target — {key, className, component, props, states}, where props and states are its legal override keys. |-| `theme.palette.generate` | An author-reviewable OKLCH palette candidate, its reproducibility receipt, summary counts, and optional candidate/receipt file-write result. |-| `upgrade.list` | Every available codemod, oldest→newest, as {name, package, title, version, optional}; returned for --list without running anything. |-| `upgrade.registry` | The copied-composition receipt for --registry: applied, ok, the counts (found, current, wouldUpdate, updated, wouldMerge, merged, wouldRefreshReceipt, receiptsRefreshed, conflicts, missing, invalid, failed), and items. |-| `upgrade.status` | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary. no_codemods and config_fixable carry cliBehindCore ({cliVersion, command}) when the installed Core is newer than the CLI, which then has no codemods for the releases after its own version. |-| `upgrade.run` | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, sourcePathFound (false when the resolved source directory does not exist, so no source file was read), and (apply mode) filesChanged, transformsApplied, and per-codemod errors. When the installed Core is newer than the CLI, it also carries cliBehindCore ({cliVersion, command}): codemods for the releases after cliVersion did not run. |-| `manifest` | The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], outsideProject? (same, refuse, or own; absent on a group), subcommands?), jsonSupported, globalMode ({docs, summary}: what a run may do beyond its command, such as the hand-off to the project's own CLI, the daily update check, and the agent skill file, and the docs topic that explains it), and the flat responseTypes index. |-| `help` | Help, in one of two shapes. A bare `astryx --json` returns the root manifest: name, version, commands (the command names), jsonSupported, and manifest (the full payload `astryx manifest --json` returns). `--help --json` on any command, or `astryx help [command] --json`, returns that command's help: command, description, usage, options (each flags, description, and defaultValue and choices when set), and subcommands (each name and description). data.manifest marks the first shape; data.usage marks the second. |-| `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, 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), and notes when there are any: {code, message} information that fails nothing, such as invalid_cli_command for a malformed cliCommand, and the package layout findings added after the last minor release, each with its fix in the message (duplicate_component_doc, symlinked_root, unreadable_file, invalid_package_json, no_provider_id, source_without_component_doc where a doc and its source still pair), until they become warnings in the next minor release. 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; 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 (relative to the package root), line, density, and message (what to cut or write instead); each is also a doc_fluff warning in issues. strayPointers lists each code span that is exactly `astryx docs <name>` for a doc that exists, in the prose, description or summary of a topic or the text fields of a component doc: topic (the topic or component doc), kind (topic \| component), section, field (the field outside any section, such as description or usage.bestPractices[0].description, else null), file (relative to the package root), line, pointer (the written command), link (the {@link} that replaces it), and message; each is also a stray_doc_pointer 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. |+| Type | What `data` carries |+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `init.run` | The install receipt: the `mode` (`default` \| `features`), the features run, agent-doc files written, any soft `docsError`, whether theme guidance was emitted, the template outcome (`workflow` \| `created` \| `skipped`) plus its path, and whether the next-steps were emitted. |+| `init.remove` | The removal receipt — returned when --remove-agents is set: `data.removed` is true when a managed agent-docs block was found and removed, and false when there was none to remove. |+| `init.user` | The computer-level agent text receipt — returned when --user is set: `data.files`, one `{path, action, reason?}` per path acted on, the skill file first and then each link to its folder (action `written` \| `linked` \| `unchanged` \| `removed` \| `absent` \| `kept`; `reason` only on `kept`: `edited` when a person changed the text, `not-astryx` when Astryx did not write it), `data.command` (the command the text names), and `data.warnings`. |+| `component.list` | The component catalog grouped by component group (each component's group field): `detail` (the level: names \| compact \| full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries ({name, package, description, import}), or a full ComponentDoc per entry with its package. |+| `component.batch` | The component specialization of the shared `BatchResponse` and `BatchRow` types. An explicit programmatic selector array, or two or more CLI selectors, returns one ordered receipt: `count` plus `results`, one row per selector including duplicates. Every row carries `selector` and `status` (found \| not_found \| ambiguous \| error). A found row carries `result`, the same {type, data} response as one selector. An ambiguous row carries `code`, `error`, and `candidates` ({package, component, kind, installed}). Other failed rows carry `code`, `error`, and optional `suggestions` ({name, reason}). |+| `component.detail` | One component's authored ComponentDoc plus ownership fields (package, the owner; import, the specifier; sourceAvailable, whether source exists) and parentDoc (present when the component is documented inside another component's doc, naming that doc). The envelope's package names the same owner. |+| `component.detail.props` | Just one component's props table (ComponentPropDoc[]). The envelope's package names the npm package that owns the component. |+| `component.detail.source` | One component's source file, as {component, source}. The envelope's package names the npm package that owns the component. |+| `component.detail.showcase` | One component's showcase example, as {component, aspectRatio, source}. The envelope's package names the npm package that owns the component. |+| `component.detail.blocks` | One component's example blocks, as {component, showcase, examples, related} of BlockEntry ({name, package, displayName, description, isShowcase, category}); each block names the package that owns it, and the envelope's package names the component's owner. |+| `docs.list` | All reference-doc topics as DocsListEntry[] ({topic, description, package, replaces?}), in read order; meta.namespaces lists the docs tree's top-level namespaces, and meta.notLoaded each package whose docs did not load. |+| `docs.detail` | One topic's full ReferenceDoc (the JSON read of a topic, --full, --dense, or a topic with one section), with token-ref blocks inlined and each section naming the package that wrote it, plus links ({up, previous, next}: the commands that open the level it sits in and its neighbors there). |+| `docs.index` | One topic's section index, the text read of a topic with more than one section (and --index): the topic's name, title, and description, plus sections, each {id, title, package, summary} (pass the id as the section argument; package is the npm package that wrote the section; summary is the section's one-line summary), and links ({up, previous, next}: the commands that open the level it sits in and its neighbors there). |+| `docs.detail.section` | One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open its topic index and the sections before and after it). The envelope's package names the npm package that wrote the section. |+| `docs.node` | One node of the docs tree, read by its route: its id, kind, package, title, summary, and breadcrumb, plus a namespace's slots with their children (one level down, each naming its package) or a typed doc's content, and links ({up, previous, next, related}: the commands that open its parent, its neighbors, and the docs it names). |+| `blog.list` | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL. |+| `blog.detail` | One post's metadata plus the feed URL and the post's full plaintext body. |+| `discover.list` | What the project has, the integrations it loads and the official packages it declares, official packages first (name, category, components, version, a list per other kind they add, and latest when a source knows it); meta.available lists what the project could add, the official packages first, each with the command that adds it, and meta.sources reports each source, the official list last; when it lists no integration it carries meta.configured to tell "nothing configured" from "nothing discovered". |+| `discover.detail` | One package, for an @scope/name or @scope/name@version query: what the shown version adds, whether the project has it, and, when a source knows the package, its versions, latest release, and the command that adds it. |+| `discover.detail.doc` | The validated ComponentDoc for one installed component, for an @scope/name/Component query. |+| `discover.item` | One item that is not an installed component, for an @scope/name/<item> query: its kind, name, package, version, and whether the project has the package. |+| `discover.search` | The echoed query plus every matching item and package across all packages, each with its kind and whether the project has it, even when only one matches; total is set when --limit cut the list. |+| `search` | The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, package, score, reason, description, command} (package is the npm package that owns the result), plus import (components, hooks), title, parent (the command that opens the level above), and, for a hit on one section, section (docs), or displayName and kind (templates). When a search with no `type` could not obtain @astryxdesign/core, `meta.partial` is {skipped, reason}: the domains it skipped (component, hook, template) and why. |+| `build.help` | The how-to-build-a-page playbook, emitted when no query is given: `playbook: true`, a title, the ordered steps (title, commands, optional returns), the on-system rules, and related lookups. Commands are bare subcommands for the caller to render with its own invocation. |+| `build.kit` | The template to start from and its kit: query, hasResults, matchCount (never a cap), directMatch, start {name, package, command, basis, reason, alternatives, ...} (the start and each alternative name the package that owns the template), pages (search's closest templates), blocks and domain as SearchResultEntry[] (each naming its package), frame and foundation (Core component names), and hint {reason, commands} when thin. |+| `swizzle.list` | The names of swizzlable components discoverable from cwd's @astryxdesign/core. The envelope's package is @astryxdesign/core. |+| `swizzle.copy` | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and, when the owner has an issues URL, feedback ({issuesUrl, ghCommand?}): where to report the gap that led to swizzling. The envelope's package names the same owning package. |+| `gap-report.categories` | The fixed gap category values and human-readable labels; when a loaded integration names its own issues URL, meta.destinations lists every destination ({to, default, issuesUrl}) and meta.ask tells an agent to ask the person. |+| `gap-report.file` | An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project \| integration \| fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals; without --to, when a loaded integration names its own issues URL, destinations and ask as on gap-report.categories. |+| `template.list` | The effective discovered TemplateListEntry[] for pages and blocks. A winning replacement entry includes optional `replaces`, naming the Core id omitted from the default list. |+| `template.show` | The resolved template's source, exactly as a copy writes it, plus its description, kind, the component names it composes, and demoMediaReplaced (how many Astryx demo media references were replaced with placeholders for you to swap for your own media). |+| `template.skeleton` | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes. The envelope's package names the npm package that owns the template. |+| `template.copy` | A scaffold receipt: template id, output directory, written file name, file count, demoMediaReplaced (how many Astryx demo media references were replaced with placeholders), notes (setup notes naming what the template needs that the project lacks — missing packages, missing StyleX compiler; empty when satisfied), missingPackages (external package names the template imports that are not in the project), and installCommand (a ready-to-run install command with the detected package manager and workspace version ranges; null when nothing is missing, or when several lockfiles leave the package manager undetermined). The envelope's package names the npm package that owns the template. |+| `template.cdn` | A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not. `exists` when a file was already there, which is a success. |+| `hook.list` | The hook catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry. The envelope's package is @astryxdesign/core, the only package that ships hooks. |+| `hook.detail` | One hook's full authored HookDoc. The envelope's package is @astryxdesign/core. |+| `hook.detail.params` | Just one hook's parameters table (HookParamDoc[]). The envelope's package is @astryxdesign/core. |+| `theme.build` | A theme build receipt: name, tokenCount and componentCount (override counts), sizeKB, the written outputs {css, cssDts, js, dts, and variantsDts when applicable}, warnings (defects to fix), and notices (advisories about a correct theme, such as a named font it does not load). |+| `theme.build.check` | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing. |+| `theme.build.batch` | Several themes built in one invocation: `count` plus one {file, receipt} per theme in argument order, where receipt is that theme's theme.build (or theme.build.check) envelope, or null when it produced no CSS. |+| `theme.list` | Every bundled, installed package, and local theme as a ThemeListEntry[]. Each entry has slug, displayName, description, maintained, owner package or local root, source, added, and default fields. Optional meta.unmigratedCopies names earlier descriptor-less copies, their missing descriptor, and the upgrade command; those copies are not data entries. |+| `theme.app` | The app theme record after add, remove, or use. It includes every added theme and its built imports, the default slug, generated module path, and the command change. After add, the envelope package names the npm package that owns the added theme; a local theme has none. |+| `theme.eject` | A local source-fork receipt with the resolved slug, displayName, source theme maintained flag, source-selector package, outputDir, source entry, exportName, and every file written, including the descriptor. The written local descriptor always uses maintained: false. |+| `theme.template` | A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not. `exists` when a file was already there, which is a success. |+| `theme.targets` | The whole themeable surface: the echoed filter, componentCount, and targets, one per theming target — {key, className, component, props, states}, where props and states are its legal override keys. |+| `theme.palette.generate` | An author-reviewable OKLCH palette candidate, its reproducibility receipt, summary counts, and optional candidate/receipt file-write result. |+| `upgrade.list` | Every available codemod, oldest→newest, as {name, package, title, version, optional}; returned for --list without running anything. |+| `upgrade.registry` | The copied-composition receipt for --registry: applied, ok, the counts (found, current, wouldUpdate, updated, wouldMerge, merged, wouldRefreshReceipt, receiptsRefreshed, conflicts, missing, invalid, failed), and items. |+| `upgrade.status` | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary. no_codemods and config_fixable carry cliBehindCore ({cliVersion, command}) when the installed Core is newer than the CLI, which then has no codemods for the releases after its own version. |+| `upgrade.run` | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, sourcePathFound (false when the resolved source directory does not exist, so no source file was read), and (apply mode) filesChanged, transformsApplied, and per-codemod errors. When the installed Core is newer than the CLI, it also carries cliBehindCore ({cliVersion, command}): codemods for the releases after cliVersion did not run. |+| `manifest` | The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], outsideProject? (same, refuse, or own; absent on a group), subcommands?), jsonSupported, globalMode ({docs, summary}: what a run may do beyond its command, such as the hand-off to the project's own CLI, the daily update check, and the agent skill file, and the docs topic that explains it), and the flat responseTypes index. |+| `help` | Help, in one of two shapes. A bare `astryx --json` returns the root manifest: name, version, commands (the command names), jsonSupported, and manifest (the full payload `astryx manifest --json` returns). `--help --json` on any command, or `astryx help [command] --json`, returns that command's help: command, description, usage, options (each flags, description, and defaultValue and choices when set), and subcommands (each name and description). data.manifest marks the first shape; data.usage marks the second. |+| `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, 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), and notes when there are any: {code, message} information that fails nothing, such as invalid_cli_command for a malformed cliCommand, and the package layout findings added after the last minor release, each with its fix in the message (duplicate_component_doc, symlinked_root, unreadable_file, invalid_package_json, no_provider_id, source_without_component_doc where a doc and its source still pair), and doc_name_mismatch and unknown_block_component, until they become warnings in the next minor release. 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). When the manifest loads, docNames lists the component doc names it could not judge: status (checked), findings (always empty; a doc name the module its import names provably does not export is a doc_name_mismatch note, with its fix in the message) and unchecked ({file, name, reason}: a doc whose name differs from the name it is listed under and whose source exports cannot all be read, such as a re-export from another package). When the manifest loads, blockComponents lists the component names templates give in exampleFor or componentsUsed that could not be judged: status (checked), findings (always empty; a name neither the package nor Core has, and the template does not import, is an unknown_block_component note, with its fix in the message) and unchecked ({file, name, reason}: a name the template may reach through anything other than named imports and re-exports from Core, React, StyleX, local helpers or the entry of the package itself, such as an import from another package, a default or namespace import, an alias of or member read off an imported binding, require() or a dynamic import(), or a local module that cannot be read, or any name Core would have to resolve when Core is not installed). |+| `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; 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 (relative to the package root), line, density, and message (what to cut or write instead); each is also a doc_fluff warning in issues. strayPointers lists each code span that is exactly `astryx docs <name>` for a doc that exists, in the prose, description or summary of a topic or the text fields of a component doc: topic (the topic or component doc), kind (topic \| component), section, field (the field outside any section, such as description or usage.bestPractices[0].description, else null), file (relative to the package root), line, pointer (the written command), link (the {@link} that replaces it), and message; each is also a stray_doc_pointer 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. |<!-- END GENERATED: response-types --><!-- Generated by scripts/generate-cli-readme.mjs from the response-types EnumDoc. Run `pnpm -F @astryxdesign/cli readme`. -->diff --git a/packages/cli/api/integration/validate-integration-gaps.test.mjs b/packages/cli/api/integration/validate-integration-gaps.test.mjsindex 47180db4e9..95b7d4a44b 100644--- a/packages/cli/api/integration/validate-integration-gaps.test.mjs+++ b/packages/cli/api/integration/validate-integration-gaps.test.mjs@@ -14,9 +14,10 @@import {afterEach, beforeEach, describe, expect, it} from 'vitest';import * as fs from 'node:fs';+import * as os from 'node:os';import * as path from 'node:path';+import {parse} from '@babel/parser';import {spawnSync} from 'node:child_process';-import {fileURLToPath} from 'node:url';import {validateIntegration,validateLocalIntegration,@@ -26,14 +27,21 @@ import {strictIssues,summarizeCheck,} from './check/check.mjs';--const CLI = fileURLToPath(- new URL('../../clients/cli/bin/astryx.mjs', import.meta.url),-);+import {componentDocNamesCheck} from '../../foundation/integrations/validate-contributions.mjs';let tmpDir;let copies = 0;+const CLI = path.join(+ process.cwd(),+ 'packages',+ 'cli',+ 'clients',+ 'cli',+ 'bin',+ 'astryx.mjs',+);+beforeEach(() => {tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-validate-gaps-'));});@@ -140,34 +148,820 @@ function only(issues, code) {return found[0].message;}+/**+ * A component doc whose import names its published subpath.+ * @param {string} stem the doc's file name+ * @param {string} name+ */+const namedDoc = (stem, name) =>+ componentDoc(name).replace(+ "type: 'component',",+ `type: 'component', import: '@acme/kit/components/${stem}',`,+ );+/**+ * A package that publishes each file under its components folder.+ * @param {Record<string, string>} files+ */+const writeNamed = files =>+ writePackage(files, {+ name: '@acme/kit',+ version: '1.0.0',+ exports: {+ './components/*': './components/*.tsx',+ '.': './index.ts',+ },+ });+describe('a name that differs from its file name', () => {- it('accepts a kebab-case file whose doc names the export it holds', async () => {+ it('lists a component doc whose name is not the name it is listed under, without an issue', async () => {+ const dir = writeNamed({+ [MANIFEST]: manifest({components: './components'}),+ 'components/AcmeWidget.doc.mjs': namedDoc('AcmeWidget', 'AcmeWidgets'),+ 'components/AcmeWidget.tsx': componentSource('AcmeWidget'),+ });++ expect(await issuesOf(dir)).toEqual([]);+ const issues = await allOf(dir);+ expect(issues.map(issue => issue.code)).toEqual(['doc_name_mismatch']);+ expect(Object.keys(issues[0]).sort()).toEqual(['code', 'message']);+ expect(issues[0].message).toBe(+ 'Component doc "AcmeWidget.doc.mjs" sets name: \'AcmeWidgets\', but components/AcmeWidget.tsx, the module its import names, does not export AcmeWidgets, so Astryx lists the component as "AcmeWidget" (its file name), and `astryx component AcmeWidget` prints `import {AcmeWidgets}`. Fix: set name: \'AcmeWidget\' in AcmeWidget.doc.mjs.',+ );++ const fixed = follow(dir, {+ write: {+ 'components/AcmeWidget.doc.mjs': namedDoc('AcmeWidget', 'AcmeWidget'),+ },+ });+ expect(await allOf(fixed)).toEqual([]);+ });++ it.each([+ [+ 'a re-export from another package',+ "export {AcmeWidgets} from '@acme/ui';\n",+ 'AcmeWidget.tsx re-exports AcmeWidgets from "@acme/ui", another package this check does not read.',+ ],+ [+ 'a .js specifier this read cannot follow',+ "export {AcmeWidgets} from './impl/widgets.js';\n",+ 'AcmeWidget.tsx re-exports AcmeWidgets from "./impl/widgets.js", which resolves to no file this check can read.',+ ],+ [+ 'an export * from another package',+ "export * from '@acme/ui';\n",+ 'AcmeWidget.tsx re-exports everything from "@acme/ui", another package this check does not read.',+ ],+ [+ 'a destructured export',+ 'const parts = {AcmeWidgets: () => null};\nexport const {AcmeWidgets} = parts;\n',+ 'AcmeWidget.tsx exports a destructured binding, whose names this check does not read.',+ ],+ [+ 'a TypeScript namespace export',+ 'export namespace AcmeWidgets {\n export const Root = () => null;\n}\n',+ 'AcmeWidget.tsx exports AcmeWidgets as a TypeScript namespace, which has a runtime value only when it holds one.',+ ],+ [+ 'an export assignment',+ 'const AcmeWidgets = () => null;\nexport = {AcmeWidgets};\n',+ 'AcmeWidget.tsx uses `export =`, whose names this check does not read.',+ ],+ ])(+ 'lists a doc name the code cannot judge as not checked, with no finding: %s',+ async (_label, source, reason) => {+ const dir = writeNamed({+ [MANIFEST]: manifest({components: './components'}),+ 'components/AcmeWidget.doc.mjs': namedDoc('AcmeWidget', 'AcmeWidgets'),+ 'components/AcmeWidget.tsx': source,+ });++ const {data} = await validateIntegration(undefined, {cwd: dir});+ expect(data.notes ?? []).toEqual([]);+ expect(data.docNames).toEqual({+ status: 'checked',+ findings: [],+ unchecked: [+ {file: 'components/AcmeWidget.doc.mjs', name: 'AcmeWidgets', reason},+ ],+ });+ // Counted as not compared, never as a failure, even under --strict.+ const checked = await integrationCheck({cwd: dir, strict: true});+ const propsNotCompared = checked.data.checks+ .map(check => check.response.data.propDrift?.unchecked?.length ?? 0)+ .reduce((a, b) => a + b, 0);+ expect(checked.data.unchecked).toBe(1 + propsNotCompared);+ expect(+ checked.data.failures.filter(+ failure => failure.code === 'doc_names_skipped',+ ),+ ).toEqual([]);+ },+ );++ it.each([+ [+ 'a source that exports both names',+ 'export function AcmeWidget() { return null; }\nexport const AcmeWidgets = AcmeWidget;\n',+ ],+ [+ 'an export import alias, a runtime value',+ 'namespace Impl {\n export const Widgets = () => null;\n}\nexport function AcmeWidget() { return null; }\nexport import AcmeWidgets = Impl.Widgets;\n',+ ],+ [+ 'an enum, a runtime value',+ 'export function AcmeWidget() { return null; }\nexport enum AcmeWidgets {\n Small,\n}\n',+ ],+ ])(+ 'checks a doc name the source exports, with nothing listed: %s',+ async (_label, source) => {+ const dir = writeNamed({+ [MANIFEST]: manifest({components: './components'}),+ 'components/AcmeWidget.doc.mjs': namedDoc('AcmeWidget', 'AcmeWidgets'),+ 'components/AcmeWidget.tsx': source,+ });++ const {data} = await validateIntegration(undefined, {cwd: dir});+ expect(data.issues).toEqual([]);+ expect(data.docNames).toEqual({+ status: 'checked',+ findings: [],+ unchecked: [],+ });+ },+ );++ it('prints the doc names it could not check', () => {+ const dir = writeNamed({+ [MANIFEST]: manifest({components: './components'}),+ 'components/AcmeWidget.doc.mjs': namedDoc('AcmeWidget', 'AcmeWidgets'),+ 'components/AcmeWidget.tsx': "export {AcmeWidgets} from '@acme/ui';\n",+ });++ const run = spawnSync(+ process.execPath,+ [CLI, 'doctor', 'integration', 'validate'],+ {cwd: dir, encoding: 'utf-8', timeout: 60_000},+ );+ expect(run.status, run.stderr).toBe(0);+ expect(run.stdout).toContain(+ '[info] Component names not checked: 1 doc(s) whose source exports this check cannot read:',+ );+ expect(run.stdout).toContain('components/AcmeWidget.doc.mjs');+ expect(run.stdout).toContain(+ 'AcmeWidget.tsx re-exports AcmeWidgets from "@acme/ui", another package this check does not read.',+ );+ });++ it('does not count a member a namespace exports as an export of the module', async () => {+ const dir = writeNamed({+ [MANIFEST]: manifest({components: './components'}),+ 'components/AcmeWidget.doc.mjs': namedDoc('AcmeWidget', 'AcmeWidgets'),+ 'components/AcmeWidget.tsx':+ 'namespace Impl {\n export const AcmeWidgets = () => null;\n}\nexport function AcmeWidget() { return null; }\n',+ });++ expect(only(await allOf(dir), 'doc_name_mismatch')).toContain(+ 'components/AcmeWidget.tsx, the module its import names, does not export AcmeWidgets',+ );+ });++ it('follows a local re-export that does not export the documented name', async () => {+ const dir = writeNamed({+ [MANIFEST]: manifest({components: './components'}),+ 'components/AcmeWidget.doc.mjs': namedDoc('AcmeWidget', 'AcmeWidgets'),+ 'components/AcmeWidget.tsx': "export * from './impl';\n",+ 'components/impl.tsx': componentSource('AcmeWidget'),+ });++ expect(only(await allOf(dir), 'doc_name_mismatch')).toContain(+ "sets name: 'AcmeWidgets'",+ );+ });++ it('proposes the export a kebab-case source holds, never its file name', async () => {+ const dir = writeNamed({+ [MANIFEST]: manifest({components: './components'}),+ 'components/acme-widget.doc.mjs': namedDoc('acme-widget', 'AcmeWidgets'),+ 'components/acme-widget.tsx': componentSource('AcmeWidget'),+ });++ const message = only(await allOf(dir), 'doc_name_mismatch');+ expect(message).toBe(+ 'Component doc "acme-widget.doc.mjs" sets name: \'AcmeWidgets\', but components/acme-widget.tsx, the module its import names, does not export AcmeWidgets, so Astryx lists the component as "acme-widget" (its file name), and `astryx component acme-widget` prints `import {AcmeWidgets}`. Fix: set name: \'AcmeWidget\' in acme-widget.doc.mjs, the component components/acme-widget.tsx exports.',+ );+ const fixed = follow(dir, {+ write: {+ 'components/acme-widget.doc.mjs': namedDoc('acme-widget', 'AcmeWidget'),+ },+ });+ expect(await allOf(fixed)).toEqual([]);+ });++ it('names no single export when a source exports several components', async () => {+ const dir = writeNamed({+ [MANIFEST]: manifest({components: './components'}),+ 'components/acme-widget.doc.mjs': namedDoc('acme-widget', 'AcmeWidgets'),+ 'components/acme-widget.tsx':+ 'export function AcmeWidget() { return null; }\nexport function AcmeGizmo() { return null; }\n',+ });++ expect(only(await allOf(dir), 'doc_name_mismatch')).toContain(+ 'Fix: set name in acme-widget.doc.mjs to the component components/acme-widget.tsx exports (AcmeGizmo, AcmeWidget).',+ );+ });++ it('judges the module the printed import names: an entry that publishes a default under the doc name passes', async () => {+ const dir = writePackage(+ {+ [MANIFEST]: manifest({components: './components'}),+ 'components/acme-widget.doc.mjs': componentDoc('AcmeWidget'),+ 'components/acme-widget.tsx':+ 'export default function AcmeWidget() { return null; }\n',+ 'index.ts':+ "export {default as AcmeWidget} from './components/acme-widget';\n",+ },+ {name: '@acme/kit', version: '1.0.0', exports: {'.': './index.ts'}},+ );++ const {data} = await validateIntegration(undefined, {cwd: dir});+ expect(data.issues).toEqual([]);+ expect(data.docNames?.unchecked).toEqual([]);+ });++ it('flags a name the printed entry provably does not publish', async () => {+ const dir = writePackage(+ {+ [MANIFEST]: manifest({components: './components'}),+ 'components/acme-widget.doc.mjs': componentDoc('AcmeWidget'),+ 'components/acme-widget.tsx':+ 'export default function AcmeWidget() { return null; }\n',+ 'index.ts':+ "export {default as AcmeGadget} from './components/acme-widget';\n",+ },+ {name: '@acme/kit', version: '1.0.0', exports: {'.': './index.ts'}},+ );++ expect(only(await allOf(dir), 'doc_name_mismatch')).toContain(+ 'but index.ts, the module its import names, does not export AcmeWidget',+ );+ });++ it('flags a name a default-only printed module cannot give, with a fix that parses and clears it', async () => {+ const dir = writeNamed({+ [MANIFEST]: manifest({components: './components'}),+ 'components/acme-widget.doc.mjs': namedDoc('acme-widget', 'AcmeWidget'),+ 'components/acme-widget.tsx':+ 'export default function AcmeWidget() { return null; }\n',+ });++ const message = only(await allOf(dir), 'doc_name_mismatch');+ expect(message).toContain(+ 'but components/acme-widget.tsx, the module its import names, does not export AcmeWidget',+ );+ expect(message).toContain(+ "Fix: add `export {AcmeWidget};` to components/acme-widget.tsx, so it exports AcmeWidget by name as well, or set the doc's import to the module that publishes it as AcmeWidget.",+ );++ const source =+ 'export default function AcmeWidget() { return null; }\nexport {AcmeWidget};\n';+ expect(() =>+ parse(source, {sourceType: 'module', plugins: ['typescript', 'jsx']}),+ ).not.toThrow();+ const fixed = follow(dir, {write: {'components/acme-widget.tsx': source}});+ expect(await allOf(fixed)).toEqual([]);+ });++ it('proposes a named binding for an anonymous default, which parses and clears it', async () => {+ const dir = writeNamed({+ [MANIFEST]: manifest({components: './components'}),+ 'components/acme-widget.doc.mjs': namedDoc('acme-widget', 'AcmeWidget'),+ 'components/acme-widget.tsx': 'export default () => null;\n',+ });++ expect(only(await allOf(dir), 'doc_name_mismatch')).toContain(+ 'Fix: bind the default to AcmeWidget in components/acme-widget.tsx and export it by name too (`const AcmeWidget = …; export default AcmeWidget; export {AcmeWidget};`)',+ );+ const source =+ 'const AcmeWidget = () => null;\nexport default AcmeWidget;\nexport {AcmeWidget};\n';+ expect(() =>+ parse(source, {sourceType: 'module', plugins: ['typescript', 'jsx']}),+ ).not.toThrow();+ const fixed = follow(dir, {write: {'components/acme-widget.tsx': source}});+ expect(await allOf(fixed)).toEqual([]);+ });++ it('lists a default-only source as not checked when no printed import can be resolved', async () => {const dir = writePackage({[MANIFEST]: manifest({components: './components'}),'components/acme-widget.doc.mjs': componentDoc('AcmeWidget'),+ 'components/acme-widget.tsx':+ 'export default function AcmeWidget() { return null; }\n',+ });+ // No package to resolve an import in: the same-stem source is read.+ const {report} = await componentDocNamesCheck({+ name: '@acme/kit',+ components: path.join(dir, 'components'),+ __spec: '@acme/kit',+ __manifestFile: path.join(dir, MANIFEST),+ });++ expect(report.unchecked).toEqual([+ {+ file: 'acme-widget.doc.mjs',+ name: 'AcmeWidget',+ reason:+ 'acme-widget.tsx exports a default, which the package entry may publish under any name.',+ },+ ]);+ });++ it('lists a name whose printed import resolves to no file as not checked', async () => {+ const dir = writePackage({+ [MANIFEST]: manifest({components: './components'}),+ 'components/acme-widget.doc.mjs': componentDoc('AcmeGadget'),'components/acme-widget.tsx': componentSource('AcmeWidget'),});- expect(await issuesOf(dir)).toEqual([]);+ const {data} = await validateIntegration(undefined, {cwd: dir});+ expect(data.issues).toEqual([]);+ expect(data.docNames?.unchecked.map(entry => entry.file)).toEqual([+ 'components/acme-widget.doc.mjs',+ ]);+ });++ it('accepts a kebab-case file whose doc names the export it holds', async () => {+ const dir = writeNamed({+ [MANIFEST]: manifest({components: './components'}),+ 'components/acme-widget.doc.mjs': namedDoc('acme-widget', 'AcmeWidget'),+ 'components/acme-widget.tsx': componentSource('AcmeWidget'),+ });++ expect(await allOf(dir)).toEqual([]);});it('leaves a doc topic named differently from its file alone: the code does not contradict it', async () => {- const dir = writePackage({+ const dir = writeNamed({[MANIFEST]: manifest({docs: './docs'}),'docs/deploying.doc.mjs': topic('deploy'),});- expect(await issuesOf(dir)).toEqual([]);+ expect(await allOf(dir)).toEqual([]);});it('leaves a template name alone: it is the display title', async () => {- const dir = writePackage({+ const dir = writeNamed({[MANIFEST]: manifest({templates: './templates'}),'templates/account-card.doc.mjs': templateDoc('Account card'),'templates/account-card.tsx': templateSource,});- expect(await issuesOf(dir)).toEqual([]);+ expect(await allOf(dir)).toEqual([]);+ });+});++describe('block component names', () => {+ /**+ * A package whose own name resolves, through its exports, to an entry that+ * publishes the names the templates import from it.+ * @param {Record<string, string>} files+ */+ const writeKit = files =>+ writePackage(+ {+ 'index.tsx':+ 'export function Panel() { return null; }\nexport const UI = {};\nexport const Lib = {};\nexport function pick() { return null; }\n',+ ...files,+ },+ {name: '@acme/kit', version: '1.0.0', exports: {'.': './index.tsx'}},+ );+ /** @param {string} extra */+ const block = extra =>+ `export default {type: 'block', name: 'Account card', displayName: 'Account card', aspectRatio: 1,${extra}};\n`;++ it('flags exampleFor and componentsUsed naming no component', async () => {+ const dir = writeKit({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/account-card.doc.mjs': block(+ " exampleFor: 'AcmeGizmo', componentsUsed: ['AcmeGizmo']",+ ),+ 'templates/account-card.tsx': templateSource,+ });++ const issues = await allOf(dir);+ expect(issues.map(issue => issue.code)).toEqual([+ 'unknown_block_component',+ 'unknown_block_component',+ ]);+ expect(issues[0].message).toBe(+ 'Template "account-card" names "AcmeGizmo" in exampleFor, but neither this package nor Core has a component by that name and the template does not import it, so `astryx template --list` and the block\'s search keywords give a component name no one can look up. Fix: use the component\'s exact name, or remove "AcmeGizmo" from exampleFor.',+ );+ });++ it("accepts every doc astryx component resolves in Core, such as Chat and Layout, and the package's and imported names", async () => {+ const dir = writeKit({+ [MANIFEST]: manifest({+ components: './components',+ templates: './templates',+ }),+ 'components/AcmeWidget.doc.mjs': componentDoc('AcmeWidget'),+ 'components/AcmeWidget.tsx': componentSource('AcmeWidget'),+ 'templates/account-card.doc.mjs': block(+ " exampleFor: 'AcmeWidget', componentsUsed: ['Chat', 'Layout', 'Button', 'AcmeWidget', 'Helper']",+ ),+ 'templates/account-card.tsx':+ "import {Helper} from 'some-lib';\nexport default function A() {\n return <Helper />;\n}\n",+ });++ expect(await allOf(dir)).toEqual([]);+ });++ it('looks a name up in Core before giving up on a namespace import', async () => {+ const dir = writeKit({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/account-card.doc.mjs': block(+ " componentsUsed: ['Layout', 'Panel']",+ ),+ 'templates/account-card.tsx':+ "import * as stylex from '@stylexjs/stylex';\nimport * as UI from '@acme/kit';\nexport default function A() {\n return <UI.Panel />;\n}\n",+ });++ const {data} = await validateIntegration(undefined, {cwd: dir});+ expect(data.issues).toEqual([]);+ expect(data.blockComponents?.unchecked.map(entry => entry.name)).toEqual([+ 'Panel',+ ]);+ });++ it('lists a name the template may render through a namespace import as not checked', async () => {+ const dir = writeKit({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/account-card.doc.mjs': block(" componentsUsed: ['Panel']"),+ 'templates/account-card.tsx':+ "import * as UI from '@acme/kit';\nexport default function A() {\n return <UI.Panel />;\n}\n",+ });++ const {data} = await validateIntegration(undefined, {cwd: dir});+ expect(data.issues).toEqual([]);+ expect(data.blockComponents?.unchecked).toEqual([+ {+ file: 'templates/account-card.doc.mjs',+ name: 'Panel',+ reason:+ 'account-card.tsx imports "@acme/kit" as a namespace (UI), whose component names this check does not read.',+ },+ ]);+ });++ it('prints the block names it could not judge', () => {+ const dir = writeKit({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/account-card.doc.mjs': block(" componentsUsed: ['Panel']"),+ 'templates/account-card.tsx':+ "import * as UI from '@acme/kit';\nexport default function A() {\n return <UI.Panel />;\n}\n",+ });++ const run = spawnSync(+ process.execPath,+ [CLI, 'doctor', 'integration', 'validate'],+ {cwd: dir, encoding: 'utf-8', timeout: 60_000},+ );+ expect(run.status, run.stderr).toBe(0);+ expect(run.stdout).toContain(+ '[info] Block component names not checked: 1 name(s) this check could not judge:',+ );+ });++ it('follows a local helper the template renders through', async () => {+ const dir = writeKit({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/account-card/account-card.doc.mjs': block(+ " componentsUsed: ['Panel', 'AcmeGizmo']",+ ),+ 'templates/account-card/account-card.tsx':+ "import {Body} from './parts/Body';\nexport default function A() {\n return <Body />;\n}\n",+ 'templates/account-card/parts/Body.tsx':+ "import {Panel} from '@acme/kit';\nexport function Body() {\n return <Panel />;\n}\n",+ });++ const {data} = await validateIntegration(undefined, {cwd: dir});+ expect((data.notes ?? []).map(note => note.message)).toEqual([+ expect.stringContaining('names "AcmeGizmo" in componentsUsed'),+ ]);+ expect(data.blockComponents?.unchecked).toEqual([]);+ });++ it.each([+ ['a named re-export', "export {Body} from './Body';\n"],+ ['an export *', "export * from './Body';\n"],+ ])(+ 'follows a helper barrel with %s like an import',+ async (_label, barrel) => {+ const dir = writeKit({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/account-card/account-card.doc.mjs': block(+ " componentsUsed: ['Panel', 'AcmeGizmo']",+ ),+ 'templates/account-card/account-card.tsx':+ "import {Body} from './parts';\nexport default function A() {\n return <Body />;\n}\n",+ 'templates/account-card/parts/index.ts': barrel,+ 'templates/account-card/parts/Body.tsx':+ "import {Panel} from '@acme/kit';\nexport function Body() {\n return <Panel />;\n}\n",+ });++ const {data} = await validateIntegration(undefined, {cwd: dir});+ expect((data.notes ?? []).map(note => note.message)).toEqual([+ expect.stringContaining('names "AcmeGizmo" in componentsUsed'),+ ]);+ expect(data.blockComponents?.unchecked).toEqual([]);+ },+ );++ it.each([+ [+ 'a default import used as a namespace',+ "import UI from '@acme/kit';\nexport default function A() {\n return <UI.Panel />;\n}\n",+ 'account-card.tsx imports the default of "@acme/kit" as UI, which may be any component.',+ ],+ [+ 'members destructured off a named import',+ "import {UI} from '@acme/kit';\nconst {Panel} = UI;\nexport default function A() {\n return <Panel />;\n}\n",+ 'account-card.tsx reads UI (imported from "@acme/kit") into another name, which this check does not follow.',+ ],+ [+ 'a member read off a named import',+ "import {UI} from '@acme/kit';\nconst Panel = UI.Panel;\nexport default function A() {\n return <Panel />;\n}\n",+ 'account-card.tsx reads members of UI (imported from "@acme/kit"), whose names this check does not read.',+ ],+ [+ 'createElement with a member',+ "import {createElement} from 'react';\nimport {UI} from '@acme/kit';\nexport default function A() {\n return createElement(UI.Panel);\n}\n",+ 'account-card.tsx reads members of UI (imported from "@acme/kit"), whose names this check does not read.',+ ],+ [+ 'a default import under another name',+ "import Panel from '@acme/kit/AcmePanel';\nexport default function A() {\n return <Panel />;\n}\n",+ 'account-card.tsx imports the default of "@acme/kit/AcmePanel" as Panel, which may be any component.',+ ],+ [+ 'an alias of an imported binding',+ "import {Lib} from '@acme/kit';\nconst UI = Lib;\nexport default function A() {\n return <UI.AcmePanel />;\n}\n",+ 'account-card.tsx reads Lib (imported from "@acme/kit") into another name, which this check does not follow.',+ ],+ [+ 'an optional member read',+ "import {UI} from '@acme/kit';\nconst Panel = UI?.AcmePanel;\nexport default function A() {\n return <Panel />;\n}\n",+ 'account-card.tsx reads members of UI (imported from "@acme/kit"), whose names this check does not read.',+ ],+ [+ 'a component held in a variable',+ "import {pick} from '@acme/kit';\nconst Panel = pick('panel');\nexport default function A() {\n return <Panel />;\n}\n",+ 'account-card.tsx renders Panel, a value this check does not trace to an import.',+ ],+ [+ 'require()',+ "const {Panel} = require('@acme/kit');\nexport default function A() {\n return <Panel />;\n}\n",+ 'account-card.tsx loads "@acme/kit" with require(), whose component names this check does not read.',+ ],+ [+ 'a lazy dynamic import',+ "import {lazy} from 'react';\nconst Panel = lazy(() => import('@acme/kit/Panel'));\nexport default function A() {\n return <Panel />;\n}\n",+ 'account-card.tsx loads "@acme/kit/Panel" with a dynamic import(), whose component names this check does not read.',+ ],+ ])(+ 'lists a name the template may render through %s as not checked',+ async (_label, source, reason) => {+ const dir = writeKit({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/account-card.doc.mjs': block(+ " componentsUsed: ['AcmePanel']",+ ),+ 'templates/account-card.tsx': source,+ });++ const {data} = await validateIntegration(undefined, {cwd: dir});+ expect(data.issues).toEqual([]);+ expect(data.blockComponents?.unchecked).toEqual([+ {file: 'templates/account-card.doc.mjs', name: 'AcmePanel', reason},+ ]);+ },+ );++ it('leaves names to unchecked when the template imports another package, which may render them', async () => {+ const dir = writeKit({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/account-card.doc.mjs': block(+ " componentsUsed: ['AcmeCardGrid', 'AcmeCard']",+ ),+ 'templates/account-card.tsx':+ "import {AcmeCardGrid} from '@acme/cards';\nexport default function A() {\n return <AcmeCardGrid />;\n}\n",+ });++ const {data} = await validateIntegration(undefined, {cwd: dir});+ expect(data.issues).toEqual([]);+ expect(data.blockComponents?.unchecked).toEqual([+ {+ file: 'templates/account-card.doc.mjs',+ name: 'AcmeCard',+ reason:+ 'account-card.tsx imports from "@acme/cards", another package whose components may render ones this check does not see.',+ },+ ]);+ });++ it('leaves names to unchecked when the template imports a default by name', async () => {+ const dir = writeKit({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/account-card.doc.mjs': block(" componentsUsed: ['AcmePanel']"),+ 'templates/account-card.tsx':+ "import {default as Panel} from '@acme/kit/AcmePanel';\nexport default function A() {\n return <Panel />;\n}\n",+ });++ const {data} = await validateIntegration(undefined, {cwd: dir});+ expect(data.issues).toEqual([]);+ expect(data.blockComponents?.unchecked).toEqual([+ {+ file: 'templates/account-card.doc.mjs',+ name: 'AcmePanel',+ reason:+ 'account-card.tsx imports the default of "@acme/kit/AcmePanel" as Panel, which may be any component.',+ },+ ]);+ });++ it('leaves names to unchecked when a helper re-exports a default by name', async () => {+ const dir = writeKit({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/account-card/account-card.doc.mjs': block(+ " componentsUsed: ['AcmePanel']",+ ),+ 'templates/account-card/account-card.tsx':+ "import {Body} from './parts';\nexport default function A() {\n return <Body />;\n}\n",+ 'templates/account-card/parts/index.ts':+ "export {default as Body} from './Body';\n",+ 'templates/account-card/parts/Body.tsx':+ 'export default function Body() {\n return null;\n}\n',+ });++ const {data} = await validateIntegration(undefined, {cwd: dir});+ expect(data.issues).toEqual([]);+ expect(data.blockComponents?.unchecked).toEqual([+ {+ file: 'templates/account-card/account-card.doc.mjs',+ name: 'AcmePanel',+ reason:+ 'parts/index.ts re-exports the default of "./Body" as Body, which may be any component.',+ },+ ]);+ });++ it('still flags a name when the template imports only from Core, React, StyleX and itself', async () => {+ const dir = writeKit({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/account-card.doc.mjs': block(+ " componentsUsed: ['Layout', 'AcmeGizmo']",+ ),+ 'templates/account-card.tsx':+ "import {useState} from 'react';\nimport * as stylex from '@stylexjs/stylex';\nimport {Layout} from '@astryxdesign/core';\nimport type {ReactNode} from 'react';\nimport type {Gizmo} from '@acme/types';\nexport default function A() {\n useState();\n return <Layout />;\n}\n",+ });++ const {data} = await validateIntegration(undefined, {cwd: dir});+ expect((data.notes ?? []).map(note => note.message)).toEqual([+ expect.stringContaining('names "AcmeGizmo" in componentsUsed'),+ ]);+ });++ it("follows an import of the package's own name to its source, and lists what that source may render", async () => {+ const dir = writeKit({+ [MANIFEST]: manifest({templates: './templates'}),+ 'index.tsx': "export {AcmeCardGrid} from './src/AcmeCardGrid';\n",+ 'src/AcmeCardGrid.tsx':+ "import {AcmeCard} from '@acme/cards';\nexport function AcmeCardGrid() {\n return <AcmeCard />;\n}\n",+ 'templates/account-card.doc.mjs': block(+ " componentsUsed: ['AcmeCardGrid', 'AcmeCardRow']",+ ),+ 'templates/account-card.tsx':+ "import {AcmeCardGrid} from '@acme/kit';\nexport default function A() {\n return <AcmeCardGrid />;\n}\n",+ });++ const {data} = await validateIntegration(undefined, {cwd: dir});+ expect(data.notes ?? []).toEqual([]);+ expect(data.blockComponents?.unchecked).toEqual([+ {+ file: 'templates/account-card.doc.mjs',+ name: 'AcmeCardRow',+ reason:+ '../src/AcmeCardGrid.tsx imports from "@acme/cards", another package whose components may render ones this check does not see.',+ },+ ]);+ });++ it("still flags a name when the package's own source it follows imports only what this check sees", async () => {+ const dir = writeKit({+ [MANIFEST]: manifest({templates: './templates'}),+ 'index.tsx': "export {AcmeCardGrid} from './src/AcmeCardGrid';\n",+ 'src/AcmeCardGrid.tsx':+ "import {Layout} from '@astryxdesign/core';\nexport function AcmeCardGrid() {\n return <Layout />;\n}\n",+ 'templates/account-card.doc.mjs': block(+ " componentsUsed: ['AcmeCardGrid', 'AcmeGizmo']",+ ),+ 'templates/account-card.tsx':+ "import {AcmeCardGrid} from '@acme/kit';\nexport default function A() {\n return <AcmeCardGrid />;\n}\n",+ });++ const {data} = await validateIntegration(undefined, {cwd: dir});+ expect((data.notes ?? []).map(note => note.message)).toEqual([+ expect.stringContaining('names "AcmeGizmo" in componentsUsed'),+ ]);+ expect(data.blockComponents?.unchecked).toEqual([]);+ });++ it("lists names behind an import of the package's own name that resolves to no source", async () => {+ const dir = writePackage({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/account-card.doc.mjs': block(" componentsUsed: ['AcmeGizmo']"),+ 'templates/account-card.tsx':+ "import {AcmeCardGrid} from '@acme/kit/grid';\nexport default function A() {\n return <AcmeCardGrid />;\n}\n",+ });++ const {data} = await validateIntegration(undefined, {cwd: dir});+ expect(data.notes ?? []).toEqual([]);+ expect(data.blockComponents?.unchecked).toEqual([+ {+ file: 'templates/account-card.doc.mjs',+ name: 'AcmeGizmo',+ reason:+ 'account-card.tsx imports "@acme/kit/grid", this package\'s own name, which resolves to no source this check can read.',+ },+ ]);+ });++ it("skips a renderless library's default import, as its namespace import", async () => {+ const dir = writeKit({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/account-card.doc.mjs': block(" componentsUsed: ['AcmeGizmo']"),+ 'templates/account-card.tsx':+ "import React from 'react';\nexport default function A() {\n return <div />;\n}\n",+ });++ const {data} = await validateIntegration(undefined, {cwd: dir});+ expect((data.notes ?? []).map(note => note.message)).toEqual([+ expect.stringContaining('names "AcmeGizmo" in componentsUsed'),+ ]);+ expect(data.blockComponents?.unchecked).toEqual([]);+ });++ it('lists a name behind a local helper it cannot read as not checked', async () => {+ const dir = writeKit({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/account-card.doc.mjs': block(" componentsUsed: ['Panel']"),+ 'templates/account-card.tsx':+ "import {Body} from './parts/missing';\nexport default function A() {\n return <Body />;\n}\n",+ });++ const {data} = await validateIntegration(undefined, {cwd: dir});+ expect(data.issues).toEqual([]);+ expect(data.blockComponents?.unchecked.map(entry => entry.name)).toEqual([+ 'Panel',+ ]);+ });++ it('lists names only Core could resolve as not checked when Core is not installed', async () => {+ const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-no-core-'));+ try {+ fs.writeFileSync(+ path.join(outside, 'package.json'),+ JSON.stringify({name: '@acme/kit', version: '1.0.0'}),+ );+ fs.writeFileSync(+ path.join(outside, MANIFEST),+ manifest({templates: './templates'}),+ );+ fs.mkdirSync(path.join(outside, 'templates'));+ fs.writeFileSync(+ path.join(outside, 'templates', 'account-card.doc.mjs'),+ block(" componentsUsed: ['Chat', 'Layout']"),+ );+ fs.writeFileSync(+ path.join(outside, 'templates', 'account-card.tsx'),+ templateSource,+ );++ const {data} = await validateIntegration(undefined, {cwd: outside});+ expect(data.notes ?? []).toEqual([]);+ const reason =+ 'Core is not installed, so its component names cannot be checked.';+ expect(data.blockComponents).toEqual({+ status: 'checked',+ findings: [],+ unchecked: [+ {file: 'templates/account-card.doc.mjs', name: 'Chat', reason},+ {file: 'templates/account-card.doc.mjs', name: 'Layout', reason},+ ],+ });+ } finally {+ fs.rmSync(outside, {recursive: true, force: true});+ }});});@@ -825,3 +1619,54 @@ describe('layout findings 0.7.2 did not fail on', () => {expect(run.stdout).toContain('Summary: 0 errors, 0 warnings');});});++describe('name findings listed until the next minor release', () => {+ /** @param {string} extra */+ const block = extra =>+ `export default {type: 'block', name: 'Account card', displayName: 'Account card', aspectRatio: 1,${extra}};\n`;+ const docLayout = () =>+ writeNamed({+ [MANIFEST]: manifest({components: './components'}),+ 'components/AcmeWidget.doc.mjs': namedDoc('AcmeWidget', 'AcmeWidgets'),+ 'components/AcmeWidget.tsx': componentSource('AcmeWidget'),+ });+ const blockLayout = () =>+ writePackage({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/account-card.doc.mjs': block(" componentsUsed: ['AcmeGizmo']"),+ 'templates/account-card.tsx': templateSource,+ });++ it.each([+ ['doc_name_mismatch', docLayout, 'docNames'],+ ['unknown_block_component', blockLayout, 'blockComponents'],+ ])(+ 'lists %s as a note beside the issues, and integration check --strict passes',+ async (code, make, report) => {+ const dir = make();+ const {data} = await validateIntegration(undefined, {cwd: dir});+ expect(data.issues).toEqual([]);+ expect(/** @type {any} */ (data)[report].findings).toEqual([]);+ expect(data.notes?.map(note => note.code)).toEqual([code]);+ expect(data.notes?.[0].message).toContain('Fix: ');++ const result = await integrationCheck({cwd: dir, strict: true});+ expect(result.data.failures).toEqual([]);+ expect(result.data.failed).toBe(false);+ },+ );++ it('prints the name notes and counts none', () => {+ const dir = blockLayout();+ const run = spawnSync(+ process.execPath,+ [CLI, 'doctor', 'integration', 'validate'],+ {cwd: dir, encoding: 'utf-8', timeout: 60_000},+ );+ expect(run.status, run.stderr).toBe(0);+ expect(run.stdout).toContain(+ 'note (unknown_block_component): Template "account-card" names "AcmeGizmo" in componentsUsed',+ );+ expect(run.stdout).toContain('Summary: 0 errors, 0 warnings');+ });+});diff --git a/packages/cli/api/integration/validate-integration.mjs b/packages/cli/api/integration/validate-integration.mjsindex 3e061c0a74..e931abc12d 100644--- a/packages/cli/api/integration/validate-integration.mjs+++ b/packages/cli/api/integration/validate-integration.mjs@@ -57,6 +57,8 @@ import {// The on-disk contribution validators live in foundation: Project and// integration-warnings need them too, and foundation must not depend on api.import {+ blockComponentsCheck,+ componentDocNamesCheck,INVALID_CLI_COMMAND,isListedIssue,issueListed as listed,@@ -495,7 +497,9 @@ export async function validateLocalIntegration(cwd = process.cwd()) {// A package without one is still checked, under a placeholder name.const fields = packageJsonFieldIssues(pkg, pkgJsonPath);const name =- typeof pkg.name === 'string' && pkg.name !== '' ? pkg.name : '(local package)';+ typeof pkg.name === 'string' && pkg.name !== ''+ ? pkg.name+ : '(local package)';const result = await validateAtPackageDir(packageDir,{name, version: pkg.version},@@ -665,10 +669,20 @@ export async function validateIntegration(pkg, options = {}) {const docTypes = integration? await integrationDocTypes(integration, cwd): undefined;- // Notes fail nothing: a malformed `cliCommand`, and the layout findings- // added after the last minor release, each with its fix in the message,- // which may not fail `--strict` until the next (architecture:cli-surface- // INV35).+ // The component names docs and blocks give: those that cannot be judged+ // are listed in their reports, and those judged wrong are notes.+ const names = integration+ ? [+ await componentDocNamesCheck(integration),+ await blockComponentsCheck(integration),+ ]+ : undefined;+ const docNames = names?.[0].report;+ const blockComponents = names?.[1].report;+ // Notes fail nothing: a malformed `cliCommand`, and the findings added+ // after the last minor release, each with its fix in the message, which+ // may not fail `--strict` until the next (architecture:cli-surface INV35):+ // the layout findings and the component names judged wrong.const notes = result.found? [...(result.notes ?? []),@@ -676,6 +690,7 @@ export async function validateIntegration(pkg, options = {}) {code: issue.code,message: issue.message,})),+ ...(names ?? []).flatMap(each => each.notes),]: [];return {@@ -699,6 +714,8 @@ export async function validateIntegration(pkg, options = {}) {: result.issues,...(notes.length > 0 ? {notes} : {}),...(docTypes ? {docTypes} : {}),+ ...(docNames ? {docNames} : {}),+ ...(blockComponents ? {blockComponents} : {}),},};}diff --git a/packages/cli/api/integration/validate-integration.type.mjs b/packages/cli/api/integration/validate-integration.type.mjsindex 6cac785ff7..6d83cdf223 100644--- a/packages/cli/api/integration/validate-integration.type.mjs+++ b/packages/cli/api/integration/validate-integration.type.mjs@@ -38,7 +38,7 @@* "healthy" — the two are otherwise byte-identical.* @typedef {object} ValidateIntegrationResponse* @property {'integration.validate'} type- * @property {{validated: boolean, name: string | null, version: string | null, issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[], notes?: Array<{code: string, message: string}>, docTypes?: DocTypesReport}} data+ * @property {{validated: boolean, name: string | null, version: string | null, issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[], notes?: Array<{code: string, message: string}>, docTypes?: DocTypesReport, docNames?: DocNamesReport, blockComponents?: BlockComponentsReport}} data* `notes`: information beside the issues that fails nothing, such as* `invalid_cli_command`, a `cliCommand` that was ignored as malformed, and* the package layout findings added after the last minor release, each with@@ -48,8 +48,9 @@* (`unreadable_file`), a package.json without `name` or `version`* (`invalid_package_json`), no provider ID (`no_provider_id`), and a doc* whose file name differs from its source only in letter case where the two- * still pair (`source_without_component_doc`); they become warnings in the- * next minor release+ * still pair (`source_without_component_doc`); and `doc_name_mismatch` and+ * `unknown_block_component` (see `docNames` and `blockComponents`); they+ * become warnings in the next minor release*//**@@ -63,4 +64,36 @@* components or docs root, which those readers skip) were not checked*/+/**+ * Each component doc whose `name` differs from the name it is listed under,+ * judged against its source. Present when the manifest loads. A name the+ * module its printed import names provably does not export is a+ * `doc_name_mismatch` note beside the issues, with its fix in the message+ * (it becomes a warning in the next minor release), so `findings` is always+ * empty; `unchecked` lists each doc whose source's+ * exports could not all be read (a re-export from another package, `export+ * =`, a destructured binding, a namespace): `file` (the doc, package-relative),+ * `name` (what the doc says), and `reason`.+ *+ * @typedef {{status: 'checked', findings: [], unchecked: Array<{file: string, name: string, reason: string}>}} DocNamesReport+ */++/**+ * Each component name a template gives in `exampleFor` or `componentsUsed`+ * that could not be judged. Present when the manifest loads. A name neither+ * the package nor Core has, and the template does not import, is an+ * `unknown_block_component` note beside the issues, with its fix in the+ * message (it becomes a warning in the next minor release), so `findings` is+ * always empty;+ * `unchecked` lists each name that cannot be judged: one the template may+ * reach through anything other than named imports and re-exports from+ * Core, React, StyleX, local helpers or the package's own entry (an import from another+ * package, a default or namespace import, an alias of or member read off an imported+ * binding, require(), a dynamic import(), a local module this check cannot+ * read), or, without Core installed, any name Core would have to resolve: `file` (the template doc, package-relative),+ * `name`, and `reason`.+ *+ * @typedef {{status: 'checked', findings: [], unchecked: Array<{file: string, name: string, reason: string}>}} BlockComponentsReport+ */+export {};diff --git a/packages/cli/api/integration/validateIntegration.doc.mjs b/packages/cli/api/integration/validateIntegration.doc.mjsindex 63d4df2ff3..7647cb6e26 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, 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; and `data.notes` when there are any: {code, message} information that fails nothing, such as `invalid_cli_command` for a `cliCommand` that was ignored as malformed, and the package layout findings added after the last minor release, each with its fix in the message: `duplicate_component_doc`, `symlinked_root`, `unreadable_file`, `invalid_package_json` (no `name` or `version`), `no_provider_id`, and `source_without_component_doc` for a doc whose file name differs from its source only in letter case where the two still pair; they become warnings in the next minor release. 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; and `data.notes` when there are any: {code, message} information that fails nothing, such as `invalid_cli_command` for a `cliCommand` that was ignored as malformed, and the package layout findings added after the last minor release, each with its fix in the message: `duplicate_component_doc`, `symlinked_root`, `unreadable_file`, `invalid_package_json` (no `name` or `version`), `no_provider_id`, and `source_without_component_doc` for a doc whose file name differs from its source only in letter case where the two still pair; and `doc_name_mismatch` and `unknown_block_component` (see `docNames` and `blockComponents`); they become warnings in the next minor release. 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. When the manifest loads, `data.docNames` lists the component doc names it could not judge: `status` (`checked`), `findings` (always empty; a doc name the module its import names provably does not export is a `doc_name_mismatch` note, with its fix in the message) and `unchecked` ({file, name, reason}: a doc whose `name` differs from the name it is listed under and whose source exports cannot all be read, such as a re-export from another package). When the manifest loads, `data.blockComponents` lists the component names templates give in `exampleFor` or `componentsUsed` that could not be judged: `status` (`checked`), `findings` (always empty; a name neither the package nor Core has, and the template does not import, is an `unknown_block_component` note, with its fix in the message) and `unchecked` ({file, name, reason}: a name the template may reach through anything other than named imports and re-exports from Core, React, StyleX, local helpers or the entry of the package itself, such as an import from another package, a default or namespace import, an alias of or member read off an imported binding, require() or a dynamic import(), or a local module that cannot be read, or any name Core would have to resolve when Core is not installed).',},],examples: [diff --git a/packages/cli/clients/cli/commands/doctor.mjs b/packages/cli/clients/cli/commands/doctor.mjsindex ed595802e5..27f6327a49 100644--- a/packages/cli/clients/cli/commands/doctor.mjs+++ b/packages/cli/clients/cli/commands/doctor.mjs@@ -179,6 +179,34 @@ function docTypesBlocks(report, failed) {return blocks;}+/**+ * The component doc names that could not be judged against their sources.+ * @param {import('../../../api/integration/validate-integration.type.mjs').DocNamesReport | undefined} report+ */+function docNamesBlocks(report) {+ if (!report || report.unchecked.length === 0) return [];+ return [+ text(+ `[info] Component names not checked: ${report.unchecked.length} doc(s) whose source exports this check cannot read:`,+ ),+ records(report.unchecked, {fields: ['file', 'name', 'reason']}),+ ];+}++/**+ * The block component names this check could not judge.+ * @param {import('../../../api/integration/validate-integration.type.mjs').BlockComponentsReport | undefined} report+ */+function blockComponentsBlocks(report) {+ if (!report || report.unchecked.length === 0) return [];+ return [+ text(+ `[info] Block component names not checked: ${report.unchecked.length} name(s) this check could not judge:`,+ ),+ records(report.unchecked, {fields: ['file', 'name', 'reason']}),+ ];+}+/*** @param {import('../../../api/integration/validate-integration.type.mjs').ValidateIntegrationResponse['data']} data*/@@ -204,6 +232,8 @@ function printIntegrationValidation(data) {`${warnings} warning${warnings === 1 ? '' : 's'}`,),...docTypesBlocks(data.docTypes, errors > 0),+ ...docNamesBlocks(data.docNames),+ ...blockComponentsBlocks(data.blockComponents),);}diff --git a/packages/cli/foundation/discovery/component-discovery.mjs b/packages/cli/foundation/discovery/component-discovery.mjsindex b099b5cafd..64752262e2 100644--- a/packages/cli/foundation/discovery/component-discovery.mjs+++ b/packages/cli/foundation/discovery/component-discovery.mjs@@ -1004,7 +1004,7 @@ function packageMain(packageDir) {* @param {Record<string, any> | null} doc* @returns {string | null | undefined}*/-function importedModule(integration, docPath, doc) {+export function importedModule(integration, docPath, doc) {const packageName = integration?.name;const packageDir = integration?.__packageDir;if (!packageName || !packageDir) return undefined;@@ -1034,6 +1034,42 @@ function importedModule(integration, docPath, doc) {).target;}+/**+ * The file an import of the package's own name resolves to, through its+ * package.json `exports` (or `main` when it has none): `@acme/kit` or+ * `@acme/kit/widget`. Null when the specifier names another package, or the+ * package publishes nothing at it.+ * @param {{name?: string, __packageDir?: string, __packageExports?: Record<string, unknown> | null}} integration+ * @param {string} specifier+ * @returns {string | null}+ */+export function ownPackageModule(integration, specifier) {+ const packageName = integration?.name;+ const packageDir = integration?.__packageDir;+ if (!packageName || !packageDir) return null;+ if (specifier !== packageName && !specifier.startsWith(`${packageName}/`)) {+ return null;+ }+ const exportsMap =+ integration.__packageExports === undefined+ ? readPackageExports(packageDir)+ : integration.__packageExports;+ if (specifier === packageName && exportsMap == null) {+ return packageMain(packageDir) ?? null;+ }+ const subpath =+ specifier === packageName+ ? '.'+ : `./${specifier.slice(packageName.length + 1)}`;+ return (+ inspectPackageExport(+ {name: packageName, exports: exportsMap ?? undefined},+ packageDir,+ subpath,+ ).target ?? null+ );+}+/*** Whether `file` sits in `folder` or below it.* @param {string} folderdiff --git a/packages/cli/foundation/discovery/module-exports.mjs b/packages/cli/foundation/discovery/module-exports.mjsindex b85cc9d387..a3d2dd1a21 100644--- a/packages/cli/foundation/discovery/module-exports.mjs+++ b/packages/cli/foundation/discovery/module-exports.mjs@@ -309,6 +309,259 @@ export function moduleExportSource(file, exportName, seen = new Set()) {return found;}+/**+ * The module's own top-level statements of one type: an `export` inside a+ * TypeScript namespace names a member of that namespace, not of the module.+ * @param {any} program+ * @param {string} type+ * @returns {any[]}+ */+function topLevel(program, type) {+ return program.body.filter((/** @type {any} */ node) => node.type === type);+}++/**+ * Every runtime name a module exports that this read can see (`default` for+ * a default export), or null when it cannot see them all: an `export *`, `export =`, CommonJS exports, or a+ * file that does not parse.+ * @param {string} file+ * @returns {string[] | null}+ */+export function moduleExportNames(file) {+ let text;+ let ast;+ try {+ if (!fs.statSync(file).isFile()) return null;+ text = moduleText(file);+ ast = parseModule(file);+ } catch {+ return null;+ }+ if (/\bmodule\.exports\b|\bexports\.[$\w]/u.test(text)) return null;+ if (+ topLevel(ast.program, 'TSExportAssignment').length > 0 ||+ topLevel(ast.program, 'ExportAllDeclaration').length > 0+ ) {+ return null;+ }+ /** @type {Set<string>} */+ const names = new Set();+ for (const node of topLevel(ast.program, 'TSImportEqualsDeclaration')) {+ if (!node.isExport) continue;+ // A type-only alias has no runtime value; any other might.+ if (node.importKind === 'type') continue;+ if (typeof node.id?.name !== 'string') return null;+ names.add(node.id.name);+ }+ for (const node of topLevel(ast.program, 'ExportNamedDeclaration')) {+ if (node.exportKind === 'type') continue;+ const declaration = node.declaration;+ if (declaration?.type === 'VariableDeclaration') {+ for (const item of declaration.declarations) {+ if (item.id?.type !== 'Identifier') return null;+ names.add(item.id.name);+ }+ } else if (declaration != null) {+ if (!runtimeDefault(declaration)) continue;+ if (typeof declaration.id?.name !== 'string') return null;+ names.add(declaration.id.name);+ }+ for (const specifier of node.specifiers ?? []) {+ if (specifier.exportKind === 'type') continue;+ const exported = specifier.exported?.name ?? specifier.exported?.value;+ if (typeof exported === 'string') names.add(exported);+ }+ }+ if (+ topLevel(ast.program, 'ExportDefaultDeclaration').some(+ (/** @type {any} */ node) => runtimeDefault(node.declaration),+ )+ ) {+ names.add('default');+ }+ return [...names].sort();+}++/**+ * @typedef {{verdict: 'exports'} | {verdict: 'lacks'} | {verdict: 'unknown', reason: string}} ExportVerdict+ */++/**+ * Whether a module exports `exportName` at runtime, read without executing+ * it: `exports` when a declaration or a followed re-export binds it, `lacks`+ * only when every export the module writes was read and none binds it, and+ * `unknown`, with the first reason, when some export could not be read: a+ * re-export from another package or from a specifier that resolves to no+ * file, a destructured binding, a namespace, an ambient or const enum+ * declaration, `export =`, CommonJS exports, or a file that does not parse.+ * @param {string} file+ * @param {string} exportName+ * @param {Set<string>} [seen]+ * @returns {ExportVerdict}+ */+export function moduleExportVerdict(file, exportName, seen = new Set()) {+ const identity = `${file}\0${exportName}`;+ // A cycle adds nothing a module's own exports have not already said.+ if (seen.has(identity)) return {verdict: 'lacks'};+ seen.add(identity);+ const shown = path.basename(file);+ let text;+ let ast;+ try {+ if (!fs.statSync(file).isFile()) {+ return {verdict: 'unknown', reason: `${shown} is not a file.`};+ }+ text = moduleText(file);+ ast = parseModule(file);+ } catch {+ return {+ verdict: 'unknown',+ reason: `${shown} could not be read or parsed.`,+ };+ }+ /** @type {string[]} */+ const unknown = [];+ if (/\bmodule\.exports\b|\bexports\.[$\w]/u.test(text)) {+ unknown.push(+ `${shown} uses CommonJS exports, whose names this check does not read.`,+ );+ }+ if (topLevel(ast.program, 'TSExportAssignment').length > 0) {+ unknown.push(`${shown} uses \`export =\`, whose names this check does not read.`);+ }+ /**+ * Follow a re-export of `imported` from `specifier`.+ * @param {string} specifier+ * @param {string} imported+ * @param {string} what how the reason names what is re-exported+ * @returns {boolean} true when it proves the export+ */+ const follow = (specifier, imported, what) => {+ if (!specifier.startsWith('.')) {+ unknown.push(+ `${shown} re-exports ${what} from "${specifier}", another package this check does not read.`,+ );+ return false;+ }+ const target = resolveLocalModule(specifier, file);+ if (!target) {+ unknown.push(+ `${shown} re-exports ${what} from "${specifier}", which resolves to no file this check can read.`,+ );+ return false;+ }+ const inner = moduleExportVerdict(target, imported, seen);+ if (inner.verdict === 'exports') return true;+ if (inner.verdict === 'unknown') unknown.push(inner.reason);+ return false;+ };+ // `export import Name = Some.Path;` binds a runtime value unless it is+ // type-only.+ for (const node of topLevel(ast.program, 'TSImportEqualsDeclaration')) {+ if (!node.isExport || node.id?.name !== exportName) continue;+ if (node.importKind === 'type') {+ unknown.push(+ `${shown} exports ${exportName} with \`export import type\`, which has no runtime value this check can see.`,+ );+ } else {+ return {verdict: 'exports'};+ }+ }+ for (const node of topLevel(ast.program, 'ExportNamedDeclaration')) {+ if (node.exportKind === 'type') continue;+ const declaration = node.declaration;+ if (declaration?.type === 'VariableDeclaration') {+ for (const item of declaration.declarations) {+ if (item.id?.type !== 'Identifier') {+ unknown.push(+ `${shown} exports a destructured binding, whose names this check does not read.`,+ );+ } else if (item.id.name === exportName) {+ if (declaration.declare === true) {+ unknown.push(+ `${shown} declares ${exportName} with \`declare\`, which has no runtime value this check can see.`,+ );+ } else {+ return {verdict: 'exports'};+ }+ }+ }+ } else if (declaration != null && declaration.id?.name === exportName) {+ if (+ ['TSInterfaceDeclaration', 'TSTypeAliasDeclaration'].includes(+ declaration.type,+ )+ ) {+ // A type only: no runtime export.+ } else if (declaration.type === 'TSModuleDeclaration') {+ unknown.push(+ `${shown} exports ${exportName} as a TypeScript namespace, which has a runtime value only when it holds one.`,+ );+ } else if (declaration.declare === true || declaration.const === true) {+ unknown.push(+ `${shown} declares ${exportName} as an ambient or const declaration, which has no runtime value this check can see.`,+ );+ } else if (runtimeDefault(declaration)) {+ return {verdict: 'exports'};+ }+ }+ for (const specifier of node.specifiers ?? []) {+ if (specifier.exportKind === 'type') continue;+ const exported = specifier.exported?.name ?? specifier.exported?.value;+ if (exported !== exportName) continue;+ if (!node.source || specifier.type === 'ExportNamespaceSpecifier') {+ return {verdict: 'exports'};+ }+ if (specifier.type !== 'ExportSpecifier') {+ unknown.push(`${shown} re-exports ${exportName} in a form this check does not read.`);+ continue;+ }+ const imported =+ specifier.local?.name ?? specifier.local?.value ?? exportName;+ if (follow(String(node.source.value), imported, exportName)) {+ return {verdict: 'exports'};+ }+ }+ }+ if (exportName === 'default') {+ const defaults = topLevel(ast.program, 'ExportDefaultDeclaration');+ if (+ defaults.some((/** @type {any} */ node) =>+ runtimeDefault(node.declaration),+ )+ ) {+ return {verdict: 'exports'};+ }+ }+ for (const node of topLevel(ast.program, 'ExportAllDeclaration')) {+ if (node.exportKind === 'type') continue;+ const exported = node.exported?.name ?? node.exported?.value;+ if (exported != null) {+ if (exported === exportName) return {verdict: 'exports'};+ continue;+ }+ // `export *` never re-exports a default.+ if (exportName === 'default') continue;+ if (follow(String(node.source?.value ?? ''), exportName, 'everything')) {+ return {verdict: 'exports'};+ }+ }+ return unknown.length > 0+ ? {verdict: 'unknown', reason: unknown[0]}+ : {verdict: 'lacks'};+}++/**+ * Whether a module provably does not export `exportName` at runtime: see+ * {@link moduleExportVerdict}.+ * @param {string} file+ * @param {string} exportName+ * @returns {boolean}+ */+export function moduleLacksExport(file, exportName) {+ return moduleExportVerdict(file, exportName).verdict === 'lacks';+}+/*** Marks an object {@link staticExportObject} returns (or one inside it) whose* source also has properties or spreads it could not read as literals. Notdiff --git a/packages/cli/foundation/integrations/validate-contributions.mjs b/packages/cli/foundation/integrations/validate-contributions.mjsindex e4af769991..ba98ee6fa8 100644--- a/packages/cli/foundation/integrations/validate-contributions.mjs+++ b/packages/cli/foundation/integrations/validate-contributions.mjs@@ -23,7 +23,9 @@import * as fs from 'node:fs';import * as path from 'node:path';+import {parse as parseModule} from '@babel/parser';import {isValidSemver} from '../env/semver.mjs';+import {findProjectCoreDir} from '../fs/paths.mjs';import {contributionFiles,findSourceOnlyCandidates,@@ -49,6 +51,12 @@ import {MANIFEST_BASENAMES} from './integrations.mjs';import {discoverIntegrationCodemods} from '../../assets/codemods/integration-discovery.mjs';import {discoverIntegrationTemplatesForOne} from '../discovery/template-adapter.mjs';import * as componentDiscovery from '../discovery/component-discovery.mjs';+import {loadComponentDoc} from '../discovery/component-loader.mjs';+import {+ moduleExportNames,+ moduleExportsName,+ moduleExportVerdict,+} from '../discovery/module-exports.mjs';import {discoverIntegrationDocs} from '../discovery/docs-discovery.mjs';import {discoverIntegrationThemes} from '../discovery/theme-discovery.mjs';@@ -397,6 +405,551 @@ async function checkTemplates(integration, issues) {checkTemplateSourcesWithoutDoc(integration, issues);}+/**+ * The component names each of a package's templates gives in `exampleFor`+ * and `componentsUsed`, judged against the components `astryx component`+ * finds: the package's own, and every doc it resolves in Core. A name the+ * template imports needs no doc of its own. A name neither has is an+ * `unknown_block_component` finding, since the template list and the+ * block's search keywords then give a name no one can look up. A name the+ * template may reach through anything the walk does not model, and, without+ * Core installed, a name the package does not have, cannot be judged and is+ * listed in `unchecked` instead.+ * @param {LoadedIntegration} integration+ * @returns {Promise<{findings: Array<{docPath: string, name: string, message: string}>, unchecked: Array<{docPath: string, name: string, reason: string}>}>}+ */+async function judgeBlockComponents(integration) {+ /** @type {Array<{docPath: string, name: string, message: string}>} */+ const findings = [];+ /** @type {Array<{docPath: string, name: string, reason: string}>} */+ const unchecked = [];+ const root = integration.templates;+ if (!root || rootProblem(root)) return {findings, unchecked};+ let templates;+ try {+ ({templates} = await discoverIntegrationTemplatesForOne(integration));+ } catch {+ return {findings, unchecked};+ }+ /** @type {Set<string>} */+ let own;+ try {+ own = new Set(+ componentDiscovery+ .discoverIntegrationComponents(integration)+ .map(record => record.name),+ );+ } catch {+ return {findings, unchecked};+ }+ // The Core installed beside the package, never the one the CLI carries:+ // a name is judged against the Core the package's users install.+ const coreDir = findProjectCoreDir(integration.__packageDir ?? root);+ /** @type {Map<string, boolean>} */+ const inCore = new Map();+ /** @param {string} name */+ const coreHas = name => {+ if (!coreDir) return false;+ if (!inCore.has(name)) {+ let found;+ try {+ found = componentDiscovery.findComponentReadme(coreDir, name) != null;+ } catch {+ found = false;+ }+ inCore.set(name, found);+ }+ return /** @type {boolean} */ (inCore.get(name));+ };+ for (const template of templates) {+ const fields = [+ ...(typeof template.exampleFor === 'string'+ ? [{field: 'exampleFor', name: template.exampleFor}]+ : []),+ ...(Array.isArray(template.componentsUsed) ? template.componentsUsed : [])+ .filter(name => typeof name === 'string')+ .map(name => ({field: 'componentsUsed', name})),+ ];+ if (fields.length === 0) continue;+ const imported = importedNames(template.filePath, integration);+ for (const {field, name} of fields) {+ if (own.has(name) || imported.names.has(name)) continue;+ if (coreHas(name)) continue;+ // A name the template may reach through a namespace import, or+ // through a local module this read could not follow, is not judged.+ if (imported.unread.length > 0) {+ unchecked.push({+ docPath: template.docPath,+ name,+ reason: imported.unread[0],+ });+ continue;+ }+ if (!coreDir) {+ unchecked.push({+ docPath: template.docPath,+ name,+ reason:+ 'Core is not installed, so its component names cannot be checked.',+ });+ continue;+ }+ findings.push({+ docPath: template.docPath,+ name,+ message: `Template "${template.dirName}" names "${name}" in ${field}, but neither this package nor Core has a component by that name and the template does not import it, so \`astryx template --list\` and the block's search keywords give a component name no one can look up. Fix: use the component's exact name, or remove "${name}" from ${field}.`,+ });+ }+ }+ return {findings, unchecked};+}++/**+ * Visit every node under `node`, depth first.+ * @param {any} node+ * @param {(node: any) => void} visit+ */+function walkNodes(node, visit) {+ if (node == null || typeof node !== 'object') return;+ if (Array.isArray(node)) {+ for (const each of node) walkNodes(each, visit);+ return;+ }+ if (typeof node.type === 'string') visit(node);+ for (const [key, value] of Object.entries(node)) {+ if (+ key === 'loc' ||+ key === 'start' ||+ key === 'end' ||+ key === 'extra' ||+ key === 'leadingComments' ||+ key === 'trailingComments'+ ) {+ continue;+ }+ if (value && typeof value === 'object') walkNodes(value, visit);+ }+}++/** The extensions a local import may leave off, in the order tried. */+const LOCAL_MODULE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mjs'];++/**+ * Libraries that render no component of this package or of Core: React's+ * own exports and StyleX. Importing them, even as a namespace+ * (`import * as stylex`), leaves no name unjudged.+ */+const RENDERLESS_SOURCES = ['react', 'react-dom', '@stylexjs/stylex'];++/**+ * Packages a template may import from without leaving its names unjudged:+ * Core and the renderless libraries. Any other package may render components+ * this check does not see, such as a grid that renders its cards.+ */+const KNOWN_SOURCES = ['@astryxdesign/core', ...RENDERLESS_SOURCES];++/** @param {string} source */+function renderlessSource(source) {+ return RENDERLESS_SOURCES.some(+ known => source === known || source.startsWith(`${known}/`),+ );+}++/**+ * Whether an import source is one whose components this check sees: Core, a+ * library that renders none, or a relative helper (followed and read in full+ * on its own). The package's own name is followed like a helper too.+ * @param {string} source+ */+function knownSource(source) {+ if (source.startsWith('.')) return true;+ return KNOWN_SOURCES.some(+ known => source === known || source.startsWith(`${known}/`),+ );+}++/**+ * Every name a template imports, as imported and as bound locally, read+ * without running it, with the names its local helper modules import (a+ * relative import or re-export is followed, so a barrel such as+ * `parts/index.ts` counts). A name is judged only where the template reaches+ * components solely through named imports and re-exports this walk reads:+ * `unread` gives the reason for anything else it meets, which leaves an+ * unresolved name unjudged. That covers a default or namespace import, an+ * alias of an imported binding, a member read off one (in JSX or not,+ * optional or computed), a rendered component it cannot trace to an import,+ * `require()`, a dynamic `import()`, an `export *` from another package, and+ * a local module it cannot read. So does any `default` binding (`import X`,+ * `{default as X}`, `export {default as X} from`) and any import from a+ * package other than Core or a library that renders no component (see+ * KNOWN_SOURCES). An import of the package's own name is followed like a+ * relative helper, through its package.json `exports`. Type-only imports+ * render nothing and are skipped, as is a namespace or default import of a+ * library that renders no component.+ * @param {string} file+ * @param {LoadedIntegration} integration+ * @returns {{names: Set<string>, unread: string[]}}+ */+function importedNames(file, integration) {+ const packageName = integration.name;+ /** @type {Set<string>} */+ const names = new Set();+ /** @type {string[]} */+ const unread = [];+ const top = path.dirname(file);+ const shownTop = path.basename(file);+ /** @type {Set<string>} */+ const seen = new Set();+ /** @param {string} current */+ const visit = current => {+ if (seen.has(current)) return;+ seen.add(current);+ const shown = slash(path.relative(top, current)) || shownTop;+ let ast;+ try {+ ast = parseModule(fs.readFileSync(current, 'utf8'), {+ sourceType: 'module',+ plugins: ['typescript', 'jsx'],+ errorRecovery: true,+ });+ } catch {+ unread.push(+ `${shown} could not be read, so the components it renders are not known.`,+ );+ return;+ }+ // A file that parses only with errors recovered may be missing parts.+ if (/** @type {any} */ (ast).errors?.length > 0) {+ unread.push(+ `${shown} does not parse cleanly, so the components it renders are not known.`,+ );+ }+ /** @type {Map<string, string>} local binding -> the module it came from */+ const bindings = new Map();+ for (const node of ast.program.body) {+ const reexport =+ (node.type === 'ExportNamedDeclaration' && node.source != null) ||+ node.type === 'ExportAllDeclaration';+ if (node.type !== 'ImportDeclaration' && !reexport) continue;+ // A type-only import or re-export renders nothing.+ if (+ /** @type {any} */ (node).importKind === 'type' ||+ /** @type {any} */ (node).exportKind === 'type'+ ) {+ continue;+ }+ const source = String(/** @type {any} */ (node).source.value);+ // The package's own name: read like a relative helper, below.+ const own =+ typeof packageName === 'string' &&+ packageName !== '' &&+ (source === packageName || source.startsWith(`${packageName}/`));+ if (!own && !knownSource(source)) {+ unread.push(+ `${shown} imports from "${source}", another package whose components may render ones this check does not see.`,+ );+ }+ if (node.type === 'ImportDeclaration') {+ for (const specifier of node.specifiers) {+ if (/** @type {any} */ (specifier).importKind === 'type') continue;+ if (specifier.type === 'ImportNamespaceSpecifier') {+ // `import * as stylex`: a library that renders no component.+ if (renderlessSource(source)) continue;+ unread.push(+ `${shown} imports "${source}" as a namespace (${specifier.local.name}), whose component names this check does not read.`,+ );+ continue;+ }+ if (+ specifier.type === 'ImportDefaultSpecifier' &&+ !renderlessSource(source)+ ) {+ // A default may be any component, under any name.+ unread.push(+ `${shown} imports the default of "${source}" as ${specifier.local.name}, which may be any component.`,+ );+ }+ names.add(specifier.local.name);+ bindings.set(specifier.local.name, source);+ if (specifier.type === 'ImportSpecifier') {+ const imported = specifier.imported;+ const importedName =+ imported.type === 'Identifier' ? imported.name : imported.value;+ if (importedName === 'default') {+ unread.push(+ `${shown} imports the default of "${source}" as ${specifier.local.name}, which may be any component.`,+ );+ } else {+ names.add(importedName);+ }+ }+ }+ } else if (node.type === 'ExportNamedDeclaration') {+ // A barrel: `export {Body} from './Body'` passes Body on, and what+ // Body renders comes from the module it names.+ for (const each of node.specifiers) {+ const specifier = /** @type {any} */ (each);+ if (specifier.exportKind === 'type') continue;+ if (specifier.type !== 'ExportSpecifier') {+ // `export * as UI from`, `export UI from`.+ unread.push(+ `${shown} re-exports "${source}" as a whole (${specifier.exported.type === 'Identifier' ? specifier.exported.name : specifier.exported.value}), whose component names this check does not read.`,+ );+ continue;+ }+ const local =+ specifier.local.type === 'Identifier'+ ? specifier.local.name+ : specifier.local.value;+ const exported =+ specifier.exported.type === 'Identifier'+ ? specifier.exported.name+ : specifier.exported.value;+ if (local === 'default') {+ unread.push(+ `${shown} re-exports the default of "${source}" as ${exported}, which may be any component.`,+ );+ } else {+ names.add(local);+ }+ names.add(exported);+ }+ } else if (!source.startsWith('.') && !own) {+ // `export * from` another package passes on names this check+ // does not list.+ unread.push(+ `${shown} re-exports everything from "${source}", whose component names this check does not read.`,+ );+ continue;+ } else if (/** @type {any} */ (node).exported) {+ // `export * as UI from './parts'`.+ unread.push(+ `${shown} re-exports "${source}" as a whole, whose component names this check does not read.`,+ );+ }+ if (!source.startsWith('.') && !own) continue;+ if (own) {+ const resolved = componentDiscovery.ownPackageModule(+ integration,+ source,+ );+ /** @type {boolean} */+ let isFile;+ try {+ isFile = resolved != null && fs.statSync(resolved).isFile();+ } catch {+ isFile = false;+ }+ if (+ resolved &&+ isFile &&+ LOCAL_MODULE_EXTENSIONS.includes(path.extname(resolved))+ ) {+ visit(resolved);+ } else {+ unread.push(+ `${shown} imports "${source}", this package's own name, which resolves to no source this check can read.`,+ );+ }+ continue;+ }+ const base = path.resolve(path.dirname(current), source);+ const target = [+ base,+ ...LOCAL_MODULE_EXTENSIONS.map(extension => `${base}${extension}`),+ ...LOCAL_MODULE_EXTENSIONS.map(extension =>+ path.join(base, `index${extension}`),+ ),+ ].find(candidate => {+ try {+ return fs.statSync(candidate).isFile();+ } catch {+ return false;+ }+ });+ if (!target) {+ unread.push(+ `${shown} imports "${source}", which resolves to no file this check can read.`,+ );+ } else if (LOCAL_MODULE_EXTENSIONS.includes(path.extname(target))) {+ visit(target);+ }+ }+ // Anything this check does not model leaves the names unjudged: what+ // the module renders through a binding, an alias, a member read, a+ // component held in a variable, or a module loaded at runtime.+ /** @type {Set<string>} functions and classes the module declares */+ const declared = new Set();+ walkNodes(ast.program, node => {+ if (+ (node.type === 'FunctionDeclaration' ||+ node.type === 'ClassDeclaration') &&+ node.id?.name+ ) {+ declared.add(node.id.name);+ } else if (+ node.type === 'VariableDeclarator' &&+ node.id?.type === 'Identifier' &&+ [+ 'ArrowFunctionExpression',+ 'FunctionExpression',+ 'ClassExpression',+ ].includes(node.init?.type)+ ) {+ declared.add(node.id.name);+ }+ });+ const from = (/** @type {string} */ name) =>+ bindings.has(name) ? ` (imported from "${bindings.get(name)}")` : '';+ walkNodes(ast.program, node => {+ if (node.type === 'JSXMemberExpression') {+ let object = node.object;+ while (object?.type === 'JSXMemberExpression') object = object.object;+ const name = object?.name ?? 'an object';+ unread.push(+ `${shown} renders members of ${name}${from(name)}, whose names this check does not read.`,+ );+ } else if (+ node.type === 'JSXOpeningElement' &&+ node.name?.type === 'JSXIdentifier' &&+ /^[A-Z]/u.test(node.name.name) &&+ !names.has(node.name.name) &&+ !declared.has(node.name.name)+ ) {+ unread.push(+ `${shown} renders ${node.name.name}, a value this check does not trace to an import.`,+ );+ } else if (+ node.type === 'VariableDeclarator' &&+ node.init?.type === 'Identifier' &&+ bindings.has(node.init.name)+ ) {+ // `const UI = Lib`, `const {Panel} = Lib`: an alias of an import.+ if (node.id?.type === 'Identifier') {+ bindings.set(+ node.id.name,+ /** @type {string} */ (bindings.get(node.init.name)),+ );+ }+ unread.push(+ `${shown} reads ${node.init.name}${from(node.init.name)} into another name, which this check does not follow.`,+ );+ } else if (+ (node.type === 'MemberExpression' ||+ node.type === 'OptionalMemberExpression') &&+ node.object?.type === 'Identifier' &&+ bindings.has(node.object.name)+ ) {+ // `UI.Panel`, `UI?.Panel`, `UI['Panel']`, `createElement(UI.Panel)`.+ unread.push(+ `${shown} reads members of ${node.object.name}${from(node.object.name)}, whose names this check does not read.`,+ );+ } else if (+ node.type === 'CallExpression' &&+ node.callee?.type === 'Identifier' &&+ node.callee.name === 'require'+ ) {+ const argument = node.arguments?.[0];+ const spec =+ argument?.type === 'StringLiteral'+ ? `"${argument.value}"`+ : 'a module';+ unread.push(+ `${shown} loads ${spec} with require(), whose component names this check does not read.`,+ );+ } else if (+ node.type === 'ImportExpression' ||+ (node.type === 'CallExpression' && node.callee?.type === 'Import')+ ) {+ const argument = node.source ?? node.arguments?.[0];+ const spec =+ argument?.type === 'StringLiteral'+ ? `"${argument.value}"`+ : 'a module';+ unread.push(+ `${shown} loads ${spec} with a dynamic import(), whose component names this check does not read.`,+ );+ }+ });+ };+ visit(file);+ return {names, unread};+}++/**+ * The local name a module's default export declares (`export default+ * function AcmeWidget()`, `export default class AcmeWidget`), or of the+ * binding it exports as default (`export default AcmeWidget`), or null.+ * @param {string} file+ * @returns {string | null}+ */+function defaultBinding(file) {+ let ast;+ try {+ ast = parseModule(fs.readFileSync(file, 'utf8'), {+ sourceType: 'module',+ plugins: ['typescript', 'jsx'],+ errorRecovery: true,+ });+ } catch {+ return null;+ }+ for (const node of ast.program.body) {+ if (node.type !== 'ExportDefaultDeclaration') continue;+ const declaration = /** @type {any} */ (node.declaration);+ if (typeof declaration?.id?.name === 'string') return declaration.id.name;+ if (declaration?.type === 'Identifier') return declaration.name;+ }+ return null;+}++/**+ * A note: information beside validate's issues that fails nothing, with the+ * fix in its message.+ * @typedef {{code: string, message: string}} Note+ */++/**+ * @param {string} code+ * @param {{message: string}} finding+ * @returns {Note}+ */+function note(code, finding) {+ return {code, message: finding.message};+}++/**+ * The block component names this check could not judge, shaped like the+ * doc type report so `integration check` counts them as not compared: each+ * name a template gives in `exampleFor` or `componentsUsed` that neither the+ * package nor Core has, when the template reaches components through+ * anything but named imports and re-exports from the package, Core, or+ * helpers read in full (see importedNames), or when Core is not installed to+ * look it up in; its findings are always empty. A name judged unknown is an+ * `unknown_block_component` note, with its fix in the message: validate+ * lists notes beside its issues, and nothing counts them, so `--strict` does+ * not fail on it until the next minor release (architecture:cli-surface+ * INV35).+ * @param {LoadedIntegration} integration+ * @returns {Promise<{report: {status: 'checked', findings: [], unchecked: Array<{file: string, name: string, reason: string}>}, notes: Note[]}>}+ */+export async function blockComponentsCheck(integration) {+ const {findings, unchecked} = await judgeBlockComponents(integration);+ const base = integration.__packageDir ?? integration.templates ?? '';+ return {+ report: {+ status: 'checked',+ findings: [],+ unchecked: unchecked.map(entry => ({+ file: slash(path.relative(base, entry.docPath)),+ name: entry.name,+ reason: entry.reason,+ })),+ },+ notes: findings.map(entry => note('unknown_block_component', entry)),+ };+}+/*** Warn about a `.tsx` directly in the templates root with no same-stem template* metadata: template discovery pairs sources with docs, so `astryx template`@@ -617,6 +1170,162 @@ function componentDocFiles(root) {return {caseMismatch, duplicates};}+/**+ * Judge each component doc's `name` against the module its printed import+ * names: a finding when that module provably does not export it, and an+ * entry in `unchecked` when it cannot be judged, so it is listed instead.+ * @param {LoadedIntegration} integration+ * @param {Array<{name: string, docPath: string, sourcePath: string|null}>} components+ * @param {string} root the components root+ * @param {Map<string, string>} skip docs already reported, by path+ * @param {Array<{docPath: string, name: string, message: string}>} findings+ * @param {Array<{docPath: string, name: string, reason: string}>} unchecked+ */+async function judgeComponentDocNames(+ integration,+ components,+ root,+ skip,+ findings,+ unchecked,+) {+ const base = integration.__packageDir ?? root;+ for (const record of components) {+ if (componentDiscovery.isIntegrationMember(record)) continue;+ if (skip.has(record.docPath)) continue;+ // A doc with no source is its own error.+ if (record.sourcePath == null) continue;+ let doc;+ try {+ doc = await loadComponentDoc(record.docPath);+ } catch {+ continue;+ }+ const name = doc?.name;+ if (typeof name !== 'string' || name === record.name) continue;+ // The module the printed import names: the doc's import, the published+ // subpath, or the package root, resolved through package.json "exports".+ // Without a package to resolve it in, the same-stem source.+ const printed = componentDiscovery.importedModule(+ integration,+ record.docPath,+ doc,+ );+ if (printed === null) {+ unchecked.push({+ docPath: record.docPath,+ name,+ reason:+ 'Its import names another package, or resolves to no file this check can read.',+ });+ continue;+ }+ const module = printed ?? record.sourcePath;+ const shown = slash(path.relative(base, module));+ // Only what the code contradicts: the module must provably not export+ // the name the doc gives.+ const judged = moduleExportVerdict(module, name);+ if (judged.verdict === 'exports') continue;+ if (judged.verdict === 'unknown') {+ unchecked.push({docPath: record.docPath, name, reason: judged.reason});+ continue;+ }+ // A source whose only export is a default, read because no printed+ // import could be resolved: the package's entry may publish it under+ // any name, so the name is not judged. A printed import that names a+ // default-only module does not export the name, which is a mismatch.+ const exportedNames = moduleExportNames(module);+ const defaultOnly =+ exportedNames != null &&+ exportedNames.length === 1 &&+ exportedNames[0] === 'default';+ if (defaultOnly && printed === undefined) {+ unchecked.push({+ docPath: record.docPath,+ name,+ reason: `${shown} exports a default, which the package entry may publish under any name.`,+ });+ continue;+ }+ const file = path.basename(record.docPath);+ // The name to propose: the file name when the module exports it, else+ // the one component the module exports.+ let fix;+ if (defaultOnly) {+ fix =+ defaultBinding(module) === name+ ? `Fix: add \`export {${name}};\` to ${shown}, so it exports ${name} by name as well, or set the doc's import to the module that publishes it as ${name}.`+ : `Fix: bind the default to ${name} in ${shown} and export it by name too (\`const ${name} = …; export default ${name}; export {${name}};\`), or set the doc's import to the module that publishes it as ${name}.`;+ } else if (moduleExportsName(module, record.name)) {+ fix = `Fix: set name: '${record.name}' in ${file}.`;+ } else {+ const exported = (exportedNames ?? []).filter(each =>+ /^[A-Z][A-Za-z0-9]*$/u.test(each),+ );+ fix =+ exported.length === 1+ ? `Fix: set name: '${exported[0]}' in ${file}, the component ${shown} exports.`+ : `Fix: set name in ${file} to the component ${shown} exports${exported.length > 1 ? ` (${exported.join(', ')})` : ''}.`;+ }+ findings.push({+ docPath: record.docPath,+ name,+ message: `Component doc "${slash(path.relative(root, record.docPath))}" sets name: '${name}', but ${shown}, the module its import names, does not export ${name}, so Astryx lists the component as "${record.name}" (its file name), and \`astryx component ${record.name}\` prints \`import {${name}}\`. ${fix}`,+ });+ }+}++/**+ * The component doc names the check could not judge, shaped like the doc type+ * report so `integration check` counts them as not compared: each doc whose+ * `name` differs from the name it is listed under and whose source's exports+ * cannot all be read without running it; its findings are always empty. A+ * name the module its printed import names provably lacks is a+ * `doc_name_mismatch` note, with its fix in the message: validate lists+ * notes beside its issues, and nothing counts them, so `--strict` does not+ * fail on it until the next minor release (architecture:cli-surface INV35).+ * @param {LoadedIntegration} integration+ * @returns {Promise<{report: {status: 'checked', findings: [], unchecked: Array<{file: string, name: string, reason: string}>}, notes: Note[]}>}+ */+export async function componentDocNamesCheck(integration) {+ /** @type {Array<{docPath: string, name: string, message: string}>} */+ const findings = [];+ /** @type {Array<{docPath: string, name: string, reason: string}>} */+ const unchecked = [];+ const root = integration.components;+ if (root && !rootProblem(root)) {+ try {+ const {components} =+ await componentDiscovery.discoverValidIntegrationComponents(+ integration,+ );+ await judgeComponentDocNames(+ integration,+ components,+ root,+ componentDocFiles(root).caseMismatch,+ findings,+ unchecked,+ );+ } catch {+ // A components root discovery cannot read is reported as an issue.+ }+ }+ const base = integration.__packageDir ?? root ?? '';+ return {+ report: {+ status: 'checked',+ findings: [],+ unchecked: unchecked.map(entry => ({+ file: slash(path.relative(base, entry.docPath)),+ name: entry.name,+ reason: entry.reason,+ })),+ },+ notes: findings.map(entry => note('doc_name_mismatch', entry)),+ };+}+/*** Validate the integration's doc topics via the landed discovery. A doc that* cannot be loaded, is not a usable topic, or collides with a sibling isdiff --git a/packages/cli/foundation/response/response-types.doc.mjs b/packages/cli/foundation/response/response-types.doc.mjsindex 76ae5d02fb..1e001ca7f7 100644--- a/packages/cli/foundation/response/response-types.doc.mjs+++ b/packages/cli/foundation/response/response-types.doc.mjs@@ -338,7 +338,7 @@ export const doc = {{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, fix?, file?, line?} (fix: the change that resolves it; file and line: where, relative to the package), and notes when there are any: {code, message} information that fails nothing, such as invalid_cli_command for a malformed cliCommand, and the package layout findings added after the last minor release, each with its fix in the message (duplicate_component_doc, symlinked_root, unreadable_file, invalid_package_json, no_provider_id, source_without_component_doc where a doc and its source still pair), until they become warnings in the next minor release. 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), and notes when there are any: {code, message} information that fails nothing, such as invalid_cli_command for a malformed cliCommand, and the package layout findings added after the last minor release, each with its fix in the message (duplicate_component_doc, symlinked_root, unreadable_file, invalid_package_json, no_provider_id, source_without_component_doc where a doc and its source still pair), and doc_name_mismatch and unknown_block_component, until they become warnings in the next minor release. 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). When the manifest loads, docNames lists the component doc names it could not judge: status (checked), findings (always empty; a doc name the module its import names provably does not export is a doc_name_mismatch note, with its fix in the message) and unchecked ({file, name, reason}: a doc whose name differs from the name it is listed under and whose source exports cannot all be read, such as a re-export from another package). When the manifest loads, blockComponents lists the component names templates give in exampleFor or componentsUsed that could not be judged: status (checked), findings (always empty; a name neither the package nor Core has, and the template does not import, is an unknown_block_component note, with its fix in the message) and unchecked ({file, name, reason}: a name the template may reach through anything other than named imports and re-exports from Core, React, StyleX, local helpers or the entry of the package itself, such as an import from another package, a default or namespace import, an alias of or member read off an imported binding, require() or a dynamic import(), or a local module that cannot be read, or any name Core would have to resolve when Core is not installed).',},{value: 'integration.template-conflicts',diff --git a/packages/cli/test/integration-check-failures.json b/packages/cli/test/integration-check-failures.jsonindex 709e61a360..b3be172a7c 100644--- a/packages/cli/test/integration-check-failures.json+++ b/packages/cli/test/integration-check-failures.json@@ -1,24 +1,28 @@{"checks": ["validate", "components", "templates", "docs"],"results": {- "validate": ["docTypes", "issues"],+ "validate": ["blockComponents", "docNames", "docTypes", "issues"],"components": ["conflicts", "issues", "propDrift"],"templates": ["conflicts", "issues"],"docs": ["copiedPassages", "findings", "fluff", "issues", "strayPointers"]},"reports": {+ "blockComponents": "block_components_skipped",+ "docNames": "doc_names_skipped","docTypes": "doc_types_skipped","propDrift": "prop_drift_skipped"},"codes": ["ambiguous_component_replacement","ambiguous_template_replacement",+ "block_components_skipped","codemod_outside_version","component_name_conflict","copied_passage","core_not_found","default_mismatch","doc_fluff",+ "doc_names_skipped","doc_types_skipped","duplicate_doc","duplicate_prop",