@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

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'");
@@ -96,6 +92,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 +122,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 +192,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 message of await packageDocsProblems(
+      /** @type {{name: string}} */ (resolved.integration),
+      discovered,
+    )) {
+      issues.push({code: 'invalid_doc_graph', severity: 'warning', 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},

package/api/integration/authoring-checks.test.mjs

@@ -2,9 +2,16 @@
 
 /**
  * @file Hermetic integration authoring checks against the real Core catalogs.
+ * @input Integration fixtures and the post-0.7 conflict projection.
+ * @output Coverage for replacement validation and public diagnostics.
+ * @position Unit coverage; the 0.6.x compatibility shape has its own fixture.
  */
 
-import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+
+vi.mock('../../foundation/discovery/template-conflict-release.mjs', () => ({
+  expandedTemplateConflictSchemaActive: () => true,
+}));
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {discoverCoreTemplates} from '../../foundation/discovery/template-adapter.mjs';
@@ -20,7 +27,14 @@ import {
 
 let tmpDir;
 
-function writeIntegration({id, name, type = 'block', root = tmpDir}) {
+function writeIntegration({
+  id,
+  name,
+  type = 'block',
+  root = tmpDir,
+  replacements,
+  withSource = true,
+}) {
   fs.mkdirSync(root, {recursive: true});
   fs.writeFileSync(
     path.join(root, 'package.json'),
@@ -33,9 +47,10 @@ function writeIntegration({id, name, type = 'block', root = tmpDir}) {
   const stem = path.join(root, 'templates', id);
   fs.mkdirSync(path.dirname(stem), {recursive: true});
   fs.writeFileSync(
-    `${stem}.template.mjs`,
-    `export default {type: '${type}', name: ${JSON.stringify(name)}, description: 'fixture'};\n`,
+    `${stem}.doc.mjs`,
+    `export default {type: '${type}', name: ${JSON.stringify(name)}, description: 'fixture'${replacements?.[id] == null ? '' : `, replaces: ${JSON.stringify(replacements[id])}`}};\n`,
   );
+  if (!withSource) return;
   fs.writeFileSync(
     `${stem}.tsx`,
     'export default function Fixture() { return null; }\n',
@@ -158,6 +173,159 @@ describe('integrationTemplateConflicts', () => {
     );
   });
 
+  it('classifies a valid replacement and points to the Core original', async () => {
+    const core = (await discoverCoreTemplates()).find(
+      template => template.type === 'page',
+    );
+    expect(core).toBeDefined();
+    writeIntegration({
+      id: 'acme-app-shell',
+      name: 'Acme app shell',
+      type: core.type,
+      replacements: {'acme-app-shell': core.dirName},
+    });
+
+    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});
+
+    expect(result.data.issues).toEqual([]);
+    expect(result.data.conflicts).toEqual([
+      expect.objectContaining({
+        id: 'acme-app-shell',
+        severity: 'info',
+        relationship: 'replaces',
+        replaces: core.dirName,
+      }),
+    ]);
+    expect(result.data.conflicts[0].command).toContain(
+      `template ${core.dirName} --package @astryxdesign/core`,
+    );
+  });
+
+  it('reports a replacement target that Core does not provide', async () => {
+    writeIntegration({
+      id: 'acme-app-shell',
+      name: 'Acme app shell',
+      type: 'page',
+      replacements: {'acme-app-shell': 'missing-core-shell'},
+    });
+
+    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});
+
+    expect(result.data.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'missing_template_replacement_target',
+          severity: 'error',
+        }),
+      ]),
+    );
+  });
+
+  it('reports a replacement declared by a template that cannot be used', async () => {
+    const [core] = await discoverCoreTemplates();
+    expect(core).toBeDefined();
+    writeIntegration({
+      id: 'broken-template',
+      name: 'Broken template',
+      type: core.type,
+      replacements: {'broken-template': core.dirName},
+      withSource: false,
+    });
+
+    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});
+
+    expect(result.data.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'invalid_template_replacement',
+          severity: 'error',
+          message: expect.stringContaining('cannot be used'),
+        }),
+      ]),
+    );
+  });
+
+  it('reports two templates that replace the same Core target as ambiguous', async () => {
+    const [core] = await discoverCoreTemplates();
+    expect(core).toBeDefined();
+    const replacements = {
+      'acme-app-shell-a': core.dirName,
+      'acme-app-shell-b': core.dirName,
+    };
+    writeIntegration({
+      id: 'acme-app-shell-a',
+      name: 'Acme app shell A',
+      type: core.type,
+      replacements,
+    });
+    writeIntegration({
+      id: 'acme-app-shell-b',
+      name: 'Acme app shell B',
+      type: core.type,
+      replacements,
+    });
+
+    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});
+
+    expect(result.data.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'ambiguous_template_replacement',
+          severity: 'error',
+        }),
+      ]),
+    );
+  });
+
+  it('reports a replacement whose template kind differs from Core', async () => {
+    const corePage = (await discoverCoreTemplates()).find(
+      template => template.type === 'page',
+    );
+    expect(corePage).toBeDefined();
+    writeIntegration({
+      id: 'acme-app-shell',
+      name: 'Acme app shell',
+      type: 'block',
+      replacements: {'acme-app-shell': corePage.dirName},
+    });
+
+    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});
+
+    expect(result.data.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'invalid_template_replacement',
+          severity: 'error',
+          message: expect.stringContaining('same type'),
+        }),
+      ]),
+    );
+  });
+
+  it('does not recommend an impossible replacement for a different Core kind', async () => {
+    const corePage = (await discoverCoreTemplates()).find(
+      template => template.type === 'page',
+    );
+    expect(corePage).toBeDefined();
+    writeIntegration({
+      id: corePage.dirName,
+      name: 'Acme block with a page id',
+      type: 'block',
+    });
+
+    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});
+    const conflict = result.data.conflicts.find(
+      item => item.id === corePage.dirName,
+    );
+
+    expect(conflict?.relationship).toBe('accidental');
+    expect(conflict?.message).toContain(
+      'cannot replace a different template kind',
+    );
+    expect(conflict?.message).toContain('Rename');
+    expect(conflict?.message).not.toContain('set replaces');
+  });
+
   it('shell-quotes unusual ids instead of allowing command substitution', () => {
     expect(shellArg('safe/id')).toBe('safe/id');
     expect(shellArg('my$thing')).toBe("'my$thing'");
@@ -176,7 +344,7 @@ describe('integrationTemplateConflicts', () => {
     );
     fs.mkdirSync(path.join(tmpDir, 'templates'), {recursive: true});
     fs.writeFileSync(
-      path.join(tmpDir, 'templates', 'broken.template.mjs'),
+      path.join(tmpDir, 'templates', 'broken.doc.mjs'),
       `throw new Error('broken fixture');\n`,
     );
     fs.writeFileSync(
@@ -221,7 +389,9 @@ describe('integrationComponentConflicts', () => {
     expect(core).toBeDefined();
     writeComponentIntegration(core.name);
 
-    const result = await integrationComponentConflicts(undefined, {cwd: tmpDir});
+    const result = await integrationComponentConflicts(undefined, {
+      cwd: tmpDir,
+    });
 
     expect(result.type).toBe('integration.component-conflicts');
     expect(result.data.issues).toEqual([]);
@@ -240,7 +410,9 @@ describe('integrationComponentConflicts', () => {
   it('does not flag an integration-only component name', async () => {
     writeComponentIntegration('AcmeOnlyWidget');
 
-    const result = await integrationComponentConflicts(undefined, {cwd: tmpDir});
+    const result = await integrationComponentConflicts(undefined, {
+      cwd: tmpDir,
+    });
 
     expect(result.data.conflicts).toEqual([]);
     expect(result.data.issues).toEqual([]);

package/api/integration/authoring-checks.type.mjs

@@ -1,6 +1,11 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @file Colocated types for integration authoring diagnostics. */
+/**
+ * @file Colocated public types for integration authoring diagnostics.
+ * @input Stable response fields exposed by integration-authoring APIs.
+ * @output JSDoc typedefs consumed by declarations, commands, and callers.
+ * @position Public type boundary for integration diagnostics.
+ */
 
 /**
  * @typedef {object} IntegrationAuthoringOptions