@ecoma-io/archkeep 0.23.0 → 0.24.1

package/src/analysis/python.mjs

@@ -227,17 +227,20 @@ import {
 
 /** PEP 503 name normalization: case-insensitive, runs of `-_.` collapse to `-`. */
 export function normalizePackageName(name) {
+  // used by its own test
   return name.toLowerCase().replace(/[-_.]+/g, "-");
 }
 
 /** The package name a PEP 508 requirement string refers to, or null. */
 export function parseRequirementName(requirement) {
+  // used by its own test
   const match = requirement.trim().match(/^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?/);
   return match ? normalizePackageName(match[0]) : null;
 }
 
 /** Every dependency name a pyproject manifest declares, deduped. */
 export function collectDeclaredDependencies(manifest) {
+  // used by its own test
   const names = new Set();
   const groups = [
     manifest.project?.dependencies ?? [],
@@ -630,6 +633,7 @@ const READ_BUILD_BACKENDS = new Set([
  * @returns {{ directories: string[], unmodelled: string[] }}
  */
 export function pythonPackageLayout(manifestText) {
+  // used by its own test
   if (manifestText === null) return { directories: [], unmodelled: [] };
   const manifest = parseManifest(manifestText);
   if (manifest === null) {
@@ -730,6 +734,7 @@ function ownPackageOf(file, projectRoot, directories) {
  * @returns {Map<string, { file: string|null, namespace: boolean }>}
  */
 export function pythonModuleIndex(projectRoot, files, directories = []) {
+  // used by its own test
   const index = new Map();
   for (const file of files) {
     if (!file.endsWith(".py")) continue;
@@ -755,6 +760,7 @@ export function pythonModuleIndex(projectRoot, files, directories = []) {
  * @returns {string[]}
  */
 export function pythonImportRoots(projectRoot, files, directories = []) {
+  // used by its own test
   return [...pythonModuleIndex(projectRoot, files, directories).keys()]
     .filter((name) => !name.includes("."))
     .sort();
@@ -1059,6 +1065,7 @@ function joinContinuedStatement(physicalLines, lineOffsets, index) {
  *   continuation?: boolean }[]}
  */
 export function parsePythonImportSites(pythonText) {
+  // used by its own test
   const sites = [];
   // Byte tolerance (`contract.md`): the lines a CRLF file splits into still
   // carry their `\r`, and a BOM-prefixed file's first line starts with
@@ -1166,6 +1173,7 @@ export function parsePythonImportSites(pythonText) {
  * @returns {string[]} Reasons, at most one per malformation kind.
  */
 export function pythonImportMalformations(pythonText) {
+  // used by its own test
   /** @type {string[]} */
   const reasons = [];
   // A bare `import` or `from` at the end of the file, or on a line with

package/src/analysis/rust.mjs

@@ -238,6 +238,7 @@ export function resolveRustDependencies(projects, filesOf, readFile) {
 
 /** Cargo's identifier spelling of a crate name: `-` and `.` become `_`. */
 export function crateIdentifier(name) {
+  // used by its own test
   return name.replace(/[-.]/g, "_");
 }
 
@@ -250,6 +251,7 @@ export function crateIdentifier(name) {
  * @returns {string|null}
  */
 export function crateImportName(manifest) {
+  // used by its own test
   const declared = manifest?.lib?.name ?? manifest?.package?.name;
   return typeof declared === "string" && declared !== "" ? crateIdentifier(declared) : null;
 }
@@ -471,7 +473,7 @@ function isOwnProjectPath(root, owner, byCrate) {
  * @param {string} path The `use` path, from the first non-space to the `;`.
  * @returns {{text: string, offset: number}[] | null}
  */
-export function braceGroupArms(path) {
+function braceGroupArms(path) {
   const open = path.indexOf("{");
   if (open === -1 || path.slice(0, open).trim() !== "") return null;
   /** @type {{text: string, offset: number}[]} */
@@ -520,6 +522,7 @@ export function braceGroupArms(path) {
  * with a brace group and names none.
  */
 export function useRootSegment(path) {
+  // used by its own test
   const match = /^\s*(?:::\s*)?([A-Za-z_]\w*)/.exec(path);
   return match ? match[1] : null;
 }
@@ -560,6 +563,7 @@ export function useRootSegment(path) {
  *   produces from reading as a clean file.
  */
 export function parseRustUseSites(rustText, knownCrates = new Set(), options = {}) {
+  // used by its own test
   const { returnMetrics = false } = options;
   /** The offset of the first `use` opener no `;` terminates, `null` before one is seen. */
   let unterminatedUseAt = null;

package/src/analysis/source-util.mjs

@@ -153,13 +153,14 @@ function ownershipIndexOf(projects) {
 /**
  * Root comparisons `projectOwning` has performed since the module loaded.
  *
- * Nothing in production reads it. It exists so the complexity test counts
- * deterministic operations instead of milliseconds — the wall-clock this
- * repository does not trust in a test (cf. #359, #369). Every comparison the
- * lookup makes is counted: one per binary-search step, one per equality probe.
+ * A test-support export: nothing in production reads it. It exists so the
+ * complexity test counts deterministic operations instead of milliseconds —
+ * the wall-clock this repository does not trust in a test (cf. #359, #369).
+ * Every comparison the lookup makes is counted: one per binary-search step,
+ * one per equality probe.
  */
 let rootComparisons = 0;
-export const ownershipRootComparisons = () => rootComparisons;
+export const ownershipRootComparisons = () => rootComparisons; // used by its own test
 
 /**
  * The first index in `roots` (sorted ascending) whose value is at or after

package/src/analysis/typescript.mjs

@@ -318,6 +318,7 @@ const SCRIPT_KIND_BY_LANG = Object.freeze({
  * @returns {{ path: boolean, relative: boolean, namesOnly: boolean }}
  */
 export function specifierSpelling(specifier) {
+  // used by its own test
   const relative =
     specifier === "." ||
     specifier === ".." ||
@@ -340,6 +341,7 @@ export function specifierSpelling(specifier) {
  * @returns {string|null}
  */
 export function packageNameOf(specifier) {
+  // used by its own test
   if (specifier === "" || specifier.startsWith(".") || specifier.startsWith("/")) return null;
   const segments = specifier.split("/");
   if (specifier.startsWith("@"))
@@ -1121,3 +1123,149 @@ export function analyzeTypeScript({ sourceFile, text, workspace, lang }) {
   }
   return result;
 }
+
+/**
+ * The names one TypeScript-language file EXPORTS, split by how the export was
+ * written — the two facts `../analysis/markdown.mjs`'s resolution needs when a
+ * document marker names a symbol and the engine must answer "which project
+ * publishes this".
+ *
+ * The split is load-bearing rather than bookkeeping. A name a file DECLARES
+ * here (`export const Button`, `export { Button }` over a local binding,
+ * `export default`) is a symbol whose home this file's project is: a marker
+ * naming it resolves to that project even when five other projects re-export
+ * it, because the re-exporters are downstream of the declaration, not
+ * alternative homes for it. A name a file RE-EXPORTS from another module
+ * (`export { Button } from "@scope/ui-button"`, `export * as ui from …`) is a
+ * name this module passes through, and the project that declares it owns the
+ * resolution. Resolution prefers the declared tier for exactly this reason —
+ * an umbrella barrel that re-exports a whole library must not turn every one
+ * of its symbols into an ambiguous claim.
+ *
+ * Only top-level statements are read, and `export * from "…"` is deliberately
+ * absent from both tiers: a star names no symbol, and enumerating one would
+ * mean resolving the starred module — a module-resolution walk this function's
+ * caller never needs, because a star's targets are themselves scanned as the
+ * files they are. A project whose public surface is star-re-exported from
+ * another project's files resolves those markers through the declaring files'
+ * own projects, which is the honest answer at project grain.
+ *
+ * Never throws: a malformed file yields whatever TypeScript could parse plus a
+ * failure per syntax error, the same posture `analyzeTypeScript` above holds —
+ * one unreadable file must not blank the index every marker resolves against.
+ *
+ * @param {{ sourceFile: string, text: string, workspace: object, lang?: string }} request
+ *   The same request shape `analyzeTypeScript` takes; `lang` is a Vue block's
+ *   `<script lang>` and is omitted for a real file.
+ * @returns {{ declared: string[], reexported: string[], failures: object[] }}
+ */
+export function exportedNamesOf({ sourceFile, text, workspace, lang }) {
+  /** @type {string[]} */
+  const declared = [];
+  /** @type {string[]} */
+  const reexported = [];
+  /** @type {object[]} */
+  const failures = [];
+  try {
+    const parsed = ts.createSourceFile(
+      `${workspace.root}/${sourceFile}`,
+      text,
+      ts.ScriptTarget.Latest,
+      false,
+      scriptKindFor(sourceFile, lang),
+    );
+    failures.push(...parseFailures(parsed, sourceFile));
+
+    const hasModifier = (node, kind) =>
+      (node.modifiers ?? []).some((modifier) => modifier.kind === kind);
+
+    for (const statement of parsed.statements) {
+      // `export { a, b as c }` with no `from` — a local binding list. The
+      // EXPORTED name is the alias side: plain `a` exports `a`, `b as c`
+      // exports `c`. Element name text is read defensively so a
+      // string-literal alias (`export { a as "x y" }`) is carried as written
+      // rather than undefined.
+      if (ts.isExportDeclaration(statement) && statement.exportClause) {
+        const clause = statement.exportClause;
+        if (ts.isNamedExports(clause)) {
+          const target = statement.moduleSpecifier ? reexported : declared;
+          for (const element of clause.elements) {
+            target.push(element.name?.text ?? "");
+          }
+        } else if (clause.name) {
+          // `export * as ns from "…"` — a re-export wearing a new name.
+          reexported.push(clause.name.text);
+        }
+        continue;
+      }
+      if (ts.isExportAssignment(statement)) {
+        // `export default <expression>` and `export = <identifier>` — the
+        // module's own default/exports binding, declared here whatever it
+        // wraps. The `export =` form carries the identifier it aliases; a
+        // default is the name every consumer writes, not the expression's.
+        declared.push(
+          statement.isExportEquals && ts.isIdentifier(statement.expression)
+            ? statement.expression.text
+            : "default",
+        );
+        continue;
+      }
+      const exported = hasModifier(statement, ts.SyntaxKind.ExportKeyword);
+      if (!exported) continue;
+      if (hasModifier(statement, ts.SyntaxKind.DefaultKeyword)) {
+        declared.push("default");
+        continue;
+      }
+      // The one-name statements — function, class, enum, namespace, type,
+      // interface — all carry the exported identifier as `.name`. Enumerated
+      // kind by kind so the type checker's statement union narrows to the
+      // members that actually have one; a future statement kind with a name
+      // is a new arm here, which is the point.
+      const named =
+        ts.isFunctionDeclaration(statement) ||
+        ts.isClassDeclaration(statement) ||
+        ts.isEnumDeclaration(statement) ||
+        ts.isTypeAliasDeclaration(statement) ||
+        ts.isInterfaceDeclaration(statement) ||
+        ts.isModuleDeclaration(statement);
+      if (named) {
+        const name = statement.name?.text ?? "";
+        if (name !== "") {
+          declared.push(name);
+          continue;
+        }
+      }
+      if (ts.isVariableStatement(statement)) {
+        for (const declaration of statement.declarationList.declarations) {
+          bindingNames(declaration.name, declared);
+        }
+      }
+    }
+  } catch (cause) {
+    failures.push(fileFailure(sourceFile, `export scan failed: ${cause?.message ?? cause}`));
+  }
+  return { declared, reexported, failures };
+}
+
+/**
+ * Every identifier a binding pattern introduces, in source order — `a`,
+ * `{ a, b: c }`'s `a` and `c`, `[x, ...rest]`'s `x` and `rest`. Computed
+ * properties (`{ [key]: value }`) introduce nothing nameable and are skipped,
+ * the same call a minifier would make: a name no source text carries is a name
+ * no marker can claim.
+ *
+ * @param {ts.Node} node A binding name or pattern.
+ * @param {string[]} out Accumulator, mutated in place.
+ */
+function bindingNames(node, out) {
+  if (ts.isIdentifier(node) || ts.isStringLiteral(node)) {
+    out.push(node.text);
+    return;
+  }
+  if (ts.isObjectBindingPattern(node) || ts.isArrayBindingPattern(node)) {
+    for (const element of node.elements) {
+      if (ts.isOmittedExpression(element)) continue;
+      bindingNames(element.name ?? element, out);
+    }
+  }
+}

package/src/architecture-intent/model.mjs

@@ -41,6 +41,7 @@ import { readFile as readFileFromDisk } from "node:fs/promises";
 import { resolve } from "node:path";
 
 import { containmentViolation } from "../containment.mjs";
+import { isEnoent } from "../errors.mjs";
 
 import { isValidSelector, splitSelector } from "./selectors.mjs";
 import { describe, isPlainObject } from "../values.mjs";
@@ -50,7 +51,7 @@ import { GOVERNANCE_ROW_KEYS, rowSchemaViolations } from "../governance/row-sche
 export const INTENT_FILE = "architecture-intent.json";
 
 /** The one supported `version`. A different value is a load error. */
-export const INTENT_VERSION = "1";
+export const INTENT_VERSION = "1"; // used by its own test
 
 /**
  * The only keys a valid intent file may carry at the top level.
@@ -65,6 +66,7 @@ export const INTENT_VERSION = "1";
  * engine judges them.
  */
 export const TOP_LEVEL_KEYS = Object.freeze([
+  // used by its own test
   "version",
   "boundaries",
   "allowed",
@@ -75,17 +77,17 @@ export const TOP_LEVEL_KEYS = Object.freeze([
 ]);
 
 /** The sub-keys a `projects` section may carry. */
-export const PROJECT_SECTION_KEYS = Object.freeze(["required", "forbidden"]);
+const PROJECT_SECTION_KEYS = Object.freeze(["required", "forbidden"]);
 /** The sub-keys a `dependencies` section may carry. */
-export const DEPENDENCY_SECTION_KEYS = Object.freeze(["allowed", "forbidden"]);
+const DEPENDENCY_SECTION_KEYS = Object.freeze(["allowed", "forbidden"]);
 /** The keys a `projects.required[]` row may carry. */
-export const REQUIRED_PROJECT_KEYS = Object.freeze(["name", "tags", "decisionRef"]);
+const REQUIRED_PROJECT_KEYS = Object.freeze(["name", "tags", "decisionRef"]);
 /** The keys a `projects.forbidden[]` row may carry. */
-export const FORBIDDEN_PROJECT_KEYS = Object.freeze(["name", "decisionRef"]);
+const FORBIDDEN_PROJECT_KEYS = Object.freeze(["name", "decisionRef"]);
 /** The keys a `dependencies.allowed[]` / `dependencies.forbidden[]` row may carry. */
-export const DEPENDENCY_ROW_KEYS = Object.freeze(["source", "target", "decisionRef"]);
+const DEPENDENCY_ROW_KEYS = Object.freeze(["source", "target", "decisionRef"]);
 /** The keys a `forbiddenTags[]` row may carry. */
-export const TAG_ROW_KEYS = Object.freeze(["from", "to", "decisionRef"]);
+const TAG_ROW_KEYS = Object.freeze(["from", "to", "decisionRef"]);
 
 /**
  * The shared governance-block check for any intent row (Contract 2): when the
@@ -156,6 +158,7 @@ function isSingleProjectSelector(selector) {
  * resolve against.
  */
 export function boundaryNames(intent) {
+  // used by its own test
   return (intent.boundaries ?? []).map((b) => b.name);
 }
 
@@ -167,6 +170,7 @@ export function boundaryNames(intent) {
  * @returns {string[]}
  */
 export function findIntentViolations(raw) {
+  // used by its own test
   const violations = [];
 
   if (!isPlainObject(raw)) {
@@ -602,6 +606,7 @@ export function findIntentViolations(raw) {
  * @returns {object} The normalized model: `{version, boundaries: {name, match, members?}[], allowed, forbidden, projects?, dependencies?, forbiddenTags?}`.
  */
 export function normalizeIntent(intent) {
+  // used by its own test
   return {
     version: intent.version,
     boundaries: intent.boundaries.map((b) => ({ name: b.name, match: [...b.match] })),
@@ -665,7 +670,7 @@ export async function loadIntent(root, { read = readFileFromDisk, tracked } = {}
     // neighbours on the identical tree are both loud: an escaping symlink
     // throws at the containment check above, and EACCES throws below. Only
     // this one was silent (`../../../../AGENTS.md`).
-    if (cause?.code === "ENOENT") {
+    if (isEnoent(cause)) {
       if (tracked === undefined) return undefined;
       throw new Error(
         `${INTENT_FILE}: is tracked but could not be read: ${cause?.message ?? cause} — ` +

package/src/architecture-intent/selectors.mjs

@@ -30,7 +30,7 @@
  */
 
 /** The three selector labels. `unlabeled` is a bare project name (equals `name:`). */
-export const SELECTOR_LABELS = Object.freeze(["name", "tag", "directory"]);
+const SELECTOR_LABELS = Object.freeze(["name", "tag", "directory"]);
 
 /**
  * Split a selector into `{exclude, label, value}` — `!` prefix removed, `*`
@@ -71,6 +71,7 @@ export function isValidSelector(value) {
  * @returns {string[]}
  */
 export function selectProjects(selector, nodes) {
+  // used by its own test
   const { label, value } = splitSelector(selector);
 
   let found;

package/src/commands/change-intent.mjs

@@ -44,10 +44,10 @@ import { readFile as readFileFromDisk } from "node:fs/promises";
 import { describe, isPlainObject } from "../values.mjs";
 
 /** The only `version` this module accepts. A different value is a load error. */
-export const CHANGE_INTENT_VERSION = "1";
+const CHANGE_INTENT_VERSION = "1";
 
 /** The only keys a valid change-intent file may carry at the top level. */
-export const CHANGE_INTENT_TOP_LEVEL_KEYS = Object.freeze([
+const CHANGE_INTENT_TOP_LEVEL_KEYS = Object.freeze([
   "version",
   "base",
   "summary",
@@ -57,16 +57,16 @@ export const CHANGE_INTENT_TOP_LEVEL_KEYS = Object.freeze([
 ]);
 
 /** The keys the `base` section may carry. */
-export const CHANGE_INTENT_BASE_KEYS = Object.freeze(["commit"]);
+const CHANGE_INTENT_BASE_KEYS = Object.freeze(["commit"]);
 
 /** The sub-keys the `projects` section may carry. */
-export const CHANGE_INTENT_PROJECT_SECTION_KEYS = Object.freeze(["add", "remove"]);
+const CHANGE_INTENT_PROJECT_SECTION_KEYS = Object.freeze(["add", "remove"]);
 /** The sub-keys the `edges` section may carry. */
-export const CHANGE_INTENT_EDGE_SECTION_KEYS = Object.freeze(["add", "remove"]);
+const CHANGE_INTENT_EDGE_SECTION_KEYS = Object.freeze(["add", "remove"]);
 /** The keys an edge row may carry. */
-export const CHANGE_INTENT_EDGE_ROW_KEYS = Object.freeze(["from", "to"]);
+const CHANGE_INTENT_EDGE_ROW_KEYS = Object.freeze(["from", "to"]);
 /** The keys the `constraints` section may carry. */
-export const CHANGE_INTENT_CONSTRAINT_KEYS = Object.freeze(["noNewViolations", "noNewCycles"]);
+const CHANGE_INTENT_CONSTRAINT_KEYS = Object.freeze(["noNewViolations", "noNewCycles"]);
 
 /**
  * The constraints the reconciliation judges, in the fixed order their verdict
@@ -204,7 +204,7 @@ function sectionListViolations(section, spec) {
  * @param {unknown} raw The parsed JSON value.
  * @returns {string[]}
  */
-export function findChangeIntentViolations(raw) {
+function findChangeIntentViolations(raw) {
   const violations = [];
   if (!isPlainObject(raw)) {
     return [`top level: must be an object, got ${describe(raw)}`];
@@ -351,7 +351,7 @@ export function findChangeIntentViolations(raw) {
  *   with absent raw sections already normalized to empty arrays.
  * @returns {string[]} Messages; empty when the intent is not a catch-all.
  */
-export function findChangeIntentBreadthViolations(intent) {
+function findChangeIntentBreadthViolations(intent) {
   const declaredRows =
     intent.projects.add.length +
     intent.projects.remove.length +
@@ -389,6 +389,7 @@ export function findChangeIntentBreadthViolations(intent) {
  *   silently would reconcile against an expectation nobody wrote.
  */
 export function parseChangeIntent(text, path) {
+  // used by its own test
   let parsed;
   try {
     parsed = JSON.parse(text);

package/src/commands/change.mjs

@@ -112,6 +112,7 @@ import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { referenceTime } from "../governance/clock.mjs";
 import {
+  assertReproducibleEventIdentity,
   classifyEvolution,
   declarationDigest,
   escapeIdentityField,
@@ -170,6 +171,7 @@ function cmpFacts(a, b) {
  * @returns {string}
  */
 export function violationFindingId(entry) {
+  // used by its own test
   const sourceProject =
     entry.sourceProject == null ? "-" : escapeIdentityField(entry.sourceProject);
   return `${escapeIdentityField(entry.messageId)}:${sourceProject}:${escapeIdentityField(entry.target)}`;
@@ -250,6 +252,7 @@ function observedFrom(structural, meta) {
  * @returns {{matched: object[], unexpected: object[], missingExpected: object[]}}
  */
 export function reconcileMaterialDelta(intent, delta) {
+  // used by its own test
   const addedProjectNames = new Set(intent.projects.add);
   const removedProjectNames = new Set(intent.projects.remove);
   // The declared row's identity is `./change-intent.mjs`'s `edgePairKey` — the
@@ -358,7 +361,7 @@ export function reconcileMaterialDelta(intent, delta) {
  * @param {string[]} unprovenReasons Why the base identity could not be proven.
  * @returns {"matched"|"undeclared"|"unfulfilled"|"unproven"}
  */
-export function reconciliationVerdict(lists, unprovenReasons) {
+function reconciliationVerdict(lists, unprovenReasons) {
   if (unprovenReasons.length > 0) return "unproven";
   if (lists.unexpected.length > 0) return "undeclared";
   if (lists.missingExpected.length > 0) return "unfulfilled";
@@ -389,6 +392,7 @@ export function reconciliationVerdict(lists, unprovenReasons) {
  * @returns {"accepted"|"rejected"|"no-verdict"}
  */
 export function reconcileDisposition(verdict, constraints = []) {
+  // used by its own test
   if (verdict === "unproven") return "no-verdict";
   if (verdict === "undeclared" || verdict === "unfulfilled") return "rejected";
   if (constraints.some((row) => row.verdict === "unknown")) return "no-verdict";
@@ -898,6 +902,18 @@ export async function changeCommand(
   /** @type {{dir: string, id: string, duplicate: boolean}|null} */
   let eventWritten = null;
   if (eventOut !== undefined && eventOut !== null && eventOut !== "") {
+    // F-delta-event-id on the reconcile event: the event's identity names
+    // base and head revisions, so a commitless head or a dirty tree collapses
+    // distinct evidence states onto one event id — a later transition is
+    // silently lost or aliased, the silent direction. `delta` holds the same
+    // gate; the shared law and its frozen wording live in
+    // `../governance/evolution-event.mjs`.
+    assertReproducibleEventIdentity({
+      label: "change",
+      headCommit,
+      baseDirty: baseline.provenance?.dirty === true,
+      headDirty: headProvenance?.dirty === true,
+    });
     // The store's io.root is the workspace root: the write must be provable
     // to stay inside the workspace (the same containment `--output` obeys).
     // A write failure throws — exit 3 upstream, the could-not-look lane —