@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.f04b501

package/api/doctor/doctor.d.mts

@@ -84,6 +84,58 @@ export function checkPeerDeps(ctx: DoctorContext): DoctorCheck;
  * @returns {DoctorCheck}
  */
 export function checkPackageManager(ctx: DoctorContext): DoctorCheck;
+/**
+ * Check 6b — every contributing integration owns its provider identity.
+ *
+ * Artifact and document IDs are provider-scoped, so a package that claims a
+ * provider ID an earlier-loaded package already holds is loaded inert: its
+ * components, templates, themes, docs, and codemods are withdrawn while the
+ * earlier package keeps contributing. That can be a deliberate transition
+ * (a renamed package installed beside its predecessor), so it warns rather
+ * than fails, but it is never allowed to happen quietly.
+ *
+ * @param {DoctorContext} ctx
+ * @returns {DoctorCheck}
+ */
+export function checkProviderIdentity(ctx: DoctorContext): DoctorCheck;
+/**
+ * Every authoring self-doc is reachable from `astryx docs authoring`, loads,
+ * and fits in one read, and every type `@astryxdesign/cli/authoring` exports
+ * has its doc there: the self-doc beside the module that declares it. The
+ * audits are imported here, inside the try, so a malformed self-doc is
+ * reported rather than taking Doctor down.
+ * @param {DoctorContext} [_ctx]
+ * @param {{root?: string, sources?: string[], topicKeys?: Set<string> | null}} [options]
+ *   Another authoring tree, list, or topic index to audit (for tests).
+ * @returns {Promise<DoctorCheck>}
+ */
+export function checkAuthoringDocs(_ctx?: DoctorContext, options?: {
+    root?: string;
+    sources?: string[];
+    topicKeys?: Set<string> | null;
+}): Promise<DoctorCheck>;
+/**
+ * Every command, API function, schema, and enum doc the CLI ships declares a
+ * namespace, and the topic that namespace names reads it: `astryx docs cli`
+ * for `cli/commands` and `cli/api`, `astryx docs authoring` for `authoring`.
+ * @param {DoctorContext | Partial<DoctorContext>} _ctx
+ * @param {{root?: string, sources?: string[], authoringSources?: string[]}} [options]
+ *   test seams: the CLI root, the docs to audit, and the authoring topic's list
+ * @returns {Promise<DoctorCheck>}
+ */
+export function checkCliDocs(_ctx: DoctorContext | Partial<DoctorContext>, options?: {
+    root?: string;
+    sources?: string[];
+    authoringSources?: string[];
+}): Promise<DoctorCheck>;
+/**
+ * Every topic reads progressively, in every language it ships: it loads, its
+ * section index and each of its sections fit in one read, and no contributed
+ * doc is invalid.
+ * @param {DoctorContext | Partial<DoctorContext>} ctx
+ * @returns {Promise<DoctorCheck>}
+ */
+export function checkDocsProgressiveDisclosure(ctx: DoctorContext | Partial<DoctorContext>): Promise<DoctorCheck>;
 /**
  * Run all diagnostic checks and return a structured report.
  *
@@ -169,9 +221,27 @@ export type DoctorContext = {
      * read at all.
      */
     integrations?: import("../../foundation/integrations/integrations.mjs").LoadedIntegration[] | null | undefined;
+    /**
+     * - The topics a docs read sees.
+     */
+    docsCatalog?: DocsCatalog | null | undefined;
+    /**
+     * `invalid_doc` issues from the project's contributed docs.
+     */
+    docsCatalogIssues?: {
+        package?: string;
+        code: string;
+        message: string;
+    }[] | undefined;
+    /**
+     * - Why the project's docs catalog
+     * could not be built, when it could not.
+     */
+    docsCatalogError?: string | null | undefined;
     /**
      * - Error thrown while resolving the config
      * path (e.g. multiple config files present), surfaced by checkConfig as a FAIL.
      */
     configError?: Error | null | undefined;
 };
+import { DocsCatalog } from '../../foundation/discovery/docs-discovery.mjs';

package/api/doctor/doctor.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'doctor',
+  namespace: 'cli/api',
   displayName: 'doctor()',
   summary: 'Read-only project + environment health check.',
   description:

package/api/doctor/doctor.mjs

