@forwardimpact/libcoaligned 0.1.5 → 0.1.7

package/README.md

@@ -11,7 +11,7 @@ invariants across the repo.
 
 ```sh
 npx coaligned                   # run every check (instructions + jtbd)
-npx coaligned instructions      # enforce L1–L6 length and checklist caps
+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
 ```
@@ -20,8 +20,9 @@ The two 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,
-  L3 agent profile, L4 SKILL.md, L5 reference, L6 checklist block) is gated by
-  a line cap **and** a word cap. Either breach fails.
+  L3 agent profile, L4 agent reference, L5 SKILL.md, L6 skill reference,
+  L7 checklist block) is gated by a line cap **and** a word cap. Either breach
+  fails.
 - `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.

package/bin/coaligned.js

@@ -2,13 +2,18 @@
 
 import "@forwardimpact/libpreflight/node22";
 
-import { readFileSync } from "node:fs";
+import { createDefaultRuntime } from "@forwardimpact/libutil/runtime";
 import { createCli } from "@forwardimpact/libcli";
 import { emitFindingsJson, emitFindingsText } from "@forwardimpact/libutil";
 import { checkInstructions, checkJtbd } from "../src/index.js";
 
+const runtime = createDefaultRuntime();
+
 const { version: VERSION } = JSON.parse(
-  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+  runtime.fsSync.readFileSync(
+    new URL("../package.json", import.meta.url),
+    "utf8",
+  ),
 );
 
 const definition = {
@@ -48,55 +53,67 @@ const definition = {
 
 const cli = createCli(definition);
 
-function writeFindings(findings, passMessage, jsonOutput, cwd) {
+function writeFindings(findings, passMessage, jsonOutput, cwd, rt) {
   if (jsonOutput) {
-    process.stdout.write(emitFindingsJson(findings));
+    rt.proc.stdout.write(emitFindingsJson(findings));
   } else if (findings.length > 0) {
-    process.stderr.write(emitFindingsText(findings, { cwd, passMessage }));
+    rt.proc.stderr.write(emitFindingsText(findings, { cwd, passMessage }));
   } else {
-    process.stdout.write(emitFindingsText(findings, { cwd, passMessage }));
+    rt.proc.stdout.write(emitFindingsText(findings, { cwd, passMessage }));
   }
 }
 
-async function runInstructions(root, jsonOutput) {
-  const findings = await checkInstructions({ root });
-  writeFindings(findings, "coaligned instructions passed", jsonOutput, root);
+async function runInstructions(root, jsonOutput, rt) {
+  const findings = await checkInstructions({ root, runtime: rt });
+  writeFindings(
+    findings,
+    "coaligned instructions passed",
+    jsonOutput,
+    root,
+    rt,
+  );
   return findings.length > 0 ? 1 : 0;
 }
 
-async function runJtbd(root, fix, jsonOutput) {
-  const { findings, stale, fixed } = await checkJtbd({ root, fix });
-  writeFindings(findings, "coaligned jtbd passed", jsonOutput, root);
-  for (const f of fixed) process.stdout.write(`Regenerated ${f}.\n`);
+async function runJtbd(root, fix, jsonOutput, rt) {
+  const { findings, stale, fixed } = await checkJtbd({
+    root,
+    fix,
+    runtime: rt,
+  });
+  writeFindings(findings, "coaligned jtbd passed", jsonOutput, root, rt);
+  for (const f of fixed) rt.proc.stdout.write(`Regenerated ${f}.\n`);
   if (stale.length > 0 && !jsonOutput) {
-    process.stderr.write(
+    rt.proc.stderr.write(
       `\n${stale.length} file${stale.length === 1 ? "" : "s"} out of date — run \`coaligned jtbd --fix\` to regenerate:\n`,
     );
