An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): integration check lists the pairing, root and package.json findings without failing --strict (#7810)
Joeyc08a49fa6d42
diff --git a/.changeset/cli-integration-check-gaps.md b/.changeset/cli-integration-check-gaps.mdindex 36ef504da7..fc465250cb 100644--- a/.changeset/cli-integration-check-gaps.md+++ b/.changeset/cli-integration-check-gaps.md@@ -2,13 +2,13 @@'@astryxdesign/cli': patch----[fix] `astryx doctor integration validate`, `astryx integration check` and `astryx integration verify` catch more package mistakes, and each new finding ends in a `Fix:` that clears it:+[fix] `astryx doctor integration validate`, `astryx integration check` and `astryx integration verify` catch more package mistakes, and each new finding ends in a `Fix:` that clears it. Findings that 0.7.2 did not fail on are listed as notes beside validate's issues, which nothing counts, until the next minor:-- Two docs for one component (`AcmeWidget.doc.mjs` and `AcmeWidget.doc.js`) warn `duplicate_component_doc` and name the one read; discovery now always reads the same one.-- A component doc whose file name differs from its source only in letter case is one finding that says which file to rename: an error where the pair fails (Linux), a `source_without_component_doc` warning where it still pairs (a case-insensitive disk) or the doc is hidden.-- A root reached through a symlinked folder warns `symlinked_root`: npm pack does not follow it.+- Two docs for one component (`AcmeWidget.doc.mjs` and `AcmeWidget.doc.js`) are listed as `duplicate_component_doc`, naming the one read; discovery now always reads the same one.+- A component doc whose file name differs from its source only in letter case is one finding that says which file to rename: an error where the pair fails (Linux), a listed `source_without_component_doc` where it still pairs (a case-insensitive disk); a hidden doc that does not pair keeps the source warning it had.+- A root reached through a symlinked folder is listed as `symlinked_root`: npm pack does not follow it.- An absolute root says roots are relative and gives the relative path; a root that is a file is reported by every check instead of crashing it.-- A package.json without `name` or `version` warns with a fix, instead of a crash or a pass; `verify` fails on it. A package whose `name` and manifest `providerId` give no provider ID warns `no_provider_id`.-- A contribution file Astryx cannot read warns `unreadable_file`, before npm pack fails on it.+- A package.json without `name` or `version` is listed with a fix, instead of a crash; `verify` fails on it. A package whose `name` and manifest `providerId` give no provider ID is listed as `no_provider_id`.+- A contribution file Astryx cannot read is listed as `unreadable_file`, before npm pack fails on it.@josephfarinadiff --git a/.changeset/cli-integration-layout-listed.md b/.changeset/cli-integration-layout-listed.mdnew file mode 100644index 0000000000..5df98adf02--- /dev/null+++ b/.changeset/cli-integration-layout-listed.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] `astryx integration check` lists the pairing, root and package.json findings without failing `--strict`; they become failures in the next minor. `astryx doctor integration validate` lists them as notes beside its issues (two docs for one component, a root reached through a symlink, a contribution file that cannot be read, a package.json without `name` or `version`, no provider ID, and a doc whose file name differs from its source only in letter case where the two still pair), each with its fix; nothing counts a note. A hidden component doc that does not pair with its source keeps the source warning it had. `astryx integration verify` still fails on a package.json npm cannot pack.++@josephfarinadiff --git a/packages/cli/README.md b/packages/cli/README.mdindex 6c2ef86f92..21f488aea7 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -528,7 +528,7 @@ Every response has a `type` discriminant. The full set is below (generated from| `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. 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.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. |diff --git a/packages/cli/api/integration/pack-check.mjs b/packages/cli/api/integration/pack-check.mjsindex ad8e4e0d50..2a0a2ec1a3 100644--- a/packages/cli/api/integration/pack-check.mjs+++ b/packages/cli/api/integration/pack-check.mjs@@ -1266,13 +1266,17 @@ export async function integrationPackCheck(options = {}) {// ── Phase 1: structure validation ──const localResult = await validateLocalIntegration(cwd);/** @type {Issue[]} */- const issues = localResult.issues.map(issue =>- // A package.json npm cannot pack is a warning to validate, which does- // not pack; here it is what fails the pack.- issue.code === 'invalid_package_json'- ? {...issue, severity: 'error'}- : issue,- );+ const issues = [+ ...localResult.issues,+ // Validate lists these layout findings without counting them. A+ // package.json npm cannot pack is what fails the pack here, as it did+ // before they were named; the rest stay warnings, which fail nothing.+ ...(localResult.found ? (localResult.listed ?? []) : []).map(issue =>+ issue.code === 'invalid_package_json'+ ? {...issue, severity: /** @type {const} */ ('error')}+ : issue,+ ),+ ];if (!localResult.found || !localResult.integration) {return emptyReceipt(pkgName, [diff --git a/packages/cli/api/integration/validate-integration-case-disk.test.mjs b/packages/cli/api/integration/validate-integration-case-disk.test.mjsindex 7293297e36..c9016c8904 100644--- a/packages/cli/api/integration/validate-integration-case-disk.test.mjs+++ b/packages/cli/api/integration/validate-integration-case-disk.test.mjs@@ -35,7 +35,7 @@ vi.mock(},);-const {validateLocalIntegration} = await import('./validate-integration.mjs');+const {validateIntegration} = await import('./validate-integration.mjs');/** @type {string} */let tmpDir;@@ -49,7 +49,7 @@ afterEach(() => {});describe('a doc whose name differs from its source only in case, on a case-insensitive disk', () => {- it('warns source_without_component_doc with the rename, without failing validate', async () => {+ it('lists source_without_component_doc with the rename, without an issue', async () => {fs.writeFileSync(path.join(tmpDir, 'package.json'),JSON.stringify({name: '@acme/kit', version: '1.0.0'}),@@ -68,14 +68,44 @@ describe('a doc whose name differs from its source only in case, on a case-insen'export function AcmeWidget() { return null; }\n',);- const {issues} = await validateLocalIntegration(tmpDir);- expect(issues).toEqual([+ const {data} = await validateIntegration(undefined, {cwd: tmpDir});+ expect(data.issues).toEqual([]);+ expect(data.notes).toEqual([{code: 'source_without_component_doc',- severity: 'warning',message:'Component doc "Acmewidget.doc.mjs" and its source "AcmeWidget.tsx" differ only in letter case. They pair on a case-insensitive disk (macOS, Windows) but not on Linux, where CI and most installs run, so there the component is missing. Fix: rename Acmewidget.doc.mjs to AcmeWidget.doc.mjs.',},]);});++ it('lists a hidden doc that pairs with its source, without an issue', async () => {+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({name: '@acme/kit', version: '1.0.0'}),+ );+ fs.writeFileSync(+ path.join(tmpDir, 'astryx.integration.mjs'),+ "export default {components: './components'};\n",+ );+ fs.mkdirSync(path.join(tmpDir, 'components'));+ fs.writeFileSync(+ path.join(tmpDir, 'components', 'Acmewidget.doc.mjs'),+ "export default {type: 'component',\n hidden: true,\n name: 'AcmeWidget', displayName: 'AcmeWidget', usage: {description: 'A widget.'}, props: []};\n",+ );+ fs.writeFileSync(+ path.join(tmpDir, 'components', 'AcmeWidget.tsx'),+ 'export function AcmeWidget() { return null; }\n',+ );++ const {data} = await validateIntegration(undefined, {cwd: tmpDir});+ expect(data.issues).toEqual([]);+ expect(data.notes).toEqual([+ {+ code: 'source_without_component_doc',+ message:+ 'Hidden component doc "Acmewidget.doc.mjs" and its source "AcmeWidget.tsx" differ only in letter case. They pair on a case-insensitive disk (macOS, Windows) but not on Linux, where CI and most installs run. Fix: rename Acmewidget.doc.mjs to AcmeWidget.doc.mjs.',+ },+ ]);+ });});diff --git a/packages/cli/api/integration/validate-integration-gaps.test.mjs b/packages/cli/api/integration/validate-integration-gaps.test.mjsindex 3b2a0f56e8..47180db4e9 100644--- a/packages/cli/api/integration/validate-integration-gaps.test.mjs+++ b/packages/cli/api/integration/validate-integration-gaps.test.mjs@@ -15,8 +15,21 @@import {afterEach, beforeEach, describe, expect, it} from 'vitest';import * as fs from 'node:fs';import * as path from 'node:path';-import {validateLocalIntegration} from './validate-integration.mjs';-import {integrationCheck} from './check/check.mjs';+import {spawnSync} from 'node:child_process';+import {fileURLToPath} from 'node:url';+import {+ validateIntegration,+ validateLocalIntegration,+} from './validate-integration.mjs';+import {+ integrationCheck,+ strictIssues,+ summarizeCheck,+} from './check/check.mjs';++const CLI = fileURLToPath(+ new URL('../../clients/cli/bin/astryx.mjs', import.meta.url),+);let tmpDir;let copies = 0;@@ -98,6 +111,24 @@ async function issuesOf(dir) {return (await validateLocalIntegration(dir)).issues;}+/**+ * The notes validate lists beside its issues, which count nowhere: the layout+ * findings added after the last minor release, each with its fix.+ * @param {string} dir+ * @returns {Promise<Array<{code: string, message: string}>>}+ */+async function listedOf(dir) {+ return (await validateIntegration(undefined, {cwd: dir})).data.notes ?? [];+}++/**+ * Issues and notes together: what a followed fix must clear.+ * @param {string} dir+ */+async function allOf(dir) {+ return [...(await issuesOf(dir)), ...(await listedOf(dir))];+}+/*** The one issue with this code, which the test is about.* @param {Array<{code: string, message: string}>} issues@@ -155,7 +186,7 @@ describe('template ids', () => {});describe('component doc files', () => {- it('warns about two docs for one component and names the one read', async () => {+ it('lists two docs for one component, naming the one read, without an issue', async () => {const dir = writePackage({[MANIFEST]: manifest({components: './components'}),'components/AcmeWidget.doc.mjs': componentDoc('AcmeWidget'),@@ -163,13 +194,14 @@ describe('component doc files', () => {'components/AcmeWidget.tsx': componentSource('AcmeWidget'),});- const message = only(await issuesOf(dir), 'duplicate_component_doc');+ expect(await issuesOf(dir)).toEqual([]);+ const message = only(await listedOf(dir), 'duplicate_component_doc');expect(message).toBe('Component "AcmeWidget" has 2 docs: AcmeWidget.doc.mjs, AcmeWidget.doc.js. Astryx reads AcmeWidget.doc.mjs and ignores AcmeWidget.doc.js. Fix: delete AcmeWidget.doc.js, moving anything only it says into AcmeWidget.doc.mjs.',);const fixed = follow(dir, {remove: ['components/AcmeWidget.doc.js']});- expect(await issuesOf(fixed)).toEqual([]);+ expect(await allOf(fixed)).toEqual([]);});it('gives one finding for a doc whose name differs from its source only in case', async () => {@@ -200,7 +232,7 @@ describe('component doc files', () => {});describe('a hidden doc beside a source whose name differs only in case', () => {- it('warns, without failing validate, about a hidden doc whose name differs from its source only in case', async () => {+ it('keeps the source warning 0.7.2 gives where the hidden doc does not pair, as on Linux', async () => {const dir = writePackage({[MANIFEST]: manifest({components: './components'}),'components/Acmewidget.doc.mjs': componentDoc('AcmeWidget').replace(@@ -211,19 +243,18 @@ describe('a hidden doc beside a source whose name differs only in case', () => {});const issues = await issuesOf(dir);- expect(issues).toEqual([- {- code: 'source_without_component_doc',- severity: 'warning',- message:- 'Hidden component doc "Acmewidget.doc.mjs" and its source "AcmeWidget.tsx" differ only in letter case. They pair on a case-insensitive disk (macOS, Windows) but not on Linux, where CI and most installs run. Fix: rename Acmewidget.doc.mjs to AcmeWidget.doc.mjs.',- },+ expect(issues.map(issue => [issue.code, issue.severity])).toEqual([+ ['source_without_component_doc', 'warning'],]);+ expect(issues[0].message).toMatch(+ /^Component source "AcmeWidget\.tsx" has no same-stem metadata file AcmeWidget\.doc\.mjs, so Astryx ignores it\. Fix: /u,+ );+ expect(await listedOf(dir)).toEqual([]);});});describe('roots', () => {- it('warns that npm pack does not follow a symlinked root, and reads its folder through it', async () => {+ it('lists that npm pack does not follow a symlinked root, and reads its folder through it', async () => {const dir = writePackage({[MANIFEST]: manifest({components: './components'}),'real-components/AcmeWidget.doc.mjs': componentDoc('AcmeWidget'),@@ -231,7 +262,8 @@ describe('roots', () => {});fs.symlinkSync('real-components', path.join(dir, 'components'));- const issues = await issuesOf(dir);+ expect(await issuesOf(dir)).toEqual([]);+ const issues = await listedOf(dir);expect(issues.map(issue => issue.code)).toEqual(['symlinked_root']);expect(issues[0].message).toBe('Declared components root "components" is reached through the symlink "components" (to "real-components"). Astryx follows it locally, but npm pack does not follow a symlinked folder, so the published package ships none of these files. Fix: replace the link with the folder itself (move real-components/ to components/), or set `components: \'./real-components\'` in astryx.integration.mjs.',@@ -241,7 +273,7 @@ describe('roots', () => {remove: ['components'],move: [['real-components', 'components']],});- expect(await issuesOf(fixed)).toEqual([]);+ expect(await allOf(fixed)).toEqual([]);});it('says an absolute root inside the package must be relative', async () => {@@ -298,7 +330,7 @@ describe('roots', () => {});describe('package.json', () => {- it('warns about a missing name and keeps checking, without crashing any check', async () => {+ it('lists a missing name and keeps checking, without crashing any check', async () => {const dir = writePackage({[MANIFEST]: manifest({components: './components', docs: './docs'}),@@ -312,14 +344,16 @@ describe('package.json', () => {for (const check of result.data.checks) {expect(check.response.data.issues.map(issue => [issue.code, issue.severity]),- ).toEqual([- ['invalid_package_json', 'warning'],- ['invalid_component', 'error'],- ]);+ ).toEqual([['invalid_component', 'error']]);}- expect(result.data.checks[0].response.data.issues[0].message).toBe(- 'package.json has no "name", so npm cannot pack or publish the package, and a project that installs it has no name to select it by. Fix: add "name": "@your-scope/your-package" to package.json.',- );+ const validate = result.data.checks[0].response.data;+ expect('notes' in validate ? validate.notes : undefined).toEqual([+ {+ code: 'invalid_package_json',+ message:+ 'package.json has no "name", so npm cannot pack or publish the package, and a project that installs it has no name to select it by. Fix: add "name": "@your-scope/your-package" to package.json.',+ },+ ]);expect(result.data.failed).toBe(true);});@@ -342,7 +376,7 @@ describe('package.json', () => {const propDrift = /** @type {any} */ (components?.response.data)?.propDrift;expect(propDrift).toBeDefined();const failures = result.data.failures.map(failure => failure.code);- expect(failures).toContain('invalid_package_json');+ expect(failures).not.toContain('invalid_package_json');if (propDrift.status === 'skipped') {// No TypeScript here: --strict names the skipped comparison.expect(failures).toContain('prop_drift_skipped');@@ -368,9 +402,9 @@ describe('package.json', () => {const components = result.data.checks.find(check => check.check === 'components',);- expect(components?.response.data.issues.map(issue => issue.code)).toEqual([- 'invalid_package_json',- ]);+ expect(components?.response.data.issues.map(issue => issue.code)).toEqual(+ [],+ );expect(result.data.failures.filter(failure => failure.code === 'invalid_doc_graph',@@ -396,10 +430,9 @@ describe('package.json', () => {docs?.response.data.issues.map(issue => issue.message) ?? [];expect(messages.join('\n')).not.toContain('astryx-unnamed-local-package');expect(docs?.response.data.issues.map(issue => issue.code)).toEqual([- 'invalid_package_json','invalid_doc_graph',]);- expect(messages[1]).toMatch(+ expect(messages[0]).toMatch(/^deploying § overview: "generic:no-such-topic" names no doc\./u,);});@@ -412,7 +445,7 @@ describe('package.json', () => {['@acme/-kit'],['~acme'],])(- 'warns that no provider ID can be derived from the name %s, and keeps checking',+ 'lists that no provider ID can be derived from the name %s, and keeps checking',async name => {const dir = writePackage({@@ -422,11 +455,11 @@ describe('package.json', () => {{name, version: '1.0.0'},);- const issues = await issuesOf(dir);- expect(issues.map(issue => [issue.code, issue.severity])).toEqual([- ['no_provider_id', 'warning'],- ['invalid_component', 'error'],- ]);+ expect(+ (await issuesOf(dir)).map(issue => [issue.code, issue.severity]),+ ).toEqual([['invalid_component', 'error']]);+ const issues = await listedOf(dir);+ expect(issues.map(issue => issue.code)).toEqual(['no_provider_id']);expect(issues[0].message).toBe(`No provider ID can be derived for this package: package.json "name" ${JSON.stringify(name)} is not a bare package name (an optional @scope/ and a name, each starting with a lowercase letter or digit and holding only lowercase letters, digits, "-", ".", "_" and "~"), and astryx.integration.mjs declares no providerId that is one. Astryx files the package's components, templates and docs under that ID, so links to them and selecting the package cannot work. Fix: rename the package, such as "@your-scope/your-package", or set \`providerId: '@your-scope/your-package'\` in astryx.integration.mjs.`,);@@ -446,6 +479,7 @@ describe('package.json', () => {const issues = await issuesOf(dir);expect(issues.map(issue => issue.code)).toEqual(['invalid_manifest']);+ expect(await listedOf(dir)).toEqual([]);});it('derives the provider ID from the manifest when the name cannot give one', async () => {@@ -532,7 +566,7 @@ describe('package.json', () => {).toEqual([]);});- it('fails only --strict on a missing name when nothing else is wrong', async () => {+ it('fails neither run on a missing name when nothing else is wrong: it is listed until the next minor', async () => {const dir = writePackage({[MANIFEST]: manifest({docs: './docs'}),@@ -543,11 +577,11 @@ describe('package.json', () => {expect((await integrationCheck({cwd: dir})).data.failed).toBe(false);expect((await integrationCheck({cwd: dir, strict: true})).data.failed).toBe(- true,+ false,);});- it('warns about a missing version and still checks the rest', async () => {+ it('lists a missing version and still checks the rest', async () => {const dir = writePackage({[MANIFEST]: manifest({components: './components'}),@@ -556,11 +590,11 @@ describe('package.json', () => {{name: '@acme/kit'},);- const issues = await issuesOf(dir);- expect(issues.map(issue => [issue.code, issue.severity])).toEqual([- ['invalid_package_json', 'warning'],- ['invalid_component', 'error'],- ]);+ expect(+ (await issuesOf(dir)).map(issue => [issue.code, issue.severity]),+ ).toEqual([['invalid_component', 'error']]);+ const issues = await listedOf(dir);+ expect(issues.map(issue => issue.code)).toEqual(['invalid_package_json']);expect(issues[0].message).toBe('package.json has no "version", so npm cannot pack or publish the package. Fix: add "version": "0.1.0" to package.json.',);@@ -572,7 +606,7 @@ describe('package.json', () => {{name: '@acme/kit', private: true},);- expect(await issuesOf(dir)).toEqual([]);+ expect(await allOf(dir)).toEqual([]);});});@@ -590,18 +624,15 @@ describe('unreadable files and theme names', () => {const file = path.join(dir, 'components', 'AcmeWidget.tsx');fs.chmodSync(file, 0);try {- const issues = await issuesOf(dir);- const message = only(issues, 'unreadable_file');- expect(issues.find(i => i.code === 'unreadable_file')?.severity).toBe(- 'warning',- );+ expect(await issuesOf(dir)).toEqual([]);+ const message = only(await listedOf(dir), 'unreadable_file');expect(message).toBe('Could not read "components/AcmeWidget.tsx" (EACCES), so Astryx cannot check it and npm pack fails on it. Fix: make it readable (chmod a+r components/AcmeWidget.tsx), or delete it if it does not belong in the package.',);} finally {fs.chmodSync(file, 0o644);}- expect(await issuesOf(dir)).toEqual([]);+ expect(await allOf(dir)).toEqual([]);},);@@ -620,7 +651,7 @@ describe('unreadable files and theme names', () => {);for (const file of files) fs.chmodSync(file, 0);try {- expect(await issuesOf(dir)).toEqual([]);+ expect(await allOf(dir)).toEqual([]);} finally {for (const file of files) fs.chmodSync(file, 0o644);}@@ -657,3 +688,140 @@ describe('unreadable files and theme names', () => {).toEqual([]);});});++describe('layout findings 0.7.2 did not fail on', () => {+ it('never fails --strict on a note: notes count nowhere', () => {+ /** @type {any} */+ const response = {+ type: 'integration.validate',+ data: {+ validated: true,+ name: '@acme/kit',+ version: '1.0.0',+ issues: [],+ notes: [+ {code: 'duplicate_component_doc', message: 'Two docs. Fix: one.'},+ ],+ },+ };+ expect(strictIssues('validate', response)).toEqual({+ warnings: [],+ skipped: [],+ });+ expect(summarizeCheck(response)).toEqual({+ errors: 0,+ warnings: 0,+ skipped: [],+ failed: false,+ });+ });++ const asRoot = process.getuid?.() === 0;++ /** @type {Array<[string, () => string]>} */+ const layouts = [+ [+ 'two docs for one component',+ () =>+ writePackage({+ [MANIFEST]: manifest({components: './components'}),+ 'components/AcmeWidget.doc.mjs': componentDoc('AcmeWidget'),+ 'components/AcmeWidget.doc.js': componentDoc('AcmeWidget'),+ 'components/AcmeWidget.tsx': componentSource('AcmeWidget'),+ }),+ ],+ [+ 'a root reached through a symlink',+ () => {+ const dir = writePackage({+ [MANIFEST]: manifest({components: './components'}),+ 'real-components/AcmeWidget.doc.mjs': componentDoc('AcmeWidget'),+ 'real-components/AcmeWidget.tsx': componentSource('AcmeWidget'),+ });+ fs.symlinkSync('real-components', path.join(dir, 'components'));+ return dir;+ },+ ],+ [+ 'a package.json without a version',+ () =>+ writePackage(+ {+ [MANIFEST]: manifest({docs: './docs'}),+ 'docs/a.doc.mjs': topic('a'),+ },+ {name: '@acme/kit'},+ ),+ ],+ [+ 'a package.json without a name',+ () =>+ writePackage(+ {+ [MANIFEST]: manifest({docs: './docs'}),+ 'docs/a.doc.mjs': topic('a'),+ },+ {version: '1.0.0'},+ ),+ ],+ ...(asRoot+ ? []+ : /** @type {Array<[string, () => string]>} */ ([+ [+ 'a contribution file it cannot read',+ () => {+ const dir = writePackage({+ [MANIFEST]: manifest({components: './components'}),+ 'components/AcmeWidget.doc.mjs': componentDoc('AcmeWidget'),+ 'components/AcmeWidget.tsx': componentSource('AcmeWidget'),+ });+ fs.chmodSync(path.join(dir, 'components', 'AcmeWidget.tsx'), 0);+ return dir;+ },+ ],+ ])),+ ];++ it.each(layouts)(+ 'lists %s as a note and passes integration check --strict',+ async (_label, make) => {+ const dir = make();+ try {+ const result = await integrationCheck({cwd: dir, strict: true});+ expect(result.data.failures).toEqual([]);+ expect(result.data.failed).toBe(false);+ const validate = /** @type {any} */ (+ result.data.checks[0].response.data+ );+ expect(validate.notes.length).toBeGreaterThan(0);+ for (const note of validate.notes) {+ expect(Object.keys(note).sort()).toEqual(['code', 'message']);+ expect(note.message).toContain('Fix: ');+ }+ } finally {+ const file = path.join(dir, 'components', 'AcmeWidget.tsx');+ if (fs.existsSync(file)) fs.chmodSync(file, 0o644);+ }+ },+ );++ it('prints the notes and counts none of them', () => {+ const dir = writePackage({+ [MANIFEST]: manifest({components: './components'}),+ 'components/AcmeWidget.doc.mjs': componentDoc('AcmeWidget'),+ 'components/AcmeWidget.doc.js': componentDoc('AcmeWidget'),+ 'components/AcmeWidget.tsx': componentSource('AcmeWidget'),+ });++ 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 (duplicate_component_doc): Component "AcmeWidget" has 2 docs:',+ );+ 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 16f498984b..3e061c0a74 100644--- a/packages/cli/api/integration/validate-integration.mjs+++ b/packages/cli/api/integration/validate-integration.mjs@@ -58,14 +58,17 @@ import {// integration-warnings need them too, and foundation must not depend on api.import {INVALID_CLI_COMMAND,+ isListedIssue,+ issueListed as listed,validateLoadedIntegration,+ validateLoadedIntegrationListed,issueError as error,issueWarning as warning,rootProblem,} from '../../foundation/integrations/validate-contributions.mjs';import {formatCliCommand} from '../../foundation/env/package-manager.mjs';-export {validateLoadedIntegration};+export {validateLoadedIntegration, isListedIssue};/*** @typedef {import('../../foundation/integrations/issue').AstryxIntegrationIssue} Issue@@ -81,6 +84,10 @@ export {validateLoadedIntegration};* @property {Issue[]} issues* @property {Array<{code: string, message: string}>} [notes] Information that* fails nothing, such as `invalid_cli_command` (a malformed `cliCommand`).+ * @property {Issue[]} [listed] Layout findings added after the last minor+ * release: validate lists them as notes, which count nowhere, since they+ * may not fail `--strict` until the next (architecture:cli-surface INV35);+ * `integration verify` still fails on a package.json npm cannot pack.* @property {import('../../foundation/integrations/integrations.mjs').LoadedIntegration} [integration]*/@@ -404,7 +411,9 @@ async function validateAtPackageDir(// `integration check --strict` fails on any warning, and a new failure code// joins only in a minor release (architecture:cli-surface INV35). Doctor's// project check still warns about it.- for (const issue of await validateLoadedIntegration(loaded)) {+ const contribution = await validateLoadedIntegrationListed(loaded);+ (result.listed ??= []).push(...contribution.listed);+ for (const issue of contribution.issues) {if (issue.code === INVALID_CLI_COMMAND) {(result.notes ??= []).push({code: issue.code, message: issue.message});} else {@@ -492,7 +501,7 @@ export async function validateLocalIntegration(cwd = process.cwd()) {{name, version: pkg.version},{scanUnreachable: true},);- result.issues.unshift(+ (result.listed ??= []).unshift(...fields,// Only a manifest that loaded says whether it declares a providerId; one// that did not is reported as invalid_manifest.@@ -536,7 +545,7 @@ function providerIdIssues(name, declared, manifestFile) {if (typeof declared === 'string' && isPackageName(declared)) return [];const manifest = path.basename(manifestFile);return [- warning(+ listed('no_provider_id',`No provider ID can be derived for this package: package.json "name" ${JSON.stringify(name)} is not a bare package name (an optional @scope/ and a name, each starting with a lowercase letter or digit and holding only lowercase letters, digits, "-", ".", "_" and "~"), and ${manifest} declares no providerId that is one. Astryx files the package's components, templates and docs under that ID, so links to them and selecting the package cannot work. Fix: rename the package, such as "@your-scope/your-package", or set \`providerId: '@your-scope/your-package'\` in ${manifest}.`,),@@ -553,11 +562,11 @@ function packageJsonFieldIssues(pkg, pkgJsonPath) {/** @type {Issue[]} */const issues = [];const shown = path.basename(pkgJsonPath);- // Warnings, so validate keeps the exit code it had for these packages;- // `integration verify`, which packs, reports them as errors.+ // Listed, so validate and `--strict` keep the result they had for these+ // packages; `integration verify`, which packs, reports them as errors.if (typeof pkg.name !== 'string' || pkg.name === '') {issues.push(- warning(+ listed('invalid_package_json',`${shown} has no "name", so npm cannot pack or publish the package, and a project that installs it has no name to select it by. Fix: add "name": "@your-scope/your-package" to ${shown}.`,),@@ -569,7 +578,7 @@ function packageJsonFieldIssues(pkg, pkgJsonPath) {(typeof pkg.version !== 'string' || pkg.version === '')) {issues.push(- warning(+ listed('invalid_package_json',`${shown} has no "version", so npm cannot pack or publish the package. Fix: add "version": "0.1.0" to ${shown}.`,),@@ -656,7 +665,19 @@ export async function validateIntegration(pkg, options = {}) {const docTypes = integration? await integrationDocTypes(integration, cwd): undefined;- const notes = result.found ? (result.notes ?? []) : [];+ // 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).+ const notes = result.found+ ? [+ ...(result.notes ?? []),+ ...(result.listed ?? []).map(issue => ({+ code: issue.code,+ message: issue.message,+ })),+ ]+ : [];return {type: 'integration.validate',data: {diff --git a/packages/cli/api/integration/validate-integration.type.mjs b/packages/cli/api/integration/validate-integration.type.mjsindex aa99b2cd76..6cac785ff7 100644--- a/packages/cli/api/integration/validate-integration.type.mjs+++ b/packages/cli/api/integration/validate-integration.type.mjs@@ -40,7 +40,16 @@* @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* `notes`: information beside the issues that fails nothing, such as- * `invalid_cli_command`, a `cliCommand` that was ignored as malformed+ * `invalid_cli_command`, 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: two docs for one component+ * (`duplicate_component_doc`), a root reached through a symlink+ * (`symlinked_root`), a contribution file that cannot be read+ * (`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*//**diff --git a/packages/cli/api/integration/validateIntegration.doc.mjs b/packages/cli/api/integration/validateIntegration.doc.mjsindex 3d61249e7a..63d4df2ff3 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. 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; 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.',},],examples: [diff --git a/packages/cli/foundation/integrations/validate-contributions.mjs b/packages/cli/foundation/integrations/validate-contributions.mjsindex b69eb5c962..e4af769991 100644--- a/packages/cli/foundation/integrations/validate-contributions.mjs+++ b/packages/cli/foundation/integrations/validate-contributions.mjs@@ -76,6 +76,32 @@ export function issueWarning(code, message) {return {code, severity: 'warning', message};}+/** Issues `issueListed` made: listed in validate's `layout` report only. */+const LISTED = new WeakSet();++/**+ * A layout finding added after the last minor release: validate lists it, in+ * its `layout` report, but it is never an issue, so nothing counts it and+ * `integration check --strict` does not fail on it. A new failing finding+ * joins only in a minor release (architecture:cli-surface INV35).+ * @param {string} code+ * @param {string} message+ * @returns {Issue}+ */+export function issueListed(code, message) {+ const issue = issueWarning(code, message);+ LISTED.add(issue);+ return issue;+}++/**+ * Whether `issueListed` made this issue.+ * @param {Issue} issue+ */+export function isListedIssue(issue) {+ return LISTED.has(issue);+}+/*** Report the manifest keys this CLI does not know.*@@ -180,7 +206,7 @@ function checkRoots(resolved, issues, packageDir) {? 'replace the link with a real folder holding its files': `replace the link with the folder itself (move ${target}/ to ${shown}/), or set \`${kind}: './${realRoot}'\` in ${manifestName(resolved)}`;issues.push(- issueWarning(+ issueListed('symlinked_root',`Declared ${kind} root "${slash(path.relative(packageDir, root))}" is reached through the symlink "${shown}" (to "${target}"). Astryx follows it locally, but npm pack does not follow a symlinked folder, so the published package ships none of these files. Fix: ${fix}.`,),@@ -434,6 +460,8 @@ async function checkComponents(integration, issues) {}issues.push(issueError('invalid_component', `${error.message} ${fix}`));}+ /** @type {Set<string>} sources a case-only rename is reported for */+ const reportedSources = new Set();for (const [docPath, source] of files.caseMismatch) {const doc = path.basename(docPath);const renamed = `${source.slice(0, -'.tsx'.length)}${doc.slice(docStemOf(doc).length)}`;@@ -441,18 +469,24 @@ async function checkComponents(integration, issues) {const linux = `They pair on a case-insensitive disk (macOS, Windows) but not on Linux, where CI and most installs run`;const fix = `Fix: rename ${doc} to ${renamed}.`;// Where discovery still pairs the doc with its source (a- // case-insensitive disk), or the doc is hidden and lists nothing, the- // component works here: a warning, as validate exited 0 for it before.- if (componentDiscovery.isHiddenComponentDoc(docPath)) {+ // case-insensitive disk), the component works here: listed, as+ // validate passed it before. A hidden doc that does not pair leaves its+ // source without a doc, which the source check below reports as it+ // always has (architecture:cli-surface INV37).+ const pairs = componentDiscovery.integrationSourceForDoc(docPath) != null;+ const hidden = componentDiscovery.isHiddenComponentDoc(docPath);+ if (hidden && !pairs) continue;+ reportedSources.add(path.join(path.dirname(docPath), source));+ if (hidden) {issues.push(- issueWarning(+ issueListed('source_without_component_doc',`Hidden component doc "${shown}" and its source "${source}" differ only in letter case. ${linux}. ${fix}`,),);- } else if (componentDiscovery.integrationSourceForDoc(docPath) != null) {+ } else if (pairs) {issues.push(- issueWarning(+ issueListed('source_without_component_doc',`Component doc "${shown}" and its source "${source}" differ only in letter case. ${linux}, so there the component is missing. ${fix}`,),@@ -470,7 +504,7 @@ async function checkComponents(integration, issues) {const readName = path.basename(read);const ignoredNames = ignored.map(file => path.basename(file));issues.push(- issueWarning(+ issueListed('duplicate_component_doc',`Component "${docStemOf(readName)}" has ${ignored.length + 1} docs: ${[readName, ...ignoredNames].join(', ')}. Astryx reads ${readName} and ignores ${ignoredNames.join(' and ')}. Fix: delete ${ignoredNames.join(' and ')}, moving anything only ${ignored.length === 1 ? 'it says' : 'they say'} into ${readName}.`,),@@ -494,9 +528,7 @@ async function checkComponents(integration, issues) {continue;}// A doc whose name differs only in case is reported above.- if (files.caseMismatchSources.has(path.join(root, `${name}.tsx`))) {- continue;- }+ if (reportedSources.has(path.join(root, `${name}.tsx`))) continue;issues.push(issueWarning('source_without_component_doc',@@ -529,8 +561,6 @@ function docStemOf(file) {function componentDocFiles(root) {/** @type {Map<string, string>} doc path -> the source's real file name */const caseMismatch = new Map();- /** @type {Set<string>} */- const caseMismatchSources = new Set();/** @type {Array<{read: string, ignored: string[]}>} */const duplicates = [];/** @param {string} dir */@@ -568,7 +598,6 @@ function componentDocFiles(root) {)) {caseMismatch.set(full, other);- caseMismatchSources.add(path.join(dir, other));}}for (const docs of byStem.values()) {@@ -585,7 +614,7 @@ function componentDocFiles(root) {}};walk(root);- return {caseMismatch, caseMismatchSources, duplicates};+ return {caseMismatch, duplicates};}/**@@ -650,7 +679,7 @@ function checkUnreadableFiles(integration, issues) {} catch (err) {const code = String(/** @type {any} */ (err)?.code ?? 'unknown error');issues.push(- issueWarning(+ issueListed('unreadable_file',`Could not read "${shown}" (${code}), so Astryx cannot check it and npm pack fails on it. Fix: make it readable (chmod a+r ${shown}), or delete it if it does not belong in the package.`,),@@ -684,6 +713,29 @@ async function runContributionChecks(integration, issues) {* @returns {Promise<Issue[]>}*/export async function validateLoadedIntegration(loaded) {+ return (await validateLoadedIntegrationListed(loaded)).issues;+}++/**+ * Every contribution check, split: `issues` as validateLoadedIntegration+ * returns them, and `listed`, the layout findings validate lists in its+ * `layout` report without counting them.+ * @param {LoadedIntegration} loaded+ * @returns {Promise<{issues: Issue[], listed: Issue[]}>}+ */+export async function validateLoadedIntegrationListed(loaded) {+ const all = await allLoadedIntegrationIssues(loaded);+ return {+ issues: all.filter(issue => !LISTED.has(issue)),+ listed: all.filter(issue => LISTED.has(issue)),+ };+}++/**+ * @param {LoadedIntegration} loaded+ * @returns {Promise<Issue[]>}+ */+async function allLoadedIntegrationIssues(loaded) {/** @type {Issue[]} */const issues = [];if (!loaded || typeof loaded !== 'object') return issues;diff --git a/packages/cli/foundation/response/response-types.doc.mjs b/packages/cli/foundation/response/response-types.doc.mjsindex 7de1a7110a..76ae5d02fb 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. 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), 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).',},{value: 'integration.template-conflicts',diff --git a/packages/cli/test/integration-check-failures.json b/packages/cli/test/integration-check-failures.jsonindex 42b6b539ce..709e61a360 100644--- a/packages/cli/test/integration-check-failures.json+++ b/packages/cli/test/integration-check-failures.json@@ -20,7 +20,6 @@"default_mismatch","doc_fluff","doc_types_skipped",- "duplicate_component_doc","duplicate_doc","duplicate_prop","duplicate_provider",@@ -51,7 +50,6 @@"missing_template_replacement_target","multiple_manifests","no_package",- "no_provider_id","not_in_code","not_in_doc","orphan_doc_overlay",@@ -64,7 +62,6 @@"source_without_component_doc","source_without_template_doc","stray_doc_pointer",- "symlinked_root","template_id_conflict","type_mismatch","unknown_field",@@ -73,7 +70,6 @@"unreachable_contribution","unreachable_scan_truncated","unread_theme_folder",- "unreadable_file","unreadable_folder","unreadable_root","wrong_type"