auditor-lambda 0.1.0

package/dist/types/graph.d.ts

@@ -0,0 +1,18 @@
+export interface GraphEdge {
+    from: string;
+    to: string;
+    kind?: string;
+}
+export interface RouteEdge {
+    path: string;
+    handler: string;
+    method?: string;
+}
+export interface GraphBundle {
+    graphs: {
+        imports?: GraphEdge[];
+        calls?: GraphEdge[];
+        routes?: RouteEdge[];
+        [key: string]: unknown;
+    };
+}

package/dist/types/graph.js

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

package/dist/types/risk.d.ts

@@ -0,0 +1,9 @@
+export interface RiskItem {
+    unit_id: string;
+    risk_score: number;
+    signals: string[];
+    notes?: string[];
+}
+export interface RiskRegister {
+    items: RiskItem[];
+}

package/dist/types/risk.js

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

package/dist/types/runLedger.d.ts

@@ -0,0 +1,13 @@
+export interface RunLedgerEntry {
+    run_id: string;
+    provider: string;
+    obligation_id: string | null;
+    selected_executor: string | null;
+    status: string;
+    started_at: string;
+    ended_at: string;
+    result_path: string;
+}
+export interface RunLedger {
+    runs: RunLedgerEntry[];
+}

package/dist/types/runLedger.js

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

package/dist/types/runtimeValidation.d.ts

@@ -0,0 +1,22 @@
+export interface RuntimeValidationTask {
+    id: string;
+    kind: string;
+    target_paths: string[];
+    reason: string;
+    priority: "high" | "medium" | "low";
+    suggested_checks?: string[];
+    source_artifacts?: string[];
+}
+export interface RuntimeValidationTaskManifest {
+    tasks: RuntimeValidationTask[];
+}
+export interface RuntimeValidationResult {
+    task_id: string;
+    status: "pending" | "confirmed" | "not_confirmed" | "inconclusive";
+    summary: string;
+    evidence?: string[];
+    notes?: string[];
+}
+export interface RuntimeValidationReport {
+    results: RuntimeValidationResult[];
+}

package/dist/types/runtimeValidation.js

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

package/dist/types/sessionConfig.d.ts

@@ -0,0 +1,27 @@
+export type ProviderName = "auto" | "local-subprocess" | "subprocess-template" | "claude-code" | "opencode" | "vscode-task";
+export type ResolvedProviderName = Exclude<ProviderName, "auto">;
+export interface SubprocessTemplateConfig {
+    command_template: string[];
+    env?: Record<string, string>;
+}
+export interface ClaudeCodeConfig {
+    command?: string;
+    extra_args?: string[];
+}
+export interface OpenCodeConfig {
+    command?: string;
+    extra_args?: string[];
+}
+export interface VSCodeTaskConfig {
+    command_template: string[];
+    env?: Record<string, string>;
+}
+export interface SessionConfig {
+    provider?: ProviderName;
+    timeout_ms?: number;
+    ui_mode?: "visible" | "headless";
+    subprocess_template?: SubprocessTemplateConfig;
+    claude_code?: ClaudeCodeConfig;
+    opencode?: OpenCodeConfig;
+    vscode_task?: VSCodeTaskConfig;
+}

package/dist/types/sessionConfig.js

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

package/dist/types/surfaces.d.ts

@@ -0,0 +1,11 @@
+export interface SurfaceRecord {
+    id: string;
+    kind: string;
+    entrypoint: string;
+    exposure?: string;
+    methods?: string[];
+    notes?: string[];
+}
+export interface SurfaceManifest {
+    surfaces: SurfaceRecord[];
+}

package/dist/types/surfaces.js

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

package/dist/types/workerResult.d.ts

@@ -0,0 +1,13 @@
+export type WorkerResultStatus = "completed" | "blocked" | "failed" | "no_progress";
+export interface WorkerResult {
+    contract_version: "audit-code-worker-result/v1alpha1";
+    run_id: string;
+    obligation_id: string | null;
+    status: WorkerResultStatus;
+    progress_made: boolean;
+    selected_executor: string | null;
+    artifacts_written: string[];
+    summary: string;
+    next_likely_step: string | null;
+    errors: string[];
+}

