unguard 0.8.0 → 0.9.0

package/README.md

@@ -25,31 +25,71 @@ npx unguard
 ## Usage
 
 ```bash
-unguard src
-unguard src --strict                  # treat warnings as errors (CI)
-unguard src --filter no-any-cast      # run a single rule
-unguard src --severity=error          # only show errors
-unguard src --severity=error,warning  # errors and warnings only
-unguard src --format=flat             # one-line-per-diagnostic, grepable
+unguard src                                  # scan files/directories
+unguard src --config ./unguard.config.json   # load config
+unguard src --ignore '**/*.gen.ts'           # add ignore globs
+unguard src --filter no-any-cast             # run a single rule
+unguard src --rule duplicate-*=warning       # override rule severity/policy
+unguard src --rule category:cross-file=warning
+unguard src --rule tag:safety=error
+unguard src --severity=error,warning         # show errors+warnings
+unguard src --fail-on=error                  # fail only on errors
+unguard src --format=flat                    # one-line-per-diagnostic, grepable
 unguard src --format=flat | grep error
 ```
 
 Add `unguard` to your lint check, especially if code is written by AI.
 
+### Config
+
+`unguard` automatically loads `./unguard.config.json` (or `./.unguardrc.json`). Use `--config <path>` to specify another file.
+
+```json
+{
+  "paths": ["src", "apps/web/src"],
+  "ignore": ["**/*.gen.ts", "**/routeTree.gen.ts"],
+  "rules": {
+    "duplicate-*": "warning",
+    "category:cross-file": "warning",
+    "tag:safety": "error",
+    "no-ts-ignore": "error",
+    "prefer-*": "off"
+  },
+  "failOn": "error"
+}
+```
+
+`rules` values can be `off`, `info`, `warning`, or `error`.
+Selectors support:
+- exact rule id: `no-ts-ignore`
+- wildcard: `duplicate-*`
+- category: `category:cross-file`
+- tag: `tag:safety`
+
+### Ignore behavior
+
+`unguard` ignores:
+- built-in: `node_modules`, `dist`, `.git`, declaration files (`*.d.ts`, `*.d.cts`, `*.d.mts`)
+- generated files: `*.gen.*`, `*.generated.*`
+- project `.gitignore`
+- anything passed via `--ignore` or config `ignore`
+
 ### Exit codes
 
 | Code | Meaning |
 | ---- | ------- |
-| 0 | No issues |
-| 1 | Warnings or info only |
-| 2 | At least one error |
+| 0 | No issues, or issues below `--fail-on` threshold |
+| 1 | Failing diagnostics without errors |
+| 2 | Failing diagnostics with at least one error |
 
-Use `--severity=error` in CI to only fail on errors:
+Use `--fail-on=error` in CI to fail only on errors while still showing all diagnostics:
 
 ```bash
-unguard src --severity=error || exit 1
+unguard src --fail-on=error
 ```
 
+`--severity` filters display only. `--fail-on` evaluates all diagnostics after rule policy.
+
 ### Output formats
 
 **Grouped** (default) -- diagnostics grouped by file:
@@ -112,10 +152,10 @@ These rules use the TypeScript type checker. Non-nullable types suppress the dia
 
 | Rule | Severity | What it catches |
 | ---- | -------- | --------------- |
-| `duplicate-type-declaration` | error | Same type shape in multiple files |
-| `duplicate-type-name` | error | Same exported type name, different shapes |
-| `duplicate-function-declaration` | error | Same function body in multiple files |
-| `duplicate-function-name` | error | Same exported function name, different bodies |
+| `duplicate-type-declaration` | warning | Same type shape in multiple files |
+| `duplicate-type-name` | warning | Same exported type name, different shapes |
+| `duplicate-function-declaration` | warning | Same function body in multiple files |
+| `duplicate-function-name` | warning | Same exported function name, different bodies |
 | `optional-arg-always-used` | warning | Optional param provided at every call site |
 | `explicit-null-arg` | warning | `fn(null)` / `fn(undefined)` to project functions |
 
