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

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

@@ -0,0 +1,125 @@
+import path from "node:path";
+import { AUDIT_FAIL_ON_THRESHOLDS, AUDIT_INCLUDE_AREAS, AUDIT_OUTPUT_FORMATS, AUDIT_TYPES, DEFAULT_AUDIT_FAIL_ON_THRESHOLD, DEFAULT_AUDIT_INCLUDE_AREAS, DEFAULT_AUDIT_OUTPUT_FORMATS, DEFAULT_AUDIT_TYPES, PLANNED_AUDIT_TYPES, } from "./auditTypes.js";
+const FLAGS_WITH_VALUE = {
+    "--target": "target",
+    "--types": "types",
+    "--include": "include",
+    "--format": "format",
+    "--fail-on": "failOn",
+    "--out": "out",
+};
+export function parseAuditArgs(argv) {
+    const result = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const key = FLAGS_WITH_VALUE[arg];
+        if (!key)
+            continue;
+        if (i + 1 >= argv.length) {
+            throw new Error(`Missing value for ${arg}. Expected a value after ${arg}.`);
+        }
+        result[key] = argv[++i];
+    }
+    return result;
+}
+export function normalizeAuditConfig(raw, toolRoot) {
+    const types = parseTypesOption(raw.types);
+    const include = parseIncludeOption(raw.include);
+    const formats = parseFormatOption(raw.format);
+    const failOn = parseFailOnOption(raw.failOn);
+    const out = raw.out !== undefined ? resolveOutDir(raw.out) : defaultOutDir(toolRoot, types.value);
+    return {
+        targetPathArg: raw.target,
+        targetMode: raw.target === undefined ? "self" : "external",
+        types: types.value,
+        typesWereDefault: types.wasDefault,
+        include: include.value,
+        includeWereDefault: include.wasDefault,
+        formats: formats.value,
+        formatsWereDefault: formats.wasDefault,
+        failOn: failOn.value,
+        failOnWasDefault: failOn.wasDefault,
+        out,
+        outWasDefault: raw.out === undefined,
+        isDefaultRun: raw.target === undefined &&
+            raw.types === undefined &&
+            raw.include === undefined &&
+            raw.format === undefined &&
+            raw.failOn === undefined &&
+            raw.out === undefined,
+    };
+}
+function splitAndNormalizeList(raw, flagName) {
+    const parts = raw.split(",").map((p) => p.trim());
+    if (parts.some((p) => p.length === 0)) {
+        throw new Error(`Invalid ${flagName} value: empty entries are not allowed. Got "${raw}".`);
+    }
+    return parts;
+}
+function parseTypesOption(raw) {
+    if (raw === undefined) {
+        return { value: [...DEFAULT_AUDIT_TYPES], wasDefault: true };
+    }
+    const parts = splitAndNormalizeList(raw, "--types");
+    const unknown = parts.filter((p) => !AUDIT_TYPES.includes(p));
+    if (unknown.length > 0) {
+        throw new Error(`Invalid --types value(s): ${unknown.join(", ")}. Valid values are: ${AUDIT_TYPES.join(", ")}.`);
+    }
+    const planned = parts.filter((p) => PLANNED_AUDIT_TYPES.includes(p));
+    if (planned.length > 0) {
+        throw new Error(`--types value(s) planned but not implemented: ${planned.join(", ")}. Only "code-rot" is implemented in this version.`);
+    }
+    const unique = new Set(parts);
+    const ordered = AUDIT_TYPES.filter((id) => unique.has(id));
+    return { value: ordered, wasDefault: false };
+}
+function parseIncludeOption(raw) {
+    if (raw === undefined) {
+        return { value: [...DEFAULT_AUDIT_INCLUDE_AREAS], wasDefault: true };
+    }
+    const parts = splitAndNormalizeList(raw, "--include");
+    const invalid = parts.filter((p) => !AUDIT_INCLUDE_AREAS.includes(p));
+    if (invalid.length > 0) {
+        throw new Error(`Invalid --include value(s): ${invalid.join(", ")}. Valid values are: ${AUDIT_INCLUDE_AREAS.join(", ")}.`);
+    }
+    const unique = new Set(parts);
+    const ordered = AUDIT_INCLUDE_AREAS.filter((id) => unique.has(id));
+    return { value: ordered, wasDefault: false };
+}
+function parseFormatOption(raw) {
+    if (raw === undefined) {
+        return { value: [...DEFAULT_AUDIT_OUTPUT_FORMATS], wasDefault: true };
+    }
+    const parts = splitAndNormalizeList(raw, "--format");
+    const invalid = parts.filter((p) => !AUDIT_OUTPUT_FORMATS.includes(p));
+    if (invalid.length > 0) {
+        throw new Error(`Invalid --format value(s): ${invalid.join(", ")}. Valid values are: ${AUDIT_OUTPUT_FORMATS.join(", ")}.`);
+    }
+    const unique = new Set(parts);
+    const ordered = AUDIT_OUTPUT_FORMATS.filter((id) => unique.has(id));
+    return { value: ordered, wasDefault: false };
+}
+function parseFailOnOption(raw) {
+    if (raw === undefined) {
+        return { value: DEFAULT_AUDIT_FAIL_ON_THRESHOLD, wasDefault: true };
+    }
+    const value = raw.trim();
+    if (!AUDIT_FAIL_ON_THRESHOLDS.includes(value)) {
+        throw new Error(`Invalid --fail-on value: "${raw}". Valid values are: ${AUDIT_FAIL_ON_THRESHOLDS.join(", ")}.`);
+    }
+    return { value: value, wasDefault: false };
+}
+function resolveOutDir(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+        throw new Error("Invalid --out value: path must not be empty.");
+    }
+    return path.resolve(trimmed);
+}
+function defaultOutDir(toolRoot, types) {
+    // Batch 1 only ever has "code-rot" as a valid resolved type, but this stays
+    // written generically so later batches (quality/security/project) don't
+    // need to touch this function, only extend the audit-type vocabulary.
+    const primaryType = types[0] ?? "code-rot";
+    return path.join(path.resolve(toolRoot), "reports", "audits", primaryType);
+}

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

