@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db52d98

package/foundation/doc-compiler/compile.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Doc compiler — authored reference topics in, compiled nodes out.
+ * @file Doc compiler — authored docs in, compiled nodes out.
  *
  * @input A {@link ReferenceTopicInput}: one topic's own file and the files of
  *   the extensions merged onto it, each already through the authored-doc parser
@@ -16,21 +16,70 @@
  *   JSON form, the one `--json` output has always shown.
  * @position The one step between authored docs and every docs reader. The docs
  *   API, doctor and search read compiled nodes, and ./lenses.mjs turns them into
- *   response shapes. Internal to the CLI: the public way in is `docs()`.
+ *   response shapes. Every other doc kind (components, hooks, templates, themes,
+ *   and the CLI's self-docs) lowers through {@link lowerDoc}, which ./read.mjs
+ *   feeds. Internal to the CLI: the public way in is the docs API.
  */
 
+import {parseTemplate} from '../../authoring/doctypes/template/parse.mjs';
+import {parseTheme} from '../../authoring/doctypes/theme/parse.mjs';
 import {mergeTopic, problemsInTopic} from '../discovery/docs-discovery.mjs';
 import {
   sectionKey,
-  sectionKeyProblems,
+  sectionKeyErrors,
   sourceTitle,
   withSectionKeys,
   withSourceTitle,
 } from '../discovery/docs-section-key.mjs';
+import {diagnostic as rawDiagnostic} from './diagnostics.mjs';
+import {scrubPaths} from './source.mjs';
+import {overlayAuthoredDoc} from './overlays.mjs';
+import {parseReadableDoc} from './parse-readable.mjs';
+
+/**
+ * A compiler diagnostic whose message names files by package, never by their
+ * location on this machine.
+ * @param {string} code
+ * @param {Parameters<typeof rawDiagnostic>[1]} at
+ */
+function diagnostic(code, at) {
+  return rawDiagnostic(code, {
+    ...at,
+    message: scrubPaths(at.message) || '(the error had no message)',
+  });
+}
 
 /** Bumped whenever the shape of a compiled node changes. */
 export const COMPILED_DOC_SCHEMA_VERSION = 1;
 
+/** Every kind a compiled node has: one per authored doc kind a root reads. */
+export const COMPILED_DOC_KINDS = /** @type {const} */ ([
+  'component',
+  'function',
+  'reference',
+  'page',
+  'block',
+  'schema',
+  'command',
+  'enum',
+  'theme',
+  'namespace',
+]);
+
+/**
+ * The roots that read docs, and the kinds each may hold. A doc without a
+ * stamped `type` (the legacy form) takes its root's first kind.
+ * @type {Readonly<Record<string, readonly string[]>>}
+ */
+export const ROOT_KINDS = Object.freeze({
+  components: ['component'],
+  hooks: ['function'],
+  templates: ['page', 'block'],
+  themes: ['theme'],
+  'self-docs': ['command', 'function', 'schema', 'enum'],
+  tree: ['namespace', 'generic'],
+});
+
 /**
  * One authored file, as discovery loaded it.
  * @typedef {object} AuthoredFile
@@ -47,8 +96,14 @@ export const COMPILED_DOC_SCHEMA_VERSION = 1;
  * @property {string} provider the package that owns the topic
  * @property {string | null} replaces the topic it took the place of
  * @property {string | null} lang the overlay language, or null for authored text
+ * @property {string} [providerId] the owner's provider id; the package name
+ *   when absent. The base file's sections resolve their links against it.
  * @property {AuthoredFile} base
- * @property {Array<AuthoredFile & {provider: string}>} extensions in merge order
+ * @property {Array<AuthoredFile & {provider: string, providerId?: string}>} extensions
+ *   in merge order; each extension's sections resolve their links against its
+ *   own provider id
+ * @property {boolean} [tree] a guide the docs tree places: its `placement` is
+ *   read by the tree, so the topic reader accepts it
  */
 
 /**
@@ -69,10 +124,33 @@ export const COMPILED_DOC_SCHEMA_VERSION = 1;
  * @property {string | null} lang
  * @property {{provider: string, replaces: string | null, extensions: string[]}} provenance
  * @property {Record<string, string>} sourceTitles section key -> authored title
+ * @property {Record<string, string>} sectionProviders section key -> the
+ *   provider id that wrote the section: a topic merges sections from its base
+ *   and its extensions, and each section's links resolve against its own
+ *   provider (spec:AST-047 FR9)
  * @property {any} doc the topic: authored fields in authored order, every
  *   section keyed; a linked node's token references carry `resolved`
  */
 
+/** Which provider wrote a section, until lowering records it by key. */
+const SECTION_PROVIDER = Symbol('astryx.docs.sectionProvider');
+
+/**
+ * Mark each section of one authored file with the provider that wrote it. The
+ * overlay, the merge, and the key stamp copy the mark with the section.
+ * @param {any} doc
+ * @param {string} provider
+ * @returns {any}
+ */
+function markProvider(doc, provider) {
+  return {
+    ...doc,
+    sections: doc.sections.map((/** @type {any} */ section) =>
+      withSourceTitle({...section, [SECTION_PROVIDER]: provider}, sourceTitle(section)),
+    ),
+  };
+}
+
 /**
  * Lower one topic: overlay each file, merge the extensions in order, and stamp
  * every section with its key.
@@ -80,14 +158,24 @@ export const COMPILED_DOC_SCHEMA_VERSION = 1;
  * @returns {CompiledReferenceNode}
  */
 export function lowerReferenceTopic(input) {
-  let doc = readAuthoredFile(input.base);
+  let doc = markProvider(
+    readAuthoredFile(input.base, {placement: input.tree === true}),
+    input.providerId ?? input.provider,
+  );
   for (const extension of input.extensions) {
-    doc = mergeTopic(doc, readAuthoredFile(extension));
-    // Merging matches on keys, so this holds unless merge itself regresses.
-    const problems = sectionKeyProblems(doc.sections);
+    doc = mergeTopic(
+      doc,
+      markProvider(
+        readAuthoredFile(extension),
+        extension.providerId ?? extension.provider,
+      ),
+    );
+    // Explicit authored IDs remain strict. Legacy title-derived collisions are
+    // assigned deterministic compatibility keys after every extension merges.
+    const problems = sectionKeyErrors(doc.sections);
     if (problems.length > 0) {
       throw new Error(
-        `${extension.file}, extending ${input.id}, leaves two sections with one key: ${problems.join('; ')}`,
+        `${extension.file}, extending ${input.id}, leaves duplicate authored section IDs: ${problems.join('; ')}`,
       );
     }
   }
@@ -95,8 +183,12 @@ export function lowerReferenceTopic(input) {
   const keyed = withSectionKeys(doc);
   /** @type {Record<string, string>} */
   const sourceTitles = {};
+  /** @type {Record<string, string>} */
+  const sectionProviders = {};
   for (const section of keyed.sections) {
     sourceTitles[section.id] = sourceTitle(section);
+    sectionProviders[section.id] =
+      section[SECTION_PROVIDER] ?? input.providerId ?? input.provider;
   }
   return {
     schemaVersion: COMPILED_DOC_SCHEMA_VERSION,
@@ -110,7 +202,9 @@ export function lowerReferenceTopic(input) {
       extensions: input.extensions.map(extension => extension.provider),
     },
     sourceTitles,
-    // The authored title travels in sourceTitles; JSON drops the symbol.
+    sectionProviders,
+    // The authored title and provider travel in sourceTitles and
+    // sectionProviders; JSON drops the symbols.
     doc: asJson(keyed, input.id),
   };
 }
@@ -191,9 +285,12 @@ function asJson(value, topic) {
   try {
     return JSON.parse(JSON.stringify(value));
   } catch (err) {
-    throw new Error(
-      `${topic} cannot be compiled: ${err instanceof Error ? err.message : String(err)}`,
-      {cause: err},
+    throw Object.assign(
+      new Error(
+        `${topic} cannot be compiled: ${err instanceof Error ? err.message : String(err)}`,
+        {cause: err},
+      ),
+      {compilerCode: 'not_json'},
     );
   }
 }
@@ -204,13 +301,13 @@ function asJson(value, topic) {
  * @param {AuthoredFile} file
  * @returns {any}
  */
-function readAuthoredFile(file) {
+function readAuthoredFile(file, {placement = false} = {}) {
   if ('error' in file) throw file.error;
   const parsed = file.doc;
   if (!('sections' in parsed)) {
     throw new Error(`${file.file} is not a reference document.`);
   }
-  const problems = problemsInTopic(parsed);
+  const problems = problemsInTopic(parsed, {placement});
   if (problems.length > 0) {
     throw new Error(`${file.file} is invalid: ${problems.join('; ')}`);
   }
@@ -260,3 +357,202 @@ function applyOverlay(docs, translation) {
     }),
   };
 }
+
+/**
+ * @typedef {import('./diagnostics.mjs').CompilerDiagnostic} CompilerDiagnostic
+ */
+
+/**
+ * One authored doc of any kind but a reference topic, as its root loaded it.
+ * @typedef {object} DocFileInput
+ * @property {string} id the input's id: provider, root, and name
+ * @property {keyof typeof ROOT_KINDS} root
+ * @property {string} provider the package that contributes it
+ * @property {string} source `<package>/<path>` of the file
+ * @property {string | null} lang the overlay language, or null
+ * @property {AuthoredFile} file `doc` is the authored export, not a parse
+ *   result; `overlay` is the translation the module exports for `lang`
+ * @property {string} [label] how a parse error names the file (default: its
+ *   file name)
+ * @property {boolean} [useParsed] carry the parser's result instead of the
+ *   authored export, for a reader that has always read the checked value
+ */
+
+/**
+ * The parser that checks a root's docs. Templates and themes have their own;
+ * every other root dispatches on the stamped type.
+ * @param {string} root
+ * @returns {(input: unknown, label?: string) => any}
+ */
+export function parserFor(root) {
+  if (root === 'themes') return parseTheme;
+  if (root === 'templates') return parseTemplate;
+  return parseReadableDoc;
+}
+
+/**
+ * A compiled node for any kind but a reference topic.
+ * @typedef {object} CompiledDocNode
+ * @property {number} schemaVersion
+ * @property {Exclude<typeof COMPILED_DOC_KINDS[number], 'reference'>} kind
+ * @property {'lowered'} stage
+ * @property {string} id
+ * @property {string | null} lang
+ * @property {{provider: string, source: string}} provenance
+ * @property {any} doc the authored doc, overlaid for `lang`, as JSON carries
+ *   it: key order kept, `undefined` and functions dropped
+ */
+
+/**
+ * The result of lowering one doc.
+ *
+ * `view` is the doc as readers have always read it: the authored export (or,
+ * where a reader has always read it, the parser's result), with its
+ * translation laid over it, not copied and not converted. Readers print from
+ * the view, so nothing they print depends on JSON. `node` is the sealed,
+ * JSON-only form a whole-project compile collects.
+ *
+ * @typedef {object} LoweredDoc
+ * @property {any} [view] absent when the file could not be read
+ * @property {CompiledDocNode | null} node null when not asked for, or when a
+ *   problem is fatal to the node
+ * @property {CompilerDiagnostic[]} diagnostics
+ * @property {boolean} [loadFailed] importing the file threw
+ * @property {unknown} [loadFailure] what importing the file threw (any value,
+ *   `undefined` included)
+ * @property {boolean} [missing] the file exports no doc
+ * @property {null | undefined} [missingValue] the empty export, as the reader
+ *   picked it
+ * @property {boolean} [failed] the kind's parser threw
+ * @property {unknown} [failure] what the kind's parser threw
+ * @property {boolean} [overlayFailed] laying the translation over threw
+ * @property {unknown} [overlayFailure] what laying the translation over threw
+ */
+
+/**
+ * Lower one doc of any kind but a reference topic.
+ *
+ * With `check`, the doc is held to its kind's parser, and a failure is
+ * recorded, not fatal: readers that never checked docs keep reading it, and a
+ * checked reader turns it into the error it has always thrown. A doc stamped
+ * with a kind its root does not read keeps its root's kind and carries a
+ * `wrong_kind` diagnostic. With `node`, the view is also carried as JSON; a
+ * value JSON cannot hold withdraws the node, never the view.
+ *
+ * @param {DocFileInput} input
+ * @param {{check?: boolean, node?: boolean}} [options]
+ * @returns {LoweredDoc}
+ */
+export function lowerDoc(input, {check = true, node: wantNode = true} = {}) {
+  const {file} = input;
+  const at = {provider: input.provider, source: input.source};
+  /** @type {CompilerDiagnostic[]} */
+  const diagnostics = [];
+  if ('error' in file) {
+    diagnostics.push(
+      diagnostic('load_failed', {
+        ...at,
+        message: `${file.file} could not be loaded: ${messageOf(file.error)}`,
+      }),
+    );
+    return {node: null, diagnostics, loadFailed: true, loadFailure: file.error};
+  }
+  if (file.doc == null) {
+    diagnostics.push(
+      diagnostic('missing_export', {
+        ...at,
+        message: `${file.file} exports no doc.`,
+      }),
+    );
+    return {node: null, diagnostics, missing: true, missingValue: file.doc};
+  }
+  const allowed = ROOT_KINDS[input.root];
+  if (!allowed) throw new Error(`No doc root is named "${input.root}".`);
+  const stamped =
+    typeof file.doc === 'object' && 'type' in file.doc
+      ? file.doc.type
+      : undefined;
+  const kindFits = stamped === undefined || allowed.includes(stamped);
+  if (!kindFits) {
+    diagnostics.push(
+      diagnostic('wrong_kind', {
+        ...at,
+        message: `${file.file} is stamped type ${JSON.stringify(stamped)}, which the ${input.root} root does not read (it reads ${allowed.join(', ')}).`,
+      }),
+    );
+  }
+  /** @type {LoweredDoc} */
+  const result = {node: null, diagnostics};
+  let view = file.doc;
+  // A theme descriptor is read statically; its parse result is the doc.
+  if (check || input.root === 'themes') {
+    try {
+      const parsed = parserFor(input.root)(file.doc, input.label ?? file.file);
+      if (input.useParsed || input.root === 'themes') view = parsed;
+    } catch (error) {
+      result.failed = true;
+      result.failure = error;
+      diagnostics.push(
+        diagnostic('invalid_doc', {...at, message: messageOf(error)}),
+      );
+    }
+  }
+  if ('overlayError' in file) {
+    result.overlayFailed = true;
+    result.overlayFailure = file.overlayError;
+  } else if (file.overlay) {
+    try {
+      view = overlayAuthoredDoc(view, file.overlay);
+    } catch (error) {
+      result.overlayFailed = true;
+      result.overlayFailure = error;
+    }
+  }
+  if (result.overlayFailed) {
+    diagnostics.push(
+      diagnostic('overlay_failed', {
+        ...at,
+        message: `${file.file}'s translation could not be applied: ${messageOf(result.overlayFailure)}`,
+      }),
+    );
+    return result;
+  }
+  result.view = view;
+  if (!wantNode) return result;
+  let json;
+  try {
+    const text = JSON.stringify(view);
+    if (text === undefined) throw new TypeError('the doc is not a JSON value');
+    json = JSON.parse(text);
+  } catch (error) {
+    diagnostics.push(
+      diagnostic('not_json', {
+        ...at,
+        message: `${file.file} cannot be compiled: ${messageOf(error)}`,
+      }),
+    );
+    return result;
+  }
+  result.node = {
+    schemaVersion: COMPILED_DOC_SCHEMA_VERSION,
+    kind: /** @type {CompiledDocNode['kind']} */ (
+      kindFits && stamped !== undefined ? stamped : allowed[0]
+    ),
+    stage: 'lowered',
+    id: input.id,
+    lang: input.lang,
+    provenance: {provider: input.provider, source: input.source},
+    doc: json,
+  };
+  return result;
+}
+
+/** @param {unknown} error */
+function messageOf(error) {
+  // Any value can be thrown; describing one must never throw in its place.
+  try {
+    return error instanceof Error ? String(error.message) : String(error);
+  } catch {
+    return Object.prototype.toString.call(error);
+  }
+}

package/foundation/doc-compiler/diagnostics.d.mts

@@ -0,0 +1,126 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @param {string} code
+ * @param {object} at
+ * @param {string | null} [at.provider]
+ * @param {string | null} [at.source]
+ * @param {string | null} [at.field]
+ * @param {string} at.message
+ * @returns {CompilerDiagnostic}
+ */
+export function diagnostic(code: string, { provider, source, field, message }: {
+    provider?: string | null | undefined;
+    source?: string | null | undefined;
+    field?: string | null | undefined;
+    message: string;
+}): CompilerDiagnostic;
+/**
+ * Diagnostics in one order, whatever order the phases found them in: by
+ * source, then phase, then code, field, and message.
+ * @param {CompilerDiagnostic[]} list
+ * @returns {CompilerDiagnostic[]} a new array
+ */
+export function sortDiagnostics(list: CompilerDiagnostic[]): CompilerDiagnostic[];
+/**
+ * What is wrong with a value that claims to be a diagnostic, or null. A known
+ * code must carry its own phase, severity, scope, and remediation: a reader
+ * never reinterprets them.
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function diagnosticProblem(value: unknown): string | null;
+/**
+ * A `<package>/<path>` that names no location on one machine: not absolute,
+ * no drive letter or URL scheme, no backslash, no `..` segment.
+ * @param {string} source
+ * @returns {boolean}
+ */
+export function isPortableSource(source: string): boolean;
+/**
+ * @file Compiler diagnostics — one shape for every problem the doc compiler
+ *   finds.
+ *
+ * @input A diagnostic code, the package and file it concerns, and a message.
+ * @output A plain-JSON diagnostic: a stable code, the phase that found it,
+ *   severity, provider, source, field, message, remediation, and the scope of
+ *   what it invalidates. Lists sort into one deterministic order.
+ * @position Shared by every compiler phase: listing inputs, loading, parsing,
+ *   overlaying, lowering, linking, serializing, and reading a bundle back. A
+ *   code fixes its phase, severity, scope, and remediation, so no phase or
+ *   reader can report the same problem two ways or downgrade it.
+ */
+/** Compiler phases, in the order a descriptor passes through them. */
+export const DIAGNOSTIC_PHASES: readonly ["discover", "load", "parse", "overlay", "lower", "link", "serialize", "bundle"];
+/**
+ * What a failure invalidates: the one node it concerns, or the whole
+ * compilation (a bundle that cannot be read at all).
+ * @typedef {'node' | 'compilation'} DiagnosticScope
+ */
+/**
+ * @typedef {typeof DIAGNOSTIC_PHASES[number]} DiagnosticPhase
+ * @typedef {'error' | 'warning'} DiagnosticSeverity
+ */
+/**
+ * @typedef {object} CompilerDiagnostic
+ * @property {string} code stable; one of {@link DIAGNOSTIC_CODES}
+ * @property {DiagnosticPhase} phase
+ * @property {DiagnosticSeverity} severity
+ * @property {DiagnosticScope} scope
+ * @property {string | null} provider the package the problem is in
+ * @property {string | null} source `<package>/<path>` of the file, never a
+ *   machine path
+ * @property {string | null} field the field or reference at fault, when known
+ * @property {string} message
+ * @property {string} remediation what to do about it
+ */
+/**
+ * @typedef {object} DiagnosticRule
+ * @property {DiagnosticPhase} phase
+ * @property {DiagnosticSeverity} severity
+ * @property {DiagnosticScope} scope
+ * @property {string} remediation
+ */
+/** Every code the compiler emits, with the facts it fixes. */
+export const DIAGNOSTIC_CODES: Readonly<Record<string, DiagnosticRule>>;
+/**
+ * What a failure invalidates: the one node it concerns, or the whole
+ * compilation (a bundle that cannot be read at all).
+ */
+export type DiagnosticScope = "node" | "compilation";
+export type DiagnosticPhase = (typeof DIAGNOSTIC_PHASES)[number];
+export type DiagnosticSeverity = "error" | "warning";
+export type CompilerDiagnostic = {
+    /**
+     * stable; one of {@link DIAGNOSTIC_CODES}
+     */
+    code: string;
+    phase: DiagnosticPhase;
+    severity: DiagnosticSeverity;
+    scope: DiagnosticScope;
+    /**
+     * the package the problem is in
+     */
+    provider: string | null;
+    /**
+     * `<package>/<path>` of the file, never a
+     * machine path
+     */
+    source: string | null;
+    /**
+     * the field or reference at fault, when known
+     */
+    field: string | null;
+    message: string;
+    /**
+     * what to do about it
+     */
+    remediation: string;
+};
+export type DiagnosticRule = {
+    phase: DiagnosticPhase;
+    severity: DiagnosticSeverity;
+    scope: DiagnosticScope;
+    remediation: string;
+};