-    for (const s of stale) process.stderr.write(`  - ${s}\n`);
+    for (const s of stale) rt.proc.stderr.write(`  - ${s}\n`);
   }
   return findings.length > 0 || stale.length > 0 ? 1 : 0;
 }
 
 async function instructionsHandler(ctx) {
-  return runInstructions(ctx.data.root, !!ctx.options.json);
+  const rt = ctx.deps.runtime;
+  return runInstructions(ctx.data.root, !!ctx.options.json, rt);
 }
 
 async function jtbdHandler(ctx) {
-  return runJtbd(ctx.data.root, !!ctx.options.fix, !!ctx.options.json);
+  const rt = ctx.deps.runtime;
+  return runJtbd(ctx.data.root, !!ctx.options.fix, !!ctx.options.json, rt);
 }
 
 async function main() {
-  const parsed = cli.parse(process.argv.slice(2));
-  if (!parsed) return 0;
+  const parsed = cli.parse(runtime.proc.argv.slice(2));
+  if (!parsed) return runtime.proc.exit(0);
 
-  const root = process.cwd();
+  const root = runtime.proc.cwd();
   const jsonOutput = !!parsed.values.json;
 
   // No subcommand → run every check; --fix stays jtbd-only and must be opted
   // into explicitly via `coaligned jtbd --fix`.
   if (parsed.positionals.length === 0) {
-    const a = await runInstructions(root, jsonOutput);
-    const b = await runJtbd(root, false, jsonOutput);
+    const a = await runInstructions(root, jsonOutput, runtime);
+    const b = await runJtbd(root, false, jsonOutput, runtime);
     return a || b;
   }
 
@@ -106,12 +123,12 @@ async function main() {
     return 2;
   }
 
-  return await cli.dispatch(parsed, { data: { root } });
+  return await cli.dispatch(parsed, { data: { root }, deps: { runtime } });
 }
 
 main()