@@ -0,0 +1,75 @@
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 1 — audit exit code policy.
+//
+// 0 = no issue met the --fail-on threshold (and no config/target/runtime
+//     error occurred).
+// 1 = at least one issue met or exceeded the --fail-on threshold.
+// 2 = invalid config, invalid target, or an audit runtime failure. This
+//     code is never returned by calculateAuditExitCode() below (a pure,
+//     issue-driven function) -- it is the caller's (scripts/audits/
+//     runAudit.ts) responsibility to catch parse/config/target errors and
+//     exit with AUDIT_EXIT_CODES.FATAL_ERROR directly, mirroring how
+//     scripts/security/validate.ts handles its own parse/target try/catch.
+// ---------------------------------------------------------------------------
+export const AUDIT_EXIT_CODES = {
+    SUCCESS: 0,
+    THRESHOLD_BREACHED: 1,
+    FATAL_ERROR: 2,
+};
+// "info" is a valid issue severity but is intentionally below every
+// selectable --fail-on threshold (including "low") -- it can never breach.
+const SEVERITY_RANK = {
+    info: 0,
+    low: 1,
+    medium: 2,
+    high: 3,
+    blocker: 4,
+};
+// "none" ranks above every severity so it can never be breached.
+const THRESHOLD_RANK = {
+    low: 1,
+    medium: 2,
+    high: 3,
+    blocker: 4,
+    none: Number.POSITIVE_INFINITY,
+};
+export function issueBreachesFailOnThreshold(severity, failOn) {
+    if (failOn === "none")
+        return false;
+    return SEVERITY_RANK[severity] >= THRESHOLD_RANK[failOn];
+}
+// v0.3.0 Batch 5 — additive export. Report-building code (src/audits/report/
+// auditReportModel.ts) needs the same severity ranking to compute a
+// "highest severity present" summary field, and must not hardcode a second
+// copy of this table (see Batch 5 spec 3.2). Signature/behavior of the two
+// functions above is unchanged.
+export function getHighestSeverity(issues) {
+    if (issues.length === 0)
+        return null;
+    let highest = issues[0].severity;
+    for (const issue of issues) {
+        if (SEVERITY_RANK[issue.severity] > SEVERITY_RANK[highest]) {
+            highest = issue.severity;
+        }
+    }
+    return highest;
+}
+// Pure function: given a final issue list and the configured --fail-on
+// threshold, decides between SUCCESS and THRESHOLD_BREACHED. Never returns
+// FATAL_ERROR -- see file header.
+export function calculateAuditExitCode(issues, failOn) {
+    if (failOn === "none") {
+        return { exitCode: AUDIT_EXIT_CODES.SUCCESS, reason: "--fail-on none: findings never block the command." };
+    }
+    const breaching = issues.filter((issue) => issueBreachesFailOnThreshold(issue.severity, failOn));
+    if (breaching.length > 0) {
+        return {
+            exitCode: AUDIT_EXIT_CODES.THRESHOLD_BREACHED,
+            reason: `${breaching.length} issue(s) met or exceeded the --fail-on ${failOn} threshold.`,
+        };
+    }
+    return {
+        exitCode: AUDIT_EXIT_CODES.SUCCESS,
+        reason: `No issues met the --fail-on ${failOn} threshold.`,
+    };
+}

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

