An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): integration checks catch pairing, root and package.json mistakes, and stop crashing on them (#7777)
Joey1d247e4cc928
diff --git a/.changeset/cli-integration-check-gaps.md b/.changeset/cli-integration-check-gaps.mdnew file mode 100644index 0000000000..36ef504da7--- /dev/null+++ b/.changeset/cli-integration-check-gaps.md@@ -0,0 +1,14 @@+---+'@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:++- 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.+- 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.++@josephfarinadiff --git a/packages/cli/api/docs/_adapter.mjs b/packages/cli/api/docs/_adapter.mjsindex e07f9e0a30..c695676595 100644--- a/packages/cli/api/docs/_adapter.mjs+++ b/packages/cli/api/docs/_adapter.mjs@@ -1146,6 +1146,14 @@ function packageCatalog(integration, discovered) {* @returns {Promise<Array<{severity: 'warning', message: string}>>}*/export async function packageComponentLinkProblems(integration, discovered) {+ // A package with no provider id (its manifest's, else its name) links+ // nothing, as on the read path: its text reads as written, so there is+ // nothing to report.+ try {+ normalizeProviderId(integration.providerId ?? integration.name);+ } catch {+ return [];+ }const catalog = packageCatalog(integration, discovered);return (await componentLinkProblems(catalog, integration.name)).map(message => ({severity: /** @type {const} */ ('warning'), message}),@@ -1176,11 +1184,15 @@ async function componentLinkProblems(catalog, owner) {// The components check reports a doc that does not load.continue;}- const linked = await linkComponentDoc(- catalog,- componentLinkProvider(record.package, record.providerId),- doc,- );+ let provider;+ try {+ provider = componentLinkProvider(record.package, record.providerId);+ } catch {+ // An owner that is not a provider id links nothing (as on the read+ // path); its text reads as written.+ continue;+ }+ const linked = await linkComponentDoc(catalog, provider, doc);const name = typeof doc?.name === 'string' ? doc.name : record.name;for (const problem of linked.problems) {problems.push(diff --git a/packages/cli/api/integration/authoring-checks.mjs b/packages/cli/api/integration/authoring-checks.mjsindex 0dfcbeb0bc..81866b02c5 100644--- a/packages/cli/api/integration/authoring-checks.mjs+++ b/packages/cli/api/integration/authoring-checks.mjs@@ -51,6 +51,8 @@ import {validateInstalledIntegration,validateLocalIntegration,} from './validate-integration.mjs';+import {rootProblem} from '../../foundation/integrations/validate-contributions.mjs';+import {normalizeProviderId} from '../../foundation/identity/provider-identity.mjs';/** @param {string} value */export function shellArg(value) {@@ -58,15 +60,61 @@ export function shellArg(value) {return `'${value.replace(/'/g, `'\\''`)}'`;}+/**+ * The provider ID a package without a name is checked under: a valid bare+ * package name no published package can hold (npm names are lowercase).+ */+const UNNAMED_PROVIDER = 'astryx-unnamed-local-package';++/**+ * A message as the package sees it: the stand-in provider ID gone, its docs+ * named by their path in the package.+ * @param {string} message+ */+function unnamedShown(message) {+ return message+ .split(`${UNNAMED_PROVIDER}/`)+ .join('')+ .split(UNNAMED_PROVIDER)+ .join('this package');+}+/*** Resolve one local or installed integration for an authoring check.* @param {string | undefined} pkg* @param {string} cwd*/async function resolveIntegration(pkg, cwd) {- return pkg- ? validateInstalledIntegration(pkg, cwd)- : validateLocalIntegration(cwd);+ const resolved = pkg+ ? await validateInstalledIntegration(pkg, cwd)+ : await validateLocalIntegration(cwd);+ const integration = resolved.found ? resolved.integration : undefined;+ if (!integration) return resolved;+ // A root that is not a readable folder is reported in the issues; the+ // checks read nothing from it rather than fail on it.+ /** @type {typeof integration & {__unnamed?: boolean}} */+ const usable = {...integration};+ // The provider ID readers key the package on: the manifest's providerId,+ // else its name. A package with neither (validate warned about it) is+ // still checked; the docs check names its docs under a stand-in ID.+ try {+ usable.providerId = normalizeProviderId(+ integration.__declaredProviderId ?? integration.name,+ );+ } catch {+ usable.__unnamed = true;+ }+ for (const kind of /** @type {const} */ ([+ 'components',+ 'templates',+ 'codemods',+ 'docs',+ 'themes',+ ])) {+ const root = usable[kind];+ if (root != null && rootProblem(root)) usable[kind] = undefined;+ }+ return {...resolved, integration: usable};}/**@@ -387,8 +435,20 @@ export async function integrationDocConflicts(pkg, options = {}) {};}+ // The docs tree names a package's docs by its provider ID, which a+ // package.json without a name does not give: its docs are checked under a+ // stand-in ID, which no message names.+ const unnamed = /** @type {{__unnamed?: boolean}} */ (resolved.integration)+ .__unnamed;+ const docsIntegration = unnamed+ ? {+ ...resolved.integration,+ name: UNNAMED_PROVIDER,+ providerId: UNNAMED_PROVIDER,+ }+ : resolved.integration;const [discovered, builtinTopics] = await Promise.all([- discoverIntegrationDocs(resolved.integration),+ discoverIntegrationDocs(docsIntegration),Promise.resolve(discoverBuiltinTopics()),]);const {records, errors} = discovered;@@ -458,27 +518,40 @@ export async function integrationDocConflicts(pkg, options = {}) {// its docs (spec:AST-046, spec:AST-047).if (errors.length === 0) {for (const {severity, message} of await packageDocsProblems(- /** @type {{name: string}} */ (resolved.integration),+ /** @type {{name: string}} */ (docsIntegration),discovered,)) {- issues.push({code: 'invalid_doc_graph', severity, message});+ issues.push({+ code: 'invalid_doc_graph',+ severity,+ message: unnamedShown(message),+ });}// A reference block includes content rather than linking to it, so one// that cannot include what it names loses that content for every reader:// an error, where a link that names no doc still prints as written.for (const message of await packageReferenceProblems(- /** @type {{name: string}} */ (resolved.integration),+ /** @type {{name: string}} */ (docsIntegration),discovered,)) {- issues.push({code: 'invalid_doc_reference', severity: 'error', message});+ issues.push({+ code: 'invalid_doc_reference',+ severity: 'error',+ message: unnamedShown(message),+ });}// One fact has one owner: a passage two topics repeat goes stale in one// of them. Each is listed and is a warning (architecture:cli-surface// DEC-8), so `integration check --strict` fails until it is fixed;// `doctor integration docs` keeps its exit code, as it fails on errors.- copiedPassages.push(...(await integrationCopiedPassages(discovered)));+ copiedPassages.push(+ ...(await integrationCopiedPassages(discovered)).map(passage => ({+ ...passage,+ message: unnamedShown(passage.message),+ })),+ );for (const {message} of copiedPassages) {issues.push({code: 'copied_passage', severity: 'warning', message});}@@ -488,6 +561,7 @@ export async function integrationDocConflicts(pkg, options = {}) {...(await integrationFluff(discovered)).map(each => ({...each,file: fromPackage(each.file),+ message: unnamedShown(each.message),})),);for (const {message} of fluff) {diff --git a/packages/cli/api/integration/pack-check.mjs b/packages/cli/api/integration/pack-check.mjsindex 11277935ee..ad8e4e0d50 100644--- a/packages/cli/api/integration/pack-check.mjs+++ b/packages/cli/api/integration/pack-check.mjs@@ -26,6 +26,7 @@ import {fileURLToPath} from 'node:url';import {spawnSync} from 'node:child_process';import {assertWithin} from '../../foundation/fs/path-safety.mjs';import {resolvePackageDir} from '../../foundation/integrations/integrations.mjs';+import {rootProblem} from '../../foundation/integrations/validate-contributions.mjs';import {componentReplacesCliProblem,docsTreeCliProblem,@@ -1265,7 +1266,13 @@ export async function integrationPackCheck(options = {}) {// ── Phase 1: structure validation ──const localResult = await validateLocalIntegration(cwd);/** @type {Issue[]} */- const issues = [...localResult.issues];+ 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,+ );if (!localResult.found || !localResult.integration) {return emptyReceipt(pkgName, [@@ -1314,6 +1321,8 @@ export async function integrationPackCheck(options = {}) {);}for (const root of fileInv.roots) {+ // A root that is not a readable folder has its own issue.+ if (rootProblem(/** @type {string} */ (loaded[root.kind]))) continue;if (root.files.length === 0) {issues.push(error(diff --git a/packages/cli/api/integration/pack-check.test.mjs b/packages/cli/api/integration/pack-check.test.mjsindex a6f157fc9f..39e3e39d08 100644--- a/packages/cli/api/integration/pack-check.test.mjs+++ b/packages/cli/api/integration/pack-check.test.mjs@@ -1919,6 +1919,24 @@ describe('integrationPackCheck', () => {expect(sourceWarnings[0].message).toContain('stray.tsx');});+ it('fails on a package.json npm cannot pack, which validate only warns about', async () => {+ writePackage({files: ['astryx.integration.mjs', 'themes']});+ const packageFile = path.join(tmpDir, 'package.json');+ const pkg = JSON.parse(fs.readFileSync(packageFile, 'utf-8'));+ delete pkg.name;+ fs.writeFileSync(packageFile, `${JSON.stringify(pkg, null, 2)}\n`);++ const result = await integrationPackCheck({cwd: tmpDir});++ expect(result.data.packable).toBe(false);+ expect(+ result.data.issues.map(issue => [issue.code, issue.severity]),+ ).toEqual([+ ['invalid_package_json', 'error'],+ ['pack_failed', 'error'],+ ]);+ });+it('cleans up its scratch consumer when npm pack fails', async () => {writePackage({files: ['astryx.integration.mjs', 'themes'],diff --git a/packages/cli/api/integration/validate-integration-case-disk.test.mjs b/packages/cli/api/integration/validate-integration-case-disk.test.mjsnew file mode 100644index 0000000000..7293297e36--- /dev/null+++ b/packages/cli/api/integration/validate-integration-case-disk.test.mjs@@ -0,0 +1,81 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file A component doc whose file name differs from its source only in+ * letter case, on a case-insensitive disk (macOS, Windows), where discovery+ * still pairs the two: a warning naming the rename, not an error. The disk is+ * simulated by finding the doc's source case-insensitively.+ */++import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';+import * as fs from 'node:fs';+import * as path from 'node:path';++vi.mock(+ '../../foundation/discovery/component-discovery.mjs',+ async importOriginal => {+ const original =+ /** @type {typeof import('../../foundation/discovery/component-discovery.mjs')} */ (+ await importOriginal()+ );+ return {+ ...original,+ /** @param {string} docPath */+ integrationSourceForDoc: docPath => {+ const dir = path.dirname(docPath);+ const want = `${path+ .basename(docPath)+ .replace(/\.doc\.(ts|mjs|js)$/u, '')}.tsx`.toLowerCase();+ const found = fs+ .readdirSync(dir)+ .find(name => name.toLowerCase() === want);+ return found ? path.join(dir, found) : null;+ },+ };+ },+);++const {validateLocalIntegration} = await import('./validate-integration.mjs');++/** @type {string} */+let tmpDir;++beforeEach(() => {+ tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-case-disk-'));+});++afterEach(() => {+ fs.rmSync(tmpDir, {recursive: true, force: true});+});++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 () => {+ 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', 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 {issues} = await validateLocalIntegration(tmpDir);+ expect(issues).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.',+ },+ ]);+ });+});diff --git a/packages/cli/api/integration/validate-integration-gaps.test.mjs b/packages/cli/api/integration/validate-integration-gaps.test.mjsnew file mode 100644index 0000000000..3b2a0f56e8--- /dev/null+++ b/packages/cli/api/integration/validate-integration-gaps.test.mjs@@ -0,0 +1,659 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Package mistakes `astryx doctor integration validate` and+ * `astryx integration check` used to pass, crash on, or describe badly: names+ * that differ from file names, ids readers cannot take, duplicate and+ * case-mismatched docs, symlinked or absolute roots, a root that is a file, a+ * package.json missing what npm needs, manifest key typos, docs and manifests+ * with no default export, and theme descriptors named for built output. Each+ * finding carries a `Fix:` that holds when followed.+ *+ * Temp dirs live under the repo root, as in validate-integration.test.mjs.+ */++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';++let tmpDir;+let copies = 0;++beforeEach(() => {+ tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-validate-gaps-'));+});++afterEach(() => {+ fs.rmSync(tmpDir, {recursive: true, force: true});+});++const MANIFEST = 'astryx.integration.mjs';+const THEME_TYPE =+ "/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\n";++/** @param {Record<string, unknown>} roots */+const manifest = roots => `export default ${JSON.stringify(roots)};\n`;+/** @param {string} name */+const componentDoc = name =>+ `export default {type: 'component', name: '${name}', displayName: '${name}', usage: {description: '${name}.'}, props: []};\n`;+/** @param {string} name */+const componentSource = name => `export function ${name}() { return null; }\n`;+/** @param {string} name */+const topic = name =>+ `export default ${JSON.stringify({+ type: 'generic',+ name,+ title: name,+ description: `The ${name} topic.`,+ sections: [{title: 'Overview', content: [{type: 'prose', text: name}]}],+ })};\n`;+/** @param {string} name */+const templateDoc = name =>+ `export default {type: 'block', name: '${name}', displayName: '${name}', aspectRatio: 1};\n`;+const templateSource = 'export default function Block() { return null; }\n';++/**+ * @param {Record<string, string>} files package-relative path -> contents+ * @param {Record<string, unknown>} [pkg] package.json+ * @returns {string} the package directory+ */+function writePackage(files, pkg = {name: '@acme/kit', version: '1.0.0'}) {+ const dir = path.join(tmpDir, 'pkg');+ fs.mkdirSync(dir, {recursive: true});+ fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify(pkg));+ for (const [file, contents] of Object.entries(files)) {+ fs.mkdirSync(path.dirname(path.join(dir, file)), {recursive: true});+ fs.writeFileSync(path.join(dir, file), contents);+ }+ return dir;+}++/**+ * Carry out a fix on a fresh copy of the package.+ * @param {string} dir+ * @param {{move?: Array<[string, string]>, write?: Record<string, string>, remove?: string[]}} steps+ */+function follow(dir, {move = [], write = {}, remove = []}) {+ copies += 1;+ const copy = path.join(tmpDir, `followed-${copies}`);+ fs.cpSync(dir, copy, {recursive: true, verbatimSymlinks: true});+ for (const file of remove) {+ fs.rmSync(path.join(copy, file), {recursive: true, force: true});+ }+ for (const [from, to] of move) {+ fs.mkdirSync(path.dirname(path.join(copy, to)), {recursive: true});+ fs.renameSync(path.join(copy, from), path.join(copy, to));+ }+ for (const [file, contents] of Object.entries(write)) {+ fs.mkdirSync(path.dirname(path.join(copy, file)), {recursive: true});+ fs.writeFileSync(path.join(copy, file), contents);+ }+ return copy;+}++/** @param {string} dir */+async function issuesOf(dir) {+ return (await validateLocalIntegration(dir)).issues;+}++/**+ * The one issue with this code, which the test is about.+ * @param {Array<{code: string, message: string}>} issues+ * @param {string} code+ */+function only(issues, code) {+ const found = issues.filter(issue => issue.code === code);+ expect(found).toHaveLength(1);+ return found[0].message;+}++describe('a name that differs from its file name', () => {+ it('accepts a kebab-case file whose doc names the export it holds', async () => {+ const dir = writePackage({+ [MANIFEST]: manifest({components: './components'}),+ 'components/acme-widget.doc.mjs': componentDoc('AcmeWidget'),+ 'components/acme-widget.tsx': componentSource('AcmeWidget'),+ });++ expect(await issuesOf(dir)).toEqual([]);+ });++ it('leaves a doc topic named differently from its file alone: the code does not contradict it', async () => {+ const dir = writePackage({+ [MANIFEST]: manifest({docs: './docs'}),+ 'docs/deploying.doc.mjs': topic('deploy'),+ });++ expect(await issuesOf(dir)).toEqual([]);+ });++ it('leaves a template name alone: it is the display title', async () => {+ const dir = writePackage({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/account-card.doc.mjs': templateDoc('Account card'),+ 'templates/account-card.tsx': templateSource,+ });++ expect(await issuesOf(dir)).toEqual([]);+ });+});++describe('template ids', () => {+ it('leaves an id with spaces alone: it is naming policy, not a contradiction', async () => {+ const dir = writePackage({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/AI Chat Conversation.doc.mjs': templateDoc(+ 'AI Chat Conversation',+ ),+ 'templates/AI Chat Conversation.tsx': templateSource,+ });++ expect(await issuesOf(dir)).toEqual([]);+ });+});++describe('component doc files', () => {+ it('warns about two docs for one component and names the one read', async () => {+ 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 message = only(await issuesOf(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([]);+ });++ it('gives one finding for a doc whose name differs from its source only in case', async () => {+ const dir = writePackage({+ [MANIFEST]: manifest({components: './components'}),+ 'components/Acmewidget.doc.mjs': componentDoc('AcmeWidget'),+ 'components/AcmeWidget.tsx': componentSource('AcmeWidget'),+ });++ const issues = await issuesOf(dir);+ expect(issues).toHaveLength(1);+ expect(issues[0]).toEqual({+ code: 'invalid_component',+ severity: 'error',+ 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 here the component is missing. Fix: rename Acmewidget.doc.mjs to AcmeWidget.doc.mjs.',+ });++ // Through a temporary name, so a case-insensitive disk renames it too.+ const fixed = follow(dir, {+ move: [+ ['components/Acmewidget.doc.mjs', 'components/tmp.doc.mjs'],+ ['components/tmp.doc.mjs', 'components/AcmeWidget.doc.mjs'],+ ],+ });+ expect(await issuesOf(fixed)).toEqual([]);+ });+});++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 () => {+ const dir = writePackage({+ [MANIFEST]: manifest({components: './components'}),+ 'components/Acmewidget.doc.mjs': componentDoc('AcmeWidget').replace(+ "type: 'component',",+ "type: 'component',\n hidden: true,",+ ),+ 'components/AcmeWidget.tsx': componentSource('AcmeWidget'),+ });++ 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.',+ },+ ]);+ });+});++describe('roots', () => {+ it('warns 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'),+ 'real-components/AcmeWidget.tsx': componentSource('AcmeWidget'),+ });+ fs.symlinkSync('real-components', path.join(dir, 'components'));++ const issues = await issuesOf(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.',+ );++ const fixed = follow(dir, {+ remove: ['components'],+ move: [['real-components', 'components']],+ });+ expect(await issuesOf(fixed)).toEqual([]);+ });++ it('says an absolute root inside the package must be relative', async () => {+ const dir = writePackage({+ 'docs/deploying.doc.mjs': topic('deploying'),+ });+ fs.writeFileSync(+ path.join(dir, MANIFEST),+ manifest({docs: path.join(dir, 'docs')}),+ );++ const issues = await issuesOf(dir);+ expect(issues).toEqual([+ {+ code: 'root_outside_package',+ severity: 'error',+ message: `The docs root "${path.join(dir, 'docs')}" is an absolute path, so Astryx reads nothing from it: a root is relative to the package, so it resolves the same wherever the package is installed. Fix: set \`docs: './docs'\` in astryx.integration.mjs.`,+ },+ ]);+ expect(issues[0].message).not.toContain('outside');++ const fixed = follow(dir, {+ write: {[MANIFEST]: manifest({docs: './docs'})},+ });+ expect(await issuesOf(fixed)).toEqual([]);+ });++ it('reports a root that is a file from every check, without crashing', async () => {+ const dir = writePackage({+ [MANIFEST]: manifest({+ components: './components/AcmeWidget.tsx',+ templates: './templates/account-card.tsx',+ docs: './docs/deploying.doc.mjs',+ }),+ 'components/AcmeWidget.tsx': componentSource('AcmeWidget'),+ 'templates/account-card.tsx': templateSource,+ 'docs/deploying.doc.mjs': topic('deploying'),+ });++ const result = await integrationCheck({cwd: dir});+ expect(result.data.checks.map(check => check.check)).toEqual([+ 'validate',+ 'components',+ 'templates',+ 'docs',+ ]);+ for (const check of result.data.checks) {+ const codes = check.response.data.issues+ .filter(issue => issue.severity === 'error')+ .map(issue => issue.code);+ expect(codes).toEqual(['invalid_root', 'invalid_root', 'invalid_root']);+ }+ });+});++describe('package.json', () => {+ it('warns about a missing name and keeps checking, without crashing any check', async () => {+ const dir = writePackage(+ {+ [MANIFEST]: manifest({components: './components', docs: './docs'}),+ 'components/AcmeWidget.doc.mjs': componentDoc('AcmeWidget'),+ 'docs/deploying.doc.mjs': topic('deploying'),+ },+ {version: '1.0.0'},+ );++ const result = await integrationCheck({cwd: dir});+ 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'],+ ]);+ }+ 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.',+ );+ expect(result.data.failed).toBe(true);+ });++ it('still compares documented props for a package without a name', async () => {+ const dir = writePackage(+ {+ [MANIFEST]: manifest({components: './components'}),+ 'components/AcmeWidget.doc.mjs':+ "export default {type: 'component', name: 'AcmeWidget', displayName: 'AcmeWidget', usage: {description: 'A widget.'}, props: [{name: 'label', type: 'string', description: 'Text.'}]};\n",+ 'components/AcmeWidget.tsx':+ 'export function AcmeWidget(props: {title: string}) { return null; }\n',+ },+ {version: '1.0.0'},+ );++ const result = await integrationCheck({cwd: dir, strict: true});+ const components = result.data.checks.find(+ check => check.check === 'components',+ );+ 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');+ if (propDrift.status === 'skipped') {+ // No TypeScript here: --strict names the skipped comparison.+ expect(failures).toContain('prop_drift_skipped');+ } else {+ expect(propDrift.findings.map((/** @type {any} */ f) => f.kind)).toEqual(+ expect.arrayContaining(['not_in_code', 'not_in_doc']),+ );+ }+ });++ it('completes --strict for a package without a name whose component docs hold links, reporting none', async () => {+ const dir = writePackage(+ {+ [MANIFEST]: manifest({components: './components'}),+ 'components/AcmeWidget.doc.mjs':+ "export default {type: 'component', name: 'AcmeWidget', displayName: 'AcmeWidget', usage: {description: 'Read {@link generic:x} first.'}, props: []};\n",+ 'components/AcmeWidget.tsx': componentSource('AcmeWidget'),+ },+ {version: '1.0.0'},+ );++ const result = await integrationCheck({cwd: dir, strict: true});+ const components = result.data.checks.find(+ check => check.check === 'components',+ );+ expect(components?.response.data.issues.map(issue => issue.code)).toEqual([+ 'invalid_package_json',+ ]);+ expect(+ result.data.failures.filter(+ failure => failure.code === 'invalid_doc_graph',+ ),+ ).toEqual([]);+ });++ it('checks the docs of a package without a name, naming them by path', async () => {+ const dir = writePackage(+ {+ [MANIFEST]: manifest({docs: './docs'}),+ 'docs/deploying.doc.mjs': topic('deploying').replace(+ '"text":"deploying"',+ '"text":"See {@link generic:no-such-topic}."',+ ),+ },+ {version: '1.0.0'},+ );++ const result = await integrationCheck({cwd: dir});+ const docs = result.data.checks.find(check => check.check === 'docs');+ const messages =+ 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(+ /^deploying § overview: "generic:no-such-topic" names no doc\./u,+ );+ });++ it.each([+ ['acme kit'],+ ['_acme'],+ ['acme/kit'],+ ['-acme'],+ ['@acme/-kit'],+ ['~acme'],+ ])(+ 'warns that no provider ID can be derived from the name %s, and keeps checking',+ async name => {+ const dir = writePackage(+ {+ [MANIFEST]: manifest({components: './components'}),+ 'components/AcmeWidget.doc.mjs': componentDoc('AcmeWidget'),+ },+ {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(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.`,+ );+ expect(issues[0].message).not.toContain('npm cannot pack');+ const result = await integrationCheck({cwd: dir});+ expect(result.data.checks.every(check => check.response.type)).toBe(true);+ },+ );++ it('leaves the provider ID to invalid_manifest when the manifest does not load', async () => {+ const dir = writePackage(+ {+ [MANIFEST]: manifest({providerId: '@acme/kit', issuesUrl: 42}),+ },+ {name: '-acme', version: '1.0.0'},+ );++ const issues = await issuesOf(dir);+ expect(issues.map(issue => issue.code)).toEqual(['invalid_manifest']);+ });++ it('derives the provider ID from the manifest when the name cannot give one', async () => {+ const dir = writePackage(+ {+ [MANIFEST]: manifest({+ providerId: '@acme/kit',+ components: './components',+ }),+ 'components/AcmeWidget.doc.mjs': componentDoc('AcmeWidget'),+ 'components/AcmeWidget.tsx': componentSource('AcmeWidget'),+ },+ {name: '@acme/_kit', version: '1.0.0'},+ );++ expect(await issuesOf(dir)).toEqual([]);+ expect((await integrationCheck({cwd: dir, strict: true})).data.failed).toBe(+ false,+ );+ });++ it('checks a package without a name whose root is a file, without crashing', async () => {+ const dir = writePackage(+ {+ [MANIFEST]: manifest({+ templates: './templates/account-card.tsx',+ docs: './docs/deploying.doc.mjs',+ }),+ 'templates/account-card.tsx': templateSource,+ 'docs/deploying.doc.mjs': topic('deploying'),+ },+ {version: '1.0.0'},+ );++ const result = await integrationCheck({cwd: dir});+ for (const check of result.data.checks) {+ expect(+ check.response.data.issues+ .filter(issue => issue.severity === 'error')+ .map(issue => issue.code),+ ).toEqual(['invalid_root', 'invalid_root']);+ }+ });++ it('checks links under the manifest providerId when the name gives none', async () => {+ const linked = (/** @type {string} */ name, /** @type {string} */ text) =>+ `export default ${JSON.stringify({+ type: 'generic',+ name,+ title: name,+ description: `The ${name} topic.`,+ sections: [{title: 'Overview', content: [{type: 'prose', text}]}],+ })};\n`;+ const dir = writePackage(+ {+ [MANIFEST]: manifest({+ providerId: '@acme/kit',+ components: './components',+ docs: './docs',+ }),+ 'components/AcmeWidget.doc.mjs':+ "export default {type: 'component', name: 'AcmeWidget', displayName: 'AcmeWidget', usage: {description: 'Read {@link generic:no-such-topic}.'}, props: []};\n",+ 'components/AcmeWidget.tsx': componentSource('AcmeWidget'),+ 'docs/deploying.doc.mjs': linked(+ 'deploying',+ 'See {@link @acme/kit:generic:other}.',+ ),+ 'docs/other.doc.mjs': linked('other', 'The other topic.'),+ },+ {name: '@acme/_kit', version: '1.0.0'},+ );++ const result = await integrationCheck({cwd: dir});+ const issuesOf = (/** @type {string} */ name) =>+ result.data.checks.find(check => check.check === name)?.response.data+ .issues ?? [];+ const componentLinks = issuesOf('components').filter(+ issue => issue.code === 'invalid_doc_graph',+ );+ expect(componentLinks).toHaveLength(1);+ expect(componentLinks[0].message).toContain('no-such-topic');+ expect(+ issuesOf('docs').filter(issue => issue.code === 'invalid_doc_graph'),+ ).toEqual([]);+ });++ it('fails only --strict on a missing name when nothing else is wrong', async () => {+ const dir = writePackage(+ {+ [MANIFEST]: manifest({docs: './docs'}),+ 'docs/deploying.doc.mjs': topic('deploying'),+ },+ {version: '1.0.0'},+ );++ expect((await integrationCheck({cwd: dir})).data.failed).toBe(false);+ expect((await integrationCheck({cwd: dir, strict: true})).data.failed).toBe(+ true,+ );+ });++ it('warns about a missing version and still checks the rest', async () => {+ const dir = writePackage(+ {+ [MANIFEST]: manifest({components: './components'}),+ 'components/AcmeWidget.doc.mjs': componentDoc('AcmeWidget'),+ },+ {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(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.',+ );+ });++ it('asks no version of a private package', async () => {+ const dir = writePackage(+ {[MANIFEST]: manifest({docs: './docs'}), 'docs/a.doc.mjs': topic('a')},+ {name: '@acme/kit', private: true},+ );++ expect(await issuesOf(dir)).toEqual([]);+ });+});++describe('unreadable files and theme names', () => {+ const asRoot = process.getuid?.() === 0;++ it.skipIf(asRoot)(+ 'reports a contribution file it cannot read, which npm pack would fail on',+ async () => {+ const dir = writePackage({+ [MANIFEST]: manifest({components: './components'}),+ 'components/AcmeWidget.doc.mjs': componentDoc('AcmeWidget'),+ 'components/AcmeWidget.tsx': componentSource('AcmeWidget'),+ });+ 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(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([]);+ },+ );++ it.skipIf(asRoot)(+ 'ignores an unreadable file no reader and no pack reads, such as .DS_Store',+ async () => {+ const dir = writePackage({+ [MANIFEST]: manifest({components: './components'}),+ 'components/AcmeWidget.doc.mjs': componentDoc('AcmeWidget'),+ 'components/AcmeWidget.tsx': componentSource('AcmeWidget'),+ 'components/.DS_Store': 'x',+ 'components/notes.txt': 'x',+ });+ const files = ['.DS_Store', 'notes.txt'].map(name =>+ path.join(dir, 'components', name),+ );+ for (const file of files) fs.chmodSync(file, 0);+ try {+ expect(await issuesOf(dir)).toEqual([]);+ } finally {+ for (const file of files) fs.chmodSync(file, 0o644);+ }+ },+ );++ const themeDoc = `${THEME_TYPE}export default {type: 'theme', name: 'ocean', displayName: 'Ocean', description: 'A theme.', maintained: true};\n`;+ /** @param {string} name */+ const themeSource = name =>+ `import {defineTheme} from '@astryxdesign/core/theme';\nexport const oceanTheme = defineTheme({\n name: '${name}',\n});\n`;++ it('accepts a theme that names itself differently from its folder', async () => {+ const dir = writePackage({+ [MANIFEST]: manifest({themes: './themes'}),+ 'themes/ocean/oceanTheme.doc.mjs': themeDoc,+ 'themes/ocean/oceanTheme.ts': themeSource('deep-sea'),+ });++ expect(+ (await issuesOf(dir)).filter(issue => issue.code === 'invalid_theme'),+ ).toEqual([]);+ });++ it('leaves a theme name it can only know by building alone', async () => {+ const dir = writePackage({+ [MANIFEST]: manifest({themes: './themes'}),+ 'themes/ocean/oceanTheme.doc.mjs': themeDoc,+ 'themes/ocean/oceanTheme.ts':+ "import {defineTheme} from '@astryxdesign/core/theme';\nconst name = 'sea';\nexport const oceanTheme = defineTheme({name});\n",+ });++ expect(+ (await issuesOf(dir)).filter(issue => issue.code === 'invalid_theme'),+ ).toEqual([]);+ });+});diff --git a/packages/cli/api/integration/validate-integration.mjs b/packages/cli/api/integration/validate-integration.mjsindex b72f807ead..16f498984b 100644--- a/packages/cli/api/integration/validate-integration.mjs+++ b/packages/cli/api/integration/validate-integration.mjs@@ -34,6 +34,7 @@import * as fs from 'node:fs';import * as path from 'node:path';import {assertWithin} from '../../foundation/fs/path-safety.mjs';+import {normalizeProviderId} from '../../foundation/identity/provider-identity.mjs';import {integrationDocTypes} from '../docs/_adapter.mjs';import {integrationDocConsistency} from '../../foundation/discovery/doc-consistency.mjs';import {@@ -99,6 +100,14 @@ function findNearestPackageJson(cwd) {}}+const ROOT_KINDS = /** @type {const} */ ([+ 'components',+ 'templates',+ 'codemods',+ 'docs',+ 'themes',+]);+const UNREACHABLE_SCAN_LIMIT = 5_000;const UNREACHABLE_SKIP_DIRS = new Set(['node_modules',@@ -148,27 +157,51 @@ function unreadThemeFolderIssues(packageDir, loaded) {** @param {string} packageDir* @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration} loaded+ * @param {string[]} [reported] folders whose files another issue already covers* @returns {Promise<Issue[]>}*/-async function findUnreachableContributionIssues(packageDir, loaded) {+async function findUnreachableContributionIssues(+ packageDir,+ loaded,+ reported = [],+) {+ // A root that is not a readable folder holds nothing: a fix must never+ // send a file into it.+ const usable = {...loaded};+ for (const kind of ROOT_KINDS) {+ const root = usable[kind];+ if (root != null && rootProblem(root)) usable[kind] = undefined;+ }+ // Every declared root is skipped, readable or not: one that cannot be read+ // has its own issue.const roots = /** @type {string[]} */ (- [- loaded.components,- loaded.templates,- loaded.codemods,- loaded.docs,- loaded.themes,- ].filter(Boolean)+ ROOT_KINDS.map(kind => loaded[kind]).filter(Boolean));+ // A folder a symlinked root points at is read through that root.+ const realRoots = roots.map(root => {+ try {+ return fs.realpathSync(root);+ } catch {+ return root;+ }+ });/** @type {Issue[]} */const issues = [];- const context = createFixContext(packageDir, loaded);+ const context = createFixContext(packageDir, usable);let scanned = 0;let truncated = false;/** @param {string} dir */async function walk(dir) {if (roots.some(root => pathIsInside(dir, root))) return;+ if (reported.some(folder => pathIsInside(dir, folder))) return;+ let realDir = dir;+ try {+ realDir = fs.realpathSync(dir);+ } catch {+ // Unreadable: reported below.+ }+ if (realRoots.some(root => pathIsInside(realDir, root))) return;let entries;try {entries = fs@@ -301,9 +334,36 @@ async function validateAtPackageDir(return result;}- /** @param {string | null | undefined} value */- const resolveRoot = (value, kind = 'contribution root') => {+ /** @type {string[]} absolute roots inside the package */+ const absoluteRoots = [];+ /**+ * @param {string | null | undefined} value+ * @param {string} key the manifest key that declares it+ */+ const resolveRoot = (value, key, kind = 'contribution root') => {if (value == null) return undefined;+ if (path.isAbsolute(value)) {+ // An absolute root names this machine's disk, which no install shares,+ // even when it happens to point inside the package.+ const inside = path.relative(packageDir, value);+ const relative =+ inside === '' || (!inside.startsWith('..') && !path.isAbsolute(inside))+ ? `./${inside.split(path.sep).join('/')}`.replace(/\/$/u, '')+ : null;+ // The code an absolute root has always carried, reworded.+ result.issues.push(+ error(+ 'root_outside_package',+ `The ${key} root "${value}" is an absolute path, so Astryx reads nothing from it: a root is relative to the package, so it resolves the same wherever the package is installed.` ++ (relative+ ? ` Fix: set \`${key}: '${relative === './' ? '.' : relative}'\` in ${path.basename(manifestFile)}.`+ : ` It also points outside the package. Fix: move the files into the package and set \`${key}\` to their folder relative to package.json, such as './${key}'.`),+ ),+ );+ // Its files are reported through this issue, not one by one.+ if (relative) absoluteRoots.push(path.resolve(value));+ return undefined;+ }try {return assertWithin(value, packageDir, {label: kind});} catch {@@ -320,11 +380,11 @@ async function validateAtPackageDir(const loaded = {name: identity.name,version: identity.version,- components: resolveRoot(manifest.components),- templates: resolveRoot(manifest.templates),- codemods: resolveRoot(manifest.codemods),- docs: resolveRoot(manifest.docs),- themes: resolveRoot(manifest.themes),+ components: resolveRoot(manifest.components, 'components'),+ templates: resolveRoot(manifest.templates, 'templates'),+ codemods: resolveRoot(manifest.codemods, 'codemods'),+ docs: resolveRoot(manifest.docs, 'docs'),+ themes: resolveRoot(manifest.themes, 'themes'),issuesUrl: manifest.issuesUrl,agentDocs: manifest.agentDocs,cliCommand: manifest.cliCommand,@@ -332,6 +392,7 @@ async function validateAtPackageDir(__agentDocsError: agentDocsError,__unknownKeys: unknownKeys,__spec: identity.name,+ __declaredProviderId: manifest.providerId,__packageDir: packageDir,__manifestFile: manifestFile,};@@ -370,7 +431,11 @@ async function validateAtPackageDir();if (scanUnreachable) {issues.push(- ...(await findUnreachableContributionIssues(packageDir, loaded)),+ ...(await findUnreachableContributionIssues(+ packageDir,+ loaded,+ absoluteRoots,+ )),);}@@ -397,7 +462,7 @@ export async function validateLocalIntegration(cwd = process.cwd()) {return {found: false, issues: []};}- /** @type {{name?: string, version?: string}} */+ /** @type {{name?: string, version?: string, private?: boolean}} */let pkg;try {pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));@@ -416,14 +481,101 @@ export async function validateLocalIntegration(cwd = process.cwd()) {};}- return validateAtPackageDir(+ // npm publishes nothing without a name and a version, and the name is the+ // provider ID every reader keys the package's contributions on.+ // 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)';+ const result = await validateAtPackageDir(packageDir,- {- name: pkg.name ?? '(local package)',- version: pkg.version,- },+ {name, version: pkg.version},{scanUnreachable: true},);+ result.issues.unshift(+ ...fields,+ // Only a manifest that loaded says whether it declares a providerId; one+ // that did not is reported as invalid_manifest.+ ...(result.integration+ ? providerIdIssues(+ pkg.name,+ result.integration.__declaredProviderId,+ result.integration.__manifestFile,+ )+ : []),+ );+ return result;+}++/**+ * Whether `name` is a bare npm package name, the form a provider ID takes.+ * @param {string} name+ */+function isPackageName(name) {+ try {+ normalizeProviderId(name);+ return true;+ } catch {+ return false;+ }+}++/**+ * A warning when no provider ID can be derived for the package: its+ * package.json `name` is not a bare package name and its manifest declares+ * no `providerId` that is one. Readers key the package's contributions on+ * that ID; a missing name is its own warning.+ * @param {unknown} name package.json `name`+ * @param {unknown} declared the manifest's `providerId`+ * @param {string} manifestFile+ * @returns {Issue[]}+ */+function providerIdIssues(name, declared, manifestFile) {+ if (typeof name !== 'string' || name === '') return [];+ if (isPackageName(name)) return [];+ if (typeof declared === 'string' && isPackageName(declared)) return [];+ const manifest = path.basename(manifestFile);+ return [+ warning(+ '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}.`,+ ),+ ];+}++/**+ * A warning for each field npm needs that package.json lacks.+ * @param {{name?: unknown, version?: unknown, private?: unknown}} pkg+ * @param {string} pkgJsonPath+ * @returns {Issue[]}+ */+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.+ if (typeof pkg.name !== 'string' || pkg.name === '') {+ issues.push(+ warning(+ '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}.`,+ ),+ );+ }+ // A private package is never published, so it needs no version.+ if (+ pkg.private !== true &&+ (typeof pkg.version !== 'string' || pkg.version === '')+ ) {+ issues.push(+ warning(+ 'invalid_package_json',+ `${shown} has no "version", so npm cannot pack or publish the package. Fix: add "version": "0.1.0" to ${shown}.`,+ ),+ );+ }+ return issues;}/**diff --git a/packages/cli/foundation/discovery/component-discovery.mjs b/packages/cli/foundation/discovery/component-discovery.mjsindex 47f53f5a0a..b099b5cafd 100644--- a/packages/cli/foundation/discovery/component-discovery.mjs+++ b/packages/cli/foundation/discovery/component-discovery.mjs@@ -118,6 +118,16 @@ function scanDocText(text) {};}+/**+ * Whether a component doc is hidden (`hidden: true`), read as discovery+ * reads it: discovery skips a hidden doc.+ * @param {string} docPath+ * @returns {boolean}+ */+export function isHiddenComponentDoc(docPath) {+ return readDocMeta(docPath).hidden;+}+/*** Read the `group`, `hiddenComponents`, and `hidden` fields from a* component's .doc.mjs file (synchronous), with what {@link scanDocText}@@ -1211,6 +1221,19 @@ export function integrationMemberEntry(doc, record) {);}+/**+ * Whether `dir` is a folder to list. A declared root that is a file is+ * reported by the root check; discovery finds nothing in it.+ * @param {string} dir+ */+function isFolder(dir) {+ try {+ return fs.statSync(dir).isDirectory();+ } catch {+ return false;+ }+}+/*** Visit every component doc under an integration's components root, hidden* ones included, in discovery order, with its stem.@@ -1218,10 +1241,26 @@ export function integrationMemberEntry(doc, record) {* @param {(docPath: string, stem: string) => void} visit*/export function forEachIntegrationDoc(componentsDir, visit) {- if (!componentsDir || !pathExists(componentsDir)) return;+ if (!componentsDir || !isFolder(componentsDir)) return;+ /** @param {string} name */+ const key = name => {+ const rank = INTEGRATION_DOC_SUFFIXES.findIndex(s => name.endsWith(s));+ return rank < 0+ ? {stem: name, rank}+ : {stem: name.slice(0, -INTEGRATION_DOC_SUFFIXES[rank].length), rank};+ };/** @param {string} dirPath */function scanDir(dirPath) {- for (const entry of listDirEntries(dirPath)) {+ // Name order, and for two docs of one stem the suffix precedence, so the+ // doc a stem records is the one a lookup by name finds, on every disk.+ const entries = listDirEntries(dirPath).sort((a, b) => {+ const left = key(a.name);+ const right = key(b.name);+ return left.stem === right.stem+ ? left.rank - right.rank+ : byCodeUnit(left.stem, right.stem);+ });+ for (const entry of entries) {if (entry.name === 'node_modules' || entry.name === '__tests__') continue;const fullPath = path.join(dirPath, entry.name);if (entry.isDirectory()) {@@ -1270,7 +1309,7 @@ export function discoverIntegrationComponents({documentedNames = true} = {},) {const componentsDir = integration?.components;- if (!componentsDir || !pathExists(componentsDir)) return [];+ if (!componentsDir || !isFolder(componentsDir)) return [];/** @type {Map<string, {name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>} */const byName = new Map();@@ -1485,7 +1524,7 @@ function findDocumentedComponent(integration, componentsDir, name) {*/export function findIntegrationComponent(integration, name) {const componentsDir = integration?.components;- if (!componentsDir || !pathExists(componentsDir)) return null;+ if (!componentsDir || !isFolder(componentsDir)) return null;const sameStem = findSameStemDoc(componentsDir, name);if (sameStem) {const exportName = otherExportName({diff --git a/packages/cli/foundation/discovery/docs-discovery.mjs b/packages/cli/foundation/discovery/docs-discovery.mjsindex 88d07a8ee2..656db0fce1 100644--- a/packages/cli/foundation/discovery/docs-discovery.mjs+++ b/packages/cli/foundation/discovery/docs-discovery.mjs@@ -423,6 +423,19 @@ export function problemsInNamespace(doc) {return problems;}+/**+ * Whether `dir` is a folder to list. A declared root that is a file is+ * reported by the root check; discovery finds nothing in it.+ * @param {string} dir+ */+function isFolder(dir) {+ try {+ return fs.statSync(dir).isDirectory();+ } catch {+ return false;+ }+}+/*** Discover the topics contributed by a single loaded integration. Mirrors* `discoverIntegrationComponents`: walk the resolved root, take every@@ -450,7 +463,7 @@ export async function discoverIntegrationDocs(integration) {const namespaces = [];/** @type {import('../doc-compiler/tree.mjs').TreeDocInput[]} */const guides = [];- if (!docsDir || !fs.existsSync(docsDir)) {+ if (!docsDir || !isFolder(docsDir)) {return {records, errors, namespaces, guides};}const providerId = integration.providerId ?? integration.name;diff --git a/packages/cli/foundation/integrations/contribution-inventory.mjs b/packages/cli/foundation/integrations/contribution-inventory.mjsindex aceffa3d76..7a949e51e0 100644--- a/packages/cli/foundation/integrations/contribution-inventory.mjs+++ b/packages/cli/foundation/integrations/contribution-inventory.mjs@@ -137,6 +137,29 @@ const ROOT_KINDS = /** @type {const} */ (['docs',]);+/**+ * The contribution files readers read under each declared root that is a+ * readable folder, package-relative, without importing anything. A folder+ * inside a root that cannot be listed is skipped.+ * @param {{components?: string, templates?: string, codemods?: string, docs?: string, themes?: string}} loaded+ * @param {string} pkgDir+ * @returns {string[]}+ */+export function contributionFiles(loaded, pkgDir) {+ /** @type {Set<string>} */+ const files = new Set();+ for (const kind of ROOT_KINDS) {+ const root = loaded[kind];+ if (!root || !isFolder(root)) continue;+ try {+ for (const file of ENUMERATORS[kind](root, pkgDir)) files.add(file);+ } catch {+ // An unreadable folder inside the root.+ }+ }+ return [...files].sort();+}+// ── Public: static file inventory ────────────────────────────────/**@@ -207,6 +230,19 @@ export function computeRequiredFiles(loaded) {* @property {{append?: readonly string[]}} [agentDocs]*/+/**+ * Whether `dir` is a folder to list. A declared root that is a file is+ * reported by the root check; discovery finds nothing in it.+ * @param {string} dir+ */+function isFolder(dir) {+ try {+ return fs.statSync(dir).isDirectory();+ } catch {+ return false;+ }+}+/*** Run the same discovery functions a consumer uses to collect every* contribution identity from a loaded integration.@@ -229,7 +265,7 @@ export async function collectIdentities(loaded) {/** @type {Array<{kind: string, message: string}>} */const errors = [];- if (loaded.themes && fs.existsSync(loaded.themes)) {+ if (loaded.themes && isFolder(loaded.themes)) {try {const themes = await discoverIntegrationThemes(/** @type {import('./integrations.mjs').LoadedIntegration} */ (loaded),@@ -245,7 +281,7 @@ export async function collectIdentities(loaded) {}}- if (loaded.components && fs.existsSync(loaded.components)) {+ if (loaded.components && isFolder(loaded.components)) {try {const records = discoverIntegrationComponents(loaded) ?? [];// A family doc backs several records: load it, and report it, once.@@ -275,7 +311,7 @@ export async function collectIdentities(loaded) {}}- if (loaded.templates && fs.existsSync(loaded.templates)) {+ if (loaded.templates && isFolder(loaded.templates)) {try {const {templates, errors: templateErrors} =await discoverIntegrationTemplatesForOne(loaded);@@ -298,7 +334,7 @@ export async function collectIdentities(loaded) {}}- if (loaded.codemods && fs.existsSync(loaded.codemods)) {+ if (loaded.codemods && isFolder(loaded.codemods)) {try {const byVersion = await discoverIntegrationCodemods([loaded]);/** @type {{version: string, id: string}[]} */@@ -317,7 +353,7 @@ export async function collectIdentities(loaded) {}}- if (loaded.docs && fs.existsSync(loaded.docs)) {+ if (loaded.docs && isFolder(loaded.docs)) {try {const {records,diff --git a/packages/cli/foundation/integrations/integrations.mjs b/packages/cli/foundation/integrations/integrations.mjsindex 2340e1e452..88f81a018f 100644--- a/packages/cli/foundation/integrations/integrations.mjs+++ b/packages/cli/foundation/integrations/integrations.mjs@@ -60,6 +60,8 @@ import {resolveProviders} from './provider-resolution.mjs';* @property {string} [__agentDocsError] contribution-specific validation* failure; other manifest contributions remain available* @property {string} __spec+ * @property {string} [__declaredProviderId] the manifest's `providerId` as+ * written, kept by validation so it can tell whether the package has one* @property {string} __packageDir* @property {Record<string, unknown>|null} [__packageExports] the owning* package's `exports` map, kept from the package.json this loader alreadydiff --git a/packages/cli/foundation/integrations/validate-contributions.mjs b/packages/cli/foundation/integrations/validate-contributions.mjsindex 6836f1f42e..b69eb5c962 100644--- a/packages/cli/foundation/integrations/validate-contributions.mjs+++ b/packages/cli/foundation/integrations/validate-contributions.mjs@@ -25,6 +25,7 @@ import * as fs from 'node:fs';import * as path from 'node:path';import {isValidSemver} from '../env/semver.mjs';import {+ contributionFiles,findSourceOnlyCandidates,findTemplateSourceOnlyCandidates,} from './contribution-inventory.mjs';@@ -104,6 +105,13 @@ function checkUnknownKeys(integration, issues) {);}+/** @param {{__manifestFile?: string}} integration */+function manifestName(integration) {+ return integration.__manifestFile+ ? path.basename(integration.__manifestFile)+ : 'the integration manifest';+}+/*** Why a declared root cannot be read as a folder, or null when it can.* A missing root keeps its own issue; a root that is a file or that the@@ -139,11 +147,14 @@ export function rootProblem(root) {* declared-but-missing root is a `missing_root` error, a file is an* `invalid_root` error, and a folder that cannot be read is an* `unreadable_root` error. The contribution checks skip all three.- * @param {{components?: string, templates?: string, codemods?: string, docs?: string, themes?: string}} resolved+ * A readable root reached through a symlinked folder is a `symlinked_root`+ * warning: npm pack does not follow it, so the published package loses it.+ * @param {{components?: string, templates?: string, codemods?: string, docs?: string, themes?: string, __manifestFile?: string}} resolved* absolute resolved roots (undefined when not declared)* @param {Issue[]} issues+ * @param {string} [packageDir] the package the roots belong to*/-function checkRoots(resolved, issues) {+function checkRoots(resolved, issues, packageDir) {const kinds = /** @type {const} */ (['components','templates',@@ -155,7 +166,28 @@ function checkRoots(resolved, issues) {const root = resolved[kind];if (root == null) continue;const problem = rootProblem(root);- if (problem == null) continue;+ if (problem == null) {+ const link = packageDir ? symlinkedFolder(root, packageDir) : null;+ if (link && packageDir) {+ const shown = slash(path.relative(packageDir, link.path));+ const realPackage = fs.realpathSync(packageDir);+ const target = slash(path.relative(realPackage, link.target));+ const realRoot = slash(+ path.relative(realPackage, fs.realpathSync(root)),+ );+ const outside = target.startsWith('../') || path.isAbsolute(target);+ const fix = outside+ ? '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(+ '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}.`,+ ),+ );+ }+ continue;+ }if (problem.kind === 'missing') {issues.push(issueError(@@ -181,6 +213,41 @@ function checkRoots(resolved, issues) {}}+/** @param {string} file */+function slash(file) {+ return file.split(path.sep).join('/');+}++/**+ * The first folder on the way from the package to `root` (the root itself+ * included) that is a symlink, with where it points, or null.+ * @param {string} root absolute+ * @param {string} packageDir absolute+ * @returns {{path: string, target: string} | null}+ */+export function symlinkedFolder(root, packageDir) {+ const relative = path.relative(packageDir, root);+ if (+ relative === '' ||+ relative.startsWith('..') ||+ path.isAbsolute(relative)+ ) {+ return null;+ }+ let current = packageDir;+ for (const segment of relative.split(path.sep)) {+ current = path.join(current, segment);+ try {+ if (fs.lstatSync(current).isSymbolicLink()) {+ return {path: current, target: fs.realpathSync(current)};+ }+ } catch {+ return null;+ }+ }+ return null;+}+/*** Validate the integration's codemods via the landed discovery. Discovery is* strict (throws on bad export / duplicate id); we convert any throw into an@@ -340,6 +407,8 @@ async function checkComponents(integration, issues) {if (!integration.components || rootProblem(integration.components)) return;const discover = componentDiscovery.discoverValidIntegrationComponents;if (typeof discover !== 'function') return; // feature not present yet+ const root = /** @type {string} */ (integration.components);+ const files = componentDocFiles(root);try {const {discovered, errors} = await discover(integration);/** @type {import('./contribution-fixes.mjs').FixContext | undefined} */@@ -352,7 +421,12 @@ async function checkComponents(integration, issues) {continue;}const docPath = record.docPath;- let fix = `Fix: add ${record.name}.tsx beside ${docPath ? path.basename(docPath) : `${record.name}.doc.mjs`}.`;+ // Reported once, below, as the case mismatch it is.+ if (docPath && files.caseMismatch.has(docPath)) continue;+ const docName = docPath+ ? path.basename(docPath)+ : `${record.name}.doc.mjs`;+ let fix = `Fix: add ${record.name}.tsx beside ${docName}.`;const stamp = docPath ? readContributionStamp(docPath, false) : null;if (stamp && stamp.type !== 'component' && integration.__packageDir) {context ??= createFixContext(integration.__packageDir, integration);@@ -360,6 +434,48 @@ async function checkComponents(integration, issues) {}issues.push(issueError('invalid_component', `${error.message} ${fix}`));}+ for (const [docPath, source] of files.caseMismatch) {+ const doc = path.basename(docPath);+ const renamed = `${source.slice(0, -'.tsx'.length)}${doc.slice(docStemOf(doc).length)}`;+ const shown = slash(path.relative(root, docPath));+ 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)) {+ issues.push(+ issueWarning(+ '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) {+ issues.push(+ issueWarning(+ 'source_without_component_doc',+ `Component doc "${shown}" and its source "${source}" differ only in letter case. ${linux}, so there the component is missing. ${fix}`,+ ),+ );+ } else {+ issues.push(+ issueError(+ 'invalid_component',+ `Component doc "${shown}" and its source "${source}" differ only in letter case. ${linux}, so here the component is missing. ${fix}`,+ ),+ );+ }+ }+ for (const {read, ignored} of files.duplicates) {+ const readName = path.basename(read);+ const ignoredNames = ignored.map(file => path.basename(file));+ issues.push(+ issueWarning(+ '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}.`,+ ),+ );+ }const overlap = integration.__packageDir? newComponentDocNote((context ??= createFixContext(integration.__packageDir, integration)),@@ -372,16 +488,15 @@ async function checkComponents(integration, issues) {// A hidden doc still pairs with its source; discovery just skips it.if (['.doc.ts', '.doc.mjs', '.doc.js'].some(suffix =>- fs.existsSync(- path.join(- /** @type {string} */ (integration.components),- `${name}${suffix}`,- ),- ),+ fs.existsSync(path.join(root, `${name}${suffix}`)),)) {continue;}+ // A doc whose name differs only in case is reported above.+ if (files.caseMismatchSources.has(path.join(root, `${name}.tsx`))) {+ continue;+ }issues.push(issueWarning('source_without_component_doc',@@ -396,6 +511,83 @@ async function checkComponents(integration, issues) {}}+const COMPONENT_DOC_SUFFIXES = ['.doc.ts', '.doc.mjs', '.doc.js'];++/** @param {string} file a doc file name */+function docStemOf(file) {+ const suffix = COMPONENT_DOC_SUFFIXES.find(each => file.endsWith(each));+ return suffix ? file.slice(0, -suffix.length) : file;+}++/**+ * The component docs under a root, read from the real directory listings:+ * those beside a source whose name differs only in letter case (which an+ * existence check on a case-insensitive disk would call paired), and stems+ * with more than one doc, with the doc discovery reads.+ * @param {string} root+ */+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 */+ const walk = dir => {+ let entries;+ try {+ entries = fs.readdirSync(dir, {withFileTypes: true});+ } catch {+ return;+ }+ const names = new Set(entries.map(entry => entry.name));+ /** @type {Map<string, string[]>} */+ const byStem = new Map();+ for (const entry of entries) {+ const full = path.join(dir, entry.name);+ if (entry.isDirectory()) {+ if (entry.name !== 'node_modules' && entry.name !== '__tests__') {+ walk(full);+ }+ continue;+ }+ const stem = docStemOf(entry.name);+ if (stem === entry.name) continue;+ byStem.set(stem, [...(byStem.get(stem) ?? []), entry.name]);+ const source = `${stem}.tsx`;+ if (names.has(source)) continue;+ const other = [...names].find(+ name => name !== source && name.toLowerCase() === source.toLowerCase(),+ );+ // The source's own doc, if it has one, is its pair.+ if (+ other &&+ !COMPONENT_DOC_SUFFIXES.some(suffix =>+ names.has(`${other.slice(0, -'.tsx'.length)}${suffix}`),+ )+ ) {+ caseMismatch.set(full, other);+ caseMismatchSources.add(path.join(dir, other));+ }+ }+ for (const docs of byStem.values()) {+ if (docs.length < 2) continue;+ const ordered = COMPONENT_DOC_SUFFIXES.map(suffix =>+ docs.find(doc => doc.endsWith(suffix)),+ ).filter(doc => doc != null);+ duplicates.push({+ read: path.join(dir, /** @type {string} */ (ordered[0])),+ ignored: ordered+ .slice(1)+ .map(doc => path.join(dir, /** @type {string} */ (doc))),+ });+ }+ };+ walk(root);+ return {caseMismatch, caseMismatchSources, duplicates};+}+/*** 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 is@@ -431,18 +623,49 @@ async function checkDocs(integration, issues) {async function checkThemes(integration, issues) {if (!integration.themes || rootProblem(integration.themes)) return;try {+ // A theme may name itself differently from its folder (its built files+ // then carry that name), so a name that differs is no finding here:+ // verify judges it against the files the package exports.await discoverIntegrationThemes(integration);} catch (err) {issues.push(issueError('invalid_theme', /** @type {any} */ (err).message));}}+/**+ * A warning for each contribution file a reader reads (the docs and sources+ * `integration verify` expects in the tarball) that the user running astryx+ * cannot read; files no reader takes, such as `.DS_Store`, are not looked at: Astryx cannot check it, and npm pack stops on it. A+ * warning, so validate keeps its exit code; `integration verify` fails on the+ * pack itself.+ * @param {LoadedIntegration} integration+ * @param {Issue[]} issues+ */+function checkUnreadableFiles(integration, issues) {+ const packageDir = integration.__packageDir;+ if (!packageDir) return;+ for (const shown of contributionFiles(integration, packageDir)) {+ try {+ fs.accessSync(path.join(packageDir, shown), fs.constants.R_OK);+ } catch (err) {+ const code = String(/** @type {any} */ (err)?.code ?? 'unknown error');+ issues.push(+ issueWarning(+ '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.`,+ ),+ );+ }+ }+}+/*** Run every contribution validator against a loaded-integration-shaped object.* @param {LoadedIntegration} integration* @param {Issue[]} issues*/async function runContributionChecks(integration, issues) {+ checkUnreadableFiles(integration, issues);await checkCodemods(integration, issues);await checkTemplates(integration, issues);await checkComponents(integration, issues);@@ -497,8 +720,10 @@ export async function validateLoadedIntegration(loaded) {codemods: loaded.codemods,docs: loaded.docs,themes: loaded.themes,+ __manifestFile: loaded.__manifestFile,},issues,+ loaded.__packageDir,);await runContributionChecks(loaded, issues);return issues;diff --git a/packages/cli/test/integration-check-failures.json b/packages/cli/test/integration-check-failures.jsonindex 709e61a360..42b6b539ce 100644--- a/packages/cli/test/integration-check-failures.json+++ b/packages/cli/test/integration-check-failures.json@@ -20,6 +20,7 @@"default_mismatch","doc_fluff","doc_types_skipped",+ "duplicate_component_doc","duplicate_doc","duplicate_prop","duplicate_provider",@@ -50,6 +51,7 @@"missing_template_replacement_target","multiple_manifests","no_package",+ "no_provider_id","not_in_code","not_in_doc","orphan_doc_overlay",@@ -62,6 +64,7 @@"source_without_component_doc","source_without_template_doc","stray_doc_pointer",+ "symlinked_root","template_id_conflict","type_mismatch","unknown_field",@@ -70,6 +73,7 @@"unreachable_contribution","unreachable_scan_truncated","unread_theme_folder",+ "unreadable_file","unreadable_folder","unreadable_root","wrong_type"