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

package/foundation/doc-compiler/ir.mjs

@@ -0,0 +1,287 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The compiled-node contract and its sealed parser.
+ *
+ * @input Any value that claims to be a compiled reference node — typically one
+ *   read back from JSON.
+ * @output The same value once it validates; a thrown Error naming the problems
+ *   otherwise. An unsupported schema version fails with its own message before
+ *   anything else is checked.
+ * @position The load boundary for compiled nodes that did not come straight
+ *   from ./compile.mjs in this process. The value is returned as given, not
+ *   rebuilt, so key order (which response JSON follows) survives. A node is
+ *   plain JSON throughout, so nothing it holds can surprise a reader.
+ */
+
+import {SECTION_KEY_RE} from '../discovery/docs-section-key.mjs';
+import {COMPILED_DOC_SCHEMA_VERSION} from './compile.mjs';
+
+const NODE_FIELDS = new Set([
+  'schemaVersion',
+  'kind',
+  'stage',
+  'id',
+  'lang',
+  'provenance',
+  'sourceTitles',
+  'doc',
+]);
+const RESOLVED_FIELDS = new Set([
+  'status',
+  'topic',
+  'section',
+  'previewType',
+  'content',
+]);
+
+/** How many problems one message lists before it stops. */
+const MAX_PROBLEMS = 10;
+
+/** @param {unknown} value @returns {value is Record<string, any>} */
+const isRecord = value =>
+  value != null && typeof value === 'object' && !Array.isArray(value);
+
+/** @param {unknown} value @returns {value is string} */
+const isText = value => typeof value === 'string' && value !== '';
+
+/**
+ * A package name, never a location: provenance must not leak a path.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+const isPackageName = value =>
+  isText(value) &&
+  !value.startsWith('/') &&
+  !value.startsWith('.') &&
+  !value.startsWith('\\') &&
+  !value.startsWith('file:') &&
+  !/^[A-Za-z]:[\\/]/.test(value);
+
+/**
+ * Validate a compiled reference node.
+ * @param {unknown} value
+ * @returns {import('./compile.mjs').CompiledReferenceNode}
+ */
+export function parseCompiledReferenceNode(value) {
+  const node = /** @type {any} */ (value);
+  if (node?.schemaVersion !== COMPILED_DOC_SCHEMA_VERSION) {
+    throw new Error(
+      `Compiled doc schema version ${JSON.stringify(node?.schemaVersion)} is not supported; this CLI reads version ${COMPILED_DOC_SCHEMA_VERSION}. Compile the docs again with this CLI.`,
+    );
+  }
+  const problems = jsonProblems(node, 'node');
+  if (problems.length === 0) problems.push(...structureProblems(node));
+  if (problems.length > 0) {
+    throw new Error(
+      `Invalid compiled doc node: ${problems.slice(0, MAX_PROBLEMS).join('; ')}`,
+    );
+  }
+  return node;
+}
+
+/**
+ * Where a value stops being plain JSON: anything but null, booleans, finite
+ * numbers, strings, arrays and plain objects; a symbol key; or a cycle.
+ * @param {unknown} value
+ * @param {string} at
+ * @param {Set<object>} [ancestors]
+ * @param {string[]} [out]
+ * @returns {string[]}
+ */
+function jsonProblems(value, at, ancestors = new Set(), out = []) {
+  if (out.length >= MAX_PROBLEMS) return out;
+  if (
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'boolean'
+  ) {
+    return out;
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value))
+      out.push(`${at}: ${value} is not a JSON number`);
+    return out;
+  }
+  if (value === undefined) {
+    out.push(`${at}: undefined is not JSON`);
+    return out;
+  }
+  if (typeof value !== 'object') {
+    out.push(`${at}: a ${typeof value} is not JSON`);
+    return out;
+  }
+  if (ancestors.has(value)) {
+    out.push(`${at}: refers back to itself`);
+    return out;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (!Array.isArray(value) && proto !== Object.prototype && proto !== null) {
+    out.push(
+      `${at}: a ${proto?.constructor?.name ?? 'non-plain object'} is not JSON`,
+    );
+    return out;
+  }
+  if (Object.getOwnPropertySymbols(value).length > 0) {
+    out.push(`${at}: has symbol keys`);
+  }
+  ancestors.add(value);
+  if (Array.isArray(value)) {
+    value.forEach((item, index) =>
+      jsonProblems(item, `${at}[${index}]`, ancestors, out),
+    );
+  } else {
+    for (const [key, item] of Object.entries(value)) {
+      jsonProblems(item, `${at}.${key}`, ancestors, out);
+    }
+  }
+  ancestors.delete(value);
+  return out;
+}
+
+/**
+ * The node's own shape, once it is known to be JSON.
+ * @param {Record<string, any>} node
+ * @returns {string[]}
+ */
+function structureProblems(node) {
+  /** @type {string[]} */
+  const problems = [];
+  const unknown = Object.keys(node).filter(key => !NODE_FIELDS.has(key));
+  if (unknown.length > 0)
+    problems.push(`unknown fields: ${unknown.join(', ')}`);
+  if (node.kind !== 'reference') problems.push('kind: expected "reference"');
+  if (node.stage !== 'lowered' && node.stage !== 'linked') {
+    problems.push('stage: expected "lowered" or "linked"');
+  }
+  if (!isText(node.id)) problems.push('id: expected a topic name');
+  if (node.lang !== null && !isText(node.lang)) {
+    problems.push('lang: expected a language or null');
+  }
+  const provenance = node.provenance;
+  if (
+    !isRecord(provenance) ||
+    !isPackageName(provenance.provider) ||
+    (provenance.replaces !== null && !isText(provenance.replaces)) ||
+    !Array.isArray(provenance.extensions) ||
+    !provenance.extensions.every(isPackageName)
+  ) {
+    problems.push(
+      'provenance: expected {provider, replaces, extensions} naming packages, not paths',
+    );
+  }
+  const titles = isRecord(node.sourceTitles) ? node.sourceTitles : null;
+  if (!titles || !Object.values(titles).every(isText)) {
+    problems.push('sourceTitles: expected section key -> authored title');
+  }
+  const doc = node.doc;
+  if (
+    !isRecord(doc) ||
+    !isText(doc.name) ||
+    !isText(doc.title) ||
+    typeof doc.description !== 'string' ||
+    !Array.isArray(doc.sections) ||
+    doc.sections.length === 0
+  ) {
+    problems.push('doc: expected {name, title, description, sections}');
+  } else {
+    problems.push(...sectionProblems(doc.sections, titles, node.stage));
+  }
+  return problems;
+}
+
+/**
+ * @param {any[]} sections
+ * @param {Record<string, any> | null} titles
+ * @param {unknown} stage
+ * @returns {string[]}
+ */
+function sectionProblems(sections, titles, stage) {
+  /** @type {string[]} */
+  const problems = [];
+  const seen = new Set();
+  sections.forEach((section, index) => {
+    const at = `doc.sections[${index}]`;
+    if (
+      !isRecord(section) ||
+      typeof section.id !== 'string' ||
+      !SECTION_KEY_RE.test(section.id)
+    ) {
+      problems.push(`${at}.id: expected a section key`);
+      return;
+    }
+    if (seen.has(section.id)) {
+      problems.push(`${at}.id: two sections have the key "${section.id}"`);
+    }
+    seen.add(section.id);
+    if (!isText(section.title)) problems.push(`${at}.title: expected a title`);
+    if (titles && !Object.hasOwn(titles, section.id)) {
+      problems.push(
+        `sourceTitles: no authored title for section "${section.id}"`,
+      );
+    }
+    if (!Array.isArray(section.content)) {
+      problems.push(`${at}.content: expected an array of blocks`);
+      return;
+    }
+    section.content.forEach((/** @type {unknown} */ block, blockIndex) => {
+      const where = `${at}.content[${blockIndex}]`;
+      if (!isRecord(block) || !isText(block.type)) {
+        problems.push(`${where}: expected a block with a type`);
+        return;
+      }
+      if (block.type !== 'token-ref') return;
+      const ref = `${where}: token reference to "${block.topic}"`;
+      if (stage === 'lowered') {
+        if ('resolved' in block) {
+          problems.push(`${ref}: a lowered node carries no resolution`);
+        }
+        return;
+      }
+      if (!('resolved' in block)) {
+        problems.push(`${ref}: a linked node resolves every reference`);
+        return;
+      }
+      const problem = resolutionProblem(block.resolved);
+      if (problem) problems.push(`${ref}: ${problem}`);
+    });
+  });
+  return problems;
+}
+
+/**
+ * @param {unknown} resolved
+ * @returns {string | null}
+ */
+function resolutionProblem(resolved) {
+  if (!isRecord(resolved)) return 'expected a resolution';
+  switch (resolved.status) {
+    case 'unknown-topic':
+    case 'unknown-section':
+      return Object.keys(resolved).length === 1 ? null : 'unexpected fields';
+    case 'resolved': {
+      if (!isText(resolved.topic)) return 'topic: expected a topic name';
+      if (
+        typeof resolved.section !== 'string' ||
+        !SECTION_KEY_RE.test(resolved.section)
+      ) {
+        return 'section: expected a section key';
+      }
+      if ('previewType' in resolved && !isText(resolved.previewType)) {
+        return 'previewType: expected a preview type';
+      }
+      if (
+        !Array.isArray(resolved.content) ||
+        !resolved.content.every(block => isRecord(block) && isText(block.type))
+      ) {
+        return 'content: expected blocks with a type';
+      }
+      const extra = Object.keys(resolved).filter(
+        key => !RESOLVED_FIELDS.has(key),
+      );
+      return extra.length > 0 ? `unexpected fields: ${extra.join(', ')}` : null;
+    }
+    default:
+      return `status: expected resolved, unknown-topic or unknown-section, got ${JSON.stringify(resolved.status)}`;
+  }
+}

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

