pi-lens 3.8.69 → 3.8.70

package/dist/clients/dispatch/rules/framework-call-noise.js

@@ -0,0 +1,67 @@
+/**
+ * Shared test-framework-call recognition for `high-fan-out` and `high-complexity`
+ * (#577). A normal `it()`/`describe()` body naturally invokes many assertion/mock
+ * helpers — that's test structure, not a coordination smell or genuine complexity.
+ *
+ * Two complementary heuristics, both call-name-based (no `ctx.fileRole` gating —
+ * these calls only exist in test-framework code, so the signal is safe to apply
+ * unconditionally):
+ *
+ * 1. `isTestFrameworkNoiseCall` — filters individual "meaningful calls" the same
+ *    way `console.*`/`Math.*`/etc. are already excluded in high-fan-out. Handles
+ *    assertion-heavy `it()` bodies directly.
+ * 2. `isTestSuiteOrganizer` — a `describe()`/`it()`/`test()` wrapper's own
+ *    FunctionSummary aggregates every call and branch from ALL of its nested test
+ *    bodies (the shared tree-sitter walk in function-facts.ts does not stop at
+ *    nested-function boundaries, since each nested callback also gets its own,
+ *    correctly-scoped, FunctionSummary). That aggregation is not real fan-out or
+ *    complexity — it's the sum of independent nested tests. A function is an
+ *    "organizer" if it directly invokes `it`/`test`/`describe` (or their
+ *    `.only`/`.skip`/`.each` variants) — i.e. it exists to group other tests, not
+ *    to implement logic itself. This does NOT exempt genuinely complex/tangled
+ *    test HELPER functions, since those don't call `it`/`describe`/`test`
+ *    themselves.
+ */
+const EXPECT_CHAIN_PREFIX = "expect(";
+const TEST_LIFECYCLE_NAMES = new Set([
+    "it",
+    "test",
+    "describe",
+    "beforeeach",
+    "aftereach",
+    "beforeall",
+    "afterall",
+]);
+const TEST_LIFECYCLE_PREFIXES = ["it.", "test.", "describe."];
+const MOCK_LIBRARY_PREFIXES = ["vi.", "jest."];
+/**
+ * True if `call` (a raw callee string from `FunctionSummary.outgoingCalls`) is
+ * test-framework noise: an `expect(...)` assertion chain, a test lifecycle call
+ * (`it`/`describe`/`test`/`beforeEach`/etc., including `.only`/`.skip`/`.each`
+ * variants), or a mock-library call (`vi.*`/`jest.*`).
+ */
+export function isTestFrameworkNoiseCall(call) {
+    const lower = call.toLowerCase();
+    if (lower === "expect" || lower.startsWith(EXPECT_CHAIN_PREFIX))
+        return true;
+    if (TEST_LIFECYCLE_NAMES.has(lower))
+        return true;
+    if (TEST_LIFECYCLE_PREFIXES.some((p) => lower.startsWith(p)))
+        return true;
+    if (MOCK_LIBRARY_PREFIXES.some((p) => lower.startsWith(p)))
+        return true;
+    return false;
+}
+/**
+ * True if this function's (unfiltered) outgoing calls include a direct call to
+ * `it`/`test`/`describe` — i.e. it groups nested test bodies rather than
+ * implementing logic itself. Its aggregated fan-out/complexity reflects the sum
+ * of independent nested tests, not one function's real signal.
+ */
+export function isTestSuiteOrganizer(calls) {
+    return calls.some((call) => {
+        const lower = call.toLowerCase();
+        const base = lower.split("(")[0].split(".")[0];
+        return base === "it" || base === "test" || base === "describe";
+    });
+}

package/dist/clients/dispatch/rules/high-complexity.js

@@ -1,3 +1,4 @@
+import { isTestSuiteOrganizer } from "./framework-call-noise.js";
 // Defaults match the historical hardcoded values so behavior is unchanged for
 // projects without a config. Project-specific overrides are read from the
 // per-dispatch context; these mutable fallbacks exist for tests/legacy direct
