@nimiplatform/nimi-coding 0.4.0 → 0.6.0

package/cli/lib/code/authority-annotation-scan.mjs

@@ -0,0 +1,162 @@
+import { Buffer } from "node:buffer";
+
+import ts from "typescript";
+
+import { compareText, createLocator } from "../authority/diagnostics.mjs";
+
+const EXACT_MARKER = /^\/\/ nimi-(authority|deprecated): ([^\s]+)$/u;
+const MARKER_CANDIDATE = /^\/\/[ \t]*nimi-(?:authority|deprecated)\b/u;
+const PHYSICAL_CANDIDATE = /^[ \t]*\/\/[ \t]*nimi-(?:authority|deprecated)\b/mu;
+const NEARBY_SOURCE_BYTES = 512;
+
+function comparePosition(left, right) {
+  return left.line - right.line || left.column - right.column;
+}
+
+function utf8Prefix(text, maxBytes) {
+  let value = "";
+  let bytes = 0;
+  for (const character of text) {
+    const size = Buffer.byteLength(character, "utf8");
+    if (bytes + size > maxBytes) break;
+    value += character;
+    bytes += size;
+  }
+  return value;
+}
+
+function nearbySource(path, text, locator, markerEnd) {
+  const start = markerEnd < text.length && text[markerEnd] === "\r" ? markerEnd + 1 : markerEnd;
+  const contentStart = start < text.length && text[start] === "\n" ? start + 1 : start;
+  const candidate = text.slice(contentStart);
+  const value = utf8Prefix(candidate, NEARBY_SOURCE_BYTES);
+  return {
+    location: { path, range: locator.range(contentStart, contentStart + value.length) },
+    text: value,
+    truncated: value.length < candidate.length,
+  };
+}
+
+function parseComment(path, text, locator, start, end, identifier) {
+  const lineStart = text.lastIndexOf("\n", start - 1) + 1;
+  if (text.slice(lineStart, start).trim().length > 0) return { occurrence: null, finding: null };
+  const raw = text.slice(start, end).replace(/\r$/u, "");
+  if (!MARKER_CANDIDATE.test(raw)) return { occurrence: null, finding: null };
+  const location = { path, range: locator.range(start, end) };
+  const match = EXACT_MARKER.exec(raw);
+  if (match === null || !identifier.test(match[2])) {
+    return {
+      occurrence: null,
+      finding: {
+        kind: "invalid-annotation",
+        source_path: path,
+        annotation_location: location,
+        reason: "annotation must match the exact standalone exact-ID-only line grammar",
+      },
+    };
+  }
+  return {
+    occurrence: {
+      annotation_kind: match[1],
+      authority_id: match[2],
+      source_path: path,
+      annotation_location: location,
+      nearby_source: nearbySource(path, text, locator, end),
+    },
+    finding: null,
+  };
+}
+
+function typeScriptLineComments(path, text) {
+  const scriptKind = path.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+  const sourceFile = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, scriptKind);
+  const comments = new Map();
+  const jsxTextRanges = [];
+  function add(ranges) {
+    for (const range of ranges ?? []) {
+      if (range.kind === ts.SyntaxKind.SingleLineCommentTrivia) {
+        comments.set(`${range.pos}:${range.end}`, { start: range.pos, end: range.end });
+      }
+    }
+  }
+  const pending = [sourceFile];
+  while (pending.length > 0) {
+    const node = pending.pop();
+    if (ts.isJsxText(node)) jsxTextRanges.push({ start: node.pos, end: node.end });
+    add(ts.getLeadingCommentRanges(text, node.pos));
+    add(ts.getTrailingCommentRanges(text, node.end));
+    pending.push(...node.getChildren(sourceFile));
+  }
+  return [...comments.values()]
+    .filter((comment) => !jsxTextRanges.some((range) => comment.start >= range.start && comment.end <= range.end))
+    .sort((left, right) => left.start - right.start || left.end - right.end);
+}
+
+function goLineComments(text) {
+  const comments = [];
+  let index = 0;
+  while (index < text.length) {
+    const character = text[index];
+    if (character === "/" && text[index + 1] === "/") {
+      const start = index;
+      index += 2;
+      while (index < text.length && text[index] !== "\n") index += 1;
+      comments.push({ start, end: index });
+      continue;
+    }
+    if (character === "/" && text[index + 1] === "*") {
+      const close = text.indexOf("*/", index + 2);
+      index = close < 0 ? text.length : close + 2;
+      continue;
+    }
+    if (character === "`" || character === "\"" || character === "'") {
+      const quote = character;
+      index += 1;
+      while (index < text.length) {
+        if (quote !== "`" && text[index] === "\\") {
+          index += Math.min(2, text.length - index);
+          continue;
+        }
+        if (text[index] === quote) {
+          index += 1;
+          break;
+        }
+        index += 1;
+      }
+      continue;
+    }
+    index += 1;
+  }
+  return comments;
+}
+
+export function scanAuthorityAnnotations(path, text, identifierPattern) {
+  if (!PHYSICAL_CANDIDATE.test(text)) return { occurrences: [], findings: [] };
+  const locator = createLocator(text);
+  const identifier = new RegExp(identifierPattern, "u");
+  const comments = path.endsWith(".go") ? goLineComments(text) : typeScriptLineComments(path, text);
+  const occurrences = [];
+  const findings = [];
+  for (const comment of comments) {
+    const parsed = parseComment(path, text, locator, comment.start, comment.end, identifier);
+    if (parsed.occurrence !== null) occurrences.push(parsed.occurrence);
+    if (parsed.finding !== null) findings.push(parsed.finding);
+  }
+  occurrences.sort(compareOccurrences);
+  findings.sort(compareAnnotationFindings);
+  return { occurrences, findings };
+}
+
+export function compareOccurrences(left, right) {
+  return compareText(left.source_path, right.source_path)
+    || comparePosition(left.annotation_location.range.start, right.annotation_location.range.start)
+    || compareText(left.annotation_kind, right.annotation_kind)
+    || compareText(left.authority_id, right.authority_id);
+}
+
+export function compareAnnotationFindings(left, right) {
+  return compareText(left.source_path, right.source_path)
+    || comparePosition(left.annotation_location.range.start, right.annotation_location.range.start)
+    || compareText(left.kind, right.kind)
+    || compareText(left.reason, right.reason);
+}

