Check an integration

Pick the check for each problem, learn what fails and what only warns, and run every check in CI.

Pick a check

Run these in the package folder. The four doctor integration checks read your source; integration verify checks the package npm would publish.

Command	Proves	Exits 1 when	Only warns when
`npx astryx doctor integration validate`	The manifest loads, and each root holds contributions the CLI can read	A declared root is missing (`missing_root`), a contribution does not load (`invalid_doc`, `invalid_component`, `invalid_theme`), or two templates in the package replace one Core id (`ambiguous_template_replacement`)	The manifest has a key this CLI does not know (`unknown_manifest_key`). With no `astryx.integration.mjs` it prints a hint and exits 0
`npx astryx doctor integration components`	No component name clashes with a Core component	Core is not installed (`core_not_found`)	A name clashes with Core
`npx astryx doctor integration templates`	Each `replaces` names a Core template of the same type	A `replaces` target is missing (`missing_template_replacement_target`) or of the other type (`invalid_template_replacement`), or two templates replace one id (`ambiguous_template_replacement`)	A template id matches a Core id without `replaces`
`npx astryx doctor integration docs`	Your docs tree, every link, and topic names against Core	A topic takes a Core topic name without `replaces` or `extends`, a doc is invalid (`invalid_doc`), or a namespace or placement fails, which hides the doc (`invalid_doc_graph`)	A link names no doc (`invalid_doc_graph`)
`npx astryx integration verify`	The packed package holds every file, shows the same contributions, resolves every public import, and declares the CLI it needs	Anything `validate` fails on, no manifest, a file left out of the `.tgz` file, an import that does not resolve, or a missing CLI peer	Anything `validate` warns about

Pass a package name, such as npx astryx doctor integration validate @acme/astryx-widgets, to check an installed copy from an app instead.

Run every check in CI

Chain the five checks so the first failure stops the run. Install devDependencies first, because the components check needs Core.

bash
npx astryx doctor integration validate && npx astryx doctor integration components && npx astryx doctor integration templates && npx astryx doctor integration docs && npx astryx integration verify

integration verify runs validate but none of the other three: a Core name clash, a replaces that names no Core template, a topic that takes a Core name, or a hidden guide still passes it.
Warnings keep exit code 0, so read them before you publish.
Bare npx astryx doctor in the package also warns about a doc section over 32 KB, which no check above measures.

Verify the packed package

integration verify packs your package with npm, unpacks it into a temporary app, and checks that the app sees everything your source has. It publishes nothing and leaves no .tgz file or temporary folder behind.

It runs npm pack the way npm publish would, including your prepack script.
It checks that every contribution file is in the .tgz file. A root missing from files fails with Add "templates" to "files" in package.json.
It lists the components, templates, themes, docs, and codemods the temporary app sees, and compares them with your source.
It resolves each component's import, and each template's public import, the way Node does, and checks that the module exports the component, or a default export for a template.
It fails a package that ships a docs section, a placed guide, a template replaces, a doc section with an id, or a theme without an @astryxdesign/cli peer of >=0.7.0.

integration pack --check, the name this check had in 0.6, still runs it and prints a note; it will be removed in a later release. The options and exit codes are in astryx docs cli/commands/integration-verify.