-  .then((code) => process.exit(code ?? 0))
+  .then((code) => runtime.proc.exit(code ?? 0))
   .catch((err) => {
     cli.error(err.message);
-    process.exit(1);
+    runtime.proc.exit(1);
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libcoaligned",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Co-Aligned architecture checks — enforce instruction-layer length caps and JTBD invariants across the repo.",
   "keywords": [
     "coaligned",

package/src/instructions.js

@@ -1,5 +1,5 @@
-import { readFile, readdir } from "node:fs/promises";
 import { resolve } from "node:path";
+import { createDefaultRuntime } from "@forwardimpact/libutil/runtime";
 import { runRules } from "@forwardimpact/libutil";
 
 const SKIP_DIRS = new Set([
@@ -14,8 +14,8 @@ const SKIP_DIRS = new Set([
   "worktrees",
 ]);
 
-const L6_MAX_ITEMS = 9;
-const L6_MAX_WORDS_PER_ITEM = 32;
+const L7_MAX_ITEMS = 9;
+const L7_MAX_WORDS_PER_ITEM = 32;
 
 const CHECKLIST_RE =
   /<(read_do_checklist|do_confirm_checklist)\b[^>]*>([\s\S]*?)<\/\1>/g;
@@ -24,10 +24,10 @@ const ITEM_SPLIT_RE = /^\s*-\s*\[[ xX]\]\s*/m;
 const lineCount = (text) => (text.match(/\n/g) || []).length;
 const wordCount = (text) => (text.match(/\S+/g) || []).length;
 
-async function walk(root, dir, visit) {
+async function walk(root, dir, visit, fs) {
   let entries;
   try {
-    entries = await readdir(resolve(root, dir), { withFileTypes: true });
+    entries = await fs.readdir(resolve(root, dir), { withFileTypes: true });
   } catch {
     return;
   }
@@ -35,75 +35,103 @@ async function walk(root, dir, visit) {
     if (SKIP_DIRS.has(e.name)) continue;
     const path = dir === "." ? e.name : `${dir}/${e.name}`;
     await visit(e, path);
-    if (e.isDirectory()) await walk(root, path, visit);
+    if (e.isDirectory()) await walk(root, path, visit, fs);
   }
 }
 
-async function listFiles(root, dir, match) {
+async function listFiles(root, dir, match, fs) {
   try {
-    const entries = await readdir(resolve(root, dir), { withFileTypes: true });
+    const entries = await fs.readdir(resolve(root, dir), {
+      withFileTypes: true,
+    });
     return entries.filter(match).map((e) => `${dir}/${e.name}`);
   } catch {
     return [];
   }
 }
 
-async function readText(root, path) {
+async function readText(root, path, fs) {
   try {
-    return await readFile(resolve(root, path), "utf8");
+    return await fs.readFile(resolve(root, path), "utf8");
   } catch {
     return null;
   }
 }
 
-async function findByName(root, name, kind) {
+async function findByName(root, name, kind, fs) {
   const out = [];
-  await walk(root, ".", (e, path) => {
-    const isMatch = kind === "file" ? e.isFile() : e.isDirectory();
-    if (isMatch && e.name === name) out.push(path);
-  });
+  await walk(
+    root,
+    ".",
+    (e, path) => {
+      const isMatch = kind === "file" ? e.isFile() : e.isDirectory();
+      if (isMatch && e.name === name) out.push(path);
+    },
+    fs,
+  );
   return out;
 }
 
-async function findAgentProfiles(root, claudeDirs) {
+async function findAgentProfiles(root, claudeDirs, fs) {
   const out = [];
   for (const d of claudeDirs) {
     const files = await listFiles(
       root,
       `${d}/agents`,
       (e) => e.isFile() && e.name.endsWith(".md"),
+      fs,
+    );
+    out.push(...files);
+  }
+  return out;
+}
+
+async function findAgentReferences(root, claudeDirs, fs) {
+  const out = [];
+  for (const d of claudeDirs) {
+    const files = await listFiles(
+      root,
+      `${d}/agents/references`,
+      (e) => e.isFile() && e.name.endsWith(".md"),
+      fs,
     );
     out.push(...files);
   }
   return out;
 }
 
-async function findSkillDirs(root, claudeDirs) {
+async function findSkillDirs(root, claudeDirs, fs) {
   const out = [];
   for (const d of claudeDirs) {
-    const dirs = await listFiles(root, `${d}/skills`, (e) => e.isDirectory());
+    const dirs = await listFiles(
+      root,
+      `${d}/skills`,
+      (e) => e.isDirectory(),
+      fs,
+    );
     out.push(...dirs);
   }
   return out;
 }
 
-async function findSkillReferences(root, skillDirs) {
+async function findSkillReferences(root, skillDirs, fs) {
   const out = [];
   for (const d of skillDirs) {
     const files = await listFiles(
       root,
       `${d}/references`,
       (e) => e.isFile() && e.name.endsWith(".md"),
+      fs,
     );
     out.push(...files);
   }
   return out;
 }
 
-async function buildLayers(root) {
-  const claudeDirs = await findByName(root, ".claude", "dir");
-  const skillDirs = await findSkillDirs(root, claudeDirs);
-  const allClaude = await findByName(root, "CLAUDE.md", "file");
+async function buildLayers(root, fs) {
+  const claudeDirs = await findByName(root, ".claude", "dir", fs);
+  const skillDirs = await findSkillDirs(root, claudeDirs, fs);
+  const allClaude = await findByName(root, "CLAUDE.md", "file", fs);
   const rootClaude = allClaude.filter((p) => p === "CLAUDE.md");
   const subdirClaude = allClaude.filter((p) => p !== "CLAUDE.md");
   return {
@@ -143,21 +171,28 @@ async function buildLayers(root) {
         name: "agent profile",
         maxLines: 72,
         maxWords: 448,
-        files: await findAgentProfiles(root, claudeDirs),
+        files: await findAgentProfiles(root, claudeDirs, fs),
       },
       {
         id: "L4",
+        name: "agent reference",
+        maxLines: 192,
+        maxWords: 1280,
+        files: await findAgentReferences(root, claudeDirs, fs),
+      },
+      {
+        id: "L5",
         name: "skill procedure",
         maxLines: 192,
         maxWords: 1280,
         files: skillDirs.map((d) => `${d}/SKILL.md`),
       },
       {
-        id: "L5",
+        id: "L6",
         name: "skill reference",
         maxLines: 128,
         maxWords: 768,
-        files: await findSkillReferences(root, skillDirs),
+        files: await findSkillReferences(root, skillDirs, fs),
       },
     ],
   };
@@ -173,11 +208,11 @@ function offsetToLine(text, offset) {
 
 // -- Subject builders ----------------------------------------------------
 
-async function buildFileSubjects(root, layers) {
+async function buildFileSubjects(root, layers, fs) {
   const subjects = [];
   for (const layer of layers) {
     for (const relPath of layer.files) {
-      const text = await readText(root, relPath);
+      const text = await readText(root, relPath, fs);
       if (text == null) continue;
       subjects.push({
         path: resolve(root, relPath),
@@ -192,10 +227,10 @@ async function buildFileSubjects(root, layers) {
   return subjects;
 }
 
-async function buildChecklistSubjects(root, sources) {
+async function buildChecklistSubjects(root, sources, fs) {
   const subjects = [];
   for (const relPath of sources) {
-    const text = await readText(root, relPath);
+    const text = await readText(root, relPath, fs);
     if (text == null) continue;
     const absPath = resolve(root, relPath);
     CHECKLIST_RE.lastIndex = 0;
@@ -241,29 +276,29 @@ export const INSTRUCTION_RULES = [
     hint: HINT_LAYER_BUDGET,
   },
   {
-    id: "L6.too-many-items",
+    id: "L7.too-many-items",
     scope: "checklist-block",
     severity: "fail",
     check: (s) =>
-      s.items.length > L6_MAX_ITEMS
-        ? { count: s.items.length, max: L6_MAX_ITEMS }
+      s.items.length > L7_MAX_ITEMS
+        ? { count: s.items.length, max: L7_MAX_ITEMS }
         : null,
     message: (s, r) =>
       `checklist #${s.blockIndex} (${s.type}) has ${r.count} items (max ${r.max})`,
     hint: "split the checklist into multiple sections, or remove items not load-bearing for the goal",
   },
   {
-    id: "L6.item-too-many-words",
+    id: "L7.item-too-many-words",
     scope: "checklist-block",
     severity: "fail",
     check: (s) => {
       const offenders = [];
       s.items.forEach((item, i) => {
-        if (item.words > L6_MAX_WORDS_PER_ITEM) {
+        if (item.words > L7_MAX_WORDS_PER_ITEM) {
           offenders.push({
             itemIndex: i + 1,
             words: item.words,
-            max: L6_MAX_WORDS_PER_ITEM,
+            max: L7_MAX_WORDS_PER_ITEM,
           });
         }
       });
@@ -278,21 +313,23 @@ export const INSTRUCTION_RULES = [
 // -- Public entry --------------------------------------------------------
 
 /**
- * Walk the repo rooted at `root`, applying the L1–L6 caps from COALIGNED.md.
+ * Walk the repo rooted at `root`, applying the L1–L7 caps from COALIGNED.md.
  * Each layer is gated by a line cap AND a word cap; either breach fails.
  *
- * @param {{ root: string }} options
+ * @param {{ root: string, runtime?: import('@forwardimpact/libutil/runtime').Runtime }} options
  * @returns {Promise<Finding[]>} Structured findings; empty when conformant.
  *   Each Finding is `{ id, level, path, lineNo?, message, hint? }` for use
  *   with `emitFindingsText` / `emitFindingsJson` from libutil.
  */
-export async function checkInstructions({ root }) {
-  const { layers, skillDirs } = await buildLayers(root);
-  const fileSubjects = await buildFileSubjects(root, layers);
-  const checklistSubjects = await buildChecklistSubjects(root, [
-    "CONTRIBUTING.md",
-    ...skillDirs.map((d) => `${d}/SKILL.md`),
-  ]);
+export async function checkInstructions({ root, runtime }) {
+  const { fs } = runtime ?? createDefaultRuntime();
+  const { layers, skillDirs } = await buildLayers(root, fs);
+  const fileSubjects = await buildFileSubjects(root, layers, fs);
+  const checklistSubjects = await buildChecklistSubjects(
+    root,
+    ["CONTRIBUTING.md", ...skillDirs.map((d) => `${d}/SKILL.md`)],
+    fs,
+  );
 
   const ctx = {
     subjects: {

package/src/jtbd.js

@@ -1,7 +1,7 @@
-import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import * as prettier from "prettier";
 import { runRules } from "@forwardimpact/libutil";
+import { createDefaultRuntime } from "@forwardimpact/libutil/runtime";
 
 const VALID_USERS = [
   "Engineering Leaders",
@@ -39,15 +39,15 @@ function catalogs(root) {
   ];
 }
 
-function loadPackages(dir, filter) {
-  if (!existsSync(dir)) return [];
+function loadPackages(dir, filter, fsSync) {
+  if (!fsSync.existsSync(dir)) return [];
   const out = [];
-  for (const name of readdirSync(dir)) {
+  for (const name of fsSync.readdirSync(dir)) {
     if (!filter(name)) continue;
     const pkgPath = join(dir, name, "package.json");
     let pkg;
     try {
-      pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+      pkg = JSON.parse(fsSync.readFileSync(pkgPath, "utf8"));
     } catch {
       continue;
     }
@@ -404,18 +404,18 @@ async function buildDescription(content, description, formatMarkdown) {
   );
 }
 
-function commitUpdate(filePath, label, original, updated, fix, result) {
+function commitUpdate(filePath, label, original, updated, fix, result, fsSync) {
   if (updated === null || updated === original) return;
   if (!fix) {
     result.stale.push(label);
     return;
   }
-  writeFileSync(filePath, updated);
+  fsSync.writeFileSync(filePath, updated);
   result.fixed.push(label);
 }
 
-async function processCatalog(catalog, fix, formatMarkdown, result) {
-  const packages = loadPackages(catalog.dir, catalog.filter);
+async function processCatalog(catalog, fix, formatMarkdown, result, fsSync) {
+  const packages = loadPackages(catalog.dir, catalog.filter, fsSync);
   const findings = validate(packages, catalog.dir, catalog.name, {
     skipUniqueHires: catalog.skipUniqueHires ?? false,
   });
@@ -424,8 +424,8 @@ async function processCatalog(catalog, fix, formatMarkdown, result) {
     return;
   }
 
-  if (existsSync(catalog.readme)) {
-    const original = readFileSync(catalog.readme, "utf8");
+  if (fsSync.existsSync(catalog.readme)) {
+    const original = fsSync.readFileSync(catalog.readme, "utf8");
     let content = original;
     content = await buildCatalog(
       content,
@@ -441,14 +441,15 @@ async function processCatalog(catalog, fix, formatMarkdown, result) {
       content,
       fix,
       result,
+      fsSync,
     );
   }
 
   for (const { dir, pkg } of packages) {
     if (!pkg.description) continue;
     const pkgReadme = join(catalog.dir, dir, "README.md");
-    if (!existsSync(pkgReadme)) continue;
-    const original = readFileSync(pkgReadme, "utf8");
+    if (!fsSync.existsSync(pkgReadme)) continue;
+    const original = fsSync.readFileSync(pkgReadme, "utf8");
     const updated = await buildDescription(
       original,
       pkg.description,
@@ -461,15 +462,20 @@ async function processCatalog(catalog, fix, formatMarkdown, result) {
       updated,
       fix,
       result,
+      fsSync,
     );
   }
 }
 
-async function processJtbdMd(root, fix, formatMarkdown, result) {
+async function processJtbdMd(root, fix, formatMarkdown, result, fsSync) {
   const jtbdPath = join(root, "JTBD.md");
-  if (!existsSync(jtbdPath)) return;
+  if (!fsSync.existsSync(jtbdPath)) return;
   const productsCatalog = catalogs(root).find((c) => c.name === "products");
-  const packages = loadPackages(productsCatalog.dir, productsCatalog.filter);
+  const packages = loadPackages(
+    productsCatalog.dir,
+    productsCatalog.filter,
+    fsSync,
+  );
   const findings = validate(packages, productsCatalog.dir, "products", {
     skipUniqueHires: true,
   });
@@ -477,11 +483,11 @@ async function processJtbdMd(root, fix, formatMarkdown, result) {
     if (result.findings.length === 0) result.findings.push(...findings);
     return;
   }
-  const original = readFileSync(jtbdPath, "utf8");
+  const original = fsSync.readFileSync(jtbdPath, "utf8");
   const updated = await buildJobs(original, packages, formatMarkdown, {
     capitalize: true,
   });
-  commitUpdate(jtbdPath, "JTBD.md", original, updated, fix, result);
+  commitUpdate(jtbdPath, "JTBD.md", original, updated, fix, result, fsSync);
 }
 
 /**
@@ -489,22 +495,23 @@ async function processJtbdMd(root, fix, formatMarkdown, result) {
  * libraries/, and (when `fix` is true) regenerate the marker-delimited catalog,
  * jobs, and description blocks in the corresponding README.md and JTBD.md.
  *
- * @param {{ root: string, fix?: boolean }} options
+ * @param {{ root: string, fix?: boolean, runtime?: import('@forwardimpact/libutil/runtime').Runtime }} options
  * @returns {Promise<{ findings: Finding[], stale: string[], fixed: string[] }>}
  *   `findings` are validation failures (structured for `emitFindingsText` /
  *   `emitFindingsJson` from libutil); `stale` is files whose generated blocks
  *   are out of date (only populated when `fix` is false); `fixed` is files
  *   that were rewritten in place.
  */
-export async function checkJtbd({ root, fix = false }) {
+export async function checkJtbd({ root, fix = false, runtime }) {
+  const { fsSync } = runtime ?? createDefaultRuntime();
   const result = { findings: [], stale: [], fixed: [] };
   const prettierConfig = await prettier.resolveConfig(join(root, "JTBD.md"));
   const formatMarkdown = makeFormatter(prettierConfig);
 
   for (const catalog of catalogs(root)) {
-    await processCatalog(catalog, fix, formatMarkdown, result);
+    await processCatalog(catalog, fix, formatMarkdown, result, fsSync);
   }
-  await processJtbdMd(root, fix, formatMarkdown, result);
+  await processJtbdMd(root, fix, formatMarkdown, result, fsSync);
 
   return result;
 }