@forwardimpact/libcoaligned 0.1.8 → 0.1.10

package/README.md

@@ -2,8 +2,8 @@
 
 <!-- BEGIN:description — Do not edit. Generated from package.json. -->
 
-Co-Aligned architecture checks — enforce instruction-layer length caps and JTBD
-invariants across the repo.
+Co-Aligned architecture checks — enforce instruction-layer length caps, JTBD
+invariants, and the repo's own declarative invariant rule modules.
 
 <!-- END:description -->
 
@@ -14,9 +14,10 @@ npx coaligned                   # run every check (instructions + jtbd)
 npx coaligned instructions      # enforce L1–L7 length and checklist caps
 npx coaligned jtbd              # validate JTBD entries against package.json
 npx coaligned jtbd --fix        # regenerate catalog and job blocks in place
+npx coaligned invariants        # run the repo's own rule modules
 ```
 
-The two subcommands implement the contract described in
+The `instructions` and `jtbd` subcommands implement the contract described in
 [COALIGNED.md](https://github.com/forwardimpact/monorepo/blob/main/COALIGNED.md):
 
 - `instructions` — every layer (L1 CLAUDE.md, L2 CONTRIBUTING.md / JTBD.md,
@@ -26,3 +27,33 @@ The two subcommands implement the contract described in
 - `jtbd` — each `package.json .jobs` entry is validated against the JTBD
   schema; with `--fix`, marker-delimited blocks in `<dir>/README.md`,
   `<dir>/<pkg>/README.md`, and root `JTBD.md` are regenerated.
+
+## Invariants
+
+`coaligned invariants` is a generic host for a repository's own invariant
+checks. It resolves the project root (from any subdirectory), loads every
+`*.rules.mjs` module under `.coaligned/invariants/`, and runs each module's
+declarative rule catalogue through the shared rules engine. The policies stay
+in the repository; the CLI ships only the engine.
+
+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 },
+  }),
+  // Declarative rules over those subjects.
+  rules: [{ 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 }) => "…",
+};
+```
+
+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

@@ -5,7 +5,14 @@ import "@forwardimpact/libpreflight/node22";
 import { createDefaultRuntime } from "@forwardimpact/libutil/runtime";
 import { createCli } from "@forwardimpact/libcli";
 import { emitFindingsJson, emitFindingsText } from "@forwardimpact/libutil";
-import { checkInstructions, checkJtbd } from "../src/index.js";
+import {
+  checkInstructions,
+  checkJtbd,
+  findInvariantsRoot,
+  INVARIANTS_DIR,
+  loadRuleModules,
+  runRuleModules,
+} from "../src/index.js";
 
 const runtime = createDefaultRuntime();
 
@@ -21,6 +28,23 @@ const definition = {
       handler: instructionsHandler,
       examples: ["coaligned instructions"],
     },
