@intentius/chant 0.124.12 → 0.124.14

package/dist/cli/commands/check-lexicon.js

@@ -0,0 +1,766 @@
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { join, basename } from "path";
+import { auditIntrinsics } from "./check-lexicon-intrinsics.js";
+import { checkExamplesBuild } from "./check-lexicon-examples.js";
+import { auditDocsClassification, auditDocsReachability } from "./check-lexicon-docs.js";
+import { auditMcpNames, lexiconNameFor } from "./check-lexicon-mcp.js";
+import { loadLexiconFromDir, registers, safeList } from "./check-lexicon-plugin.js";
+import { RULE_CATALOG } from "../../audit/catalog.js";
+// ── Helpers ──────────────────────────────────────────────────────────
+/** List .ts files in a directory, optionally excluding some basenames. */
+function listTsFiles(dir, exclude = []) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".ts") && !exclude.includes(f));
+}
+/** Recursively find files matching a predicate. */
+function findFiles(dir, predicate) {
+    if (!existsSync(dir))
+        return [];
+    const results = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+            results.push(...findFiles(join(dir, entry.name), predicate));
+        }
+        else if (predicate(entry.name)) {
+            results.push(join(dir, entry.name));
+        }
+    }
+    return results;
+}
+/** Read a file's content, returning empty string if missing. */
+/**
+ * Count the names in a validate.ts. Reads the entries of the exported
+ * REQUIRED_NAMES array; a lexicon with no such export falls back to counting
+ * quoted capitalised identifiers (digits allowed, e.g. K8sClusterReceiver).
+ */
+export function countRequiredNames(validateContent) {
+    const arr = validateContent.match(/export\s+const\s+REQUIRED_NAMES\b[^=]*=\s*\[([\s\S]*?)\]/);
+    const body = arr ? arr[1] : validateContent;
+    return (body.match(/["'][A-Z][A-Za-z0-9]*["']/g) || []).length;
+}
+function readOr(path) {
+    try {
+        return readFileSync(path, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+/** Count subdirectories in a directory, ignoring .gitkeep-only dirs. */
+function countSubdirs(dir) {
+    if (!existsSync(dir))
+        return 0;
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .filter((e) => {
+        const contents = readdirSync(join(dir, e.name));
+        // Ignore directories that only contain .gitkeep
+        return contents.length > 0 && !(contents.length === 1 && contents[0] === ".gitkeep");
+    })
+        .length;
+}
+/**
+ * #1330 — gate on the plugin's own spec-coverage accounting.
+ *
+ * fountain's `coverage.test.ts` asserts `unaccountedKinds == []` in CI, but a
+ * lexicon-local test is a convention, not a check-lexicon contract — the same
+ * class of gap #1342 closed for LSP providers. `coverageReport()` gives core
+ * the one fact to gate on: which upstream spec kinds are neither modeled nor
+ * on the lexicon's exclusion list. A lexicon without the member passes
+ * vacuously, the same conditional shape as the docs-reachability and
+ * Diátaxis checks; a report that throws fails, for the same reason `safeList`
+ * treats a throw as worse than absence.
+ */
+export async function coverageReportCheck(plugin) {
+    const report = plugin?.coverageReport;
+    const hasReport = typeof report === "function";
+    let unaccounted = [];
+    let error;
+    if (hasReport) {
+        try {
+            unaccounted = (await report.call(plugin))?.unaccountedKinds ?? [];
+        }
+        catch (e) {
+            error = e instanceof Error ? e.message : String(e);
+        }
+    }
+    return {
+        name: "coverageReport() leaves no spec kind unaccounted",
+        tier: 1,
+        pass: !hasReport || (error === undefined && unaccounted.length === 0),
+        detail: error !== undefined
+            ? `threw: ${error}`
+            : unaccounted.length > 0
+                ? `${unaccounted.length} unaccounted: ${unaccounted.join(", ")}`
+                : hasReport
+                    ? "all spec kinds accounted for"
+                    : undefined,
+    };
+}
+/**
+ * #3104 — how many composites a lexicon ships.
+ *
+ * This counted every `.ts` file in `src/composites/` except `index.ts`, so
+ * `catalog.ts`, `catalog.test.ts`, `composites.test.ts` and helper modules all
+ * counted: otel reported "4 composite(s)" for `NodeAgent` alone. The same rule
+ * as #1342 applies: a capability is what the plugin exposes, and a lexicon
+ * with composites exposes them through `composites()`, the catalog generated
+ * from its real exports (#2662). Ask that when it is there. Only a lexicon
+ * without it falls back to the files, and then not to tests, the catalog, the
+ * barrel or helper modules.
+ */
+export function countComposites(plugin, dir) {
+    if (registers(plugin, "composites")) {
+        const { items, error } = safeList(plugin.composites.bind(plugin));
+        if (error !== undefined)
+            return { count: 0, detail: `composites() threw: ${error}` };
+        const names = new Set(items.map((e) => e.name));
+        return { count: names.size, detail: `${names.size} composite(s) in composites()` };
+    }
+    const files = listTsFiles(join(dir, "src/composites"), ["index.ts", "catalog.ts", "helpers.ts", "shared.ts"])
+        .filter((f) => !f.endsWith(".test.ts") && !f.endsWith(".d.ts") && !f.endsWith("-helpers.ts"));
+    return {
+        count: files.length,
+        detail: `${files.length} composite file(s) in src/composites/; the plugin has no composites()`,
+    };
+}
+/**
+ * #2535 — a lexicon that supplies member kinds publishes them as data at a
+ * `./workspace-kinds` subpath (ws-031). The file must be JSON, validate as
+ * kind data, and ship in the package. A lexicon without the subpath passes
+ * vacuously, like `coverageReport()` above. The workspace module loads only
+ * here, when the check runs.
+ */
+export async function workspaceKindsCheck(dir) {
+    const { readPackageKinds, kindsFileShips } = await import("../../workspace/kinds.js");
+    const read = readPackageKinds(dir);
+    const problems = [...read.problems];
+    if (read.file && problems.length === 0 && !kindsFileShips(dir, read.file)) {
+        problems.push(`${basename(read.file)} is not covered by package.json "files", so the published package would not carry it`);
+    }
+    return {
+        name: "Any ./workspace-kinds subpath holds valid kind data",
+        tier: 1,
+        pass: problems.length === 0,
+        detail: problems.length > 0 ? problems.join("; ") : read.file ? `${read.kinds.length} kind(s): ${read.kinds.map((k) => k.name).join(", ")}` : undefined,
+    };
+}
+// ── Check runner ─────────────────────────────────────────────────────
+/**
+ * Run all completeness checks against a lexicon directory.
+ */
+export async function checkLexicon(dir) {
+    const items = [];
+    // ── Tier 1: Required ───────────────────────────────────────────
+    // #1342 — a capability is present when the plugin exposes it, not when a file
+    // with the right name sits on disk. The checks below used to be existence
+    // assertions, which is how helm shipped `src/lsp/completions.ts` and
+    // `src/lsp/hover.ts` (with tests) while registering neither provider, and
+    // passed every tier. `cli/lsp/server.ts` dispatches through the plugin
+    // members, so those files were unreachable in an editor.
+    const loaded = await loadLexiconFromDir(dir);
+    const plugin = loaded.plugin;
+    items.push({
+        name: "The package exports a LexiconPlugin",
+        tier: 1,
+        pass: plugin !== undefined,
+        detail: loaded.error ?? (loaded.entry ? `exported by ${basename(loaded.entry)}` : undefined),
+    });
+    const serializer = plugin?.serializer;
+    const serializerOk = typeof serializer?.name === "string" &&
+        typeof serializer?.rulePrefix === "string" &&
+        typeof serializer?.serialize === "function";
+    items.push({
+        name: "The plugin exposes a Serializer with a name and rule prefix",
+        tier: 1,
+        pass: serializerOk,
+        detail: serializerOk
+            ? `${String(serializer?.name)} (${String(serializer?.rulePrefix)})`
+            : plugin
+                ? "serializer is missing name, rulePrefix, or serialize"
+                : undefined,
+    });
+    const lintRules = safeList(plugin?.lintRules?.bind(plugin));
+    items.push({
+        name: "lintRules() returns at least 1 rule",
+        tier: 1,
+        pass: lintRules.items.length > 0,
+        detail: lintRules.error ? `threw: ${lintRules.error}` : `${lintRules.items.length} rule(s)`,
+    });
+    const postSynthChecks = safeList(plugin?.postSynthChecks?.bind(plugin));
+    items.push({
+        name: "postSynthChecks() returns at least 1 check",
+        tier: 1,
+        pass: postSynthChecks.items.length > 0,
+        detail: postSynthChecks.error
+            ? `threw: ${postSynthChecks.error}`
+            : `${postSynthChecks.items.length} check(s)`,
+    });
+    // #1349 — `rulePrefix` exists so ids do not collide when several lexicons are
+    // loaded together (forgejo wraps github's rules as `WFJ-GHA0xx` for exactly
+    // that reason), and it was checked by nothing. k8s shipped five `ARGO0xx`
+    // checks outside its declared `WK8`. Core's cross-cutting ids are exempt:
+    // they belong to core, not to whichever lexicon surfaces them.
+    const declaredPrefixes = [
+        typeof serializer?.rulePrefix === "string" ? serializer.rulePrefix : "",
+        ...(plugin?.serializer?.extraRulePrefixes ?? []),
+    ].filter((p) => p.length > 0);
+    const allRuleIds = [
+        ...lintRules.items.map((r) => r.id),
+        ...postSynthChecks.items.map((c) => c.id),
+    ].filter((id) => typeof id === "string");
+    const offPrefix = allRuleIds.filter((id) => !(id in RULE_CATALOG) && !declaredPrefixes.some((p) => id.startsWith(p)));
+    items.push({
+        name: "Every rule id starts with a declared rule prefix",
+        tier: 1,
+        pass: declaredPrefixes.length > 0 && offPrefix.length === 0,
+        detail: offPrefix.length > 0
+            ? `${offPrefix.length} outside ${declaredPrefixes.join("/")}: ${[...new Set(offPrefix)].slice(0, 6).join(", ")}`
+            : declaredPrefixes.length > 0
+                ? `${allRuleIds.length} id(s) under ${declaredPrefixes.join("/")}`
+                : "no rule prefix declared",
+    });
+    items.push({
+        name: "The plugin registers completionProvider",
+        tier: 1,
+        pass: registers(plugin, "completionProvider"),
+    });
+    items.push({
+        name: "The plugin registers hoverProvider",
+        tier: 1,
+        pass: registers(plugin, "hoverProvider"),
+    });
+    items.push({
+        name: "The plugin registers docs()",
+        tier: 1,
+        pass: registers(plugin, "docs"),
+    });
+    items.push({
+        name: "dist/manifest.json exists",
+        tier: 1,
+        pass: existsSync(join(dir, "dist/manifest.json")),
+    });
+    // chant #1067 — chantVersion was "optional, unchecked": a lexicon could
+    // declare (or omit) a core-version constraint and nothing failed. This
+    // does not validate compatibility against the running core version — that
+    // needs a live check at plugin-load time (a different tool: candidates are
+    // `loadPlugin`/`loadPlugins` in ../plugins.ts), which is a deliberate
+    // non-goal here (see PR description). It closes the narrower gap that the
+    // field can be silently absent or malformed in the shipped manifest.
+    const manifestJson = readOr(join(dir, "dist/manifest.json"));
+    let chantVersionOk = false;
+    let chantVersionDetail;
+    if (manifestJson) {
+        try {
+            const parsed = JSON.parse(manifestJson);
+            const cv = parsed.chantVersion;
+            chantVersionOk = typeof cv === "string" && /\d/.test(cv);
+            chantVersionDetail = chantVersionOk ? `chantVersion: ${cv}` : `chantVersion: ${JSON.stringify(cv)}`;
+        }
+        catch {
+            chantVersionDetail = "dist/manifest.json is not valid JSON";
+        }
+    }
+    else {
+        chantVersionDetail = "dist/manifest.json missing or unreadable";
+    }
+    items.push({
+        name: "dist/manifest.json declares a chantVersion",
+        tier: 1,
+        pass: chantVersionOk,
+        detail: chantVersionDetail,
+    });
+    // chant #1067 — packaging shape ("all 11 lexicons route exports['.'].default
+    // at ./src/index.ts and delete emitted JS in build") was real but
+    // unenforced; a lexicon shipping differently would break consumers
+    // silently. Cheap structural check on package.json, not a build execution.
+    const packageJsonRaw = readOr(join(dir, "package.json"));
+    let packagingOk = false;
+    let packagingDetail;
+    if (packageJsonRaw) {
+        try {
+            const pkg = JSON.parse(packageJsonRaw);
+            const defaultExport = pkg.exports?.["."]?.default;
+            const buildScript = pkg.scripts?.build ?? "";
+            const exportOk = defaultExport === "./src/index.ts";
+            const deletesEmittedJs = /-delete/.test(buildScript) && /\.js/.test(buildScript);
+            packagingOk = exportOk && deletesEmittedJs;
+            const problems = [];
+            if (!exportOk)
+                problems.push(`exports["."].default is ${JSON.stringify(defaultExport)}, expected "./src/index.ts"`);
+            if (!deletesEmittedJs)
+                problems.push(`build script doesn't delete emitted .js from dist/: ${JSON.stringify(buildScript)}`);
+            packagingDetail = problems.length > 0 ? problems.join("; ") : undefined;
+        }
+        catch {
+            packagingDetail = "package.json is not valid JSON";
+        }
+    }
+    else {
+        packagingDetail = "package.json missing or unreadable";
+    }
+    items.push({
+        name: 'package.json routes exports["."].default at ./src/index.ts and deletes emitted JS in build',
+        tier: 1,
+        pass: packagingOk,
+        detail: packagingDetail,
+    });
+    const exampleCount = countSubdirs(join(dir, "examples"));
+    items.push({
+        name: "At least 1 example in examples/",
+        tier: 1,
+        pass: exampleCount > 0,
+        detail: exampleCount > 0 ? `${exampleCount} example(s)` : undefined,
+    });
+    // chant #1067 — every shipped example must actually build. The prior
+    // checks only ever counted example directories; none tried to build one,
+    // so `lexicons/aws/examples/core-concepts` shipped with a discovery-time
+    // "Duplicate export name" error while this tool reported "All tier-1
+    // checks passed." chant #1400 — and the built output must pass the
+    // lexicon's own post-synth checks at error severity; three aws examples
+    // taught patterns (no TLS-only bucket policy, mutable ECR tags) the
+    // lexicon flags as errors. See ./check-lexicon-examples.ts.
+    const exampleBuilds = await checkExamplesBuild(dir);
+    const brokenExamples = exampleBuilds.filter((e) => !e.ok);
+    items.push({
+        name: "Every shipped example builds and passes its own post-synth checks",
+        tier: 1,
+        pass: brokenExamples.length === 0,
+        detail: brokenExamples.length > 0
+            ? brokenExamples.map((e) => `${e.example}: ${e.detail}`).join(" | ")
+            : exampleBuilds.length > 0
+                ? `${exampleBuilds.length} example(s) built`
+                : undefined,
+    });
+    // chant #1067 — foldability (isTag) is required and validated, not an
+    // optional flag nobody checks. #1039 shipped with it wrong in both
+    // directions (aws's Sub missing isTag; gitlab's reference() claiming
+    // isTag: true for a plain call) and nothing caught either half. See
+    // ./check-lexicon-intrinsics.ts for what "exported"/"matches" mean.
+    const intrinsicAudit = auditIntrinsics(dir);
+    const unexportedIntrinsics = intrinsicAudit.filter((i) => !i.exported);
+    items.push({
+        name: "Registered intrinsics are exported by the package",
+        tier: 1,
+        pass: unexportedIntrinsics.length === 0,
+        detail: unexportedIntrinsics.length > 0
+            ? unexportedIntrinsics.map((i) => i.detail).join(" | ")
+            : intrinsicAudit.length > 0
+                ? `${intrinsicAudit.length} intrinsic(s) checked`
+                : undefined,
+    });
+    const mismatchedIntrinsics = intrinsicAudit.filter((i) => !i.ok);
+    items.push({
+        name: "Registered intrinsics' isTag matches how they're authored",
+        tier: 1,
+        pass: mismatchedIntrinsics.length === 0,
+        detail: mismatchedIntrinsics.length > 0
+            ? mismatchedIntrinsics.map((i) => i.detail).join(" | ")
+            : intrinsicAudit.length > 0
+                ? `${intrinsicAudit.length} intrinsic(s) checked`
+                : undefined,
+    });
+    // chant #1044 — the call-form opt-in (`foldsAsCall`) admits a plain call
+    // into `fold()`, which has no general CallExpression case. Declaring it on
+    // a tagged template claims a form the intrinsic cannot be invoked in, so
+    // it fails here rather than being quietly ignored — the same reasoning as
+    // the isTag check above.
+    const badCallForm = intrinsicAudit.filter((i) => !i.callFormOk);
+    items.push({
+        name: "Registered intrinsics' foldsAsCall opt-in is only on plain calls",
+        tier: 1,
+        pass: badCallForm.length === 0,
+        detail: badCallForm.length > 0
+            ? badCallForm.map((i) => i.callFormDetail).join(" | ")
+            : intrinsicAudit.length > 0
+                ? `${intrinsicAudit.length} intrinsic(s) checked`
+                : undefined,
+    });
+    // #1341 — core namespaces MCP contributions, and so do the shared helpers and
+    // most lexicons, so the names agents actually saw were `gitlab:gitlab:diff`
+    // and `chant://azure/chant://lexicon/azure/catalog`. The check is on the
+    // registered name rather than the declared one: three authored forms are in
+    // use and all of them are fine, but only one registered shape is.
+    const mcpNames = await auditMcpNames(dir);
+    items.push({
+        name: "MCP tools and resources register under one well-formed namespace",
+        tier: 1,
+        pass: mcpNames.violations.length === 0,
+        detail: mcpNames.violations.length > 0
+            ? mcpNames.violations.join(" | ")
+            : mcpNames.loaded
+                ? `${mcpNames.checked} contribution(s) checked`
+                : "lexicon could not be loaded — not checked",
+    });
+    const hasPluginTest = findFiles(join(dir, "src"), (n) => n === "plugin.test.ts").length > 0;
+    items.push({
+        name: "plugin.test.ts exists",
+        tier: 1,
+        pass: hasPluginTest,
+    });
+    const hasSerializerTest = findFiles(join(dir, "src"), (n) => n === "serializer.test.ts").length > 0;
+    items.push({
+        name: "serializer.test.ts exists",
+        tier: 1,
+        pass: hasSerializerTest,
+    });
+    const mdxFiles = findFiles(join(dir, "docs"), (n) => n.endsWith(".mdx"));
+    items.push({
+        name: "At least 1 .mdx doc page",
+        tier: 1,
+        pass: mdxFiles.length > 0,
+        detail: mdxFiles.length > 0 ? `${mdxFiles.length} page(s)` : undefined,
+    });
+    // Counting pages says nothing about whether a reader can find them.
+    // Starlight has no auto-discovery, so a page missing from the sidebar is
+    // reachable only by direct URL (#1312).
+    const docsReach = auditDocsReachability(dir);
+    items.push({
+        name: "Every doc page is reachable from the sidebar",
+        tier: 1,
+        pass: !docsReach.hasSite || docsReach.unreachable.length === 0,
+        detail: docsReach.unreachable.length > 0
+            ? `${docsReach.unreachable.length} unreachable: ${docsReach.unreachable.join(", ")}`
+            : undefined,
+    });
+    // Authored pages name their Diátaxis quadrant; the sidebar is built from
+    // it, so an untagged page cannot be placed (#1731).
+    const docsClass = auditDocsClassification(dir);
+    items.push({
+        name: "Every authored doc page has a diataxis quadrant",
+        tier: 1,
+        pass: !docsClass.hasPages || docsClass.unclassified.length === 0,
+        detail: docsClass.unclassified.length > 0
+            ? `${docsClass.unclassified.length} unclassified: ${docsClass.unclassified.join(", ")}`
+            : undefined,
+    });
+    // #1330 — fountain's spec-coverage gate lived in a lexicon-local vitest
+    // assertion, a convention rather than a check-lexicon contract. The plugin
+    // now states the fact directly via `coverageReport()`.
+    items.push(await coverageReportCheck(plugin));
+    items.push(await workspaceKindsCheck(dir));
+    // ── Tier 2: Recommended ────────────────────────────────────────
+    const pluginContent = readOr(join(dir, "src/plugin.ts"));
+    // #1342 — these were a regex over plugin.ts source text, which passed on a
+    // method declared in a form the regex happened to match and on one that
+    // throws when called. Ask the plugin instead.
+    for (const method of ["mcpTools", "mcpResources", "skills", "detectTemplate", "initTemplates"]) {
+        items.push({
+            name: `The plugin registers ${method}`,
+            tier: 2,
+            pass: registers(plugin, method),
+        });
+    }
+    // #1346 — `resolveAuditCatalog` contributes nothing for a lexicon that omits
+    // the method, silently, so its checks surface in `chant audit` with no title,
+    // tier, fix kind, or category. Tier 2 rather than tier 1: the lexicon builds
+    // and lints correctly without it; what suffers is one command's output.
+    const auditCatalog = (() => {
+        try {
+            return plugin?.auditCatalog?.() ?? {};
+        }
+        catch {
+            return {};
+        }
+    })();
+    const uncatalogued = postSynthChecks.items
+        .map((c) => c.id)
+        .filter((id) => typeof id === "string" && !(id in auditCatalog) && !(id in RULE_CATALOG));
+    items.push({
+        name: "auditCatalog() covers every post-synth check",
+        tier: 2,
+        pass: uncatalogued.length === 0,
+        detail: uncatalogued.length > 0
+            ? `${uncatalogued.length} without metadata: ${uncatalogued.slice(0, 6).join(", ")}`
+            : `${Object.keys(auditCatalog).length} entry/entries`,
+    });
+    // #1348 — the marker channel is a claim: declaring `reads: ["exportResources"]`
+    // while not implementing `exportResources` promises a verdict from a path
+    // that does not exist. The behavioral half lives in the observation
+    // conformance suite, which holds a declared path to a real verdict and an
+    // undeclared one to `unknown`; this is the static half.
+    const channel = plugin?.ownershipChannel;
+    const channelProblems = [];
+    if (channel) {
+        for (const path of channel.reads) {
+            if (!registers(plugin, path)) {
+                channelProblems.push(`declares a marker channel on ${path}, which the plugin does not implement`);
+            }
+        }
+        const keys = channel.keys;
+        for (const key of ["managedBy", "stack", "env"]) {
+            if (typeof keys?.[key] !== "string" || keys[key].length === 0) {
+                channelProblems.push(`marker keys are missing ${key}`);
+            }
+        }
+        if (channel.reads.length === 0) {
+            channelProblems.push("declares marker keys but no read path — nothing can resolve a verdict");
+        }
+    }
+    items.push({
+        name: "Any declared ownership channel names paths the plugin implements",
+        tier: 2,
+        pass: channelProblems.length === 0,
+        detail: channelProblems.length > 0
+            ? channelProblems.join("; ")
+            : channel
+                ? `marker on ${channel.reads.join(", ")}`
+                : "no marker channel — every verdict must be unknown",
+    });
+    // #1344 — a lexicon that reads its own `chant.config.ts` namespace should
+    // declare its shape, or a typo inside that namespace is accepted and silently
+    // ignored: `forgejo: { runnerLabel: … }` left the dialect on its defaults with
+    // nothing said. Source scan, because the read happens deep in a serializer
+    // rather than anywhere the plugin object can be asked.
+    const lexiconName = lexiconNameFor(dir);
+    const readsOwnNamespace = findFiles(join(dir, "src"), (n) => n.endsWith(".ts") && !n.endsWith(".test.ts"))
+        .some((file) => new RegExp(`config\\s*\\??\\.\\s*${lexiconName}\\b`).test(readOr(file)));
+    items.push({
+        name: "Declares a configSchema if it reads its own config namespace",
+        tier: 2,
+        pass: !readsOwnNamespace || plugin?.configSchema !== undefined,
+        detail: readsOwnNamespace
+            ? plugin?.configSchema
+                ? `config.${lexiconName} is declared and validated`
+                : `reads config.${lexiconName} but declares no schema — unknown keys there are silently ignored`
+            : "reads no config namespace of its own",
+    });
+    const composites = countComposites(plugin, dir);
+    items.push({
+        name: "At least 1 composite",
+        tier: 2,
+        pass: composites.count > 0,
+        detail: composites.detail,
+    });
+    items.push({
+        name: "At least 3 examples",
+        tier: 2,
+        pass: exampleCount >= 3,
+        detail: `${exampleCount} example(s)`,
+    });
+    items.push({
+        name: "src/lsp/completions.test.ts exists",
+        tier: 2,
+        pass: existsSync(join(dir, "src/lsp/completions.test.ts")),
+    });
+    items.push({
+        name: "src/lsp/hover.test.ts exists",
+        tier: 2,
+        pass: existsSync(join(dir, "src/lsp/hover.test.ts")),
+    });
+    const coverageContent = readOr(join(dir, "src/coverage.ts"));
+    items.push({
+        name: "coverage.ts is implemented",
+        tier: 2,
+        pass: !coverageContent.includes("not yet implemented"),
+        detail: coverageContent.includes("not yet implemented") ? "contains 'not yet implemented'" : undefined,
+    });
+    items.push({
+        name: "At least 8 doc pages",
+        tier: 2,
+        pass: mdxFiles.length >= 8,
+        detail: `${mdxFiles.length} page(s)`,
+    });
+    // Post-synth check count (excluding helpers, tests, and support files)
+    const postSynthCheckFiles = listTsFiles(join(dir, "src/lint/post-synth"), ["index.ts"])
+        .filter((f) => !f.endsWith(".test.ts") && !f.endsWith("-helpers.ts") && f !== "helpers.ts" && !f.startsWith("arm-") && !f.startsWith("k8s-"));
+    items.push({
+        name: "At least 15 post-synth checks",
+        tier: 2,
+        pass: postSynthCheckFiles.length >= 15,
+        detail: `${postSynthCheckFiles.length} check(s)`,
+    });
+    // Skills count
+    const skillsDir = join(dir, "src/skills");
+    const skillFiles = existsSync(skillsDir) ? readdirSync(skillsDir).filter((f) => f.endsWith(".md")) : [];
+    items.push({
+        name: "At least 3 skills",
+        tier: 2,
+        pass: skillFiles.length >= 3,
+        detail: `${skillFiles.length} skill(s)`,
+    });
+    // initTemplates count — check for template branches in plugin.ts
+    const initTemplateBranches = (pluginContent.match(/template\s*===\s*["']/g) || []).length + 1; // +1 for default
+    items.push({
+        name: "At least 3 initTemplates",
+        tier: 2,
+        pass: initTemplateBranches >= 3,
+        detail: `${initTemplateBranches} template(s)`,
+    });
+    // ── Tier 3: Thoroughness ───────────────────────────────────────
+    // Each lint rule has a test (per-file or consolidated)
+    const ruleDir = join(dir, "src/lint/rules");
+    const ruleSourceFiles = listTsFiles(ruleDir, ["index.ts"]).filter((f) => !f.endsWith(".test.ts"));
+    const ruleTestFiles = listTsFiles(ruleDir).filter((f) => f.endsWith(".test.ts"));
+    // A consolidated test file (e.g. rules.test.ts) covers all rules in the directory
+    const hasConsolidatedRuleTest = ruleTestFiles.length > 0;
+    const untestedRules = hasConsolidatedRuleTest
+        ? []
+        : ruleSourceFiles.filter((f) => !ruleTestFiles.includes(f.replace(".ts", ".test.ts")));
+    items.push({
+        name: "Each lint rule has a .test.ts",
+        tier: 3,
+        pass: ruleSourceFiles.length > 0 && untestedRules.length === 0,
+        detail: untestedRules.length > 0 ? `missing: ${untestedRules.join(", ")}` : undefined,
+    });
+    // Each post-synth has a test (per-file or consolidated)
+    const postSynthDir = join(dir, "src/lint/post-synth");
+    const postSynthSourceFiles = listTsFiles(postSynthDir, ["index.ts"])
+        .filter((f) => !f.endsWith(".test.ts") && !f.endsWith("-helpers.ts") && f !== "helpers.ts");
+    const postSynthTestFiles = listTsFiles(postSynthDir).filter((f) => f.endsWith(".test.ts"));
+    // A consolidated test file (e.g. post-synth.test.ts) covers all checks in the directory
+    const hasConsolidatedPostSynthTest = postSynthTestFiles.length > 0;
+    const untestedPostSynth = hasConsolidatedPostSynthTest
+        ? []
+        : postSynthSourceFiles.filter((f) => !postSynthTestFiles.includes(f.replace(".ts", ".test.ts")));
+    items.push({
+        name: "Each post-synth check has a .test.ts",
+        tier: 3,
+        pass: postSynthSourceFiles.length > 0 && untestedPostSynth.length === 0,
+        detail: untestedPostSynth.length > 0 ? `missing: ${untestedPostSynth.join(", ")}` : undefined,
+    });
+    const hasTypecheckTest = findFiles(join(dir, "src"), (n) => n === "typecheck.test.ts").length > 0;
+    items.push({
+        name: "typecheck.test.ts exists",
+        tier: 3,
+        pass: hasTypecheckTest,
+    });
+    // A round trip over a large corpus can be an end-to-end test, kept out of the unit project's
+    // per-test budget under the e2e name.
+    const hasRoundtripTest = findFiles(join(dir, "src"), (n) => n === "roundtrip.test.ts" || n === "roundtrip.e2e.test.ts").length > 0;
+    items.push({
+        name: "roundtrip.test.ts exists",
+        tier: 3,
+        pass: hasRoundtripTest,
+    });
+    items.push({
+        name: "At least 5 composites",
+        tier: 3,
+        pass: composites.count >= 5,
+        detail: composites.detail,
+    });
+    const hasActions = existsSync(join(dir, "src/actions")) &&
+        listTsFiles(join(dir, "src/actions"), ["index.ts"]).length > 0;
+    items.push({
+        name: "src/actions/ with at least 1 action",
+        tier: 3,
+        pass: hasActions,
+    });
+    // Validate required names count
+    const validateContent = readOr(join(dir, "src/validate.ts"));
+    const requiredNamesMatches = countRequiredNames(validateContent);
+    items.push({
+        name: "validate.ts checks at least 30 required names",
+        tier: 3,
+        pass: requiredNamesMatches >= 30,
+        detail: `${requiredNamesMatches} required name(s)`,
+    });
+    // Composite test file exists
+    const hasCompositeTest = existsSync(join(dir, "src/composites/composites.test.ts"));
+    items.push({
+        name: "Composite test file exists",
+        tier: 3,
+        pass: hasCompositeTest,
+    });
+    // Examples with tests (per-example or consolidated root test file)
+    const examplesDir = join(dir, "examples");
+    let examplesWithTests = 0;
+    if (existsSync(examplesDir)) {
+        // A .test.ts in the examples root directory covers all examples
+        const rootTestFiles = readdirSync(examplesDir).filter((f) => f.endsWith(".test.ts"));
+        const hasConsolidatedExampleTest = rootTestFiles.length > 0;
+        const exampleDirs = readdirSync(examplesDir, { withFileTypes: true }).filter((e) => e.isDirectory());
+        for (const entry of exampleDirs) {
+            if (hasConsolidatedExampleTest) {
+                // Consolidated test covers all non-empty example dirs
+                const contents = readdirSync(join(examplesDir, entry.name));
+                if (contents.length > 0 && !(contents.length === 1 && contents[0] === ".gitkeep")) {
+                    examplesWithTests++;
+                }
+            }
+            else {
+                const exampleTests = findFiles(join(examplesDir, entry.name), (n) => n.endsWith(".test.ts"));
+                if (exampleTests.length > 0)
+                    examplesWithTests++;
+            }
+        }
+    }
+    items.push({
+        name: "At least 5 examples with tests",
+        tier: 3,
+        pass: examplesWithTests >= 5,
+        detail: `${examplesWithTests} example(s) with tests`,
+    });
+    const tier1Pass = items.filter((i) => i.tier === 1).every((i) => i.pass);
+    return { items, tier1Pass };
+}
+// ── Output formatting ────────────────────────────────────────────────
+const COLORS = {
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    gray: "\x1b[90m",
+    red: "\x1b[31m",
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+};
+function useColors() {
+    return !process.env.NO_COLOR && process.stdout.isTTY !== false;
+}
+function c(text, code) {
+    return useColors() ? `${code}${text}${COLORS.reset}` : text;
+}
+/**
+ * Print the check result as a colored table or JSON.
+ */
+export function printCheckResult(result, json) {
+    if (json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    const tierLabels = {
+        1: "required",
+        2: "recommended",
+        3: "thoroughness",
+    };
+    for (const tier of [1, 2, 3]) {
+        const tierItems = result.items.filter((i) => i.tier === tier);
+        if (tierItems.length === 0)
+            continue;
+        const passCount = tierItems.filter((i) => i.pass).length;
+        const label = tierLabels[tier];
+        console.log("");
+        console.log(c(`Tier ${tier} — ${label} (${passCount}/${tierItems.length})`, COLORS.bold));
+        for (const item of tierItems) {
+            let icon;
+            let nameColor;
+            if (item.pass) {
+                icon = c("PASS", COLORS.green);
+                nameColor = COLORS.green;
+            }
+            else if (tier === 1) {
+                icon = c("FAIL", COLORS.red);
+                nameColor = COLORS.red;
+            }
+            else if (tier === 2) {
+                icon = c("WARN", COLORS.yellow);
+                nameColor = COLORS.yellow;
+            }
+            else {
+                icon = c("INFO", COLORS.gray);
+                nameColor = COLORS.gray;
+            }
+            const detail = item.detail ? c(` (${item.detail})`, COLORS.gray) : "";
+            console.log(`  ${icon}  ${c(item.name, nameColor)}${detail}`);
+        }
+    }
+    console.log("");
+    if (result.tier1Pass) {
+        console.log(c("All tier-1 checks passed.", COLORS.green));
+    }
+    else {
+        const failures = result.items.filter((i) => i.tier === 1 && !i.pass);
+        console.log(c(`${failures.length} tier-1 check(s) failed.`, COLORS.red));
+    }
+}