@nimiplatform/nimi-coding 0.3.1 → 0.5.0

package/cli/lib/authority/audit.mjs

@@ -0,0 +1,567 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { lstat, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import YAML, { isMap, isScalar, isSeq } from "yaml";
+
+import { compileAuthorityPath } from "./compile.mjs";
+import { createCompiledAuthoritySnapshot } from "./compiled-snapshot.mjs";
+import { compareText, createLocator, makeDiagnostic, portablePath } from "./diagnostics.mjs";
+
+const AUDIT_FORMAT = "nimicoding.authority-audit/v2";
+const BINDING_FORMAT = "nimicoding.authority-verifier-bindings/v2";
+const GRAPH_DETECTOR = "minimum-independent-incoming-reference/v1";
+const LEXICAL_DETECTOR = "exact-lexical-invariant/v1";
+const FINGERPRINT_FORMAT = "nimicoding.authority-audit-fingerprint/v2";
+const NORMATIVE_FIELDS = ["meaning", "statement", "condition", "failure"];
+const contractPath = fileURLToPath(new URL("../../../contracts/authority-verifier-bindings.schema.yaml", import.meta.url));
+
+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 !== 2 || contract?.contract?.id !== "nimicoding.authority-verifier-bindings.v2") {
+      throw new Error("installed authority verifier binding contract is invalid");
+    }
+    return contract;
+  });
+  return contractPromise;
+}
+
+function bindingDiagnostic(file, reason, location = null) {
+  return makeDiagnostic({
+    code: "AUTH_AUDIT_BINDING_INVALID",
+    file,
+    range: location?.range ?? { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } },
+    pointer: location?.sourcePointer ?? "",
+    reason,
+    repair: "declare one exact closed built-in verifier binding; project policy is never inferred from authority prose or change history",
+  });
+}
+
+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 validExactTerm(value) {
+  return typeof value === "string"
+    && value.length > 0
+    && value.trim() === value
+    && !/[\0\r\n\v\f\u0085\u2028\u2029]/u.test(value);
+}
+
+async function loadBindings(file, labelOverride = null) {
+  const absolute = path.resolve(file);
+  const label = labelOverride ?? portablePath(absolute);
+  let bytes;
+  try {
+    const info = await lstat(absolute);
+    if (info.isSymbolicLink() || !info.isFile()) {
+      return { ok: false, diagnostics: [bindingDiagnostic(label, "verifier bindings must be one regular non-symlink YAML file")] };
+    }
+    bytes = await readFile(absolute);
+  } catch (error) {
+    return { ok: false, diagnostics: [bindingDiagnostic(label, `verifier binding file is not readable: ${error.message}`)] };
+  }
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return { ok: false, diagnostics: [bindingDiagnostic(label, "verifier 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
+      ? "verifier bindings must contain exactly one YAML document"
+      : error ? `invalid verifier binding YAML: ${error.message.split(" at line")[0]}` : "verifier bindings require one top-level mapping";
+    return { ok: false, diagnostics: [bindingDiagnostic(label, reason, location)] };
+  }
+  let data;
+  try {
+    data = documents[0].toJS({ maxAliasCount: 0 });
+  } catch (error) {
+    return { ok: false, diagnostics: [bindingDiagnostic(label, `invalid verifier 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 !== BINDING_FORMAT || !Array.isArray(data.bindings) || data.bindings.length === 0) {
+    return { ok: false, diagnostics: [bindingDiagnostic(label, "verifier bindings require exact format and one non-empty bindings list", parsedLocation(parsed, ""))] };
+  }
+  const identifier = new RegExp(contract.identifier_pattern);
+  const token = new RegExp(contract.token_pattern, "u");
+  const bindings = [];
+  const bindingIds = new Set();
+  for (let index = 0; index < data.bindings.length; index += 1) {
+    const value = data.bindings[index];
+    const pointer = `/bindings/${index}`;
+    const fields = value?.detector === GRAPH_DETECTOR
+      ? contract.fields.graph_binding
+      : value?.detector === LEXICAL_DETECTOR ? contract.fields.lexical_binding : null;
+    if (fields === null) {
+      return { ok: false, diagnostics: [bindingDiagnostic(label, `unknown detector: ${String(value?.detector)}`, parsedLocation(parsed, `${pointer}/detector`))] };
+    }
+    if (!exactObject(value, fields)) {
+      return { ok: false, diagnostics: [bindingDiagnostic(label, `binding fields do not match detector ${value.detector}`, parsedLocation(parsed, pointer))] };
+    }
+    if (typeof value.id !== "string" || !identifier.test(value.id)) {
+      return { ok: false, diagnostics: [bindingDiagnostic(label, "binding id must be an exact dotted lowercase identifier", parsedLocation(parsed, `${pointer}/id`))] };
+    }
+    if (bindingIds.has(value.id)) return { ok: false, diagnostics: [bindingDiagnostic(label, `duplicate binding ID: ${value.id}`, parsedLocation(parsed, `${pointer}/id`))] };
+    bindingIds.add(value.id);
+    if (!contract.policies.includes(value.policy)) {
+      return { ok: false, diagnostics: [bindingDiagnostic(label, "binding policy must be advisory or blocking", parsedLocation(parsed, `${pointer}/policy`))] };
+    }
+
+    if (value.detector === LEXICAL_DETECTOR) {
+      if (!validExactTerm(value.term)) {
+        return { ok: false, diagnostics: [bindingDiagnostic(label, "lexical term must be non-empty trimmed single-line exact text", parsedLocation(parsed, `${pointer}/term`))] };
+      }
+      if (!contract.lexical_matches.includes(value.match)) {
+        return { ok: false, diagnostics: [bindingDiagnostic(label, "lexical match must be token or phrase", parsedLocation(parsed, `${pointer}/match`))] };
+      }
+      if (value.match === "token" && !token.test(value.term)) {
+        return { ok: false, diagnostics: [bindingDiagnostic(label, "token matching requires one exact lexical token", parsedLocation(parsed, `${pointer}/term`))] };
+      }
+      if (!contract.lexical_expectations.includes(value.expectation)) {
+        return { ok: false, diagnostics: [bindingDiagnostic(label, "lexical expectation must be present or absent", parsedLocation(parsed, `${pointer}/expectation`))] };
+      }
+      bindings.push({
+        ...value,
+        location: parsedLocation(parsed, `${pointer}/id`),
+        termLocation: parsedLocation(parsed, `${pointer}/term`),
+      });
+      continue;
+    }
+
+    if (typeof value.premise !== "string" || !identifier.test(value.premise)) {
+      return { ok: false, diagnostics: [bindingDiagnostic(label, "binding premise must be one exact authority ID", parsedLocation(parsed, `${pointer}/premise`))] };
+    }
+    if (!Array.isArray(value.targets) || value.targets.length === 0) {
+      return { ok: false, diagnostics: [bindingDiagnostic(label, "binding targets must be a non-empty exact ID list", parsedLocation(parsed, `${pointer}/targets`))] };
+    }
+    const targets = [];
+    const targetIds = new Set();
+    for (let targetIndex = 0; targetIndex < value.targets.length; targetIndex += 1) {
+      const target = value.targets[targetIndex];
+      const targetPointer = `${pointer}/targets/${targetIndex}`;
+      if (typeof target !== "string" || !identifier.test(target)) {
+        return { ok: false, diagnostics: [bindingDiagnostic(label, "binding targets must contain only exact authority IDs", parsedLocation(parsed, targetPointer))] };
+      }
+      if (targetIds.has(target)) return { ok: false, diagnostics: [bindingDiagnostic(label, `duplicate binding target: ${target}`, parsedLocation(parsed, targetPointer))] };
+      targetIds.add(target);
+      targets.push({ id: target, location: parsedLocation(parsed, targetPointer) });
+    }
+    if (!Number.isSafeInteger(value.minimum) || value.minimum <= 0) {
+      return { ok: false, diagnostics: [bindingDiagnostic(label, "binding minimum must be a positive safe integer", parsedLocation(parsed, `${pointer}/minimum`))] };
+    }
+    bindings.push({
+      ...value,
+      location: parsedLocation(parsed, `${pointer}/id`),
+      premiseLocation: parsedLocation(parsed, `${pointer}/premise`),
+      targetEntries: targets,
+    });
+  }
+  bindings.sort((left, right) => compareText(left.id, right.id));
+  return { ok: true, diagnostics: [], bindings };
+}
+
+function refused(compiled, diagnostics) {
+  return {
+    ok: false,
+    diagnostics,
+    fileCount: compiled?.fileCount ?? 0,
+    unitCount: 0,
+    auditBytes: 0,
+    audit: null,
+    partial: false,
+  };
+}
+
+function fingerprint(parts) {
+  const digest = createHash("sha256").update([FINGERPRINT_FORMAT, ...parts].join("\0")).digest("hex");
+  return `sha256:${digest}`;
+}
+
+function relatedLocation(role, location) {
+  return { role, location };
+}
+
+function compareRelatedLocation(left, right) {
+  return compareText(left.role, right.role)
+    || compareText(left.location.file, right.location.file)
+    || left.location.range.start.line - right.location.range.start.line
+    || left.location.range.start.column - right.location.range.start.column
+    || compareText(left.location.sourcePointer, right.location.sourcePointer);
+}
+
+function edgeKey(edge) {
+  return `${edge.source}\0${edge.type}\0${edge.target}`;
+}
+
+function auditBudgetDiagnostic(kind, required, admitted, location = null) {
+  return makeDiagnostic({
+    code: "AUTH_AUDIT_BUDGET",
+    file: location?.file ?? ".",
+    range: location?.range ?? { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } },
+    pointer: location?.sourcePointer ?? "",
+    reason: `complete authority audit requires ${required} ${kind} but the explicit budget is ${admitted}`,
+    repair: "increase the explicit audit budget; partial findings are forbidden",
+  });
+}
+
+function validBudget(value) {
+  return Number.isSafeInteger(value) && value > 0;
+}
+
+function validateBindingAuthority(binding, snapshot, compiled) {
+  if (binding.detector !== GRAPH_DETECTOR) return { ok: true };
+  const premise = snapshot.byId.get(binding.premise);
+  if (!premise || premise.unit.kind !== "rule" || premise.unit.lifecycle !== "active") {
+    return refused(compiled, [bindingDiagnostic(
+      binding.premiseLocation.file,
+      `binding premise must resolve to one exact active rule: ${binding.premise}`,
+      binding.premiseLocation,
+    )]);
+  }
+  for (const target of binding.targetEntries) {
+    const resolved = snapshot.byId.get(target.id);
+    if (!resolved || resolved.unit.kind !== "definition" || resolved.unit.lifecycle !== "active") {
+      return refused(compiled, [bindingDiagnostic(
+        target.location.file,
+        `binding target must resolve to one exact active definition: ${target.id}`,
+        target.location,
+      )]);
+    }
+  }
+  return { ok: true };
+}
+
+function graphFinding(binding, target, code, message, witness, primaryLocation, relatedLocations) {
+  const authorityRefs = [...new Set([binding.premise, target.id, ...(witness.incomingRefs ?? [])])].sort(compareText);
+  return {
+    code,
+    detector: GRAPH_DETECTOR,
+    binding: binding.id,
+    premise: binding.premise,
+    target: target.id,
+    basis: "configured",
+    policy: binding.policy,
+    fingerprint: fingerprint([code, GRAPH_DETECTOR, binding.id, binding.premise, target.id, `minimum=${binding.minimum}`]),
+    message,
+    authorityRefs,
+    primaryLocation,
+    relatedLocations: [...relatedLocations].sort(compareRelatedLocation),
+    witness,
+  };
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+function countExactMatches(text, term, match) {
+  if (match === "token") {
+    const expression = new RegExp(`(?<![\\p{L}\\p{N}_.-])${escapeRegExp(term)}(?![\\p{L}\\p{N}_.-])`, "gu");
+    return [...text.matchAll(expression)].length;
+  }
+  let count = 0;
+  let offset = 0;
+  while (offset <= text.length - term.length) {
+    const found = text.indexOf(term, offset);
+    if (found < 0) break;
+    count += 1;
+    offset = found + term.length;
+  }
+  return count;
+}
+
+function portableMappedLocation(compiled, pointer, basePath) {
+  const mapped = compiled.sourceMap.fields[pointer];
+  return { file: portablePath(mapped.file, basePath), range: mapped.range, sourcePointer: mapped.sourcePointer };
+}
+
+function unitIdentityLocation(snapshot, entry) {
+  return portableMappedLocation(
+    snapshot.compiled,
+    `/units/${entry.unitIndex}/id`,
+    snapshot.inputRoot,
+  );
+}
+
+function relationTargetLocation(snapshot, edge) {
+  return portableMappedLocation(
+    snapshot.compiled,
+    `/units/${edge.sourceUnitIndex}/relations/${edge.relationIndex}/target`,
+    snapshot.inputRoot,
+  );
+}
+
+function lexicalOccurrences(binding, compiled, basePath, traversedUnits) {
+  const occurrences = [];
+  compiled.ir.units.forEach((unit, unitIndex) => {
+    if (unit.lifecycle !== "active") return;
+    traversedUnits.add(unit.id);
+    for (const field of NORMATIVE_FIELDS) {
+      const text = unit.semantic?.[field];
+      if (typeof text !== "string") continue;
+      const count = countExactMatches(text, binding.term, binding.match);
+      if (count === 0) continue;
+      occurrences.push({
+        unitId: unit.id,
+        field,
+        count,
+        location: portableMappedLocation(compiled, `/units/${unitIndex}/semantic/${field}`, basePath),
+      });
+    }
+  });
+  return occurrences;
+}
+
+function evaluateLexicalBinding(binding, compiled, basePath, traversedUnits) {
+  const occurrences = lexicalOccurrences(binding, compiled, basePath, traversedUnits);
+  const count = occurrences.reduce((total, entry) => total + entry.count, 0);
+  const satisfied = binding.expectation === "present" ? count > 0 : count === 0;
+  const authorityRefs = [...new Set(occurrences.map((entry) => entry.unitId))].sort(compareText);
+  const witness = {
+    type: "exact-lexical-invariant",
+    term: binding.term,
+    match: binding.match,
+    expectation: binding.expectation,
+    satisfied,
+    count,
+    occurrences,
+  };
+  const relatedLocations = [
+    relatedLocation("binding-term", binding.termLocation),
+    ...occurrences.map((entry) => relatedLocation("normative-field", entry.location)),
+  ].sort(compareRelatedLocation);
+  if (satisfied) return null;
+  const code = "AUTH_AUDIT_EXACT_LEXICAL_INVARIANT_VIOLATION";
+  const primaryLocation = occurrences[0]?.location ?? binding.termLocation;
+  return {
+    code,
+    detector: LEXICAL_DETECTOR,
+    binding: binding.id,
+    premise: null,
+    basis: "configured",
+    policy: binding.policy,
+    fingerprint: fingerprint([code, LEXICAL_DETECTOR, binding.id, binding.match, binding.expectation, binding.term]),
+    message: `expected exact ${binding.match} ${JSON.stringify(binding.term)} to be ${binding.expectation} in active normative authority fields; observed ${count}`,
+    authorityRefs,
+    primaryLocation,
+    relatedLocations,
+    witness,
+  };
+}
+
+function evaluateGraphBinding(binding, snapshot, traversedUnits, traversedEdges) {
+  const premise = snapshot.byId.get(binding.premise);
+  traversedUnits.add(binding.premise);
+  const premiseEdges = snapshot.outgoing.get(binding.premise).filter((edge) => edge.type === "applies_to");
+  for (const edge of premiseEdges) {
+    traversedEdges.add(edgeKey(edge));
+    traversedUnits.add(edge.source);
+    traversedUnits.add(edge.target);
+  }
+  const findings = [];
+  for (const target of [...binding.targetEntries].sort((left, right) => compareText(left.id, right.id))) {
+    const targetNode = snapshot.byId.get(target.id);
+    traversedUnits.add(target.id);
+    const attachment = premiseEdges.find((edge) => edge.target === target.id) ?? null;
+    if (attachment) traversedEdges.add(edgeKey(attachment));
+    const incomingCandidates = snapshot.incoming.get(target.id).filter((edge) => edge.type === "applies_to");
+    for (const edge of incomingCandidates) {
+      traversedEdges.add(edgeKey(edge));
+      traversedUnits.add(edge.source);
+      traversedUnits.add(edge.target);
+    }
+    const incoming = incomingCandidates
+      .filter((edge) => edge.source !== binding.premise)
+      .filter((edge) => {
+        const source = snapshot.byId.get(edge.source).unit;
+        return source.kind === "rule" && source.lifecycle === "active";
+      });
+    if (!attachment) {
+      findings.push(graphFinding(
+        binding,
+        target,
+        "AUTH_AUDIT_PREMISE_TARGET_UNATTACHED",
+        `premise ${binding.premise} does not directly attach required target ${target.id}`,
+        { type: "premise-direct-attachment", relation: "applies_to", attached: false },
+        unitIdentityLocation(snapshot, targetNode),
+        [
+          relatedLocation("binding", binding.location),
+          relatedLocation("binding-target", target.location),
+          relatedLocation("premise", unitIdentityLocation(snapshot, premise)),
+        ],
+      ));
+    }
+    const observed = new Set(incoming.map((edge) => edge.source)).size;
+    if (observed < binding.minimum) {
+      const relatedLocations = [
+        relatedLocation("binding", binding.location),
+        relatedLocation("binding-target", target.location),
+        relatedLocation("premise", unitIdentityLocation(snapshot, premise)),
+      ];
+      if (attachment) relatedLocations.push(relatedLocation("premise-attachment", relationTargetLocation(snapshot, attachment)));
+      for (const edge of incoming) relatedLocations.push(relatedLocation("incoming-reference", relationTargetLocation(snapshot, edge)));
+      findings.push(graphFinding(
+        binding,
+        target,
+        "AUTH_AUDIT_MINIMUM_INDEPENDENT_INCOMING_REFERENCE",
+        `target ${target.id} has ${observed} independent active-rule applies_to references; binding requires ${binding.minimum}`,
+        {
+          type: "minimum-independent-incoming-reference",
+          relation: "applies_to",
+          minimum: binding.minimum,
+          observed,
+          incomingRefs: [...new Set(incoming.map((edge) => edge.source))].sort(compareText),
+        },
+        unitIdentityLocation(snapshot, targetNode),
+        relatedLocations,
+      ));
+    }
+  }
+  return findings;
+}
+
+export function canonicalAuditBytes(audit) {
+  return Buffer.byteLength(JSON.stringify(audit), "utf8");
+}
+
+export async function auditAuthoritySnapshot(authoritySnapshot, bindingsPath, { maxUnits, maxEdges, maxBytes, bindingLabel = null }) {
+  if (![maxUnits, maxEdges, maxBytes].every(validBudget)) {
+    return refused(null, [auditBudgetDiagnostic("positive safe-integer budget values", "all", "invalid")]);
+  }
+  const compiled = authoritySnapshot?.compiled;
+  if (compiled?.ok !== true || typeof authoritySnapshot?.inputRoot !== "string") {
+    throw new TypeError("authority audit snapshot requires one successful immutable compiler snapshot");
+  }
+  const parsedBindings = await loadBindings(bindingsPath, bindingLabel);
+  if (!parsedBindings.ok) return refused(compiled, parsedBindings.diagnostics);
+  const basePath = authoritySnapshot.inputRoot;
+  for (const binding of parsedBindings.bindings) {
+    const validation = validateBindingAuthority(binding, authoritySnapshot, compiled);
+    if (validation.ok === false) return validation;
+  }
+
+  const traversedUnits = new Set();
+  const traversedEdges = new Set();
+  const findings = [];
+  for (const binding of parsedBindings.bindings) {
+    if (binding.detector === GRAPH_DETECTOR) {
+      findings.push(...evaluateGraphBinding(binding, authoritySnapshot, traversedUnits, traversedEdges));
+    } else {
+      const finding = evaluateLexicalBinding(binding, compiled, basePath, traversedUnits);
+      if (finding) findings.push(finding);
+    }
+  }
+
+  findings.sort((left, right) => compareText(left.binding, right.binding) || compareText(left.target ?? "", right.target ?? "") || compareText(left.code, right.code));
+  const traversal = { units: traversedUnits.size, edges: traversedEdges.size };
+  const firstLocation = parsedBindings.bindings[0]?.location ?? null;
+  if (traversal.units > maxUnits) return refused(compiled, [auditBudgetDiagnostic("units", traversal.units, maxUnits, firstLocation)]);
+  if (traversal.edges > maxEdges) return refused(compiled, [auditBudgetDiagnostic("edges", traversal.edges, maxEdges, firstLocation)]);
+  const blocking = findings.some((finding) => finding.policy === "blocking");
+  const audit = {
+    format: AUDIT_FORMAT,
+    operationStatus: "completed",
+    blockingStatus: blocking ? "blocked" : "clear",
+    findings,
+    counts: {
+      bindings: {
+        configured: parsedBindings.bindings.length,
+        evaluated: parsedBindings.bindings.length,
+      },
+      returned: {
+        findings: findings.length,
+      },
+      traversal,
+    },
+    budgets: { maxUnits, maxEdges, maxBytes },
+  };
+  const auditBytes = canonicalAuditBytes(audit);
+  if (auditBytes > maxBytes) return refused(compiled, [auditBudgetDiagnostic("UTF-8 bytes", auditBytes, maxBytes, firstLocation)]);
+  return {
+    ok: true,
+    diagnostics: [],
+    fileCount: compiled.fileCount,
+    unitCount: compiled.unitCount,
+    auditBytes,
+    audit,
+    partial: false,
+  };
+}
+
+export async function auditAuthorityPath(inputPath, bindingsPath, options) {
+  const { maxUnits, maxEdges, maxBytes } = options;
+  if (![maxUnits, maxEdges, maxBytes].every(validBudget)) {
+    return refused(null, [auditBudgetDiagnostic("positive safe-integer budget values", "all", "invalid")]);
+  }
+  const compiled = await compileAuthorityPath(inputPath);
+  if (!compiled.ok) return refused(compiled, compiled.diagnostics);
+  const absoluteInput = path.resolve(inputPath);
+  const inputInfo = await stat(absoluteInput);
+  const basePath = inputInfo.isDirectory() ? absoluteInput : path.dirname(absoluteInput);
+  return auditAuthoritySnapshot(createCompiledAuthoritySnapshot(compiled, basePath), bindingsPath, options);
+}
+
+export { AUDIT_FORMAT, BINDING_FORMAT, GRAPH_DETECTOR, LEXICAL_DETECTOR };