@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

package/api/integration/add-theme.test.mjs

@@ -32,7 +32,7 @@ afterEach(() => {
 });
 
 describe('integrationAddTheme', () => {
-  it('writes a valid source theme, catalog, root, package files entry, and receipt', async () => {
+  it('writes a typed same-stem descriptor and source with no central catalog', async () => {
     setup();
     const result = await integrationAddTheme('ocean', {cwd: tmpDir});
 
@@ -45,7 +45,7 @@ describe('integrationAddTheme', () => {
         manifest: 'astryx.integration.mjs',
         files: [
           'themes/ocean/oceanTheme.ts',
-          'themes/manifest.json',
+          'themes/ocean/oceanTheme.doc.mjs',
           'package.json',
           'astryx.integration.mjs',
         ],
@@ -56,21 +56,17 @@ describe('integrationAddTheme', () => {
     expect(
       fs.readFileSync(path.join(tmpDir, 'themes/ocean/oceanTheme.ts'), 'utf-8'),
     ).toContain('export const oceanTheme = defineTheme');
-    expect(
-      JSON.parse(
-        fs.readFileSync(path.join(tmpDir, 'themes/manifest.json'), 'utf-8'),
-      ),
-    ).toMatchObject({
-      version: 1,
-      themes: [
-        {
-          slug: 'ocean',
-          entry: 'oceanTheme.ts',
-          exportName: 'oceanTheme',
-          files: ['oceanTheme.ts'],
-        },
-      ],
-    });
+
+    const descriptor = fs.readFileSync(
+      path.join(tmpDir, 'themes/ocean/oceanTheme.doc.mjs'),
+      'utf-8',
+    );
+    expect(descriptor).toContain("@astryxdesign/cli/authoring').ThemeDoc");
+    expect(descriptor).toContain("type: 'theme'");
+    expect(descriptor).toContain("name: 'ocean'");
+    expect(fs.existsSync(path.join(tmpDir, 'themes/manifest.json'))).toBe(
+      false,
+    );
     expect(
       fs.readFileSync(path.join(tmpDir, 'astryx.integration.mjs'), 'utf-8'),
     ).toContain("themes: './themes'");
@@ -81,6 +77,40 @@ describe('integrationAddTheme', () => {
     expect((await validateLocalIntegration(tmpDir)).issues).toEqual([]);
   });
 
+  it('declares the optional CLI peer that reads typed theme descriptors', async () => {
+    setup({includeFiles: false});
+    const result = await integrationAddTheme('ocean', {cwd: tmpDir});
+    expect(result.data.files).toContain('package.json');
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8'),
+    );
+    expect(pkg.peerDependencies).toEqual({'@astryxdesign/cli': '>=0.7.0'});
+    expect(pkg.peerDependenciesMeta).toEqual({
+      '@astryxdesign/cli': {optional: true},
+    });
+  });
+
+  it('keeps a CLI peer that already reads typed theme descriptors', async () => {
+    const pkg = {
+      name: '@acme/themes',
+      version: '1.0.0',
+      peerDependencies: {'@astryxdesign/cli': '^0.7.2'},
+    };
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify(pkg, null, 2)}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      'export default {};\n',
+    );
+    const result = await integrationAddTheme('ocean', {cwd: tmpDir});
+    expect(result.data.files).not.toContain('package.json');
+    expect(
+      JSON.parse(fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8')),
+    ).toEqual(pkg);
+  });
+
   it('dry-runs the identical receipt without writing anything', async () => {
     setup();
     const beforeManifest = fs.readFileSync(
@@ -96,6 +126,7 @@ describe('integrationAddTheme', () => {
     expect(result.data.dryRun).toBe(true);
     expect(result.data.root).toEqual({path: './themes', created: true});
     expect(result.data.files).toContain('themes/ocean/oceanTheme.ts');
+    expect(result.data.files).toContain('themes/ocean/oceanTheme.doc.mjs');
     expect(fs.existsSync(path.join(tmpDir, 'themes'))).toBe(false);
     expect(
       fs.readFileSync(path.join(tmpDir, 'astryx.integration.mjs'), 'utf-8'),
@@ -125,22 +156,69 @@ describe('integrationAddTheme', () => {
     expect(
       fs.existsSync(path.join(tmpDir, 'src/themes/ocean/oceanTheme.ts')),
     ).toBe(true);
+    expect(
+      fs.existsSync(path.join(tmpDir, 'src/themes/ocean/oceanTheme.doc.mjs')),
+    ).toBe(true);
   });
 
-  it('refuses an invalid existing catalog without changing its bytes', async () => {
+  it('keeps each theme to its own folder: a second theme touches no shared file', async () => {
+    setup({manifest: "export default {themes: './themes'};\n"});
+    await integrationAddTheme('ocean', {cwd: tmpDir});
+    const shared = ['package.json', 'astryx.integration.mjs'].map(file =>
+      fs.readFileSync(path.join(tmpDir, file), 'utf-8'),
+    );
+
+    const result = await integrationAddTheme('reef', {cwd: tmpDir});
+
+    expect(result.data.files).toEqual([
+      'themes/reef/reefTheme.ts',
+      'themes/reef/reefTheme.doc.mjs',
+    ]);
+    expect(fs.readdirSync(path.join(tmpDir, 'themes')).sort()).toEqual([
+      'ocean',
+      'reef',
+    ]);
+    expect(
+      ['package.json', 'astryx.integration.mjs'].map(file =>
+        fs.readFileSync(path.join(tmpDir, file), 'utf-8'),
+      ),
+    ).toEqual(shared);
+  });
+
+  it('refuses an obsolete central catalog without changing its bytes', async () => {
     setup();
     fs.mkdirSync(path.join(tmpDir, 'themes'));
     const catalog = path.join(tmpDir, 'themes', 'manifest.json');
-    fs.writeFileSync(catalog, '{not-json\n');
+    fs.writeFileSync(catalog, '{"version":1}\n');
 
     await expect(
       integrationAddTheme('ocean', {cwd: tmpDir}),
     ).rejects.toMatchObject({code: 'ERR_THEME_INVALID'});
-    expect(fs.readFileSync(catalog, 'utf-8')).toBe('{not-json\n');
+    expect(fs.readFileSync(catalog, 'utf-8')).toBe('{"version":1}\n');
     expect(fs.existsSync(path.join(tmpDir, 'themes', 'ocean'))).toBe(false);
   });
 
-  it('refuses duplicate themes and existing source files', async () => {
+  it('refuses an invalid existing descriptor without changing it', async () => {
+    setup();
+    const existing = path.join(tmpDir, 'themes', 'forest');
+    fs.mkdirSync(existing, {recursive: true});
+    const descriptor = path.join(existing, 'forestTheme.doc.mjs');
+    fs.writeFileSync(descriptor, 'export default {type: "theme"};\n');
+    fs.writeFileSync(
+      path.join(existing, 'forestTheme.ts'),
+      'export const forestTheme = {};\n',
+    );
+
+    await expect(
+      integrationAddTheme('ocean', {cwd: tmpDir}),
+    ).rejects.toMatchObject({code: 'ERR_THEME_INVALID'});
+    expect(fs.readFileSync(descriptor, 'utf-8')).toBe(
+      'export default {type: "theme"};\n',
+    );
+    expect(fs.existsSync(path.join(tmpDir, 'themes', 'ocean'))).toBe(false);
+  });
+
+  it('refuses a duplicate valid theme directory', async () => {
     setup();
     await integrationAddTheme('ocean', {cwd: tmpDir});
     await expect(
@@ -148,6 +226,46 @@ describe('integrationAddTheme', () => {
     ).rejects.toMatchObject({code: 'ERR_FILE_EXISTS'});
   });
 
+  it('refuses an existing invalid theme directory', async () => {
+    setup();
+    fs.mkdirSync(path.join(tmpDir, 'themes', 'ocean'), {recursive: true});
+    fs.writeFileSync(
+      path.join(tmpDir, 'themes', 'ocean', 'oceanTheme.ts'),
+      'export const oceanTheme = {};\n',
+    );
+    await expect(
+      integrationAddTheme('ocean', {cwd: tmpDir}),
+    ).rejects.toMatchObject({code: 'ERR_THEME_INVALID'});
+  });
+
+  it.each([
+    ['an empty folder', []],
+    ['a folder holding .gitkeep', ['.gitkeep']],
+    ['a folder holding NOTES.md', ['NOTES.md']],
+  ])('fills %s', async (_, files) => {
+    setup();
+    const dir = path.join(tmpDir, 'themes', 'ocean');
+    fs.mkdirSync(dir, {recursive: true});
+    for (const file of files) fs.writeFileSync(path.join(dir, file), 'x\n');
+    const result = await integrationAddTheme('ocean', {cwd: tmpDir});
+    expect(result.data.written).toBe(true);
+    expect(fs.readdirSync(dir).sort()).toEqual(
+      [...files, 'oceanTheme.doc.mjs', 'oceanTheme.ts'].sort(),
+    );
+  });
+
+  it('refuses to overwrite a file it would write', async () => {
+    setup();
+    await integrationAddTheme('ocean', {cwd: tmpDir});
+    await expect(
+      integrationAddTheme('ocean', {cwd: tmpDir}),
+    ).rejects.toMatchObject({
+      code: 'ERR_FILE_EXISTS',
+      message:
+        'Refusing to overwrite existing file themes/ocean/oceanTheme.ts.',
+    });
+  });
+
   it.each(['../ocean', 'Ocean', 'ocean theme', '.ocean'])(
     'refuses unsafe or noncanonical name %s',
     async name => {

package/api/integration/authoring-checks.mjs

@@ -3,13 +3,22 @@
 /**
  * @file Integration authoring diagnostics against the built-in Core catalog.
  *
- * Components and templates may intentionally share a Core identity, but
- * unqualified lookup then fails closed and callers must select the package.
- * Docs have explicit `replaces` / `extends` relationships, so the check can
- * distinguish intentional ownership from an accidental same-name shadow.
+ * Templates may intentionally replace Core identities; undeclared same-id
+ * overlaps stay fail-closed and require package selection. The CLI package
+ * version gates replacement-specific fields so 0.6.x keeps its released shape.
+ * Docs have explicit `replaces` / `extends` relationships with parallel
+ * validation semantics.
+ *
+ * @input Integration packages, built-in catalogs, and the CLI release boundary.
+ * @output Typed template, component, and documentation authoring diagnostics.
+ * @position Public integration-authoring API over private discovery adapters.
  */
 
 import {getCliInvocation} from '../../foundation/env/package-manager.mjs';
+import {
+  packageDocsProblems,
+  packageReferenceProblems,
+} from '../docs/_adapter.mjs';
 import {findCoreDir} from '../../foundation/fs/paths.mjs';
 import {
   discoverIntegrationComponents,
@@ -20,9 +29,11 @@ import {
   discoverIntegrationDocs,
 } from '../../foundation/discovery/docs-discovery.mjs';
 import {
+  applyTemplateReplacements,
   discoverCoreTemplates,
   discoverIntegrationTemplatesForOne,
 } from '../../foundation/discovery/template-adapter.mjs';
+import {expandedTemplateConflictSchemaActive} from '../../foundation/discovery/template-conflict-release.mjs';
 import {
   validateInstalledIntegration,
   validateLocalIntegration,
@@ -48,16 +59,27 @@ async function resolveIntegration(pkg, cwd) {
 /**
  * Add discovery errors once to an issue list.
  * @param {Array<{code: string, severity: 'warning' | 'error', message: string}>} issues
- * @param {Array<{message: string} | Error>} errors
+ * @param {Array<{message: string, code?: string, severity?: 'warning' | 'error'} | Error>} errors
  * @param {string} code
  */
 function addErrors(issues, errors, code) {
   for (const error of errors) {
     const message = error.message;
-    if (issues.some(issue => issue.code === code && issue.message === message)) {
+    const issueCode =
+      'code' in error && typeof error.code === 'string' ? error.code : code;
+    const severity =
+      'severity' in error &&
+      (error.severity === 'warning' || error.severity === 'error')
+        ? error.severity
+        : 'error';
+    if (
+      issues.some(
+        issue => issue.code === issueCode && issue.message === message,
+      )
+    ) {
       continue;
     }
-    issues.push({code, severity: 'error', message});
+    issues.push({code: issueCode, severity, message});
   }
 }
 
@@ -74,7 +96,7 @@ export async function integrationTemplateConflicts(pkg, options = {}) {
   const version = resolved.found ? (resolved.version ?? null) : null;
   const issues = [...resolved.issues];
 
-  if (!resolved.integration?.templates || name == null) {
+  if (!resolved.integration || name == null) {
     return {
       type: 'integration.template-conflicts',
       data: {name, version, conflicts: [], issues},
@@ -87,6 +109,32 @@ export async function integrationTemplateConflicts(pkg, options = {}) {
   ]);
   addErrors(issues, errors, 'invalid_template');
 
+  const expandedConflictSchema = expandedTemplateConflictSchemaActive();
+  const replacementResolution = applyTemplateReplacements(
+    [...coreTemplates, ...templates],
+    errors.filter(error => error.replacementTarget != null),
+  );
+  for (const error of replacementResolution.errors) {
+    if (
+      !issues.some(
+        issue => issue.code === error.code && issue.message === error.message,
+      )
+    ) {
+      issues.push({
+        code: error.code,
+        severity: error.severity,
+        message: error.message,
+      });
+    }
+  }
+  const activeReplacementIds = new Set(
+    replacementResolution.templates
+      .filter(
+        template => template.package === name && template.replaces != null,
+      )
+      .map(template => template.dirName),
+  );
+
   /** @type {Map<string, Array<{type: 'page' | 'block', name: string}>>} */
   const coreById = new Map();
   for (const template of coreTemplates) {
@@ -101,30 +149,69 @@ export async function integrationTemplateConflicts(pkg, options = {}) {
   }
 
   const run = getCliInvocation(cwd);
-  const conflicts = templates
-    .flatMap(template => {
-      const coreMatches = coreById.get(template.dirName);
-      if (!coreMatches) return [];
-      const command = `${run} template ${shellArg(template.dirName)} --package ${shellArg(name)}`;
-      const coreKinds = coreMatches
-        .map(match => `${match.type} "${match.name}"`)
-        .join(', ');
-      return [
-        {
+  /** @type {import('./authoring-checks.type.mjs').IntegrationTemplateConflict[]} */
+  const conflicts = [];
+  for (const template of templates) {
+    const sameIdCore = coreById.get(template.dirName);
+    const replacementIsActive = activeReplacementIds.has(template.dirName);
+
+    if (
+      expandedConflictSchema &&
+      replacementIsActive &&
+      template.replaces != null
+    ) {
+      // This branch is unreachable before the package reaches 0.7.0. Keep the
+      // published 0.6.x conflict typedef narrow until the activation change.
+      conflicts.push(
+        /** @type {any} */ ({
           id: template.dirName,
-          severity: /** @type {const} */ ('warning'),
+          severity: 'info',
+          relationship: 'replaces',
+          replaces: template.replaces,
           integrationPackage: name,
           integrationType: template.type,
           integrationName: template.name,
-          coreMatches,
+          coreMatches: coreById.get(template.replaces) ?? [],
           message:
-            `Template id "${template.dirName}" conflicts with Core (${coreKinds}). ` +
-            'Consider renaming the integration template. If you keep it, always select it with --package.',
-          command,
-        },
-      ];
-    })
-    .sort((a, b) => a.id.localeCompare(b.id));
+            `Intentional replacement: "${template.dirName}" replaces the Core template ` +
+            `"${template.replaces}" for unqualified lookup.`,
+          command: `${run} template ${shellArg(template.replaces)} --package ${shellArg('@astryxdesign/core')}`,
+        }),
+      );
+    }
+
+    if (
+      sameIdCore &&
+      !(replacementIsActive && template.replaces === template.dirName)
+    ) {
+      const coreKinds = sameIdCore
+        .map(match => `${match.type} "${match.name}"`)
+        .join(', ');
+      const compatibleKind = sameIdCore.some(
+        match => match.type === template.type,
+      );
+      conflicts.push({
+        id: template.dirName,
+        severity: 'warning',
+        ...(expandedConflictSchema ? {relationship: 'accidental'} : {}),
+        integrationPackage: name,
+        integrationType: template.type,
+        integrationName: template.name,
+        coreMatches: sameIdCore,
+        message: expandedConflictSchema
+          ? compatibleKind
+            ? `Template id "${template.dirName}" conflicts with Core (${coreKinds}). Consider renaming it, or set replaces: ${JSON.stringify(template.dirName)} in its metadata to replace the Core template.`
+            : `Template id "${template.dirName}" conflicts with Core (${coreKinds}), but a ${template.type} template cannot replace a different template kind. Rename the integration template.`
+          : `Template id "${template.dirName}" conflicts with Core (${coreKinds}). Consider renaming the integration template. If you keep it, always select it with --package.`,
+        command: `${run} template ${shellArg(template.dirName)} --package ${shellArg(name)}`,
+      });
+    }
+  }
+  conflicts.sort((a, b) =>
+    `${a.id}:${'relationship' in a ? a.relationship : ''}`.localeCompare(
+      `${b.id}:${'relationship' in b ? b.relationship : ''}`,
+    ),
+  );
 
   return {
     type: 'integration.template-conflicts',
@@ -211,10 +298,11 @@ export async function integrationDocConflicts(pkg, options = {}) {
     };
   }
 
-  const [{records, errors}, builtinTopics] = await Promise.all([
+  const [discovered, builtinTopics] = await Promise.all([
     discoverIntegrationDocs(resolved.integration),
     Promise.resolve(discoverBuiltinTopics()),
   ]);
+  const {records, errors} = discovered;
   addErrors(issues, errors, 'invalid_doc');
   const coreTopicsByKey = new Map(
     Object.keys(builtinTopics).map(topic => [topic.toLowerCase(), topic]),
@@ -276,6 +364,28 @@ export async function integrationDocConflicts(pkg, options = {}) {
     ),
   );
 
+  // The same graph checks `astryx doctor` runs in a project: the namespaces
+  // and placed guides this package adds to the docs tree, and every link in
+  // its docs (spec:AST-046, spec:AST-047).
+  if (errors.length === 0) {
+    for (const {severity, message} of await packageDocsProblems(
+      /** @type {{name: string}} */ (resolved.integration),
+      discovered,
+    )) {
+      issues.push({code: 'invalid_doc_graph', severity, 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),
+      discovered,
+    )) {
+      issues.push({code: 'invalid_doc_reference', severity: 'error', message});
+    }
+  }
+
   return {
     type: 'integration.doc-conflicts',
     data: {name, version, findings, issues},