@@ -27,6 +27,15 @@ import {MIN_NODE_VERSION, isNodeVersionSupported} from '../../foundation/env/nod
 import {CLI_ROOT, findCoreDir, findInstalledPackage} from '../../foundation/fs/paths.mjs';
 import {explainPackageManager, getCliInvocation} from '../../foundation/env/package-manager.mjs';
 import {findConfigPath, Project} from '../../foundation/config/project.mjs';
+import {DocsCatalog} from '../../foundation/discovery/docs-discovery.mjs';
+import {buildDocsIndexData} from '../../foundation/discovery/docs-section-key.mjs';
+import {
+  DOC_OUTPUT_BUDGET_BYTES,
+  docsIndexBytes,
+  oversizedDocSections,
+} from '../../foundation/discovery/docs-output-budget.mjs';
+import {compileTopic, lowerTopic, overlayLanguages} from '../docs/_adapter.mjs';
+import {detailView, indexView} from '../../foundation/doc-compiler/lenses.mjs';
 import {semverCompare, isValidSemver, satisfiesRange} from '../../foundation/env/semver.mjs';
 
 /**
@@ -52,6 +61,11 @@ import {semverCompare, isValidSemver, satisfiesRange} from '../../foundation/env
  * @property {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]|null} [integrations]
  *   Every integration the project loaded, or null when the project could not be
  *   read at all.
+ * @property {DocsCatalog|null} [docsCatalog] - The topics a docs read sees.
+ * @property {Array<{package?: string, code: string, message: string}>} [docsCatalogIssues]
+ *   `invalid_doc` issues from the project's contributed docs.
+ * @property {string|null} [docsCatalogError] - Why the project's docs catalog
+ *   could not be built, when it could not.
  * @property {Error|null} [configError] - Error thrown while resolving the config
  *   path (e.g. multiple config files present), surfaced by checkConfig as a FAIL.
  */
@@ -627,6 +641,372 @@ export function checkPackageManager(ctx) {
   };
 }
 