@@ -35,6 +36,16 @@ export const highComplexityRule = {
         const configuredCcThreshold = ctx.projectConfig?.rules["high-complexity"]?.threshold;
         const activeCcThreshold = configuredCcThreshold ?? ccThreshold;
         for (const f of fns) {
+            // A describe()/it()/test() wrapper's own complexity/nesting-depth
+            // aggregates branches from ALL of its nested test bodies (#577) — e.g. a
+            // `for` loop inside each of several `it()`s sums into the enclosing
+            // `describe()`'s cyclomatic complexity, even though no single test is
+            // complex. Unlike high-fan-out's call-name filter, there's no per-call
+            // signal to exclude for branch counting, so the equivalent fix here is to
+            // skip the organizer function itself. Genuinely complex test HELPER
+            // functions don't call it/describe/test themselves, so they're unaffected.
+            if (isTestSuiteOrganizer(f.outgoingCalls))
+                continue;
             const ccBreached = f.cyclomaticComplexity >= activeCcThreshold;
             const depthBreached = f.maxNestingDepth >= depthThreshold;
             if (!ccBreached && !depthBreached)
@@ -46,7 +57,7 @@ export const highComplexityRule = {
                 parts.push(`nesting depth ${f.maxNestingDepth}`);
             diagnostics.push({
                 id: `high-complexity:${ctx.filePath}:${f.line}`,
-                tool: "high-complexity",
+                tool: "fact-rules",
                 rule: "high-complexity",
                 filePath: ctx.filePath,
                 line: f.line,

package/dist/clients/dispatch/rules/high-fan-out.js

@@ -1,3 +1,4 @@
+import { isTestFrameworkNoiseCall, isTestSuiteOrganizer, } from "./framework-call-noise.js";
 // Default matches the historical hardcoded value so behavior is unchanged for
 // projects without a config. Project-specific overrides are read from the
 // per-dispatch context; this mutable fallback exists for tests/legacy direct
@@ -27,7 +28,16 @@ export const highFanOutRule = {
         const configuredFanOutThreshold = ctx.projectConfig?.rules["high-fan-out"]?.threshold;
         const activeFanOutThreshold = configuredFanOutThreshold ?? fanOutThreshold;
         for (const f of fns) {
-            // Filter out noise: utility calls, logging, type assertions
+            // A describe()/it()/test() wrapper's own call list aggregates every call
+            // from ALL of its nested test bodies (#577) — not real fan-out. Genuinely
+            // complex test HELPER functions don't call it/describe/test themselves, so
+            // they're unaffected.
+            if (isTestSuiteOrganizer(f.outgoingCalls))
+                continue;
+            // Filter out noise: utility calls, logging, type assertions, and
+            // test-framework calls (expect/it/describe/vi.*/jest.*, #577) — assertion-
+            // and mock-heavy test bodies naturally call many of these; that's test
+            // structure, not a coordination smell.
             const meaningful = f.outgoingCalls.filter((c) => {
                 const lower = c.toLowerCase();
                 return (!lower.startsWith("console.") &&
@@ -42,13 +52,14 @@ export const highFanOutRule = {
                     c !== "resolve" &&
                     c !== "reject" &&
                     c !== "next" &&
-                    c !== "done");
+                    c !== "done" &&
+                    !isTestFrameworkNoiseCall(c));
             });
             if (meaningful.length < activeFanOutThreshold)
                 continue;
             diagnostics.push({
                 id: `high-fan-out:${ctx.filePath}:${f.line}`,
-                tool: "high-fan-out",
+                tool: "fact-rules",
                 rule: "high-fan-out",
                 filePath: ctx.filePath,
                 line: f.line,

package/dist/clients/dispatch/rules/high-import-coupling.js

@@ -23,7 +23,7 @@ export const highImportCouplingRule = {
         return [
             {
                 id: `high-import-coupling:${ctx.filePath}:1:1`,
-                tool: "high-import-coupling",
+                tool: "fact-rules",
                 rule: "high-import-coupling",
                 filePath: ctx.filePath,
                 line: 1,

package/dist/clients/dispatch/rules/missing-error-propagation.js

@@ -46,7 +46,7 @@ export const missingErrorPropagationRule = {
                     continue;
                 diagnostics.push({
                     id: `missing-error-propagation:${ctx.filePath}:${c.line}`,
-                    tool: "missing-error-propagation",
+                    tool: "fact-rules",
                     rule: "missing-error-propagation",
                     filePath: ctx.filePath,
                     line: c.line,

package/dist/clients/dispatch/rules/no-commented-credentials.js

@@ -34,7 +34,7 @@ export const commentedCredentialsRule = {
                 if (p.test(line)) {
                     diagnostics.push({
                         id: `no-commented-credentials:${ctx.filePath}:${i + 1}`,
-                        tool: "no-commented-credentials",
+                        tool: "fact-rules",
                         rule: "no-commented-credentials",
                         filePath: ctx.filePath,
                         line: i + 1,

package/dist/clients/dispatch/rules/pass-through-wrappers.js

@@ -23,7 +23,7 @@ export const passThroughWrappersRule = {
                 continue;
             diagnostics.push({
                 id: `pass-through-wrapper:${ctx.filePath}:${fn.line}:${fn.column}`,
-                tool: "pass-through-wrappers",
+                tool: "fact-rules",
                 filePath: ctx.filePath,
                 line: fn.line,
                 column: fn.column,

package/dist/clients/dispatch/rules/placeholder-comments.js

@@ -25,7 +25,7 @@ export const placeholderCommentsRule = {
                 continue;
             diagnostics.push({
                 id: `placeholder-comments:${ctx.filePath}:${comment.line}:1`,
-                tool: "placeholder-comments",
+                tool: "fact-rules",
                 filePath: ctx.filePath,
                 line: comment.line,
                 column: 1,

package/dist/clients/dispatch/rules/unsafe-boundary.js

@@ -80,7 +80,7 @@ export const unsafeBoundaryRule = {
                 continue;
             diagnostics.push({
                 id: `unsafe-boundary:${ctx.filePath}:${f.line}`,
-                tool: "unsafe-boundary",
+                tool: "fact-rules",
                 rule: "unsafe-boundary",
                 filePath: ctx.filePath,
                 line: f.line,

package/dist/clients/dispatch/runners/ast-grep-napi.js

@@ -38,14 +38,31 @@ const SUPPORTED_EXTS = [".ts", ".tsx", ".js", ".jsx", ".css", ".html", ".htm"];
 const MAX_MATCHES_PER_RULE = 10;
 /** Maximum total diagnostics per file to prevent output spam */
 const MAX_TOTAL_DIAGNOSTICS = 50;
-/** Rules already covered by tree-sitter runner (priority 14, runs first) */
-const TREE_SITTER_OVERLAP = new Set([
-    "constructor-super",
-    "empty-catch",
-    "long-parameter-list",
-    "nested-ternary",
-    "no-dupe-class-members",
-]);
+/**
+ * #660: this runner used to skip a hardcoded set of rule ids
+ * (`constructor-super`, `empty-catch`, `long-parameter-list`,
+ * `nested-ternary`, `no-dupe-class-members`) on the assumption that the
+ * tree-sitter query runner (priority 14) already covered them, to avoid
+ * double-reporting. That assumption was false for every entry: three of
+ * them (`nested-ternary`, `long-parameter-list`, `no-dupe-class-members`)
+ * have no active tree-sitter query — their would-be queries either live
+ * under `rules/tree-sitter-queries/typescript-disabled/` (excluded from
+ * loading, see clients/tree-sitter-query-loader.ts) or were never written —
+ * so those three rule ids had ZERO coverage in the NAPI fallback runner
+ * (used when the ast-grep binary isn't installed) despite having a
+ * perfectly good, shipped, active ast-grep rule sitting right there. The
+ * other two (`constructor-super`, `empty-catch`) are disabled everywhere
+ * (ast-grep AND tree-sitter, see rules-disabled/, #206), so skipping them
+ * was already a no-op. The whole skip-set has been removed; if tree-sitter
+ * coverage is ever added back for one of these rule ids, reintroduce a
+ * scoped skip alongside the query that actually covers it — don't recreate
+ * a blanket assumption-based list.
+ *
+ * Note: `no-dupe-class-members` didn't actually fire immediately
+ * post-removal — its rule YAML uses a top-level `utils:` block that this
+ * runner's native-config passthrough dropped entirely, a separate bug
+ * (affecting 5 shipped rules, not just this one) fixed in #663.
+ */
 /**
  * Rules commonly covered by ESLint/Biome correctness checks.
  * We can suppress these from ast-grep in lint-enabled projects to reduce noise.
@@ -103,6 +120,32 @@ function normalizeRuleId(ruleId) {
 export function canHandle(filePath) {
     return SUPPORTED_EXTS.includes(path.extname(filePath).toLowerCase());
 }
+/**
+ * The TypeScript grammar is a syntactic superset of JavaScript, so a
+ * `JavaScript`-tagged rule using generic node kinds (`variable_declarator`,
+ * `assignment_expression`, …) still matches against a parsed `.ts`/`.tsx`
+ * root — and vice versa isn't an issue since JS files never parse
+ * TS-only syntax, but a `TypeScript`-tagged rule with a plain-JS-compatible
+ * body would equally double-fire alongside a `JavaScript` twin on a `.ts`
+ * file. Without this, `language:` reads as a real filter but isn't one for
+ * ts↔js pairs, so twin rules sharing a base name (e.g. `hardcoded-url` /
+ * `hardcoded-url-js`) both match the same construct in the SAME runner
+ * invocation (#657). Returns undefined for extensions this scoping doesn't
+ * apply to (css/html), where no filtering is added.
+ */
+export function ruleLanguageForFile(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    switch (ext) {
+        case ".ts":
+        case ".tsx":
+            return "typescript";
+        case ".js":
+        case ".jsx":
+            return "javascript";
+        default:
+            return undefined;
+    }
+}
 export function getLang(filePath, sgModule) {
     const ext = path.extname(filePath).toLowerCase();
     switch (ext) {
@@ -169,9 +212,11 @@ export function evaluateAstGrepRules(filePath, rootNode, cwd, kind, options = {}
     const maxMatchesPerRule = options.maxMatchesPerRule ?? MAX_MATCHES_PER_RULE;
     const maxTotalDiagnostics = options.maxTotalDiagnostics ?? MAX_TOTAL_DIAGNOSTICS;
     const blockingOnly = options.blockingOnly === true;
+    const log = options.log;
     const diagnostics = [];
     const seenRuleIds = new Set();
     const suppressLinterOverlap = kind === "jsts" && hasEslintConfig(cwd);
+    const fileLang = ruleLanguageForFile(filePath);
     // Shared with the raw sgconfig materializer so both surfaces walk the same
     // workspace-rooted sources in the same precedence order.
     const ruleSources = getAstGrepRuleSources(options.projectRoot ?? cwd);
@@ -205,9 +250,6 @@ export function evaluateAstGrepRules(filePath, rootNode, cwd, kind, options = {}
                 !NON_SUPPRESSIBLE.has(normalizeRuleId(rule.id))) {
                 continue;
             }
-            // Skip rules already handled by tree-sitter runner (priority 14)
-            if (TREE_SITTER_OVERLAP.has(rule.id))
-                continue;
             // Skip rules whose top-level pattern is overly broad ($NAME, $X, etc.)
             // without additional structural constraints to narrow matches.
             if (rule.rule &&
@@ -219,6 +261,12 @@ export function evaluateAstGrepRules(filePath, rootNode, cwd, kind, options = {}
             if (lang && lang !== "typescript" && lang !== "javascript") {
                 continue;
             }
+            // Scope TypeScript/JavaScript-tagged rules to the file's actual
+            // grammar (#657) — otherwise a `-js` twin sharing generic node
+            // kinds with its TS sibling double-fires on every .ts file.
+            if (lang && fileLang && lang !== fileLang) {
+                continue;
+            }
             if (blockingOnly && rule.rule) {
                 const complexity = calculateRuleComplexity(rule.rule);
                 if (complexity > MAX_BLOCKING_RULE_COMPLEXITY) {
@@ -232,18 +280,26 @@ export function evaluateAstGrepRules(filePath, rootNode, cwd, kind, options = {}
                 // Delegate matching to napi's native engine, which handles the
                 // full ast-grep rule grammar (pattern, kind, has/inside/follows/
                 // precedes/stopBy/field/nthChild, any/all/not) plus metavariable
-                // `constraints` (#206). A faithful js-yaml parse feeds the rule
+                // `constraints` (#206) AND top-level `utils` — reusable named
+                // matchers referenced via `matches: <name>` inside `rule`
+                // (#663; `NapiConfig.utils: Record<string, Rule>` per
+                // @ast-grep/napi's types, same shape napi already expects for
+                // `rule`/`constraints`). A faithful js-yaml parse feeds the rule
                 // object straight through. If napi rejects the rule (a malformed
-                // or invalid-kind rule), skip it — never silently match nothing
-                // through a partial interpreter.
-                const nativeConfig = rule.constraints
-                    ? { rule: rule.rule, constraints: rule.constraints }
-                    : { rule: rule.rule };
+                // or invalid-kind rule, or an unresolved `matches:` reference),
+                // skip it — never silently match nothing through a partial
+                // interpreter.
+                const nativeConfig = { rule: rule.rule };
+                if (rule.constraints)
+                    nativeConfig.constraints = rule.constraints;
+                if (rule.utils)
+                    nativeConfig.utils = rule.utils;
                 try {
                     matches = rootNode.findAll(nativeConfig);
                 }
-                catch {
+                catch (err) {
                     matches = [];
+                    log?.(`ast-grep-napi: rule "${rule.id}" rejected by native engine (${err instanceof Error ? err.message : String(err)})`);
                 }
                 const limitedMatches = matches.slice(0, maxMatchesPerRule);
                 for (const match of limitedMatches) {
@@ -355,6 +411,7 @@ const astGrepNapiRunner = {
         const diagnostics = evaluateAstGrepRules(ctx.filePath, rootNode, ctx.cwd, ctx.kind, {
             blockingOnly: ctx.blockingOnly,
             projectRoot: ctx.projectRoot,
+            log: (message) => ctx.log(message),
         });
         const hasBlocking = diagnostics.some((d) => d.semantic === "blocking");
         let semantic = "none";

package/dist/clients/dispatch/runners/lsp.js

@@ -16,7 +16,7 @@ import { RUNTIME_CONFIG } from "../../runtime-config.js";
 import { PRIORITY } from "../priorities.js";
 import { resolveRunnerPath } from "../runner-context.js";
 import { convertLspDiagnostics } from "../utils/lsp-diagnostics.js";
-import { enabledAuxiliaryLspServerIds, findAuxiliaryProfileForSource, } from "../auxiliary-lsp.js";
+import { enabledAuxiliaryLspServerIds, findAuxiliaryProfileForSource, isAuxiliaryDiagnosticSuppressed, } from "../auxiliary-lsp.js";
 import { readFileContent } from "./utils.js";
 const LSP_MAX_FILE_BYTES = RUNTIME_CONFIG.pipeline.lspMaxFileBytes;
 const LSP_MAX_FILE_LINES = RUNTIME_CONFIG.pipeline.lspMaxFileLines;
@@ -104,6 +104,11 @@ const lspRunner = {
         // spawn that didn't complete in the budget, or LSP unavailable for this
         // file) — distinct from `[]`, which means the server replied with zero.
         let lspClientReady = true;
+        // True when touchFile ran but couldn't confirm its result within
+        // budget (notify write and/or diagnostics wait timed out on at least
+        // one spawned server) — an empty `lspDiags` in that case is NOT a
+        // confirmed clean result and must not be reported as one (#570).
+        let diagnosticsInconclusive = false;
         let failureReason = "";
         const content = readFileContent(ctx.filePath);
         if (!content) {
@@ -133,6 +138,7 @@ const lspRunner = {
             }
             else {
                 lspDiags = touched;
+                diagnosticsInconclusive = touched.inconclusive === true;
             }
         }
         catch (err) {
@@ -173,6 +179,18 @@ const lspRunner = {
             // published late still land in the client cache and surface then.
             return { status: "skipped", diagnostics: [], semantic: "none" };
         }
+        if (diagnosticsInconclusive) {
+            // The touch ran and a client was ready, but the notify write and/or
+            // diagnostics wait hit their deadline before the server confirmed
+            // completion — `lspDiags` (even if non-empty) is not a trustworthy
+            // merged result. Same treatment as `!lspClientReady`: report
+            // "skipped" rather than "succeeded" with a possibly-incomplete
+            // diagnostics list, so the coverage notice flags the gap instead of
+            // the footer reading this as a confirmed clean/partial result (#570).
+            // Diagnostics that do arrive late still land in the client cache and
+            // surface on the next edit.
+            return { status: "skipped", diagnostics: [], semantic: "none" };
+        }
         if (lspDiags.length === 0) {
             return {
                 status: "succeeded",
@@ -216,11 +234,9 @@ const lspRunner = {
             const profile = findAuxiliaryProfileForSource(validLspDiags[i]?.source);
             if (!profile)
                 continue;
-            if (profile.isSuppressed) {
-                if (profile.isSuppressed(validLspDiags[i], content)) {
-                    suppressedIndices.add(i);
-                    continue;
-                }
+            if (isAuxiliaryDiagnosticSuppressed(validLspDiags[i], content)) {
+                suppressedIndices.add(i);
+                continue;
             }
             let blockingAllowed = blockingAllowedByProfile.get(profile);
             if (blockingAllowed === undefined) {

package/dist/clients/gitleaks-client.js

@@ -17,6 +17,13 @@
  *   - `gitleaks` reference in `package.json` deps, OR
  *   - a git pre-commit hook (.husky/, .git/hooks/) referencing gitleaks
  *
+ * `lens_diagnostics mode=full`'s fresh-fetch path (`clients/project-diagnostics/
+ * fresh-fetch.ts`) uses a looser "smart-default" gate instead — any tracked
+ * git repo, via `hasGitRepo` — since that's an explicitly-requested
+ * comprehensive review where gitleaks's low cost and advisory-only findings
+ * make the stricter default needlessly conservative. session_start and
+ * per-edit dispatch keep the strict gate above unchanged.
+ *
  * If the gate trips, the runner auto-installs gitleaks from GitHub releases
  * (installer entry registered in clients/installer/index.ts) and runs
  * `gitleaks detect --no-git --report-format json` against the analysis root.
@@ -95,6 +102,26 @@ export function hasGitleaksSignal(cwd) {
     }
     return false;
 }
+/**
+ * "Smart-default" tier from #130's own considered-but-unshipped options:
+ * fire whenever the project is a tracked git repo, not only when an explicit
+ * gitleaks signal is present. gitleaks's own scan target is "a git repo's
+ * history/tree" — nearly every project qualifies, so this is meaningfully
+ * looser than {@link hasGitleaksSignal}. Used ONLY by `mode=full`'s
+ * fresh-fetch path (an explicitly-requested comprehensive review, where
+ * gitleaks's low cost — ~10MB binary, no external DB pull — and advisory-only
+ * findings make the stricter opt-in gate needlessly conservative); session_start
+ * and per-edit dispatch keep the strict {@link hasGitleaksSignal} gate
+ * unchanged, so day-to-day noise/cost stays exactly as conservative as before.
+ */
+export function hasGitRepo(cwd) {
+    try {
+        return fs.existsSync(path.join(cwd, ".git"));
+    }
+    catch {
+        return false;
+    }
+}
 // --- Client ---
 export class GitleaksClient extends SecurityScanClient {
     constructor(verbose = false) {
@@ -107,6 +134,10 @@ export class GitleaksClient extends SecurityScanClient {
     static hasGitleaksSignal(cwd) {
         return hasGitleaksSignal(cwd);
     }
+    /** Smart-default tier (#130) — see {@link hasGitRepo}'s doc comment. */
+    static hasGitRepo(cwd) {
+        return hasGitRepo(cwd);
+    }
     /**
      * Auto-install via the GitHub-release path (registered in
      * `clients/installer/index.ts`) when gitleaks isn't already on PATH.
@@ -118,18 +149,22 @@ export class GitleaksClient extends SecurityScanClient {
     /**
      * Scan a directory tree for secrets.
      *
-     * Skips early when the directory shows no gitleaks opt-in signal. When
-     * gitleaks is unavailable, returns an empty result with an explanatory
-     * summary rather than failing the session_start task.
+     * Skips early when the directory shows no gitleaks opt-in signal — unless
+     * `requireSignal: false` (the `mode=full` fresh-fetch path uses this to
+     * apply the looser #130 "smart-default" gate, {@link hasGitRepo}, instead;
+     * session_start and per-edit dispatch never pass this, so their behavior
+     * is unchanged). When gitleaks is unavailable, returns an empty result
+     * with an explanatory summary rather than failing the session_start task.
      *
      * Re-entrancy safe: concurrent calls against the same root share a
      * single gitleaks process (mirrors `KnipClient` / `JscpdClient` /
      * `GovulncheckClient`).
      */
-    async scan(cwd) {
+    async scan(cwd, options) {
         const targetDir = path.resolve(cwd);
         const scannedAt = new Date().toISOString();
-        if (!GitleaksClient.hasGitleaksSignal(targetDir)) {
+        const requireSignal = options?.requireSignal ?? true;
+        if (requireSignal && !GitleaksClient.hasGitleaksSignal(targetDir)) {
             return {
                 ...EMPTY_RESULT,
                 success: true,