package/dist/types/workerResult.js

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

package/dist/types/workerSession.d.ts

@@ -0,0 +1,13 @@
+export interface WorkerTask {
+    contract_version: "audit-code-worker/v1alpha1";
+    run_id: string;
+    repo_root: string;
+    artifacts_dir: string;
+    obligation_id: string | null;
+    preferred_executor: string;
+    result_path: string;
+    worker_command: string[];
+    audit_results_path?: string;
+    runtime_updates_path?: string;
+    external_analyzer_results_path?: string;
+}

package/dist/types/workerSession.js

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

package/dist/types.d.ts

@@ -0,0 +1,104 @@
+export type Lens = "correctness" | "architecture" | "maintainability" | "security" | "reliability" | "performance" | "data_integrity" | "tests" | "operability" | "config_deployment";
+export interface FileRecord {
+    path: string;
+    language: string;
+    size_bytes: number;
+    hash?: string;
+    excluded?: boolean;
+    exclusion_reason?: string;
+}
+export interface RepoManifest {
+    repository: {
+        name: string;
+        root?: string;
+        default_branch?: string;
+    };
+    generated_at: string;
+    files: FileRecord[];
+}
+export interface AuditUnit {
+    unit_id: string;
+    name: string;
+    kind?: string;
+    files: string[];
+    risk_score?: number;
+    required_lenses: Lens[];
+    critical_flows?: string[];
+}
+export interface UnitManifest {
+    units: AuditUnit[];
+}
+export interface ReviewedLineRange {
+    path: string;
+    start: number;
+    end: number;
+    pass_id: string;
+    lens?: Lens;
+    agent_role?: string;
+}
+export interface CoverageFileRecord {
+    path: string;
+    unit_ids: string[];
+    classification_status: string;
+    audit_status: string;
+    required_lenses: Lens[];
+    completed_lenses: Lens[];
+    reviewed_line_ranges: ReviewedLineRange[];
+}
+export interface CoverageMatrix {
+    files: CoverageFileRecord[];
+}
+export interface AuditTask {
+    task_id: string;
+    unit_id: string;
+    pass_id: string;
+    lens: Lens;
+    file_paths: string[];
+    line_ranges?: Array<{
+        path: string;
+        start: number;
+        end: number;
+    }>;
+    inputs?: Record<string, string>;
+    rationale: string;
+    priority?: "high" | "medium" | "low";
+    tags?: string[];
+}
+export interface Finding {
+    id: string;
+    title: string;
+    category: string;
+    severity: "critical" | "high" | "medium" | "low" | "info";
+    confidence: "high" | "medium" | "low";
+    lens: Lens;
+    summary: string;
+    affected_files: Array<{
+        path: string;
+        line_start?: number;
+        line_end?: number;
+        symbol?: string;
+    }>;
+    impact?: string;
+    likelihood?: string;
+    evidence?: string[];
+    reproduction?: string[];
+    remediation?: string[];
+    systemic?: boolean;
+    related_findings?: string[];
+}
+export interface AuditResult {
+    task_id: string;
+    unit_id: string;
+    pass_id: string;
+    lens: Lens;
+    agent_role?: string;
+    reviewed_ranges: Array<{
+        path: string;
+        start: number;
+        end: number;
+    }>;
+    findings: Finding[];
+    notes?: string[];
+    requires_followup?: boolean;
+    followup_tasks?: string[];
+}

package/dist/types.js

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

package/dist/validation/artifacts.d.ts

@@ -0,0 +1,3 @@
+import type { ArtifactBundle } from "../io/artifacts.js";
+import type { ValidationIssue } from "./basic.js";
+export declare function validateArtifactBundle(bundle: ArtifactBundle): ValidationIssue[];

package/dist/validation/artifacts.js

