slopbrick 0.18.3 → 0.18.4

package/dist/index.cjs

@@ -58267,6 +58267,139 @@ async function applyFixes(report, config, scannedFiles) {
 // src/cli/program.ts
 init_cache();
 init_types();
+
+// src/cli/help.ts
+var CATEGORY_LABELS3 = {
+  file: "File selection",
+  filter: "Filter",
+  output: "Output & display",
+  perf: "Performance",
+  fix: "Auto-fix",
+  ci: "CI / threshold",
+  watch: "Watch & diagnose",
+  tokens: "Tokens",
+  telemetry: "Telemetry",
+  other: "Other"
+};
+var OPTION_CATEGORY = {
+  // File selection
+  "--include": "file",
+  "--exclude": "file",
+  "--since": "file",
+  "--diff": "file",
+  "--staged": "file",
+  "--changed": "file",
+  "--workspace": "file",
+  // Filter
+  "--ai-only": "filter",
+  "--human-only": "filter",
+  "--security-only": "filter",
+  "--ignore-wcag22": "filter",
+  "--framework": "filter",
+  // Output & display
+  "--format": "output",
+  "--brief": "output",
+  "--full": "output",
+  "--json": "output",
+  "--html": "output",
+  "--no-color": "output",
+  "--quiet": "output",
+  "--verbose": "output",
+  "--heatmap": "output",
+  "--trend": "output",
+  "--why-failing": "output",
+  // Performance
+  "--threads": "perf",
+  "--incremental": "perf",
+  "--cache": "perf",
+  "--cache-path": "perf",
+  // Auto-fix
+  "--fix": "fix",
+  "--dry-run": "fix",
+  "--show-fixes-diff": "fix",
+  // CI / threshold
+  "--strict": "ci",
+  "--no-increase": "ci",
+  "--baseline": "ci",
+  "--threshold": "ci",
+  // Watch & diagnose
+  "--watch": "watch",
+  "--doctor": "watch",
+  "--suggest": "watch",
+  "--tighten": "watch",
+  // Tokens
+  "--tokens": "tokens",
+  // Telemetry
+  "--no-telemetry": "telemetry"
+};
+var CATEGORY_ORDER2 = [
+  "file",
+  "filter",
+  "output",
+  "perf",
+  "fix",
+  "ci",
+  "watch",
+  "tokens",
+  "telemetry",
+  "other"
+];
+function groupOptions(cmd) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const category of CATEGORY_ORDER2) {
+    grouped.set(category, []);
+  }
+  for (const opt of cmd.options) {
+    if (opt.hidden) continue;
+    const longFlag = opt.long ?? opt.short ?? "";
+    const category = longFlag ? OPTION_CATEGORY[longFlag] ?? "other" : "other";
+    grouped.get(category).push({
+      category,
+      flags: opt.flags,
+      description: opt.description ?? ""
+    });
+  }
+  return grouped;
+}
+function renderOption(opt, flagWidth) {
+  const padded = opt.flags.padEnd(flagWidth, " ");
+  return `  ${padded}  ${opt.description}`;
+}
+function formatGroupedHelp(cmd) {
+  const lines = [];
+  const usage = cmd.usage ? cmd.usage() : `Usage: ${cmd.name()} [options]`;
+  lines.push(usage);
+  lines.push("");
+  if (cmd.description()) {
+    lines.push(cmd.description());
+    lines.push("");
+  }
+  const grouped = groupOptions(cmd);
+  let flagWidth = 0;
+  for (const options of grouped.values()) {
+    for (const opt of options) {
+      if (opt.flags.length > flagWidth) flagWidth = opt.flags.length;
+    }
+  }
+  let firstCategory = true;
+  for (const category of CATEGORY_ORDER2) {
+    const options = grouped.get(category);
+    if (options.length === 0) continue;
+    if (!firstCategory) lines.push("");
+    firstCategory = false;
+    lines.push(`  ${CATEGORY_LABELS3[category]}:`);
+    for (const opt of options) {
+      lines.push(renderOption(opt, flagWidth));
+    }
+  }
+  lines.push("");
+  lines.push(
+    "Use `--help-flat` for the standard un-grouped list. See `https://usebrick.dev/docs/scan-options` for full docs."
+  );
+  return lines.join("\n");
+}
+
+// src/cli/program.ts
 init_scan();
 process.on("uncaughtException", (err) => {
   logger.error(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
@@ -58275,6 +58408,7 @@ process.on("uncaughtException", (err) => {
 async function runCli({ start }) {
   try {
     const program = new import_commander2.Command().name("slopbrick").description("Repository Coherence Scanner \u2014 surface AI-induced pattern drift, secret leaks, and design-token violations").version(VERSION).option("--framework <name>", "framework multiplier to apply").option("--include <glob>", "include pattern (repeatable)", collectGlob, []).option("--exclude <glob>", "exclude pattern (repeatable)", collectGlob, []).option("--ai-only", "only report AI-specific issues").option("--human-only", "only report human-facing issues").option("--ignore-wcag22", "ignore WCAG 2.2 related issues").option("--format <pretty|json|sarif|html>", "output format", "pretty").option("--threads <n>", "number of worker threads", parseThreads).option("--since <ref>", "only scan files changed since git ref").option("--diff <ref>", "alias for --since <ref>; also adds PR Slop Score to the report").option("--workspace <path>", "workspace/project path", process.cwd()).option("--tighten", "tighten baseline allowances").option("--fix", "apply auto-fixes").option("--dry-run", "with --fix: print what would change without writing").option("--show-fixes-diff", "print unified diff of proposed auto-fixes").option("--doctor", "run diagnostics").option("--watch", "watch files and re-run").option("--suggest", "print remediation advice").option("--why-failing", "print the top 5 rules dragging the score down").option("--brief", "terse output (verdict + headline + threshold + delta only)").option("--heatmap", "print migration ROI heatmap").option("--quiet", "suppress non-error output").option("--verbose", "enable debug logging (file paths, timings, rule-fire counts)").option("--strict", "exit 2 if any high-severity issue remains").option("--no-increase", "exit 2 if slop index increased since last run").option("--baseline", "save a baseline after this scan").option("--trend [n]", "print a sparkline of the last n runs", parseTrend).option("--json [path]", "write JSON report to path or stdout").option("--html [path]", "write HTML report to path or stdout").option("--staged", "scan only changed files (staged and unstaged)").option("--changed", "scan working-tree changes (staged + unstaged + untracked)").option("--incremental", "skip unchanged files using the persisted hash cache").option("--cache-path <path>", "path to the incremental-scan cache (default: .slopbrick-cache.json)").option("--tokens <path>", "merge tokens.json layout values into the arbitrary-value allowlist").option("--cache", "cache parsed AST results locally").option("--no-color", "suppress ANSI color codes in output").option("--security-only", "run only the security/* rules").option("--full", "show the complete report (all issues, all categories)");
+    program.helpInformation = () => formatGroupedHelp(program);
     registerInit(program);
     registerInstall(program);
     registerUninstall(program);
@@ -58438,6 +58572,11 @@ async function runCli({ start }) {
     registerTokens(program);
     registerReport(program);
     registerScan(program, scanAction);
+    if (process.argv.includes("--help-flat")) {
+      delete program.helpInformation;
+      program.outputHelp();
+      process.exit(0);
+    }
     await program.parseAsync(process.argv);
   } catch (err) {
     if (err instanceof ConfigValidationError) {

package/dist/index.js

@@ -58176,6 +58176,139 @@ async function applyFixes(report, config, scannedFiles) {
 // src/cli/program.ts
 init_cache();
 init_types();
+
+// src/cli/help.ts
+var CATEGORY_LABELS3 = {
+  file: "File selection",
+  filter: "Filter",
+  output: "Output & display",
+  perf: "Performance",
+  fix: "Auto-fix",
+  ci: "CI / threshold",
+  watch: "Watch & diagnose",
+  tokens: "Tokens",
+  telemetry: "Telemetry",
+  other: "Other"
+};
+var OPTION_CATEGORY = {
+  // File selection
+  "--include": "file",
+  "--exclude": "file",
+  "--since": "file",
+  "--diff": "file",
+  "--staged": "file",
+  "--changed": "file",
+  "--workspace": "file",
+  // Filter
+  "--ai-only": "filter",
+  "--human-only": "filter",
+  "--security-only": "filter",
+  "--ignore-wcag22": "filter",
+  "--framework": "filter",
+  // Output & display
+  "--format": "output",
+  "--brief": "output",
+  "--full": "output",
+  "--json": "output",
+  "--html": "output",
+  "--no-color": "output",
+  "--quiet": "output",
+  "--verbose": "output",
+  "--heatmap": "output",
+  "--trend": "output",
+  "--why-failing": "output",
+  // Performance
+  "--threads": "perf",
+  "--incremental": "perf",
+  "--cache": "perf",
+  "--cache-path": "perf",
+  // Auto-fix
+  "--fix": "fix",
+  "--dry-run": "fix",
+  "--show-fixes-diff": "fix",
+  // CI / threshold
+  "--strict": "ci",
+  "--no-increase": "ci",
+  "--baseline": "ci",
+  "--threshold": "ci",
+  // Watch & diagnose
+  "--watch": "watch",
+  "--doctor": "watch",
+  "--suggest": "watch",
+  "--tighten": "watch",
+  // Tokens
+  "--tokens": "tokens",
+  // Telemetry
+  "--no-telemetry": "telemetry"
+};
+var CATEGORY_ORDER2 = [
+  "file",
+  "filter",
+  "output",
+  "perf",
+  "fix",
+  "ci",
+  "watch",
+  "tokens",
+  "telemetry",
+  "other"
+];
+function groupOptions(cmd) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const category of CATEGORY_ORDER2) {
+    grouped.set(category, []);
+  }
+  for (const opt of cmd.options) {
+    if (opt.hidden) continue;
+    const longFlag = opt.long ?? opt.short ?? "";
+    const category = longFlag ? OPTION_CATEGORY[longFlag] ?? "other" : "other";
+    grouped.get(category).push({
+      category,
+      flags: opt.flags,
+      description: opt.description ?? ""
+    });
+  }
+  return grouped;
+}
+function renderOption(opt, flagWidth) {
+  const padded = opt.flags.padEnd(flagWidth, " ");
+  return `  ${padded}  ${opt.description}`;
+}
+function formatGroupedHelp(cmd) {
+  const lines = [];
+  const usage = cmd.usage ? cmd.usage() : `Usage: ${cmd.name()} [options]`;
+  lines.push(usage);
+  lines.push("");
+  if (cmd.description()) {
+    lines.push(cmd.description());
+    lines.push("");
+  }
+  const grouped = groupOptions(cmd);
+  let flagWidth = 0;
+  for (const options of grouped.values()) {
+    for (const opt of options) {
+      if (opt.flags.length > flagWidth) flagWidth = opt.flags.length;
+    }
+  }
+  let firstCategory = true;
+  for (const category of CATEGORY_ORDER2) {
+    const options = grouped.get(category);
+    if (options.length === 0) continue;
+    if (!firstCategory) lines.push("");
+    firstCategory = false;
+    lines.push(`  ${CATEGORY_LABELS3[category]}:`);
+    for (const opt of options) {
+      lines.push(renderOption(opt, flagWidth));
+    }
+  }
+  lines.push("");
+  lines.push(
+    "Use `--help-flat` for the standard un-grouped list. See `https://usebrick.dev/docs/scan-options` for full docs."
+  );
+  return lines.join("\n");
+}
+
+// src/cli/program.ts
 init_scan();
 process.on("uncaughtException", (err) => {
   logger.error(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
@@ -58184,6 +58317,7 @@ process.on("uncaughtException", (err) => {
 async function runCli({ start }) {
   try {
     const program = new Command().name("slopbrick").description("Repository Coherence Scanner \u2014 surface AI-induced pattern drift, secret leaks, and design-token violations").version(VERSION).option("--framework <name>", "framework multiplier to apply").option("--include <glob>", "include pattern (repeatable)", collectGlob, []).option("--exclude <glob>", "exclude pattern (repeatable)", collectGlob, []).option("--ai-only", "only report AI-specific issues").option("--human-only", "only report human-facing issues").option("--ignore-wcag22", "ignore WCAG 2.2 related issues").option("--format <pretty|json|sarif|html>", "output format", "pretty").option("--threads <n>", "number of worker threads", parseThreads).option("--since <ref>", "only scan files changed since git ref").option("--diff <ref>", "alias for --since <ref>; also adds PR Slop Score to the report").option("--workspace <path>", "workspace/project path", process.cwd()).option("--tighten", "tighten baseline allowances").option("--fix", "apply auto-fixes").option("--dry-run", "with --fix: print what would change without writing").option("--show-fixes-diff", "print unified diff of proposed auto-fixes").option("--doctor", "run diagnostics").option("--watch", "watch files and re-run").option("--suggest", "print remediation advice").option("--why-failing", "print the top 5 rules dragging the score down").option("--brief", "terse output (verdict + headline + threshold + delta only)").option("--heatmap", "print migration ROI heatmap").option("--quiet", "suppress non-error output").option("--verbose", "enable debug logging (file paths, timings, rule-fire counts)").option("--strict", "exit 2 if any high-severity issue remains").option("--no-increase", "exit 2 if slop index increased since last run").option("--baseline", "save a baseline after this scan").option("--trend [n]", "print a sparkline of the last n runs", parseTrend).option("--json [path]", "write JSON report to path or stdout").option("--html [path]", "write HTML report to path or stdout").option("--staged", "scan only changed files (staged and unstaged)").option("--changed", "scan working-tree changes (staged + unstaged + untracked)").option("--incremental", "skip unchanged files using the persisted hash cache").option("--cache-path <path>", "path to the incremental-scan cache (default: .slopbrick-cache.json)").option("--tokens <path>", "merge tokens.json layout values into the arbitrary-value allowlist").option("--cache", "cache parsed AST results locally").option("--no-color", "suppress ANSI color codes in output").option("--security-only", "run only the security/* rules").option("--full", "show the complete report (all issues, all categories)");
+    program.helpInformation = () => formatGroupedHelp(program);
     registerInit(program);
     registerInstall(program);
     registerUninstall(program);
@@ -58347,6 +58481,11 @@ async function runCli({ start }) {
     registerTokens(program);
     registerReport(program);
     registerScan(program, scanAction);
+    if (process.argv.includes("--help-flat")) {
+      delete program.helpInformation;
+      program.outputHelp();
+      process.exit(0);
+    }
     await program.parseAsync(process.argv);
   } catch (err) {
     if (err instanceof ConfigValidationError) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slopbrick",
-  "version": "0.18.3",
+  "version": "0.18.4",
   "description": "Discovered, modeled, and governed repository structure. SlopBrick scans source code, classifies it against 95 rules in 15 categories, computes 4 scores (aiQuality, engineeringHygiene, security, repositoryHealth), and persists the structure for AI agents and CI.",
   "type": "module",
   "bin": {