@nimiplatform/nimi-coding 0.3.1 → 0.5.0

package/cli/lib/authority/source-map.mjs

@@ -0,0 +1,105 @@
+import { compareText, makeDiagnostic, REPAIRS, sortDiagnostics, sourcePointer as absoluteSourcePointer } from "./diagnostics.mjs";
+
+function addMappedLeaf(source, fields, diagnostics, outputPointer, sourcePointer) {
+  const range = source.locations.get(sourcePointer);
+  if (!range) {
+    diagnostics.push(makeDiagnostic({
+      code: "AUTH_SOURCE_MAP_MISSING",
+      file: source.file,
+      range: source.locations.get("") ?? source.locator.range(0),
+      pointer: absoluteSourcePointer(source, sourcePointer),
+      reason: `AuthorityIR leaf ${outputPointer} has no source range at ${sourcePointer}`,
+      repair: REPAIRS.structural,
+    }));
+  } else {
+    fields[outputPointer] = { file: source.file, range, sourcePointer: absoluteSourcePointer(source, sourcePointer) };
+  }
+}
+
+function collectIrLeaves(value, pointer = "", leaves = new Set()) {
+  if (Array.isArray(value)) {
+    if (value.length === 0) leaves.add(pointer);
+    else value.forEach((entry, index) => collectIrLeaves(entry, `${pointer}/${index}`, leaves));
+    return leaves;
+  }
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value);
+    if (entries.length === 0) leaves.add(pointer);
+    else entries.forEach(([key, entry]) => collectIrLeaves(entry, `${pointer}/${key}`, leaves));
+    return leaves;
+  }
+  leaves.add(pointer);
+  return leaves;
+}
+
+function mapUnit(source, outputIndex, fields, diagnostics) {
+  const base = `/units/${outputIndex}`;
+  for (const field of ["id", "kind", "owner", "lifecycle"]) {
+    addMappedLeaf(source, fields, diagnostics, `${base}/${field}`, `/${field}`);
+  }
+  addMappedLeaf(source, fields, diagnostics, `${base}/metadata/title`, "/title");
+  if (source.data.reason !== undefined) addMappedLeaf(source, fields, diagnostics, `${base}/metadata/reason`, "/reason");
+  if (source.data.lifecycle === "active" && source.data.kind === "definition") {
+    addMappedLeaf(source, fields, diagnostics, `${base}/semantic/meaning`, "/meaning");
+  }
+  if (source.data.lifecycle === "active" && source.data.kind === "rule") {
+    for (const field of ["modality", "statement", "condition", "failure"]) {
+      addMappedLeaf(source, fields, diagnostics, `${base}/semantic/${field}`, `/${field}`);
+    }
+    source.data.scope
+      .map((value, sourceIndex) => ({ value, sourceIndex }))
+      .sort((left, right) => compareText(left.value, right.value))
+      .forEach((entry, scopeIndex) => addMappedLeaf(source, fields, diagnostics, `${base}/semantic/scope/${scopeIndex}`, `/scope/${entry.sourceIndex}`));
+  }
+  if (source.data.relations.length === 0) {
+    addMappedLeaf(source, fields, diagnostics, `${base}/relations`, "/relations");
+  } else {
+    source.data.relations
+      .map((relation, sourceIndex) => ({ relation, sourceIndex }))
+      .sort((left, right) => compareText(left.relation.type, right.relation.type) || compareText(left.relation.target, right.relation.target))
+      .forEach((entry, relationIndex) => {
+        const outputPointer = `${base}/relations/${relationIndex}`;
+        const sourcePointer = `/relations/${entry.sourceIndex}`;
+        addMappedLeaf(source, fields, diagnostics, `${outputPointer}/type`, `${sourcePointer}/type`);
+        addMappedLeaf(source, fields, diagnostics, `${outputPointer}/target`, `${sourcePointer}/target`);
+      });
+  }
+}
+
+export function buildSourceMap(sources, ir) {
+  const diagnostics = [];
+  const fields = {};
+  const orderedSources = [...sources].sort((left, right) => compareText(left.data.id, right.data.id));
+  orderedSources.forEach((source, outputIndex) => mapUnit(source, outputIndex, fields, diagnostics));
+  const expectedLeaves = collectIrLeaves(ir);
+  for (const pointer of Object.keys(fields)) {
+    if (!expectedLeaves.has(pointer)) {
+      const mapped = fields[pointer];
+      diagnostics.push(makeDiagnostic({
+        code: "AUTH_SOURCE_MAP_MISSING",
+        file: mapped.file,
+        range: mapped.range,
+        pointer: mapped.sourcePointer,
+        reason: `SourceMap entry does not address an AuthorityIR leaf: ${pointer}`,
+        repair: REPAIRS.structural,
+      }));
+    }
+  }
+  for (const pointer of expectedLeaves) {
+    if (!Object.hasOwn(fields, pointer)) {
+      const match = pointer.match(/^\/units\/(\d+)/);
+      const source = orderedSources[Number(match?.[1] ?? 0)] ?? orderedSources[0];
+      diagnostics.push(makeDiagnostic({
+        code: "AUTH_SOURCE_MAP_MISSING",
+        file: source.file,
+        range: source.locations.get("") ?? source.locator.range(0),
+        pointer: absoluteSourcePointer(source, ""),
+        reason: `AuthorityIR leaf is not mapped: ${pointer}`,
+        repair: REPAIRS.structural,
+      }));
+    }
+  }
+  return { ok: diagnostics.length === 0, diagnostics: sortDiagnostics(diagnostics), sourceMap: { fields } };
+}
+
+export { collectIrLeaves };

