@nimiplatform/nimi-coding 0.3.1 → 0.4.0

package/cli/lib/authority/compile.mjs

@@ -0,0 +1,110 @@
+import { compareText, makeDiagnostic, sortDiagnostics } from "./diagnostics.mjs";
+import { formattingDiagnostics, parseAuthorityPath } from "./format.mjs";
+import { validateAuthorityScopeBindings } from "./scope-bindings.mjs";
+import { buildSourceMap } from "./source-map.mjs";
+import { validateAuthoritySources } from "./validate.mjs";
+
+function lowerUnit(source) {
+  const data = source.data;
+  const unit = {
+    id: data.id,
+    kind: data.kind,
+    owner: data.owner,
+    lifecycle: data.lifecycle,
+    metadata: {
+      title: data.title,
+      ...(data.reason === undefined ? {} : { reason: data.reason }),
+    },
+    relations: [...data.relations]
+      .map((relation) => ({ type: relation.type, target: relation.target }))
+      .sort((left, right) => compareText(left.type, right.type) || compareText(left.target, right.target)),
+  };
+  if (data.lifecycle === "active" && data.kind === "definition") unit.semantic = { meaning: data.meaning };
+  if (data.lifecycle === "active" && data.kind === "rule") unit.semantic = {
+    modality: data.modality,
+    scope: [...data.scope].sort(compareText),
+    statement: data.statement,
+    condition: data.condition,
+    failure: data.failure,
+  };
+  return unit;
+}
+
+async function admittedSources(inputPath) {
+  const parsed = await parseAuthorityPath(inputPath);
+  const formatDiagnostics = formattingDiagnostics(parsed.documents, parsed.contract);
+  if (formatDiagnostics.length > 0) return { ok: false, diagnostics: formatDiagnostics, parsed };
+  const validation = validateAuthoritySources(parsed.sources, parsed.contract);
+  if (!validation.ok) return { ok: false, diagnostics: validation.diagnostics, parsed };
+  return { ok: true, diagnostics: [], parsed };
+}
+
+function requiredFormatDiagnostics(documents, requiredFormat) {
+  if (requiredFormat === null) return [];
+  return sortDiagnostics(documents.flatMap((document) => {
+    const found = document.data?.format;
+    if (found === requiredFormat) return [];
+    return [makeDiagnostic({
+      code: "AUTH_FORMAT_REQUIRED",
+      file: document.file,
+      range: document.locations.get("/format") ?? document.locations.get("") ?? document.locator.range(0),
+      pointer: "/format",
+      reason: `authority check requires format ${requiredFormat}, but ${document.file} declares ${found}`,
+      repair: "rewrite the container in the explicitly required admitted format without changing product semantics",
+    })];
+  }));
+}
+
+export async function checkAuthorityPath(inputPath, { scopeBindings = null, requireFormat = null } = {}) {
+  const result = await admittedSources(inputPath);
+  const formatDiagnostics = requiredFormatDiagnostics(result.parsed.documents, requireFormat);
+  const diagnostics = sortDiagnostics([...result.diagnostics, ...formatDiagnostics]);
+  if (!result.ok || formatDiagnostics.length > 0 || scopeBindings === null) return {
+    ok: result.ok && formatDiagnostics.length === 0,
+    diagnostics,
+    fileCount: result.parsed.files.length,
+    unitCount: result.ok && formatDiagnostics.length === 0 ? result.parsed.sources.length : 0,
+  };
+  const scopeValidation = await validateAuthorityScopeBindings(result.parsed.sources, scopeBindings);
+  return {
+    ok: scopeValidation.ok,
+    diagnostics: scopeValidation.diagnostics,
+    fileCount: result.parsed.files.length,
+    unitCount: scopeValidation.ok ? result.parsed.sources.length : 0,
+  };
+}
+
+export async function compileAuthorityPath(inputPath) {
+  const admitted = await admittedSources(inputPath);
+  const inputBytes = admitted.parsed.documents.reduce((total, document) => total + document.inputBytes, 0);
+  if (!admitted.ok) return {
+    ok: false,
+    diagnostics: admitted.diagnostics,
+    fileCount: admitted.parsed.files.length,
+    unitCount: 0,
+    inputBytes,
+    ir: null,
+    sourceMap: null,
+  };
+  const sources = [...admitted.parsed.sources].sort((left, right) => compareText(left.data.id, right.data.id));
+  const ir = { units: sources.map(lowerUnit) };
+  const mapped = buildSourceMap(sources, ir);
+  if (!mapped.ok) return {
+    ok: false,
+    diagnostics: mapped.diagnostics,
+    fileCount: admitted.parsed.files.length,
+    unitCount: 0,
+    inputBytes,
+    ir: null,
+    sourceMap: null,
+  };
+  return {
+    ok: true,
+    diagnostics: [],
+    fileCount: admitted.parsed.files.length,
+    unitCount: ir.units.length,
+    inputBytes,
+    ir,
+    sourceMap: mapped.sourceMap,
+  };
+}

