@forwardimpact/libcoaligned 0.1.6 → 0.1.8

package/bin/coaligned.js

@@ -2,18 +2,15 @@
 
 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 { version: VERSION } = JSON.parse(
-  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
-);
+const runtime = createDefaultRuntime();
 
 const definition = {
   name: "coaligned",
-  version: VERSION,
   description:
     "Enforce the layered instruction architecture defined in COALIGNED.md (no subcommand: run every check)",
   commands: [
@@ -46,57 +43,72 @@ const definition = {
   examples: ["coaligned", "coaligned instructions", "coaligned jtbd --fix"],
 };
 
-const cli = createCli(definition);
+const cli = createCli(definition, {
+  runtime,
+  packageJsonUrl: new URL("../package.json", import.meta.url),
+});
 
-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 +118,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.6",
+  "version": "0.1.8",
   "description": "Co-Aligned architecture checks — enforce instruction-layer length caps and JTBD invariants across the repo.",
   "keywords": [
     "coaligned",
@@ -50,6 +50,9 @@
     "@forwardimpact/libutil": "*",
     "prettier": "^3.0.0"
   },
+  "devDependencies": {
+    "@forwardimpact/libmock": "^0.1.0"
+  },
   "engines": {
     "bun": ">=1.2.0",
     "node": ">=22.0.0"

package/src/instructions.js

@@ -1,4 +1,3 @@
-import { readFile, readdir } from "node:fs/promises";
 import { resolve } from "node:path";
 import { runRules } from "@forwardimpact/libutil";
 
@@ -24,10 +23,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,88 +34,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) {
+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 {
@@ -156,14 +170,14 @@ 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),
+        files: await findAgentReferences(root, claudeDirs, fs),
       },
       {
         id: "L5",
@@ -177,7 +191,7 @@ async function buildLayers(root) {
         name: "skill reference",
         maxLines: 128,
         maxWords: 768,
-        files: await findSkillReferences(root, skillDirs),
+        files: await findSkillReferences(root, skillDirs, fs),
       },
     ],
   };
@@ -193,11 +207,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),
@@ -212,10 +226,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;
@@ -301,18 +315,21 @@ export const INSTRUCTION_RULES = [
  * 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 }) {
+  if (!runtime) throw new Error("runtime is required");
+  const { fs } = runtime;
+  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,4 +1,3 @@
-import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import * as prettier from "prettier";
 import { runRules } from "@forwardimpact/libutil";
@@ -39,15 +38,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 +403,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 +423,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 +440,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 +461,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 +482,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 +494,24 @@ 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 }) {
+  if (!runtime) throw new Error("runtime is required");
+  const { fsSync } = runtime;
   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;
 }