@nimiplatform/nimi-coding 0.4.0 → 0.6.0

package/cli/lib/authority/closed-sets.mjs

@@ -65,11 +65,6 @@ function refused(diagnostics, { fileCount = 0 } = {}) {
   };
 }
 
-function isWithin(root, candidate) {
-  const relative = path.relative(root, candidate);
-  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-
 function portableRelative(repository, candidate) {
   return path.relative(repository, candidate).split(path.sep).join(path.posix.sep);
 }
@@ -540,12 +535,16 @@ export async function closedSetsAuthorityRepository(repositoryPath, specPath, {
   }
   const canonical = canonicalGroups(compiled);
 
+  const gitlinks = new Set(inventory.gitlinks);
   const classifiedFiles = await classifyTrackedTextFiles(
     inventory.repository,
     inventory.files,
-    (file) => file === ".nimi/spec" || file.startsWith(".nimi/spec/")
-      ? "authority-corpus"
-      : implementationFileKind(file) === null ? "not-a-scanned-kind" : null,
+    (file) => {
+      if (gitlinks.has(file)) return "gitlink";
+      return file === ".nimi/spec" || file.startsWith(".nimi/spec/")
+        ? "authority-corpus"
+        : implementationFileKind(file) === null ? "not-a-scanned-kind" : null;
+    },
   );
   if (classifiedFiles.error !== undefined) {
     return refused([inputDiagnostic("AUTH_CLOSED_SETS_IMPLEMENTATION_INPUT_INVALID", classifiedFiles.error)], { fileCount: compiled.fileCount });

package/cli/lib/authority/compile.mjs

@@ -1,4 +1,4 @@
-import { compareText, makeDiagnostic, sortDiagnostics } from "./diagnostics.mjs";
+import { compareText } from "./diagnostics.mjs";
 import { formattingDiagnostics, parseAuthorityPath } from "./format.mjs";
 import { validateAuthorityScopeBindings } from "./scope-bindings.mjs";
 import { buildSourceMap } from "./source-map.mjs";
@@ -39,31 +39,13 @@ async function admittedSources(inputPath) {
   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 } = {}) {
+export async function checkAuthorityPath(inputPath, { scopeBindings = 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,
+  if (!result.ok || scopeBindings === null) return {
+    ok: result.ok,
+    diagnostics: result.diagnostics,
     fileCount: result.parsed.files.length,
-    unitCount: result.ok && formatDiagnostics.length === 0 ? result.parsed.sources.length : 0,
+    unitCount: result.ok ? result.parsed.sources.length : 0,
   };
   const scopeValidation = await validateAuthorityScopeBindings(result.parsed.sources, scopeBindings);
   return {

package/cli/lib/authority/compiled-snapshot.mjs

@@ -0,0 +1,143 @@
+import path from "node:path";
+
+import { compareText, portablePath } from "./diagnostics.mjs";
+
+class ReadonlyIndex {
+  #values;
+
+  constructor(entries) {
+    this.#values = new Map(entries);
+    Object.freeze(this);
+  }
+
+  get size() {
+    return this.#values.size;
+  }
+
+  get(key) {
+    return this.#values.get(key);
+  }
+
+  has(key) {
+    return this.#values.has(key);
+  }
+
+  *entries() {
+    for (const [key, value] of this.#values) yield Object.freeze([key, value]);
+  }
+
+  keys() {
+    return this.#values.keys();
+  }
+
+  values() {
+    return this.#values.values();
+  }
+
+  forEach(callback, thisArg = undefined) {
+    for (const [key, value] of this.#values) callback.call(thisArg, value, key, this);
+  }
+
+  [Symbol.iterator]() {
+    return this.entries();
+  }
+
+  get [Symbol.toStringTag]() {
+    return "ReadonlyIndex";
+  }
+}
+
+function freezeTree(value, seen = new Set()) {
+  if (value === null || typeof value !== "object" || Object.isFrozen(value) || seen.has(value)) return value;
+  seen.add(value);
+  for (const key of Reflect.ownKeys(value)) freezeTree(value[key], seen);
+  return Object.freeze(value);
+}
+
+function readonlyIndex(entries) {
+  return new ReadonlyIndex([...entries].sort(([left], [right]) => compareText(left, right)));
+}
+
+function groupedIndex(entries, keys) {
+  const groups = new Map();
+  for (const entry of entries) {
+    for (const key of keys(entry)) {
+      const values = groups.get(key) ?? [];
+      values.push(entry);
+      groups.set(key, values);
+    }
+  }
+  return readonlyIndex([...groups.entries()].map(([key, values]) => [
+    key,
+    Object.freeze(values.sort((left, right) => compareText(left.unit.id, right.unit.id))),
+  ]));
+}
+
+function compareEdge(left, right) {
+  return compareText(left.source, right.source)
+    || compareText(left.type, right.type)
+    || compareText(left.target, right.target);
+}
+
+function adjacencyIndexes(entries) {
+  const outgoing = new Map(entries.map((entry) => [entry.unit.id, []]));
+  const incoming = new Map(entries.map((entry) => [entry.unit.id, []]));
+  for (const entry of entries) {
+    entry.unit.relations.forEach((relation, relationIndex) => {
+      const edge = Object.freeze({
+        source: entry.unit.id,
+        type: relation.type,
+        target: relation.target,
+        sourceUnitIndex: entry.unitIndex,
+        relationIndex,
+      });
+      outgoing.get(edge.source).push(edge);
+      incoming.get(edge.target).push(edge);
+    });
+  }
+  const finish = (index) => readonlyIndex([...index.entries()].map(([id, edges]) => [
+    id,
+    Object.freeze(edges.sort(compareEdge)),
+  ]));
+  return { outgoing: finish(outgoing), incoming: finish(incoming) };
+}
+
+export function createCompiledAuthoritySnapshot(compiled, inputRoot) {
+  if (
+    compiled?.ok !== true
+    || !Array.isArray(compiled?.ir?.units)
+    || compiled?.sourceMap?.fields === null
+    || typeof compiled?.sourceMap?.fields !== "object"
+  ) {
+    throw new TypeError("compiled authority snapshot requires one successful compiler result");
+  }
+  if (typeof inputRoot !== "string" || inputRoot.length === 0) {
+    throw new TypeError("compiled authority snapshot requires one non-empty input root");
+  }
+  const resolvedRoot = path.resolve(inputRoot);
+  const entries = compiled.ir.units.map((unit, unitIndex) => {
+    const mapped = compiled.sourceMap.fields[`/units/${unitIndex}/id`];
+    if (!mapped) throw new TypeError(`compiled authority snapshot cannot locate unit identity: ${unit.id}`);
+    return Object.freeze({
+      unit,
+      unitIndex,
+      container: portablePath(mapped.file, resolvedRoot),
+    });
+  });
+  const byId = readonlyIndex(entries.map((entry) => [entry.unit.id, entry]));
+  const byOwner = groupedIndex(entries, (entry) => [entry.unit.owner]);
+  const byScope = groupedIndex(entries, (entry) => entry.unit.semantic?.scope ?? []);
+  const byContainer = groupedIndex(entries, (entry) => [entry.container]);
+  const { incoming, outgoing } = adjacencyIndexes(entries);
+  freezeTree(compiled);
+  return Object.freeze({
+    inputRoot: resolvedRoot,
+    compiled,
+    byId,
+    byOwner,
+    byScope,
+    byContainer,
+    incoming,
+    outgoing,
+  });
+}

package/cli/lib/authority/consumers.mjs

@@ -3,7 +3,7 @@ import path from "node:path";
 
 import YAML from "yaml";
 
-import { compareText, makeDiagnostic, sortDiagnostics } from "./diagnostics.mjs";
+import { compareText, isPathWithin, makeDiagnostic, sortDiagnostics } from "./diagnostics.mjs";
 import { AuthorityReviewRefusal } from "./git-snapshot.mjs";
 import { resolveRepositoryCorpus } from "./repository-corpus.mjs";
 import { repositoryInventory } from "./repository-inventory.mjs";
@@ -15,7 +15,10 @@ const CONSUMERS_FORMAT = "nimicoding.authority-consumers/v1";
 // 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 single backslash followed by a common source-string escape starter ends a
+// local path instead of creating another path segment. Escaped Windows
+// separators remain visible in source as a run of at least two backslashes.
+const SPEC_REFERENCE = /\.nimi(?:\/+|\\{2,}|\\(?![nrtbfv0xu'"`$]))spec(?:(?:\/+|\\{2,}|\\(?![nrtbfv0xu'"`$]))[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.
@@ -84,11 +87,6 @@ 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");
 }
@@ -115,29 +113,66 @@ function lineCounter(text) {
   };
 }
 
+function collapseEscapedLineContinuations(text) {
+  const chunks = [];
+  const continuations = [];
+  let segmentStart = 0;
+  let searchFrom = 0;
+  let normalizedLength = 0;
+  for (let index = text.indexOf("\\", searchFrom); index !== -1; index = text.indexOf("\\", searchFrom)) {
+    const width = text[index + 1] === "\n"
+      ? 2
+      : text[index + 1] === "\r" && text[index + 2] === "\n" ? 3 : 0;
+    if (width === 0) {
+      searchFrom = index + 1;
+      continue;
+    }
+    const chunk = text.slice(segmentStart, index);
+    chunks.push(chunk);
+    normalizedLength += chunk.length;
+    continuations.push({ offset: normalizedLength, width });
+    segmentStart = index + width;
+    searchFrom = segmentStart;
+  }
+  if (continuations.length === 0) return { text, originalOffset: (index) => index };
+  chunks.push(text.slice(segmentStart));
+  return {
+    text: chunks.join(""),
+    originalOffset(index) {
+      let removedWidth = 0;
+      for (const continuation of continuations) {
+        if (continuation.offset > index) break;
+        removedWidth += continuation.width;
+      }
+      return index + removedWidth;
+    },
+  };
+}
+
 function extractReferences(consumer, text) {
+  const logical = collapseEscapedLineContinuations(text);
   const found = [];
-  for (const match of text.matchAll(SPEC_REFERENCE)) {
+  for (const match of logical.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 });
+    found.push({ index: logical.originalOffset(match.index), target, reason: null });
   }
-  for (const match of text.matchAll(SPEC_CONSTRUCTOR)) {
+  for (const match of logical.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 });
+    const continues = CONSTRUCTOR_CONTINUES.test(logical.text.slice(match.index + match[0].length));
+    found.push({ index: logical.originalOffset(match.index), target, reason: continues ? "non-literal-path-segment" : null });
   }
-  for (const match of text.matchAll(EXTERNAL_REFERENCE)) {
+  for (const match of logical.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]}:`),
+      index: logical.originalOffset(match.index + match[0].indexOf(`${match[1]}:`)),
       target: coordinate,
       scheme: match[1],
       path: externalPath,
@@ -173,18 +208,28 @@ function targetExists(target, trackedFiles) {
 // 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";
+  if (targetExists(reference.target, trackedFiles)) return { classification: "canonical", reference };
+  if (reference.target.endsWith(".")) {
+    const withoutSentencePeriod = reference.target.slice(0, -1);
+    if (targetExists(withoutSentencePeriod, trackedFiles)) {
+      return {
+        classification: "canonical",
+        reference: { ...reference, target: withoutSentencePeriod },
+      };
+    }
+  }
+  return { classification: "canonicalDead", reference };
 }
 
 async function externalTargetStatus(root, relative) {
   const candidate = path.resolve(root, ...relative.split("/"));
-  if (!isWithin(root, candidate)) return "non-canonical";
+  if (!isPathWithin(root, candidate)) return "non-canonical";
 
   let probe = candidate;
   while (true) {
     try {
       const resolved = await realpath(probe);
-      if (!isWithin(root, resolved)) return "non-canonical";
+      if (!isPathWithin(root, resolved)) return "non-canonical";
       return probe === candidate ? "authority" : "dead";
     } catch (error) {
       if (error.code !== "ENOENT" && error.code !== "ENOTDIR") throw error;
@@ -354,10 +399,14 @@ export async function consumersAuthorityRepository(repositoryPath, specPath, { m
   }
 
   const candidates = [...new Set([...inventory.files, "package.json"])].sort(compareText);
+  const gitlinks = new Set(inventory.gitlinks);
   const classifiedFiles = await classifyTrackedTextFiles(
     inventory.repository,
     candidates,
-    (file) => isSpecSource(file) ? "authority-corpus" : null,
+    (file) => {
+      if (gitlinks.has(file)) return "gitlink";
+      return isSpecSource(file) ? "authority-corpus" : null;
+    },
   );
   if (classifiedFiles.error !== undefined) {
     return refused([inputDiagnostic("AUTH_CONSUMERS_INPUT_INVALID", classifiedFiles.error)]);
@@ -401,7 +450,8 @@ export async function consumersAuthorityRepository(repositoryPath, specPath, { m
   try {
     for (const reference of references) {
       if (reference.external === undefined) {
-        classified[classifyLocalReference(reference, trackedFiles)].push(reference);
+        const local = classifyLocalReference(reference, trackedFiles);
+        classified[local.classification].push(local.reference);
         continue;
       }
       const root = roots.get(reference.external.scheme);

package/cli/lib/authority/diagnostics.mjs

@@ -1,14 +1,22 @@
 import path from "node:path";
 
+import { PROJECT_LOCAL_CLI_INVOCATION } from "../../constants.mjs";
+
 export function compareText(left, right) {
   const a = String(left);
   const b = String(right);
   return a === b ? 0 : a < b ? -1 : 1;
 }
 
+export function isPathWithin(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === ""
+    || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
 export function portablePath(filePath, cwd = process.cwd()) {
   const relative = path.relative(cwd, filePath);
-  const value = relative && !relative.startsWith("..") && !path.isAbsolute(relative) ? relative : filePath;
+  const value = relative && isPathWithin(cwd, filePath) ? relative : filePath;
   return value.split(path.sep).join(path.posix.sep);
 }
 
@@ -83,5 +91,5 @@ export const REPAIRS = {
   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",
+  format: `run \`${PROJECT_LOCAL_CLI_INVOCATION} authority fmt\` on this file`,
 };