+/**
+ * Check 6b — every contributing integration owns its provider identity.
+ *
+ * Artifact and document IDs are provider-scoped, so a package that claims a
+ * provider ID an earlier-loaded package already holds is loaded inert: its
+ * components, templates, themes, docs, and codemods are withdrawn while the
+ * earlier package keeps contributing. That can be a deliberate transition
+ * (a renamed package installed beside its predecessor), so it warns rather
+ * than fails, but it is never allowed to happen quietly.
+ *
+ * @param {DoctorContext} ctx
+ * @returns {DoctorCheck}
+ */
+export function checkProviderIdentity(ctx) {
+  const id = 'provider-identity';
+  const label = 'Integration provider identity';
+
+  if (ctx.integrations == null) {
+    return {
+      id,
+      label,
+      status: 'info',
+      message: 'Skipped — the project configuration could not be read.',
+    };
+  }
+
+  const conflicts = ctx.integrations.filter(
+    integration => integration.__providerConflict,
+  );
+  if (conflicts.length > 0) {
+    return {
+      id,
+      label,
+      status: 'warn',
+      message: conflicts
+        .map(integration => integration.__providerConflict?.message)
+        .join(' '),
+      fix:
+        'Give each integration its own `providerId` in astryx.integration.*. ' +
+        "A renamed package may keep its predecessor's ID only when the " +
+        'predecessor is no longer installed.',
+    };
+  }
+
+  const count = ctx.integrations.filter(
+    integration =>
+      integration.providerId != null && integration.__loadError == null,
+  ).length;
+  if (count === 0) {
+    return {
+      id,
+      label,
+      status: 'info',
+      message: 'None — no loaded integration has a provider identity.',
+    };
+  }
+  return {
+    id,
+    label,
+    status: 'pass',
+    message:
+      count === 1
+        ? '1 loaded integration has its own provider ID.'
+        : `${count} loaded integrations each have their own provider ID.`,
+  };
+}
+
+/** @param {number} bytes */
+const kilobytes = bytes => `${Math.ceil(bytes / 1024)} KB`;
+
+/**
+ * @param {string[]} problems
+ * @returns {string}
+ */
+function joinProblems(problems) {
+  return problems.length === 1
+    ? problems[0]
+    : `${problems.length} problems: ${problems.join('; ')}`;
+}
+
+/** How the self-doc audit's problems are fixed. */
+const AUTHORING_DOCS_FIX =
+  'List every authoring self-doc in AUTHORING_SELF_DOCS, fix the one that fails to load, and split a section that is too large.';
+
+/** How the public-surface audit's problems are fixed. */
+const AUTHORING_SURFACE_FIX =
+  'Put a self-doc beside each module whose types @astryxdesign/cli/authoring exports and list it in AUTHORING_SELF_DOCS; export what each listed self-doc documents, or remove that self-doc.';
+
+/** Types one problem names before it counts the rest. */
+const NAMED_TYPES = 40;
+
+/**
+ * @param {string[]} names
+ * @returns {string}
+ */
+function nameTypes(names) {
+  return names.length <= NAMED_TYPES
+    ? names.join(', ')
+    : `${names.slice(0, NAMED_TYPES).join(', ')} and ${names.length - NAMED_TYPES} more`;
+}
+
+/**
+ * The section keys `astryx docs authoring --index` lists, read the way that
+ * command reads them.
+ * @returns {Promise<{keys: Set<string>} | {keys: null, error: string}>}
+ */
+async function authoringTopicKeys() {
+  try {
+    const catalog = DocsCatalog.fromBuiltins();
+    const entry = catalog.resolve('authoring');
+    if (!entry) return {keys: null, error: 'it is not a built-in topic'};
+    const index = indexView(await lowerTopic(catalog, entry));
+    return {keys: new Set(index.sections.map(section => section.id))};
+  } catch (err) {
+    return {
+      keys: null,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof import('../../foundation/discovery/authoring-surface.mjs').auditAuthoringSurface>>} surface
+ * @returns {string[]}
+ */
+function surfaceProblems(surface) {
+  /** @type {string[]} */
+  const problems = [];
+  if (surface.types === 0 && surface.untraced.length === 0) {
+    problems.push(
+      '@astryxdesign/cli/authoring exports no types, so nothing was compared with `astryx docs authoring`',
+    );
+  }
+  for (const {module, names, reason, source, key} of surface.unreadable) {
+    const why =
+      reason === 'no-self-doc'
+        ? `no self-doc sits beside ${module}`
+        : reason === 'unregistered'
+          ? `${source} is not listed in AUTHORING_SELF_DOCS`
+          : reason === 'failed'
+            ? `${source} does not load`
+            : `${source} renders section "${key}", which the topic's index does not list`;
+    problems.push(
+      `${nameTypes(names)} from ${module} ${names.length === 1 ? 'has' : 'have'} no doc in \`astryx docs authoring\`: ${why}`,
+    );
+  }
+  for (const {name, reason} of surface.untraced) {
+    problems.push(
+      `${name} cannot be traced to the module that declares it: ${reason}`,
+    );
+  }
+  for (const {source, subject} of surface.unmatched) {
+    problems.push(
+      subject
+        ? `${source} documents ${subject}, which @astryxdesign/cli/authoring does not export`
+        : `${source} documents no type @astryxdesign/cli/authoring exports`,
+    );
+  }
+  return problems;
+}
+
+/**
+ * Every authoring self-doc is reachable from `astryx docs authoring`, loads,
+ * and fits in one read, and every type `@astryxdesign/cli/authoring` exports
+ * has its doc there: the self-doc beside the module that declares it. The
+ * audits are imported here, inside the try, so a malformed self-doc is
+ * reported rather than taking Doctor down.
+ * @param {DoctorContext} [_ctx]
+ * @param {{root?: string, sources?: string[], topicKeys?: Set<string> | null}} [options]
+ *   Another authoring tree, list, or topic index to audit (for tests).
+ * @returns {Promise<DoctorCheck>}
+ */
+export async function checkAuthoringDocs(_ctx, options = {}) {
+  const id = 'authoring-docs';
+  const label = 'Authoring docs';
+  try {
+    const {auditAuthoringSelfDocs} =
+      await import('../../foundation/discovery/authoring-self-docs.mjs');
+    const {auditAuthoringSurface} =
+      await import('../../foundation/discovery/authoring-surface.mjs');
+    const {root, sources} = options;
+    const audit = await auditAuthoringSelfDocs({root, sources});
+    const problems = [
+      ...audit.unreachable.map(
+        source => `${source} is not in \`astryx docs authoring\``,
+      ),
+      ...audit.failed.map(
+        ({source, error}) => `${source} failed to load: ${error}`,
+      ),
+      ...audit.oversized.map(
+        ({key, bytes}) =>
+          `authoring section "${key}" is ${kilobytes(bytes)}, over the ${kilobytes(DOC_OUTPUT_BUDGET_BYTES)} one read may return`,
+      ),
+    ];
+    const topic =
+      options.topicKeys === undefined
+        ? await authoringTopicKeys()
+        : {keys: options.topicKeys};
+    const surface = [
+      ...('error' in topic
+        ? [`\`astryx docs authoring\` could not be read: ${topic.error}`]
+        : []),
+      ...surfaceProblems(
+        await auditAuthoringSurface({root, sources, topicKeys: topic.keys}),
+      ),
+    ];
+    if (problems.length + surface.length > 0) {
+      return {
+        id,
+        label,
+        status: 'fail',
+        message: joinProblems([...problems, ...surface]),
+        fix: [
+          problems.length > 0 ? AUTHORING_DOCS_FIX : null,
+          surface.length > 0 ? AUTHORING_SURFACE_FIX : null,
+        ]
+          .filter(Boolean)
+          .join(' '),
+      };
+    }
+    return {
+      id,
+      label,
+      status: 'pass',
+      message: `All ${audit.sections} authoring schemas are readable in \`astryx docs authoring\`.`,
+    };
+  } catch (err) {
+    return {
+      id,
+      label,
+      status: 'fail',
+      message: `The authoring docs could not be audited: ${err instanceof Error ? err.message : String(err)}`,
+      fix: 'Reinstall @astryxdesign/cli.',
+    };
+  }
+}
+
+/** How the CLI-docs audit's problems are fixed. */
+const CLI_DOCS_FIX =
+  "Set `namespace` on each CLI doc to the one that reads it: cli/commands for a command, cli/api for an API function or the output schema, error codes, and response types, and authoring for a file an author writes (and list it in AUTHORING_SELF_DOCS).";
+
+/**
+ * Every command, API function, schema, and enum doc the CLI ships declares a
+ * namespace, and the topic that namespace names reads it: `astryx docs cli`
+ * for `cli/commands` and `cli/api`, `astryx docs authoring` for `authoring`.
+ * @param {DoctorContext | Partial<DoctorContext>} _ctx
+ * @param {{root?: string, sources?: string[], authoringSources?: string[]}} [options]
+ *   test seams: the CLI root, the docs to audit, and the authoring topic's list
+ * @returns {Promise<DoctorCheck>}
+ */
+export async function checkCliDocs(_ctx, options = {}) {
+  const id = 'cli-docs';
+  const label = 'CLI docs';
+  try {
+    const {auditCliSelfDocs} =
+      await import('../../foundation/discovery/cli-self-docs.mjs');
+    const audit = await auditCliSelfDocs(options);
+    const problems = [
+      ...audit.missing.map(
+        source =>
+          `${source} has no namespace, so no \`astryx docs\` topic reads it`,
+      ),
+      ...audit.unknown.map(
+        ({source, namespace}) =>
+          `${source} has namespace "${namespace}", which no \`astryx docs\` topic reads`,
+      ),
+      ...audit.misfiled.map(({message}) => message),
+      ...audit.failed.map(
+        ({source, error}) => `${source} failed to load: ${error}`,
+      ),
+      ...audit.keyProblems.map(problem => `\`astryx docs cli\`: ${problem}`),
+      ...audit.oversized.map(
+        ({key, bytes}) =>
+          `cli section "${key}" is ${kilobytes(bytes)}, over the ${kilobytes(DOC_OUTPUT_BUDGET_BYTES)} one read may return`,
+      ),
+    ];
+    if (problems.length > 0) {
+      return {
+        id,
+        label,
+        status: 'fail',
+        message: joinProblems(problems),
+        fix: CLI_DOCS_FIX,
+      };
+    }
+    return {
+      id,
+      label,
+      status: 'pass',
+      message: `All ${audit.docs} CLI docs are readable: ${audit.sections} in \`astryx docs cli\` and ${audit.authoring} in \`astryx docs authoring\`.`,
+    };
+  } catch (err) {
+    return {
+      id,
+      label,
+      status: 'fail',
+      message: `The CLI docs could not be audited: ${err instanceof Error ? err.message : String(err)}`,
+      fix: 'Reinstall @astryxdesign/cli.',
+    };
+  }
+}
+
+/**
+ * Every topic reads progressively, in every language it ships: it loads, its
+ * section index and each of its sections fit in one read, and no contributed
+ * doc is invalid.
+ * @param {DoctorContext | Partial<DoctorContext>} ctx
+ * @returns {Promise<DoctorCheck>}
+ */
+export async function checkDocsProgressiveDisclosure(ctx) {
+  const id = 'docs-progressive-disclosure';
+  const label = 'Documentation navigation and size';
+  const budget = kilobytes(DOC_OUTPUT_BUDGET_BYTES);
+  /** @type {string[]} */
+  const problems = [];
+  if (ctx.docsCatalogError) {
+    problems.push(`The docs catalog could not be built: ${ctx.docsCatalogError}`);
+  }
+  for (const issue of ctx.docsCatalogIssues ?? []) {
+    problems.push(`${issue.package ?? 'a contributed doc'}: ${issue.message}`);
+  }
+  let topics = 0;
+  const catalog = ctx.docsCatalog;
+  if (catalog) {
+    for (const entry of catalog.entries()) {
+      for (const lang of [null, ...overlayLanguages(entry)]) {
+        const where = lang ? `${entry.name} [${lang}]` : entry.name;
+        try {
+          const doc = detailView(await compileTopic(catalog, entry, lang));
+          if (lang == null) topics += 1;
+          const indexBytes = docsIndexBytes(buildDocsIndexData(doc));
+          if (indexBytes > DOC_OUTPUT_BUDGET_BYTES) {
+            problems.push(
+              `${where}: its section index is ${kilobytes(indexBytes)}, over the ${budget} one read may return`,
+            );
+          }
+          for (const over of oversizedDocSections(doc.sections)) {
+            problems.push(
+              `${where} ${over.key}: ${kilobytes(over.bytes)}, over the ${budget} one read may return`,
+            );
+          }
+        } catch (err) {
+          problems.push(
+            `${where}: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+      }
+    }
+  }
+  if (problems.length > 0) {
+    return {
+      id,
+      label,
+      status: 'fail',
+      message: joinProblems(problems),
+      fix: 'Fix the doc each problem names; split a section that is too large into smaller ones, each with its own key.',
+    };
+  }
+  return {
+    id,
+    label,
+    status: 'pass',
+    message: `${topics} topics: every section index and section fits in one ${budget} read.`,
+  };
+}
+
 /**
  * Ordered list of synchronous check functions. Append here to add a check.
  * (checkConfig is async and is awaited separately by {@link runChecks}.)
@@ -638,6 +1018,7 @@ export const SYNC_CHECKS = [
   checkVersionAlignment,
   checkThemes,
   checkImplicitIntegrations,
+  checkProviderIdentity,
   checkAgentDocs,
   checkPeerDeps,
   checkPackageManager,
@@ -669,11 +1050,28 @@ export async function runChecks(options = {}) {
   let configTheme = null;
   /** @type {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]|null} */
   let integrations = null;
+  // A docs read falls back to the built-in topics when the project cannot be
+  // read, so the docs checks do too; the config check reports the config.
+  /** @type {DocsCatalog|null} */
+  let docsCatalog = DocsCatalog.fromBuiltins();
+  /** @type {Array<{package?: string, code: string, message: string}>} */
+  let docsCatalogIssues = [];
+  /** @type {string|null} */
+  let docsCatalogError = null;
   try {
     const project = await Project.load(cwd);
     configTheme =
       /** @type {{theme?: string}} */ (project.config ?? {}).theme ?? null;
     integrations = project.loadedIntegrations;
+    try {
+      docsCatalog = await project.docs();
+      docsCatalogIssues = (await project.issues()).filter(
+        issue => issue.code === 'invalid_doc',
+      );
+    } catch (err) {
+      docsCatalog = null;
+      docsCatalogError = err instanceof Error ? err.message : String(err);
+    }
   } catch {
     // Best-effort: a missing/invalid config leaves configTheme null.
   }
@@ -686,6 +1084,9 @@ export async function runChecks(options = {}) {
     configPath,
     configTheme,
     integrations,
+    docsCatalog,
+    docsCatalogIssues,
+    docsCatalogError,
     configError,
   };
 
@@ -698,6 +1099,9 @@ export async function runChecks(options = {}) {
       checks.push(await checkConfig(ctx));
     }
   }
+  checks.push(await checkAuthoringDocs(ctx));
+  checks.push(await checkCliDocs(ctx));
+  checks.push(await checkDocsProgressiveDisclosure(ctx));
 
   const summary = {pass: 0, warn: 0, fail: 0, info: 0};
   for (const c of checks) summary[c.status] += 1;