@dailephd/my-dev-kit-lab 0.2.1 → 0.3.0

package/dist/src/audits/codeRot/detectors/architectureDriftDetector.js

@@ -0,0 +1,271 @@
+import fs from "node:fs";
+import path from "node:path";
+import { currentClaimPatternFor } from "../utils/docClaimPatterns.js";
+import { readBoundedFileText } from "../utils/boundedRead.js";
+import { deduplicateIssuesById, makeCodeRotIssue } from "../utils/issueFactories.js";
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 4 — architecture drift detector.
+//
+// Deterministic path/claim checks only -- no semantic judgment. Two of the
+// checks below (stale/missing backtick path mentions, and the hardcoded
+// "audit framework described as planned while implemented" check) are
+// deliberately scoped to docs/ARCHITECTURE.md and docs/CURRENT_STATE.md
+// only, not every doc file. Both files' own headers state their purpose is
+// describing CURRENT implemented state ("This file is the concise source of
+// truth for the checked-in implementation" / "Current implemented
+// architecture"). docs/ROADMAP.md, by contrast, is full of legitimate
+// backtick-quoted "Suggested architecture" paths for genuinely
+// not-yet-built future work items -- scanning it with the same "does this
+// path exist" check would produce many false positives against accurate,
+// correctly-labeled-as-future roadmap content. Restricting scope keeps this
+// detector's signal high-confidence.
+// ---------------------------------------------------------------------------
+const DETECTOR_ID = "architecture-drift";
+const MAX_READ_BYTES = 200_000;
+const CURRENT_STATE_DOC_BASENAMES = new Set(["architecture.md", "current_state.md"]);
+const BACKTICK_SRC_PATH_PATTERN = /`(src\/[\w./-]+|scripts\/[\w./-]+)`/g;
+const HISTORICAL_FRAMING_PATTERN = /\b(historical|previously|used to|no longer|removed|deprecated)\b/i;
+const PLANNED_FRAMING_PATTERN = /\b(planned|future|roadmap|not (?:yet )?implemented)\b/i;
+const AUDIT_FRAMEWORK_SUBJECT_PATTERN = /\baudit (?:framework|contracts)\b|\bcode rot detector\b/i;
+const MIN_SOURCE_FILES_FOR_MAJOR_DIR = 3;
+export const ARCHITECTURE_DRIFT_DETECTOR = {
+    id: DETECTOR_ID,
+    auditType: "code-rot",
+    title: "Architecture drift",
+    description: "Detects deterministic drift between documentation and actual source layout: doc-claimed paths that don't exist, the audit framework described as planned while implemented, major source directories missing from ARCHITECTURE.md, and unhedged manual-pentest/Android implementation claims.",
+    supportedIncludeAreas: ["architecture", "docs", "package", "cli"],
+    shouldSkip: (ctx) => {
+        if (!ctx.config.include.includes("docs") && !ctx.config.include.includes("architecture")) {
+            return { skip: true, reason: "--include selects neither docs nor architecture; this detector's checks are docs-based." };
+        }
+        return { skip: false };
+    },
+    run: (ctx) => {
+        const issues = [];
+        const currentStateDocs = ctx.inventory.docsFiles.filter((f) => CURRENT_STATE_DOC_BASENAMES.has(path.basename(f.relativePath).toLowerCase()));
+        for (const docFile of currentStateDocs) {
+            const content = readBoundedFileText(ctx.target.rootPath, docFile.relativePath, docFile.sizeBytes, MAX_READ_BYTES);
+            if (content === null)
+                continue;
+            issues.push(...findStaleOrMissingBacktickPaths(ctx, docFile.relativePath, content));
+        }
+        issues.push(...findAuditFrameworkDescribedAsPlanned(ctx, currentStateDocs));
+        const architectureDoc = ctx.inventory.docsFiles.find((f) => path.basename(f.relativePath).toLowerCase() === "architecture.md");
+        if (architectureDoc) {
+            const content = readBoundedFileText(ctx.target.rootPath, architectureDoc.relativePath, architectureDoc.sizeBytes, MAX_READ_BYTES);
+            if (content !== null) {
+                issues.push(...findMajorDirsAbsentFromArchitectureDoc(ctx, architectureDoc.relativePath, content));
+            }
+        }
+        for (const docFile of ctx.inventory.docsFiles) {
+            const content = readBoundedFileText(ctx.target.rootPath, docFile.relativePath, docFile.sizeBytes, MAX_READ_BYTES);
+            if (content === null)
+                continue;
+            issues.push(...findUnsupportedCurrentClaims(docFile.relativePath, content));
+        }
+        return deduplicateIssuesById(issues);
+    },
+};
+function pathExistsInInventoryOrDisk(ctx, claimedPath) {
+    const trimmed = claimedPath.replace(/\/$/, "");
+    const inventoryHit = ctx.inventory.files.some((f) => f.relativePath === trimmed || f.relativePath.startsWith(`${trimmed}/`));
+    if (inventoryHit)
+        return true;
+    try {
+        return fs.existsSync(path.join(ctx.target.rootPath, trimmed));
+    }
+    catch {
+        return false;
+    }
+}
+function findStaleOrMissingBacktickPaths(ctx, docRelativePath, content) {
+    const issues = [];
+    const seen = new Set();
+    BACKTICK_SRC_PATH_PATTERN.lastIndex = 0;
+    for (const match of content.matchAll(BACKTICK_SRC_PATH_PATTERN)) {
+        const claimedPath = match[1];
+        if (seen.has(claimedPath))
+            continue;
+        seen.add(claimedPath);
+        if (pathExistsInInventoryOrDisk(ctx, claimedPath))
+            continue;
+        const matchIndex = match.index ?? 0;
+        const windowStart = Math.max(0, matchIndex - 200);
+        const windowEnd = Math.min(content.length, matchIndex + claimedPath.length + 200);
+        const window = content.slice(windowStart, windowEnd);
+        const isHistorical = HISTORICAL_FRAMING_PATTERN.test(window);
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: [docRelativePath, isHistorical ? "stale-path-mention" : "claimed-path-missing", claimedPath],
+            title: isHistorical
+                ? `${docRelativePath} mentions a stale (historically-framed) path: "${claimedPath}"`
+                : `${docRelativePath} claims path "${claimedPath}" exists, but it does not`,
+            description: isHistorical
+                ? `${docRelativePath} mentions "${claimedPath}" with historical framing, and the path no longer exists on disk. Low-severity because it is explicitly framed as historical.`
+                : `${docRelativePath} references "${claimedPath}" as a current path (backtick code span), but no such file or directory exists in the project.`,
+            severity: isHistorical ? "low" : "medium",
+            confidence: isHistorical ? "medium" : "medium",
+            falsePositiveRisk: "medium",
+            category: "architecture-drift",
+            recommendedAction: isHistorical
+                ? `Confirm whether the historical reference to "${claimedPath}" is still useful context.`
+                : `Update ${docRelativePath} to reference an existing path, or restore/implement "${claimedPath}".`,
+            suggestedFixStrategy: `Correct or remove the "${claimedPath}" reference in ${docRelativePath}.`,
+            validationCommands: ["npm run audit -- --types code-rot --include architecture,docs"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "file",
+                    message: "Backtick-quoted path does not exist on disk.",
+                    filePath: docRelativePath,
+                    excerpt: claimedPath,
+                    source: DETECTOR_ID,
+                    confidence: "medium",
+                },
+            ],
+            affectedFiles: [docRelativePath],
+        }));
+    }
+    return issues;
+}
+function findAuditFrameworkDescribedAsPlanned(ctx, currentStateDocs) {
+    const auditImplemented = fs.existsSync(path.join(ctx.target.rootPath, "src", "audits")) && "audit" in (ctx.sourceOfTruth.package?.scripts ?? {});
+    if (!auditImplemented)
+        return [];
+    const issues = [];
+    for (const docFile of currentStateDocs) {
+        const content = readBoundedFileText(ctx.target.rootPath, docFile.relativePath, docFile.sizeBytes, MAX_READ_BYTES);
+        if (content === null)
+            continue;
+        AUDIT_FRAMEWORK_SUBJECT_PATTERN.lastIndex = 0;
+        const subjectMatch = AUDIT_FRAMEWORK_SUBJECT_PATTERN.exec(content);
+        if (!subjectMatch)
+            continue;
+        const matchIndex = subjectMatch.index;
+        const windowStart = Math.max(0, matchIndex - 400);
+        const windowEnd = Math.min(content.length, matchIndex + subjectMatch[0].length + 400);
+        const window = content.slice(windowStart, windowEnd);
+        if (!PLANNED_FRAMING_PATTERN.test(window))
+            continue;
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: [docFile.relativePath, "audit-framework-planned-but-implemented"],
+            title: `${docFile.relativePath} describes the audit framework as planned/future, but it is already implemented`,
+            description: `${docFile.relativePath} mentions "${subjectMatch[0]}" near planned/future/not-implemented wording, but src/audits exists and package.json defines an "audit" script -- the audit framework is already implemented, not merely planned.`,
+            severity: "high",
+            confidence: "medium",
+            falsePositiveRisk: "medium",
+            category: "architecture-drift",
+            recommendedAction: `Update ${docFile.relativePath} to describe the audit framework's actual current implementation status.`,
+            suggestedFixStrategy: `Move the audit-framework description in ${docFile.relativePath} out of the planned/future section.`,
+            validationCommands: ["npm run audit -- --types code-rot --include architecture,docs"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "file",
+                    message: "Doc describes the audit framework as planned/future near this mention, but src/audits exists and an \"audit\" npm script is defined.",
+                    filePath: docFile.relativePath,
+                    excerpt: subjectMatch[0],
+                    source: DETECTOR_ID,
+                    confidence: "medium",
+                },
+            ],
+            affectedFiles: [docFile.relativePath],
+        }));
+    }
+    return issues;
+}
+function findMajorDirsAbsentFromArchitectureDoc(ctx, docRelativePath, content) {
+    const countsByDir = new Map();
+    for (const file of ctx.inventory.sourceFiles) {
+        const parts = file.relativePath.split("/");
+        if (parts[0] !== "src" || parts.length < 3)
+            continue;
+        const dirName = parts[1];
+        countsByDir.set(dirName, (countsByDir.get(dirName) ?? 0) + 1);
+    }
+    const issues = [];
+    const sortedDirs = [...countsByDir.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+    for (const [dirName, count] of sortedDirs) {
+        if (count < MIN_SOURCE_FILES_FOR_MAJOR_DIR)
+            continue;
+        if (content.includes(dirName))
+            continue;
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: [docRelativePath, "major-dir-absent-from-architecture-doc", dirName],
+            title: `Major implemented directory "src/${dirName}" is not mentioned in ${docRelativePath}`,
+            description: `"src/${dirName}" contains ${count} source files but is never mentioned in ${docRelativePath}.`,
+            severity: "medium",
+            confidence: "medium",
+            falsePositiveRisk: "medium",
+            category: "architecture-drift",
+            recommendedAction: `Add "src/${dirName}" to ${docRelativePath}'s module map.`,
+            suggestedFixStrategy: `Document the responsibility of "src/${dirName}" in ${docRelativePath}.`,
+            validationCommands: ["npm run audit -- --types code-rot --include architecture,docs"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "observation",
+                    message: `"src/${dirName}" has ${count} source files and is not mentioned anywhere in ${docRelativePath}.`,
+                    filePath: docRelativePath,
+                    source: DETECTOR_ID,
+                    confidence: "medium",
+                },
+            ],
+            affectedFiles: [docRelativePath],
+        }));
+    }
+    return issues;
+}
+function findUnsupportedCurrentClaims(docRelativePath, content) {
+    const issues = [];
+    const subjects = [
+        { id: "manual-pentest", label: "manual pentest", pattern: "manual pentest" },
+        { id: "android-validation", label: "Android/mobile validation", pattern: "(?:android (?:validation|support))" },
+    ];
+    for (const subject of subjects) {
+        const pattern = currentClaimPatternFor(subject.pattern);
+        const match = pattern.exec(content);
+        if (!match)
+            continue;
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: [docRelativePath, "unsupported-current-claim", subject.id],
+            title: `${docRelativePath} claims "${subject.label}" is implemented/current`,
+            description: `${docRelativePath} contains an unhedged "${subject.label} is implemented/current" claim, but there is no corresponding source signal for this repo.`,
+            severity: "high",
+            confidence: "medium",
+            falsePositiveRisk: "medium",
+            category: "architecture-drift",
+            recommendedAction: `Confirm whether "${subject.label}" is actually implemented; if not, correct ${docRelativePath}.`,
+            suggestedFixStrategy: `Rephrase the "${subject.label}" claim in ${docRelativePath} to accurately reflect its planned status.`,
+            validationCommands: ["npm run audit -- --types code-rot --include architecture,docs"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "file",
+                    message: `Matched an unhedged "${subject.label} is implemented/current" claim pattern.`,
+                    filePath: docRelativePath,
+                    excerpt: match[0].slice(0, 200),
+                    source: DETECTOR_ID,
+                    confidence: "medium",
+                },
+            ],
+            affectedFiles: [docRelativePath],
+        }));
+    }
+    return issues;
+}

