unguard 0.15.1 → 0.15.2

package/README.md

@@ -36,6 +36,8 @@ 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
+unguard src --concurrency 1                  # disable worker-thread parallelism
+unguard src --no-cache                       # bypass on-disk diagnostic cache
 ```
 
 Add `unguard` to your lint check, especially if code is written by AI.
@@ -56,12 +58,15 @@ Add `unguard` to your lint check, especially if code is written by AI.
     "no-ts-ignore": "error",
     "prefer-*": "off"
   },
-  "failOn": "error"
+  "failOn": "error",
+  "concurrency": 4,
+  "cache": true
 }
 ```
 
 `rules` values can be `off`, `info`, `warning`, or `error`.
 Selectors support:
+
 - exact rule id: `no-ts-ignore`
 - wildcard: `duplicate-*`
 - category: `category:cross-file`
@@ -70,6 +75,7 @@ Selectors support:
 ### Ignore behavior
 
 `unguard` ignores:
+
 - built-in: `node_modules`, `dist`, `.git`, declaration files (`*.d.ts`, `*.d.cts`, `*.d.mts`)
 - generated files: `*.gen.*`, `*.generated.*`
 - project `.gitignore`
@@ -232,6 +238,21 @@ for (const d of execution.visibleDiagnostics) {
 }
 ```
 
+### Caching
+
+unguard caches scan results under `node_modules/.cache/unguard/`. On a warm
+run, if every file's content hash and the active rule set are unchanged,
+unguard returns cached diagnostics without building a TypeScript program.
+The cache invalidates automatically on:
+
+- file content changes (mtime-only changes are ignored — `git checkout` and `git stash` stay cache hits)
+- changes to active rules or rule severities
+- changes to scan paths, ignore globs, or `failOn`
+- unguard version upgrades
+
+Disable with `--no-cache` (CLI), `cache: false` (config), or pass
+`cache: false` to `executeScan({ cache: false })` programmatically.
+
 ## License
 
 MIT

package/dist/{chunk-VHRD75ET.js → chunk-BLCVXVLX.js}

@@ -1,3 +1,37 @@
+// src/rules/types.ts
+function isTSRule(r) {
+  return "kind" in r && r.kind === "ts";
+}
+function reportDuplicateGroup(group, ruleId, severity, formatOther, formatMessage, diagnostics, context) {
+  const sorted = [...group].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+  const entries = selectDuplicateReportEntries(sorted, context.reportableFiles);
+  for (const entry of entries) {
+    const others = sorted.filter((e) => e !== entry).map(formatOther).join(", ");
+    diagnostics.push({
+      ruleId,
+      severity,
+      message: formatMessage(entry, others),
+      file: entry.file,
+      line: entry.line,
+      column: 1
+    });
+  }
+}
+function selectReportTarget(group, reportableFiles) {
+  const sorted = [...group].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+  if (reportableFiles === void 0) return sorted[0];
+  return sorted.find((entry) => reportableFiles.has(entry.file));
+}
+function selectDuplicateReportEntries(sorted, reportableFiles) {
+  const defaultEntries = sorted.slice(1);
+  if (reportableFiles === void 0) return defaultEntries;
+  const reportableDefaultEntries = defaultEntries.filter((entry) => reportableFiles.has(entry.file));
+  if (reportableDefaultEntries.length > 0) return reportableDefaultEntries;
+  const first = sorted[0];
+  if (first !== void 0 && sorted.length > 1 && reportableFiles.has(first.file)) return [first];
+  return [];
+}
+
 // src/rules/cross-file/dead-overload.ts
 import * as ts from "typescript";
 var deadOverload = {
@@ -170,40 +204,6 @@ function normalizeText(text) {
   return text.replace(/\s+/g, "");
 }
 
-// src/rules/types.ts
-function isTSRule(r) {
-  return "kind" in r && r.kind === "ts";
-}
-function reportDuplicateGroup(group, ruleId, severity, formatOther, formatMessage, diagnostics, context) {
-  const sorted = [...group].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
-  const entries = selectDuplicateReportEntries(sorted, context.reportableFiles);
-  for (const entry of entries) {
-    const others = sorted.filter((e) => e !== entry).map(formatOther).join(", ");
-    diagnostics.push({
-      ruleId,
-      severity,
-      message: formatMessage(entry, others),
-      file: entry.file,
-      line: entry.line,
-      column: 1
-    });
-  }
-}
-function selectReportTarget(group, reportableFiles) {
-  const sorted = [...group].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
-  if (reportableFiles === void 0) return sorted[0];
-  return sorted.find((entry) => reportableFiles.has(entry.file));
-}
-function selectDuplicateReportEntries(sorted, reportableFiles) {
-  const defaultEntries = sorted.slice(1);
-  if (reportableFiles === void 0) return defaultEntries;
-  const reportableDefaultEntries = defaultEntries.filter((entry) => reportableFiles.has(entry.file));
-  if (reportableDefaultEntries.length > 0) return reportableDefaultEntries;
-  const first = sorted[0];
-  if (first !== void 0 && sorted.length > 1 && reportableFiles.has(first.file)) return [first];
-  return [];
-}
-
 // src/rules/cross-file/duplicate-constant-declaration.ts
 var duplicateConstantDeclaration = {
   id: "duplicate-constant-declaration",
@@ -2389,57 +2389,6 @@ function getRuleMetadata(ruleId) {
   return { category: "cross-file", tags: [] };
 }
 
-// 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 } from "fs";
 
@@ -3484,9 +3433,8 @@ function createCachedCompilerHost(options, cache) {
   };
   return host;
 }
-function isStableCachedSourceFile(fileName) {
-  const normalized = fileName.replaceAll("\\", "/");
-  return normalized.includes("/node_modules/") || /\.d\.[cm]?ts$/.test(normalized) || normalized.endsWith(".json");
+function isStableCachedSourceFile(_fileName) {
+  return true;
 }
 function sourceFileCacheKey(fileKey, languageVersionOrOptions) {
   if (typeof languageVersionOrOptions !== "object") {
@@ -3566,8 +3514,80 @@ function createProgramForGroup(group, options) {
   return createProgramForConfig(rootFiles, group.configPath, options.cache);
 }
 
+// src/scan/worker-pool.ts
+import { existsSync as existsSync2 } from "fs";
+import { Worker } from "worker_threads";
+import { fileURLToPath } from "url";
+var WORKER_URL = new URL("./worker.js", import.meta.url);
+function workersAvailable() {
+  return existsSync2(fileURLToPath(WORKER_URL));
+}
+async function runGroupsInWorkers(tasks, ruleSpecs, indexNeeds, concurrency) {
+  if (tasks.length === 0) return [];
+  const ordered = [...tasks].sort((a, b) => b.groupConfig.scanFiles.length - a.groupConfig.scanFiles.length);
+  const workerCount = Math.min(concurrency, ordered.length);
+  const workers = [];
+  const results = new Array(tasks.length);
+  for (let i = 0; i < tasks.length; i++) results[i] = [];
+  let nextIndex = 0;
+  let remaining = ordered.length;
+  let firstError = null;
+  await new Promise((resolve2, reject) => {
+    function finishOne() {
+      remaining--;
+      if (remaining === 0) {
+        if (firstError !== null) reject(firstError);
+        else resolve2();
+      }
+    }
+    function dispatchNext(worker) {
+      if (nextIndex >= ordered.length) return;
+      const task = ordered[nextIndex];
+      if (task === void 0) return;
+      nextIndex++;
+      const req = {
+        taskId: task.id,
+        groupConfig: task.groupConfig,
+        ruleSpecs,
+        indexNeeds
+      };
+      worker.postMessage(req);
+    }
+    for (let i = 0; i < workerCount; i++) {
+      const worker = new Worker(fileURLToPath(WORKER_URL));
+      workers.push(worker);
+      worker.on("message", (response) => {
+        if (response.ok) {
+          results[response.taskId] = response.diagnostics;
+        } else if (firstError === null) {
+          firstError = new Error(`unguard worker error: ${response.error}`);
+        }
+        finishOne();
+        dispatchNext(worker);
+      });
+      worker.on("error", (err) => {
+        if (firstError === null) {
+          firstError = err instanceof Error ? err : new Error(String(err));
+        }
+        finishOne();
+      });
+      worker.on("exit", (code) => {
+        if (remaining > 0 && code !== 0 && firstError === null) {
+          firstError = new Error(`unguard worker exited with code ${code}`);
+          finishOne();
+        }
+      });
+      dispatchNext(worker);
+    }
+  }).finally(() => {
+    for (const w of workers) w.terminate().catch(() => {
+    });
+  });
+  return results;
+}
+
 // src/scan/analyze.ts
-function analyzeFiles(files, rules) {
+async function analyzeFiles(files, rules, options) {
   const tsRules = rules.filter(isTSRule);
   const crossFileRules = rules.filter((r) => !isTSRule(r));
   const indexNeeds = collectIndexNeeds(crossFileRules);
@@ -3576,24 +3596,46 @@ function analyzeFiles(files, rules) {
   }
   const groupConfigs = mergeCompatibleGroups(groupFilesByTsconfig(files));
   if (groupConfigs.length === 0) return [];
-  const allDiagnostics = [];
-  const allFiles = /* @__PURE__ */ new Map();
+  const concurrency = resolveConcurrency(options.concurrency, groupConfigs.length);
+  if (concurrency > 1 && groupConfigs.length > 1 && workersAvailable()) {
+    return await runGroupsViaWorkers(groupConfigs, rules, indexNeeds, concurrency);
+  }
+  return runGroupsSerial(groupConfigs, tsRules, crossFileRules, indexNeeds);
+}
+function runGroupsSerial(groupConfigs, tsRules, crossFileRules, indexNeeds) {
   const programCache = createProgramBuildCache();
+  const allDiagnostics = [];
   for (const groupConfig of groupConfigs) {
-    const projectIndex = createProjectIndex();
-    const program = createProgramForGroup(groupConfig, { expandProjectFiles: true, cache: programCache });
-    const allowed = new Set(groupConfig.scanFiles);
-    const collectFiles = indexNeeds.size > 0 ? new Set(expandProjectFiles(groupConfig).filter(isAnalyzableSourcePath)) : /* @__PURE__ */ new Set();
-    const { diagnostics } = collectProject(program, tsRules, allowed, {
-      collectFiles,
-      needs: indexNeeds,
-      index: projectIndex
-    });
-    allDiagnostics.push(...diagnostics);
-    allDiagnostics.push(...runCrossFileRules(crossFileRules, projectIndex, allowed));
-    addFileData(allFiles, projectIndex, allowed);
+    const groupDiags = analyzeGroup(groupConfig, tsRules, crossFileRules, indexNeeds, programCache);
+    allDiagnostics.push(...groupDiags);
   }
-  return finalizeDiagnostics(allDiagnostics, allFiles);
+  return dedupeDiagnostics(allDiagnostics);
+}
+async function runGroupsViaWorkers(groupConfigs, rules, indexNeeds, concurrency) {
+  const ruleSpecs = rules.map((rule) => ({ id: rule.id, severity: rule.severity }));
+  const tasks = groupConfigs.map((groupConfig, idx) => ({ id: idx, groupConfig }));
+  const diagnosticsByTask = await runGroupsInWorkers(tasks, ruleSpecs, [...indexNeeds], concurrency);
+  const allDiagnostics = [];
+  for (const diags of diagnosticsByTask) {
+    allDiagnostics.push(...diags);
+  }
+  return dedupeDiagnostics(allDiagnostics);
+}
+function analyzeGroup(groupConfig, tsRules, crossFileRules, indexNeeds, programCache) {
+  const projectIndex = createProjectIndex();
+  const program = createProgramForGroup(groupConfig, { expandProjectFiles: true, cache: programCache });
+  const allowed = new Set(groupConfig.scanFiles);
+  const collectFiles = indexNeeds.size > 0 ? new Set(expandProjectFiles(groupConfig).filter(isAnalyzableSourcePath)) : /* @__PURE__ */ new Set();
+  const { diagnostics } = collectProject(program, tsRules, allowed, {
+    collectFiles,
+    needs: indexNeeds,
+    index: projectIndex
+  });
+  const groupDiagnostics = [...diagnostics];
+  groupDiagnostics.push(...runCrossFileRules(crossFileRules, projectIndex, allowed));
+  const fileData = /* @__PURE__ */ new Map();
+  addFileData(fileData, projectIndex, allowed);
+  return finalizeDiagnostics(groupDiagnostics, fileData);
 }
 function analyzeSourceOnlyFiles(files, tsRules, crossFileRules, indexNeeds) {
   const diagnostics = [];
@@ -3685,6 +3727,13 @@ function finalizeDiagnostics(diagnostics, files) {
   }
   return dedupeDiagnostics(finalized);
 }
+function resolveConcurrency(requested, groupCount) {
+  if (requested !== void 0) {
+    if (!Number.isInteger(requested) || requested < 1) return 1;
+    return Math.min(requested, groupCount);
+  }
+  return 1;
+}
 function annotateAndFilter(diagnostics, comments, source) {
   if (diagnostics.length === 0) return diagnostics;
   if (comments.length === 0) return diagnostics;
@@ -3791,145 +3840,11 @@ function lineAt(source, offset) {
   return line;
 }
 
-// src/scan/discover.ts
-import fg from "fast-glob";
-import ignore from "ignore";
-import { existsSync as existsSync2, readFileSync as readFileSync2 } 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 (!existsSync2(gitIgnorePath)) return files;
-  const matcher = ignore().add(readFileSync2(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 {
+  isTSRule,
   allRules,
   getRuleMetadata,
-  toRulePolicyEntries,
-  isRulePolicySeverity,
-  isSeverity,
-  isFailOn,
-  executeScan,
-  scan
+  analyzeFiles,
+  analyzeGroup
 };
-//# sourceMappingURL=chunk-VHRD75ET.js.map
+//# sourceMappingURL=chunk-BLCVXVLX.js.map