@forwardimpact/libcoaligned 0.1.10 → 0.1.12

package/LICENSE

@@ -1,201 +1,21 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to the Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright 2026 Dick Olsson
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+MIT License
+
+Copyright (c) 2019 Zachary Rice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -41,19 +41,56 @@ A rule module's default export is:
 ```js
 export default {
   name: "ambient-deps",
-  // Walk the repo and return plain subjects per scope (plus optional
-  // shared ctx the rules read).
-  build: async ({ root, runtime }) => ({
-    subjects: { "src-file": [{ path, smells }] },
-    ctx: { deny },
+  // `build` (and `seed`) receive the injected build kit; the module never
+  // imports the engine (it loads into consuming repos via npx, where the
+  // package is not resolvable from `.coaligned/`). Return plain subjects per
+  // scope, plus optional shared ctx the rules read.
+  build: (kit) => ({
+    subjects: { "src-file": kit.scanAst({ dirs, match, extract }) },
+    ctx: { deny: kit.config("ambient-deps.deny.yml", {}) },
   }),
-  // Declarative rules over those subjects.
-  rules: [{ id, scope, severity, when, check, message, hint }],
+  // Declarative rules over those subjects: either a static array, or a
+  // `(ruleKit) => array` factory that builds them from the rule helpers.
+  rules: ({ parseError, failAll }) => [
+    parseError("src-file"),
+    { id, scope, severity, when, check, message, hint },
+  ],
   // Optional: text for `coaligned invariants --seed <name>` — e.g. a
-  // regenerated grandfather deny-list.
-  seed: async ({ root, runtime }) => "…",
+  // regenerated grandfather deny-list. Also receives the build kit.
+  seed: (kit) => "…",
 };
 ```
 
+### The build kit
+
+The engine binds a kit per run to the repo `root`, the module's own `dir`
+(for co-located config), and the `runtime` bag (fs and ripgrep route through
+it, so the engine carries no ambient dependencies). The module declares only
+policy; the kit owns the mechanism:
+
+- `scan({ dirs, match, skip?, under?, read? })` — collect files as
+  `{ path, rel, text? }`; `under` restricts to the per-package `src`/`test`
+  shape.
+- `scanAst({ dirs, match, extract, locations?, … })` — read + parse each file
+  and merge `extract(ast)`; a parse failure becomes `{ path, rel, parseError }`.
+- `parse(src, path, opts?)`, `walk(ast, visit)` — the lower-level AST seam.
+- `grep({ pattern | patterns, paths?, globs?, caseSensitive?, onlyMatching?,
+  dedupe? })` — ripgrep matches as `{ path, lineNo, text, reason? }`, with
+  per-entry `exclude` and built-in de-duplication.
+- `restatementDrift({ entries, equal })` — the shared "single source restated
+  across consumers" scan + compare (service URLs, scalar values).
+- `readText`, `readJson`, `config(name, fallback?)` (co-located JSON/YAML),
+  `listDir(path, { dirsOnly? })`.
+- `lineAt(text, offset)`, `glob(pattern)`.
+
+### The rule kit
+
+When `rules` is a function it receives the rule helpers:
+
+- `parseError(scope, { id?, hint? })` — fails any subject carrying a
+  `parseError` (paired with `scanAst`).
+- `failAll(scope, { id, message, hint?, when? })` — fails every subject in
+  scope (the build step already decided each is a violation).
+
 Findings render in the same ESLint-style format as the other subcommands
 (`--json` for machine output); any finding fails the run.

package/bin/coaligned.js

@@ -2,12 +2,15 @@
 
 import "@forwardimpact/libpreflight/node22";
 
