@syv-ai/rulecast 0.1.1 → 0.3.0

package/dist/cli.js

@@ -1,15 +1,19 @@
 #!/usr/bin/env node
 import {
   ADAPTERS,
+  adapterByName,
+  builtinDetectors,
+  createRegistry,
+  renderBacklog,
+  summarise
+} from "./chunk-KOUHBT7F.js";
+import {
   CONFIG_FILE,
   LockTimeoutError,
   MANIFEST_FILE,
   NO_PROMPT,
   RepoFetchError,
-  VERSION,
-  adapterByName,
   allFiles,
-  builtinDetectors,
   cacheHome,
   cachedRepo,
   cachedRepos,
@@ -18,37 +22,45 @@ import {
   checkDetectors,
   compile,
   compileManifest,
-  createRegistry,
+  createReferenceResolver,
   debugLogger,
   defaultConfig,
-  detectorCacheDir,
   diagnosticText,
-  diskCache,
   ensureProjectState,
   ensureRepo,
-  errorMessage,
   fetchCheckout,
   fetchingRepos,
   fixedRepo,
   git,
-  isNotFound,
-  memoryCache,
   mergeBase,
   parseConfig,
-  parseVersion,
   projectStateDir,
   readConfigData,
   readManifest,
-  readSourceFile,
-  renderAgentText,
   repoLabel,
+  resolveRuleContext,
+  rulesOfKind,
   runDetection,
   runPipeline,
-  scanHeadings,
   stagedFiles,
-  tagsOf,
   withLock
-} from "./chunk-3HRTZULM.js";
+} from "./chunk-7KUPYT35.js";
+import {
+  VERSION,
+  detectorCacheDir,
+  diskCache,
+  errorMessage,
+  isDetectorRule,
+  isNotFound,
+  memoryCache,
+  onPath,
+  parseVersion,
+  readSourceFile,
+  renderAgentText,
+  renderTemplate,
+  scanHeadings,
+  tagsOf
+} from "./chunk-HZUATJ53.js";
 import {
   Cancelled
 } from "./chunk-K37BHCEK.js";
@@ -196,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")));
@@ -434,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}
@@ -477,7 +494,7 @@ async function dryRun(project, registry) {
   }
   const lines = [];
   for (const rule of project.rules) {
-    if (rule.detector === null) {
+    if (!isDetectorRule(rule)) {
       lines.push({ rule: rule.id, level: "ok", detail: "context only, nothing to run" });
       continue;
     }
@@ -542,7 +559,7 @@ async function warmDetectors(options) {
   await Promise.all(
     kinds.map(async (kind) => {
       const detector = registry.get(kind);
-      const rules = project.rules.filter((rule) => rule.detector?.kind === kind).map((rule) => ({ id: rule.id, config: rule.detector.config }));
+      const rules = rulesOfKind(project.rules, kind);
       try {
         await withLock(
           path4.join(stateDir, "warm", kind),
@@ -1237,15 +1254,25 @@ 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) {
     const count = shown.get(finding.rule) ?? 0;
     if (count >= options.maxMatchesPerRule) {
-      hidden.set(finding.rule, [...hidden.get(finding.rule) ?? [], finding]);
+      const rest = hidden.get(finding.rule);
+      if (rest === void 0) hidden.set(finding.rule, [finding]);
+      else rest.push(finding);
       continue;
     }
     shown.set(finding.rule, count + 1);
@@ -1256,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(", ")}`);
@@ -1271,8 +1302,26 @@ 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,
+      warnings: delivery.warnings,
+      stop: delivery.stop
+    },
+    null,
+    2
+  );
+}
 function sarif(delivery) {
   const rules = [...new Set(delivery.findings.map((finding) => finding.rule))].map((id) => ({ id }));
   return JSON.stringify(
@@ -1309,7 +1358,7 @@ function formatDelivery(delivery, format, options) {
     case "agent":
       return renderAgentText(delivery, options);
     case "json":
-      return JSON.stringify(delivery, null, 2);
+      return json(delivery);
     case "sarif":
       return sarif(delivery);
   }
@@ -1328,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" },
@@ -1356,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");
   }
@@ -1363,6 +1414,7 @@ function parseRunArgs(args) {
     leading,
     files: values.files ? files : null,
     allFiles: values["all-files"],
+    summary: values.summary,
     fromRef,
     toRef,
     format,
@@ -1406,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);
@@ -1420,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);
@@ -1438,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) => {
@@ -1462,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")) {
@@ -1499,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);
@@ -1536,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>
@@ -1563,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":
@@ -1603,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: [] },
@@ -1620,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;