@dailephd/my-dev-kit-lab 0.3.1 → 0.3.2

package/dist/src/audits/core/projectInventory.js

@@ -356,7 +356,7 @@ function classifyFile(relativePath, basename, extension) {
     if (relativePath.startsWith(".github/workflows/") && (extension === ".yml" || extension === ".yaml")) {
         return "ci";
     }
-    if (isTestFile(relativePath, basename))
+    if (isTestFile(relativePath, basename, extension))
         return "tests";
     // Top-level scripts/ directory -- classified before generic "source" so
     // scripts (which are also .ts/.js) land in their own category.
@@ -374,11 +374,37 @@ function classifyFile(relativePath, basename, extension) {
         return "source";
     return "unknown";
 }
-function isTestFile(relativePath, basename) {
+// v0.3.2 Batch 1 -- conservative pytest naming conventions. Gated to .py so
+// this can never reclassify a non-Python file. "tests/**/*.py" and
+// "**/tests/**/*.py" are already covered by the generic, extension-agnostic
+// check above; only the singular "test/" directory and the test_*.py /
+// *_test.py filename conventions are Python-specific additions here.
+function isPythonTestFile(relativePath, basename) {
+    if (relativePath.startsWith("test/") || relativePath.includes("/test/"))
+        return true;
+    return /^test_.*\.py$/.test(basename) || /^.*_test\.py$/.test(basename);
+}
+function isTestFile(relativePath, basename, extension) {
     if (relativePath.startsWith("tests/") || relativePath.includes("/tests/"))
         return true;
-    return /\.(test|spec)\.[jt]sx?$/.test(basename);
+    if (/\.(test|spec)\.[jt]sx?$/.test(basename))
+        return true;
+    if (extension === ".py" && isPythonTestFile(relativePath, basename))
+        return true;
+    return false;
 }
+// v0.3.2 Batch 1 -- recognized Python project/config metadata filenames.
+// Matched by basename only (same convention as PACKAGE_FILE_NAMES above),
+// not restricted to root, since these are specific enough not to collide
+// with unrelated fixture/benchmark content. Deliberately narrow: does not
+// match arbitrary *.toml/*.ini/*.txt files, only these exact names.
+const PYTHON_PROJECT_METADATA_FILE_NAMES = new Set([
+    "pyproject.toml",
+    "requirements.txt",
+    "setup.cfg",
+    "tox.ini",
+    "pytest.ini",
+]);
 function isConfigFile(relativePath, basename, extension) {
     if (/^tsconfig(\..+)?\.json$/.test(basename))
         return true;
@@ -388,6 +414,12 @@ function isConfigFile(relativePath, basename, extension) {
         return true;
     if (basename === ".editorconfig" || basename === ".gitignore" || basename === ".npmignore")
         return true;
+    // v0.3.2 Batch 1 -- setup.py has a .py extension and would otherwise fall
+    // through to the generic KNOWN_SOURCE_EXTENSIONS "source" classification
+    // below; the other names have no source-extension conflict but are listed
+    // here for the same "project metadata, not source" reasoning.
+    if (basename === "setup.py" || PYTHON_PROJECT_METADATA_FILE_NAMES.has(basename))
+        return true;
     // Root-level dotfile configs (e.g. .prettierrc, .babelrc) not already
     // covered above -- deliberately conservative (root-only, not recursive)
     // to avoid misclassifying dotfiles inside fixture/benchmark projects.

package/dist/src/audits/core/pythonAnalyzer.js

@@ -0,0 +1,328 @@
+// ---------------------------------------------------------------------------
+// v0.3.2 Batch 1 -- conservative, dependency-free Python source analyzer.
+//
+// There is no Python parser available in this Node/TypeScript project, and
+// per this batch's own scope this analyzer must not add a new parser
+// dependency. Facts are therefore extracted with a deliberately narrow,
+// line-oriented regex scan -- not a real tokenizer, not an AST, and not a
+// syntax validator. This is the single-file, best-effort analogue of
+// typescriptJavaScriptAnalyzer.ts's AST walk: same LanguageAnalyzer contract,
+// same SourceFileFacts shape, same size-bounding philosophy, but confidence
+// is necessarily lower since nothing here proves the file is syntactically
+// valid Python.
+//
+// What this DOES extract (see requirements 3 of the batch spec):
+//   - import module[, module2][ as alias]
+//   - from [.[.]]module import name[ as alias][, ...]  (single physical line)
+//   - from module import *
+//   - module-level `def`/`async def`/`class` declarations
+//   - class-body method declarations, via a simple indentation-based scope
+//     stack (not scope-accurate for deeply nested blocks, just "is this def
+//     more indented than the nearest enclosing class line")
+//   - a single-line `__all__ = [...]`/`(...)` string list, used to set
+//     `exported` precisely when present
+//
+// What this explicitly does NOT do (see requirements 3's "do not implement"
+// list): type checking, full AST/semantic resolution, virtualenv/dependency
+// resolution, runtime or dynamic import resolution, decorator/metaclass/
+// fixture semantics, or any claim of dead-code/duplicate-implementation
+// proof. `__import__(...)`/`importlib.import_module(...)` calls are recorded
+// only as an informational diagnostic, never as a resolved import fact.
+// ---------------------------------------------------------------------------
+export const PYTHON_ANALYZER_ID = "python-analyzer";
+const SUPPORTED_EXTENSIONS = [".py"];
+// Mirrors typescriptJavaScriptAnalyzer.ts's MAX_ANALYZABLE_BYTES bound and
+// reasoning -- a large file is not worth line-scanning, and stays at
+// file-level-only rather than file-level-only masquerading as parsed.
+const MAX_ANALYZABLE_BYTES = 1_000_000;
+const IMPORT_LINE_PATTERN = /^\s*import\s+(.+)$/;
+const FROM_IMPORT_LINE_PATTERN = /^\s*from\s+(\.{0,2}[\w.]*)\s+import\s+(.+)$/;
+const DEF_LINE_PATTERN = /^(\s*)(?:async\s+def|def)\s+([A-Za-z_]\w*)\s*\(/;
+const CLASS_LINE_PATTERN = /^(\s*)class\s+([A-Za-z_]\w*)\s*[:(]/;
+const ALL_ASSIGNMENT_PATTERN = /^\s*__all__\s*=\s*[[(](.*)$/;
+const DYNAMIC_IMPORT_PATTERN = /\b(?:__import__\s*\(|importlib\.import_module\s*\()/;
+const QUOTED_NAME_PATTERN = /(['"])((?:(?!\1).)*)\1/g;
+export const PYTHON_ANALYZER = {
+    id: PYTHON_ANALYZER_ID,
+    supportedLanguages: ["python"],
+    supportedExtensions: SUPPORTED_EXTENSIONS,
+    analyzeFile,
+};
+function analyzeFile(input) {
+    const { relativePath, language, role, content, inventoryEntry } = input;
+    if (Buffer.byteLength(content, "utf8") > MAX_ANALYZABLE_BYTES) {
+        return {
+            relativePath,
+            language,
+            role,
+            parseStatus: "file-level-only",
+            analyzerId: PYTHON_ANALYZER_ID,
+            lineCount: inventoryEntry.lineCount,
+            imports: [],
+            exports: [],
+            declarations: [],
+            references: [],
+            diagnostics: [
+                {
+                    severity: "info",
+                    code: "file-too-large-for-analysis",
+                    message: `File exceeds the ${MAX_ANALYZABLE_BYTES}-byte analyzer bound; only inventory-level facts are available.`,
+                    path: relativePath,
+                    analyzerId: PYTHON_ANALYZER_ID,
+                },
+            ],
+        };
+    }
+    const diagnostics = [];
+    const { logical, hadUnterminatedTripleQuote } = buildLogicalLines(content);
+    const imports = [];
+    for (let i = 0; i < logical.length; i++) {
+        const line = logical[i];
+        const lineNumber = i + 1;
+        if (parseFromImportLine(line, lineNumber, imports, diagnostics, relativePath))
+            continue;
+        parseImportLine(line, lineNumber, imports);
+    }
+    const exportedSet = scanAllExport(logical);
+    const declarations = scanDeclarations(logical, exportedSet);
+    scanDynamicImportPatterns(logical, diagnostics, relativePath);
+    const exports = exportedSet ? [...exportedSet].map((name) => ({ name, kind: "named" })) : [];
+    if (hadUnterminatedTripleQuote) {
+        diagnostics.push({
+            severity: "error",
+            code: "unterminated-triple-quoted-string",
+            message: "File appears to contain an unterminated triple-quoted string (unbalanced \"\"\"/''' delimiters); facts from this best-effort scan may be incomplete.",
+            path: relativePath,
+            analyzerId: PYTHON_ANALYZER_ID,
+        });
+    }
+    const parseStatus = hadUnterminatedTripleQuote ? "parse-error" : "parsed";
+    return {
+        relativePath,
+        language,
+        role,
+        parseStatus,
+        analyzerId: PYTHON_ANALYZER_ID,
+        lineCount: inventoryEntry.lineCount,
+        imports,
+        exports,
+        declarations,
+        references: [],
+        diagnostics,
+    };
+}
+// ---------------------------------------------------------------------------
+// Comment/triple-quoted-string stripping (heuristic, not a tokenizer).
+// ---------------------------------------------------------------------------
+// Strips a trailing `# comment`, respecting simple single/double-quoted
+// strings on the same line (so `x = "a # b"` is not truncated at the `#`
+// inside the string). Does not understand triple-quoted strings -- those are
+// handled one level up by buildLogicalLines(), which never passes a
+// mid-triple-quote-block line to this function.
+function stripLineComment(line) {
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (ch === "\\" && (inSingle || inDouble)) {
+            i++;
+            continue;
+        }
+        if (ch === "'" && !inDouble)
+            inSingle = !inSingle;
+        else if (ch === '"' && !inSingle)
+            inDouble = !inDouble;
+        else if (ch === "#" && !inSingle && !inDouble)
+            return line.slice(0, i);
+    }
+    return line;
+}
+// Produces one "logical" line per physical line: comments stripped, and any
+// content inside a triple-quoted string block (`"""..."""` / `'''...'''`)
+// blanked out so it can never be misread as an import/def/class statement.
+// Deliberately narrow: only tracks a single open triple-quote marker at a
+// time and does not handle more than one triple-quoted segment opening and
+// closing on the same physical line.
+function buildLogicalLines(content) {
+    const rawLines = content.split(/\r\n|\r|\n/);
+    const logical = [];
+    let openQuote = null;
+    for (const rawLine of rawLines) {
+        if (openQuote) {
+            const closeIdx = rawLine.indexOf(openQuote);
+            if (closeIdx === -1) {
+                logical.push("");
+                continue;
+            }
+            openQuote = null;
+            logical.push(stripLineComment(rawLine.slice(closeIdx + 3)));
+            continue;
+        }
+        const stripped = stripLineComment(rawLine);
+        const tripleMatch = stripped.match(/"""|'''/);
+        if (!tripleMatch) {
+            logical.push(stripped);
+            continue;
+        }
+        const marker = tripleMatch[0];
+        const firstIdx = stripped.indexOf(marker);
+        const secondIdx = stripped.indexOf(marker, firstIdx + marker.length);
+        if (secondIdx === -1) {
+            logical.push(stripped.slice(0, firstIdx));
+            openQuote = marker;
+        }
+        else {
+            logical.push(stripped.slice(0, firstIdx) + stripped.slice(secondIdx + marker.length));
+        }
+    }
+    return { logical, hadUnterminatedTripleQuote: openQuote !== null };
+}
+function leadingWhitespaceCount(line) {
+    let count = 0;
+    for (const ch of line) {
+        if (ch === " " || ch === "\t")
+            count += 1;
+        else
+            break;
+    }
+    return count;
+}
+// ---------------------------------------------------------------------------
+// Imports.
+// ---------------------------------------------------------------------------
+function parseImportLine(line, lineNumber, imports) {
+    const match = line.match(IMPORT_LINE_PATTERN);
+    if (!match)
+        return;
+    for (const rawSegment of match[1].split(",")) {
+        const segment = rawSegment.trim();
+        if (!segment)
+            continue;
+        const asMatch = segment.match(/^([\w.]+)\s+as\s+(\w+)$/);
+        if (asMatch) {
+            imports.push({ source: asMatch[1], kind: "static", importedNames: [asMatch[2]], line: lineNumber });
+        }
+        else {
+            imports.push({ source: segment, kind: "static", line: lineNumber });
+        }
+    }
+}
+function parseFromImportLine(line, lineNumber, imports, diagnostics, relativePath) {
+    const match = line.match(FROM_IMPORT_LINE_PATTERN);
+    if (!match)
+        return false;
+    const modulePath = match[1] || ".";
+    let namesPart = match[2].trim();
+    if (namesPart.startsWith("(") && namesPart.endsWith(")")) {
+        namesPart = namesPart.slice(1, -1);
+    }
+    else if (namesPart.startsWith("(")) {
+        // Multi-line parenthesized from-import list -- this single-line scanner
+        // does not follow continuation lines. Recorded as a diagnostic rather
+        // than silently dropped or guessed at.
+        diagnostics.push({
+            severity: "info",
+            code: "multiline-from-import-unsupported",
+            message: "Multi-line parenthesized from-import list is not analyzed by this conservative single-line scanner.",
+            path: relativePath,
+            analyzerId: PYTHON_ANALYZER_ID,
+        });
+        return true;
+    }
+    if (namesPart === "*") {
+        imports.push({ source: modulePath, kind: "static", line: lineNumber });
+        return true;
+    }
+    const importedNames = [];
+    for (const rawSegment of namesPart.split(",")) {
+        const segment = rawSegment.trim();
+        if (!segment)
+            continue;
+        const asMatch = segment.match(/^(\w+)\s+as\s+(\w+)$/);
+        importedNames.push(asMatch ? asMatch[2] : segment);
+    }
+    imports.push({
+        source: modulePath,
+        kind: "static",
+        line: lineNumber,
+        ...(importedNames.length > 0 ? { importedNames } : {}),
+    });
+    return true;
+}
+// ---------------------------------------------------------------------------
+// __all__ (optional, single-line only).
+// ---------------------------------------------------------------------------
+function scanAllExport(logical) {
+    for (const line of logical) {
+        const match = line.match(ALL_ASSIGNMENT_PATTERN);
+        if (!match)
+            continue;
+        const names = [...match[1].matchAll(QUOTED_NAME_PATTERN)].map((m) => m[2]);
+        if (names.length > 0)
+            return new Set(names);
+    }
+    return null;
+}
+function isExported(name, exportedSet) {
+    if (exportedSet)
+        return exportedSet.has(name);
+    // Conservative convention-based heuristic when no __all__ is present: a
+    // leading underscore is Python's own "not public" signal. This is a
+    // heuristic, not a semantic guarantee -- see module header comment.
+    return !name.startsWith("_");
+}
+// ---------------------------------------------------------------------------
+// Declarations (functions, async functions, classes, class methods).
+// ---------------------------------------------------------------------------
+function scanDeclarations(logical, exportedSet) {
+    const declarations = [];
+    // Indent levels of currently-open `class` blocks, outermost first. A line
+    // whose indentation drops to or below the top of this stack has exited
+    // that class body.
+    const classIndentStack = [];
+    for (let i = 0; i < logical.length; i++) {
+        const line = logical[i];
+        if (line.trim().length === 0)
+            continue;
+        const lineNumber = i + 1;
+        const indent = leadingWhitespaceCount(line);
+        while (classIndentStack.length > 0 && indent <= classIndentStack[classIndentStack.length - 1]) {
+            classIndentStack.pop();
+        }
+        const classMatch = line.match(CLASS_LINE_PATTERN);
+        if (classMatch) {
+            const name = classMatch[2];
+            declarations.push({ name, kind: "class", exported: isExported(name, exportedSet), line: lineNumber });
+            classIndentStack.push(indent);
+            continue;
+        }
+        const defMatch = line.match(DEF_LINE_PATTERN);
+        if (defMatch) {
+            const name = defMatch[2];
+            const isMethod = classIndentStack.length > 0 && indent > classIndentStack[classIndentStack.length - 1];
+            declarations.push({
+                name,
+                kind: isMethod ? "method" : "function",
+                // Methods are not tracked against __all__/underscore-export
+                // semantics -- __all__ only ever names module-level symbols in
+                // real Python, so claiming a method is "exported" would overclaim.
+                exported: isMethod ? false : isExported(name, exportedSet),
+                line: lineNumber,
+            });
+        }
+    }
+    return declarations;
+}
+function scanDynamicImportPatterns(logical, diagnostics, relativePath) {
+    for (const line of logical) {
+        if (!DYNAMIC_IMPORT_PATTERN.test(line))
+            continue;
+        diagnostics.push({
+            severity: "info",
+            code: "dynamic-import-pattern-unsupported",
+            message: "Detected a __import__/importlib.import_module call; dynamic imports are not resolved as import facts.",
+            path: relativePath,
+            analyzerId: PYTHON_ANALYZER_ID,
+        });
+    }
+}

package/dist/src/audits/core/pythonProjectMetadata.js

@@ -0,0 +1,80 @@
+import fs from "node:fs";
+import path from "node:path";
+const PYPROJECT_PROJECT_NAME_PATTERN = /^\s*name\s*=\s*["']([^"']+)["']\s*$/m;
+const PYPROJECT_PYTEST_SECTION_PATTERN = /^\s*\[tool\.pytest\.ini_options\]\s*$/m;
+const SETUP_CFG_PYTEST_SECTION_PATTERN = /^\s*\[tool:pytest\]\s*$/m;
+const INI_SECTION_HEADER_PATTERN = /^\s*\[([^\]]+)\]\s*$/;
+const INI_NAME_KEY_PATTERN = /^\s*name\s*=\s*(.+?)\s*$/;
+// Extracts the `name = ...` value from a setup.cfg-style [metadata] section
+// via a simple line scan (no INI parser dependency) -- stops at the next
+// "[section]" header or end of file.
+function extractSetupCfgProjectName(content) {
+    const lines = content.split(/\r\n|\r|\n/);
+    let inMetadataSection = false;
+    for (const line of lines) {
+        const sectionMatch = line.match(INI_SECTION_HEADER_PATTERN);
+        if (sectionMatch) {
+            inMetadataSection = sectionMatch[1].trim().toLowerCase() === "metadata";
+            continue;
+        }
+        if (!inMetadataSection)
+            continue;
+        const nameMatch = line.match(INI_NAME_KEY_PATTERN);
+        if (nameMatch)
+            return nameMatch[1];
+    }
+    return null;
+}
+export function collectPythonProjectMetadata(targetRoot, inventory) {
+    const warnings = [];
+    const knownPaths = new Set(inventory.files.map((f) => f.relativePath));
+    const has = (name) => knownPaths.has(name);
+    const hasPyprojectToml = has("pyproject.toml");
+    const hasRequirementsTxt = has("requirements.txt");
+    const hasSetupPy = has("setup.py");
+    const hasSetupCfg = has("setup.cfg");
+    const hasToxIni = has("tox.ini");
+    const hasPytestIni = has("pytest.ini");
+    let projectName = null;
+    let pytestSectionDetected = false;
+    if (hasPyprojectToml) {
+        const content = readSafely(targetRoot, "pyproject.toml", warnings);
+        if (content !== null) {
+            const nameMatch = content.match(PYPROJECT_PROJECT_NAME_PATTERN);
+            if (nameMatch)
+                projectName = nameMatch[1];
+            if (PYPROJECT_PYTEST_SECTION_PATTERN.test(content))
+                pytestSectionDetected = true;
+        }
+    }
+    if (hasSetupCfg) {
+        const content = readSafely(targetRoot, "setup.cfg", warnings);
+        if (content !== null) {
+            if (projectName === null) {
+                projectName = extractSetupCfgProjectName(content);
+            }
+            if (SETUP_CFG_PYTEST_SECTION_PATTERN.test(content))
+                pytestSectionDetected = true;
+        }
+    }
+    return {
+        hasPyprojectToml,
+        hasRequirementsTxt,
+        hasSetupPy,
+        hasSetupCfg,
+        hasToxIni,
+        hasPytestIni,
+        hasPytestConfiguration: hasPytestIni || pytestSectionDetected,
+        projectName,
+        warnings,
+    };
+}
+function readSafely(targetRoot, relativePath, warnings) {
+    try {
+        return fs.readFileSync(path.join(targetRoot, relativePath), "utf8");
+    }
+    catch (err) {
+        warnings.push(`Could not read ${relativePath}: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}

package/dist/src/audits/report/auditReportModel.js

@@ -55,6 +55,7 @@ export function summarizeSourceFacts(sourceFacts) {
         filesByLanguage: sourceFacts.filesByLanguage,
         filesByParseStatus: sourceFacts.filesByParseStatus,
         analyzerDiagnosticCount: sourceFacts.analyzerDiagnostics.length,
+        filesWithDiagnosticsCount: sourceFacts.files.filter((f) => f.diagnostics.length > 0).length,
         warnings: sourceFacts.warnings,
     };
 }
@@ -188,6 +189,8 @@ export function buildAuditReportModel(result, opts) {
         inventory: summarizeInventory(result.inventory),
         sourceOfTruth: summarizeSourceOfTruth(result.sourceOfTruth),
         sourceFacts: summarizeSourceFacts(result.sourceFacts),
+        pythonProjectMetadata: result.pythonProjectMetadata,
+        securitySummary: result.securitySummary,
         detectors,
         issues,
         skippedDetectors: result.skippedDetectors,

package/dist/src/audits/report/renderAuditJsonReport.js

@@ -19,6 +19,8 @@ export function renderAuditJsonReport(model) {
         inventory: model.inventory,
         sourceOfTruth: model.sourceOfTruth,
         sourceFacts: model.sourceFacts,
+        pythonProjectMetadata: model.pythonProjectMetadata,
+        securitySummary: model.securitySummary,
         detectors: model.detectors,
         issues: model.issues,
         skippedDetectors: model.skippedDetectors,

package/dist/src/audits/report/renderAuditTextReport.js

@@ -83,6 +83,20 @@ export function renderAuditTextReport(model) {
     if (model.sourceFacts.analyzerDiagnosticCount > 0) {
         lines.push(`  analyzer diagnostics: ${model.sourceFacts.analyzerDiagnosticCount}`);
     }
+    if (model.sourceFacts.filesWithDiagnosticsCount > 0) {
+        lines.push(`  files with a per-file diagnostic: ${model.sourceFacts.filesWithDiagnosticsCount}`);
+    }
+    lines.push("");
+    // v0.3.2 Batch 3 -- informational only. Presence booleans and a
+    // best-effort project name/pytest-configuration flag, never a
+    // release-readiness or dependency-health signal -- see
+    // pythonProjectMetadata.ts's own header comment.
+    lines.push("Python project metadata");
+    lines.push(divider("-"));
+    const pm = model.pythonProjectMetadata;
+    lines.push(`  pyproject.toml=${pm.hasPyprojectToml} requirements.txt=${pm.hasRequirementsTxt} setup.py=${pm.hasSetupPy} setup.cfg=${pm.hasSetupCfg} tox.ini=${pm.hasToxIni} pytest.ini=${pm.hasPytestIni}`);
+    lines.push(`  project name detected: ${pm.projectName ?? "(none)"}`);
+    lines.push(`  pytest configuration detected: ${pm.hasPytestConfiguration}`);
     lines.push("");
     lines.push("Source-of-truth summary");
     lines.push(divider("-"));
@@ -93,6 +107,32 @@ export function renderAuditTextReport(model) {
         lines.push(`  warnings: ${model.sourceOfTruth.warnings.length}`);
     }
     lines.push("");
+    // v0.3.2 Batch 4 -- bounded summary only. Never dumps raw scanner
+    // output/full finding text here (that lives in the original security
+    // validation report at securitySummary.reportPaths) -- this section only
+    // links to it and shows counts, matching the same "reference, don't
+    // duplicate" convention docs/security section 5 of the task spec asks for.
+    lines.push("Security validation summary");
+    lines.push(divider("-"));
+    if (!model.securitySummary.ran) {
+        lines.push("  (not run -- add \"security\" to --types to include it, e.g. --types code-rot,security)");
+    }
+    else {
+        const sec = model.securitySummary;
+        lines.push(`  Verdict: ${sec.verdictLabel ?? "(unknown)"}`);
+        lines.push(`  Checks: total=${sec.totalChecks} passed=${sec.checksPassed} warning=${sec.checksWarning} failed=${sec.checksFailed} skipped=${sec.checksSkipped}`);
+        lines.push(`  Findings: blocker=${sec.findingCounts.blocker} major=${sec.findingCounts.major} minor=${sec.findingCounts.minor} informational=${sec.findingCounts.informational} (mapped to ${sec.mappedIssueCount} audit issue(s))`);
+        if (sec.targetDescription) {
+            lines.push(`  Target: ${sanitizeLine(sec.targetDescription)}`);
+        }
+        if (sec.recommendedNextStep) {
+            lines.push(`  Next step: ${sanitizeLine(sec.recommendedNextStep)}`);
+        }
+        if (sec.reportPaths.text || sec.reportPaths.json) {
+            lines.push(`  Full report: ${sec.reportPaths.text ?? "(none)"} / ${sec.reportPaths.json ?? "(none)"}`);
+        }
+    }
+    lines.push("");
     lines.push("Issue summary");
     lines.push(divider("-"));
     lines.push(`  Total issues: ${model.summary.totalIssues}`);

package/dist/src/audits/security/mapSecurityFindingToAuditIssue.js

@@ -0,0 +1,70 @@
+import { makeAuditEvidence } from "../core/auditIssue.js";
+// ---------------------------------------------------------------------------
+// v0.3.2 Batch 4 — maps a structured SecurityFinding (already produced by the
+// existing securityValidation framework — see src/securityValidation/types.ts)
+// into an AuditIssue. Pure, no I/O, no re-running of any check: this module
+// only translates one already-computed result shape into another. Skipped
+// optional checks never reach this function at all (see
+// securityAuditAdapter.ts) — only findings attached to executed checks are
+// mapped, so "skipped" never silently becomes an issue or a passed result.
+// ---------------------------------------------------------------------------
+export const SECURITY_AUDIT_DETECTOR_ID = "security-validation-adapter";
+// SecuritySeverity -> AuditSeverity. Conservative mapping: "major" (a
+// mandatory-check-adjacent severity in the security-validation verdict
+// policy, see verdict.ts's calculateVerdict) maps to "high", never "medium",
+// so a security major finding is never understated relative to a code-rot
+// "high". "skipped" is not a real finding severity in practice (skippedCheck()
+// in runSecurityValidation.ts sets it on the SecurityCheckResult, not on a
+// SecurityFinding) but is mapped defensively to "info" for type completeness.
+const SEVERITY_MAP = {
+    blocker: "blocker",
+    major: "high",
+    minor: "medium",
+    informational: "info",
+    skipped: "info",
+};
+// Security findings originate from already-executed, structured scanners/
+// checks (npm audit, CodeQL, Semgrep, package-content inspection) rather than
+// from a per-finding confidence value — SecurityFinding carries no confidence
+// field of its own. "medium" is a conservative default that neither
+// overstates a scanner's certainty (npm audit CVE matches can be version-range
+// false positives) nor discounts it as unreliable.
+const DEFAULT_CONFIDENCE = "medium";
+const DEFAULT_FALSE_POSITIVE_RISK = "medium";
+export function mapSecurityFindingToAuditIssue(finding) {
+    const severity = SEVERITY_MAP[finding.severity];
+    // Mirrors verdict.ts's calculateVerdict: blocker and major findings are
+    // what drive a "not-ready-security-blocker-remains" verdict — minor/
+    // informational findings never block release or implementation on their own.
+    const isBlockingSeverity = finding.severity === "blocker" || finding.severity === "major";
+    const evidence = finding.evidence
+        ? [
+            makeAuditEvidence({
+                kind: "observation",
+                message: `Security validation (${finding.category}): ${finding.title}`,
+                excerpt: finding.evidence,
+                source: `security-validation:${finding.category}`,
+                confidence: DEFAULT_CONFIDENCE,
+            }),
+        ]
+        : [];
+    return {
+        id: `security:${finding.id}`,
+        auditType: "security",
+        detectorId: SECURITY_AUDIT_DETECTOR_ID,
+        title: finding.title,
+        description: finding.description,
+        severity,
+        confidence: DEFAULT_CONFIDENCE,
+        falsePositiveRisk: DEFAULT_FALSE_POSITIVE_RISK,
+        category: finding.category,
+        evidence,
+        affectedFiles: finding.affectedFiles ?? [],
+        recommendedAction: finding.recommendation ?? "Review the security validation report for remediation guidance.",
+        suggestedFixStrategy: finding.recommendation ?? "See the linked security validation report for details.",
+        validationCommands: ["npm run security:validate"],
+        releaseBlocking: isBlockingSeverity,
+        implementationBlocking: isBlockingSeverity,
+        autoFixEligible: false,
+    };
+}