@dailephd/my-dev-kit-lab 0.4.1 → 0.4.3

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

@@ -0,0 +1,116 @@
+import { makeAuditEvidence } from "../core/auditIssue.js";
+import { isBlockingSecuritySeverity, mapSecuritySeverityToAuditSeverity } from "./mapSecurityFindingToAuditIssue.js";
+// ---------------------------------------------------------------------------
+// v0.4.2 Batch 1 — pure Android SecurityFinding -> AuditIssue mapper.
+//
+// Android checks already reuse SecurityFinding as-is (see
+// src/mobile/android/audit/androidFinding.ts's own header comment) — there is
+// no parallel "AndroidSecurityFinding" type. What Android findings lose by
+// reusing the generic SecurityFinding shape is per-family taxonomy: every
+// Android finding's own `category` is the single shared value "static-scan"
+// (a SecurityCheckCategory), while the *specific* Android family (backup,
+// secrets, webview, ...) only lives on the owning AndroidCheckResult.category.
+// This mapper therefore takes a small AndroidAuditMappingContext alongside
+// the finding — supplied by the (future Batch 2) caller that already has the
+// owning AndroidCheckResult in hand — rather than trying to recover that
+// context by parsing the finding's own opaque id/evidence text.
+//
+// Reuses mapSecurityFindingToAuditIssue's severity/blocking policy exactly
+// (SecuritySeverity is the same shared type for Android and non-Android
+// findings) instead of defining a second severity table. Pure, no I/O, no
+// mutation, no CandidateEvidence handling — CandidateEvidence is a distinct
+// type (see src/mobile/android/advancedSecurity/candidateEvidence.ts) and
+// cannot be passed here at all: this function's parameter type is
+// SecurityFinding, not CandidateEvidence.
+// ---------------------------------------------------------------------------
+export const ANDROID_SECURITY_AUDIT_DETECTOR_ID = "android-security-validation-adapter";
+const DEFAULT_CONFIDENCE = "medium";
+const DEFAULT_FALSE_POSITIVE_RISK = "medium";
+// MobileConfidence carries an extra "unknown" state SecurityFinding-derived
+// AuditConfidence has no equivalent for; mapped to the same conservative
+// "medium" default the generic security mapper uses when no per-finding
+// confidence exists at all, rather than inventing a fourth AuditConfidence
+// value.
+function mapCheckConfidenceToAuditConfidence(confidence) {
+    if (confidence === "high" || confidence === "medium" || confidence === "low")
+        return confidence;
+    return DEFAULT_CONFIDENCE;
+}
+// makeAndroidFinding (src/mobile/android/audit/androidFinding.ts) is the sole
+// place Android findings compose their `evidence` string, always in the exact
+// form `location=<relativePath>(:<line>)?` (optionally followed by further
+// ` | `-joined detail segments). Extracting the line from that well-known,
+// single-producer format is not fabricating a source position — it is
+// reading a real value the same codebase already wrote, deterministically.
+// Guarded so a value is only trusted when its path matches the finding's own
+// affectedFiles[0]; anything else is left absent rather than guessed.
+const LOCATION_EVIDENCE_PATTERN = /(?:^|\s\|\s)location=([^\s|]+)/;
+function extractAndroidFindingLine(finding) {
+    if (!finding.evidence)
+        return undefined;
+    const relativePath = finding.affectedFiles?.[0];
+    if (!relativePath)
+        return undefined;
+    const match = LOCATION_EVIDENCE_PATTERN.exec(finding.evidence);
+    if (!match)
+        return undefined;
+    const [locationPath, lineText] = match[1].split(":");
+    if (locationPath !== relativePath || lineText === undefined)
+        return undefined;
+    const line = Number(lineText);
+    return Number.isInteger(line) && line > 0 ? line : undefined;
+}
+export function mapAndroidSecurityFindingToAuditIssue(finding, context) {
+    const severity = mapSecuritySeverityToAuditSeverity(finding.severity);
+    const isBlockingSeverity = isBlockingSecuritySeverity(finding.severity);
+    const relativePath = finding.affectedFiles?.[0];
+    const line = extractAndroidFindingLine(finding);
+    const provenanceSuffix = context.externalToolId ? `, tool=${context.externalToolId}` : "";
+    const evidence = finding.evidence
+        ? [
+            makeAuditEvidence({
+                kind: "observation",
+                message: `Android security validation (${context.checkId}${provenanceSuffix}): ${finding.title}`,
+                excerpt: finding.evidence,
+                filePath: relativePath,
+                line,
+                source: `android-security-validation:${context.checkId}`,
+                confidence: mapCheckConfidenceToAuditConfidence(context.checkConfidence),
+            }),
+        ]
+        : [];
+    const reportPath = context.reportReference?.json ?? context.reportReference?.text ?? undefined;
+    if (reportPath) {
+        evidence.push(makeAuditEvidence({
+            kind: "reference",
+            message: "Original Android security-validation report",
+            filePath: reportPath,
+            source: "android-security-validation:report",
+            confidence: DEFAULT_CONFIDENCE,
+        }));
+    }
+    return {
+        id: `android:${context.checkId}:${finding.id}`,
+        auditType: "security",
+        detectorId: ANDROID_SECURITY_AUDIT_DETECTOR_ID,
+        title: finding.title,
+        description: finding.description,
+        severity,
+        confidence: mapCheckConfidenceToAuditConfidence(context.checkConfidence),
+        falsePositiveRisk: DEFAULT_FALSE_POSITIVE_RISK,
+        // Deliberately the Android-specific check category (e.g.
+        // "android-backup-configuration"), not finding.category — every Android
+        // finding's own `category` is the single shared "static-scan" value, so
+        // reusing it here would make every mapped Android issue's category
+        // uselessly uniform. See module header comment.
+        category: context.checkCategory,
+        evidence,
+        affectedFiles: finding.affectedFiles ?? [],
+        recommendedAction: finding.recommendation ?? "Review the Android security validation report for remediation guidance.",
+        suggestedFixStrategy: finding.recommendation ?? "See the linked Android security validation report for details.",
+        validationCommands: ["npm run security:validate -- --profile android"],
+        releaseBlocking: isBlockingSeverity,
+        implementationBlocking: isBlockingSeverity,
+        autoFixEligible: false,
+    };
+}

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

