@freetesh/canon 0.0.0-stage → 0.16.0

package/cli/dist/checks/context-size.js

@@ -0,0 +1,46 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { REMOVED_WIKI_FOLDERS as REMOVED_FOLDERS } from "../config/schema.js";
+import { wikiPages } from "./wiki-frontmatter.js";
+// Every line here is read by an agent on every task; a cap keeps .context to what it would get wrong without.
+const MAX_LINES = { page: 60, decision: 30, readme: 30, tasks: 100 };
+const DATED_NAME = /^\d{4}-\d{2}-\d{2}-/;
+const lineCount = (repo, file) => readFileSync(join(repo, file), "utf8").trimEnd().split("\n").length;
+export const contextSize = {
+    id: "context-size",
+    module: "docs",
+    description: "pages, decisions, README.md and tasks.md stay under their line caps; decisions are one file per topic; no flow pages",
+    run({ repo }) {
+        const findings = [];
+        const warn = (file, message) => findings.push({ check: "context-size", level: "warn", file, message });
+        const overCap = (file, cap) => {
+            const lines = lineCount(repo, file);
+            if (lines > cap)
+                warn(file, `${lines} lines, cap ${cap} — cut what code, designs or git already say`);
+        };
+        for (const [folder, why] of Object.entries(REMOVED_FOLDERS)) {
+            if (existsSync(join(repo, ".context/wiki", folder)))
+                warn(`.context/wiki/${folder}`, `${folder}/ is gone: ${why}`);
+        }
+        for (const file of wikiPages(repo)) {
+            const folder = file.split("/")[2];
+            if (folder === "synthesis" || folder in REMOVED_FOLDERS)
+                continue;
+            if (folder === "decisions" && DATED_NAME.test(basename(file))) {
+                warn(file, "name a decision by topic and edit it in place — git keeps the history");
+            }
+            overCap(file, folder === "decisions" ? MAX_LINES.decision : MAX_LINES.page);
+        }
+        const readme = ".context/README.md";
+        const tasks = ".context/tasks.md";
+        if (existsSync(join(repo, readme)))
+            overCap(readme, MAX_LINES.readme);
+        if (existsSync(join(repo, tasks))) {
+            overCap(tasks, MAX_LINES.tasks);
+            if (/^## (Done|Session Notes)\b/m.test(readFileSync(join(repo, tasks), "utf8"))) {
+                warn(tasks, "tasks.md holds only open work — delete done tasks and session notes; the commits record them");
+            }
+        }
+        return findings;
+    },
+};

package/cli/dist/checks/features.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from "./types.ts";
+export declare const features: Check;

package/cli/dist/checks/features.js