@@ -0,0 +1,20 @@
+export const AUDIT_EVIDENCE_KINDS = [
+    "file",
+    "command",
+    "diff",
+    "reference",
+    "observation",
+];
+const MAX_EXCERPT_LENGTH = 400;
+// Bounds an excerpt to a safe preview length so evidence never embeds huge
+// file contents. Does not attempt secret redaction here — detectors that
+// scan for secret-shaped content are responsible for redacting before this
+// point, same division of responsibility documented in exploitEvidence.ts.
+export function boundExcerpt(raw, maxLength = MAX_EXCERPT_LENGTH) {
+    if (raw.length <= maxLength)
+        return raw;
+    return `${raw.slice(0, maxLength)}... [truncated, ${raw.length} chars total]`;
+}
+export function makeAuditEvidence(evidence) {
+    return evidence.excerpt !== undefined ? { ...evidence, excerpt: boundExcerpt(evidence.excerpt) } : evidence;
+}

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

@@ -0,0 +1,40 @@
+import { STALE_COMMAND_REFERENCE_DETECTOR, DOCS_CODE_MISMATCH_DETECTOR, PACKAGE_RELEASE_ROT_DETECTOR, DUPLICATE_IMPLEMENTATION_DETECTOR, DEAD_CODE_CANDIDATE_DETECTOR, TEST_ROT_DETECTOR, ARCHITECTURE_DRIFT_DETECTOR, DEPENDENCY_ENVIRONMENT_ROT_DETECTOR, CROSS_PLATFORM_ROT_DETECTOR, SECURITY_VALIDATION_ASSUMPTION_ROT_DETECTOR, } from "../codeRot/codeRotDetectors.js";
+// v0.3.0 Batch 3/4 — code-rot detectors. Batch 4 completes the full
+// code-rot detector family planned in docs/ROADMAP.md's v0.3.0 section:
+// stale command/workflow reference, docs/code mismatch, package/release
+// rot (Batch 3), plus duplicate-implementation, dead-code, test-rot,
+// architecture-drift, dependency/environment-rot, cross-platform-rot, and
+// security/validation-assumption-rot (Batch 4).
+export const DEFAULT_AUDIT_REGISTRY = createAuditRegistry([
+    STALE_COMMAND_REFERENCE_DETECTOR,
+    DOCS_CODE_MISMATCH_DETECTOR,
+    PACKAGE_RELEASE_ROT_DETECTOR,
+    DUPLICATE_IMPLEMENTATION_DETECTOR,
+    DEAD_CODE_CANDIDATE_DETECTOR,
+    TEST_ROT_DETECTOR,
+    ARCHITECTURE_DRIFT_DETECTOR,
+    DEPENDENCY_ENVIRONMENT_ROT_DETECTOR,
+    CROSS_PLATFORM_ROT_DETECTOR,
+    SECURITY_VALIDATION_ASSUMPTION_ROT_DETECTOR,
+]);
+// Validates a detector list has no duplicate ids. Later batches call this
+// when assembling their own registries; Batch 1's empty default trivially
+// passes.
+export function createAuditRegistry(detectors) {
+    const seen = new Set();
+    for (const detector of detectors) {
+        if (seen.has(detector.id)) {
+            throw new Error(`Duplicate audit detector id: "${detector.id}".`);
+        }
+        seen.add(detector.id);
+    }
+    return detectors;
+}
+// Filters a registry down to detectors matching the selected audit types and
+// at least one selected include area. Order is preserved from the input
+// registry (deterministic, not re-sorted).
+export function selectDetectors(registry, types, include) {
+    const typeSet = new Set(types);
+    const includeSet = new Set(include);
+    return registry.filter((detector) => typeSet.has(detector.auditType) && detector.supportedIncludeAreas.some((area) => includeSet.has(area)));
+}

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

