@nimiplatform/nimi-coding 0.3.1 → 0.4.0

package/cli/lib/authority/scope-bindings.mjs

@@ -0,0 +1,225 @@
+import { lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import YAML, { isMap, isScalar, isSeq } from "yaml";
+
+import { compareText, createLocator, makeDiagnostic, portablePath, sortDiagnostics, sourcePointer } from "./diagnostics.mjs";
+
+const SCOPE_BINDINGS_FORMAT = "nimicoding.scope-bindings/v1";
+const contractPath = fileURLToPath(new URL("../../../contracts/authority-scope-bindings.schema.yaml", import.meta.url));
+const LINE_BREAK = /[\u000A\u000B\u000C\u000D\u0085\u2028\u2029]/u;
+
+let contractPromise = null;
+
+function exactObject(value, fields) {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    && Object.keys(value).length === fields.length
+    && Object.keys(value).every((key) => fields.includes(key));
+}
+
+function pointerToken(value) {
+  return String(value).replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
+function nodeRange(node, locator) {
+  const range = node?.range;
+  if (!Array.isArray(range)) return locator.range(0);
+  return locator.range(range[0], range[1] ?? range[0]);
+}
+
+function collectLocations(node, locator, pointer, locations) {
+  if (!node) return;
+  locations.set(pointer, nodeRange(node, locator));
+  if (isMap(node)) {
+    for (const pair of node.items) {
+      const key = isScalar(pair.key) ? String(pair.key.value) : "";
+      const childPointer = `${pointer}/${pointerToken(key)}`;
+      locations.set(childPointer, nodeRange(pair.value ?? pair.key, locator));
+      collectLocations(pair.value, locator, childPointer, locations);
+    }
+  } else if (isSeq(node)) {
+    node.items.forEach((item, index) => collectLocations(item, locator, `${pointer}/${index}`, locations));
+  }
+}
+
+async function loadContract() {
+  if (!contractPromise) contractPromise = readFile(contractPath, "utf8").then((text) => {
+    const contract = YAML.parse(text);
+    if (contract?.version !== 1 || contract?.contract?.id !== "nimicoding.scope-bindings.v1") {
+      throw new Error("installed scope binding contract is invalid");
+    }
+    return contract;
+  });
+  return contractPromise;
+}
+
+function scopeBindingDiagnostic(file, reason, location = null, code = "AUTH_SCOPE_BINDING_INVALID", repair = "declare the exact closed scope registry without inferring repository anchors") {
+  return makeDiagnostic({
+    code,
+    file,
+    range: location?.range ?? { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } },
+    pointer: location?.sourcePointer ?? "",
+    reason,
+    repair,
+  });
+}
+
+function parsedLocation(parsed, pointer) {
+  return {
+    file: parsed.file,
+    range: parsed.locations.get(pointer) ?? parsed.locations.get("") ?? { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } },
+    sourcePointer: pointer,
+  };
+}
+
+function syntaxLocation(error, file, locator) {
+  const positions = Array.isArray(error?.pos) ? error.pos : [0, 0];
+  return {
+    file,
+    range: locator.range(positions[0] ?? 0, positions[1] ?? positions[0] ?? 0),
+    sourcePointer: "",
+  };
+}
+
+function validText(value) {
+  return typeof value === "string"
+    && value.length > 0
+    && value.isWellFormed()
+    && !LINE_BREAK.test(value);
+}
+
+async function loadScopeBindings(file) {
+  const absolute = path.resolve(file);
+  const label = portablePath(absolute);
+  let bytes;
+  try {
+    const info = await lstat(absolute);
+    if (info.isSymbolicLink() || !info.isFile()) {
+      return { ok: false, diagnostics: [scopeBindingDiagnostic(label, "scope bindings must be one regular non-symlink YAML file")] };
+    }
+    bytes = await readFile(absolute);
+  } catch (error) {
+    return { ok: false, diagnostics: [scopeBindingDiagnostic(label, `scope binding file is not readable: ${error.message}`)] };
+  }
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return { ok: false, diagnostics: [scopeBindingDiagnostic(label, "scope binding bytes are not valid UTF-8")] };
+  }
+  const locator = createLocator(text);
+  const documents = YAML.parseAllDocuments(text, {
+    keepSourceTokens: true,
+    prettyErrors: false,
+    strict: true,
+    uniqueKeys: true,
+    version: "1.2",
+  });
+  if (documents.length !== 1 || documents[0].errors.length > 0 || !isMap(documents[0].contents)) {
+    const error = documents[0]?.errors?.[0];
+    const location = syntaxLocation(error, label, locator);
+    const reason = documents.length !== 1
+      ? "scope bindings must contain exactly one YAML document"
+      : error ? `invalid scope binding YAML: ${error.message.split(" at line")[0]}` : "scope bindings require one top-level mapping";
+    return { ok: false, diagnostics: [scopeBindingDiagnostic(label, reason, location)] };
+  }
+  let data;
+  try {
+    data = documents[0].toJS({ maxAliasCount: 0 });
+  } catch (error) {
+    return { ok: false, diagnostics: [scopeBindingDiagnostic(label, `invalid scope binding YAML: ${error.message}`)] };
+  }
+  const locations = new Map();
+  collectLocations(documents[0].contents, locator, "", locations);
+  const parsed = { file: label, locations, data };
+  const contract = await loadContract();
+  if (!exactObject(data, contract.fields.top)
+    || data.format !== SCOPE_BINDINGS_FORMAT
+    || !Array.isArray(data.scopes)
+    || data.scopes.length === 0) {
+    return { ok: false, diagnostics: [scopeBindingDiagnostic(label, "scope bindings require exact format and one non-empty scopes sequence", parsedLocation(parsed, ""))] };
+  }
+  const scopes = [];
+  const seenScopes = new Set();
+  for (let index = 0; index < data.scopes.length; index += 1) {
+    const value = data.scopes[index];
+    const pointer = `/scopes/${index}`;
+    if (!exactObject(value, contract.fields.scope)) {
+      return { ok: false, diagnostics: [scopeBindingDiagnostic(label, "each scope entry requires exact scope and bindings fields", parsedLocation(parsed, pointer))] };
+    }
+    if (!validText(value.scope)) {
+      return { ok: false, diagnostics: [scopeBindingDiagnostic(label, "scope must be one non-empty text line", parsedLocation(parsed, `${pointer}/scope`))] };
+    }
+    if (seenScopes.has(value.scope)) {
+      return { ok: false, diagnostics: [scopeBindingDiagnostic(label, `duplicate registered scope: ${value.scope}`, parsedLocation(parsed, `${pointer}/scope`))] };
+    }
+    seenScopes.add(value.scope);
+    if (!Array.isArray(value.bindings) || value.bindings.length === 0) {
+      return { ok: false, diagnostics: [scopeBindingDiagnostic(label, "scope bindings must be a non-empty sequence", parsedLocation(parsed, `${pointer}/bindings`))] };
+    }
+    const bindings = [];
+    for (let bindingIndex = 0; bindingIndex < value.bindings.length; bindingIndex += 1) {
+      const binding = value.bindings[bindingIndex];
+      const bindingPointer = `${pointer}/bindings/${bindingIndex}`;
+      if (!exactObject(binding, contract.fields.binding)) {
+        return { ok: false, diagnostics: [scopeBindingDiagnostic(label, "each scope binding requires exact kind and value fields", parsedLocation(parsed, bindingPointer))] };
+      }
+      if (!contract.binding_kinds.includes(binding.kind)) {
+        return { ok: false, diagnostics: [scopeBindingDiagnostic(label, `scope binding kind must be one of: ${contract.binding_kinds.join(", ")}`, parsedLocation(parsed, `${bindingPointer}/kind`))] };
+      }
+      if (!validText(binding.value)) {
+        return { ok: false, diagnostics: [scopeBindingDiagnostic(label, "scope binding value must be one non-empty text line", parsedLocation(parsed, `${bindingPointer}/value`))] };
+      }
+      bindings.push({
+        kind: binding.kind,
+        value: binding.value,
+        location: parsedLocation(parsed, `${bindingPointer}/value`),
+      });
+    }
+    scopes.push({ scope: value.scope, location: parsedLocation(parsed, `${pointer}/scope`), bindings });
+  }
+  scopes.sort((left, right) => compareText(left.scope, right.scope));
+  return { ok: true, diagnostics: [], scopes };
+}
+
+function sourceRange(source, pointer) {
+  return source.locations.get(pointer) ?? source.locations.get("") ?? source.locator.range(0);
+}
+
+export async function validateAuthorityScopeBindings(sources, bindingsPath) {
+  const parsed = await loadScopeBindings(bindingsPath);
+  if (!parsed.ok) return parsed;
+  const registered = new Set(parsed.scopes.map((entry) => entry.scope));
+  const used = new Set();
+  const diagnostics = [];
+  for (const source of sources) {
+    if (source.data.kind !== "rule" || source.data.lifecycle !== "active") continue;
+    source.data.scope.forEach((scope, index) => {
+      used.add(scope);
+      if (registered.has(scope)) return;
+      const pointer = `/scope/${index}`;
+      diagnostics.push(makeDiagnostic({
+        code: "AUTH_SCOPE_UNREGISTERED",
+        file: source.file,
+        range: sourceRange(source, pointer),
+        pointer: sourcePointer(source, pointer),
+        reason: `active rule ${source.data.id} uses unregistered scope: ${scope}`,
+        repair: "register the exact scope and its declared bindings; repository anchor resolution is not performed by check",
+      }));
+    });
+  }
+  for (const entry of parsed.scopes) {
+    if (used.has(entry.scope)) continue;
+    diagnostics.push(scopeBindingDiagnostic(
+      entry.location.file,
+      `registered scope has no active rule use: ${entry.scope}`,
+      entry.location,
+      "AUTH_SCOPE_BINDING_UNUSED",
+      "remove the dead registration or declare an active rule use only from product authority",
+    ));
+  }
+  return { ok: diagnostics.length === 0, diagnostics: sortDiagnostics(diagnostics) };
+}
+
+export { loadScopeBindings, SCOPE_BINDINGS_FORMAT };

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`;
+}