arkgate 4.8.23 → 4.8.25

package/bin/lib/arkgate-pins.mjs

@@ -0,0 +1,91 @@
+/**
+ * Tooling I/O for the config version floor (#338): read the files that can pin
+ * an arkgate version and hand their text to the pure Domain parser.
+ *
+ * Bounded and non-recursive. Missing or oversized files are skipped. Every
+ * probed path is reported to `observeInput` so a resident snapshot notices a
+ * later edit of package.json or a workflow.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArkgatePins } from './analysis-engine.mjs';
+import { __packageRoot } from './gate-files.mjs';
+
+const MAX_PIN_FILE_BYTES = 256 * 1024;
+
+const FIXED_CANDIDATES = [
+  ['package.json', 'package-json'],
+  ['package-lock.json', 'package-lock'],
+  ['node_modules/arkgate/package.json', 'installed'],
+  ['.claude/settings.json', 'hook'],
+  ['.cursor/hooks.json', 'hook'],
+  ['.codex/hooks.json', 'hook'],
+  ['.codex/config.toml', 'hook'],
+  ['.grok/settings.json', 'hook'],
+];
+
+/** Directories whose direct children may pin arkgate, with a basename filter. */
+const DIRECTORY_CANDIDATES = [
+  ['scripts', 'hook', (name) => /hook/i.test(name)],
+  ['.husky', 'hook', () => true],
+  ['.githooks', 'hook', () => true],
+  ['.github/workflows', 'ci', (name) => /\.ya?ml$/i.test(name)],
+];
+
+function readSmall(absolute) {
+  try {
+    const stat = fs.statSync(absolute);
+    if (!stat.isFile() || stat.size > MAX_PIN_FILE_BYTES) return null;
+    return fs.readFileSync(absolute, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function listDirectory(absolute) {
+  try {
+    return fs
+      .readdirSync(absolute, { withFileTypes: true })
+      .filter((entry) => entry.isFile())
+      .map((entry) => entry.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Every arkgate pin under `root` (repo-relative files, 1-based lines).
+ * @param {string} root
+ * @param {{ observeInput?: (absolutePath: string, kind: string) => void }} [options]
+ */
+export function collectArkgatePins(root, { observeInput } = {}) {
+  const pins = [];
+  const probe = (rel, source) => {
+    const absolute = path.join(root, rel);
+    observeInput?.(absolute, 'arkgate-pin');
+    const text = readSmall(absolute);
+    if (text) pins.push(...parseArkgatePins(rel, text, source));
+  };
+  for (const [rel, source] of FIXED_CANDIDATES) probe(rel, source);
+  for (const [dir, source, accept] of DIRECTORY_CANDIDATES) {
+    const absoluteDir = path.join(root, dir);
+    observeInput?.(absoluteDir, 'arkgate-pin');
+    for (const name of listDirectory(absoluteDir)) {
+      if (accept(name)) probe(`${dir}/${name}`, source);
+    }
+  }
+  return pins;
+}
+
+/** The arkgate version running this check. */
+export function runningArkgateVersion() {
+  const text = readSmall(path.join(__packageRoot, 'package.json'));
+  if (!text) return undefined;
+  try {
+    const pkg = JSON.parse(text);
+    return typeof pkg.version === 'string' ? pkg.version : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/bin/lib/arkrule-file-hints.mjs

@@ -11,11 +11,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { buildArkRuleFileHints } from './arkrules-sensors.mjs';
+import { matchSimpleGlob } from './invariant-coverage-io.mjs';
 
 /** Default hint-file budget. Same lever as `coverage.maxFiles`. */
 export const DEFAULT_MAX_HINT_FILES = 400;
 /** Hard ceiling — same clamp as coverage.maxFiles. */
-export const MAX_HINT_FILES_CAP = 20_000;
+const MAX_HINT_FILES_CAP = 20_000;
 const MAX_FILE_BYTES = 256 * 1024;
 
 const HINT_SENSORS = new Set([
@@ -37,17 +38,6 @@ export function needsArkRuleFileHints(arkRules) {
   return (arkRules?.structure ?? []).some((rule) => HINT_SENSORS.has(rule?.sensor));
 }
 
-/**
- * @param {unknown} maxFiles
- * @returns {number}
- */
-export function resolveHintBudget(maxFiles) {
-  if (Number.isInteger(maxFiles) && maxFiles > 0) {
-    return Math.min(maxFiles, MAX_HINT_FILES_CAP);
-  }
-  return DEFAULT_MAX_HINT_FILES;
-}
-
 /**
  * @param {unknown} hints
  * @returns {null | {
@@ -74,41 +64,6 @@ export function formatHintBudgetDoctorLine(budget) {
   return `${HINT_BUDGET_DOCTOR_LINE} Hinted ${budget.hinted} of ${budget.governed} eligible governed files (budget ${budget.budget}).`;
 }
 
-/**
- * Minimal glob match (double-star slash = zero path segments).
- * @param {string} glob
- * @param {string} file
- */
-function matchSimpleGlob(glob, file) {
-  const pattern = String(glob || '').replace(/\\/g, '/');
-  const target = String(file || '').replace(/\\/g, '/');
-  if (!pattern) return false;
-  let out = '';
-  for (let i = 0; i < pattern.length; i += 1) {
-    const c = pattern[i];
-    if (c === '*') {
-      if (pattern[i + 1] === '*') {
-        if (pattern[i + 2] === '/') {
-          out += '(?:.*/)?';
-          i += 2;
-        } else {
-          out += '.*';
-          i += 1;
-        }
-      } else {
-        out += '[^/]*';
-      }
-    } else if (c === '?') {
-      out += '[^/]';
-    } else if (/[.+^${}()|[\]\\]/.test(c)) {
-      out += `\\${c}`;
-    } else {
-      out += c;
-    }
-  }
-  return new RegExp(`^${out}$`).test(target);
-}
-
 /**
  * @param {string} file
  * @param {unknown} appliesTo

package/bin/lib/arkrules-contract.mjs

@@ -8,8 +8,9 @@
  * Pure CLI helper (bin/lib/arkrules-contract.mjs). Zero Node I/O.
  */
 
+import { isObject, validateSchemaNode, valueType } from './schema-validation.mjs';
 export const ARK_RULES_SCHEMA_VERSION = '1.0';
-export const ARK_RULES_SCHEMA_URL = 'https://unpkg.com/arkgate/schemas/ark.arkrules.schema.json';
+const ARK_RULES_SCHEMA_URL = 'https://unpkg.com/arkgate/schemas/ark.arkrules.schema.json';
 /** Closed sensor vocabulary — keep in lockstep with arkRulesTypes.ARK_RULE_SENSOR_IDS. */
 export const ARK_RULE_SENSORS = [
     'aggregate-private-state',
@@ -105,113 +106,6 @@ export class ArkRulesValidationError extends Error {
         this.issues = issues;
     }
 }
-function isObject(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-function propertyPath(parent, key) {
-    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
-        ? `${parent}.${key}`
-        : `${parent}[${JSON.stringify(key)}]`;
-}
-function valueType(value) {
-    if (value === null)
-        return 'null';
-    if (Array.isArray(value))
-        return 'array';
-    return typeof value;
-}
-function resolveSchemaRef(ref, root) {
-    const prefix = '#/$defs/';
-    if (!ref.startsWith(prefix))
-        return undefined;
-    return root.$defs[ref.slice(prefix.length)];
-}
-function validateNode(value, schema, path, root, issues) {
-    if (schema.$ref) {
-        const referenced = resolveSchemaRef(schema.$ref, root);
-        if (!referenced) {
-            issues.push({ path, message: `schema reference ${schema.$ref} cannot be resolved` });
-            return;
-        }
-        validateNode(value, referenced, path, root, issues);
-        return;
-    }
-    if (schema.const !== undefined && !Object.is(value, schema.const)) {
-        issues.push({ path, message: `must equal ${JSON.stringify(schema.const)}` });
-        return;
-    }
-    if (schema.enum && !schema.enum.some((candidate) => Object.is(candidate, value))) {
-        issues.push({ path, message: `must be one of ${schema.enum.map(String).join(', ')}` });
-        return;
-    }
-    if (schema.type === 'object') {
-        if (!isObject(value)) {
-            issues.push({ path, message: `must be an object; received ${valueType(value)}` });
-            return;
-        }
-        const properties = schema.properties ?? {};
-        for (const key of schema.required ?? []) {
-            if (value[key] === undefined) {
-                issues.push({ path: propertyPath(path, key), message: 'is required' });
-            }
-        }
-        if (schema.additionalProperties === false) {
-            for (const key of Object.keys(value)) {
-                if (!(key in properties)) {
-                    issues.push({ path: propertyPath(path, key), message: 'unknown field' });
-                }
-            }
-        }
-        else if (isObject(schema.additionalProperties)) {
-            const additional = schema.additionalProperties;
-            for (const key of Object.keys(value)) {
-                if (!(key in properties)) {
-                    validateNode(value[key], additional, propertyPath(path, key), root, issues);
-                }
-            }
-        }
-        for (const [key, childSchema] of Object.entries(properties)) {
-            if (value[key] !== undefined) {
-                validateNode(value[key], childSchema, propertyPath(path, key), root, issues);
-            }
-        }
-        return;
-    }
-    if (schema.type === 'array') {
-        if (!Array.isArray(value)) {
-            issues.push({ path, message: `must be an array; received ${valueType(value)}` });
-            return;
-        }
-        if (schema.minItems !== undefined && value.length < schema.minItems) {
-            issues.push({ path, message: `must contain at least ${schema.minItems} item(s)` });
-        }
-        if (schema.uniqueItems) {
-            const serialized = value.map((entry) => JSON.stringify(entry));
-            if (new Set(serialized).size !== serialized.length) {
-                issues.push({ path, message: 'must not contain duplicate items' });
-            }
-        }
-        if (schema.items) {
-            value.forEach((entry, index) => validateNode(entry, schema.items, `${path}[${index}]`, root, issues));
-        }
-        return;
-    }
-    if (schema.type === 'string') {
-        if (typeof value !== 'string') {
-            issues.push({ path, message: `must be a string; received ${valueType(value)}` });
-            return;
-        }
-        if (schema.minLength !== undefined && value.length < schema.minLength) {
-            issues.push({ path, message: `must contain at least ${schema.minLength} character(s)` });
-        }
-        return;
-    }
-    if (schema.type === 'boolean') {
-        if (typeof value !== 'boolean') {
-            issues.push({ path, message: `must be a boolean; received ${valueType(value)}` });
-        }
-    }
-}
 function defaultedArkRules(input) {
     return {
         ...input,
@@ -299,7 +193,7 @@ export function loadArkRulesContract(input, source = 'arkrules.json', expectedLa
     }
     const candidate = defaultedArkRules(input);
     const issues = [];
-    validateNode(candidate, ARK_RULES_SCHEMA, '$', ARK_RULES_SCHEMA, issues);
+    validateSchemaNode(candidate, ARK_RULES_SCHEMA, '$', ARK_RULES_SCHEMA, issues);
     validateSemantics(candidate, issues);
     if (expectedLayer !== undefined &&
         typeof candidate.layer === 'string' &&
@@ -328,39 +222,136 @@ export function parseArkRulesJson(json, source = 'arkrules.json', expectedLayer)
     }
     return loadArkRulesContract(input, source, expectedLayer);
 }
+function effectiveRuleId(part, localId) {
+    return part.childId ? `${part.childId}#${localId}` : localId;
+}
+function effectiveAppliesTo(part, appliesTo) {
+    if (appliesTo && appliesTo.length > 0)
+        return [...appliesTo];
+    if (part.childId && part.defaultAppliesTo && part.defaultAppliesTo.length > 0) {
+        return [...part.defaultAppliesTo];
+    }
+    return undefined;
+}
+function provenanceFor(part, localId) {
+    return {
+        sourceFile: part.sourceFile,
+        ruleId: effectiveRuleId(part, localId),
+        layer: part.layer,
+        ...(part.childId ? { childId: part.childId } : {}),
+    };
+}
+/**
+ * True when every path the glob can match stays under the slice root.
+ * A wider prefix, a `**` that is not the last segment, or `..` escapes.
+ */
+function appliesToPatternInsideSlice(pattern, sliceRoot) {
+    const root = sliceRoot.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+    const value = pattern.trim().replace(/\\/g, '/').replace(/^\.\//, '').toLowerCase();
+    if (!value || !root || value.includes('..'))
+        return false;
+    if (value === root || value === `${root}/**` || value === `${root}/*`)
+        return true;
+    if (value.startsWith(`${root}/`)) {
+        const parts = value.slice(root.length + 1).split('/');
+        const globStar = parts.indexOf('**');
+        if (globStar !== -1 && globStar !== parts.length - 1)
+            return false;
+        return parts.every((part) => part.length > 0);
+    }
+    const bareRoot = root.replace(/^(?:src|app)\//, '');
+    const bareValue = value.replace(/^(?:src|app)\//, '');
+    if (bareRoot !== root || bareValue !== value)
+        return appliesToPatternInsideSlice(bareValue, bareRoot);
+    return false;
+}
+/** Explicit appliesTo on a discovered file that can match outside its slice. */
+export function sliceScopeEscapes(part) {
+    if (!part.childId || !part.defaultAppliesTo?.length)
+        return [];
+    const sliceRoot = String(part.defaultAppliesTo[0]).replace(/\/\*\*$/, '');
+    const escapes = [];
+    const entries = [...(part.file.structure ?? []), ...(part.file.invariants ?? [])];
+    for (const entry of entries) {
+        for (const pattern of entry.appliesTo ?? []) {
+            if (!appliesToPatternInsideSlice(pattern, sliceRoot))
+                escapes.push({ id: entry.id, pattern });
+        }
+    }
+    return escapes;
+}
+/** Effective ids declared by more than one part. Central ids stay bare; slice ids are namespaced. */
+export function duplicateArkRuleIds(parts) {
+    const seen = new Map();
+    const dupes = new Map();
+    for (const part of parts) {
+        const localIds = [
+            ...(part.file.structure ?? []).map((entry) => entry.id),
+            ...(part.file.invariants ?? []).map((entry) => entry.id),
+        ];
+        for (const localId of localIds) {
+            const id = effectiveRuleId(part, localId);
+            const key = `${part.layer}\0${id}`;
+            const existing = seen.get(key);
+            if (!existing) {
+                seen.set(key, { id, layer: part.layer, sourceFiles: [part.sourceFile] });
+                continue;
+            }
+            const row = dupes.get(key) ?? { id, layer: part.layer, sourceFiles: [...existing.sourceFiles] };
+            if (!row.sourceFiles.includes(part.sourceFile))
+                row.sourceFiles.push(part.sourceFile);
+            dupes.set(key, row);
+        }
+    }
+    return [...dupes.values()];
+}
 /**
  * Build the Effective Contract from already-validated ArkRules files.
- * Callers supply `{ layer → { sourceFile, file } }` after resolving references.
+ * Same-layer parts merge. A child id namespaces the effective id and does not rewrite the file.
  */
 export function buildEffectiveArkRules(parts) {
     const byLayer = {};
     const structure = [];
     const invariants = [];
-    const ordered = [...parts].sort((a, b) => a.layer.localeCompare(b.layer));
+    const ordered = [...parts].sort((a, b) => a.layer.localeCompare(b.layer) || a.sourceFile.localeCompare(b.sourceFile));
     for (const part of ordered) {
-        const structureRules = (part.file.structure ?? []).map((entry) => ({
-            ...entry,
-            mode: normalizeMode(entry.mode),
-            provenance: {
-                sourceFile: part.sourceFile,
-                ruleId: entry.id,
-                layer: part.layer,
-            },
-        }));
-        const invariantRules = (part.file.invariants ?? []).map((entry) => ({
-            ...entry,
-            mode: normalizeMode(entry.mode),
-            provenance: {
+        const structureRules = (part.file.structure ?? []).map((entry) => {
+            const appliesTo = effectiveAppliesTo(part, entry.appliesTo);
+            return {
+                ...entry,
+                id: effectiveRuleId(part, entry.id),
+                ...(appliesTo ? { appliesTo } : { appliesTo: undefined }),
+                mode: normalizeMode(entry.mode),
+                provenance: provenanceFor(part, entry.id),
+            };
+        });
+        const invariantRules = (part.file.invariants ?? []).map((entry) => {
+            const appliesTo = effectiveAppliesTo(part, entry.appliesTo);
+            return {
+                ...entry,
+                id: effectiveRuleId(part, entry.id),
+                ...(appliesTo ? { appliesTo } : { appliesTo: undefined }),
+                mode: normalizeMode(entry.mode),
+                provenance: provenanceFor(part, entry.id),
+            };
+        });
+        const bucket = byLayer[part.layer];
+        if (!bucket) {
+            byLayer[part.layer] = {
                 sourceFile: part.sourceFile,
-                ruleId: entry.id,
-                layer: part.layer,
-            },
-        }));
-        byLayer[part.layer] = {
-            sourceFile: part.sourceFile,
-            structure: structureRules,
-            invariants: invariantRules,
-        };
+                sourceFiles: [part.sourceFile],
+                structure: structureRules,
+                invariants: invariantRules,
+            };
+        }
+        else {
+            if (!bucket.sourceFiles)
+                bucket.sourceFiles = [bucket.sourceFile];
+            if (!bucket.sourceFiles.includes(part.sourceFile))
+                bucket.sourceFiles.push(part.sourceFile);
+            bucket.structure.push(...structureRules);
+            bucket.invariants.push(...invariantRules);
+        }
         structure.push(...structureRules);
         invariants.push(...invariantRules);
     }