@astryxdesign/cli 0.6.3 → 0.6.4-canary.10dd683

package/api/integration/add-helpers.mjs

@@ -5,7 +5,8 @@
  *
  * Hosts the atomic staged-write transaction, package.json files-array
  * maintenance, package-dir resolution, and project-path normalization that
- * every `integration add <kind>` command needs. Stateless and side-effect-free
+ * every `integration add <kind>` command needs. `theme add` and `theme build`
+ * write through the same transaction. Stateless and side-effect-free
  * outside of {@link applyWrites}.
  */
 
@@ -40,7 +41,7 @@ export function findPackageDir(startDir) {
 /**
  * @typedef {object} WritePlan
  * @property {string} path
- * @property {string} contents
+ * @property {string | Buffer} contents a Buffer is written byte for byte
  * @property {boolean} createOnly
  * @property {Buffer} [expectedOriginal] bytes captured before validation;
  *   a different current file is a concurrent edit and must never be overwritten
@@ -192,21 +193,29 @@ export function packageJsonUpdate(
 
 // ── Atomic staged-write transaction ─────────────────────────────────
 
-/** @param {string} file */
+/**
+ * @param {string} file
+ * @returns {boolean} false when the file is still there
+ */
 function removeTemporary(file) {
   try {
     fs.rmSync(file, {force: true});
+    return true;
   } catch {
     // Best effort. The transaction error remains the actionable failure.
+    return false;
   }
 }
 
 /**
  * Restore writes that already published.  Best-effort so callers preserve
- * the original actionable error.
+ * the original actionable error; returns every path it could not put back.
  * @param {Array<WritePlan & {temporary: string, original: Buffer|null, mode: number}>} published
+ * @returns {string[]}
  */
 function rollbackWrites(published) {
+  /** @type {string[]} */
+  const unrestored = [];
   for (const plan of [...published].reverse()) {
     let restore = null;
     try {
@@ -225,12 +234,18 @@ function rollbackWrites(published) {
         fs.renameSync(restore, plan.path);
         restore = null;
       }
-    } catch {
-      // Best effort. A concurrent edit belongs to its writer, not this rollback.
+    } catch (error) {
+      // A created file that is already gone needs nothing. Any other failure
+      // leaves this call's bytes, or no bytes, where the original was.
+      const gone =
+        error instanceof Error &&
+        /** @type {NodeJS.ErrnoException} */ (error).code === 'ENOENT';
+      if (!(gone && plan.original == null)) unrestored.push(plan.path);
     } finally {
       if (restore != null) removeTemporary(restore);
     }
   }
+  return unrestored;
 }
 
 /** @param {string} file */
@@ -325,10 +340,22 @@ export function applyWrites(plans) {
       }
       published.push(plan);
     }
-    return () => rollbackWrites(published);
+    return () => {
+      rollbackWrites(published);
+    };
   } catch (error) {
-    for (const plan of staged) removeTemporary(plan.temporary);
-    rollbackWrites(published);
+    const leftovers = staged
+      .filter(plan => !removeTemporary(plan.temporary))
+      .map(plan => plan.temporary);
+    const unrestored = rollbackWrites(published);
+    if (error instanceof Error) {
+      if (unrestored.length > 0) {
+        error.message += ` Could not restore: ${unrestored.join(', ')}.`;
+      }
+      if (leftovers.length > 0) {
+        error.message += ` Could not remove temporary files: ${leftovers.join(', ')}.`;
+      }
+    }
     throw error;
   }
 }

package/api/integration/add-theme.mjs