@@ -0,0 +1,191 @@
+import { requireKeys } from "./basic.js";
+function pushIssue(issues, path, message) {
+    issues.push({ path, message });
+}
+export function validateArtifactBundle(bundle) {
+    const issues = [];
+    if (bundle.repo_manifest) {
+        issues.push(...requireKeys(bundle.repo_manifest, "repo_manifest", ["repository", "generated_at", "files"]));
+    }
+    if (bundle.unit_manifest) {
+        issues.push(...requireKeys(bundle.unit_manifest, "unit_manifest", ["units"]));
+    }
+    if (bundle.coverage_matrix) {
+        issues.push(...requireKeys(bundle.coverage_matrix, "coverage_matrix", ["files"]));
+    }
+    if (bundle.graph_bundle) {
+        issues.push(...requireKeys(bundle.graph_bundle, "graph_bundle", ["graphs"]));
+    }
+    if (bundle.surface_manifest) {
+        issues.push(...requireKeys(bundle.surface_manifest, "surface_manifest", ["surfaces"]));
+    }
+    if (bundle.critical_flows) {
+        issues.push(...requireKeys(bundle.critical_flows, "critical_flows", ["flows"]));
+    }
+    if (bundle.flow_coverage) {
+        issues.push(...requireKeys(bundle.flow_coverage, "flow_coverage", ["flows"]));
+    }
+    if (bundle.risk_register) {
+        issues.push(...requireKeys(bundle.risk_register, "risk_register", ["items"]));
+    }
+    if (bundle.runtime_validation_tasks) {
+        issues.push(...requireKeys(bundle.runtime_validation_tasks, "runtime_validation_tasks", ["tasks"]));
+    }
+    if (bundle.runtime_validation_report) {
+        issues.push(...requireKeys(bundle.runtime_validation_report, "runtime_validation_report", ["results"]));
+    }
+    if (bundle.external_analyzer_results) {
+        issues.push(...requireKeys(bundle.external_analyzer_results, "external_analyzer_results", ["tool", "results"]));
+    }
+    const repoPaths = new Set(bundle.repo_manifest?.files.map((file) => file.path) ?? []);
+    const dispositionMap = new Map(bundle.file_disposition?.files.map((item) => [item.path, item.status]) ??
+        []);
+    const unitIds = new Set(bundle.unit_manifest?.units.map((unit) => unit.unit_id) ?? []);
+    const flowIds = new Set(bundle.critical_flows?.flows.map((flow) => flow.id) ?? []);
+    const runtimeTaskIds = new Set(bundle.runtime_validation_tasks?.tasks.map((task) => task.id) ?? []);
+    if (bundle.repo_manifest && bundle.coverage_matrix) {
+        const coveragePaths = new Set(bundle.coverage_matrix.files.map((file) => file.path));
+        for (const path of repoPaths) {
+            if (!coveragePaths.has(path)) {
+                pushIssue(issues, "coverage_matrix", `Missing coverage entry for ${path}`);
+            }
+        }
+    }
+    if (bundle.repo_manifest && bundle.file_disposition) {
+        const dispositionPaths = new Set(bundle.file_disposition.files.map((file) => file.path));
+        for (const path of repoPaths) {
+            if (!dispositionPaths.has(path)) {
+                pushIssue(issues, "file_disposition", `Missing disposition entry for ${path}`);
+            }
+        }
+    }
+    if (bundle.unit_manifest) {
+        for (const unit of bundle.unit_manifest.units) {
+            if (unit.files.length === 0) {
+                pushIssue(issues, `unit_manifest:${unit.unit_id}`, "Unit has no files");
+            }
+            if (unit.required_lenses.length === 0) {
+                pushIssue(issues, `unit_manifest:${unit.unit_id}`, "Unit has no required lenses");
+            }
+            for (const path of unit.files) {
+                if (!repoPaths.has(path)) {
+                    pushIssue(issues, `unit_manifest:${unit.unit_id}`, `Unit references unknown file ${path}`);
+                }
+                const disposition = dispositionMap.get(path);
+                if (disposition && disposition !== "included") {
+                    pushIssue(issues, `unit_manifest:${unit.unit_id}`, `Unit includes non-included file ${path} with disposition ${disposition}`);
+                }
+            }
+        }
+    }
+    if (bundle.coverage_matrix && bundle.unit_manifest) {
+        for (const file of bundle.coverage_matrix.files) {
+            if (!repoPaths.has(file.path)) {
+                pushIssue(issues, "coverage_matrix", `Coverage contains unknown file ${file.path}`);
+            }
+            for (const unitId of file.unit_ids) {
+                if (!unitIds.has(unitId)) {
+                    pushIssue(issues, `coverage_matrix:${file.path}`, `Coverage references unknown unit ${unitId}`);
+                }
+            }
+            const disposition = dispositionMap.get(file.path);
+            if (disposition &&
+                disposition !== "included" &&
+                file.audit_status !== "excluded") {
+                pushIssue(issues, `coverage_matrix:${file.path}`, `Non-included file should be excluded in coverage; found status ${file.audit_status}`);
+            }
+            for (const lens of file.completed_lenses) {
+                if (!file.required_lenses.includes(lens) &&
+                    file.audit_status !== "excluded") {
+                    pushIssue(issues, `coverage_matrix:${file.path}`, `Completed lens ${lens} is not listed in required_lenses`);
+                }
+            }
+        }
+    }
+    if (bundle.critical_flows) {
+        for (const flow of bundle.critical_flows.flows) {
+            if (flow.paths.length === 0) {
+                pushIssue(issues, `critical_flows:${flow.id}`, "Flow has no paths");
+            }
+            if (flow.entrypoints.length === 0) {
+                pushIssue(issues, `critical_flows:${flow.id}`, "Flow has no entrypoints");
+            }
+            for (const path of flow.paths) {
+                if (!repoPaths.has(path)) {
+                    pushIssue(issues, `critical_flows:${flow.id}`, `Flow references unknown file ${path}`);
+                }
+                const disposition = dispositionMap.get(path);
+                if (disposition && disposition !== "included") {
+                    pushIssue(issues, `critical_flows:${flow.id}`, `Flow includes non-included file ${path} with disposition ${disposition}`);
+                }
+            }
+        }
+    }
+    if (bundle.flow_coverage && bundle.critical_flows) {
+        for (const flow of bundle.flow_coverage.flows) {
+            if (!flowIds.has(flow.flow_id)) {
+                pushIssue(issues, `flow_coverage:${flow.flow_id}`, `Flow coverage references unknown flow ${flow.flow_id}`);
+            }
+            for (const lens of flow.completed_lenses) {
+                if (!flow.required_lenses.includes(lens)) {
+                    pushIssue(issues, `flow_coverage:${flow.flow_id}`, `Completed lens ${lens} is not in required_lenses`);
+                }
+            }
+            const expectedStatus = flow.required_lenses.length > 0 &&
+                flow.required_lenses.every((lens) => flow.completed_lenses.includes(lens))
+                ? "complete"
+                : flow.completed_lenses.length > 0
+                    ? "partial"
+                    : "pending";
+            if (flow.status !== expectedStatus) {
+                pushIssue(issues, `flow_coverage:${flow.flow_id}`, `Flow status ${flow.status} does not match expected ${expectedStatus}`);
+            }
+        }
+    }
+    if (bundle.risk_register && bundle.unit_manifest) {
+        const riskUnitIds = new Set(bundle.risk_register.items.map((item) => item.unit_id));
+        for (const unit of bundle.unit_manifest.units) {
+            if (!riskUnitIds.has(unit.unit_id)) {
+                pushIssue(issues, "risk_register", `Missing risk entry for unit ${unit.unit_id}`);
+            }
+        }
+    }
+    if (bundle.surface_manifest) {
+        for (const surface of bundle.surface_manifest.surfaces) {
+            if (!repoPaths.has(surface.entrypoint)) {
+                pushIssue(issues, `surface_manifest:${surface.id}`, `Surface references unknown entrypoint ${surface.entrypoint}`);
+            }
+            const disposition = dispositionMap.get(surface.entrypoint);
+            if (disposition && disposition !== "included") {
+                pushIssue(issues, `surface_manifest:${surface.id}`, `Surface entrypoint ${surface.entrypoint} is not included`);
+            }
+        }
+    }
+    if (bundle.runtime_validation_tasks) {
+        for (const task of bundle.runtime_validation_tasks.tasks) {
+            if (task.target_paths.length === 0) {
+                pushIssue(issues, `runtime_validation_tasks:${task.id}`, "Runtime validation task has no target paths");
+            }
+            for (const path of task.target_paths) {
+                if (!repoPaths.has(path)) {
+                    pushIssue(issues, `runtime_validation_tasks:${task.id}`, `Runtime validation task references unknown path ${path}`);
+                }
+            }
+        }
+    }
+    if (bundle.runtime_validation_report) {
+        for (const result of bundle.runtime_validation_report.results) {
+            if (!runtimeTaskIds.has(result.task_id)) {
+                pushIssue(issues, `runtime_validation_report:${result.task_id}`, `Runtime validation result references unknown task ${result.task_id}`);
+            }
+        }
+    }
+    if (bundle.external_analyzer_results) {
+        for (const item of bundle.external_analyzer_results.results) {
+            if (!repoPaths.has(item.path) && bundle.repo_manifest) {
+                pushIssue(issues, `external_analyzer_results:${item.id}`, `External analyzer result references unknown path ${item.path}`);
+            }
+        }
+    }
+    return issues;
+}