@@ -31,12 +31,22 @@ const SEVERITY_MAP = {
 // false positives) nor discounts it as unreliable.
 const DEFAULT_CONFIDENCE = "medium";
 const DEFAULT_FALSE_POSITIVE_RISK = "medium";
+// Exported so other SecurityFinding-consuming mappers (e.g. the Android
+// audit-adapter mapper, v0.4.2 Batch 1) reuse the same conservative
+// severity policy instead of defining a second one.
+export function mapSecuritySeverityToAuditSeverity(severity) {
+    return SEVERITY_MAP[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. Exported for
+// reuse by other SecurityFinding-consuming mappers.
+export function isBlockingSecuritySeverity(severity) {
+    return severity === "blocker" || severity === "major";
+}
 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 severity = mapSecuritySeverityToAuditSeverity(finding.severity);
+    const isBlockingSeverity = isBlockingSecuritySeverity(finding.severity);
     const evidence = finding.evidence
         ? [
             makeAuditEvidence({

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

@@ -6,7 +6,9 @@ import { writeSecurityReportFiles } from "../../securityValidation/report/writeS
 import { DEFAULT_SECURITY_CHECKS, DEFAULT_SECURITY_PROFILE } from "../../securityValidation/validate/cliOptions.js";
 import { verdictToHumanLabel } from "../../securityValidation/validate/verdict.js";
 import { mapSecurityFindingToAuditIssue } from "./mapSecurityFindingToAuditIssue.js";
-export async function runSecurityAuditAdapter(options) {
+import { runAndroidAuditIntegration } from "./androidAuditIntegration.js";
+import { ANDROID_AUDIT_NOT_REQUESTED_SUMMARY, } from "./securityAuditTypes.js";
+export async function runSecurityAuditAdapter(options, dependencies = {}) {
     const { toolRoot, config } = options;
     const summary = await runSecurityValidation({
         cwd: toolRoot,
@@ -60,7 +62,23 @@ export async function runSecurityAuditAdapter(options) {
         verdictReasonSummary: summary.verdictReasonSummary ?? null,
         reportPaths: { text: textPath, json: jsonPath },
     };
-    return { issues, summary: securitySummary };
+    // v0.4.2 Batch 2 — Android integration is strictly additive: existing
+    // non-Android issues/summary above are computed identically whether or not
+    // Android is requested, and Android issues are always appended after them,
+    // never interleaved or reordered.
+    let androidIssues = [];
+    let androidSummary = ANDROID_AUDIT_NOT_REQUESTED_SUMMARY;
+    if (options.android?.enabled) {
+        const androidResult = await runAndroidAuditIntegration({
+            toolRoot,
+            targetPathArg: config.targetPathArg,
+            request: options.android,
+            runAndroidValidation: dependencies.runAndroidValidation,
+        });
+        androidIssues = androidResult.issues;
+        androidSummary = androidResult.summary;
+    }
+    return { issues: [...issues, ...androidIssues], summary: securitySummary, android: androidSummary };
 }
 function buildRunScopedReportSuffix(startedAt, finishedAt) {
     return `${sanitizeTimestamp(startedAt)}-${sanitizeTimestamp(finishedAt)}-${process.pid}`;

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

@@ -15,3 +15,40 @@ export const SECURITY_AUDIT_NOT_RUN_SUMMARY = {
     verdictReasonSummary: null,
     reportPaths: { text: null, json: null },
 };
+// Mirrors SecurityAuditReportSummary's own `ran`-first, always-present
+// convention: a status literal rather than inferring "did it run" from
+// nullable fields, so callers/tests can switch on one value instead of
+// reconstructing a state machine from several optional fields.
+export const ANDROID_AUDIT_STATUSES = ["not-requested", "not-applicable", "completed", "failed"];
+export const EMPTY_ANDROID_AUDIT_CANDIDATE_SUMMARY = {
+    totalCount: 0,
+    checksWithCandidates: 0,
+    byConfidence: { unknown: 0, low: 0, medium: 0, high: 0 },
+    byResolutionState: { resolved: 0, unresolved: 0, missing: 0, malformed: 0, unsupported: 0, "not-applicable": 0 },
+    byCategory: {},
+};
+export const ANDROID_AUDIT_NOT_REQUESTED_SUMMARY = {
+    requested: false,
+    applicable: null,
+    status: "not-requested",
+    verdict: null,
+    totalChecks: 0,
+    passedChecks: 0,
+    checksWithFindings: 0,
+    candidateOnlyChecks: 0,
+    skippedChecks: 0,
+    inconclusiveChecks: 0,
+    failedChecks: 0,
+    confirmedFindingCount: 0,
+    mappedIssueCount: 0,
+    candidateEvidenceCount: 0,
+    requestedGradleOperationCount: 0,
+    executedGradleOperationCount: 0,
+    requestedExternalToolCount: 0,
+    executedExternalToolCount: 0,
+    skippedExternalToolCount: 0,
+    reportPaths: { text: null, json: null },
+    warnings: [],
+    errors: [],
+    candidateSummary: EMPTY_ANDROID_AUDIT_CANDIDATE_SUMMARY,
+};

package/dist/src/evaluation/stageContextDeterminism/calculateStageContextDeterminism.js

@@ -0,0 +1,52 @@
+import { createHash } from "node:crypto";
+import { canonicalizeStageContextRun } from "./canonicalizeStageContextRun.js";
+function sha256Hex(text) {
+    return createHash("sha256").update(Buffer.from(text, "utf8")).digest("hex");
+}
+export function calculateStageContextDeterminism(candidates) {
+    if (candidates.length === 0) {
+        throw new Error("calculateStageContextDeterminism requires at least one candidate.");
+    }
+    if (candidates.length === 1) {
+        return {
+            availability: "not-applicable",
+            repeatCount: 1,
+            deterministic: null,
+            baselineSha256: null,
+            runDigests: [],
+            mismatchRunNumbers: [],
+            reason: "Repeated-run determinism requires at least two runs."
+        };
+    }
+    let runDigests;
+    try {
+        runDigests = candidates.map((candidate) => ({
+            runNumber: candidate.runNumber,
+            sha256: sha256Hex(canonicalizeStageContextRun(candidate.value))
+        }));
+    }
+    catch {
+        return {
+            availability: "unavailable",
+            repeatCount: candidates.length,
+            deterministic: null,
+            baselineSha256: null,
+            runDigests: [],
+            mismatchRunNumbers: [],
+            reason: "Stage-context run values could not be canonicalized for determinism comparison."
+        };
+    }
+    const baselineSha256 = runDigests[0].sha256;
+    const mismatchRunNumbers = runDigests
+        .filter((digest) => digest.sha256 !== baselineSha256)
+        .map((digest) => digest.runNumber);
+    return {
+        availability: "available",
+        repeatCount: candidates.length,
+        deterministic: mismatchRunNumbers.length === 0,
+        baselineSha256,
+        runDigests,
+        mismatchRunNumbers,
+        reason: null
+    };
+}

package/dist/src/evaluation/stageContextDeterminism/canonicalizeStageContextRun.js

@@ -0,0 +1,53 @@
+export function canonicalizeStageContextRun(value) {
+    const seen = new WeakSet();
+    function serialize(input) {
+        if (input === null)
+            return "null";
+        const kind = typeof input;
+        if (kind === "bigint") {
+            throw new TypeError("Stage-context run values must not contain BigInt.");
+        }
+        if (kind === "function") {
+            throw new TypeError("Stage-context run values must not contain functions.");
+        }
+        if (kind === "symbol") {
+            throw new TypeError("Stage-context run values must not contain symbols.");
+        }
+        if (kind === "undefined") {
+            return "null";
+        }
+        if (kind === "number") {
+            if (!Number.isFinite(input)) {
+                throw new RangeError("Stage-context run values must not contain non-finite numbers.");
+            }
+            return JSON.stringify(input);
+        }
+        if (kind === "boolean" || kind === "string") {
+            return JSON.stringify(input);
+        }
+        if (Array.isArray(input)) {
+            if (seen.has(input)) {
+                throw new TypeError("Stage-context run values must not contain circular references.");
+            }
+            seen.add(input);
+            const items = input.map((item) => (item === undefined ? "null" : serialize(item)));
+            seen.delete(input);
+            return `[${items.join(",")}]`;
+        }
+        if (kind === "object") {
+            const obj = input;
+            if (seen.has(obj)) {
+                throw new TypeError("Stage-context run values must not contain circular references.");
+            }
+            seen.add(obj);
+            const keys = Object.keys(obj)
+                .filter((key) => obj[key] !== undefined)
+                .sort();
+            const parts = keys.map((key) => `${JSON.stringify(key)}:${serialize(obj[key])}`);
+            seen.delete(obj);
+            return `{${parts.join(",")}}`;
+        }
+        throw new TypeError("Stage-context run values contain an unsupported type.");
+    }
+    return serialize(value);
+}

package/dist/src/evaluation/stageContextDeterminism/index.js

@@ -0,0 +1,2 @@
+export { canonicalizeStageContextRun } from "./canonicalizeStageContextRun.js";
+export { calculateStageContextDeterminism } from "./calculateStageContextDeterminism.js";

package/dist/src/evaluation/stageContextDeterminism/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/evaluation/stageContextExpectations/index.js

@@ -0,0 +1,2 @@
+export { validateStageContextExpectationFixtureV1 } from "./validation.js";
+export { readStageContextExpectationFixtureV1 } from "./readStageContextExpectationFixtureV1.js";

package/dist/src/evaluation/stageContextExpectations/readStageContextExpectationFixtureV1.js

@@ -0,0 +1,50 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { validateStageContextExpectationFixtureV1 } from "./validation.js";
+export async function readStageContextExpectationFixtureV1(sourcePathInput) {
+    const sourcePath = path.resolve(sourcePathInput);
+    let raw;
+    try {
+        raw = await readFile(sourcePath, "utf8");
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT") {
+            return {
+                ok: false,
+                sourcePath,
+                code: "FILE_NOT_FOUND",
+                message: `Stage context expectation fixture was not found at "${sourcePath}".`
+            };
+        }
+        return {
+            ok: false,
+            sourcePath,
+            code: "UNREADABLE_FILE",
+            message: `Stage context expectation fixture at "${sourcePath}" could not be read: ${error.message}`
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            sourcePath,
+            code: "MALFORMED_JSON",
+            message: `Stage context expectation fixture at "${sourcePath}" is not valid JSON: ${error.message}`
+        };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return {
+            ok: false,
+            sourcePath,
+            code: "NON_OBJECT_ROOT",
+            message: `Stage context expectation fixture at "${sourcePath}" must parse to a JSON object at the root.`,
+            expected: "object",
+            actual: parsed
+        };
+    }
+    return validateStageContextExpectationFixtureV1(parsed, sourcePath);
+}

package/dist/src/evaluation/stageContextExpectations/readTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/src/evaluation/stageContextExpectations/types.js

@@ -0,0 +1 @@
+export {};