@@ -0,0 +1,38 @@
+import { readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { listFiles } from "../lib/files.js";
+import { parseFrontmatter } from "../lib/frontmatter.js";
+const TYPES = ["feature", "experiment", "chore", "platform"];
+const STATUSES = ["planned", "building", "shipped", "shelved", "superseded"];
+// A chore or a platform change ships with nothing a user reads; a feature that never shipped keeps its target release.
+const NEEDS_STORE_COPY = ["feature", "experiment"];
+const NEVER_SHIPPED = ["shelved", "superseded"];
+const STORE_COPY = /^## Store copy[ \t]*\n([\s\S]*?)(?=^## |(?![\s\S]))/m;
+export const features = {
+    id: "features",
+    module: "docs",
+    description: "each features/ page has id, type and status from their sets; a released feature has its Store copy blockquote (the What's New text)",
+    run({ repo }) {
+        const pages = listFiles(repo, ".context/features", (name) => /^\d{4}-.+\.md$/.test(name));
+        return pages.flatMap((file) => {
+            const findings = [];
+            const add = (message) => findings.push({ check: "features", level: "error", file, message });
+            const { data, body } = parseFrontmatter(readFileSync(join(repo, file), "utf8"));
+            if (!data)
+                return [{ check: "features", level: "error", file, message: `no frontmatter (${basename(file)})` }];
+            for (const field of ["id", "type", "status"])
+                if (!data[field])
+                    add(`missing ${field}`);
+            if (data.type && !TYPES.includes(String(data.type)))
+                add(`type ${data.type} is not one of ${TYPES.join(", ")}`);
+            if (data.status && !STATUSES.includes(String(data.status)))
+                add(`status ${data.status} is not one of ${STATUSES.join(", ")}`);
+            const released = /\d+\.\d+\.\d+/.test(String(data.release ?? "")) && !NEVER_SHIPPED.includes(String(data.status));
+            const copy = STORE_COPY.exec(body.replace(/<!--[\s\S]*?-->/g, ""));
+            if (released && NEEDS_STORE_COPY.includes(String(data.type)) && !(copy && /^>[ \t]*\S/m.test(copy[1]))) {
+                add(`ships in ${data.release} with no "> …" line under ## Store copy`);
+            }
+            return findings;
+        });
+    },
+};

package/cli/dist/checks/index.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from "./types.ts";
+export declare const ALL_CHECKS: Check[];

package/cli/dist/checks/index.js

@@ -0,0 +1,34 @@
+import { architecture } from "./architecture.js";
+import { canonicalValues } from "./canonical-values.js";
+import { contextLayout } from "./context-layout.js";
+import { contextSize } from "./context-size.js";
+import { staleCopies } from "./stale-copies.js";
+import { standardsCopies } from "./standards-copies.js";
+import { commandChecks } from "./commands.js";
+import { features } from "./features.js";
+import { listing } from "./listing.js";
+import { metricsDefinitions } from "./metrics-definitions.js";
+import { pipeline } from "./pipeline.js";
+import { refs } from "./refs.js";
+import { sharedFiles } from "./shared-files.js";
+import { sources } from "./sources.js";
+import { tasks } from "./tasks.js";
+import { wikiFrontmatter } from "./wiki-frontmatter.js";
+export const ALL_CHECKS = [
+    contextLayout,
+    wikiFrontmatter,
+    contextSize,
+    tasks,
+    features,
+    listing,
+    canonicalValues,
+    standardsCopies,
+    sharedFiles,
+    refs,
+    staleCopies,
+    architecture,
+    metricsDefinitions,
+    sources,
+    pipeline,
+    commandChecks,
+];

package/cli/dist/checks/listing.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from "./types.ts";
+export declare const listing: Check;

package/cli/dist/checks/listing.js

@@ -0,0 +1,51 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { listFiles } from "../lib/files.js";
+const LISTING = ".context/listing";
+// supply and deliver treat every folder in metadata/ as a locale, so a stray one aborts the upload.
+const NOT_LOCALES = ["review_information", "trade_representative_contact_information", "app_clip_review_information"];
+const LOCALE = /^[a-z]{2,3}(-([A-Za-z]{2}|[A-Za-z]{4}))?$/;
+const PLAY_TEXT = ["title.txt", "short_description.txt", "full_description.txt"];
+const PLAY_IMAGE_FOLDERS = ["phoneScreenshots", "sevenInchScreenshots", "tenInchScreenshots", "tvScreenshots", "wearScreenshots"];
+const folders = (path) => (existsSync(path) ? readdirSync(path, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name) : []);
+export const listing = {
+    id: "listing",
+    module: "listing",
+    description: "listing/ is fastlane's tree: metadata/ per store, locale folders only, Play's three text files, fastlane image folders, zero-padded screenshots",
+    run({ repo }) {
+        const root = join(repo, LISTING);
+        if (!existsSync(root))
+            return [];
+        const findings = [];
+        const add = (file, message) => findings.push({ check: "listing", level: "error", file, message });
+        for (const store of ["android", "ios"]) {
+            if (!existsSync(join(root, store)))
+                continue;
+            const metadata = join(root, store, "metadata");
+            if (!existsSync(metadata)) {
+                add(`${LISTING}/${store}/`, "no metadata/ folder");
+                continue;
+            }
+            for (const name of folders(metadata)) {
+                if (!NOT_LOCALES.includes(name) && !LOCALE.test(name))
+                    add(`${LISTING}/${store}/metadata/${name}`, "not a locale — fastlane would upload it as one");
+            }
+        }
+        for (const locale of folders(join(root, "android", "metadata"))) {
+            const at = `${LISTING}/android/metadata/${locale}`;
+            for (const file of PLAY_TEXT)
+                if (!existsSync(join(repo, at, file)))
+                    add(`${at}/${file}`, "missing");
+            for (const name of folders(join(repo, at, "images"))) {
+                if (!PLAY_IMAGE_FOLDERS.includes(name))
+                    add(`${at}/images/${name}`, "not a fastlane image folder");
+            }
+        }
+        // Play ships screenshots in file-name order, so `2-` sorts after `10-`.
+        for (const file of listFiles(repo, LISTING, (name) => name.endsWith(".png"))) {
+            if (/[Ss]creenshots\//.test(file) && /\/\d-[^/]*$/.test(file))
+                add(file, "unpadded screenshot number — name it NN-<screen>.png");
+        }
+        return findings;
+    },
+};

package/cli/dist/checks/metrics-definitions.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from "./types.ts";
+export declare const metricsDefinitions: Check;

package/cli/dist/checks/metrics-definitions.js

@@ -0,0 +1,14 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+const DEFINITIONS = ".context/metrics/definitions.yml";
+export const metricsDefinitions = {
+    id: "metrics-definitions",
+    module: "metrics",
+    description: "metrics/definitions.yml names the numbers the weigh gate measures value against",
+    run({ repo }) {
+        if (existsSync(join(repo, DEFINITIONS)))
+            return [];
+        // A warning: most products turn metrics on before they define a single number.
+        return [{ check: "metrics-definitions", level: "warn", file: DEFINITIONS, message: "no metric definitions — the weigh gate cannot name the metric a request moves" }];
+    },
+};

package/cli/dist/checks/pipeline.d.ts

@@ -0,0 +1,8 @@
+import type { Check } from "./types.ts";
+/**
+ * Stages run in the order canon.yaml lists them. A stage has started once one
+ * of its `done` paths exists; a gated stage must be approved before any later
+ * stage starts. Each unapproved gate is reported once, at the first later
+ * stage that started.
+ */
+export declare const pipeline: Check;

package/cli/dist/checks/pipeline.js

@@ -0,0 +1,34 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { readApprovals } from "../pipeline.js";
+/**
+ * Stages run in the order canon.yaml lists them. A stage has started once one
+ * of its `done` paths exists; a gated stage must be approved before any later
+ * stage starts. Each unapproved gate is reported once, at the first later
+ * stage that started.
+ */
+export const pipeline = {
+    id: "pipeline",
+    module: null,
+    description: "no stage starts before every earlier gate is approved",
+    run({ repo, config }) {
+        const approved = new Set(readApprovals(repo).map((approval) => approval.stage));
+        const startedAt = config.pipeline.map((stage) => stage.done.find((path) => existsSync(join(repo, path))));
+        return config.pipeline.flatMap((gate, index) => {
+            if (!gate.gate || approved.has(gate.id))
+                return [];
+            const later = config.pipeline.findIndex((_, i) => i > index && startedAt[i] !== undefined);
+            if (later === -1)
+                return [];
+            const stage = config.pipeline[later];
+            return [
+                {
+                    check: "pipeline",
+                    level: "error",
+                    file: startedAt[later],
+                    message: `stage "${stage.id}" started before gate "${gate.id}" was approved — review ${gate.id}, then a person runs \`canon approve ${gate.id}\``,
+                },
+            ];
+        });
+    },
+};

package/cli/dist/checks/refs.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from "./types.ts";
+export declare const refs: Check;

package/cli/dist/checks/refs.js

@@ -0,0 +1,92 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join, normalize } from "node:path";
+import { usedCopies } from "./shared-files.js";
+// A `.context/` path not preceded by something that makes it part of a longer one (another
+// product's, an absolute path, a URL). A leading `./` means "beside this file".
+const PATH = /(?<![\w/~.-])(\.\/)?(\.context\/[\w./@+-]*)/g;
+const PLACEHOLDER = /[<{*[$]|YYYY|NNNN/;
+const LINK = /\[\[([^\]|#]+)(?:[|#][^\]]*)?\]\]/g;
+// A line reading a path out of git history names it as it was.
+const FROM_HISTORY = /git (show|checkout|log|diff|restore)\b/;
+// Dated records keep a path as it was on the day.
+const DATED = /(^|\/)CHANGELOG\.md$|^\.context\/ops\/incidents\//;
+const BINARY = /\.(png|jpe?g|gif|webp|ico|icns|mp4|mov|pdf|zip|aab|apk|jks|keystore|p8|p12|ttf|otf|woff2?|lock|snap|sqlite|db|bin)$|(^|\/)pnpm-lock\.yaml$/i;
+const FEATURE_FILE = /^\.context\/features\/(\d{4})-[^/]+\.md$/;
+// A pipeline stage's `done:` paths name what will exist once that stage starts.
+const STAGE_DONE = /^\s*-\s*\{[^}]*\bdone:\s*\[/;
+function git(repo, args) {
+    const result = spawnSync("git", ["-C", repo, ...args], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    return { status: result.status ?? 1, stdout: result.stdout ?? "" };
+}
+/** The part of a path that names something real: cut back to the last whole folder before a placeholder. */
+function literalPart(token, restOfLine) {
+    let path = token.replace(/[.,;:]+$/, "");
+    const cut = PLACEHOLDER.exec(path);
+    if (cut || PLACEHOLDER.test(restOfLine.slice(0, 1))) {
+        path = cut ? path.slice(0, cut.index) : path;
+        path = path.slice(0, path.lastIndexOf("/") + 1);
+    }
+    return path.replace(/^[./]+|[./]+$/g, "") === "context" ? null : path;
+}
+export const refs = {
+    id: "refs",
+    // A module, not always on: a repo whose docs describe other repos' .context/ (a tool, a portfolio) does not use it.
+    module: "refs",
+    description: "every .context/ path a tracked file names exists; a [[link]] names a page (a link to a page not yet written is a note)",
+    run({ repo, config }) {
+        const listed = git(repo, ["ls-files", "-z"]);
+        if (listed.status !== 0)
+            return [];
+        const files = listed.stdout.split("\0").filter((file) => file && !BINARY.test(file));
+        // A copy of the source repo's file carries the source's paths; the product cannot edit it.
+        const copied = new Set(usedCopies(config).map((pair) => pair.to));
+        const pages = new Set(files.filter((f) => f.startsWith(".context/wiki/") && f.endsWith(".md")).map((f) => basename(f, ".md")));
+        const features = new Set(files.flatMap((f) => (FEATURE_FILE.exec(f) ? [`FEAT-${FEATURE_FILE.exec(f)[1]}`] : [])));
+        const resolves = (target) => pages.has(target) || features.has(target) || existsSync(join(repo, ".context", `${target}.md`));
+        const exists = new Map();
+        const present = (path) => {
+            if (!exists.has(path)) {
+                exists.set(path, existsSync(join(repo, path)) || git(repo, ["check-ignore", "-q", path]).status === 0);
+            }
+            return exists.get(path);
+        };
+        const findings = [];
+        for (const file of files) {
+            if (copied.has(file))
+                continue;
+            let text;
+            try {
+                text = readFileSync(join(repo, file), "utf8");
+            }
+            catch {
+                continue; // deleted in the working tree, or a submodule
+            }
+            const dated = DATED.test(file);
+            const links = file.startsWith(".context/") && file.endsWith(".md");
+            text.split("\n").forEach((line, index) => {
+                const at = `${file}:${index + 1}`;
+                const future = file === ".claude/canon.yaml" && STAGE_DONE.test(line);
+                if (!dated && !future && line.includes(".context/") && !FROM_HISTORY.test(line)) {
+                    for (const match of line.matchAll(PATH)) {
+                        let path = literalPart(match[2], line.slice(match.index + match[0].length));
+                        if (path === null)
+                            continue;
+                        if (match[1])
+                            path = normalize(join(dirname(file), path)) + (path.endsWith("/") ? "/" : "");
+                        if (!present(path))
+                            findings.push({ check: "refs", level: "error", file: at, message: `${path} does not exist` });
+                    }
+                }
+                if (links && line.includes("[[")) {
+                    for (const match of line.matchAll(LINK)) {
+                        const target = match[1].trim();
+                        if (!resolves(target))
+                            findings.push({ check: "refs", level: "warn", file: at, message: `[[${target}]] names no page yet` });
+                    }
+                }
+            });
+        }
+        return findings;
+    },
+};

package/cli/dist/checks/shared-files.d.ts

@@ -0,0 +1,22 @@
+import type { Config } from "../config/schema.ts";
+import type { Check } from "./types.ts";
+export interface Pair {
+    set: string;
+    from: string;
+    to: string;
+    named: boolean;
+    until?: string;
+}
+/** Every file of every set the product uses, as source → product paths. */
+export declare function usedCopies(config: Config): Pair[];
+export interface CopyState {
+    pair: Pair;
+    state: "same" | "drift" | "missing" | "unknown-set" | "no-source" | "unnamed";
+    /** What the product file should hold; set for a drift --sync can repair. */
+    want?: string;
+}
+/** Compares every file of every set the product uses with the source repo. */
+export declare function compareCopies(repo: string, config: Config): CopyState[];
+/** Overwrites each drifted copy with the source's. Never adds a missing file. Returns the paths written. */
+export declare function syncCopies(repo: string, config: Config): string[];
+export declare const sharedFiles: Check;

package/cli/dist/checks/shared-files.js

@@ -0,0 +1,84 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { loadConfig } from "../config/load.js";
+// canon init writes the README heading `# .context — <Name>`; a product without a `name:` is read from it.
+const README_NAME = /^# \.context — (.+)$/m;
+const pairOf = (set, file) => typeof file === "string" ? { set, from: file, to: file, named: false } : { set, from: file.from, to: file.to ?? file.from, named: file.named ?? false, until: file.until };
+/** Every file of every set the product uses, as source → product paths. */
+export function usedCopies(config) {
+    return config.copies.use.flatMap((set) => (config.copies.sets[set] ?? []).map((file) => pairOf(set, file)));
+}
+function nameOf(repo, config) {
+    if (config.name)
+        return config.name;
+    const readme = join(repo, ".context", "README.md");
+    return existsSync(readme) ? README_NAME.exec(readFileSync(readme, "utf8"))?.[1]?.trim() : undefined;
+}
+function split(text, marker) {
+    const lines = text.split("\n");
+    const at = lines.findIndex((line) => line.includes(marker));
+    return at === -1 ? null : { shared: lines.slice(0, at).join("\n"), own: lines.slice(at).join("\n") };
+}
+/** Compares every file of every set the product uses with the source repo. */
+export function compareCopies(repo, config) {
+    const { source, sets, use } = config.copies;
+    if (use.length === 0 || !source || resolve(source) === resolve(repo))
+        return [];
+    const unknown = use.filter((set) => !sets[set]).map((set) => ({ pair: { set, from: "", to: "", named: false }, state: "unknown-set" }));
+    const productName = nameOf(repo, config);
+    const sourceName = nameOf(source, loadConfig(source).config);
+    return [
+        ...unknown,
+        ...usedCopies(config).map((pair) => {
+            const from = join(source, pair.from);
+            const to = join(repo, pair.to);
+            if (!existsSync(from))
+                return { pair, state: "no-source" };
+            if (!existsSync(to))
+                return { pair, state: "missing" };
+            if (pair.named && (!productName || !sourceName))
+                return { pair, state: "unnamed" };
+            const original = pair.named ? readFileSync(from, "utf8").replaceAll(sourceName, productName) : readFileSync(from, "utf8");
+            const current = readFileSync(to, "utf8");
+            if (!pair.until)
+                return original === current ? { pair, state: "same" } : { pair, state: "drift", want: original };
+            const theirs = split(original, pair.until);
+            const ours = split(current, pair.until);
+            if (theirs && ours && theirs.shared === ours.shared)
+                return { pair, state: "same" };
+            // Without the marker the product's own part cannot be told from the shared one, so nothing is written.
+            return { pair, state: "drift", want: theirs && ours ? `${theirs.shared}\n${ours.own}` : undefined };
+        }),
+    ];
+}
+/** Overwrites each drifted copy with the source's. Never adds a missing file. Returns the paths written. */
+export function syncCopies(repo, config) {
+    return compareCopies(repo, config).flatMap(({ pair, state, want }) => {
+        if (state !== "drift" || want === undefined)
+            return [];
+        writeFileSync(join(repo, pair.to), want);
+        return [pair.to];
+    });
+}
+export const sharedFiles = {
+    id: "shared-files",
+    module: null,
+    description: "every file of every copies set the product uses exists and matches copies.source",
+    run({ repo, config }) {
+        const source = config.copies.source ? basename(config.copies.source) : "copies.source";
+        return compareCopies(repo, config).flatMap(({ pair, state }) => {
+            const finding = (file, message) => [{ check: "shared-files", level: "error", file, message }];
+            if (state === "unknown-set")
+                return finding(".claude/canon.yaml", `copies.use names ${pair.set}, which no copies.sets defines`);
+            if (state === "no-source")
+                return finding(pair.to, `${source} has no ${pair.from} (set ${pair.set})`);
+            if (state === "missing")
+                return finding(pair.to, `missing — set ${pair.set} is in use; copy it from ${source}`);
+            if (state === "unnamed")
+                return finding(pair.to, "no product name to compare with — set name: in canon.yaml");
+            if (state === "drift")
+                return finding(pair.to, `differs from ${source}${pair.until ? " above the shared block's end" : ""} — \`canon copies --sync\` copies it`);
+            return [];
+        });
+    },
+};

package/cli/dist/checks/sources.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from "./types.ts";
+export declare const sources: Check;

package/cli/dist/checks/sources.js

@@ -0,0 +1,40 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseFrontmatter } from "../lib/frontmatter.js";
+import { wikiPages } from "./wiki-frontmatter.js";
+// canon has no connectors: a source page must say which MCP server, skill or CLI
+// reads it, or that a person reads it by hand (`manual:`), or the weigh gate
+// cannot turn a claim into a fact.
+const ACCESS = /^(mcp|skill|cli|manual):\s*(\S+)/;
+const HOW_TO_QUERY = /^## How to query\s*$/m;
+function accessValue(body, id) {
+    const row = body.split("\n").find((line) => line.replace(/\s/g, "").startsWith(`|${id}.ACCESS|`));
+    return row ? (row.split("|")[2]?.trim() ?? "") : null;
+}
+export const sources = {
+    id: "sources",
+    module: "docs",
+    description: "each SOURCE.* entity page says how to read it (mcp, skill, manual, or a cli in doctor.tools) and has a How to query section",
+    run({ repo, config }) {
+        const tools = new Set(config.doctor.tools.map((tool) => tool.tool));
+        return wikiPages(repo).flatMap((file) => {
+            const { data, body } = parseFrontmatter(readFileSync(join(repo, file), "utf8"));
+            const id = String(data?.id ?? "");
+            if (!file.startsWith(".context/wiki/entities/") || !id.startsWith("SOURCE."))
+                return [];
+            const findings = [];
+            const add = (message) => findings.push({ check: "sources", level: "error", file, message });
+            if (!HOW_TO_QUERY.test(body))
+                add("no `## How to query` section");
+            const access = accessValue(body, id);
+            const match = access === null ? null : ACCESS.exec(access);
+            if (access === null)
+                add(`no ${id}.ACCESS row — say how to read it`);
+            else if (!match)
+                add(`${id}.ACCESS is "${access}" — write mcp: <server>, skill: <name>, cli: <command> or manual: <where>`);
+            else if (match[1] === "cli" && !tools.has(match[2]))
+                add(`cli ${match[2]} is not in doctor.tools — canon doctor cannot report it missing`);
+            return findings;
+        });
+    },
+};

package/cli/dist/checks/stale-copies.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from "./types.ts";
+export declare const staleCopies: Check;

package/cli/dist/checks/stale-copies.js

@@ -0,0 +1,18 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+// Instruction files for agents other than Claude Code. They are copies of
+// AGENTS.md that nobody reads, so they only drift.
+const OTHER_AGENT_FILES = [".github/copilot-instructions.md", ".cursorrules", ".windsurfrules"];
+export const staleCopies = {
+    id: "stale-copies",
+    module: null,
+    description: "no instruction files for agents that are not used (Copilot, Cursor, Windsurf)",
+    run({ repo }) {
+        return OTHER_AGENT_FILES.filter((file) => existsSync(join(repo, file))).map((file) => ({
+            check: "stale-copies",
+            level: "warn",
+            file,
+            message: "instructions for an agent not in use — delete, Claude reads AGENTS.md",
+        }));
+    },
+};

package/cli/dist/checks/standards-copies.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from "./types.ts";
+export declare const standardsCopies: Check;

package/cli/dist/checks/standards-copies.js

@@ -0,0 +1,57 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+// Fraction of a shared standard's lines that must appear in a product file
+// before it counts as a copy rather than a reference.
+const COPY_THRESHOLD = 0.6;
+const STANDARD_COPIES = [{ file: ".context/wiki/CLAUDE.md", standard: "standards/wiki-schema.md" }];
+function meaningfulLines(text) {
+    return new Set(text
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith("<!--")));
+}
+function sharedFraction(standard, candidate) {
+    const wanted = meaningfulLines(standard);
+    const present = meaningfulLines(candidate);
+    const shared = [...wanted].filter((line) => present.has(line)).length;
+    return wanted.size === 0 ? 0 : shared / wanted.size;
+}
+export const standardsCopies = {
+    id: "standards-copies",
+    module: null,
+    description: "shared rules and skills come from canon, not from a copy in the product",
+    run({ repo, canonRoot }) {
+        const findings = [];
+        for (const { file, standard } of STANDARD_COPIES) {
+            const productFile = join(repo, file);
+            const standardFile = join(canonRoot, standard);
+            if (!existsSync(productFile) || !existsSync(standardFile))
+                continue;
+            const fraction = sharedFraction(readFileSync(standardFile, "utf8"), readFileSync(productFile, "utf8"));
+            if (fraction >= COPY_THRESHOLD) {
+                findings.push({
+                    check: "standards-copies",
+                    level: "warn",
+                    file,
+                    message: `${Math.round(fraction * 100)}% copy of canon ${standard} — replace with a pointer`,
+                });
+            }
+        }
+        const canonSkills = join(canonRoot, "skills");
+        const productSkills = join(repo, ".claude", "skills");
+        if (existsSync(canonSkills) && existsSync(productSkills)) {
+            const provided = new Set(readdirSync(canonSkills));
+            for (const skill of readdirSync(productSkills)) {
+                if (!provided.has(skill))
+                    continue;
+                findings.push({
+                    check: "standards-copies",
+                    level: "warn",
+                    file: `.claude/skills/${skill}`,
+                    message: `canon provides this as canon:${skill} — delete the product copy`,
+                });
+            }
+        }
+        return findings;
+    },
+};

package/cli/dist/checks/tasks.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from "./types.ts";
+export declare const tasks: Check;