package/cli/lib/code/authority-annotations.mjs

@@ -0,0 +1,293 @@
+import { Buffer } from "node:buffer";
+import path from "node:path";
+
+import { compileAuthorityPath } from "../authority/compile.mjs";
+import { compareText } from "../authority/diagnostics.mjs";
+import { captureStableRegularFile } from "../authority/git-snapshot.mjs";
+import { buildAuthorityGraphSnapshot } from "../authority/graph.mjs";
+import { repositoryInventory } from "../authority/repository-inventory.mjs";
+import { resolveRepositoryCorpus } from "../authority/repository-corpus.mjs";
+import { loadAuthorityContract } from "../authority/source-yaml.mjs";
+import {
+  compareAnnotationFindings,
+  compareOccurrences,
+  scanAuthorityAnnotations,
+} from "./authority-annotation-scan.mjs";
+
+const SUPPORTED_SOURCE = /(?:\.d)?\.tsx?$|\.go$/u;
+const UTF8 = new TextDecoder("utf-8", { fatal: true });
+const CLASSIFICATION_ORDER = new Map([
+  ["active-reference", 0],
+  ["removed-reference", 1],
+  ["superseded-reference", 2],
+  ["missing-reference", 3],
+  ["explicit-deprecated", 4],
+]);
+
+export class CodeAuthorityFailure extends Error {
+  constructor(code, message, exitCode = 2) {
+    super(message);
+    this.name = "CodeAuthorityFailure";
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+}
+
+function fail(code, message, exitCode = 2) {
+  throw new CodeAuthorityFailure(code, message, exitCode);
+}
+
+function compareLocation(left, right) {
+  return left.range.start.line - right.range.start.line
+    || left.range.start.column - right.range.start.column;
+}
+
+function compareClassifications(left, right) {
+  return (CLASSIFICATION_ORDER.get(left) ?? 99) - (CLASSIFICATION_ORDER.get(right) ?? 99)
+    || compareText(left, right);
+}
+
+function directRelations(graph, id) {
+  return {
+    authored_successors: (graph.incoming.get(id) ?? []).map((edge) => ({
+      id: edge.source,
+      authority_location: edge.sourceLocation,
+      relation_location: edge.relationLocation,
+    })),
+    authored_supersedes: (graph.outgoing.get(id) ?? []).map((edge) => ({
+      id: edge.target,
+      authority_location: edge.targetLocation,
+      relation_location: edge.relationLocation,
+    })),
+  };
+}
+
+function authorityDescriptor(graph, id) {
+  const entry = graph.byId.get(id);
+  if (entry === undefined) {
+    return {
+      id,
+      resolution: "missing",
+      lifecycle: null,
+      authority_location: null,
+      authored_successors: [],
+      authored_supersedes: [],
+    };
+  }
+  return {
+    id,
+    resolution: "resolved",
+    lifecycle: entry.node.lifecycle,
+    authority_location: entry.node.location,
+    ...directRelations(graph, id),
+  };
+}
+
+function classifyOccurrence(graph, occurrence) {
+  const descriptor = authorityDescriptor(graph, occurrence.authority_id);
+  const classifications = [];
+  if (descriptor.resolution === "missing") classifications.push("missing-reference");
+  else if (descriptor.lifecycle === "removed") classifications.push("removed-reference");
+  else classifications.push("active-reference");
+  if (descriptor.authored_successors.length > 0) classifications.push("superseded-reference");
+  if (occurrence.annotation_kind === "deprecated") classifications.push("explicit-deprecated");
+  return {
+    ...occurrence,
+    classifications: classifications.sort(compareClassifications),
+    authority: descriptor,
+    pairing: occurrence.annotation_kind === "deprecated" ? "not_evaluated" : null,
+  };
+}
+
+function findingFromOccurrence(occurrence, kind) {
+  return {
+    kind,
+    source_path: occurrence.source_path,
+    annotation_kind: occurrence.annotation_kind,
+    authority_id: occurrence.authority_id,
+    annotation_location: occurrence.annotation_location,
+    authority_location: occurrence.authority.authority_location,
+    authored_successors: occurrence.authority.authored_successors,
+  };
+}
+
+function compareFindings(left, right) {
+  return compareText(left.source_path, right.source_path)
+    || compareLocation(left.annotation_location, right.annotation_location)
+    || compareText(left.kind, right.kind)
+    || compareText(left.authority_id ?? "", right.authority_id ?? "");
+}
+
+function auditFindings(occurrences, invalidFindings) {
+  const findings = [...invalidFindings];
+  for (const occurrence of occurrences) {
+    for (const kind of occurrence.classifications) {
+      if (kind !== "active-reference") findings.push(findingFromOccurrence(occurrence, kind));
+    }
+  }
+  return findings.sort(compareFindings);
+}
+
+function countsFor(occurrences, invalidFindings) {
+  const counts = {
+    annotations: occurrences.length,
+    "active-reference": 0,
+    "explicit-deprecated": 0,
+    "removed-reference": 0,
+    "superseded-reference": 0,
+    "missing-reference": 0,
+    "invalid-annotation": invalidFindings.length,
+  };
+  for (const occurrence of occurrences) {
+    for (const classification of occurrence.classifications) counts[classification] += 1;
+  }
+  return counts;
+}
+
+function normalizeSourceSelector(source) {
+  if (
+    typeof source !== "string"
+    || source.length === 0
+    || source.includes("\\")
+    || source.startsWith("/")
+    || source.split("/").some((segment) => segment === "" || segment === "." || segment === "..")
+  ) return null;
+  return source;
+}
+
+async function readCurrentSource(repository, source, remainingBytes) {
+  const absolute = path.join(repository, ...source.split("/"));
+  let bytes;
+  try {
+    bytes = await captureStableRegularFile(absolute, source, repository, remainingBytes);
+  } catch (error) {
+    if (error?.code === "AUTH_REVIEW_INPUT_BUDGET") {
+      fail("CODE_AUTHORITY_INPUT_BUDGET", "max-bytes cannot contain the complete authority and source input", 1);
+    }
+    fail("CODE_AUTHORITY_SOURCE_INVALID", "tracked current source is not one stable repository-contained regular file");
+  }
+  let text;
+  try {
+    text = UTF8.decode(bytes);
+  } catch {
+    fail("CODE_AUTHORITY_SOURCE_INVALID", "tracked current source is not valid UTF-8");
+  }
+  return { bytes: bytes.length, text };
+}
+
+export async function queryCodeAuthority({ repository: repositoryPath, selector, maxFiles, maxBytes }) {
+  let inventory;
+  try {
+    inventory = await repositoryInventory(repositoryPath);
+  } catch {
+    fail("CODE_AUTHORITY_REPOSITORY_INVALID", "repo must name one exact readable Git worktree root");
+  }
+  let corpus;
+  try {
+    corpus = await resolveRepositoryCorpus(
+      inventory.repository,
+      path.join(inventory.repository, ".nimi", "spec"),
+      "code authority",
+    );
+  } catch {
+    fail("CODE_AUTHORITY_CORPUS_INVALID", "repository canonical authority corpus is not readable");
+  }
+  let compiled;
+  try {
+    compiled = await compileAuthorityPath(corpus.path);
+  } catch {
+    fail("CODE_AUTHORITY_CORPUS_INVALID", "canonical authority corpus cannot be compiled");
+  }
+  if (!compiled.ok) fail("CODE_AUTHORITY_CORPUS_INVALID", "canonical authority corpus does not compile");
+  if (compiled.inputBytes > maxBytes) {
+    fail("CODE_AUTHORITY_INPUT_BUDGET", "max-bytes cannot contain the complete authority and source input", 1);
+  }
+  const contract = await loadAuthorityContract();
+  const identifier = new RegExp(contract.identifier_pattern, "u");
+  if (selector.kind === "authority" && !identifier.test(selector.id)) {
+    fail("CODE_USAGE", "authority selector must be one exact canonical authority ID");
+  }
+
+  const tracked = new Set(inventory.files);
+  const gitlinks = new Set(inventory.gitlinks);
+  let sourcePaths;
+  if (selector.kind === "source") {
+    const normalized = normalizeSourceSelector(selector.path);
+    if (normalized === null || !SUPPORTED_SOURCE.test(normalized) || !tracked.has(normalized) || gitlinks.has(normalized)) {
+      fail("CODE_AUTHORITY_SOURCE_INVALID", "source selector must name one tracked .ts, .tsx, or .go file");
+    }
+    sourcePaths = [normalized];
+  } else {
+    sourcePaths = inventory.files.filter((source) => SUPPORTED_SOURCE.test(source) && !gitlinks.has(source));
+  }
+
+  const requiredFiles = compiled.fileCount + sourcePaths.length;
+  if (requiredFiles > maxFiles) {
+    fail("CODE_AUTHORITY_FILES_BUDGET", "max-files cannot contain the complete authority and source file set", 1);
+  }
+  const graph = buildAuthorityGraphSnapshot(compiled, inventory.repository, ["supersedes"]);
+  const occurrences = [];
+  const invalidFindings = [];
+  let inputBytes = compiled.inputBytes;
+  for (const source of sourcePaths) {
+    const current = await readCurrentSource(inventory.repository, source, maxBytes - inputBytes);
+    inputBytes += current.bytes;
+    const scanned = scanAuthorityAnnotations(source, current.text, contract.identifier_pattern);
+    occurrences.push(...scanned.occurrences.map((occurrence) => classifyOccurrence(graph, occurrence)));
+    invalidFindings.push(...scanned.findings);
+  }
+  occurrences.sort(compareOccurrences);
+  invalidFindings.sort(compareAnnotationFindings);
+  const findings = auditFindings(occurrences, invalidFindings);
+  const counts = countsFor(occurrences, invalidFindings);
+  const usage = {
+    authority_files: compiled.fileCount,
+    source_files: sourcePaths.length,
+    input_bytes: inputBytes,
+    max_files: maxFiles,
+    max_bytes: maxBytes,
+  };
+
+  if (selector.kind === "authority") {
+    const selectedOccurrences = occurrences.filter((occurrence) => occurrence.authority_id === selector.id);
+    const selectedFindings = findings.filter((finding) => finding.authority_id === selector.id);
+    return {
+      operation: "authority-to-code",
+      scope: { repository: ".", authority_id: selector.id },
+      result: {
+        authority: authorityDescriptor(graph, selector.id),
+        occurrences: selectedOccurrences,
+      },
+      findings: selectedFindings,
+      counts: countsFor(selectedOccurrences, []),
+      usage,
+    };
+  }
+  if (selector.kind === "source") {
+    return {
+      operation: "code-to-authority",
+      scope: { repository: ".", source_path: selector.path },
+      result: {
+        source_path: selector.path,
+        occurrences,
+        unannotated_semantics: "not_evaluated",
+      },
+      findings,
+      counts,
+      usage,
+    };
+  }
+  return {
+    operation: "lifecycle-audit",
+    scope: { repository: ".", source_languages: ["go", "typescript", "tsx"] },
+    result: {
+      conclusion: findings.length === 0
+        ? "annotated implementation surface has no deterministic authority lifecycle residue"
+        : "annotated implementation surface contains deterministic authority lifecycle residue",
+      unannotated_semantics: "not_evaluated",
+    },
+    findings,
+    counts,
+    usage,
+  };
+}