package/dist/src/audits/codeRot/detectors/crossPlatformRotDetector.js

@@ -0,0 +1,214 @@
+import { readBoundedFileText } from "../utils/boundedRead.js";
+import { deduplicateIssuesById, makeCodeRotIssue } from "../utils/issueFactories.js";
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 4 — cross-platform rot detector.
+//
+// Read-only with respect to the target project throughout -- never
+// modifies scripts or source. Bounded (per-file MAX_READ_BYTES skip).
+//
+// Simplification made after self-testing against this repo's own source:
+// the spec's ".split(\"/\")" raw-path-splitting sub-check was DROPPED. This
+// repo's own project inventory (src/audits/core/projectInventory.ts)
+// guarantees relativePath values are always forward-slash normalized, so
+// splitting an already-normalized relativePath on "/" (as several of this
+// batch's own new detector files legitimately do, e.g.
+// filePatternUtils.ts's firstTwoPathSegments()) is the correct, intentional
+// pattern here, not a cross-platform bug -- a bare regex cannot distinguish
+// that from a genuinely unsafe raw OS path split without semantic analysis.
+// The much narrower, high-signal ".split(\"\\\\\")" (raw double-backslash
+// Windows-style split) sub-check is kept, since that pattern has near-zero
+// legitimate use in this codebase.
+// ---------------------------------------------------------------------------
+const DETECTOR_ID = "cross-platform-rot";
+const MAX_READ_BYTES = 200_000;
+const WINDOWS_MENTION_PATTERN = /\bWindows\b/;
+const POSIX_ONLY_BINARY_PATTERN = /(^|&&)\s*(rm -rf|cp -r|mv |grep |sed |cat |find \.)/;
+const SPLIT_NEWLINE_LITERAL_PATTERN = /\.split\(\s*["']\\n["']\s*\)/g;
+const RAW_BACKSLASH_SPLIT_PATTERN = /\.split\(\s*["']\\\\["']\s*\)/g;
+const SHELL_TRUE_PATTERN = /shell:\s*true/;
+const EXEC_SPAWN_CALL_PATTERN = /\b(exec|spawn|execFile\w*|spawnSync|execSync|execFileSync)\s*\(/;
+export const CROSS_PLATFORM_ROT_DETECTOR = {
+    id: DETECTOR_ID,
+    auditType: "code-rot",
+    title: "Cross-platform rot",
+    description: "Detects POSIX-only shell syntax in npm scripts when Windows support is claimed, raw .split(\"\\n\") usage outside the canonical splitLines() helper, raw backslash path splitting, and exec/spawn calls with shell: true.",
+    supportedIncludeAreas: ["cli", "package", "docs", "tests"],
+    shouldSkip: (ctx) => {
+        if (!ctx.config.include.includes("cli") && !ctx.config.include.includes("package")) {
+            return { skip: true, reason: "--include selects neither cli nor package; this detector's checks are script/source-based." };
+        }
+        return { skip: false };
+    },
+    run: (ctx) => {
+        const issues = [];
+        const pkg = ctx.sourceOfTruth.package;
+        let docsClaimWindowsSupport = false;
+        if (ctx.config.include.includes("docs")) {
+            docsClaimWindowsSupport = docsClaimWindows(ctx);
+        }
+        if (ctx.config.include.includes("package") && pkg) {
+            issues.push(...findPosixOnlyScriptSyntax(pkg.scripts, docsClaimWindowsSupport));
+        }
+        if (ctx.config.include.includes("cli")) {
+            issues.push(...scanSourceFiles(ctx));
+        }
+        return deduplicateIssuesById(issues);
+    },
+};
+function docsClaimWindows(ctx) {
+    for (const docFile of ctx.inventory.docsFiles) {
+        const content = readBoundedFileText(ctx.target.rootPath, docFile.relativePath, docFile.sizeBytes, MAX_READ_BYTES);
+        if (content !== null && WINDOWS_MENTION_PATTERN.test(content))
+            return true;
+    }
+    return false;
+}
+function findPosixOnlyScriptSyntax(scripts, docsClaimWindowsSupport) {
+    const issues = [];
+    for (const [scriptName, command] of Object.entries(scripts)) {
+        const segments = command.split("&&").map((s) => s.trim());
+        for (const segment of segments) {
+            if (!POSIX_ONLY_BINARY_PATTERN.test(segment))
+                continue;
+            issues.push(makeCodeRotIssue({
+                auditType: "code-rot",
+                detectorId: DETECTOR_ID,
+                idCues: ["posix-only-script-syntax", scriptName],
+                title: `Script "${scriptName}" appears to use POSIX-only shell syntax`,
+                description: `package.json script "${scriptName}" contains a segment that looks like a bare POSIX shell command ("${segment.slice(0, 60)}"), which is not guaranteed to work on Windows without a POSIX shell shim.${docsClaimWindowsSupport ? " Docs explicitly claim Windows support." : ""}`,
+                severity: docsClaimWindowsSupport ? "high" : "medium",
+                confidence: "medium",
+                falsePositiveRisk: "medium",
+                category: "cross-platform-rot",
+                recommendedAction: "Replace the POSIX-only command with a cross-platform Node script or a guarded/portable equivalent.",
+                suggestedFixStrategy: `Rewrite the "${scriptName}" script segment to avoid relying on a POSIX-only shell binary.`,
+                validationCommands: [`npm run ${scriptName}`],
+                releaseBlocking: false,
+                implementationBlocking: false,
+                autoFixEligible: false,
+                evidence: [
+                    {
+                        kind: "reference",
+                        message: "Script command segment matches a bare POSIX-only shell binary pattern.",
+                        filePath: "package.json",
+                        excerpt: segment.slice(0, 200),
+                        source: DETECTOR_ID,
+                        confidence: "medium",
+                    },
+                ],
+                affectedFiles: ["package.json"],
+            }));
+        }
+    }
+    return issues;
+}
+function scanSourceFiles(ctx) {
+    const issues = [];
+    const auditSourceFiles = ctx.inventory.sourceFiles.filter((f) => f.relativePath.startsWith("src/audits/"));
+    for (const file of auditSourceFiles) {
+        if (path_basename(file.relativePath) === "textLines.ts")
+            continue; // canonical implementation, allowed
+        const content = readBoundedFileText(ctx.target.rootPath, file.relativePath, file.sizeBytes, MAX_READ_BYTES);
+        if (content === null)
+            continue;
+        SPLIT_NEWLINE_LITERAL_PATTERN.lastIndex = 0;
+        if (SPLIT_NEWLINE_LITERAL_PATTERN.test(content)) {
+            issues.push(makeCodeRotIssue({
+                auditType: "code-rot",
+                detectorId: DETECTOR_ID,
+                idCues: [file.relativePath, "raw-split-newline"],
+                title: `"${file.relativePath}" uses raw .split("\\n") instead of the canonical splitLines() helper`,
+                description: `"${file.relativePath}" contains a raw ".split(\\"\\n\\")"/".split('\\n')" call. This project's own convention (see src/audits/codeRot/utils/textLines.ts) requires splitLines() for all doc/text line-splitting, because a bare split leaves a trailing "\\r" on every line for CRLF-authored files.`,
+                severity: "medium",
+                confidence: "high",
+                falsePositiveRisk: "low",
+                category: "cross-platform-rot",
+                recommendedAction: `Replace the raw .split("\\n") in "${file.relativePath}" with splitLines() from ../utils/textLines.js.`,
+                suggestedFixStrategy: `Import and use splitLines() in "${file.relativePath}".`,
+                validationCommands: ["npm run audit -- --types code-rot --include cli"],
+                releaseBlocking: false,
+                implementationBlocking: false,
+                autoFixEligible: false,
+                evidence: [
+                    {
+                        kind: "file",
+                        message: "Raw .split(\"\\n\") usage found outside the canonical splitLines() implementation.",
+                        filePath: file.relativePath,
+                        source: DETECTOR_ID,
+                        confidence: "high",
+                    },
+                ],
+                affectedFiles: [file.relativePath],
+            }));
+        }
+        RAW_BACKSLASH_SPLIT_PATTERN.lastIndex = 0;
+        if (RAW_BACKSLASH_SPLIT_PATTERN.test(content)) {
+            issues.push(makeCodeRotIssue({
+                auditType: "code-rot",
+                detectorId: DETECTOR_ID,
+                idCues: [file.relativePath, "raw-backslash-split"],
+                title: `"${file.relativePath}" raw-splits a path on a literal backslash`,
+                description: `"${file.relativePath}" contains a raw backslash .split() call, which assumes Windows-style backslash separators and will silently fail to split forward-slash paths (e.g. on POSIX or already-normalized relative paths).`,
+                severity: "medium",
+                confidence: "medium",
+                falsePositiveRisk: "medium",
+                category: "cross-platform-rot",
+                recommendedAction: `Use path.sep/path.normalize or a forward-slash-normalized path representation instead of a raw backslash split in "${file.relativePath}".`,
+                suggestedFixStrategy: `Replace the raw backslash split in "${file.relativePath}" with a portable path-handling helper.`,
+                validationCommands: ["npm run audit -- --types code-rot --include cli"],
+                releaseBlocking: false,
+                implementationBlocking: false,
+                autoFixEligible: false,
+                evidence: [
+                    {
+                        kind: "file",
+                        message: "Raw backslash-splitting pattern found in source.",
+                        filePath: file.relativePath,
+                        source: DETECTOR_ID,
+                        confidence: "medium",
+                    },
+                ],
+                affectedFiles: [file.relativePath],
+            }));
+        }
+        SHELL_TRUE_PATTERN.lastIndex = 0;
+        const shellTrueMatch = SHELL_TRUE_PATTERN.exec(content);
+        if (shellTrueMatch && EXEC_SPAWN_CALL_PATTERN.test(nearbyWindow(content, shellTrueMatch.index))) {
+            issues.push(makeCodeRotIssue({
+                auditType: "code-rot",
+                detectorId: DETECTOR_ID,
+                idCues: [file.relativePath, "shell-true-usage"],
+                title: `"${file.relativePath}" appears to invoke a subprocess with shell: true`,
+                description: `"${file.relativePath}" contains a "shell: true" option near an exec/spawn call. This is a known risk pattern (shell metacharacter injection via unsanitized arguments).`,
+                severity: "high",
+                confidence: "medium",
+                falsePositiveRisk: "medium",
+                category: "cross-platform-rot",
+                recommendedAction: `Remove "shell: true" and pass arguments as an array instead, in "${file.relativePath}".`,
+                suggestedFixStrategy: `Refactor the subprocess call in "${file.relativePath}" to avoid shell: true.`,
+                validationCommands: ["npm run audit -- --types code-rot --include cli"],
+                releaseBlocking: true,
+                implementationBlocking: false,
+                autoFixEligible: false,
+                evidence: [
+                    {
+                        kind: "file",
+                        message: "shell: true found near an exec/spawn-family call.",
+                        filePath: file.relativePath,
+                        source: DETECTOR_ID,
+                        confidence: "medium",
+                    },
+                ],
+                affectedFiles: [file.relativePath],
+            }));
+        }
+    }
+    return issues;
+}
+function nearbyWindow(content, index, radius = 150) {
+    return content.slice(Math.max(0, index - radius), Math.min(content.length, index + radius));
+}
+function path_basename(relativePath) {
+    const idx = relativePath.lastIndexOf("/");
+    return idx === -1 ? relativePath : relativePath.slice(idx + 1);
+}