package/dist/validation/basic.d.ts

@@ -0,0 +1,5 @@
+export interface ValidationIssue {
+    path: string;
+    message: string;
+}
+export declare function requireKeys(record: Record<string, unknown>, path: string, keys: string[]): ValidationIssue[];

package/dist/validation/basic.js

@@ -0,0 +1,9 @@
+export function requireKeys(record, path, keys) {
+    const issues = [];
+    for (const key of keys) {
+        if (!(key in record)) {
+            issues.push({ path, message: `Missing required key: ${key}` });
+        }
+    }
+    return issues;
+}

package/dist/validation/sessionConfig.d.ts

@@ -0,0 +1,6 @@
+import type { SessionConfig } from "../types/sessionConfig.js";
+import type { ValidationIssue } from "./basic.js";
+export declare function validateSessionConfig(value: unknown): ValidationIssue[];
+export declare function validateConfiguredProviderEnvironment(sessionConfig: SessionConfig, options?: {
+    commandExists?: (command: string) => boolean;
+}): ValidationIssue[];

package/dist/validation/sessionConfig.js

@@ -0,0 +1,139 @@
+import { spawnSync } from "node:child_process";
+const VALID_PROVIDERS = new Set([
+    "auto",
+    "local-subprocess",
+    "subprocess-template",
+    "claude-code",
+    "opencode",
+    "vscode-task",
+]);
+const VALID_UI_MODES = new Set(["headless", "visible"]);
+function pushIssue(issues, path, message) {
+    issues.push({ path, message });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateStringArray(value, path, label, issues, options = {}) {
+    if (!Array.isArray(value)) {
+        pushIssue(issues, path, `${label} must be an array of strings.`);
+        return;
+    }
+    if (!options.allowEmptyArray && value.length === 0) {
+        pushIssue(issues, path, `${label} must not be empty.`);
+    }
+    for (const [index, item] of value.entries()) {
+        if (typeof item !== "string" || item.trim().length === 0) {
+            pushIssue(issues, `${path}[${index}]`, `${label} entries must be non-empty strings.`);
+        }
+    }
+}
+function validateEnvOverlay(value, path, issues) {
+    if (!isRecord(value)) {
+        pushIssue(issues, path, "env must be an object of string values.");
+        return;
+    }
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry !== "string") {
+            pushIssue(issues, `${path}.${key}`, "Environment override values must be strings.");
+        }
+    }
+}
+function validateTemplateProviderSection(value, path, issues, required) {
+    if (value === undefined) {
+        if (required) {
+            pushIssue(issues, path, "Provider requires this config section with a non-empty command_template.");
+        }
+        return;
+    }
+    if (!isRecord(value)) {
+        pushIssue(issues, path, "Provider config must be a JSON object.");
+        return;
+    }
+    if (value.command_template === undefined) {
+        if (required) {
+            pushIssue(issues, `${path}.command_template`, "command_template is required for this provider.");
+        }
+    }
+    else {
+        validateStringArray(value.command_template, `${path}.command_template`, "command_template", issues);
+    }
+    if (value.env !== undefined) {
+        validateEnvOverlay(value.env, `${path}.env`, issues);
+    }
+}
+function validateAgentProviderSection(value, path, issues) {
+    if (value === undefined) {
+        return;
+    }
+    if (!isRecord(value)) {
+        pushIssue(issues, path, "Provider config must be a JSON object.");
+        return;
+    }
+    if (value.command !== undefined) {
+        if (typeof value.command !== "string" || value.command.trim().length === 0) {
+            pushIssue(issues, `${path}.command`, "command must be a non-empty string when provided.");
+        }
+    }
+    if (value.extra_args !== undefined) {
+        validateStringArray(value.extra_args, `${path}.extra_args`, "extra_args", issues, { allowEmptyArray: true });
+    }
+}
+function commandExists(command) {
+    const lookupCommand = process.platform === "win32" ? "where" : "which";
+    const result = spawnSync(lookupCommand, [command], { stdio: "ignore" });
+    return result.status === 0;
+}
+export function validateSessionConfig(value) {
+    const issues = [];
+    if (value === undefined) {
+        return issues;
+    }
+    if (!isRecord(value)) {
+        pushIssue(issues, "session_config", "Session config must be a JSON object.");
+        return issues;
+    }
+    const provider = value.provider;
+    if (provider !== undefined) {
+        if (typeof provider !== "string") {
+            pushIssue(issues, "provider", "provider must be a string.");
+        }
+        else if (!VALID_PROVIDERS.has(provider)) {
+            pushIssue(issues, "provider", `Unsupported provider "${provider}". Expected one of: ${Array.from(VALID_PROVIDERS).join(", ")}.`);
+        }
+    }
+    const timeoutMs = value.timeout_ms;
+    if (timeoutMs !== undefined &&
+        (!Number.isInteger(timeoutMs) || Number(timeoutMs) <= 0)) {
+        pushIssue(issues, "timeout_ms", "timeout_ms must be a positive integer number of milliseconds.");
+    }
+    const uiMode = value.ui_mode;
+    if (uiMode !== undefined) {
+        if (typeof uiMode !== "string" || !VALID_UI_MODES.has(uiMode)) {
+            pushIssue(issues, "ui_mode", `ui_mode must be one of: ${Array.from(VALID_UI_MODES).join(", ")}.`);
+        }
+    }
+    validateTemplateProviderSection(value.subprocess_template, "subprocess_template", issues, provider === "subprocess-template");
+    validateTemplateProviderSection(value.vscode_task, "vscode_task", issues, provider === "vscode-task");
+    validateAgentProviderSection(value.claude_code, "claude_code", issues);
+    validateAgentProviderSection(value.opencode, "opencode", issues);
+    return issues;
+}
+export function validateConfiguredProviderEnvironment(sessionConfig, options = {}) {
+    const issues = [];
+    const lookupCommand = options.commandExists ?? commandExists;
+    const provider = sessionConfig.provider ?? "local-subprocess";
+    if (provider === "claude-code") {
+        const command = sessionConfig.claude_code?.command ?? "claude";
+        if (!lookupCommand(command)) {
+            pushIssue(issues, "claude_code.command", `Configured claude-code executable was not found on PATH: ${command}.`);
+        }
+    }
+    if (provider === "opencode") {
+        const command = sessionConfig.opencode?.command ?? "opencode";
+        if (!lookupCommand(command)) {
+            pushIssue(issues, "opencode.command", `Configured opencode executable was not found on PATH: ${command}.`);
+        }
+    }
+    return issues;
+}