Skip to content

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.md
new file mode 100644
index 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.
+
+@josephfarina
diff --git a/packages/cli/api/docs/_adapter.mjs b/packages/cli/api/docs/_adapter.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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 already
diff --git a/packages/cli/foundation/integrations/validate-contributions.mjs b/packages/cli/foundation/integrations/validate-contributions.mjs
index 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.json
index 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"