adsa-cli 0.1.0

package/lib/config.mjs

@@ -0,0 +1,103 @@
+/**
+ * Configuration. Everything has a default, and anything the tool can read from the
+ * repo is never asked for: the config exists for the handful of things detection
+ * gets wrong in a repo laid out unusually.
+ */
+import { join } from "node:path";
+import { readdirSync } from "node:fs";
+import { exists, isDir, read, readJson } from "./fsx.mjs";
+
+export const CONFIG_NAME = "adsa.config.json";
+
+export const DEFAULTS = {
+    /** Directories that hold component guides, in priority order. */
+    guides: null,
+    /** Where component source lives. */
+    source: null,
+    /** Extra packages a consumer must never import alongside this system. */
+    forbidden: ["lucide-react", "@heroicons/react", "react-icons", "@mui/material", "@chakra-ui/react", "antd", "shadcn-ui"],
+    /** Files that carry agent instructions, in priority order. */
+    agentFiles: ["AGENTS.md", "CLAUDE.md", ".cursorrules", ".github/copilot-instructions.md"],
+    /** Minimum score for `adsa audit --gate`. */
+    minScore: null,
+    /** Dimensions to skip, e.g. ["patterns"] for a primitives-only library. */
+    skip: [],
+};
+
+const GUIDE_DIRS = ["guidelines", "docs/components", "docs/guides", "documentation/components", "docs", "documentation", "www/content", "apps/docs/content"];
+const SOURCE_DIRS = ["src/components", "Sources", "src/main/kotlin", "src", "packages/ui/src", "lib/components", "components"];
+
+export function loadConfig(root) {
+    const file = readJson(join(root, CONFIG_NAME)) || {};
+    const config = { ...DEFAULTS, ...file };
+    config.guides = normalizeDirs(root, config.guides, GUIDE_DIRS);
+    config.source = normalizeDirs(root, config.source, SOURCE_DIRS);
+    config.configFile = exists(join(root, CONFIG_NAME)) ? CONFIG_NAME : null;
+    return config;
+}
+
+function normalizeDirs(root, value, candidates) {
+    const list = value ? (Array.isArray(value) ? value : [value]) : candidates;
+    const found = list.filter((d) => isDir(join(root, d)));
+    // Only the first match from the candidate list, so `docs` does not shadow `guidelines`.
+    return value ? found : found.slice(0, 1);
+}
+
+/**
+ * Design systems usually live in a monorepo. When the given directory is a workspace
+ * root with nothing to audit in it, pick the package that looks most like the design
+ * system — the one with the most guides and exported subpaths — and say so.
+ *
+ * @returns {{ dir:string, note:string|null, candidates:Array<{dir:string,name:string,score:number}> }}
+ */
+export function resolveTarget(root) {
+    const pkg = readJson(join(root, "package.json"));
+    if (pkg && (pkg.exports || isDir(join(root, "guidelines")))) return { dir: root, note: null, candidates: [] };
+
+    const patterns = workspacePatterns(root, pkg);
+    if (!patterns.length) return { dir: root, note: null, candidates: [] };
+
+    const candidates = [];
+    for (const pattern of patterns) {
+        for (const dir of expand(root, pattern)) {
+            const p = readJson(join(dir, "package.json"));
+            if (!p || p.private === true) continue;
+            const guides = countGuides(dir);
+            const exports_ = Object.keys(p.exports || {}).filter((k) => k.startsWith("./")).length;
+            const score = guides * 3 + exports_;
+            if (score > 0) candidates.push({ dir, name: p.name || dir, score, guides, exports: exports_ });
+        }
+    }
+    candidates.sort((a, b) => b.score - a.score);
+    if (!candidates.length) return { dir: root, note: null, candidates: [] };
+    return { dir: candidates[0].dir, note: `workspace: audited ${candidates[0].name}`, candidates };
+}
+
+function workspacePatterns(root, pkg) {
+    const fromPkg = Array.isArray(pkg?.workspaces) ? pkg.workspaces : pkg?.workspaces?.packages || [];
+    const yaml = read(join(root, "pnpm-workspace.yaml")) || "";
+    const fromYaml = [...yaml.matchAll(/^\s*-\s*["']?([^"'\n]+)["']?/gm)].map((m) => m[1].trim());
+    return [...new Set([...fromPkg, ...fromYaml])].filter(Boolean);
+}
+
+/** Only the `dir/*` and `dir` shapes real workspace globs use. */
+function expand(root, pattern) {
+    const clean = pattern.replace(/\/\*\*$/, "/*");
+    if (!clean.includes("*")) return isDir(join(root, clean)) ? [join(root, clean)] : [];
+    const base = join(root, clean.slice(0, clean.indexOf("*")).replace(/\/$/, ""));
+    if (!isDir(base)) return [];
+    try {
+        return readdirSync(base, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+            .map((e) => join(base, e.name));
+    } catch {
+        return [];
+    }
+}
+
+function countGuides(dir) {
+    for (const candidate of ["guidelines", "docs", "documentation"]) {
+        if (isDir(join(dir, candidate))) return 1;
+    }
+    return 0;
+}

package/lib/dense.mjs

@@ -0,0 +1,21 @@
+/** Strips prose, keeps the parts an agent acts on: headings, code, tables, lists. */
+export function dense(markdown) {
+    const lines = markdown.split("\n");
+    const out = [];
+    let inFence = false;
+    for (const line of lines) {
+        if (/^\s*```/.test(line)) {
+            inFence = !inFence;
+            out.push(line);
+            continue;
+        }
+        if (inFence) {
+            out.push(line);
+            continue;
+        }
+        if (/^\s*#{1,6}\s/.test(line) || /^\s*\|/.test(line) || /^\s*[-*+]\s/.test(line) || /^\s*\d+\.\s/.test(line) || /^\s*$/.test(line) || /^\s*>/.test(line)) {
+            out.push(line);
+        }
+    }
+    return out.join("\n").replace(/\n{3,}/g, "\n\n").trim() + "\n";
+}

package/lib/eval.mjs

@@ -0,0 +1,140 @@
+/**
+ * The experiment. A static audit says how well documented a system is; this measures
+ * what an agent actually produced when it used the system, which is the only number
+ * that has ever changed anyone's mind.
+ *
+ * The agent does the building. This writes the task and then measures the result.
+ */
+import { join, relative } from "node:path";
+import { isDir, read, rel, walk } from "./fsx.mjs";
+
+const IMPORT = /import\s*(?:type\s*)?(?:\{([^}]*)\}|(\w+)|\*\s*as\s*(\w+))?\s*(?:,\s*\{([^}]*)\})?\s*from\s*["']([^"']+)["']/g;
+const PALETTE = "slate|gray|grey|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose";
+const RAW_PALETTE = new RegExp(`\\b(?:bg|text|border|ring|fill|stroke|from|to|via|divide)-(?:${PALETTE})-\\d{2,3}\\b`, "g");
+const HEX = /#[0-9a-fA-F]{6}\b/g;
+
+/** Always relative: a task file is committed, and an absolute path is both a leak and wrong for everyone else. */
+function systemPath(root) {
+    const rel = relative(process.cwd(), root);
+    return !rel ? "." : rel.startsWith("..") ? "<path-to-the-design-system>" : rel;
+}
+
+export function taskFile(facts, values) {
+    return `# Agent-readiness experiment
+
+Give this task to a coding agent in a **fresh session**, with no other context than
+this repository and the design system it depends on.
+
+## The task
+
+Build one real page using **only ${facts.name}**. Pick a page your product actually
+has — a list with filters, a settings form, a detail view — not a showcase of
+components.
+
+Rules for the agent:
+
+- Every UI element comes from ${facts.name}. No second component library, no icons
+  from anywhere else, no local copies of component source.
+- Colour, spacing and typography come from the system's tokens.
+- If something you need does not exist in the system, **stop and say so** instead of
+  building your own version of it.
+- Work to a running page, not a sketch.
+
+## Then measure it
+
+\`\`\`bash
+adsa eval score <the-project-you-just-built> --system ${systemPath(facts.root)}
+\`\`\`
+
+The number that matters is how many imports name components the system does not
+have. Everything else is commentary.
+
+## What to record
+
+| Metric | Round 1 | Round 2 |
+| :-- | :-- | :-- |
+| Components invented | | |
+| Imports from the system | | |
+| Forbidden packages | | |
+| Raw palette classes | | |
+| Time to a working page | | |
+
+Run it again after the fixes. The gap between the two columns is the argument.
+`;
+}
+
+/**
+ * @param {string} consumerRoot project the agent produced
+ * @param {object} facts scan of the design system it was supposed to use
+ */
+export function evaluate(consumerRoot, facts, config) {
+    const files = walk(consumerRoot, [".tsx", ".jsx", ".ts", ".js", ".vue", ".svelte"], 7).filter((f) => !/\.(test|spec|stories)\./.test(f));
+    const known = facts.symbols instanceof Set ? facts.symbols : new Set(facts.symbols || []);
+    const forbidden = new Set(config.forbidden || []);
+    const result = {
+        project: consumerRoot,
+        system: facts.name,
+        files: files.length,
+        used: new Set(),
+        invented: [],
+        systemImports: 0,
+        forbiddenImports: [],
+        rawPalette: [],
+        hex: [],
+        localUiFolder: ["components/ui", "src/components/ui", "app/components/ui"].filter((p) => isDir(join(consumerRoot, p))),
+    };
+
+    for (const file of files) {
+        const text = read(file) || "";
+        const lines = text.split("\n");
+        for (const [index, line] of lines.entries()) {
+            for (const m of line.matchAll(RAW_PALETTE)) result.rawPalette.push({ file: rel(consumerRoot, file), line: index + 1, value: m[0] });
+            for (const m of line.matchAll(HEX)) result.hex.push({ file: rel(consumerRoot, file), line: index + 1, value: m[0] });
+        }
+        for (const m of text.matchAll(IMPORT)) {
+            const from = m[5];
+            const named = `${m[1] || ""},${m[4] || ""}`
+                .split(",")
+                .map((s) => s.trim().split(/\s+as\s+/)[0].trim())
+                .filter((s) => s && /^[A-Z]/.test(s));
+            const pkg = packageOf(from);
+            if (forbidden.has(pkg)) {
+                result.forbiddenImports.push({ file: rel(consumerRoot, file), package: pkg });
+                continue;
+            }
+            if (!isSystemImport(from, facts.name)) continue;
+            result.systemImports += named.length;
+            for (const name of named) {
+                if (known.has(name)) result.used.add(name);
+                else result.invented.push({ file: rel(consumerRoot, file), name, from });
+            }
+        }
+    }
+
+    result.used = [...result.used].sort();
+    result.inventedRatio = result.systemImports ? result.invented.length / result.systemImports : 0;
+    result.verdict = verdict(result);
+    return result;
+}
+
+function isSystemImport(from, name) {
+    if (!name) return false;
+    return from === name || from.startsWith(name + "/");
+}
+
+function packageOf(from) {
+    if (from.startsWith(".") || from.startsWith("/")) return null;
+    const parts = from.split("/");
+    return from.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+}
+
+function verdict(r) {
+    if (!r.systemImports) return "The agent did not import from the system at all — check the package name and whether it was installed.";
+    if (r.invented.length === 0 && !r.forbiddenImports.length && !r.rawPalette.length) return "Clean run: every component came from the system, no forbidden packages, no raw palette.";
+    const bits = [];
+    if (r.invented.length) bits.push(`${r.invented.length} of ${r.systemImports} imports name components that do not exist`);
+    if (r.forbiddenImports.length) bits.push(`${r.forbiddenImports.length} imports from packages the system forbids`);
+    if (r.rawPalette.length) bits.push(`${r.rawPalette.length} raw palette classes`);
+    if (r.localUiFolder.length) bits.push(`a local ${r.localUiFolder[0]} folder`);
+    return `${bits.join(", ")}.`;
+}

package/lib/fix.mjs

@@ -0,0 +1,260 @@
+/**
+ * Fixes. Two kinds, and the difference is honest rather than cosmetic:
+ *
+ *   apply  — a file this tool can write correctly in any repository.
+ *   brief  — a task that needs the repo's own stack to do properly, written as a
+ *            specification an agent executes, with the traps we already hit in it.
+ *
+ * Everything is idempotent: applied files are written between markers or created
+ * only when absent, so running a fix twice is a no-op.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { exists, read, readJson } from "./fsx.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES = join(here, "..", "templates");
+const START = "<!-- adsa:start -->";
+const END = "<!-- adsa:end -->";
+
+export const FIXES = {
+    "agents-md": { kind: "apply", title: "Write agent instructions", dimension: "agent-instructions", run: fixAgents },
+    "gaps-file": { kind: "apply", title: "List what the system does not have", dimension: "gap-handling", run: fixGaps },
+    "mcp-config": { kind: "apply", title: "Expose the docs as MCP tools", dimension: "machine-surface", run: fixMcp },
+    "tokens-doc": { kind: "apply", title: "Document tokens as tables", dimension: "tokens", run: fixTokens },
+    "ci-workflow": { kind: "apply", title: "Put the checks in CI", dimension: "verification", run: fixCi },
+    "coverage-gate": { kind: "brief", title: "Fail CI on an undocumented export", dimension: "docs-coverage", brief: "coverage-gate" },
+    "prop-tables": { kind: "brief", title: "Generate prop tables from types", dimension: "docs-freshness", brief: "prop-tables" },
+    "examples-check": { kind: "brief", title: "Compile guide examples in CI", dimension: "docs-freshness", brief: "examples-check" },
+    "a11y-docs": { kind: "brief", title: "Add keyboard and accessibility sections", dimension: "a11y", brief: "a11y-docs" },
+    "patterns-doc": { kind: "brief", title: "Write page-level patterns", dimension: "patterns", brief: "patterns-doc" },
+};
+
+/** Values a template may reference. Derived from the scan, never asked for. */
+export function vars(facts, config) {
+    const platform = facts.platform?.primary || "web";
+    const pm = exists(join(facts.root, "yarn.lock")) ? "yarn" : exists(join(facts.root, "pnpm-lock.yaml")) ? "pnpm" : "npm run";
+    const cli = facts.machine.binNames[0];
+    const lookup = cli ? `run \`npx ${cli} docs <component>\`` : "run `npx adsa-cli search \"<what you need>\"`, then `npx adsa-cli docs <component>`";
+    // Prefer a directory that already holds a real guide — e.g. a Swift package's own
+    // .docc bundle, found by scanning rather than listed in adsa.config.json — over a
+    // generic per-platform guess.
+    const existingGuideDir = facts.guides[0] ? dirname(facts.guides[0].path) : null;
+    const guidesDir = (config.guides && config.guides[0]) || existingGuideDir || defaultGuidesDir(platform);
+    const sourceDir = (config.source && config.source[0]) || defaultSourceDir(platform);
+
+    if (platform === "swift") return swiftVars(facts, guidesDir, sourceDir, lookup);
+    if (platform === "android") return androidVars(facts, guidesDir, sourceDir, lookup);
+
+    // Web and React Native share the same import/export syntax; only the habits and
+    // the token surface differ.
+    const subpath = facts.components.find((c) => c.from === "exports");
+    const isNative = platform === "react-native";
+    return {
+        name: facts.name,
+        version: facts.version ? ` ${facts.version}` : "",
+        stack: isNative
+            ? [facts.stack.expo && "Expo", "React Native", facts.stack.typescript && "TypeScript", facts.stack.nativewind && "NativeWind"].filter(Boolean).join(", ")
+            : [facts.stack.react && "React", facts.stack.typescript && "TypeScript", facts.stack.tailwind && "Tailwind", facts.stack.storybook && "Storybook"].filter(Boolean).join(", ") || "unknown",
+        headless: facts.stack.headless.join(", ") || (isNative ? "Pressable, View and the platform's own accessibility props" : "your headless primitives"),
+        guidesDir,
+        sourceDir,
+        pkgRun: pm,
+        lookup,
+        importExample: subpath ? `import { ${subpath.name} } from "${facts.name}/${subpath.slug}"` : `import { Button } from "${facts.name}"`,
+        importRule: subpath ? "Never from the package root." : "",
+        paletteExample: isNative
+            ? facts.stack.nativewind
+                ? "Raw palette classes (`bg-gray-100`, `text-blue-600`) and raw hex values"
+                : "Raw color literals in `StyleSheet.create` (e.g. `#3366FF`) and inline hex strings"
+            : facts.stack.tailwind
+              ? "`bg-gray-100`, `text-blue-600`"
+              : "raw colour literals",
+        gapsFile: "GAPS.md",
+        finishCheck: finishCheck(facts, pm),
+    };
+}
+
+function defaultGuidesDir(platform) {
+    if (platform === "swift") return "Sources/Documentation.docc";
+    if (platform === "android") return "docs";
+    return "docs";
+}
+
+function defaultSourceDir(platform) {
+    if (platform === "swift") return "Sources";
+    if (platform === "android") return "src/main/kotlin";
+    return "src";
+}
+
+function finishCheck(facts, pm) {
+    const scripts = facts.verification;
+    const bits = [];
+    if (scripts.typecheckScript) bits.push(`\`${pm} typecheck\``);
+    if (scripts.lintScript) bits.push(`\`${pm} lint\``);
+    if (scripts.testScript) bits.push(`\`${pm} test\``);
+    return bits.length ? `${bits.join(", ")} must pass` : "your project's type check and lint must pass";
+}
+
+/** `public struct Foo: View` in Swift takes a module import, not a named one. */
+function swiftVars(facts, guidesDir, sourceDir, lookup) {
+    const first = facts.components[0];
+    return {
+        name: facts.name,
+        version: facts.version ? ` ${facts.version}` : "",
+        stack: "Swift, SwiftUI",
+        headless: "UIKit's accessibility protocol and SwiftUI's accessibility modifiers (`.accessibilityLabel`, `.accessibilityAddTraits`)",
+        guidesDir,
+        sourceDir,
+        pkgRun: "swift",
+        lookup,
+        importExample: `import ${facts.name}`,
+        importRule: first ? `Then use the view directly, e.g. \`${first.name}(...)\`. Never copy its source into your app target.` : "Never copy a view's source into your app target.",
+        paletteExample: "Raw `Color(red:green:blue:)` literals and hardcoded hex strings",
+        gapsFile: "GAPS.md",
+        finishCheck: exists(join(facts.root, "Package.swift")) ? "`swift build` and `swift test` must pass" : "your Xcode scheme's build and tests must pass",
+    };
+}
+
+/** A Kotlin `@Composable fun Foo(...)` is imported by its real package, not guessed. */
+function androidVars(facts, guidesDir, sourceDir, lookup) {
+    const first = facts.components[0];
+    const pkg = first ? kotlinPackageOf(facts.root, first) : null;
+    return {
+        name: facts.name,
+        version: facts.version ? ` ${facts.version}` : "",
+        stack: "Kotlin, Jetpack Compose",
+        headless: "Compose's Semantics API (`contentDescription`, `Role`, `mergeDescendants`)",
+        guidesDir,
+        sourceDir,
+        pkgRun: "./gradlew",
+        lookup,
+        importExample: pkg && first ? `import ${pkg}.${first.name}` : `import <your.package>.${first ? first.name : "Button"}`,
+        importRule: "Never redeclare a composable in your own module.",
+        paletteExample: "Hardcoded `Color(0xFF...)` values and raw hex in layout XML",
+        gapsFile: "GAPS.md",
+        finishCheck: "`./gradlew test lint` must pass",
+    };
+}
+
+function kotlinPackageOf(root, component) {
+    const text = read(join(root, component.from)) || "";
+    const m = text.match(/^package\s+([\w.]+)/m);
+    return m ? m[1] : null;
+}
+
+export function render(template, values) {
+    return template.replace(/\{\{(\w+)\}\}/g, (_, key) => (values[key] === undefined ? `{{${key}}}` : String(values[key])));
+}
+
+function template(name) {
+    return readFileSync(join(TEMPLATES, name), "utf8");
+}
+
+/** @returns {Array<{file:string, action:"create"|"update"|"skip", note:string}>} */
+export function applyFix(id, facts, config, opts = {}) {
+    const fix = FIXES[id];
+    if (!fix) throw new Error(`Unknown fix "${id}". Run \`adsa fix --list\`.`);
+    const values = vars(facts, config);
+    if (fix.kind === "brief") return writeBrief(id, fix, values, facts, opts);
+    return fix.run(facts, config, values, opts);
+}
+
+function writeBrief(id, fix, values, facts, opts) {
+    const file = join(".adsa", "fixes", `${id}.md`);
+    const body = render(template(join("briefs", `${fix.brief}.md`)), values);
+    return [write(facts.root, file, body, opts, "brief for your agent")];
+}
+
+/* ------------------------------------------------------------- apply fixes */
+
+function agentsTemplateFile(platform) {
+    if (platform === "react-native") return "AGENTS.react-native.md.tmpl";
+    if (platform === "swift") return "AGENTS.swift.md.tmpl";
+    if (platform === "android") return "AGENTS.android.md.tmpl";
+    return "AGENTS.md.tmpl";
+}
+
+function tokensTemplateFile(platform) {
+    if (platform === "react-native") return "tokens.native.md.tmpl";
+    if (platform === "swift") return "tokens.swift.md.tmpl";
+    if (platform === "android") return "tokens.android.md.tmpl";
+    return "tokens.md.tmpl";
+}
+
+function fixAgents(facts, config, values, opts) {
+    const target = facts.agentFiles.find((a) => a.file === "AGENTS.md" || a.file === "CLAUDE.md");
+    const file = target ? target.file : "AGENTS.md";
+    const path = join(facts.root, file);
+    const section = render(template(agentsTemplateFile(facts.platform?.primary)), values);
+    const current = read(path);
+    if (current === null) return [write(facts.root, file, `# Agents\n\n${section}`, opts, "design-system section added")];
+    if (current.includes(START) && current.includes(END)) {
+        const next = current.slice(0, current.indexOf(START)) + section.trimEnd() + current.slice(current.indexOf(END) + END.length);
+        if (next === current) return [{ file, action: "skip", note: "section already up to date" }];
+        return [write(facts.root, file, next, opts, "section refreshed")];
+    }
+    return [write(facts.root, file, current.replace(/\s*$/, "\n\n") + section, opts, "section appended")];
+}
+
+function fixGaps(facts, config, values, opts) {
+    const file = facts.gaps.file || "GAPS.md";
+    if (exists(join(facts.root, file))) return [{ file, action: "skip", note: "a gap list already exists" }];
+    return [write(facts.root, "GAPS.md", template("GAPS.md.tmpl"), opts, "created; fill in the real absences")];
+}
+
+function fixMcp(facts, config, values, opts) {
+    const entry = { command: "npx", args: ["--yes", "adsa-cli@latest", "mcp"] };
+    const results = [];
+    for (const file of [".mcp.json", ".cursor/mcp.json", ".vscode/mcp.json"]) {
+        const path = join(facts.root, file);
+        const present = exists(path);
+        if (!present && file !== ".mcp.json") continue;
+        const current = present ? readJson(path) : null;
+        if (present && !current) {
+            results.push({ file, action: "skip", note: "not valid JSON — left alone" });
+            continue;
+        }
+        const config_ = current || {};
+        const key = config_.servers && !config_.mcpServers ? "servers" : "mcpServers";
+        const servers = config_[key] || {};
+        if (servers.adsa) {
+            results.push({ file, action: "skip", note: "the adsa server is already registered" });
+            continue;
+        }
+        const next = { ...config_, [key]: { ...servers, adsa: entry } };
+        results.push(write(facts.root, file, JSON.stringify(next, null, indentOf(present ? readFileSync(path, "utf8") : "")) + "\n", opts, present ? "adsa server added" : "adsa server registered"));
+    }
+    results.push({ file: "—", action: "note", note: "restart your MCP client, then run `adsa doctor`" });
+    return results;
+}
+
+function indentOf(text) {
+    const m = text.match(/\n([ \t]+)\S/);
+    return m ? m[1] : 2;
+}
+
+function fixTokens(facts, config, values, opts) {
+    if (facts.tokens.docs.length) return [{ file: facts.tokens.docs[0], action: "skip", note: "token documentation already exists" }];
+    const file = join(values.guidesDir, "design-tokens.md");
+    return [write(facts.root, file, template(tokensTemplateFile(facts.platform?.primary)), opts, "created; replace the example rows")];
+}
+
+function fixCi(facts, config, values, opts) {
+    const file = ".github/workflows/adsa.yml";
+    if (exists(join(facts.root, file))) return [{ file, action: "skip", note: "workflow already present" }];
+    return [write(facts.root, file, template(join("ci", "adsa.yml")), opts, "gates the score on every pull request")];
+}
+
+/* ------------------------------------------------------------------ writing */
+
+function write(root, file, body, opts, note) {
+    const path = join(root, file);
+    const existed = exists(path);
+    if (!opts.dryRun) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, body);
+    }
+    return { file, action: existed ? "update" : "create", note };
+}

package/lib/fsx.mjs

@@ -0,0 +1,94 @@
+/** Filesystem helpers. No dependencies: this runs inside somebody else's repo. */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "out", ".next", "coverage", ".turbo", ".yarn", "storybook-static", ".cache"]);
+
+/** Every file under `dir` with one of `exts`, depth-limited. Returns absolute paths. */
+export function walk(dir, exts, maxDepth = 8, _depth = 0, _out = []) {
+    if (_depth > maxDepth || !existsSync(dir)) return _out;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return _out;
+    }
+    for (const e of entries) {
+        if (e.name.startsWith(".") && e.name !== ".github") continue;
+        const path = join(dir, e.name);
+        if (e.isDirectory()) {
+            if (SKIP_DIRS.has(e.name)) continue;
+            walk(path, exts, maxDepth, _depth + 1, _out);
+        } else if (!exts || exts.some((x) => e.name.endsWith(x))) {
+            _out.push(path);
+        }
+    }
+    return _out;
+}
+
+/**
+ * Every directory under `dir` whose name ends with one of `suffixes` — e.g. `.xcodeproj`,
+ * `.xcassets`, `.docc`. Does not descend into a matched directory: a bundle like
+ * `Assets.xcassets` is a leaf as far as this tool is concerned. Returns absolute paths.
+ */
+export function walkDirs(dir, suffixes, maxDepth = 8, _depth = 0, _out = []) {
+    if (_depth > maxDepth || !existsSync(dir)) return _out;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return _out;
+    }
+    for (const e of entries) {
+        if (!e.isDirectory()) continue;
+        const path = join(dir, e.name);
+        if (suffixes.some((s) => e.name.endsWith(s))) {
+            _out.push(path);
+            continue;
+        }
+        if (e.name.startsWith(".") || SKIP_DIRS.has(e.name)) continue;
+        walkDirs(path, suffixes, maxDepth, _depth + 1, _out);
+    }
+    return _out;
+}
+
+export function read(path) {
+    try {
+        return readFileSync(path, "utf8");
+    } catch {
+        return null;
+    }
+}
+
+export function readJson(path) {
+    const text = read(path);
+    if (!text) return null;
+    try {
+        return JSON.parse(text);
+    } catch {
+        return null;
+    }
+}
+
+export function exists(path) {
+    return existsSync(path);
+}
+
+export function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+export function rel(root, path) {
+    const r = relative(root, path);
+    return r.split("\\").join("/");
+}
+
+/** First existing path from a list of candidates, relative to root. */
+export function firstExisting(root, candidates) {
+    for (const c of candidates) if (existsSync(join(root, c))) return c;
+    return null;
+}