@@ -0,0 +1,33 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The node's sections as readers look them up: each one knows its authored
+ * title, so a query in the authoring language finds a translated section.
+ * For lookup only; a section a reader gets back comes from
+ * {@link sectionView}.
+ * @param {import('./compile.mjs').CompiledReferenceNode} node
+ * @returns {any[]}
+ */
+export function readerSections(node: import("./compile.mjs").CompiledReferenceNode): any[];
+/**
+ * `docs.detail`: the whole topic, with every token reference inlined.
+ * @param {import('./compile.mjs').CompiledReferenceNode} node a linked node
+ * @returns {any}
+ */
+export function detailView(node: import("./compile.mjs").CompiledReferenceNode): any;
+/**
+ * `docs.index`: what the topic is, and each section's key, title and summary.
+ * @param {import('./compile.mjs').CompiledReferenceNode} node
+ * @returns {import('../../api/docs/docs.type.mjs').DocsIndex}
+ */
+export function indexView(node: import("./compile.mjs").CompiledReferenceNode): import("../../api/docs/docs.type.mjs").DocsIndex;
+/**
+ * `docs.detail.section`: one section with its token references inlined. A
+ * referenced section's content takes the reference's place; the section takes
+ * the preview type of the last reference that has one, unless it has its own.
+ * @param {import('./compile.mjs').CompiledReferenceNode} node
+ * @param {any} section a linked section of `node`
+ * @returns {any}
+ */
+export function sectionView(node: import("./compile.mjs").CompiledReferenceNode, section: any): any;