@@ -1,9 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx integration add theme` — scaffold one valid source theme into
- * an integration package, update its theme catalog, and declare the root on
- * first use.
+ * @file `astryx integration add theme` — scaffold one strongly typed,
+ * same-stem source/descriptor pair into an integration package and declare the
+ * themes root on first use.
  */
 
 import * as fs from 'node:fs';
@@ -15,16 +15,14 @@ import {
   PathSafetyError,
   sanitizeName,
 } from '../../foundation/fs/path-safety.mjs';
-import {
-  discoverThemeCatalog,
-  THEME_MANIFEST_BASENAME,
-} from '../../foundation/discovery/theme-discovery.mjs';
+import {discoverThemeDirectory} from '../../foundation/discovery/theme-discovery.mjs';
 import {
   findLocalIntegrationManifestOrNull,
   IntegrationRootConflictError,
   patchIntegrationRoot,
 } from '../../foundation/integrations/manifest-writer.mjs';
 import {loadManifestObject} from '../../foundation/integrations/integrations.mjs';
+import {themeDescriptorSource} from '../../foundation/integrations/theme-descriptor.mjs';
 import {assertContributionVisible} from '../../foundation/integrations/contribution-inventory.mjs';
 import {
   applyWrites,
@@ -70,6 +68,7 @@ function themeIdentity(slug) {
     displayName,
     exportName: `${identifier}Theme`,
     entry: `${identifier}Theme.ts`,
+    descriptor: `${identifier}Theme.doc.mjs`,
   };
 }
 
@@ -78,9 +77,20 @@ function themeSource(identity) {
   return `import {defineTheme} from '@astryxdesign/core/theme';\n\nexport const ${identity.exportName} = defineTheme({\n  name: '${identity.slug}',\n});\n`;
 }
 
+/** @param {{slug: string, displayName: string}} identity */
+function themeDescriptor(identity) {
+  return themeDescriptorSource({
+    type: 'theme',
+    name: identity.slug,
+    displayName: identity.displayName,
+    description: `${identity.displayName} theme.`,
+    maintained: true,
+  });
+}
+
 /**
- * Read the bytes back through the same integration-theme discovery seam Project
- * uses. A write is not successful until the requested slug resolves.
+ * Read bytes back through the same discovery seam Project uses. A write is not
+ * successful until the requested slug resolves.
  * @param {string} packageDir
  * @param {string} manifestFile
  * @param {string} owner
@@ -176,6 +186,9 @@ export async function integrationAddTheme(name, options = {}) {
       dryRun: true,
       createIfMissing: true,
     });
+    if (fs.existsSync(root)) {
+      discoverThemeDirectory(root, owner);
+    }
   } catch (error) {
     if (error instanceof IntegrationRootConflictError) {
       throw new AstryxError(
@@ -197,72 +210,29 @@ export async function integrationAddTheme(name, options = {}) {
   const sourceFile = assertWithin(identity.entry, themeDir, {
     label: 'theme source file',
   });
-  if (fs.existsSync(sourceFile)) {
-    throw new AstryxError(
-      `Refusing to overwrite existing file ${projectPath(path.relative(packageDir, sourceFile))}.`,
-      undefined,
-      ERROR_CODES.ERR_FILE_EXISTS,
-    );
-  }
-
-  const catalogFile = assertWithin(THEME_MANIFEST_BASENAME, root, {
-    label: 'theme catalog manifest',
+  const descriptorFile = assertWithin(identity.descriptor, themeDir, {
+    label: 'theme descriptor file',
   });
-  /** @type {{version: 1, themes: Array<Record<string, unknown>>, [key: string]: unknown}} */
-  let catalog = {version: 1, themes: []};
-  /** @type {Buffer|null} */
-  let catalogOriginal = null;
-  if (fs.existsSync(catalogFile)) {
-    try {
-      catalogOriginal = fs.readFileSync(catalogFile);
-      catalog = JSON.parse(catalogOriginal.toString('utf-8'));
-      // The discovery seam is the schema/source-of-truth validator. The write
-      // plan carries catalogOriginal, so any concurrent change between this read
-      // and publish is refused rather than overwritten with this snapshot.
-      discoverThemeCatalog(root, owner);
-    } catch (error) {
+  // An existing folder is filled; only a file this would write is refused.
+  for (const file of [sourceFile, descriptorFile]) {
+    if (fs.existsSync(file)) {
       throw new AstryxError(
-        error instanceof Error ? error.message : String(error),
+        `Refusing to overwrite existing file ${projectPath(path.relative(packageDir, file))}.`,
         undefined,
-        ERROR_CODES.ERR_THEME_INVALID,
+        ERROR_CODES.ERR_FILE_EXISTS,
       );
     }
   }
-  if (
-    catalog.themes.some(
-      theme =>
-        typeof theme.slug === 'string' &&
-        theme.slug.toLowerCase() === identity.slug.toLowerCase(),
-    )
-  ) {
-    throw new AstryxError(
-      `Theme "${identity.slug}" already exists in ${projectPath(path.relative(packageDir, catalogFile))}.`,
-      undefined,
-      ERROR_CODES.ERR_FILE_EXISTS,
-    );
-  }
-
-  catalog.themes.push({
-    slug: identity.slug,
-    displayName: identity.displayName,
-    description: `${identity.displayName} theme.`,
-    maintained: true,
-    entry: identity.entry,
-    exportName: identity.exportName,
-    files: [identity.entry],
-  });
 
   /** @type {import('./add-helpers.mjs').WritePlan[]} */
-  const plans = [];
-  plans.push(
+  const plans = [
     {path: sourceFile, contents: themeSource(identity), createOnly: true},
     {
-      path: catalogFile,
-      contents: `${JSON.stringify(catalog, null, 2)}\n`,
-      createOnly: catalogOriginal == null,
-      expectedOriginal: catalogOriginal ?? undefined,
+      path: descriptorFile,
+      contents: themeDescriptor(identity),
+      createOnly: true,
     },
-  );
+  ];
   const packageUpdate = packageJsonUpdate(
     packageFile,
     rootPath,

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},