@syv-ai/rulecast 0.2.0 → 0.3.0

package/dist/{chunk-ZEFEQKG5.js → chunk-HZUATJ53.js}

@@ -404,7 +404,7 @@ function emptyDelivery() {
 }
 
 // src/core/version.ts
-var VERSION2 = "0.2.0";
+var VERSION2 = "0.3.0";
 function parseVersion(text) {
   const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(text);
   return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
@@ -457,6 +457,7 @@ function templateBindings(template) {
 var GROUP_FROM = 3;
 var GROUP_MIN_LITERAL = 40;
 var MAX_LOCATION_PAD = 40;
+var BACKLOG_HINT = "  see all of it: rulecast run --all-files --summary";
 var WRAP = 96;
 var plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
 function header(delivery) {
@@ -562,13 +563,14 @@ function renderAgentText(delivery, options) {
     out.push(...ruleBlock(rule, findings, delivery.templates[rule], omittedFor(delivery.omitted, rule), options));
     out.push("");
   }
-  for (const summary of delivery.preexistingSummary) {
-    out.push(`pre-existing (not blocking): ${summary.rule} \xD7${summary.count} in ${summary.file}`);
-  }
-  if (delivery.omitted.preexisting > 0) {
-    out.push(`\u2026and ${delivery.omitted.preexisting} more pre-existing (not blocking)`);
+  if (delivery.preexistingSummary.length > 0 || delivery.omitted.preexisting > 0) {
+    out.push("backlog in files you touched (not from your edit):");
+    for (const summary of delivery.preexistingSummary) {
+      out.push(`  ${summary.rule} \xD7${summary.count} in ${summary.file}`);
+    }
+    if (delivery.omitted.preexisting > 0) out.push(`  \u2026and ${delivery.omitted.preexisting} more`);
+    out.push(BACKLOG_HINT, "");
   }
-  if (delivery.preexistingSummary.length > 0 || delivery.omitted.preexisting > 0) out.push("");
   for (const reference of delivery.references) out.push(...referenceLines(reference));
   if (out.length > 0 && out.at(-1) !== "") out.push("");
   if (delivery.warnings.length > 0) {
@@ -788,6 +790,8 @@ async function compileRule(input, context) {
     if (unknown) return `unknown template variable "${unknown}"`;
   } else {
     if (data.refuse_write) return "refuse_write needs detect: there is nothing to refuse a write for";
+    if (data.scope) return "scope needs detect: there is nothing to classify";
+    if (data.examples) return "examples need detect: there is nothing to run them against";
     if (stages.some((stage) => stage !== "touch")) return "rules without detect need stages: [touch]";
     if (data.message !== void 0) return "message needs detect";
     if (!data.context?.length) return "rules without detect need context";
@@ -800,6 +804,9 @@ async function compileRule(input, context) {
     excludeTypes: data.exclude_types ?? []
   });
   if (typeof filter === "string") return filter;
+  for (const example of [...data.examples?.good ?? [], ...data.examples?.bad ?? []]) {
+    if (!filter(example.path)) return `example path "${example.path}" does not match this rule's files`;
+  }
   const references = [];
   for (const reference of data.context ?? []) {
     let spec;
@@ -823,12 +830,14 @@ async function compileRule(input, context) {
     description: data.description ?? null,
     source: input.source,
     severity: data.severity ?? "error",
+    scope: data.scope ?? "instance",
     refuseWrite: data.refuse_write === true,
     stages,
     matches: (file) => global(file) && filter(file),
     detector,
     message: data.message ?? null,
-    context: references
+    context: references,
+    examples: data.examples ?? null
   };
 }
 
@@ -921,6 +930,7 @@ export {
   VERSION2 as VERSION,
   parseVersion,
   isOlder,
+  BACKLOG_HINT,
   measureRuleBlock,
   renderAgentText,
   tagsOf,

package/dist/{chunk-C6C5EER7.js → chunk-KOUHBT7F.js}

@@ -14,7 +14,7 @@ import {
   readSourceFile,
   renderAgentText,
   resolveModel
-} from "./chunk-ZEFEQKG5.js";
+} from "./chunk-HZUATJ53.js";
 
 // src/core/detection/registry.ts
 function createRegistry(detectors) {
@@ -1292,10 +1292,70 @@ function adapterByName(name) {
   return ADAPTERS.find((adapter) => adapter.name === name);
 }
 
+// src/adapters/cli/backlog.ts
+function summarise(delivery) {
+  const byRule = /* @__PURE__ */ new Map();
+  const byFile = /* @__PURE__ */ new Map();
+  const add = (rule, file, count) => {
+    const entry = byRule.get(rule) ?? { violations: 0, files: /* @__PURE__ */ new Set() };
+    entry.violations += count;
+    entry.files.add(file);
+    byRule.set(rule, entry);
+    byFile.set(file, (byFile.get(file) ?? 0) + count);
+  };
+  for (const finding of delivery.findings) add(finding.rule, finding.file, finding.count);
+  for (const summary of delivery.preexistingSummary) add(summary.rule, summary.file, summary.count);
+  const rules = [...byRule].map(([rule, entry]) => ({ rule, violations: entry.violations, files: entry.files.size })).sort((a, b) => b.violations - a.violations || (a.rule < b.rule ? -1 : a.rule > b.rule ? 1 : 0));
+  const files = [...byFile].map(([file, violations]) => ({ file, violations })).sort((a, b) => b.violations - a.violations || (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+  return {
+    rules,
+    files,
+    totalViolations: rules.reduce((sum, entry) => sum + entry.violations, 0),
+    totalFiles: files.length
+  };
+}
+var plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+function table(header, rows) {
+  const widths = header.map((_, column) => Math.max(...[header, ...rows].map((row) => row[column].length)));
+  const line = (row) => `  ${row.map((cell, column) => column === 0 ? cell.padEnd(widths[column]) : cell.padStart(widths[column])).join("  ")}`;
+  return [line(header), ...rows.map(line)];
+}
+function renderBacklog(summary, options) {
+  if (summary.totalViolations === 0) return "backlog: no violations";
+  const out = [
+    `backlog: ${plural(summary.totalViolations, "violation")} in ${plural(summary.totalFiles, "file")}`,
+    "",
+    ...table(
+      ["rule", "violations", "files"],
+      summary.rules.map((entry) => [entry.rule, String(entry.violations), String(entry.files)])
+    )
+  ];
+  const shown = summary.files.slice(0, options.topFiles);
+  if (shown.length > 0) {
+    out.push(
+      "",
+      ...table(
+        ["worst files", "violations"],
+        shown.map((entry) => [entry.file, String(entry.violations)])
+      )
+    );
+    const rest = summary.files.length - shown.length;
+    if (rest > 0) out.push(`  \u2026and ${plural(rest, "more file")}`);
+  }
+  out.push(
+    "",
+    "This is the stock, not a rate. Enforcement on edits does not reduce it.",
+    "Remediate a file at a time: a file that already follows a rule rarely breaks it."
+  );
+  return out.join("\n");
+}
+
 export {
   createRegistry,
   builtinDetectors,
   claudeCodeAdapter,
   ADAPTERS,
-  adapterByName
+  adapterByName,
+  summarise,
+  renderBacklog
 };

package/dist/cli.js

@@ -3,8 +3,10 @@ import {
   ADAPTERS,
   adapterByName,
   builtinDetectors,
-  createRegistry
-} from "./chunk-C6C5EER7.js";
+  createRegistry,
+  renderBacklog,
+  summarise
+} from "./chunk-KOUHBT7F.js";
 import {
   CONFIG_FILE,
   LockTimeoutError,
@@ -20,6 +22,7 @@ import {
   checkDetectors,
   compile,
   compileManifest,
+  createReferenceResolver,
   debugLogger,
   defaultConfig,
   diagnosticText,
@@ -35,12 +38,13 @@ import {
   readConfigData,
   readManifest,
   repoLabel,
+  resolveRuleContext,
   rulesOfKind,
   runDetection,
   runPipeline,
   stagedFiles,
   withLock
-} from "./chunk-RODZRI7B.js";
+} from "./chunk-7KUPYT35.js";
 import {
   VERSION,
   detectorCacheDir,
@@ -49,12 +53,14 @@ import {
   isDetectorRule,
   isNotFound,
   memoryCache,
+  onPath,
   parseVersion,
   readSourceFile,
   renderAgentText,
+  renderTemplate,
   scanHeadings,
   tagsOf
-} from "./chunk-ZEFEQKG5.js";
+} from "./chunk-HZUATJ53.js";
 import {
   Cancelled
 } from "./chunk-K37BHCEK.js";
@@ -202,6 +208,9 @@ function inFile(file, transform) {
     throw new Error(`${file}: ${errorMessage(error)}`);
   }
 }
+async function hookCommandResolves(root, signal) {
+  return existsSync2(path2.join(root, "node_modules", ".bin", "rulecast")) || await onPath("rulecast", signal);
+}
 async function hooksInstalled(root, adapter, verifyMs) {
   const install = installOf(adapter);
   const command = install.command(existsSync2(path2.join(root, "node_modules", ".bin", "rulecast")));
@@ -440,12 +449,14 @@ async function doctorCommand(root, args, registry, io) {
     }
   }
   io.stdout("\nhooks\n");
+  const resolves = await hookCommandResolves(root);
   for (const adapter of ADAPTERS) {
     if (adapter.install === null) continue;
     const file = await hooksInstalled(root, adapter, project.config.timeouts.verifyMs);
-    const level = file === null ? "warning" : "ok";
+    const level = file === null || !resolves ? "warning" : "ok";
     count(level);
-    io.stdout(line(level, adapter.label, file ?? "not installed (run rulecast install)"));
+    const detail = file === null ? "not installed (run rulecast install)" : resolves ? file : `${file} \u2014 but "rulecast" is on neither the PATH nor node_modules/.bin, so the hooks do nothing. Add it to the project (pnpm add -D @syv-ai/rulecast) and run rulecast install again.`;
+    io.stdout(line(level, adapter.label, detail));
   }
   io.stdout("\ncache\n");
   io.stdout(`  home       ${home}
@@ -1243,9 +1254,17 @@ import { parseArgs as parseArgs5 } from "util";
 
 // src/adapters/cli/format.ts
 var CLI_FORMATS = ["terminal", "agent", "json", "sarif"];
+var TOP_FILES = 10;
 var plural3 = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
 function terminal(delivery, options) {
   const out = [];
+  if (options.findings === false) {
+    if (delivery.warnings.length > 0) {
+      out.push("warnings:", ...delivery.warnings.map((warning) => `  - ${warning}`), "");
+    }
+    if (options.backlog === true) out.push(renderBacklog(summarise(delivery), { topFiles: TOP_FILES }));
+    return out.join("\n");
+  }
   const shown = /* @__PURE__ */ new Map();
   const hidden = /* @__PURE__ */ new Map();
   for (const finding of delivery.findings) {
@@ -1264,8 +1283,12 @@ function terminal(delivery, options) {
   }
   for (const [rule, rest] of hidden) out.push(`\u2026and ${rest.length} more for ${rule}`);
   if (out.length > 0) out.push("");
-  for (const summary of delivery.preexistingSummary) {
-    out.push(`pre-existing (not blocking): ${summary.rule} \xD7${summary.count} in ${summary.file}`);
+  if (delivery.preexistingSummary.length > 0) {
+    out.push("backlog in the files checked (not from your change):");
+    for (const summary of delivery.preexistingSummary) {
+      out.push(`  ${summary.rule} \xD7${summary.count} in ${summary.file}`);
+    }
+    if (options.backlog !== true) out.push("  see all of it: rulecast run --all-files --summary");
   }
   if (delivery.references.length > 0) {
     out.push(`conventions: ${delivery.references.map((reference) => reference.ref).join(", ")}`);
@@ -1279,12 +1302,16 @@ function terminal(delivery, options) {
   out.push(
     delivery.findings.length === 0 ? "no findings" : `${plural3(errors, "error")}, ${plural3(warningsCount, "warning")}`
   );
+  if (options.backlog === true) out.push("", renderBacklog(summarise(delivery), { topFiles: TOP_FILES }));
   return out.join("\n");
 }
 function json(delivery) {
   return JSON.stringify(
     {
       findings: delivery.findings,
+      // Always, whatever flags were given: a consumer that did not ask for it can ignore a key, and
+      // one that wanted it cannot conjure it. This is the number a team tracks over time.
+      backlog: summarise(delivery),
       preexistingSummary: delivery.preexistingSummary,
       references: delivery.references,
       touches: delivery.touches,
@@ -1350,6 +1377,7 @@ function parseRunArgs(args) {
     options: {
       files: { type: "boolean", default: false },
       "all-files": { type: "boolean", default: false },
+      summary: { type: "boolean", default: false },
       "from-ref": { type: "string" },
       "to-ref": { type: "string" },
       format: { type: "string", default: "terminal" },
@@ -1378,6 +1406,7 @@ function parseRunArgs(args) {
   if (values.files && files.length === 0) throw new UsageError("--files needs at least one file");
   if (values.files && values["all-files"]) throw new UsageError("--all-files and --files cannot be combined");
   if (toRef !== null && fromRef === null) throw new UsageError("--to-ref needs --from-ref");
+  if (values.summary && format === "sarif") throw new UsageError("--summary cannot be combined with --format sarif");
   if (fromRef !== null && (values.files || values["all-files"])) {
     throw new UsageError("--from-ref cannot be combined with --all-files or --files");
   }
@@ -1385,6 +1414,7 @@ function parseRunArgs(args) {
     leading,
     files: values.files ? files : null,
     allFiles: values["all-files"],
+    summary: values.summary,
     fromRef,
     toRef,
     format,
@@ -1428,7 +1458,11 @@ async function executeRun({ project, ruleId, run: run2, registry, io }) {
     skipDetectorKinds: run2.noLlm ? /* @__PURE__ */ new Set(["llm"]) : void 0,
     onlyRules: ruleId === null ? void 0 : /* @__PURE__ */ new Set([ruleId])
   });
-  const text = formatDelivery(result.delivery, run2.format, { maxMatchesPerRule: project.config.maxMatchesPerRule });
+  const text = formatDelivery(result.delivery, run2.format, {
+    maxMatchesPerRule: project.config.maxMatchesPerRule,
+    findings: !run2.summary,
+    backlog: run2.allFiles || run2.summary
+  });
   if (text) io.stdout(`${text}
 `);
   return exitCodeFor(result.delivery, result.failed);
@@ -1442,13 +1476,238 @@ async function runCommand(root, args, registry, io) {
   return executeRun({ project, ruleId: run2.leading[0] ?? null, run: run2, registry, io });
 }
 
+// src/commands/test.ts
+import { parseArgs as parseArgs6 } from "util";
+
+// src/core/examples.ts
+import { mkdir as mkdir3, mkdtemp, rm as rm2, writeFile as writeFile4 } from "fs/promises";
+import path7 from "path";
+var EXAMPLES_DIR = ".rulecast-examples-";
+function skippedResult(rule) {
+  return { ...emptyResult(rule), skipped: true };
+}
+function emptyResult(rule) {
+  return {
+    rule,
+    outcomes: [],
+    recall: { matched: 0, total: 0 },
+    precision: { correct: 0, total: 0 },
+    missing: false,
+    empty: false,
+    skipped: false
+  };
+}
+async function runExamples(input) {
+  const { rule } = input;
+  const result = emptyResult(rule.id);
+  if (rule.examples === null) return { ...result, missing: true };
+  const cases = [
+    ...rule.examples.good.map((example, index) => ({ kind: "good", index, example })),
+    ...rule.examples.bad.map((example, index) => ({ kind: "bad", index, example }))
+  ];
+  if (cases.length === 0) return { ...result, empty: true };
+  const scratch = path7.basename(await mkdtemp(path7.join(input.root, EXAMPLES_DIR)));
+  try {
+    for (const { kind, index, example } of cases) {
+      const outcome = await runOne(input, scratch, example);
+      const fired2 = outcome.findings.length > 0;
+      const passed = outcome.error === void 0 && fired2 === (kind === "bad");
+      result.outcomes.push({ kind, index, path: example.path, ...outcome, passed });
+    }
+  } finally {
+    await rm2(path7.join(input.root, scratch), { recursive: true, force: true });
+  }
+  const fired = (outcome) => outcome.findings.length > 0;
+  const bad = result.outcomes.filter((outcome) => outcome.kind === "bad");
+  const goodFired = result.outcomes.filter((outcome) => outcome.kind === "good" && fired(outcome));
+  const badFired = bad.filter(fired);
+  result.recall = { matched: badFired.length, total: bad.length };
+  result.precision = { correct: badFired.length, total: badFired.length + goodFired.length };
+  return result;
+}
+async function runOne(input, scratch, example) {
+  const relative = path7.join(scratch, example.path);
+  const file = path7.join(input.root, relative);
+  await mkdir3(path7.dirname(file), { recursive: true });
+  await writeFile4(file, example.code);
+  const output = await runDetection({
+    root: input.root,
+    event: "verify",
+    selections: [{ rule: input.rule, files: [relative] }],
+    // No baseline: an example is entirely new, which is what an author is asking about.
+    changes: /* @__PURE__ */ new Map(),
+    read: (name) => readSourceFile(input.root, name),
+    registry: input.registry,
+    cacheFor: input.cacheFor,
+    contextFor: input.contextFor,
+    settings: input.settings,
+    timeoutMs: input.timeoutMs
+  });
+  const failure = output.errors[0]?.message ?? (output.timedOut.length > 0 ? "timed out" : void 0);
+  if (failure !== void 0) return { findings: [], error: failure };
+  const findings = output.findings.map(({ match }) => ({
+    line: match.line,
+    column: match.column,
+    message: renderTemplate(input.rule.message, {
+      ...match.captures,
+      file: example.path,
+      line: String(match.line),
+      column: String(match.column),
+      text: match.text,
+      rule: input.rule.id
+    })
+  }));
+  return { findings };
+}
+
+// src/commands/test.ts
+function parseTestArgs(args) {
+  const { values, positionals } = parseArgs6({
+    args,
+    allowPositionals: true,
+    options: { against: { type: "string", multiple: true } }
+  });
+  if (positionals.length > 1) throw new UsageError(`unexpected arguments: ${positionals.slice(1).join(" ")}`);
+  const against = values.against ?? [];
+  const ruleId = positionals[0] ?? null;
+  if (against.length > 0 && ruleId === null) throw new UsageError("--against needs a RULE_ID");
+  return { ruleId, against };
+}
+var AGAINST_NOTES = [
+  "  A rule this common is usually true by definition rather than a convention.",
+  "  A rule with almost no violations is usually not worth an agent's context."
+];
+var ZERO_NOTES = [
+  "  Nothing to fix today is not the same as nothing to catch: this counts the",
+  "  stock, not how often an edit would break the rule."
+];
+var ratio = (part, whole) => whole === 0 ? "   \u2014 " : (part / whole).toFixed(2);
+function summaryLine(rule, result) {
+  const id = rule.id.padEnd(36);
+  if (result.skipped) return `  ${id}skipped (llm; name the rule to run it)`;
+  if (result.missing || result.empty) return `  ${id}no examples`;
+  const passed = result.outcomes.filter((outcome) => outcome.passed).length;
+  const score = `${passed}/${result.outcomes.length}`.padEnd(7);
+  return `  ${id}${score} P ${ratio(result.precision.correct, result.precision.total)}  R ${ratio(result.recall.matched, result.recall.total)}`;
+}
+function failureLines(rule, result) {
+  const out = [];
+  for (const outcome of result.outcomes) {
+    if (outcome.passed) continue;
+    const name = `${outcome.kind}[${outcome.index}] ${outcome.path}`;
+    if (outcome.error !== void 0) {
+      out.push(`      ${name} \u2014 ${rule.detector.kind} failed: ${outcome.error}`);
+      continue;
+    }
+    if (outcome.kind === "bad") {
+      out.push(`      ${name} \u2014 no finding`);
+      continue;
+    }
+    const source = (rule.examples?.good[outcome.index]?.code ?? "").split(/\r?\n/);
+    for (const finding of outcome.findings) {
+      out.push(`      ${name} \u2014 fired at line ${finding.line}`, `        ${source[finding.line - 1]?.trim() ?? ""}`);
+    }
+  }
+  return out;
+}
+var AGAINST_TOP_FILES = 10;
+async function reportAgainst(root, rule, paths, detection, io) {
+  const prefixes = paths.map((given) => {
+    const resolved = toProjectPath(root, io.cwd, given);
+    if (resolved === null) throw new UsageError(`${given} is outside the project`);
+    return resolved === "." ? "" : resolved;
+  });
+  const under = (file) => prefixes.some((prefix) => prefix === "" || file === prefix || file.startsWith(`${prefix}/`));
+  const files = (await allFiles(root)).filter((file) => under(file) && rule.matches(file));
+  if (files.length === 0) {
+    io.stdout(`
+  no files under ${paths.join(", ")} match ${rule.id}
+
+`);
+    return 0;
+  }
+  const output = await runDetection({
+    ...detection,
+    root,
+    event: "verify",
+    selections: [{ rule, files }],
+    changes: /* @__PURE__ */ new Map(),
+    read: (file) => readSourceFile(root, file)
+  });
+  const failure = output.errors[0];
+  if (failure !== void 0) throw new Error(`${rule.detector.kind} detector failed: ${failure.message}`);
+  const byFile = /* @__PURE__ */ new Map();
+  for (const { match } of output.findings) byFile.set(match.file, (byFile.get(match.file) ?? 0) + 1);
+  const worst = [...byFile].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1)).slice(0, AGAINST_TOP_FILES);
+  const width = Math.max(...worst.map(([file]) => file.length), 0);
+  const out = ["", `  ${output.findings.length} violations in ${byFile.size} of ${files.length} matching files`];
+  if (worst.length > 0) {
+    out.push("", ...worst.map(([file, count]) => `  ${file.padEnd(width + 2)}${count}`));
+    if (byFile.size > worst.length) out.push(`  \u2026and ${byFile.size - worst.length} more files`);
+  }
+  out.push("", ...AGAINST_NOTES);
+  if (output.findings.length === 0) out.push(...ZERO_NOTES);
+  out.push("");
+  io.stdout(out.join("\n"));
+  return 0;
+}
+async function testCommand(root, args, registry, io) {
+  const { ruleId, against } = parseTestArgs(args);
+  if (!hasProject(root)) throw new Error(`no ${CONFIG_FILE} in ${io.cwd} or its parents`);
+  const project = await compile({ root, registry, repos: fetchingRepos(cacheHome(io.env)) });
+  if (ruleId !== null && !project.rules.some((rule) => rule.id === ruleId)) {
+    throw new UsageError(`no rule "${ruleId}" (see rulecast validate)`);
+  }
+  const rules = project.rules.filter(isDetectorRule).filter((rule) => ruleId === null || rule.id === ruleId);
+  const stateDir = ensureProjectState(cacheHome(io.env), root);
+  const resolver = createReferenceResolver(root);
+  const detection = {
+    registry,
+    settings: { llm: project.config.llm },
+    contextFor: (one) => resolveRuleContext(resolver, one.context),
+    cacheFor: (kind) => diskCache(detectorCacheDir(stateDir, kind)),
+    timeoutMs: project.config.timeouts.verifyMs
+  };
+  if (against.length > 0) return await reportAgainst(root, rules[0], against, detection, io);
+  const lines = [""];
+  const noExamples = [];
+  let failedRules = 0;
+  let ranRules = 0;
+  for (const rule of rules) {
+    const result = ruleId === null && rule.detector.kind === "llm" ? skippedResult(rule.id) : await runExamples({ ...detection, root, rule });
+    lines.push(summaryLine(rule, result));
+    if (result.missing || result.empty) {
+      noExamples.push(rule.id);
+      continue;
+    }
+    if (result.skipped) continue;
+    ranRules++;
+    if (result.outcomes.some((outcome) => !outcome.passed)) {
+      failedRules++;
+      lines.push(...failureLines(rule, result));
+    }
+  }
+  if (rules.length === 0) {
+    io.stdout("no rules with a detector\n");
+    return 0;
+  }
+  if (noExamples.length > 0) lines.push("", `  no examples: ${noExamples.join(", ")}`);
+  lines.push(
+    "",
+    failedRules === 0 ? ranRules === 0 ? "  nothing to run" : `  ${ranRules} ${ranRules === 1 ? "rule" : "rules"} passed` : `  ${failedRules} of ${ranRules} rules failed`,
+    ""
+  );
+  io.stdout(lines.join("\n"));
+  return failedRules === 0 ? 0 : 1;
+}
+
 // src/commands/try-repo.ts
 import { existsSync as existsSync5, statSync as statSync2 } from "fs";
-import { mkdtemp, rm as rm2 } from "fs/promises";
+import { mkdtemp as mkdtemp2, rm as rm3 } from "fs/promises";
 import { tmpdir as tmpdir2 } from "os";
-import path7 from "path";
+import path8 from "path";
 var isDirectory = (file) => existsSync5(file) && statSync2(file).isDirectory();
-var isGitRepo = (dir) => existsSync5(path7.join(dir, ".git")) || existsSync5(path7.join(dir, "HEAD"));
+var isGitRepo = (dir) => existsSync5(path8.join(dir, ".git")) || existsSync5(path8.join(dir, "HEAD"));
 async function baseConfigData(root) {
   if (!hasProject(root)) return {};
   const data = await readConfigData(root);
@@ -1460,16 +1719,16 @@ async function tryRepoCommand(root, args, registry, io) {
   const [repo, ruleId, ...extra] = run2.leading;
   if (repo === void 0) throw new UsageError("try-repo needs a repository path or URL");
   if (extra.length > 0) throw new UsageError(`unexpected arguments: ${extra.join(" ")}`);
-  const local = path7.resolve(io.cwd, repo);
+  const local = path8.resolve(io.cwd, repo);
   const directory = isDirectory(local);
   if (directory && run2.ref !== null && !isGitRepo(local)) throw new UsageError("--ref only applies to URLs");
   const fromDirectory = directory && run2.ref === null;
   const rev = fromDirectory ? "working-tree" : run2.ref ?? "HEAD";
-  const temp = fromDirectory ? null : await mkdtemp(path7.join(tmpdir2(), "rulecast-try-repo-"));
+  const temp = fromDirectory ? null : await mkdtemp2(path8.join(tmpdir2(), "rulecast-try-repo-"));
   try {
     const dir = temp ?? local;
     if (temp !== null) await fetchCheckout(directory ? local : repo, rev, temp);
-    const label = fromDirectory ? `${path7.basename(local)}@${rev}` : repoLabel(repo, rev);
+    const label = fromDirectory ? `${path8.basename(local)}@${rev}` : repoLabel(repo, rev);
     const manifest = await readManifest(dir);
     if (!manifest.ok) throw new Error(`${label}: ${manifest.message}`);
     const ids = manifest.value.flatMap((rule) => {
@@ -1484,29 +1743,29 @@ async function tryRepoCommand(root, args, registry, io) {
     const project = await compile({ root, registry, repos: fixedRepo(dir, label), configData });
     return await executeRun({ project, ruleId: null, run: run2, registry, io });
   } finally {
-    if (temp !== null) await rm2(temp, { recursive: true, force: true });
+    if (temp !== null) await rm3(temp, { recursive: true, force: true });
   }
 }
 
 // src/commands/validate.ts
 import { existsSync as existsSync6 } from "fs";
-import path8 from "path";
+import path9 from "path";
 function formatDiagnostic(diagnostic) {
   return `${diagnostic.level === "warning" ? "warning: " : ""}${diagnosticText(diagnostic)}`;
 }
 async function validateCommand(root, args, registry, io) {
-  const targets = args.length > 0 ? args.map((file) => ({ shown: file, full: path8.resolve(io.cwd, file) })) : [CONFIG_FILE, MANIFEST_FILE].filter((name) => existsSync6(path8.join(root, name))).map((name) => ({ shown: name, full: path8.join(root, name) }));
+  const targets = args.length > 0 ? args.map((file) => ({ shown: file, full: path9.resolve(io.cwd, file) })) : [CONFIG_FILE, MANIFEST_FILE].filter((name) => existsSync6(path9.join(root, name))).map((name) => ({ shown: name, full: path9.join(root, name) }));
   if (targets.length === 0) throw new Error(`nothing to validate: no ${CONFIG_FILE} or ${MANIFEST_FILE}`);
   for (const { shown, full } of targets) {
-    const name = path8.basename(full);
+    const name = path9.basename(full);
     if (name !== CONFIG_FILE && name !== MANIFEST_FILE) {
       throw new UsageError(`${shown}: not a ${CONFIG_FILE} or ${MANIFEST_FILE}`);
     }
   }
   let failed = false;
   for (const { shown, full } of targets) {
-    const dir = path8.dirname(full);
-    const result = path8.basename(full) === CONFIG_FILE ? await compile({ root: dir, registry, repos: fetchingRepos(cacheHome(io.env)) }) : await compileManifest(dir, registry);
+    const dir = path9.dirname(full);
+    const result = path9.basename(full) === CONFIG_FILE ? await compile({ root: dir, registry, repos: fetchingRepos(cacheHome(io.env)) }) : await compileManifest(dir, registry);
     for (const diagnostic of result.diagnostics) io.stdout(`${shown}: ${formatDiagnostic(diagnostic)}
 `);
     if (result.diagnostics.some((diagnostic) => diagnostic.level === "error")) {
@@ -1521,10 +1780,10 @@ async function validateCommand(root, args, registry, io) {
 }
 
 // src/commands/warm.ts
-import { parseArgs as parseArgs6 } from "util";
+import { parseArgs as parseArgs7 } from "util";
 var WARM_TIMEOUT_MS = 5 * 6e4;
 async function warmCommand(root, args, registry, io) {
-  const { values } = parseArgs6({ args, options: { detector: { type: "string", multiple: true } } });
+  const { values } = parseArgs7({ args, options: { detector: { type: "string", multiple: true } } });
   if (!hasProject(root)) throw new Error(`no .rulecast-config.yaml in ${root} or its parents (run rulecast init)`);
   const home = cacheHome(io.env);
   const stateDir = ensureProjectState(home, root);
@@ -1558,9 +1817,10 @@ var USAGE = `usage:
   rulecast init [--rules id,id | --no-rules] [--agent <name>]... [--scope shared|personal] [--yes]
   rulecast install [--agent <name>]... [--scope shared|personal]
   rulecast uninstall [--agent <name>]...
-  rulecast run [RULE_ID] [--all-files | --files F...] [--from-ref A [--to-ref B]] [--format terminal|agent|json|sarif] [--session <id>] [--no-llm]
+  rulecast run [RULE_ID] [--all-files | --files F...] [--from-ref A [--to-ref B]] [--summary] [--format terminal|agent|json|sarif] [--session <id>] [--no-llm]
   rulecast autoupdate [--freeze] [--repo URL]...
   rulecast try-repo <path|url> [RULE_ID] [--ref REV] [run flags]
+  rulecast test [RULE_ID]
   rulecast validate [file...]
   rulecast clean [--project]
   rulecast hook <adapter>
@@ -1585,6 +1845,8 @@ async function main(argv, io) {
         return await autoupdateCommand(root, args, io);
       case "try-repo":
         return await tryRepoCommand(root, args, registry, io);
+      case "test":
+        return await testCommand(root, args, registry, io);
       case "validate":
         return await validateCommand(root, args, registry, io);
       case "clean":
@@ -1625,7 +1887,7 @@ function spawnDetached(command, args, cwd) {
 // src/init/clipboard.ts
 import { spawn as spawn2 } from "child_process";
 import { accessSync, constants, statSync as statSync3 } from "fs";
-import path9 from "path";
+import path10 from "path";
 var CANDIDATES = [
   { command: "pbcopy", args: [] },
   { command: "wl-copy", args: [] },
@@ -1642,9 +1904,9 @@ function isExecutable(file) {
   }
 }
 function findOnPath(name, env) {
-  for (const dir of (env.PATH ?? "").split(path9.delimiter)) {
+  for (const dir of (env.PATH ?? "").split(path10.delimiter)) {
     if (dir === "") continue;
-    const candidate = path9.join(dir, name);
+    const candidate = path10.join(dir, name);
     if (isExecutable(candidate)) return candidate;
   }
   return null;