package/cli/lib/authority/consumers.mjs

@@ -0,0 +1,470 @@
+import { readFile, lstat, realpath } from "node:fs/promises";
+import path from "node:path";
+
+import YAML from "yaml";
+
+import { compareText, makeDiagnostic, sortDiagnostics } from "./diagnostics.mjs";
+import { AuthorityReviewRefusal } from "./git-snapshot.mjs";
+import { resolveRepositoryCorpus } from "./repository-corpus.mjs";
+import { repositoryInventory } from "./repository-inventory.mjs";
+import { classifyTrackedTextFiles, trackedTextInventory } from "./tracked-text.mjs";
+
+const CONSUMERS_FORMAT = "nimicoding.authority-consumers/v1";
+// Literal references, in either slash direction, including the bare corpus
+// root: a checker that walks ".nimi/spec" and recurses is a consumer, and
+// requiring a trailing segment reported it as no reference at all.
+// A separator run rather than one character: inside a source string literal a
+// Windows path is written escaped, so the file text holds ".nimi\\spec".
+const SPEC_REFERENCE = /\.nimi[/\\]+spec(?:[/\\]+[A-Za-z0-9_.\\/*<>-]*[A-Za-z0-9_*<>-])?/gu;
+// A path built from adjacent string literals, e.g. path.join(root, '.nimi',
+// 'spec', 'runtime', 'x.yaml'). Reconstructed only while every segment is a
+// literal; the first non-literal segment makes the target unresolved.
+const SPEC_CONSTRUCTOR = /(['"])\.nimi\1\s*,\s*(['"])spec\2((?:\s*,\s*(['"])[A-Za-z0-9_.-]+\4)*)/gu;
+const CONSTRUCTOR_SEGMENT = /(['"])([A-Za-z0-9_.-]+)\1/gu;
+const CONSTRUCTOR_CONTINUES = /^\s*,\s*[^'")\s]/u;
+// An authority owned by another repository, named by an explicit scheme:
+// "<scheme>:spec/<path>". The scheme is whatever the projects agreed on; this
+// tool does not know any particular one, and resolves a scheme only when the
+// caller supplies a root for it.
+const EXTERNAL_UNIT_ID = "[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z](?:[a-z0-9-]*[a-z0-9])?)+";
+const EXTERNAL_REFERENCE = new RegExp(
+  `(?:^|[^A-Za-z0-9_.:/-])([a-z][a-z0-9-]*):(spec/[A-Za-z0-9_./-]*[A-Za-z0-9_-])(?:#(${EXTERNAL_UNIT_ID}))?`,
+  "gu",
+);
+const LIFECYCLE_SCRIPTS = new Set([
+  "test", "build", "lint", "prepare", "prepublishOnly", "preinstall", "postinstall",
+  "prepack", "pack", "publish", "start", "dev", "format",
+]);
+function validBudget(value) {
+  return Number.isSafeInteger(value) && value > 0;
+}
+
+function baseDiagnostic(code, reason, repair, file = ".") {
+  return makeDiagnostic({
+    code,
+    file,
+    range: { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } },
+    reason,
+    repair,
+  });
+}
+
+function budgetDiagnostic(kind, required, admitted) {
+  const option = kind === "files" ? "max-files" : kind === "references" ? "max-refs" : "max-bytes";
+  return baseDiagnostic(
+    "AUTH_CONSUMERS_BUDGET",
+    `complete authority consumer analysis requires ${required} ${kind} but ${option} is ${admitted}`,
+    "increase the explicit consumer-analysis budget; partial consumption and gate-wiring reports are forbidden",
+  );
+}
+
+function refused(diagnostics) {
+  return {
+    ok: false,
+    complete: false,
+    partial: false,
+    diagnostics: sortDiagnostics(diagnostics),
+    fileCount: 0,
+    referenceCount: 0,
+    scannedBytes: 0,
+    consumers: null,
+  };
+}
+
+function inputDiagnostic(code, reason, file = ".") {
+  return baseDiagnostic(
+    code,
+    reason,
+    "provide one exact readable Git repository, canonical corpus directory, and UTF-8 repository inputs; partial analysis is forbidden",
+    file,
+  );
+}
+
+function repositoryDiagnostic(error) {
+  return inputDiagnostic("AUTH_CONSUMERS_REPOSITORY_INVALID", error.message, error.file ?? ".");
+}
+
+function isWithin(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+async function resolveCorpus(repository, specPath) {
+  return resolveRepositoryCorpus(repository, specPath, "authority consumer");
+}
+
+function isSpecSource(file) {
+  return file === ".nimi/spec" || file.startsWith(".nimi/spec/");
+}
+
+function compareReference(left, right) {
+  return compareText(left.consumer, right.consumer)
+    || left.line - right.line
+    || compareText(left.target, right.target);
+}
+
+function lineCounter(text) {
+  let cursor = 0;
+  let line = 1;
+  return (index) => {
+    while (cursor < index) {
+      if (text[cursor] === "\n") line += 1;
+      cursor += 1;
+    }
+    return line;
+  };
+}
+
+function extractReferences(consumer, text) {
+  const found = [];
+  for (const match of text.matchAll(SPEC_REFERENCE)) {
+    const target = match[0].replace(/[/\\]+/gu, "/");
+    if (target.includes("*") || target.includes("<") || target.includes(">")) continue;
+    found.push({ index: match.index, target, reason: null });
+  }
+  for (const match of text.matchAll(SPEC_CONSTRUCTOR)) {
+    const segments = [...match[3].matchAll(CONSTRUCTOR_SEGMENT)].map((segment) => segment[2]);
+    const target = [".nimi", "spec", ...segments].join("/");
+    // A further segment that is not a string literal makes the built path
+    // unknowable here. Reporting it as unresolved keeps the scan from
+    // presenting silence as proof that nothing consumes the corpus.
+    const continues = CONSTRUCTOR_CONTINUES.test(text.slice(match.index + match[0].length));
+    found.push({ index: match.index, target, reason: continues ? "non-literal-path-segment" : null });
+  }
+  for (const match of text.matchAll(EXTERNAL_REFERENCE)) {
+    const externalPath = match[2];
+    const fragment = match[3] ?? null;
+    const coordinate = `${match[1]}:${externalPath}${fragment === null ? "" : `#${fragment}`}`;
+    const nonCanonical = externalPath.split("/").some((segment) => segment === "." || segment === "..");
+    found.push({
+      index: match.index + match[0].indexOf(`${match[1]}:`),
+      target: coordinate,
+      scheme: match[1],
+      path: externalPath,
+      fragment,
+      reason: nonCanonical ? "non-canonical-external-path" : null,
+    });
+  }
+  found.sort((left, right) => left.index - right.index);
+  const atLine = lineCounter(text);
+  const references = [];
+  const unresolved = [];
+  for (const entry of found) {
+    const record = { consumer, line: atLine(entry.index), target: entry.target };
+    if (entry.scheme !== undefined) {
+      record.external = { scheme: entry.scheme, path: entry.path };
+      if (entry.fragment !== null) record.fragment = entry.fragment;
+    }
+    if (entry.reason === null) references.push(record);
+    else unresolved.push({ ...record, reason: entry.reason });
+  }
+  return { references, unresolved };
+}
+
+function targetExists(target, trackedFiles) {
+  if (trackedFiles.has(target)) return true;
+  const prefix = `${target}/`;
+  return [...trackedFiles].some((file) => file.startsWith(prefix));
+}
+
+// Local references all start at the corpus root, so the only question is
+// whether the target exists: being inside the corpus is not proof of existing.
+// A scheme-qualified reference names an authority this repository does not
+// own. Without a root for that scheme the target is unknowable here, which is
+// not the same claim as dead.
+function classifyLocalReference(reference, trackedFiles) {
+  return targetExists(reference.target, trackedFiles) ? "canonical" : "canonicalDead";
+}
+
+async function externalTargetStatus(root, relative) {
+  const candidate = path.resolve(root, ...relative.split("/"));
+  if (!isWithin(root, candidate)) return "non-canonical";
+
+  let probe = candidate;
+  while (true) {
+    try {
+      const resolved = await realpath(probe);
+      if (!isWithin(root, resolved)) return "non-canonical";
+      return probe === candidate ? "authority" : "dead";
+    } catch (error) {
+      if (error.code !== "ENOENT" && error.code !== "ENOTDIR") throw error;
+      const parent = path.dirname(probe);
+      if (parent === probe) return "non-canonical";
+      probe = parent;
+    }
+  }
+}
+
+async function externalFragmentExists(root, relative, fragment) {
+  const bytes = await readFile(path.resolve(root, ...relative.split("/")));
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return false;
+  }
+  let container;
+  try {
+    container = YAML.parse(text);
+  } catch {
+    return false;
+  }
+  return Array.isArray(container?.units)
+    && container.units.some((unit) => unit !== null && typeof unit === "object" && unit.id === fragment);
+}
+
+function escapeRegularExpression(text) {
+  return text.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+}
+
+function containsKeyToken(text, key) {
+  const expression = new RegExp(`(?:^|[^A-Za-z0-9:_-])${escapeRegularExpression(key)}(?=$|[^A-Za-z0-9:_-])`, "u");
+  return expression.test(text);
+}
+
+function parseScripts(text) {
+  let manifest;
+  try {
+    manifest = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`repository root package.json is not valid JSON: ${error.message}`);
+  }
+  if (manifest === null || typeof manifest !== "object" || Array.isArray(manifest)) {
+    throw new Error("repository root package.json must contain one JSON object");
+  }
+  if (manifest.scripts === undefined) return {};
+  if (manifest.scripts === null || typeof manifest.scripts !== "object" || Array.isArray(manifest.scripts)) {
+    throw new Error("repository root package.json scripts must be one object");
+  }
+  const scripts = {};
+  for (const key of Object.keys(manifest.scripts).sort(compareText)) {
+    if (key.length === 0 || typeof manifest.scripts[key] !== "string") {
+      throw new Error("repository root package.json script keys must be non-empty and commands must be strings");
+    }
+    scripts[key] = manifest.scripts[key];
+  }
+  return scripts;
+}
+
+function gateWiring(scripts, workflows) {
+  const keys = Object.keys(scripts).sort(compareText);
+  const scriptMap = {};
+  let workflowReachable = 0;
+  let scriptChainedOnly = 0;
+  const orphans = [];
+  for (const key of keys) {
+    const workflowMatches = workflows
+      .filter((workflow) => containsKeyToken(workflow.text, key))
+      .map((workflow) => workflow.file);
+    const referencedByScripts = keys
+      .filter((other) => other !== key && containsKeyToken(scripts[other], key));
+    const orphan = workflowMatches.length === 0
+      && referencedByScripts.length === 0
+      && !LIFECYCLE_SCRIPTS.has(key);
+    if (workflowMatches.length > 0) workflowReachable += 1;
+    else if (referencedByScripts.length > 0) scriptChainedOnly += 1;
+    if (orphan) orphans.push(key);
+    scriptMap[key] = { workflows: workflowMatches, referencedByScripts, orphan };
+  }
+  return {
+    counts: {
+      totalKeys: keys.length,
+      workflowReachable,
+      scriptChainedOnly,
+      orphan: orphans.length,
+    },
+    orphans,
+    scripts: scriptMap,
+  };
+}
+
+async function readScannedFiles(repository, files, maxBytes) {
+  let statedBytes = 0;
+  for (const file of files) {
+    const absolute = path.join(repository, ...file.split("/"));
+    let metadata;
+    try {
+      metadata = await lstat(absolute);
+    } catch (error) {
+      throw new Error(`${file} is not readable: ${error.message}`);
+    }
+    if (!metadata.isFile() || metadata.isSymbolicLink()) throw new Error(`${file} must be one regular non-symlink file`);
+    statedBytes += metadata.size;
+  }
+  if (statedBytes > maxBytes) return { budget: budgetDiagnostic("UTF-8 bytes", statedBytes, maxBytes) };
+
+  const texts = new Map();
+  let scannedBytes = 0;
+  for (const file of files) {
+    let bytes;
+    try {
+      bytes = await readFile(path.join(repository, ...file.split("/")));
+    } catch (error) {
+      throw new Error(`${file} is not readable: ${error.message}`);
+    }
+    scannedBytes += bytes.length;
+    if (scannedBytes > maxBytes) return { budget: budgetDiagnostic("UTF-8 bytes", scannedBytes, maxBytes) };
+    try {
+      texts.set(file, new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    } catch {
+      throw new Error(`${file} is not valid UTF-8`);
+    }
+  }
+  return { texts, scannedBytes, budget: null };
+}
+
+async function resolveExternalRoots(externalRoots) {
+  const resolved = new Map();
+  for (const [scheme, root] of externalRoots) {
+    let real;
+    try {
+      real = await realpath(path.resolve(root));
+    } catch (error) {
+      throw new Error(`external authority root ${scheme} is not readable: ${error.message}`);
+    }
+    const metadata = await lstat(real);
+    if (!metadata.isDirectory()) throw new Error(`external authority root ${scheme} must be one directory`);
+    resolved.set(scheme, real);
+  }
+  return resolved;
+}
+
+export async function consumersAuthorityRepository(repositoryPath, specPath, { maxFiles, maxRefs, maxBytes, externalRoots = [] }) {
+  if (![maxFiles, maxRefs, maxBytes].every(validBudget)) {
+    return refused([baseDiagnostic(
+      "AUTH_CONSUMERS_BUDGET",
+      "authority consumer-analysis budgets must be positive safe integers",
+      "provide explicit positive safe max-files, max-refs, and max-bytes budgets",
+    )]);
+  }
+
+  let inventory;
+  try {
+    inventory = await repositoryInventory(repositoryPath);
+  } catch (error) {
+    if (error instanceof AuthorityReviewRefusal) return refused([repositoryDiagnostic(error)]);
+    throw error;
+  }
+
+  let corpus;
+  try {
+    corpus = await resolveCorpus(inventory.repository, specPath);
+  } catch (error) {
+    return refused([inputDiagnostic("AUTH_CONSUMERS_CORPUS_INVALID", error.message)]);
+  }
+
+  const candidates = [...new Set([...inventory.files, "package.json"])].sort(compareText);
+  const classifiedFiles = await classifyTrackedTextFiles(
+    inventory.repository,
+    candidates,
+    (file) => isSpecSource(file) ? "authority-corpus" : null,
+  );
+  if (classifiedFiles.error !== undefined) {
+    return refused([inputDiagnostic("AUTH_CONSUMERS_INPUT_INVALID", classifiedFiles.error)]);
+  }
+  const scanFiles = classifiedFiles.scanned;
+  if (!scanFiles.includes("package.json")) {
+    return refused([inputDiagnostic("AUTH_CONSUMERS_MANIFEST_INVALID", "repository root package.json must be classified as UTF-8 text", "package.json")]);
+  }
+  if (scanFiles.length > maxFiles) return refused([budgetDiagnostic("files", scanFiles.length, maxFiles)]);
+
+  let scanned;
+  try {
+    scanned = await readScannedFiles(inventory.repository, scanFiles, maxBytes);
+  } catch (error) {
+    return refused([inputDiagnostic("AUTH_CONSUMERS_INPUT_INVALID", error.message)]);
+  }
+  if (scanned.budget) return refused([scanned.budget]);
+
+  const references = [];
+  const unresolvedReferences = [];
+  for (const file of scanFiles) {
+    const extracted = extractReferences(file, scanned.texts.get(file));
+    references.push(...extracted.references);
+    unresolvedReferences.push(...extracted.unresolved);
+  }
+  references.sort(compareReference);
+  unresolvedReferences.sort(compareReference);
+  const referenceTotal = references.length + unresolvedReferences.length;
+  if (referenceTotal > maxRefs) return refused([budgetDiagnostic("references", referenceTotal, maxRefs)]);
+
+  let roots;
+  try {
+    roots = await resolveExternalRoots(externalRoots);
+  } catch (error) {
+    return refused([inputDiagnostic("AUTH_CONSUMERS_EXTERNAL_ROOT_INVALID", error.message)]);
+  }
+  const trackedFiles = new Set(inventory.files);
+  const classified = {
+    canonical: [], canonicalDead: [], externalAuthority: [], externalDead: [], externalUnresolved: [],
+  };
+  try {
+    for (const reference of references) {
+      if (reference.external === undefined) {
+        classified[classifyLocalReference(reference, trackedFiles)].push(reference);
+        continue;
+      }
+      const root = roots.get(reference.external.scheme);
+      if (root === undefined) {
+        classified.externalUnresolved.push(reference);
+        continue;
+      }
+      const status = await externalTargetStatus(root, reference.external.path);
+      const fragmentExists = status === "authority" && reference.fragment !== undefined
+        ? await externalFragmentExists(root, reference.external.path, reference.fragment)
+        : true;
+      if (status === "authority" && fragmentExists) classified.externalAuthority.push(reference);
+      else if (status === "dead" || (status === "authority" && !fragmentExists)) classified.externalDead.push(reference);
+      else unresolvedReferences.push({ ...reference, reason: "non-canonical-external-path" });
+    }
+  } catch (error) {
+    return refused([inputDiagnostic("AUTH_CONSUMERS_EXTERNAL_ROOT_INVALID", `external authority target cannot be resolved: ${error.message}`)]);
+  }
+  unresolvedReferences.sort(compareReference);
+
+  let scripts;
+  try {
+    scripts = parseScripts(scanned.texts.get("package.json"));
+  } catch (error) {
+    return refused([inputDiagnostic("AUTH_CONSUMERS_MANIFEST_INVALID", error.message, "package.json")]);
+  }
+  const workflows = inventory.files
+    .filter((file) => /^\.github\/workflows\/[^/]+\.ya?ml$/u.test(file))
+    .map((file) => ({ file, text: scanned.texts.get(file) }))
+    .filter((workflow) => workflow.text !== undefined);
+  const wiring = gateWiring(scripts, workflows);
+  const classifiedReferenceTotal = Object.values(classified).reduce((total, entries) => total + entries.length, 0);
+  const specConsumption = {
+    counts: {
+      total: classifiedReferenceTotal,
+      canonical: classified.canonical.length,
+      canonicalDead: classified.canonicalDead.length,
+      externalAuthority: classified.externalAuthority.length,
+      externalDead: classified.externalDead.length,
+      externalUnresolved: classified.externalUnresolved.length,
+      unresolved: unresolvedReferences.length,
+    },
+    references: classified,
+    unresolved: unresolvedReferences,
+  };
+  const consumers = {
+    format: CONSUMERS_FORMAT,
+    complete: true,
+    fileInventory: trackedTextInventory(candidates.length, classifiedFiles),
+    specConsumption,
+    gateWiring: wiring,
+  };
+  return {
+    ok: true,
+    complete: true,
+    partial: false,
+    diagnostics: [],
+    fileCount: scanFiles.length,
+    referenceCount: referenceTotal,
+    scannedBytes: scanned.scannedBytes,
+    trackedPathSetDigest: inventory.trackedPathSetDigest,
+    consumers,
+  };
+}
+
+export { CONSUMERS_FORMAT, LIFECYCLE_SCRIPTS };

package/cli/lib/authority/diagnostics.mjs

@@ -0,0 +1,87 @@
+import path from "node:path";
+
+export function compareText(left, right) {
+  const a = String(left);
+  const b = String(right);
+  return a === b ? 0 : a < b ? -1 : 1;
+}
+
+export function portablePath(filePath, cwd = process.cwd()) {
+  const relative = path.relative(cwd, filePath);
+  const value = relative && !relative.startsWith("..") && !path.isAbsolute(relative) ? relative : filePath;
+  return value.split(path.sep).join(path.posix.sep);
+}
+
+export function createLocator(text) {
+  const lineStarts = [0];
+  for (let index = 0; index < text.length; index += 1) {
+    if (text[index] === "\n") lineStarts.push(index + 1);
+  }
+  function position(offset) {
+    const bounded = Math.max(0, Math.min(offset, text.length));
+    let low = 0;
+    let high = lineStarts.length;
+    while (low + 1 < high) {
+      const middle = Math.floor((low + high) / 2);
+      if (lineStarts[middle] <= bounded) low = middle;
+      else high = middle;
+    }
+    return {
+      line: low + 1,
+      column: [...text.slice(lineStarts[low], bounded)].length + 1,
+    };
+  }
+  return {
+    range(start, end = start) {
+      return { start: position(start), end: position(end) };
+    },
+  };
+}
+
+export function makeDiagnostic({ code, file, range, pointer = "", reason, repair, related = [] }) {
+  return {
+    code,
+    severity: "error",
+    path: file,
+    range,
+    pointer,
+    reason,
+    repair,
+    related,
+  };
+}
+
+function comparePosition(left, right) {
+  return left.line - right.line || left.column - right.column;
+}
+
+export function sortDiagnostics(diagnostics) {
+  return [...diagnostics].sort((left, right) => (
+    compareText(left.path, right.path)
+    || comparePosition(left.range.start, right.range.start)
+    || compareText(left.code, right.code)
+    || compareText(left.pointer, right.pointer)
+  ));
+}
+
+export function sourcePointer(source, pointer) {
+  return `${source.sourcePrefix ?? ""}${pointer}`;
+}
+
+export function relatedLocation(source, pointer, role) {
+  return {
+    path: source.file,
+    range: source.locations.get(pointer) ?? source.locations.get("") ?? source.locator.range(0),
+    pointer: sourcePointer(source, pointer),
+    role,
+  };
+}
+
+export const REPAIRS = {
+  structural: "make the source structure explicit without inventing product semantics",
+  required: "declare the required value from product authority",
+  invalid: "replace the value with one admitted by the authoring contract",
+  relation: "repair the explicit relation using product authority; do not infer a target",
+  duplicate: "keep one declaration chosen from product authority and remove the duplicate",
+  format: "run `nimicoding authority fmt` on this file",
+};