@monte3l/groundwork 0.0.0

package/dist/harness/frontmatter.js

@@ -0,0 +1,204 @@
+/**
+ * A reader for the YAML subset Claude Code frontmatter actually uses --
+ * `SKILL.md`, agent, and rule files. Hand-rolled because this package has no
+ * runtime dependencies (see `jsonc.ts` for the same trade-off). It handles
+ * the scalar forms real harness files contain: plain, single/double quoted,
+ * block scalars (`>-`, `>`, `|`, `|-`), block lists, and flow lists.
+ *
+ * Deliberately NOT supported: nested mappings (a key whose value is an
+ * indented map, e.g. `mcpServers:` with inline server definitions) -- such a
+ * key is recorded with an empty string value rather than misparsed -- plus
+ * anchors, tags, and multi-document streams. Every string result is
+ * trimmed; a block scalar's trailing newline is not preserved.
+ */
+const KEY_LINE = /^([A-Za-z_][\w-]*):(?:[ \t]+(.*))?$/;
+const BLOCK_SCALAR = /^([>|])(?:[+-]\d?|\d[+-]?)?$/;
+/** Removes the smallest common indent from every non-blank line. */
+function dedent(lines) {
+    const indents = lines
+        .filter((line) => line.trim() !== "")
+        .map((line) => /^[ \t]*/.exec(line)?.[0].length ?? 0);
+    const strip = indents.length === 0 ? 0 : Math.min(...indents);
+    return lines.map((line) => line.slice(strip));
+}
+function foldBlockScalar(lines) {
+    const paragraphs = [[]];
+    for (const line of lines) {
+        if (line.trim() === "") {
+            paragraphs.push([]);
+        }
+        else {
+            paragraphs[paragraphs.length - 1]?.push(line.trim());
+        }
+    }
+    return paragraphs
+        .filter((paragraph) => paragraph.length > 0)
+        .map((paragraph) => paragraph.join(" "))
+        .join("\n");
+}
+/** Unquotes one YAML scalar; an unterminated quote yields `undefined`. */
+function unquote(text) {
+    const trimmed = text.trim();
+    const quote = trimmed[0];
+    if (quote !== '"' && quote !== "'") {
+        return trimmed.replace(/\s+#.*$/, "");
+    }
+    let out = "";
+    for (let i = 1; i < trimmed.length; i++) {
+        const ch = trimmed[i];
+        if (quote === '"' && ch === "\\") {
+            const escaped = trimmed[i + 1];
+            out += escaped === "n" ? "\n" : escaped === "t" ? "\t" : (escaped ?? "");
+            i++;
+        }
+        else if (quote === "'" && ch === "'" && trimmed[i + 1] === "'") {
+            out += "'";
+            i++;
+        }
+        else if (ch === quote) {
+            return out;
+        }
+        else {
+            out += ch ?? "";
+        }
+    }
+    return undefined;
+}
+/** Splits a flow-list body on commas that sit outside quotes. */
+function splitFlowList(inner) {
+    const items = [];
+    let current = "";
+    let quote;
+    for (const ch of inner) {
+        if (quote !== undefined) {
+            current += ch;
+            if (ch === quote)
+                quote = undefined;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+        }
+        else if (ch === ",") {
+            items.push(current);
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+    }
+    items.push(current);
+    return items.map((item) => item.trim()).filter((item) => item !== "");
+}
+/**
+ * Parses the `---`-delimited frontmatter at the top of `content`. Returns a
+ * structured failure (never throws) when there is no block or it is never
+ * closed; lines it cannot interpret inside an otherwise valid block are
+ * reported in `problems`.
+ */
+export function parseFrontmatter(content) {
+    const lines = content.replace(/\r\n/g, "\n").split("\n");
+    if (lines[0]?.trimEnd() !== "---") {
+        return {
+            ok: false,
+            error: "no frontmatter block (the file must start with `---`)",
+        };
+    }
+    const end = lines.findIndex((line, index) => index > 0 && line.trimEnd() === "---");
+    if (end === -1) {
+        return {
+            ok: false,
+            error: "frontmatter block is never closed with a `---` line",
+        };
+    }
+    const block = lines.slice(1, end);
+    const body = lines.slice(end + 1).join("\n");
+    const fields = new Map();
+    const problems = [];
+    let i = 0;
+    while (i < block.length) {
+        const line = block[i] ?? "";
+        if (line.trim() === "" || line.trimStart().startsWith("#")) {
+            i++;
+            continue;
+        }
+        const match = KEY_LINE.exec(line);
+        if (match?.[1] === undefined) {
+            problems.push(`unparseable frontmatter line: ${line.trim()}`);
+            i++;
+            continue;
+        }
+        const key = match[1];
+        const rest = (match[2] ?? "").trim();
+        const continuation = [];
+        let j = i + 1;
+        while (j < block.length) {
+            const next = block[j] ?? "";
+            if (next.trim() === "" || /^\s/.test(next) || /^-(\s|$)/.test(next)) {
+                continuation.push(next);
+                j++;
+            }
+            else {
+                break;
+            }
+        }
+        i = j;
+        if (fields.has(key)) {
+            problems.push(`duplicate frontmatter key: ${key}`);
+        }
+        const blockScalar = BLOCK_SCALAR.exec(rest);
+        if (blockScalar !== null) {
+            const dedented = dedent(continuation);
+            const text = blockScalar[1] === ">"
+                ? foldBlockScalar(dedented)
+                : dedented.join("\n");
+            fields.set(key, text.trim());
+            continue;
+        }
+        if (rest === "") {
+            const items = continuation
+                .filter((entry) => /^\s*-(\s|$)/.test(entry))
+                .map((entry) => unquote(entry.replace(/^\s*-\s*/, "")) ?? "")
+                .filter((item) => item !== "");
+            fields.set(key, items.length > 0 ? items : "");
+            continue;
+        }
+        const joined = [rest, ...continuation.map((entry) => entry.trim())]
+            .filter((part) => part !== "")
+            .join(" ");
+        if (rest.startsWith("[")) {
+            if (!joined.trimEnd().endsWith("]")) {
+                problems.push(`unterminated flow list for key: ${key}`);
+                fields.set(key, "");
+                continue;
+            }
+            const inner = joined.trim().slice(1, -1);
+            fields.set(key, splitFlowList(inner).map((item) => unquote(item) ?? item));
+            continue;
+        }
+        const scalar = unquote(joined);
+        if (scalar === undefined) {
+            problems.push(`unterminated quoted string for key: ${key}`);
+            fields.set(key, "");
+        }
+        else {
+            fields.set(key, scalar);
+        }
+    }
+    return { ok: true, fields, body, problems };
+}
+/** A field as one string -- a list is joined with `, `. `undefined` when absent. */
+export function fieldText(fields, key) {
+    const value = fields.get(key);
+    return Array.isArray(value) ? value.join(", ") : value;
+}
+/** A field as a list -- a non-empty scalar becomes a one-item list. `undefined` when absent. */
+export function fieldList(fields, key) {
+    const value = fields.get(key);
+    if (value === undefined)
+        return undefined;
+    if (Array.isArray(value))
+        return value;
+    return value === "" ? [] : [value];
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/harness/grade.d.ts

@@ -0,0 +1,4 @@
+import type { HarnessGrade } from "./types.js";
+/** Runs every rule over the harness rooted at `rootDir` and tallies the result. */
+export declare function gradeHarness(rootDir: string): HarnessGrade;
+//# sourceMappingURL=grade.d.ts.map

package/dist/harness/grade.js

@@ -0,0 +1,105 @@
+/**
+ * Grades a project's Claude Code harness. `gradeHarness` reads the `.claude/`
+ * tree and `CLAUDE.md` once into a `HarnessSnapshot`, then runs every rule in
+ * `rules.ts` over it. Offline and read-only -- safe to point at an adopted
+ * project.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readJsoncFile } from "../jsonc.js";
+import { walkBounded } from "../survey/fs-walk.js";
+import { RULES } from "./rules.js";
+import { HARNESS_CATEGORIES } from "./types.js";
+const PROJECT_WALK_DEPTH = 8;
+function readText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function readSettings(path) {
+    if (!existsSync(path)) {
+        return { present: false, error: undefined, parsed: undefined };
+    }
+    const result = readJsoncFile(path);
+    return result.ok
+        ? { present: true, error: undefined, parsed: result.value }
+        : { present: true, error: result.error, parsed: undefined };
+}
+function loadSnapshot(root) {
+    const entries = walkBounded(root, PROJECT_WALK_DEPTH);
+    const claudeEntries = entries.filter((entry) => entry.relPath.startsWith(".claude/"));
+    const readEach = (pattern, strip) => new Map(claudeEntries
+        .filter((entry) => !entry.isDirectory && pattern.test(entry.relPath))
+        .map((entry) => [
+        entry.relPath.slice(strip.length),
+        readText(entry.path) ?? "",
+    ]));
+    const skills = claudeEntries
+        .filter((entry) => entry.isDirectory && /^\.claude\/skills\/[^/]+$/.test(entry.relPath))
+        .map((dir) => {
+        const prefix = `${dir.relPath}/`;
+        const files = claudeEntries
+            .filter((entry) => !entry.isDirectory && entry.relPath.startsWith(prefix))
+            .map((entry) => entry.relPath.slice(prefix.length));
+        return {
+            name: dir.relPath.slice(".claude/skills/".length),
+            skillMd: files.includes("SKILL.md")
+                ? readText(join(dir.path, "SKILL.md"))
+                : undefined,
+            files,
+        };
+    });
+    const settingsLocalResult = readJsoncFile(join(root, ".claude", "settings.local.json"));
+    return {
+        settings: readSettings(join(root, ".claude", "settings.json")),
+        settingsLocal: settingsLocalResult.ok
+            ? settingsLocalResult.value
+            : undefined,
+        hooks: readEach(/^\.claude\/hooks\/[^/]+$/, ".claude/hooks/"),
+        agents: readEach(/^\.claude\/agents\/[^/]+\.md$/, ".claude/agents/"),
+        skills,
+        rules: readEach(/^\.claude\/rules\/[^/]+\.md$/, ".claude/rules/"),
+        claudeMd: readText(join(root, "CLAUDE.md")),
+        claudeTree: new Set(claudeEntries.map((entry) => entry.relPath)),
+        projectFiles: entries
+            .filter((entry) => !entry.isDirectory)
+            .map((entry) => entry.relPath),
+    };
+}
+function emptyTally() {
+    return { checked: 0, failed: 0 };
+}
+/** Runs every rule over the harness rooted at `rootDir` and tallies the result. */
+export function gradeHarness(rootDir) {
+    const snapshot = loadSnapshot(rootDir);
+    const findings = [];
+    const structural = emptyTally();
+    const rubric = Object.fromEntries(HARNESS_CATEGORIES.map((category) => [category, emptyTally()]));
+    for (const rule of RULES) {
+        const result = rule.check(snapshot);
+        const tally = rule.level === "structural" ? structural : rubric[rule.category];
+        tally.checked += result.checked;
+        tally.failed += result.failures.length;
+        for (const failure of result.failures) {
+            findings.push({
+                ruleId: rule.id,
+                level: rule.level,
+                category: rule.category,
+                subject: failure.subject,
+                message: failure.message,
+            });
+        }
+    }
+    const rubricChecked = Object.values(rubric).reduce((sum, tally) => sum + tally.checked, 0);
+    const rubricFailed = Object.values(rubric).reduce((sum, tally) => sum + tally.failed, 0);
+    return {
+        findings,
+        structural,
+        rubric,
+        rubricScore: rubricChecked === 0 ? 1 : 1 - rubricFailed / rubricChecked,
+    };
+}
+//# sourceMappingURL=grade.js.map

package/dist/harness/rules.d.ts

@@ -0,0 +1,55 @@
+import type { HarnessCategory, RuleLevel } from "./types.js";
+export interface SkillSnapshot {
+    /** The skill's directory name. */
+    name: string;
+    /** `SKILL.md`'s text, or `undefined` when the file is missing. */
+    skillMd: string | undefined;
+    /** Every file under the skill directory, relative to it. */
+    files: string[];
+}
+export interface HarnessSnapshot {
+    settings: {
+        present: boolean;
+        error: string | undefined;
+        parsed: unknown;
+    };
+    /** `.claude/settings.local.json`, parsed, or `undefined` when absent/unparseable. */
+    settingsLocal: unknown;
+    /** Hook filename to source text. */
+    hooks: Map<string, string>;
+    /** Agent filename (with `.md`) to text. */
+    agents: Map<string, string>;
+    skills: SkillSnapshot[];
+    /** Rule filename (with `.md`) to text. */
+    rules: Map<string, string>;
+    claudeMd: string | undefined;
+    /** Every file and directory under `.claude/`, as project-relative paths. */
+    claudeTree: Set<string>;
+    /** Every project file (bounded walk), as project-relative paths. */
+    projectFiles: string[];
+}
+interface RuleFailure {
+    subject: string;
+    message: string;
+}
+interface RuleResult {
+    /** How many subjects the rule examined -- the denominator of the rubric score. */
+    checked: number;
+    failures: RuleFailure[];
+}
+export interface HarnessRule {
+    id: string;
+    level: RuleLevel;
+    category: HarnessCategory;
+    check: (snapshot: HarnessSnapshot) => RuleResult;
+}
+/**
+ * Model ids and aliases considered current. Bump alongside the
+ * `harness-guidance` refresh sweep; `templates/core/bin/lib/harness-rules.mjs`
+ * carries the same list and the parity test keeps the two equal.
+ */
+export declare const CURRENT_MODELS: readonly string[];
+/** Every rule, structural first. Order is the order findings are reported in. */
+export declare const RULES: readonly HarnessRule[];
+export {};
+//# sourceMappingURL=rules.d.ts.map