package/foundation/doc-compiler/lenses.mjs

@@ -0,0 +1,127 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Lenses — the docs API's response shapes, read off compiled nodes.
+ *
+ * @input A compiled reference node from ./compile.mjs: lowered for the index
+ *   and for section lookup, linked for anything that inlines token references.
+ * @output The `docs.detail` topic, the `docs.index` section index, one
+ *   `docs.detail.section` section, and the sections as readers look them up.
+ *   Every view is a fresh copy, so a reader may edit what it gets back without
+ *   touching the node, which other reads of the same catalog share.
+ * @position Between the compiler and api/docs. A lens only projects: it never
+ *   loads, merges, overlays, keys, or resolves a reference itself.
+ */
+
+import {
+  buildDocsIndexData,
+  withSourceTitle,
+} from '../discovery/docs-section-key.mjs';
+
+/**
+ * @param {import('./compile.mjs').CompiledReferenceNode} node
+ * @param {any} section
+ * @returns {string}
+ */
+function authoredTitle(node, section) {
+  return node.sourceTitles[section.id] ?? section.title;
+}
+
+/**
+ * The node's sections as readers look them up: each one knows its authored
+ * title, so a query in the authoring language finds a translated section.
+ * For lookup only; a section a reader gets back comes from
+ * {@link sectionView}.
+ * @param {import('./compile.mjs').CompiledReferenceNode} node
+ * @returns {any[]}
+ */
+export function readerSections(node) {
+  return node.doc.sections.map((/** @type {any} */ section) =>
+    withSourceTitle({...section}, authoredTitle(node, section)),
+  );
+}
+
+/**
+ * `docs.detail`: the whole topic, with every token reference inlined.
+ * @param {import('./compile.mjs').CompiledReferenceNode} node a linked node
+ * @returns {any}
+ */
+export function detailView(node) {
+  if (node.stage !== 'linked') {
+    throw new Error(
+      `"${node.id}" must be linked before its whole doc is read.`,
+    );
+  }
+  // Assigning `sections` keeps it where the authored doc put it.
+  const view = structuredClone({...node.doc, sections: []});
+  view.sections = node.doc.sections.map((/** @type {any} */ section) =>
+    sectionView(node, section),
+  );
+  return view;
+}
+
+/**
+ * `docs.index`: what the topic is, and each section's key, title and summary.
+ * @param {import('./compile.mjs').CompiledReferenceNode} node
+ * @returns {import('../../api/docs/docs.type.mjs').DocsIndex}
+ */
+export function indexView(node) {
+  return buildDocsIndexData(node.doc);
+}
+
+/**
+ * `docs.detail.section`: one section with its token references inlined. A
+ * referenced section's content takes the reference's place; the section takes
+ * the preview type of the last reference that has one, unless it has its own.
+ * @param {import('./compile.mjs').CompiledReferenceNode} node
+ * @param {any} section a linked section of `node`
+ * @returns {any}
+ */
+export function sectionView(node, section) {
+  /** @type {any[]} */
+  const content = [];
+  /** @type {string | null} */
+  let previewType = null;
+  for (const block of section.content) {
+    if (block?.type !== 'token-ref') {
+      content.push(structuredClone(block));
+      continue;
+    }
+    const target = block.resolved;
+    if (target == null) {
+      throw new Error(
+        `The token reference to "${block.topic}" in "${node.id}" was read before it was linked.`,
+      );
+    }
+    if (target.status === 'unknown-topic') {
+      content.push({
+        type: 'prose',
+        text: `[token-ref: unknown topic "${block.topic}"]`,
+      });
+      continue;
+    }
+    if (target.status === 'unknown-section') {
+      content.push({
+        type: 'prose',
+        text: `[token-ref: section "${block.section}" not found in "${block.topic}"]`,
+      });
+      continue;
+    }
+    // A copy per reference: two references to one section share nothing.
+    for (const refBlock of target.content) {
+      content.push(structuredClone(refBlock));
+    }
+    if (target.previewType && !section.previewType) {
+      previewType = target.previewType;
+    }
+  }
+  // Assigning `content` keeps it where the section put it; a carried preview
+  // type lands after the section's own keys, as it always has.
+  const view = structuredClone(
+    previewType == null
+      ? {...section, content: []}
+      : {...section, previewType, content: []},
+  );
+  view.content = content;
+  return withSourceTitle(view, authoredTitle(node, section));
+}