@@ -141,10 +181,24 @@ file.ts:2:31 error Explicit `any` annotation ... (intentional escape hatch for u
 ## API
 
 ```typescript
-import { scan } from "unguard";
-
-const result = await scan({ paths: ["src/"] });
-for (const d of result.diagnostics) {
+import { executeScan, scan } from "unguard";
+
+const result = await scan({ paths: ["src/"] }); // raw diagnostics
+const execution = await executeScan({
+  paths: ["src"],
+  ignore: ["**/*.gen.ts"],
+  rulePolicy: {
+    "duplicate-*": "warning",
+    "category:cross-file": "warning",
+    "tag:safety": "error",
+    "prefer-*": "off",
+  },
+  showSeverities: ["error", "warning"],
+  failOn: "error",
+});
+
+console.log(execution.exitCode);
+for (const d of execution.visibleDiagnostics) {
   console.log(`${d.file}:${d.line} [${d.ruleId}] ${d.message}`);
 }
 ```

package/dist/{chunk-YYX4R25B.js → chunk-I4RZLVE2.js}

@@ -630,7 +630,7 @@ var preferRequiredParamWithGuard = {
 // src/rules/cross-file/duplicate-type-declaration.ts
 var duplicateTypeDeclaration = {
   id: "duplicate-type-declaration",
-  severity: "error",
+  severity: "warning",
   message: "Identical type shape declared in multiple files; consolidate to a single definition",
   analyze(project) {
     const diagnostics = [];
@@ -658,7 +658,7 @@ var duplicateTypeDeclaration = {
 import * as ts19 from "typescript";
 var duplicateFunctionDeclaration = {
   id: "duplicate-function-declaration",
-  severity: "error",
+  severity: "warning",
   message: "Identical function body declared in multiple files; consolidate to a single definition",
   analyze(project) {
     const diagnostics = [];
@@ -862,7 +862,7 @@ import { dirname, resolve } from "path";
 var EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
 var duplicateFunctionName = {
   id: "duplicate-function-name",
-  severity: "error",
+  severity: "warning",
   message: "Same function name exported from multiple files; consolidate or rename to avoid ambiguity",
   analyze(project) {
     const diagnostics = [];
@@ -911,7 +911,7 @@ function resolveCandidates(fromFile, specifier) {
   const candidates = [base];
   for (const ext of EXTENSIONS) {
     candidates.push(base + ext);
-    candidates.push(resolve(base, "index" + ext));
+    candidates.push(resolve(base, `index${ext}`));
   }
   return candidates;
 }
@@ -920,7 +920,7 @@ function resolveCandidates(fromFile, specifier) {
 import * as ts23 from "typescript";
 var duplicateTypeName = {
   id: "duplicate-type-name",
-  severity: "error",
+  severity: "warning",
   message: "Same type name exported from multiple files; consolidate or rename to avoid ambiguity",
   analyze(project) {
     const diagnostics = [];
@@ -991,15 +991,93 @@ var allRules = [
   duplicateTypeName,
   noDynamicImport
 ];
+var ruleMetadata = {
+  "no-any-cast": { category: "type-evasion", tags: ["safety"] },
+  "no-explicit-any-annotation": { category: "type-evasion", tags: ["safety"] },
+  "no-type-assertion": { category: "type-evasion", tags: ["safety"] },
+  "no-ts-ignore": { category: "type-evasion", tags: ["safety"] },
+  "no-optional-property-access": { category: "defensive-code", tags: ["type-aware"] },
+  "no-optional-element-access": { category: "defensive-code", tags: ["type-aware"] },
+  "no-optional-call": { category: "defensive-code", tags: ["type-aware"] },
+  "no-nullish-coalescing": { category: "defensive-code", tags: ["type-aware"] },
+  "no-logical-or-fallback": { category: "defensive-code", tags: ["type-aware"] },
+  "no-null-ternary-normalization": { category: "defensive-code", tags: ["type-aware"] },
+  "no-non-null-assertion": { category: "defensive-code", tags: ["type-aware"] },
+  "no-double-negation-coercion": { category: "defensive-code", tags: ["readability"] },
+  "no-redundant-existence-guard": { category: "defensive-code", tags: ["type-aware"] },
+  "no-empty-catch": { category: "error-handling", tags: ["safety"] },
+  "no-catch-return": { category: "error-handling", tags: ["safety"] },
+  "no-error-rewrap": { category: "error-handling", tags: ["safety"] },
+  "no-inline-type-in-params": { category: "interface-design", tags: ["api"] },
+  "prefer-default-param-value": { category: "interface-design", tags: ["api"] },
+  "prefer-required-param-with-guard": { category: "interface-design", tags: ["api"] },
+  "duplicate-type-declaration": { category: "cross-file", tags: ["duplicate"] },
+  "duplicate-type-name": { category: "cross-file", tags: ["duplicate"] },
+  "duplicate-function-declaration": { category: "cross-file", tags: ["duplicate"] },
+  "duplicate-function-name": { category: "cross-file", tags: ["duplicate"] },
+  "optional-arg-always-used": { category: "cross-file", tags: ["api"] },
+  "explicit-null-arg": { category: "cross-file", tags: ["api"] },
+  "no-dynamic-import": { category: "imports", tags: ["safety"] }
+};
+function getRuleMetadata(ruleId) {
+  const metadata = ruleMetadata[ruleId];
+  if (metadata !== void 0) return metadata;
+  return { category: "cross-file", tags: [] };
+}
 
-// src/engine.ts
-import fg from "fast-glob";
-import { readFileSync as readFileSync2 } from "fs";
-
-// src/rules/types.ts
-function isTSRule(r) {
-  return "kind" in r && r.kind === "ts";
+// src/scan/config.ts
+var BUILTIN_IGNORE = [
+  "**/node_modules/**",
+  "**/dist/**",
+  "**/.git/**",
+  "**/*.d.ts",
+  "**/*.d.cts",
+  "**/*.d.mts"
+];
+var GENERATED_IGNORE = [
+  "**/*.gen.*",
+  "**/*.generated.*"
+];
+var DEFAULT_FAIL_ON = "info";
+function resolveScanConfig(options) {
+  const paths = options.paths.length > 0 ? options.paths : ["."];
+  const ignore2 = [...BUILTIN_IGNORE, ...GENERATED_IGNORE, ...options.ignore ?? []];
+  return {
+    paths,
+    strict: options.strict ?? false,
+    rules: options.rules ? [...options.rules] : null,
+    ignore: ignore2,
+    rulePolicy: toRulePolicyEntries(options.rulePolicy),
+    showSeverities: normalizeSeveritySet(options.showSeverities),
+    failOn: options.failOn ?? DEFAULT_FAIL_ON,
+    useGitIgnore: options.useGitIgnore ?? true
+  };
+}
+function toRulePolicyEntries(policy) {
+  if (policy === void 0) return [];
+  if (Array.isArray(policy)) return [...policy];
+  const entries = [];
+  for (const [selector, severity] of Object.entries(policy)) {
+    entries.push({ selector, severity });
+  }
+  return entries;
 }
+function normalizeSeveritySet(levels) {
+  if (levels === void 0 || levels.length === 0) return null;
+  return new Set(levels);
+}
+function isRulePolicySeverity(value) {
+  return value === "off" || value === "info" || value === "warning" || value === "error";
+}
+function isSeverity(value) {
+  return value === "info" || value === "warning" || value === "error";
+}
+function isFailOn(value) {
+  return value === "none" || isSeverity(value);
+}
+
+// src/scan/analyze.ts
+import { readFileSync as readFileSync2 } from "fs";
 
 // src/collect/index.ts
 import * as ts26 from "typescript";
@@ -1299,6 +1377,11 @@ function collectAllComments(sourceFile) {
   return comments;
 }
 
+// src/rules/types.ts
+function isTSRule(r) {
+  return "kind" in r && r.kind === "ts";
+}
+
 // src/typecheck/program.ts
 import * as ts27 from "typescript";
 import { dirname as dirname2 } from "path";
@@ -1388,86 +1471,67 @@ function buildContext(rule, sourceFile, checker, source, filename, diagnostics)
   };
 }
 
-// src/engine.ts
-async function scan(options) {
-  const patterns = options.paths.length > 0 ? options.paths : ["."];
-  const globs = patterns.map((p) => {
-    if (p === ".") return `./**/*.{ts,cts,mts,tsx}`;
-    if (p.endsWith("/")) return `${p}**/*.{ts,cts,mts,tsx}`;
-    if (!p.includes("*") && !p.endsWith(".ts") && !p.endsWith(".tsx") && !p.endsWith(".cts") && !p.endsWith(".mts")) {
-      return `${p}/**/*.{ts,cts,mts,tsx}`;
-    }
-    return p;
-  });
-  const files = await fg(globs, {
-    ignore: ["**/node_modules/**", "**/dist/**", "**/.git/**", "**/*.d.ts", "**/*.d.cts", "**/*.d.mts"],
-    absolute: true
-  });
-  const activeRules = allRules.filter((r) => {
-    if (options.rules && !options.rules.includes(r.id)) return false;
-    return true;
-  });
-  const tsRules = activeRules.filter(isTSRule);
-  const crossFileRules = activeRules.filter((r) => !isTSRule(r));
+// src/scan/analyze.ts
+function analyzeFiles(files, rules) {
+  const tsRules = rules.filter(isTSRule);
+  const crossFileRules = rules.filter((r) => !isTSRule(r));
   const diagnostics = [];
   const program = files.length > 0 ? createProgramFromFiles(files) : null;
-  if (tsRules.length > 0 && program) {
+  if (!program) return diagnostics;
+  if (tsRules.length > 0) {
     const checker = program.getTypeChecker();
     for (const file of files) {
       const source = readFileSync2(file, "utf8");
       const sourceFile = program.getSourceFile(file);
       if (sourceFile) {
-        const tsDiags = runTSRules(tsRules, sourceFile, checker, source, file);
-        diagnostics.push(...tsDiags);
+        diagnostics.push(...runTSRules(tsRules, sourceFile, checker, source, file));
       }
     }
   }
-  if (crossFileRules.length > 0 && program) {
+  if (crossFileRules.length > 0) {
     const projectIndex = collectProject(program);
     for (const rule of crossFileRules) {
-      const crossDiags = rule.analyze(projectIndex);
-      for (const d of crossDiags) {
-        const fileData = projectIndex.files.get(d.file);
-        if (fileData !== void 0) annotate([d], fileData.comments, fileData.source);
+      const crossDiagnostics = rule.analyze(projectIndex);
+      for (const diagnostic of crossDiagnostics) {
+        const fileData = projectIndex.files.get(diagnostic.file);
+        if (fileData !== void 0) annotate([diagnostic], fileData.comments, fileData.source);
       }
-      diagnostics.push(...crossDiags);
+      diagnostics.push(...crossDiagnostics);
     }
   }
+  return dedupeDiagnostics(diagnostics);
+}
+function dedupeDiagnostics(diagnostics) {
   const seen = /* @__PURE__ */ new Set();
   const deduped = [];
-  for (const d of diagnostics) {
-    const key = `${d.file}:${d.line}:${d.ruleId}`;
+  for (const diagnostic of diagnostics) {
+    const key = `${diagnostic.file}:${diagnostic.line}:${diagnostic.ruleId}`;
     if (seen.has(key)) continue;
     seen.add(key);
-    deduped.push(d);
-  }
-  if (options.strict) {
-    for (const d of deduped) {
-      d.severity = "error";
-    }
+    deduped.push(diagnostic);
   }
-  return { diagnostics: deduped, fileCount: files.length };
+  return deduped;
 }
 function annotate(diagnostics, comments, source) {
   if (comments.length === 0 || diagnostics.length === 0) return;
   const byEndLine = /* @__PURE__ */ new Map();
-  for (const c of comments) {
-    const endLine = lineAt(source, c.end);
+  for (const comment of comments) {
+    const endLine = lineAt(source, comment.end);
     let list = byEndLine.get(endLine);
     if (list === void 0) {
       list = [];
       byEndLine.set(endLine, list);
     }
-    list.push(c);
+    list.push(comment);
   }
-  for (const d of diagnostics) {
-    const inline = findInlineComment(d.line, byEndLine);
+  for (const diagnostic of diagnostics) {
+    const inline = findInlineComment(diagnostic.line, byEndLine);
     if (inline !== null) {
-      d.annotation = inline;
+      diagnostic.annotation = inline;
       continue;
     }
-    const above = collectAnnotation(d.line - 1, byEndLine, source);
-    if (above !== null) d.annotation = above;
+    const above = collectAnnotation(diagnostic.line - 1, byEndLine, source);
+    if (above !== null) diagnostic.annotation = above;
   }
 }
 function findInlineComment(diagLine, byEndLine) {
@@ -1485,9 +1549,7 @@ function collectAnnotation(commentEndLine, byEndLine, source) {
   if (commentsOnLine === void 0 || commentsOnLine.length === 0) return null;
   const comment = commentsOnLine.at(-1);
   if (comment === void 0) return null;
-  if (comment.type === "Block") {
-    return cleanBlockComment(comment.value);
-  }
+  if (comment.type === "Block") return cleanBlockComment(comment.value);
   const lines = [comment.value.trim()];
   let prevLine = commentEndLine - 1;
   for (; ; ) {
@@ -1512,8 +1574,145 @@ function lineAt(source, offset) {
   return line;
 }
 
+// src/scan/discover.ts
+import fg from "fast-glob";
+import ignore from "ignore";
+import { existsSync, readFileSync as readFileSync3 } from "fs";
+import { relative, resolve as resolve2, sep } from "path";
+async function discoverFiles(config) {
+  const globs = expandGlobs(config.paths);
+  const discoveredFiles = await fg(globs, {
+    ignore: config.ignore,
+    absolute: true
+  });
+  if (!config.useGitIgnore) return discoveredFiles;
+  return applyGitIgnore(discoveredFiles);
+}
+function expandGlobs(paths) {
+  return paths.map((p) => {
+    if (p === ".") return "./**/*.{ts,cts,mts,tsx}";
+    if (p.endsWith("/")) return `${p}**/*.{ts,cts,mts,tsx}`;
+    if (!p.includes("*") && !p.endsWith(".ts") && !p.endsWith(".tsx") && !p.endsWith(".cts") && !p.endsWith(".mts")) {
+      return `${p}/**/*.{ts,cts,mts,tsx}`;
+    }
+    return p;
+  });
+}
+function applyGitIgnore(files) {
+  const gitIgnorePath = resolve2(process.cwd(), ".gitignore");
+  if (!existsSync(gitIgnorePath)) return files;
+  const matcher = ignore().add(readFileSync3(gitIgnorePath, "utf8"));
+  return files.filter((file) => {
+    const rel = relative(process.cwd(), file);
+    if (rel.startsWith("..")) return true;
+    const normalized = rel.split(sep).join("/");
+    return !matcher.ignores(normalized);
+  });
+}
+
+// src/scan/policy.ts
+function buildRuleDescriptors(rules) {
+  return rules.map((rule) => {
+    const metadata = getRuleMetadata(rule.id);
+    return {
+      rule,
+      category: metadata.category,
+      tags: metadata.tags
+    };
+  });
+}
+function resolveActiveRules(descriptors, config) {
+  const selectedRules = config.rules ? new Set(config.rules) : null;
+  const active = [];
+  for (const descriptor of descriptors) {
+    if (selectedRules && !selectedRules.has(descriptor.rule.id)) continue;
+    const resolvedSeverity = resolveRuleSeverity(descriptor, config);
+    if (resolvedSeverity === "off") continue;
+    if (descriptor.rule.severity === resolvedSeverity) {
+      active.push(descriptor.rule);
+      continue;
+    }
+    active.push({ ...descriptor.rule, severity: resolvedSeverity });
+  }
+  return active;
+}
+function resolveRuleSeverity(descriptor, config) {
+  let severity = descriptor.rule.severity;
+  for (const entry of config.rulePolicy) {
+    if (!matchesSelector(descriptor, entry.selector)) continue;
+    severity = entry.severity;
+  }
+  if (severity === "off") return "off";
+  if (config.strict) return "error";
+  return severity;
+}
+function matchesSelector(descriptor, selector) {
+  if (selector.startsWith("category:")) {
+    return descriptor.category === selector.slice("category:".length);
+  }
+  if (selector.startsWith("tag:")) {
+    return descriptor.tags.includes(selector.slice("tag:".length));
+  }
+  if (selector === descriptor.rule.id) return true;
+  if (!selector.includes("*")) return false;
+  const regex = new RegExp(`^${escapeRegex(selector).replaceAll("\\*", ".*")}$`);
+  return regex.test(descriptor.rule.id);
+}
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function finalizeScanResult(diagnostics, fileCount, config) {
+  const visibleDiagnostics = config.showSeverities ? diagnostics.filter((d) => config.showSeverities?.has(d.severity)) : diagnostics;
+  return {
+    diagnostics,
+    visibleDiagnostics,
+    fileCount,
+    exitCode: computeExitCode(diagnostics, config.failOn)
+  };
+}
+function toScanResult(execution) {
+  return {
+    diagnostics: execution.diagnostics,
+    fileCount: execution.fileCount
+  };
+}
+function computeExitCode(diagnostics, failOn) {
+  if (failOn === "none") return 0;
+  const hasError = diagnostics.some((d) => d.severity === "error");
+  const hasWarning = diagnostics.some((d) => d.severity === "warning");
+  const hasInfo = diagnostics.some((d) => d.severity === "info");
+  if (failOn === "error") return hasError ? 2 : 0;
+  if (failOn === "warning") {
+    if (hasError) return 2;
+    return hasWarning ? 1 : 0;
+  }
+  if (hasError) return 2;
+  if (hasWarning || hasInfo) return 1;
+  return 0;
+}
+
+// src/engine.ts
+async function executeScan(options) {
+  const config = resolveScanConfig(options);
+  const files = await discoverFiles(config);
+  const descriptors = buildRuleDescriptors(allRules);
+  const activeRules = resolveActiveRules(descriptors, config);
+  const diagnostics = analyzeFiles(files, activeRules);
+  return finalizeScanResult(diagnostics, files.length, config);
+}
+async function scan(options) {
+  const execution = await executeScan(options);
+  return toScanResult(execution);
+}
+
 export {
   allRules,
+  getRuleMetadata,
+  toRulePolicyEntries,
+  isRulePolicySeverity,
+  isSeverity,
+  isFailOn,
+  executeScan,
   scan
 };
-//# sourceMappingURL=chunk-YYX4R25B.js.map
+//# sourceMappingURL=chunk-I4RZLVE2.js.map