package/cli/lib/authority/source-markdown.mjs

@@ -0,0 +1,167 @@
+import { makeDiagnostic, portablePath, REPAIRS, createLocator } from "./diagnostics.mjs";
+import { FRONTMATTER_KEY_ORDER, parseRestrictedYaml, stringifyCanonicalYaml } from "./source-yaml.mjs";
+
+const SECTION_FIELDS = new Map([
+  ["Meaning", "meaning"],
+  ["Statement", "statement"],
+  ["Condition", "condition"],
+  ["Failure", "failure"],
+  ["Removal reason", "reason"],
+]);
+const BODY_ORDER = [
+  ["meaning", "Meaning"],
+  ["statement", "Statement"],
+  ["condition", "Condition"],
+  ["failure", "Failure"],
+  ["reason", "Removal reason"],
+];
+
+function lineTable(text) {
+  const lines = [];
+  let start = 0;
+  for (let index = 0; index <= text.length; index += 1) {
+    if (index === text.length || text[index] === "\n") {
+      const raw = text.slice(start, index);
+      lines.push({ text: raw.endsWith("\r") ? raw.slice(0, -1) : raw, start, end: index });
+      start = index + 1;
+    }
+  }
+  return lines;
+}
+
+function ambiguous(file, locator, line, reason) {
+  return makeDiagnostic({
+    code: "AUTH_MARKDOWN_AMBIGUOUS",
+    file,
+    range: locator.range(line.start, line.end),
+    reason,
+    repair: REPAIRS.structural,
+  });
+}
+
+function isPlainMarkdownSlot(value) {
+  if (typeof value !== "string" || value.length === 0 || value.trim() !== value || /[\r\n\t]/.test(value)) return false;
+  if (!/^[\p{L}\p{N}\p{M}\p{Zs}\p{P}\p{S}]+$/u.test(value)) return false;
+  if (/[`*_\[\]<>\\~]/u.test(value)) return false;
+  if (/^(?:#{1,6}(?:\s|$)|>|[-+*](?:\s|$)|\d+[.)](?:\s|$)|(?:-{3,}|={3,})(?:\s|$))/u.test(value)) return false;
+  return true;
+}
+
+export function parseMarkdownAuthority(text, absolutePath, options = {}) {
+  const file = portablePath(absolutePath, options.cwd);
+  const locator = createLocator(text);
+  const lines = lineTable(text);
+  const diagnostics = [];
+  if (lines[0]?.text !== "---") {
+    diagnostics.push(ambiguous(file, locator, lines[0] ?? { start: 0, end: 0 }, "Markdown authority must start with YAML front matter"));
+    return { ok: false, file, locator, diagnostics, locations: new Map(), data: null, profile: "markdown" };
+  }
+  const closingIndex = lines.findIndex((line, index) => index > 0 && line.text === "---");
+  if (closingIndex < 0) {
+    diagnostics.push(ambiguous(file, locator, lines[0], "Markdown front matter is missing its closing delimiter"));
+    return { ok: false, file, locator, diagnostics, locations: new Map(), data: null, profile: "markdown" };
+  }
+  const frontStart = lines[0].end + 1;
+  const frontEnd = lines[closingIndex].start;
+  const front = text.slice(frontStart, frontEnd);
+  const parsedFront = parseRestrictedYaml(front, absolutePath, { ...options, offset: frontStart, fullText: text, keyOrder: FRONTMATTER_KEY_ORDER });
+  if (!parsedFront.ok) return { ...parsedFront, profile: "markdown" };
+  const data = { ...parsedFront.data };
+  const frontKeys = Object.keys(parsedFront.data);
+  const locations = new Map(parsedFront.locations);
+  const keyLocations = new Map(parsedFront.keyLocations);
+  const insertionPoints = new Map(parsedFront.insertionPoints);
+  const closingInsertion = locator.range(lines[closingIndex].start, lines[closingIndex].start);
+  if (!Object.hasOwn(data, "relations")) insertionPoints.set("/relations", closingInsertion);
+  locations.set("", locator.range(0, text.length));
+  let index = closingIndex + 1;
+  while (index < lines.length && lines[index].text === "") index += 1;
+  if (lines[index]?.text.startsWith("# ")) {
+    const title = lines[index].text.slice(2);
+    data.title = title;
+    locations.set("/title", locator.range(lines[index].start + 2, lines[index].end));
+    if (!isPlainMarkdownSlot(title)) diagnostics.push(ambiguous(file, locator, lines[index], "Markdown title must be one plain non-empty text line"));
+    index += 1;
+  } else if (/^#(?!#)/.test(lines[index]?.text ?? "")) {
+    diagnostics.push(ambiguous(file, locator, lines[index], "Markdown authority allows exactly one level-one title"));
+    index += 1;
+  }
+  const seenSections = new Set();
+  const sectionHeadings = new Map();
+  while (index < lines.length) {
+    while (index < lines.length && lines[index].text === "") index += 1;
+    if (index >= lines.length || (index === lines.length - 1 && lines[index].text === "")) break;
+    const heading = lines[index];
+    if (!heading.text.startsWith("## ")) {
+      diagnostics.push(ambiguous(file, locator, heading, "prose and constructs outside known Markdown authority slots are not admitted"));
+      index += 1;
+      continue;
+    }
+    const headingName = heading.text.slice(3);
+    const field = SECTION_FIELDS.get(headingName);
+    if (!field) {
+      diagnostics.push(ambiguous(file, locator, heading, `unknown Markdown authority section: ${headingName}`));
+      index += 1;
+      continue;
+    }
+    if (seenSections.has(field)) {
+      diagnostics.push(ambiguous(file, locator, heading, `duplicate Markdown authority section: ${headingName}`));
+      index += 1;
+      continue;
+    }
+    seenSections.add(field);
+    sectionHeadings.set(field, locator.range(heading.start, heading.end));
+    index += 1;
+    while (index < lines.length && lines[index].text === "") index += 1;
+    const body = lines[index];
+    if (!body || body.text.startsWith("#")) {
+      data[field] = "";
+      locations.set(`/${field}`, locator.range(heading.end, heading.end));
+      continue;
+    }
+    if (!isPlainMarkdownSlot(body.text)) {
+      diagnostics.push(ambiguous(file, locator, body, `${headingName} must contain exactly one plain text line`));
+    }
+    data[field] = body.text;
+    locations.set(`/${field}`, locator.range(body.start, body.end));
+    index += 1;
+    if (index < lines.length && lines[index].text !== "" && !lines[index].text.startsWith("## ")) {
+      diagnostics.push(ambiguous(file, locator, lines[index], `${headingName} must contain exactly one text line`));
+      index += 1;
+    }
+  }
+  const firstBodyPosition = locator.range(lines[closingIndex].end + 1, lines[closingIndex].end + 1);
+  if (!Object.hasOwn(data, "title")) insertionPoints.set("/title", firstBodyPosition);
+  for (let bodyIndex = 0; bodyIndex < BODY_ORDER.length; bodyIndex += 1) {
+    const [field] = BODY_ORDER[bodyIndex];
+    if (Object.hasOwn(data, field)) continue;
+    const nextField = BODY_ORDER.slice(bodyIndex + 1).map(([candidate]) => candidate).find((candidate) => sectionHeadings.has(candidate));
+    insertionPoints.set(`/${field}`, nextField ? { start: sectionHeadings.get(nextField).start, end: sectionHeadings.get(nextField).start } : locator.range(text.length, text.length));
+  }
+  return {
+    ok: diagnostics.length === 0,
+    file,
+    locator,
+    diagnostics,
+    locations,
+    keyLocations,
+    insertionPoints,
+    data,
+    profile: "markdown",
+    sourceText: text,
+    frontKeys,
+  };
+}
+
+export function stringifyCanonicalMarkdown(data) {
+  const front = {};
+  for (const key of ["format", "id", "kind", "owner", "lifecycle", "modality", "scope", "relations"]) {
+    if (Object.hasOwn(data, key)) front[key] = data[key];
+  }
+  let output = `---\n${stringifyCanonicalYaml(front, { frontmatter: true }).trimEnd()}\n---`;
+  if (Object.hasOwn(data, "title")) output += `\n# ${data.title}`;
+  for (const [field, heading] of BODY_ORDER) {
+    if (Object.hasOwn(data, field)) output += `\n\n## ${heading}\n\n${String(data[field])}`;
+  }
+  return `${output}\n`;
+}

package/cli/lib/authority/source-yaml.mjs

@@ -0,0 +1,308 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+import YAML, { isAlias, isMap, isScalar, isSeq, visit } from "yaml";
+
+import { compareText, createLocator, makeDiagnostic, portablePath, REPAIRS } from "./diagnostics.mjs";
+
+const CONTRACT_PATH = fileURLToPath(new URL("../../../contracts/authority-source.schema.yaml", import.meta.url));
+let contractPromise = null;
+
+export async function loadAuthorityContract() {
+  if (!contractPromise) {
+    contractPromise = readFile(CONTRACT_PATH, "utf8").then((text) => {
+      const value = YAML.parse(text);
+      if (value?.version !== 1 || value?.contract?.id !== "nimicoding.authority-source.v2") {
+        throw new Error("installed authority source contract is invalid");
+      }
+      return value;
+    });
+  }
+  return contractPromise;
+}
+
+function pointerToken(value) {
+  return String(value).replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
+function nodeRange(node, locator, offset) {
+  const range = node?.range;
+  if (!Array.isArray(range)) return locator.range(offset, offset);
+  return locator.range(offset + range[0], offset + (range[1] ?? range[0]));
+}
+
+function collectLocations(node, locator, offset, pointer, locations, keyLocations) {
+  if (!node) return;
+  locations.set(pointer, nodeRange(node, locator, offset));
+  if (isMap(node)) {
+    for (const pair of node.items) {
+      const key = isScalar(pair.key) ? String(pair.key.value) : "";
+      const childPointer = `${pointer}/${pointerToken(key)}`;
+      keyLocations.set(childPointer, nodeRange(pair.key, locator, offset));
+      locations.set(childPointer, nodeRange(pair.value ?? pair.key, locator, offset));
+      collectLocations(pair.value, locator, offset, childPointer, locations, keyLocations);
+    }
+  } else if (isSeq(node)) {
+    node.items.forEach((item, index) => collectLocations(item, locator, offset, `${pointer}/${index}`, locations, keyLocations));
+  }
+}
+
+function zeroAt(position) {
+  return { start: position, end: position };
+}
+
+export function buildInsertionPoints(data, locations, keyLocations, keyOrder) {
+  const insertionPoints = new Map();
+  const rootEnd = locations.get("")?.end ?? { line: 1, column: 1 };
+  for (let index = 0; index < keyOrder.length; index += 1) {
+    const field = keyOrder[index];
+    if (Object.hasOwn(data, field)) continue;
+    const nextField = keyOrder.slice(index + 1).find((candidate) => keyLocations.has(`/${candidate}`));
+    insertionPoints.set(`/${field}`, nextField ? zeroAt(keyLocations.get(`/${nextField}`).start) : zeroAt(rootEnd));
+  }
+  if (Array.isArray(data.relations)) {
+    data.relations.forEach((relation, index) => {
+      if (!relation || typeof relation !== "object" || Array.isArray(relation)) return;
+      const pointer = `/relations/${index}`;
+      const relationEnd = locations.get(pointer)?.end ?? rootEnd;
+      if (!Object.hasOwn(relation, "type")) {
+        insertionPoints.set(`${pointer}/type`, keyLocations.has(`${pointer}/target`)
+          ? zeroAt(keyLocations.get(`${pointer}/target`).start)
+          : zeroAt(relationEnd));
+      }
+      if (!Object.hasOwn(relation, "target")) insertionPoints.set(`${pointer}/target`, zeroAt(relationEnd));
+    });
+  }
+  return insertionPoints;
+}
+
+function yamlErrorDiagnostic(error, file, locator, offset) {
+  const positions = Array.isArray(error.pos) ? error.pos : [0, 0];
+  const duplicate = /keys must be unique|duplicate key/i.test(error.message);
+  return makeDiagnostic({
+    code: duplicate ? "AUTH_DUPLICATE_KEY" : "AUTH_SYNTAX_UNSUPPORTED",
+    file,
+    range: locator.range(offset + positions[0], offset + (positions[1] ?? positions[0])),
+    reason: duplicate ? "YAML mapping keys must be unique" : `unsupported YAML syntax: ${error.message.split(" at line")[0]}`,
+    repair: duplicate ? REPAIRS.duplicate : REPAIRS.structural,
+  });
+}
+
+export function parseRestrictedYaml(text, absolutePath, options = {}) {
+  const offset = options.offset ?? 0;
+  const fullText = options.fullText ?? text;
+  const file = portablePath(absolutePath, options.cwd);
+  const locator = createLocator(fullText);
+  const diagnostics = [];
+  const documents = YAML.parseAllDocuments(text, {
+    keepSourceTokens: true,
+    prettyErrors: false,
+    strict: true,
+    uniqueKeys: true,
+    version: "1.2",
+  });
+  if (documents.length !== 1) {
+    diagnostics.push(makeDiagnostic({
+      code: "AUTH_SYNTAX_UNSUPPORTED",
+      file,
+      range: locator.range(offset, offset + text.length),
+      reason: "authority source must contain exactly one YAML document",
+      repair: REPAIRS.structural,
+    }));
+  }
+  const document = documents[0];
+  for (const error of document?.errors ?? []) diagnostics.push(yamlErrorDiagnostic(error, file, locator, offset));
+  if (diagnostics.length > 0 || !document) {
+    return { ok: false, file, locator, diagnostics, locations: new Map(), keyLocations: new Map(), insertionPoints: new Map(), data: null };
+  }
+  if (!isMap(document.contents)) {
+    diagnostics.push(makeDiagnostic({
+      code: "AUTH_SYNTAX_UNSUPPORTED",
+      file,
+      range: nodeRange(document.contents, locator, offset),
+      reason: "authority YAML must be one top-level mapping",
+      repair: REPAIRS.structural,
+    }));
+  }
+  if (/^%/.test(text)) {
+    diagnostics.push(makeDiagnostic({
+      code: "AUTH_SYNTAX_UNSUPPORTED",
+      file,
+      range: locator.range(offset, offset + Math.min(text.length, text.indexOf("\n") + 1 || text.length)),
+      reason: "YAML directives are not admitted",
+      repair: REPAIRS.structural,
+    }));
+  }
+  if (document.comment || document.commentBefore) {
+    const searchStart = document.contents?.range?.[2] ?? document.contents?.range?.[1] ?? 0;
+    const commentStart = text.indexOf("#", searchStart);
+    diagnostics.push(makeDiagnostic({
+      code: "AUTH_SYNTAX_UNSUPPORTED",
+      file,
+      range: locator.range(offset + Math.max(0, commentStart), offset + (commentStart < 0 ? text.length : commentStart + 1)),
+      reason: "YAML comments are not admitted in canonical authority",
+      repair: REPAIRS.structural,
+    }));
+  }
+  if (document.contents) {
+    visit(document, (_key, node) => {
+      if (!node || typeof node !== "object") return;
+      let reason = null;
+      if (node.comment || node.commentBefore) reason = "YAML comments are not admitted in canonical authority";
+      else if (isAlias(node)) reason = "YAML aliases are not admitted";
+      else if (node.anchor) reason = "YAML anchors are not admitted";
+      else if (node.tag) reason = "explicit YAML tags are not admitted";
+      if (reason) diagnostics.push(makeDiagnostic({
+        code: "AUTH_SYNTAX_UNSUPPORTED",
+        file,
+        range: nodeRange(node, locator, offset),
+        reason,
+        repair: REPAIRS.structural,
+      }));
+      if (node.constructor?.name === "Pair" && !isScalar(node.key)) {
+        diagnostics.push(makeDiagnostic({
+          code: "AUTH_SYNTAX_UNSUPPORTED",
+          file,
+          range: nodeRange(node.key, locator, offset),
+          reason: "complex YAML mapping keys are not admitted",
+          repair: REPAIRS.structural,
+        }));
+      }
+    });
+  }
+  if (diagnostics.length > 0) return { ok: false, file, locator, diagnostics, locations: new Map(), keyLocations: new Map(), insertionPoints: new Map(), data: null };
+  const locations = new Map();
+  const keyLocations = new Map();
+  collectLocations(document.contents, locator, offset, "", locations, keyLocations);
+  const data = document.toJS({ mapAsMap: false });
+  const insertionPoints = buildInsertionPoints(data, locations, keyLocations, options.keyOrder ?? []);
+  return {
+    ok: true,
+    file,
+    locator,
+    diagnostics,
+    locations,
+    keyLocations,
+    insertionPoints,
+    data,
+    yamlDocument: document,
+    sourceText: fullText,
+  };
+}
+
+export const AUTHORITY_FORMAT_V2 = "nimicoding.authority/v2";
+export const YAML_CONTAINER_KEY_ORDER = ["format", "owner", "scope", "units"];
+export const YAML_UNIT_KEY_ORDER = [
+  "id", "kind", "owner", "lifecycle", "title", "meaning", "modality", "scope",
+  "statement", "condition", "failure", "reason", "relations",
+];
+export const FRONTMATTER_KEY_ORDER = ["format", "id", "kind", "owner", "lifecycle", "modality", "scope", "relations"];
+
+function orderedObject(data, order) {
+  return Object.fromEntries(order.filter((key) => Object.hasOwn(data, key)).map((key) => [key, data[key]]));
+}
+
+function normalizedUnit(data, order = YAML_UNIT_KEY_ORDER, defaults = null) {
+  const next = orderedObject(data, order);
+  if (defaults) {
+    if (next.owner === defaults.owner) delete next.owner;
+    if (next.lifecycle === "active") delete next.lifecycle;
+    if (Array.isArray(next.relations) && next.relations.length === 0) delete next.relations;
+    if (next.kind === "rule" && next.lifecycle !== "removed" && Array.isArray(next.scope)
+      && next.scope.length === 1 && next.scope[0] === defaults.scope) delete next.scope;
+  }
+  if (Array.isArray(next.scope)) next.scope = [...next.scope].sort(compareText);
+  if (Array.isArray(next.relations)) {
+    next.relations = next.relations.map((entry) => ({ type: entry.type, target: entry.target })).sort((left, right) => (
+      compareText(left.type, right.type) || compareText(left.target, right.target)
+    ));
+  }
+  return next;
+}
+
+export function normalizedData(data, { frontmatter = false, container = false } = {}) {
+  if (frontmatter === container) throw new TypeError("canonical YAML serialization requires exactly one explicit profile: container or frontmatter");
+  if (container) {
+    const v2 = data?.format === AUTHORITY_FORMAT_V2;
+    const defaults = v2 ? { owner: data.owner, scope: data.scope } : null;
+    return {
+      ...(Object.hasOwn(data, "format") ? { format: data.format } : {}),
+      ...(v2 && Object.hasOwn(data, "owner") ? { owner: data.owner } : {}),
+      ...(v2 && Object.hasOwn(data, "scope") ? { scope: data.scope } : {}),
+      ...(Object.hasOwn(data, "units") ? { units: Array.isArray(data.units) ? data.units.map((unit) => normalizedUnit(unit, YAML_UNIT_KEY_ORDER, defaults)) : data.units } : {}),
+    };
+  }
+  return normalizedUnit(data, FRONTMATTER_KEY_ORDER);
+}
+
+export function stringifyCanonicalYaml(data, options = {}) {
+  return YAML.stringify(normalizedData(data, options), {
+    indent: 2,
+    lineWidth: 0,
+    minContentWidth: 0,
+    defaultStringType: "PLAIN",
+    defaultKeyType: "PLAIN",
+  });
+}
+
+function localMap(map, prefix) {
+  return new Map([...map.entries()]
+    .filter(([pointer]) => pointer === prefix || pointer.startsWith(`${prefix}/`))
+    .map(([pointer, range]) => [pointer.slice(prefix.length), range]));
+}
+
+function yamlUnitSource(parsed, index) {
+  const prefix = `/units/${index}`;
+  const locations = localMap(parsed.locations, prefix);
+  const keyLocations = localMap(parsed.keyLocations, prefix);
+  const authoredData = parsed.data.units[index];
+  let data = authoredData;
+  if (parsed.data.format === AUTHORITY_FORMAT_V2 && authoredData && typeof authoredData === "object" && !Array.isArray(authoredData)) {
+    data = { ...authoredData };
+    const unitRange = locations.get("") ?? parsed.locations.get(prefix);
+    if (!Object.hasOwn(data, "owner") && typeof parsed.data.owner === "string") {
+      data.owner = parsed.data.owner;
+      locations.set("/owner", parsed.locations.get("/owner") ?? unitRange);
+    }
+    if (!Object.hasOwn(data, "lifecycle")) {
+      data.lifecycle = "active";
+      locations.set("/lifecycle", unitRange);
+    }
+    if (!Object.hasOwn(data, "relations")) {
+      data.relations = [];
+      locations.set("/relations", unitRange);
+    }
+    if (data.kind === "rule" && data.lifecycle === "active" && !Object.hasOwn(data, "scope") && typeof parsed.data.scope === "string") {
+      data.scope = [parsed.data.scope];
+      locations.set("/scope", parsed.locations.get("/scope") ?? unitRange);
+      locations.set("/scope/0", parsed.locations.get("/scope") ?? unitRange);
+    }
+  }
+  return {
+    ok: true,
+    file: parsed.file,
+    locator: parsed.locator,
+    diagnostics: [],
+    locations,
+    keyLocations,
+    insertionPoints: authoredData && typeof authoredData === "object" && !Array.isArray(authoredData)
+      ? buildInsertionPoints(authoredData, locations, keyLocations, YAML_UNIT_KEY_ORDER)
+      : new Map(),
+    data,
+    authoredData,
+    documentFormat: parsed.data.format,
+    profile: "yaml",
+    sourcePrefix: prefix,
+    sourceIndex: index,
+    sourceText: parsed.sourceText,
+  };
+}
+
+export function parseYamlAuthority(text, absolutePath, options = {}) {
+  const parsed = parseRestrictedYaml(text, absolutePath, { ...options, keyOrder: YAML_CONTAINER_KEY_ORDER });
+  if (!parsed.ok) return { ...parsed, profile: "yaml", isDocument: true, units: [] };
+  const units = Array.isArray(parsed.data?.units)
+    ? parsed.data.units.map((_unit, index) => yamlUnitSource(parsed, index))
+    : [];
+  return { ...parsed, profile: "yaml", isDocument: true, units };
+}

package/cli/lib/authority/surface.mjs

@@ -0,0 +1,97 @@
+// The command surface the parser actually enforces.
+//
+// This is not documentation. parseOptions derives its flag admission from this
+// table, so a flag that is not here is rejected at parse time, and a flag added
+// here without a product contract fails the surface gate. Both directions have
+// to move together or something breaks.
+
+// anchors validates and exits non-zero on findings; the other three report and
+// do not. Each contract states which it is rather than the name implying it.
+export const REPOSITORY_BOUND_COMMANDS = ["anchors", "consumers", "terms", "closed-sets"];
+
+// audit reads one complete authority input plus one explicit bindings file. It
+// is corpus-bound, not repository-bound, but its public parser/help/contract
+// surface is enforced by the same consistency gate.
+export const CORPUS_BOUND_COMMANDS = ["audit"];
+export const ENFORCED_AUTHORITY_COMMANDS = [
+  ...REPOSITORY_BOUND_COMMANDS,
+  ...CORPUS_BOUND_COMMANDS,
+];
+
+// fmt is not repository-bound, but its flags and the formats it admits are
+// exactly what the authoring contract promises, so it is compared too.
+export const AUTHORING_SURFACE = {
+  fmt: {
+    contract: "nimicoding.authority-authoring.v2",
+    booleanFlags: ["json", "check"],
+    valueFlags: [],
+    integerFlags: [],
+    repeatableFlags: [],
+  },
+};
+
+export const AUTHORITY_SURFACE = {
+  audit: {
+    contract: "nimicoding.authority-audit.v2",
+    reportFormat: "nimicoding.authority-audit/v2",
+    corpus: "authority-input",
+    booleanFlags: ["json", "sarif"],
+    valueFlags: ["bindings"],
+    integerFlags: ["max-units", "max-edges", "max-bytes"],
+    repeatableFlags: [],
+  },
+  anchors: {
+    contract: "nimicoding.authority-anchors.v1",
+    reportFormat: "nimicoding.authority-anchors/v1",
+    corpus: "repository",
+    booleanFlags: ["json", "embedded-paths"],
+    valueFlags: ["spec", "scope-bindings"],
+    integerFlags: ["max-units", "max-anchors", "max-bytes"],
+    repeatableFlags: [],
+  },
+  consumers: {
+    contract: "nimicoding.authority-consumers.v1",
+    reportFormat: "nimicoding.authority-consumers/v1",
+    corpus: "repository",
+    booleanFlags: ["json"],
+    valueFlags: ["spec"],
+    integerFlags: ["max-files", "max-refs", "max-bytes"],
+    repeatableFlags: ["external-root"],
+  },
+  terms: {
+    contract: "nimicoding.authority-terms.v1",
+    reportFormat: "nimicoding.authority-terms/v1",
+    corpus: "repository",
+    booleanFlags: ["json", "code"],
+    valueFlags: ["spec", "term"],
+    integerFlags: ["max-units", "max-terms", "max-bytes"],
+    repeatableFlags: [],
+  },
+  "closed-sets": {
+    contract: "nimicoding.authority-closed-sets.v1",
+    reportFormat: "nimicoding.authority-closed-sets/v1",
+    corpus: "repository",
+    booleanFlags: ["json"],
+    valueFlags: ["spec"],
+    integerFlags: ["max-units", "max-sets", "max-bytes"],
+    repeatableFlags: [],
+  },
+};
+
+export function integerFlagAdmission() {
+  const admission = {};
+  for (const [command, entry] of Object.entries(AUTHORITY_SURFACE)) {
+    for (const flag of entry.integerFlags) {
+      const option = `--${flag}`;
+      admission[option] = admission[option] ?? [];
+      admission[option].push(command);
+    }
+  }
+  return admission;
+}
+
+export function booleanFlagAdmission(flag) {
+  return Object.entries(AUTHORITY_SURFACE)
+    .filter(([, entry]) => entry.booleanFlags.includes(flag))
+    .map(([command]) => command);
+}