package/foundation/identity/provider-identity.d.mts

@@ -0,0 +1,90 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Normalize an npm package name into a ProviderId.
+ * @param {string} packageName
+ * @returns {ProviderId}
+ */
+export function normalizeProviderId(packageName: string): ProviderId;
+/**
+ * Normalize a SHA-256 digest.
+ * @param {string} digest
+ * @returns {ContentDigest}
+ */
+export function normalizeContentDigest(digest: string): ContentDigest;
+/**
+ * Build a stable provider + contribution kind + artifact-name ID.
+ * @param {string} provider
+ * @param {ContributionKind} kind
+ * @param {string} name
+ * @returns {ArtifactId}
+ */
+export function createArtifactId(provider: string, kind: ContributionKind, name: string): ArtifactId;
+/**
+ * Build a stable document ID from provider + authored kind + stable name.
+ * @param {string} provider
+ * @param {AuthoredDocKind} kind
+ * @param {string} name
+ * @returns {DocId}
+ */
+export function createDocId(provider: string, kind: AuthoredDocKind, name: string): DocId;
+/**
+ * Build a normalized logical artifact record.
+ * @param {string} provider
+ * @param {ContributionKind} kind
+ * @param {string} name
+ * @returns {ArtifactIdentity}
+ */
+export function createArtifactIdentity(provider: string, kind: ContributionKind, name: string): ArtifactIdentity;
+/**
+ * Parse and canonicalize an ArtifactId.
+ * @param {string} value
+ * @returns {ArtifactIdentity}
+ */
+export function parseArtifactId(value: string): ArtifactIdentity;
+/**
+ * Build one immutable provider instance.
+ * @param {{providerId: string, packageName: string, packageVersion: string, sourceDigest: string}} input
+ * @returns {ProviderInstance}
+ */
+export function createProviderInstance(input: {
+    providerId: string;
+    packageName: string;
+    packageVersion: string;
+    sourceDigest: string;
+}): ProviderInstance;
+/**
+ * Bind one validated authored document to immutable provider and source
+ * provenance. Runtime lifecycle state is intentionally absent.
+ * @param {{
+ *   provider: ProviderInstance,
+ *   kind: AuthoredDocKind,
+ *   stableName: string,
+ *   source: {group: string, path: string, digest: string},
+ *   authored: AuthoredDoc,
+ * }} input
+ * @returns {AuthoredDocEntry}
+ */
+export function createAuthoredDocEntry(input: {
+    provider: ProviderInstance;
+    kind: AuthoredDocKind;
+    stableName: string;
+    source: {
+        group: string;
+        path: string;
+        digest: string;
+    };
+    authored: AuthoredDoc;
+}): AuthoredDocEntry;
+export type ArtifactId = import("../../authoring/identity/type").ArtifactId;
+export type ArtifactIdentity = import("../../authoring/identity/type").ArtifactIdentity;
+export type AuthoredDoc = import("../../authoring/identity/type").AuthoredDoc;
+export type AuthoredDocEntry = import("../../authoring/identity/type").AuthoredDocEntry;
+export type AuthoredDocKind = import("../../authoring/doctypes/base/type").AuthoredDocKind;
+export type ContentDigest = import("../../authoring/identity/type").ContentDigest;
+export type ContributionKind = import("../../authoring/identity/type").ContributionKind;
+export type DocId = import("../../authoring/identity/type").DocId;
+export type ProviderId = import("../../authoring/identity/type").ProviderId;
+export type ProviderInstance = import("../../authoring/identity/type").ProviderInstance;
+export type ProviderInstanceId = import("../../authoring/identity/type").ProviderInstanceId;