@@ -0,0 +1,71 @@
+import { calculateAuditExitCode } from "./auditExitCode.js";
+import { DEFAULT_AUDIT_REGISTRY, selectDetectors } from "./auditRegistry.js";
+import { resolveAuditTarget } from "./auditTarget.js";
+import { scanProjectInventory } from "./projectInventory.js";
+import { collectSourceOfTruth } from "./sourceOfTruth.js";
+export async function runAudit(options) {
+    const { config, toolRoot } = options;
+    const registry = options.registry ?? DEFAULT_AUDIT_REGISTRY;
+    const target = options.target ?? resolveAuditTarget(config.targetPathArg, toolRoot);
+    const inventory = scanProjectInventory(target.rootPath);
+    const sourceOfTruth = collectSourceOfTruth(target.rootPath, inventory);
+    const selected = selectDetectors(registry, config.types, config.include);
+    const ctx = { target, config, inventory, sourceOfTruth };
+    const issues = [];
+    const skippedDetectors = [];
+    const detectorErrors = [];
+    // Sequential, in registry order -- keeps issue ordering deterministic
+    // without needing a secondary sort step.
+    for (const detector of selected) {
+        try {
+            if (detector.shouldSkip) {
+                const decision = detector.shouldSkip(ctx);
+                if (decision.skip) {
+                    skippedDetectors.push({ id: detector.id, reason: decision.reason });
+                    continue;
+                }
+            }
+            const detectorIssues = await detector.run(ctx);
+            issues.push(...detectorIssues);
+        }
+        catch (err) {
+            detectorErrors.push({
+                id: detector.id,
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    const issueCounts = countIssuesBySeverity(issues);
+    const { exitCode, reason } = calculateAuditExitCode(issues, config.failOn);
+    return {
+        configSummary: {
+            types: config.types,
+            include: config.include,
+            formats: config.formats,
+            failOn: config.failOn,
+            out: config.out,
+            isDefaultRun: config.isDefaultRun,
+        },
+        targetSummary: {
+            rootPath: target.rootPath,
+            displayName: target.displayName,
+            isSelf: target.isSelf,
+        },
+        issues,
+        skippedDetectors,
+        detectorErrors,
+        issueCounts,
+        exitCode,
+        exitReason: reason,
+        inventory,
+        sourceOfTruth,
+        noDetectorsRegistered: selected.length === 0,
+    };
+}
+function countIssuesBySeverity(issues) {
+    const counts = { blocker: 0, high: 0, medium: 0, low: 0, info: 0 };
+    for (const issue of issues) {
+        counts[issue.severity] += 1;
+    }
+    return counts;
+}

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

@@ -0,0 +1,19 @@
+import path from "node:path";
+import { resolveLocalProjectTarget } from "../../core/localProjectTarget.js";
+// Resolves and validates an audit target. Throws a descriptive Error (no
+// stack trace wrapper) for a missing path or a non-directory path. Does not
+// modify the target in any way.
+export function resolveAuditTarget(targetPathArg, toolRoot) {
+    const metadata = resolveLocalProjectTarget(targetPathArg, toolRoot);
+    const displayName = metadata.packageName ?? path.basename(metadata.targetRoot);
+    return {
+        rootPath: metadata.targetRoot,
+        displayName,
+        exists: true,
+        isDirectory: true,
+        packageJsonPath: metadata.hasPackageJson ? path.join(metadata.targetRoot, "package.json") : null,
+        gitRoot: metadata.hasGit ? metadata.targetRoot : null,
+        isSelf: metadata.isSelf,
+        safeReportOutputRoot: path.join(path.resolve(toolRoot), "reports", "audits"),
+    };
+}

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

@@ -0,0 +1,30 @@
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 1 — generic audit framework core vocabulary.
+//
+// Deliberately kept separate from src/securityValidation/types.ts. Audit and
+// security-validation are two distinct frameworks (see docs/ROADMAP.md); a
+// later v0.3.2 batch may integrate their results into a unified report, but
+// this batch keeps the audit issue schema independent even where a
+// vocabulary word (e.g. "blocker") happens to be shared.
+// ---------------------------------------------------------------------------
+// Recognized --types values. Only "code-rot" has real detector coverage in
+// Batch 1 — the rest are known, named future audit types that must fail
+// cleanly with a "planned but not implemented" message rather than being
+// silently accepted or treated as an unknown/garbage value.
+export const AUDIT_TYPES = ["code-rot", "quality", "security", "project", "all"];
+export const IMPLEMENTED_AUDIT_TYPES = ["code-rot"];
+export const PLANNED_AUDIT_TYPES = ["quality", "security", "project", "all"];
+export const DEFAULT_AUDIT_TYPES = IMPLEMENTED_AUDIT_TYPES;
+export const AUDIT_INCLUDE_AREAS = ["docs", "tests", "package", "architecture", "cli"];
+export const DEFAULT_AUDIT_INCLUDE_AREAS = AUDIT_INCLUDE_AREAS;
+export const AUDIT_OUTPUT_FORMATS = ["text", "json"];
+export const DEFAULT_AUDIT_OUTPUT_FORMATS = ["text", "json"];
+// "none" is a valid, explicit opt-out — findings never block the command.
+export const AUDIT_FAIL_ON_THRESHOLDS = ["blocker", "high", "medium", "low", "none"];
+export const DEFAULT_AUDIT_FAIL_ON_THRESHOLD = "blocker";
+// Issue severity. Distinct from AuditFailOnThreshold: "info" is a valid
+// issue severity but not a selectable --fail-on threshold (an info-severity
+// issue can never breach any threshold, including "low").
+export const AUDIT_SEVERITIES = ["blocker", "high", "medium", "low", "info"];
+export const AUDIT_CONFIDENCE_LEVELS = ["high", "medium", "low"];
+export const AUDIT_FALSE_POSITIVE_RISK_LEVELS = ["high", "medium", "low"];