+import { resolve } from "node:path";
+
 import { createDefaultRuntime } from "@forwardimpact/libutil/runtime";
 import { createCli } from "@forwardimpact/libcli";
 import { emitFindingsJson, emitFindingsText } from "@forwardimpact/libutil";
 import {
   checkInstructions,
   checkJtbd,
+  createBuildKit,
   findInvariantsRoot,
   INVARIANTS_DIR,
   loadRuleModules,
@@ -134,7 +137,10 @@ async function invariantsHandler(ctx) {
       cli.error(`rule module "${mod.name}" has no seed output`);
       return 1;
     }
-    rt.proc.stdout.write(await mod.seed({ root, runtime: rt }));
+    const dir = resolve(root, INVARIANTS_DIR);
+    rt.proc.stdout.write(
+      await mod.seed(createBuildKit({ root, dir, runtime: rt })),
+    );
     return 0;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libcoaligned",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Co-Aligned architecture checks — enforce instruction-layer length caps, JTBD invariants, and the repo's own declarative invariant rule modules.",
   "keywords": [
     "coaligned",
@@ -21,11 +21,11 @@
   "jobs": [
     {
       "user": "Platform Builders",
-      "goal": "Keep Instruction Layers Honest",
-      "trigger": "Editing a CLAUDE.md or skill procedure and realizing the layer has quietly grown past its budget.",
-      "bigHire": "enforce instruction-layer length caps and JTBD invariants without hand-rolling repo checks.",
+      "goal": "Run a Predictable Platform",
+      "trigger": "A service fails on a customer machine and the cause is a missing precondition, an unsupervised process, missing telemetry, or stale instructions.",
+      "bigHire": "check preconditions before anything heavy runs, supervise long-running processes, emit structured telemetry, and keep instruction files honest.",
       "littleHire": "verify a docs change before commit and trust the layered architecture has not drifted.",
-      "competesWith": "ad-hoc shell scripts; eyeballing word counts; tolerating slow drift in the instruction architecture"
+      "competesWith": "failing deep in execution instead of at startup; ad-hoc process management; console.log debugging; instruction files nobody validates"
     }
   ],
   "type": "module",
@@ -49,7 +49,9 @@
     "@forwardimpact/libcli": "^0.1.9",
     "@forwardimpact/libpreflight": "^0.1.0",
     "@forwardimpact/libutil": "*",
-    "prettier": "^3.8.4"
+    "acorn": "^8.17.0",
+    "prettier": "^3.8.4",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@forwardimpact/libmock": "^0.1.0"

package/src/index.js

@@ -1,4 +1,5 @@
 export { checkInstructions } from "./instructions.js";
+export { createBuildKit, RULE_KIT } from "./invariant-kit.js";
 export {
   checkInvariants,
   findInvariantsRoot,

package/src/invariant-kit.js

@@ -0,0 +1,468 @@
+// The invariant authoring kit: the mechanism an invariant rule module needs to
+// turn the repository into subjects and findings, so the module itself carries
+// only policy. The engine injects a *build kit* into every module's `build`
+// (and `seed`), and a *rule kit* into a module's `rules` when it is written as
+// a function. Modules never import this file — the host (invariants.js) binds a
+// kit per run and passes it in, the same way the rest of the monorepo threads
+// the `runtime` bag instead of importing ambient collaborators.
+//
+// Filesystem and subprocess access route through the injected `runtime`
+// (`runtime.fsSync`, `runtime.subprocess`) so this module — which lives under
+// libraries/<pkg>/src — stays clean under the repo's own ambient-deps invariant.
+
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+import { parse as acornParse } from "acorn";
+import { parse as parseYaml } from "yaml";
+
+// -- AST -----------------------------------------------------------------
+
+/**
+ * Parse an ES module, wrapping acorn's error with the offending path.
+ *
+ * @param {string} source - Module source text.
+ * @param {string} filePath - Path used in parse-error messages.
+ * @param {{ locations?: boolean }} [options]
+ * @returns {object} The acorn AST.
+ */
+export function parse(source, filePath, { locations = false } = {}) {
+  try {
+    return acornParse(source, {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      locations,
+      allowAwaitOutsideFunction: true,
+    });
+  } catch (err) {
+    throw new Error(`failed to parse ${filePath}: ${err.message}`);
+  }
+}
+
+/**
+ * Depth-first visit of every typed node in an acorn AST.
+ *
+ * @param {object|object[]} node - AST node (or array of nodes).
+ * @param {(node: object) => void} visit - Called once per typed node.
+ */
+export function walk(node, visit) {
+  if (!node || typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    for (const child of node) walk(child, visit);
+    return;
+  }
+  if (typeof node.type !== "string") return;
+  visit(node);
+  for (const key of Object.keys(node)) {
+    if (key === "loc" || key === "start" || key === "end") continue;
+    walk(node[key], visit);
+  }
+}
+
+// -- Small pure utilities ------------------------------------------------
+
+/**
+ * The 1-based line number a character offset falls on.
+ *
+ * @param {string} text - The source text.
+ * @param {number} offset - A character offset into `text`.
+ * @returns {number} The 1-based line number.
+ */
+export function lineAt(text, offset) {
+  let line = 1;
+  for (let i = 0; i < offset && i < text.length; i++) {
+    if (text.charCodeAt(i) === 10) line++;
+  }
+  return line;
+}
+
+/**
+ * Compile a minimal path glob to a `RegExp`. `**` matches any path segments;
+ * `*` matches a non-slash run.
+ *
+ * @param {string} pattern - The glob.
+ * @returns {RegExp} An anchored regular expression.
+ */
+export function glob(pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(
+    `^${escaped
+      .replace(/\*\*/g, "DOUBLESTAR")
+      .replace(/\*/g, "[^/]*")
+      .replace(/DOUBLESTAR/g, ".*")}$`,
+  );
+}
+
+// -- Filesystem walking (over runtime.fsSync) ----------------------------
+
+function collectFiles(fsSync, dir, skip, match) {
+  const out = [];
+  if (!fsSync.existsSync(dir)) return out;
+  for (const entry of fsSync.readdirSync(dir)) {
+    if (skip.has(entry)) continue;
+    const full = join(dir, entry);
+    if (fsSync.statSync(full).isDirectory()) {
+      out.push(...collectFiles(fsSync, full, skip, match));
+    } else if (match(entry)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function readTextOrNull(fsSync, abs) {
+  try {
+    return fsSync.readFileSync(abs, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+// -- ripgrep (over runtime.subprocess.runSync) ---------------------------
+
+function normalizePatterns(pattern, patterns) {
+  const list = patterns ?? (pattern === undefined ? [] : [pattern]);
+  return list.map((p) => (typeof p === "string" ? { pattern: p } : p));
+}
+
+function parseRgLine(raw) {
+  const i = raw.indexOf(":");
+  const j = raw.indexOf(":", i + 1);
+  return {
+    rel: raw.slice(0, i),
+    lineNo: Number.parseInt(raw.slice(i + 1, j), 10),
+    text: raw.slice(j + 1),
+    raw,
+  };
+}
+
+// Keep the first row per key. `dedupe` is `false`, `true` (key on the raw
+// line), or a key function over the row.
+function dedupeRows(rows, dedupe) {
+  if (!dedupe) return rows;
+  const keyOf = typeof dedupe === "function" ? dedupe : (m) => m.raw;
+  const seen = new Set();
+  return rows.filter((r) => {
+    const k = keyOf(r);
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+}
+
+// A grep row carries `rel`/`raw` for dedupe; the subject keeps only the
+// reportable fields (plus `reason` when the matching entry supplied one).
+function toGrepSubject({ path, lineNo, text, reason }) {
+  const subject = { path, lineNo, text };
+  if (reason !== undefined) subject.reason = reason;
+  return subject;
+}
+
+// -- The build kit -------------------------------------------------------
+
+/**
+ * Build the kit injected into a rule module's `build` and `seed`. Every
+ * collaborator is bound to `root` (the repository root), `dir` (the module's
+ * own directory, for co-located config), and `runtime` (the ambient bag).
+ *
+ * @param {{ root: string, dir: string, runtime: import('@forwardimpact/libutil/runtime').Runtime }} options
+ * @returns {object} The build kit.
+ */
+export function createBuildKit({ root, dir, runtime }) {
+  const { fsSync, subprocess } = runtime;
+  const abs = (p) => (isAbsolute(p) ? p : resolve(root, p));
+
+  /**
+   * Collect files under one or more directories as subjects.
+   *
+   * @param {object} options
+   * @param {string[]} options.dirs - Root directories, relative to the repo.
+   * @param {(name: string) => boolean} options.match - File-name predicate.
+   * @param {Iterable<string>} [options.skip] - Directory names to prune.
+   * @param {string} [options.under] - Restrict to `<dir>/<child>/<under>/**`,
+   *   the per-package `src`/`test` shape.
+   * @param {boolean} [options.read] - Attach file `text` (default true).
+   * @returns {Array<{ path: string, rel: string, text?: string }>}
+   */
+  function scan({ dirs, match, skip = [], under, read = true }) {
+    const skipSet = new Set(skip);
+    const files = [];
+    for (const d of dirs) {
+      const base = resolve(root, d);
+      const roots = under
+        ? (fsSync.existsSync(base) ? fsSync.readdirSync(base) : []).map((n) =>
+            join(base, n, under),
+          )
+        : [base];
+      for (const r of roots)
+        files.push(...collectFiles(fsSync, r, skipSet, match));
+    }
+    return files.map((path) => {
+      const subject = { path, rel: relative(root, path) };
+      if (read) subject.text = readTextOrNull(fsSync, path) ?? "";
+      return subject;
+    });
+  }
+
+  /**
+   * Like `scan`, but parse each file and merge `extract(ast)` into the subject.
+   * A file that fails to parse becomes `{ path, rel, parseError }` instead, so
+   * the module pairs it with the rule kit's `parseError(scope, …)`.
+   *
+   * @param {object} options - `scan` options plus the two below.
+   * @param {(ast: object) => object} options.extract - Subject fields from the AST.
+   * @param {boolean} [options.locations] - Pass `locations` to the parser.
+   * @returns {Array<object>}
+   */
+  function scanAst({ extract, locations = false, ...scanOpts }) {
+    return scan({ ...scanOpts, read: true }).map(({ path, rel, text }) => {
+      try {
+        return { path, rel, ...extract(parse(text, rel, { locations })) };
+      } catch (err) {
+        return { path, rel, parseError: err.message };
+      }
+    });
+  }
+
+  function assertRg() {
+    if (subprocess.runSync("rg", ["--version"]).exitCode !== 0) {
+      throw new Error("ripgrep (rg) is required by the invariant rule modules");
+    }
+  }
+
+  function rgOnce({ pattern, paths, globs, caseSensitive, onlyMatching }) {
+    const args = [
+      "--hidden",
+      "--no-messages",
+      "--line-number",
+      "--color",
+      "never",
+    ];
+    if (!caseSensitive) args.push("-i");
+    if (onlyMatching) args.push("--only-matching");
+    for (const g of globs) args.push("--glob", g);
+    args.push("-e", pattern, ...paths);
+    const { stdout, exitCode } = subprocess.runSync("rg", args, { cwd: root });
+    if (exitCode === 2)
+      throw new Error(`ripgrep failed for pattern: ${pattern}`);
+    return (stdout || "").split("\n").filter(Boolean).map(parseRgLine);
+  }
+
+  /**
+   * Scan the repo with ripgrep and return matches as subjects. Accepts one
+   * `pattern` or a list of `patterns` (strings, or `{ pattern, reason?, globs?,
+   * caseSensitive?, onlyMatching?, exclude? }`); per-entry options override the
+   * call defaults, and a per-entry `exclude` RegExp drops matches whose raw
+   * line it tests true (a false-positive filter). `dedupe` is `false`, `true`
+   * (key on the raw line), or a key function over `{ path, rel, lineNo, text,
+   * raw, reason }`.
+   *
+   * Each subject is `{ path, lineNo, text }`, plus `reason` when the matching
+   * entry carries one. The repo-relative `rel` and full `raw` line are
+   * available to the `dedupe` key function but are not part of the subject.
+   *
+   * @param {object} options
+   * @returns {Array<{ path: string, lineNo: number, text: string, reason?: string }>}
+   */
+  function grep({
+    pattern,
+    patterns,
+    paths = ["."],
+    globs = [],
+    caseSensitive = false,
+    onlyMatching = false,
+    dedupe = false,
+  }) {
+    assertRg();
+    const rows = [];
+    for (const entry of normalizePatterns(pattern, patterns)) {
+      const matches = rgOnce({
+        pattern: entry.pattern,
+        paths,
+        globs: [...globs, ...(entry.globs ?? [])],
+        caseSensitive: entry.caseSensitive ?? caseSensitive,
+        onlyMatching: entry.onlyMatching ?? onlyMatching,
+      });
+      for (const m of matches) {
+        if (entry.exclude && entry.exclude.test(m.raw)) continue;
+        rows.push({ ...m, path: resolve(root, m.rel), reason: entry.reason });
+      }
+    }
+    return dedupeRows(rows, dedupe).map(toGrepSubject);
+  }
+
+  /**
+   * Read a repo file's text (path relative to the repo root, or absolute).
+   *
+   * @param {string} path
+   * @returns {string|null} The text, or `null` when missing.
+   */
+  function readText(path) {
+    return readTextOrNull(fsSync, abs(path));
+  }
+
+  /**
+   * Read and parse a repo JSON file, returning `null` when missing or invalid.
+   *
+   * @param {string} path - Relative to the repo root, or absolute.
+   * @returns {object|null}
+   */
+  function readJson(path) {
+    const text = readTextOrNull(fsSync, abs(path));
+    if (text == null) return null;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Read a config file co-located with the rule module (`<dir>/<name>`),
+   * parsed by extension (`.json` / `.yml` / `.yaml`). Returns `fallback` when
+   * the file is missing, empty, or unparseable.
+   *
+   * @param {string} name - File name beside the module.
+   * @param {*} [fallback] - Value when absent or unreadable (default `null`).
+   * @returns {*}
+   */
+  function config(name, fallback = null) {
+    const text = readTextOrNull(fsSync, join(dir, name));
+    if (text == null || text.trim() === "") return fallback;
+    try {
+      const parsed = name.endsWith(".json")
+        ? JSON.parse(text)
+        : parseYaml(text);
+      return parsed ?? fallback;
+    } catch {
+      return fallback;
+    }
+  }
+
+  /**
+   * The shared "single source restated across consumers" check. For every
+   * registry `entry` (`{ key, expected, consumers: [{ path, pattern }] }`),
+   * scan each consumer file line by line for `pattern` and emit one subject
+   * per match: the restated value (capture group 1, else the whole match,
+   * trimmed) paired with the entry's `expected` value and an `ok` verdict from
+   * `equal(restated, expected, key)`. The module supplies the domain pieces
+   * (how `expected` is computed, what `equal` means); the kit owns the scan.
+   *
+   * Native line-by-line matching, not ripgrep: the surfaces carry URLs and
+   * other colon-bearing values that ripgrep's single-file output corrupts, and
+   * look-around is sometimes needed.
+   *
+   * @param {object} options
+   * @param {Array<{ key: string, expected: *, consumers: Array<{ path: string, pattern: RegExp|string }> }>} options.entries
+   * @param {(restated: string, expected: *, key: string) => boolean} options.equal
+   * @returns {Array<{ key: string, path: string, lineNo: number, restated: string, expected: *, ok: boolean }>}
+   */
+  function restatementDrift({ entries, equal }) {
+    const subjects = [];
+    for (const { key, expected, consumers } of entries) {
+      for (const consumer of consumers) {
+        const text = readTextOrNull(fsSync, abs(consumer.path));
+        if (text == null) continue;
+        const re =
+          typeof consumer.pattern === "string"
+            ? new RegExp(consumer.pattern)
+            : consumer.pattern;
+        text.split("\n").forEach((line, i) => {
+          const m = line.match(re);
+          if (!m) return;
+          const restated = (m[1] ?? m[0]).trim();
+          subjects.push({
+            key,
+            path: consumer.path,
+            lineNo: i + 1,
+            restated,
+            expected,
+            ok: equal(restated, expected, key),
+          });
+        });
+      }
+    }
+    return subjects;
+  }
+
+  /**
+   * List the entries of a repo directory by name, returning `[]` when missing.
+   *
+   * @param {string} path - Relative to the repo root, or absolute.
+   * @param {{ dirsOnly?: boolean, filesOnly?: boolean }} [options]
+   * @returns {string[]}
+   */
+  function listDir(path, { dirsOnly = false, filesOnly = false } = {}) {
+    let entries;
+    try {
+      entries = fsSync.readdirSync(abs(path), { withFileTypes: true });
+    } catch {
+      return [];
+    }
+    return entries
+      .filter((e) =>
+        dirsOnly ? e.isDirectory() : filesOnly ? e.isFile() : true,
+      )
+      .map((e) => e.name);
+  }
+
+  return {
+    root,
+    dir,
+    runtime,
+    scan,
+    scanAst,
+    parse,
+    walk,
+    grep,
+    restatementDrift,
+    readText,
+    readJson,
+    config,
+    listDir,
+    lineAt,
+    glob,
+  };
+}
+
+// -- The rule kit --------------------------------------------------------
+
+/**
+ * Helpers a rule module receives when it exports `rules` as a function. They
+ * build the two recurring rule shapes so the module declares only policy.
+ */
+export const RULE_KIT = {
+  /**
+   * The standard parse-error rule: fails any subject carrying a `parseError`
+   * string (as produced by the build kit's `scanAst`).
+   *
+   * @param {string} scope - The subject scope to guard.
+   * @param {{ id?: string, hint?: string }} [options]
+   * @returns {object} A rule for the rules engine.
+   */
+  parseError(scope, { id = `${scope}.parse-error`, hint } = {}) {
+    return {
+      id,
+      scope,
+      severity: "fail",
+      check: (s) => (s.parseError ? { msg: s.parseError } : null),
+      message: (_s, r) => r.msg,
+      hint: hint ?? "fix the syntax error so the file can be parsed",
+    };
+  },
+
+  /**
+   * A rule that fails every subject in `scope` (optionally gated by `when`).
+   * The build step has already decided each subject is a violation; the rule
+   * only renders it.
+   *
+   * @param {string} scope
+   * @param {{ id: string, message: (s: object, r: object, c: object) => string, hint?: string, when?: (s: object, c: object) => boolean }} options
+   * @returns {object} A rule for the rules engine.
+   */
+  failAll(scope, { id, message, hint, when }) {
+    const rule = { id, scope, severity: "fail", check: () => ({}), message };
+    if (hint !== undefined) rule.hint = hint;
+    if (when !== undefined) rule.when = when;
+    return rule;
+  },
+};

package/src/invariants.js

@@ -1,6 +1,7 @@
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { runRules } from "@forwardimpact/libutil";
+import { createBuildKit, RULE_KIT } from "./invariant-kit.js";
 
 // The conventional rules location, relative to the project root.
 export const INVARIANTS_DIR = ".coaligned/invariants";
@@ -45,14 +46,20 @@ function assertModuleShape(mod, fileName) {
     mod &&
     typeof mod.name === "string" &&
     typeof mod.build === "function" &&
-    Array.isArray(mod.rules);
+    (Array.isArray(mod.rules) || typeof mod.rules === "function");
   if (!ok) {
     throw new Error(
-      `${fileName}: default export must be { name, build, rules }`,
+      `${fileName}: default export must be { name, build, rules } (rules is an array or a (ruleKit) => array)`,
     );
   }
 }
 
+// A module's rules are either a static array or a `(ruleKit) => array` factory
+// that builds them from the shared rule helpers.
+function resolveRules(mod) {
+  return typeof mod.rules === "function" ? mod.rules(RULE_KIT) : mod.rules;
+}
+
 /**
  * Discover and import every rule module under `rulesDir` (sorted by file
  * name for a stable run order).
@@ -89,20 +96,26 @@ export async function loadRuleModules({
 }
 
 /**
- * Run already-loaded rule modules: build each module's subjects, then apply
- * its rule catalogue through the shared rules engine.
+ * Run already-loaded rule modules: inject the build kit, build each module's
+ * subjects, then apply its rule catalogue through the shared rules engine.
  *
  * @param {object[]} modules - Rule-module default exports.
- * @param {{ root: string, runtime: import('@forwardimpact/libutil/runtime').Runtime }} options
+ * @param {{ root: string, runtime: import('@forwardimpact/libutil/runtime').Runtime, dir?: string }} options
+ *   `dir` is the modules' directory (for co-located config); defaults to
+ *   `<root>/.coaligned/invariants`.
  * @returns {Promise<object[]>} Structured findings; empty when conformant.
  */
-export async function runRuleModules(modules, { root, runtime }) {
+export async function runRuleModules(
+  modules,
+  { root, runtime, dir = resolve(root, INVARIANTS_DIR) },
+) {
   const findings = [];
   for (const mod of modules) {
-    const { subjects, ctx = {} } = await mod.build({ root, runtime });
+    const kit = createBuildKit({ root, dir, runtime });
+    const { subjects, ctx = {} } = await mod.build(kit);
     findings.push(
       ...runRules(
-        mod.rules,
+        resolveRules(mod),
         { ...ctx, subjects },
         { resolveScope: (key, c) => c.subjects[key] ?? [] },
       ),
@@ -125,6 +138,7 @@ export async function checkInvariants({
   runtime,
 }) {
   if (!runtime) throw new Error("runtime is required");
+  const dir = resolve(root, rulesDir);
   const modules = await loadRuleModules({ root, rulesDir, runtime });
-  return runRuleModules(modules, { root, runtime });
+  return runRuleModules(modules, { root, runtime, dir });
 }