@astryxdesign/cli 0.6.3-canary.f22695a → 0.6.3

package/foundation/doc-compiler/ir.mjs

@@ -1,287 +0,0 @@
-// 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

@@ -1,33 +0,0 @@
-// @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

@@ -1,127 +0,0 @@
-// 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

@@ -1,90 +0,0 @@
-// @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;