@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9c4d44d

package/foundation/integrations/contribution-inventory.d.mts

@@ -15,7 +15,7 @@
  */
 /**
  * Compute the files the tarball must contain for an integration's
- * contributions to be visible. Reads catalogs and walks directories;
+ * contributions to be visible. Walks descriptor-owned directories;
  * never imports or executes authored modules.
  *
  * @param {import('./integrations.mjs').LoadedIntegration} loaded
@@ -26,7 +26,7 @@ export function computeRequiredFiles(loaded: import("./integrations.mjs").Loaded
  * @typedef {object} ContributionIdentities
  * @property {{slug: string, exportName: string}[]} themes
  * @property {string[]} components
- * @property {{id: string, type: string, name: string}[]} templates
+ * @property {{id: string, type: string, name: string, replaces?: string}[]} templates
  * @property {{version: string, id: string}[]} codemods
  * @property {string[]} docs
  * @property {string[]} agentDocsAppend
@@ -127,6 +127,7 @@ export type ContributionIdentities = {
         id: string;
         type: string;
         name: string;
+        replaces?: string;
     }[];
     codemods: {
         version: string;

package/foundation/integrations/contribution-inventory.mjs

@@ -14,8 +14,11 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {isDeepStrictEqual} from 'node:util';
-import {THEME_MANIFEST_BASENAME} from '../discovery/theme-discovery.mjs';
-import {discoverIntegrationThemes} from '../discovery/theme-discovery.mjs';
+import {
+  discoverIntegrationThemes,
+  isThemeFolder,
+  listThemeFiles,
+} from '../discovery/theme-discovery.mjs';
 import {discoverIntegrationComponents} from '../discovery/component-discovery.mjs';
 import {loadComponentDoc} from '../discovery/component-loader.mjs';
 import {discoverIntegrationTemplatesForOne} from '../discovery/template-adapter.mjs';
@@ -65,27 +68,21 @@ function rel(packageDir, file) {
 
 /** @param {string} root @param {string} pkgDir */
 function enumerateThemeFiles(root, pkgDir) {
+  if (!root || !fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    return [];
+  }
+  // Exactly what `theme add` copies: each theme folder's files, including
+  // tests and fixtures, but no dot entry or file npm never publishes. Files
+  // beside the theme folders belong to no theme.
   /** @type {string[]} */
   const files = [];
-  const catalog = path.join(root, THEME_MANIFEST_BASENAME);
-  if (!fs.existsSync(catalog)) return files;
-  files.push(rel(pkgDir, catalog));
-  try {
-    const data = JSON.parse(fs.readFileSync(catalog, 'utf-8'));
-    if (data?.version !== 1 || !Array.isArray(data.themes)) return files;
-    for (const theme of data.themes) {
-      if (typeof theme.slug !== 'string' || !Array.isArray(theme.files))
-        continue;
-      for (const f of theme.files) {
-        if (typeof f === 'string') {
-          files.push(rel(pkgDir, path.join(root, theme.slug, f)));
-        }
-      }
+  for (const entry of fs.readdirSync(root, {withFileTypes: true})) {
+    const full = path.join(root, entry.name);
+    if (entry.isDirectory() && isThemeFolder(full)) {
+      files.push(...listThemeFiles(full).map(file => path.join(full, file)));
     }
-  } catch {
-    /* Phase 1 catches structural issues */
   }
-  return files;
+  return files.sort().map(file => rel(pkgDir, file));
 }
 
 /** @param {string} root @param {string} pkgDir */
@@ -158,7 +155,7 @@ const ROOT_KINDS = /** @type {const} */ ([
 
 /**
  * Compute the files the tarball must contain for an integration's
- * contributions to be visible. Reads catalogs and walks directories;
+ * contributions to be visible. Walks descriptor-owned directories;
  * never imports or executes authored modules.
  *
  * @param {import('./integrations.mjs').LoadedIntegration} loaded
@@ -192,7 +189,7 @@ export function computeRequiredFiles(loaded) {
  * @typedef {object} ContributionIdentities
  * @property {{slug: string, exportName: string}[]} themes
  * @property {string[]} components
- * @property {{id: string, type: string, name: string}[]} templates
+ * @property {{id: string, type: string, name: string, replaces?: string}[]} templates
  * @property {{version: string, id: string}[]} codemods
  * @property {string[]} docs
  * @property {string[]} agentDocsAppend
@@ -281,7 +278,12 @@ export async function collectIdentities(loaded) {
         errors.push({kind: 'templates', message: templateError.message});
       }
       identities.templates = templates
-        .map(t => ({id: t.dirName, type: t.type, name: t.name}))
+        .map(t => ({
+          id: t.dirName,
+          type: t.type,
+          name: t.name,
+          ...(t.replaces == null ? {} : {replaces: t.replaces}),
+        }))
         .sort((a, b) => a.id.localeCompare(b.id));
     } catch (err) {
       errors.push({
@@ -312,12 +314,13 @@ export async function collectIdentities(loaded) {
 
   if (loaded.docs && fs.existsSync(loaded.docs)) {
     try {
-      const {records, errors: docErrors} =
+      const {records, guides, errors: docErrors} =
         await discoverIntegrationDocs(loaded);
       for (const docError of docErrors) {
         errors.push({kind: 'docs', message: docError.message});
       }
-      identities.docs = records.map(r => r.name).sort();
+      // A guide placed in the docs tree is a doc contribution too.
+      identities.docs = [...records, ...guides].map(r => r.name).sort();
     } catch (err) {
       errors.push({kind: 'docs', message: /** @type {Error} */ (err).message});
     }

package/foundation/integrations/contribution-inventory.test.mjs

@@ -37,30 +37,37 @@ function loaded(overrides = {}) {
 
 function writeTheme(slug, files = [`${slug}Theme.ts`]) {
   const root = path.join(tmpDir, 'themes');
-  fs.mkdirSync(path.join(root, slug), {recursive: true});
-  for (const f of files) {
-    fs.writeFileSync(path.join(root, slug, f), `// ${f}\n`);
+  const themeDir = path.join(root, slug);
+  fs.mkdirSync(themeDir, {recursive: true});
+  for (const file of files) {
+    const target = path.join(themeDir, file);
+    fs.mkdirSync(path.dirname(target), {recursive: true});
+    fs.writeFileSync(target, `// ${file}\n`);
   }
-  const catalogPath = path.join(root, 'manifest.json');
-  let catalog = {version: 1, themes: []};
-  if (fs.existsSync(catalogPath)) {
-    catalog = JSON.parse(fs.readFileSync(catalogPath, 'utf-8'));
-  }
-  catalog.themes.push({
-    slug,
-    displayName: slug,
-    description: `${slug} theme.`,
-    maintained: true,
-    entry: files[0],
-    exportName: `${slug}Theme`,
-    files,
-  });
-  fs.writeFileSync(catalogPath, JSON.stringify(catalog, null, 2) + '\n');
+  fs.writeFileSync(
+    path.join(themeDir, `${slug}Theme.doc.mjs`),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {type: 'theme', name: '${slug}', displayName: '${slug}', description: '${slug} theme.', maintained: true};\n`,
+  );
   return root;
 }
 
+const UNPUBLISHED = [
+  '.DS_Store',
+  '._oceanTheme.ts',
+  '.gitignore',
+  '.npmignore',
+  '.npmrc',
+  'oceanTheme.ts.orig',
+  'npm-debug.log',
+  'palette/.DS_Store',
+  'palette/npm-debug.log',
+  '.git/HEAD',
+  'CVS/Entries',
+  'node_modules/dep/index.js',
+];
+
 describe('computeRequiredFiles', () => {
-  it('enumerates manifest + theme catalog files', () => {
+  it('enumerates each complete descriptor-owned theme directory', () => {
     const root = writeTheme('ocean', ['oceanTheme.ts', 'tokens.ts']);
     const inv = computeRequiredFiles(loaded({themes: root}));
 
@@ -69,13 +76,46 @@ describe('computeRequiredFiles', () => {
     expect(inv.roots[0].kind).toBe('themes');
     expect(inv.roots[0].files).toEqual(
       expect.arrayContaining([
-        'themes/manifest.json',
+        'themes/ocean/oceanTheme.doc.mjs',
         'themes/ocean/oceanTheme.ts',
         'themes/ocean/tokens.ts',
       ]),
     );
     expect(inv.allFiles).toContain('astryx.integration.mjs');
-    expect(inv.allFiles).toContain('themes/manifest.json');
+    expect(inv.allFiles).toContain('themes/ocean/oceanTheme.doc.mjs');
+    expect(inv.allFiles).not.toContain('themes/manifest.json');
+  });
+
+  it('requires no file npm leaves out, at any depth, and none beside the themes', () => {
+    const root = writeTheme('ocean', ['oceanTheme.ts', 'palette/tokens.ts']);
+    for (const file of [
+      ...UNPUBLISHED.map(name => `ocean/${name}`),
+      'README.md',
+      'npm-debug.log',
+    ]) {
+      fs.mkdirSync(path.dirname(path.join(root, file)), {recursive: true});
+      fs.writeFileSync(path.join(root, file), 'x\n');
+    }
+    expect(computeRequiredFiles(loaded({themes: root})).roots[0].files).toEqual(
+      [
+        'themes/ocean/oceanTheme.doc.mjs',
+        'themes/ocean/oceanTheme.ts',
+        'themes/ocean/palette/tokens.ts',
+      ],
+    );
+  });
+
+  it('requires only the folders theme discovery reads', () => {
+    const root = writeTheme('ocean');
+    for (const file of ['shared/palette.ts', '.cache/state.json']) {
+      fs.mkdirSync(path.dirname(path.join(root, file)), {recursive: true});
+      fs.writeFileSync(path.join(root, file), '{}\n');
+    }
+    const inv = computeRequiredFiles(loaded({themes: root}));
+    expect(inv.roots[0].files).toEqual([
+      'themes/ocean/oceanTheme.doc.mjs',
+      'themes/ocean/oceanTheme.ts',
+    ]);
   });
 
   it('enumerates paired component metadata and source files', () => {
@@ -139,31 +179,31 @@ describe('computeRequiredFiles', () => {
     const root = path.join(tmpDir, 'templates');
     fs.mkdirSync(path.join(root, 'dashboard'), {recursive: true});
     fs.writeFileSync(
-      path.join(root, 'dashboard', 'dashboard.template.mjs'),
+      path.join(root, 'dashboard', 'dashboard.doc.mjs'),
       '// tmpl\n',
     );
     fs.writeFileSync(path.join(root, 'dashboard', 'dashboard.tsx'), '// src\n');
     const inv = computeRequiredFiles(loaded({templates: root}));
 
     expect(inv.roots[0].files).toContain(
-      'templates/dashboard/dashboard.template.mjs',
+      'templates/dashboard/dashboard.doc.mjs',
     );
     expect(inv.roots[0].files).toContain('templates/dashboard/dashboard.tsx');
   });
 
-  it('enumerates legacy .doc template metadata with paired sources', () => {
+  it('enumerates released .template compatibility metadata with paired sources', () => {
     const root = path.join(tmpDir, 'templates');
     fs.mkdirSync(path.join(root, 'dashboard'), {recursive: true});
     fs.writeFileSync(
-      path.join(root, 'dashboard', 'dashboard.doc.mjs'),
-      '// legacy template\n',
+      path.join(root, 'dashboard', 'dashboard.template.mjs'),
+      '// released compatibility template\n',
     );
     fs.writeFileSync(path.join(root, 'dashboard', 'dashboard.tsx'), '// src\n');
 
     const inv = computeRequiredFiles(loaded({templates: root}));
 
     expect(inv.roots[0].files).toEqual([
-      'templates/dashboard/dashboard.doc.mjs',
+      'templates/dashboard/dashboard.template.mjs',
       'templates/dashboard/dashboard.tsx',
     ]);
   });
@@ -264,6 +304,25 @@ describe('compareIdentities', () => {
     expect(issues[0].message).toContain('dash');
   });
 
+  it('errors when a packed template replaces a different target', () => {
+    const template = {id: 'acme-shell', type: 'page', name: 'Acme shell'};
+    const local = {
+      ...base(),
+      templates: [{...template, replaces: 'shell-side-nav'}],
+    };
+    const packed = {
+      ...base(),
+      templates: [{...template, replaces: 'shell-top-nav'}],
+    };
+
+    expect(compareIdentities(local, packed)).toEqual([
+      expect.objectContaining({
+        code: 'identity_mismatch',
+        message: expect.stringContaining('acme-shell'),
+      }),
+    ]);
+  });
+
   it('errors when a codemod is missing from packed', () => {
     const local = {
       ...base(),

package/foundation/integrations/integration-warnings.d.mts

@@ -8,10 +8,17 @@
  *
  *   Warning: <pkg> has N integration issue(s). Run: astryx doctor integration validate <pkg>
  *
- * @param {Array<import('./integrations.mjs').LoadedIntegration>} loadedIntegrations the Project's loaded integrations
+ * @param {Array<import('./integrations.mjs').LoadedIntegration> | {issues: () => Promise<Array<{package: string, code: string, severity: string, message: string}>>}} source loaded integrations or their Project owner
  * @param {{json?: boolean}} [options]
  * @returns {Promise<void>}
  */
-export function warnOnIntegrationIssues(loadedIntegrations: Array<import("./integrations.mjs").LoadedIntegration>, { json }?: {
+export function warnOnIntegrationIssues(source: Array<import("./integrations.mjs").LoadedIntegration> | {
+    issues: () => Promise<Array<{
+        package: string;
+        code: string;
+        severity: string;
+        message: string;
+    }>>;
+}, { json }?: {
     json?: boolean;
 }): Promise<void>;

package/foundation/integrations/integration-warnings.mjs

@@ -10,8 +10,9 @@
  * contributions or spamming per-contribution diagnostics.
  *
  * Design constraints (all enforced here):
- *   - Reuses the Doctor integration validators (validateLoadedIntegration);
- *     no validation logic is duplicated.
+ *   - Reuses Project.issues() when a Project is available, so cross-package
+ *     replacement warnings are visible; accepts loaded integrations for legacy
+ *     internal callers and tests.
  *   - Writes to STDERR only, so it never corrupts a --json stdout envelope.
  *   - Suppressed entirely in --json mode.
  *   - Best-effort: never throws, never changes the exit code. Broken
@@ -28,38 +29,62 @@ import {validateLoadedIntegration} from './validate-contributions.mjs';
  *
  *   Warning: <pkg> has N integration issue(s). Run: astryx doctor integration validate <pkg>
  *
- * @param {Array<import('./integrations.mjs').LoadedIntegration>} loadedIntegrations the Project's loaded integrations
+ * @param {Array<import('./integrations.mjs').LoadedIntegration> | {issues: () => Promise<Array<{package: string, code: string, severity: string, message: string}>>}} source loaded integrations or their Project owner
  * @param {{json?: boolean}} [options]
  * @returns {Promise<void>}
  */
-export async function warnOnIntegrationIssues(loadedIntegrations, {json = false} = {}) {
+export async function warnOnIntegrationIssues(source, {json = false} = {}) {
   try {
-    // Cheap guard: only do work when integrations are actually configured.
     if (json) return;
-    if (!Array.isArray(loadedIntegrations) || loadedIntegrations.length === 0) {
-      return;
-    }
-    for (const integration of loadedIntegrations) {
-      if (!integration || typeof integration !== 'object') continue;
-      // A package set aside for a provider-ID conflict is fine in isolation,
-      // so `doctor integration validate` would not explain it. Say it here.
-      if (integration.__providerConflict) {
-        console.error(`Warning: ${integration.__providerConflict.message}`);
-        continue;
+
+    /** @type {Map<string, number>} */
+    const issueCounts = new Map();
+    const fromProject =
+      source != null &&
+      !Array.isArray(source) &&
+      typeof source.issues === 'function';
+
+    if (fromProject) {
+      const issues = await source.issues();
+      for (const issue of issues) {
+        // A provider-conflict issue carries the specific message that
+        // `doctor integration validate` would not explain. Print it directly.
+        if (issue.code === 'duplicate_provider') {
+          console.error(`Warning: ${issue.message}`);
+          continue;
+        }
+        issueCounts.set(
+          issue.package,
+          (issueCounts.get(issue.package) ?? 0) + 1,
+        );
       }
-      let issues;
-      try {
-        issues = await validateLoadedIntegration(integration);
-      } catch {
-        // Best-effort: a validator throwing must not break the host command.
-        continue;
+    } else if (Array.isArray(source)) {
+      for (const integration of source) {
+        if (!integration || typeof integration !== 'object') continue;
+        // A package set aside for a provider-ID conflict is fine in isolation,
+        // so `doctor integration validate` would not explain it. Say it here.
+        if (integration.__providerConflict) {
+          console.error(`Warning: ${integration.__providerConflict.message}`);
+          continue;
+        }
+        let issues;
+        try {
+          issues = await validateLoadedIntegration(integration);
+        } catch {
+          continue;
+        }
+        if (!Array.isArray(issues) || issues.length === 0) continue;
+        const pkg = integration.name ?? integration.__spec ?? '(integration)';
+        issueCounts.set(pkg, issues.length);
       }
-      if (!Array.isArray(issues) || issues.length === 0) continue;
-      const pkg = integration.name ?? integration.__spec ?? '(integration)';
-      // Stderr only — keeps stdout (and any --json envelope) clean.
+    }
+
+    for (const [pkg, count] of issueCounts) {
+      const command = fromProject
+        ? 'astryx doctor'
+        : `astryx doctor integration validate ${pkg}`;
       console.error(
-        `Warning: ${pkg} has ${issues.length} integration issue(s). ` +
-          `Run: astryx doctor integration validate ${pkg}`,
+        `Warning: ${pkg} has ${count} integration issue(s). Run: ${command}`,
       );
     }
   } catch {

package/foundation/integrations/integration-warnings.test.mjs

@@ -37,7 +37,12 @@ afterEach(() => {
  * Build a loaded-integration-shaped object. Roots are absolute (mirrors
  * loadIntegrations' resolveRoot).
  */
-function loaded({name = '@acme/widgets', components, templates, codemods} = {}) {
+function loaded({
+  name = '@acme/widgets',
+  components,
+  templates,
+  codemods,
+} = {}) {
   return {
     name,
     version: '1.0.0',
@@ -62,6 +67,25 @@ describe('warnOnIntegrationIssues', () => {
     );
   });
 
+  it('surfaces cross-package issues collected by Project', async () => {
+    const project = {
+      issues: async () => [
+        {
+          package: '@acme/later',
+          code: 'ambiguous_template_replacement',
+          severity: 'warning',
+          message: 'Later configured replacement wins.',
+        },
+      ],
+    };
+
+    await warnOnIntegrationIssues(project, {json: false});
+
+    expect(errLines).toEqual([
+      'Warning: @acme/later has 1 integration issue(s). Run: astryx doctor',
+    ]);
+  });
+
   it('emits nothing in --json mode (keeps stdout/JSON clean)', async () => {
     const integration = loaded({components: 'does-not-exist'});
     await warnOnIntegrationIssues([integration], {json: true});
@@ -116,4 +140,53 @@ describe('warnOnIntegrationIssues', () => {
     ).resolves.toBeUndefined();
     expect(errLines).toHaveLength(0);
   });
+
+  it('prints the specific provider-conflict message via the array path', async () => {
+    const conflict = {
+      name: '@acme/charts',
+      version: '2.0.0',
+      __spec: '@acme/charts',
+      __packageDir: tmpDir,
+      __providerConflict: {
+        providerId: '@acme/lab',
+        claimedBy: '@acme/lab',
+        message:
+          '@acme/charts@2.0.0 and @acme/lab@1.0.0 both claim provider ID ' +
+          '"@acme/lab". @acme/lab@1.0.0 loads first and is used; ' +
+          '@acme/charts@2.0.0 contributes nothing until one package changes ' +
+          'its providerId.',
+      },
+    };
+    await warnOnIntegrationIssues([conflict], {json: false});
+
+    expect(errLines).toHaveLength(1);
+    expect(errLines[0]).toBe(`Warning: ${conflict.__providerConflict.message}`);
+    // Must NOT print the generic validate pointer for a provider conflict.
+    expect(errLines[0]).not.toContain('integration issue(s)');
+  });
+
+  it('prints the specific provider-conflict message via the Project path', async () => {
+    const conflictMessage =
+      '@acme/charts@2.0.0 and @acme/lab@1.0.0 both claim provider ID ' +
+      '"@acme/lab". @acme/lab@1.0.0 loads first and is used; ' +
+      '@acme/charts@2.0.0 contributes nothing until one package changes ' +
+      'its providerId.';
+    const project = {
+      issues: async () => [
+        {
+          package: '@acme/charts@2.0.0',
+          code: 'duplicate_provider',
+          severity: 'warning',
+          message: conflictMessage,
+        },
+      ],
+    };
+
+    await warnOnIntegrationIssues(project, {json: false});
+
+    expect(errLines).toHaveLength(1);
+    expect(errLines[0]).toBe(`Warning: ${conflictMessage}`);
+    // Must NOT print the generic validate pointer for a provider conflict.
+    expect(errLines[0]).not.toContain('integration issue(s)');
+  });
 });

package/foundation/integrations/integrations.d.mts

@@ -14,6 +14,9 @@
  * issues, Doctor, and the per-command warning name the one set aside instead of
  * dropping it without a word.
  *
+ * The conflict pass of {@link resolveProviders}, for a list that is already
+ * assembled.
+ *
  * @param {LoadedIntegration[]} integrations in precedence order
  * @returns {LoadedIntegration[]}
  */
@@ -42,7 +45,7 @@ export function findManifestPaths(dir: string): string[];
  * @param {string} file absolute manifest path
  * @param {string} [label] used in error messages
  * @param {{fresh?: boolean}} [options]
- * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, agentDocsError?: string}>}
+ * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, discover?: import('../../authoring/discover/type').DiscoverSource, discoverError?: string, agentDocsError?: string}>}
  */
 export function loadManifest(file: string, label?: string, { fresh }?: {
     fresh?: boolean;
@@ -52,6 +55,8 @@ export function loadManifest(file: string, label?: string, { fresh }?: {
     debug?: import("../../authoring/debug/type").DebugEventHandler;
     gapReport?: import("../../authoring/gap-report/type").GapReportHandler;
     gapReportError?: string;
+    discover?: import("../../authoring/discover/type").DiscoverSource;
+    discoverError?: string;
     agentDocsError?: string;
 }>;
 /**
@@ -151,6 +156,9 @@ export function loadIntegrations(specs?: string[], { cwd, fresh, resolveProvider
  *   validated package-owned handler from the `gapReport` NAMED export.
  * @property {string} [__gapReportError] isolated named-handler validation error.
  *   Named exports are not manifest keys — see {@link loadManifest}.
+ * @property {import('../../authoring/discover/type').DiscoverSource} [__discover]
+ *   validated catalog source from the `discover` NAMED export.
+ * @property {string} [__discoverError] isolated discover-source validation error.
  */
 /** Conventional manifest basenames, in load-precedence order. */
 export const MANIFEST_BASENAMES: string[];
@@ -242,4 +250,12 @@ export type LoadedIntegration = {
      * Named exports are not manifest keys — see {@link loadManifest}.
      */
     __gapReportError?: string | undefined;
+    /**
+     * validated catalog source from the `discover` NAMED export.
+     */
+    __discover?: import("../../authoring/discover/type").DiscoverSource | undefined;
+    /**
+     * isolated discover-source validation error.
+     */
+    __discoverError?: string | undefined;
 };