+    {
+      name: "invariants",
+      args: [],
+      description: `Run the repository's invariant rule modules from ${INVARIANTS_DIR}/`,
+      options: {
+        seed: {
+          type: "string",
+          description:
+            "Print the named module's seed output (e.g. a refreshed deny-list) instead of checking",
+        },
+      },
+      handler: invariantsHandler,
+      examples: [
+        "coaligned invariants",
+        "coaligned invariants --seed ambient-deps",
+      ],
+    },
     {
       name: "jtbd",
       args: [],
@@ -92,6 +116,39 @@ async function instructionsHandler(ctx) {
   return runInstructions(ctx.data.root, !!ctx.options.json, rt);
 }
 
+// Unlike instructions/jtbd, invariants resolves the project root through the
+// finder so the rule modules are picked up from `<root>/.coaligned/invariants`
+// no matter which subdirectory the command runs from.
+async function invariantsHandler(ctx) {
+  const rt = ctx.deps.runtime;
+  const root = findInvariantsRoot(rt);
+  const modules = await loadRuleModules({ root, runtime: rt });
+
+  if (ctx.options.seed) {
+    const mod = modules.find((m) => m.name === ctx.options.seed);
+    if (!mod) {
+      cli.error(`no rule module named "${ctx.options.seed}"`);
+      return 1;
+    }
+    if (typeof mod.seed !== "function") {
+      cli.error(`rule module "${mod.name}" has no seed output`);
+      return 1;
+    }
+    rt.proc.stdout.write(await mod.seed({ root, runtime: rt }));
+    return 0;
+  }
+
+  const findings = await runRuleModules(modules, { root, runtime: rt });
+  writeFindings(
+    findings,
+    "coaligned invariants passed",
+    !!ctx.options.json,
+    root,
+    rt,
+  );
+  return findings.length > 0 ? 1 : 0;
+}
+
 async function jtbdHandler(ctx) {
   const rt = ctx.deps.runtime;
   return runJtbd(ctx.data.root, !!ctx.options.fix, !!ctx.options.json, rt);

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@forwardimpact/libcoaligned",
-  "version": "0.1.8",
-  "description": "Co-Aligned architecture checks — enforce instruction-layer length caps and JTBD invariants across the repo.",
+  "version": "0.1.10",
+  "description": "Co-Aligned architecture checks — enforce instruction-layer length caps, JTBD invariants, and the repo's own declarative invariant rule modules.",
   "keywords": [
     "coaligned",
     "instructions",
     "jtbd",
+    "invariants",
     "checklist",
     "agent"
   ],
@@ -48,7 +49,7 @@
     "@forwardimpact/libcli": "^0.1.9",
     "@forwardimpact/libpreflight": "^0.1.0",
     "@forwardimpact/libutil": "*",
-    "prettier": "^3.0.0"
+    "prettier": "^3.8.4"
   },
   "devDependencies": {
     "@forwardimpact/libmock": "^0.1.0"

package/src/index.js

@@ -1,2 +1,9 @@
 export { checkInstructions } from "./instructions.js";
+export {
+  checkInvariants,
+  findInvariantsRoot,
+  INVARIANTS_DIR,
+  loadRuleModules,
+  runRuleModules,
+} from "./invariants.js";
 export { checkJtbd } from "./jtbd.js";

package/src/invariants.js

@@ -0,0 +1,130 @@
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { runRules } from "@forwardimpact/libutil";
+
+// The conventional rules location, relative to the project root.
+export const INVARIANTS_DIR = ".coaligned/invariants";
+
+/**
+ * Resolve the root whose `.coaligned/invariants/` applies to the working
+ * directory. The nearest `package.json` is not enough — inside a monorepo
+ * every workspace package has one — so search upward for the rules directory
+ * itself, falling back to the nearest project root so the loader's error
+ * names the expected location.
+ *
+ * @param {import('@forwardimpact/libutil/runtime').Runtime} runtime
+ * @returns {string} Project root directory path.
+ */
+export function findInvariantsRoot(runtime) {
+  const found = runtime.finder.findUpward(
+    runtime.proc.cwd(),
+    INVARIANTS_DIR,
+    8,
+  );
+  return found ? resolve(found, "../..") : runtime.finder.findProjectRoot();
+}
+
+// Generic host for repo-local invariant rule modules. A rule module is a
+// `*.rules.mjs` (or `*.rules.js`) file whose default export is:
+//
+//   {
+//     name:  "ambient-deps",
+//     build: async ({ root, runtime }) =>
+//              ({ subjects: { "<scope>": [subject, …] }, ctx? }),
+//     rules: [{ id, scope, severity, when?, check, message, hint? }, …],
+//     seed?: async ({ root, runtime }) => "text",   // e.g. a refreshed deny-list
+//   }
+//
+// `build` walks the repo and returns plain subjects per scope; `rules` are the
+// declarative checks `runRules` applies over them. The repository owns its
+// rule modules — this host only discovers, loads, and runs them, so the
+// policies themselves never ship with the CLI.
+
+function assertModuleShape(mod, fileName) {
+  const ok =
+    mod &&
+    typeof mod.name === "string" &&
+    typeof mod.build === "function" &&
+    Array.isArray(mod.rules);
+  if (!ok) {
+    throw new Error(
+      `${fileName}: default export must be { name, build, rules }`,
+    );
+  }
+}
+
+/**
+ * Discover and import every rule module under `rulesDir` (sorted by file
+ * name for a stable run order).
+ *
+ * @param {{ root: string, rulesDir: string, runtime: import('@forwardimpact/libutil/runtime').Runtime }} options
+ * @returns {Promise<object[]>} The modules' default exports.
+ */
+export async function loadRuleModules({
+  root,
+  rulesDir = INVARIANTS_DIR,
+  runtime,
+}) {
+  const dir = resolve(root, rulesDir);
+  let entries;
+  try {
+    entries = await runtime.fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    throw new Error(`rules directory not found: ${dir}`);
+  }
+  const names = entries
+    .filter((e) => e.isFile() && /\.rules\.m?js$/.test(e.name))
+    .map((e) => e.name)
+    .sort();
+  if (names.length === 0) {
+    throw new Error(`no *.rules.mjs modules found in ${dir}`);
+  }
+  const modules = [];
+  for (const name of names) {
+    const mod = (await import(pathToFileURL(resolve(dir, name)).href)).default;
+    assertModuleShape(mod, name);
+    modules.push(mod);
+  }
+  return modules;
+}
+
+/**
+ * Run already-loaded rule modules: 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
+ * @returns {Promise<object[]>} Structured findings; empty when conformant.
+ */
+export async function runRuleModules(modules, { root, runtime }) {
+  const findings = [];
+  for (const mod of modules) {
+    const { subjects, ctx = {} } = await mod.build({ root, runtime });
+    findings.push(
+      ...runRules(
+        mod.rules,
+        { ...ctx, subjects },
+        { resolveScope: (key, c) => c.subjects[key] ?? [] },
+      ),
+    );
+  }
+  return findings;
+}
+
+/**
+ * Load every rule module under `root`/`rulesDir` and run it.
+ *
+ * @param {{ root: string, rulesDir: string, runtime: import('@forwardimpact/libutil/runtime').Runtime }} options
+ * @returns {Promise<object[]>} Structured findings; empty when conformant.
+ *   Each finding is `{ id, level, path, lineNo?, message, hint? }` for use
+ *   with `emitFindingsText` / `emitFindingsJson` from libutil.
+ */
+export async function checkInvariants({
+  root,
+  rulesDir = INVARIANTS_DIR,
+  runtime,
+}) {
+  if (!runtime) throw new Error("runtime is required");
+  const modules = await loadRuleModules({ root, rulesDir, runtime });
+  return runRuleModules(modules, { root, runtime });
+}