package/lib/history.mjs

@@ -0,0 +1,41 @@
+/** Score history, committed with the repo so a regression is visible in a diff. */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { readJson } from "./fsx.mjs";
+
+export const DIR = ".adsa";
+
+export function historyPath(root) {
+    return join(root, DIR, "history.json");
+}
+
+export function readHistory(root) {
+    const json = readJson(historyPath(root));
+    return Array.isArray(json) ? json : [];
+}
+
+/** Appends a run, collapsing same-day reruns so the file does not grow per invocation. */
+export function appendHistory(root, entry) {
+    const history = readHistory(root);
+    const day = entry.date.slice(0, 10);
+    const filtered = history.filter((h) => h.date.slice(0, 10) !== day);
+    filtered.push(entry);
+    write(historyPath(root), filtered);
+    return filtered;
+}
+
+export function write(path, data) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(data, null, 2) + "\n");
+}
+
+/** Per-dimension delta against the previous run. */
+export function compare(previous, current) {
+    if (!previous) return null;
+    const moved = [];
+    for (const [id, score] of Object.entries(current.dimensions)) {
+        const before = previous.dimensions[id];
+        if (before !== score && before != null && score != null) moved.push({ id, from: before, to: score });
+    }
+    return { from: previous.total, to: current.total, delta: current.total - previous.total, moved, since: previous.generatedAt || previous.date };
+}