auditor-lambda 0.1.0

package/dist/coverage.d.ts

@@ -0,0 +1,11 @@
+import type { CoverageFileRecord, CoverageMatrix, Lens, ReviewedLineRange } from "./types.js";
+export declare function mergeRanges(ranges: ReviewedLineRange[]): ReviewedLineRange[];
+export declare function createCoverageMatrix(paths: string[]): CoverageMatrix;
+export declare function markExcludedPath(matrix: CoverageMatrix, path: string, classificationStatus: string): void;
+export declare function applyUnitCoverage(matrix: CoverageMatrix, path: string, unitId: string, requiredLenses: Lens[]): void;
+export declare function applyReviewedRanges(matrix: CoverageMatrix, reviewedRanges: ReviewedLineRange[]): void;
+export declare function findUncoveredFiles(matrix: CoverageMatrix): CoverageFileRecord[];
+export declare function buildRequeueTargets(matrix: CoverageMatrix): Array<{
+    path: string;
+    missing_lenses: Lens[];
+}>;

package/dist/coverage.js

@@ -0,0 +1,102 @@
+function sortRanges(ranges) {
+    return [...ranges].sort((a, b) => {
+        if (a.path !== b.path)
+            return a.path.localeCompare(b.path);
+        if (a.start !== b.start)
+            return a.start - b.start;
+        return a.end - b.end;
+    });
+}
+export function mergeRanges(ranges) {
+    const sorted = sortRanges(ranges);
+    const merged = [];
+    for (const range of sorted) {
+        const last = merged[merged.length - 1];
+        if (!last || last.path !== range.path || range.start > last.end + 1) {
+            merged.push({ ...range });
+            continue;
+        }
+        last.end = Math.max(last.end, range.end);
+        last.pass_id = `${last.pass_id},${range.pass_id}`;
+        last.agent_role = [last.agent_role, range.agent_role]
+            .filter(Boolean)
+            .join(",");
+    }
+    return merged;
+}
+export function createCoverageMatrix(paths) {
+    return {
+        files: paths.map((path) => ({
+            path,
+            unit_ids: [],
+            classification_status: "unclassified",
+            audit_status: "pending",
+            required_lenses: [],
+            completed_lenses: [],
+            reviewed_line_ranges: [],
+        })),
+    };
+}
+export function markExcludedPath(matrix, path, classificationStatus) {
+    const record = matrix.files.find((file) => file.path === path);
+    if (!record)
+        return;
+    record.classification_status = classificationStatus;
+    record.audit_status = "excluded";
+    record.required_lenses = [];
+    record.completed_lenses = [];
+    record.reviewed_line_ranges = [];
+    record.unit_ids = [];
+}
+export function applyUnitCoverage(matrix, path, unitId, requiredLenses) {
+    const record = matrix.files.find((file) => file.path === path);
+    if (!record || record.audit_status === "excluded")
+        return;
+    if (!record.unit_ids.includes(unitId)) {
+        record.unit_ids.push(unitId);
+    }
+    record.classification_status = "classified";
+    record.required_lenses = [
+        ...new Set([...record.required_lenses, ...requiredLenses]),
+    ];
+}
+export function applyReviewedRanges(matrix, reviewedRanges) {
+    for (const range of reviewedRanges) {
+        const record = matrix.files.find((file) => file.path === range.path);
+        if (!record || record.audit_status === "excluded")
+            continue;
+        record.reviewed_line_ranges.push(range);
+        record.reviewed_line_ranges = mergeRanges(record.reviewed_line_ranges);
+        if (range.lens && !record.completed_lenses.includes(range.lens)) {
+            record.completed_lenses.push(range.lens);
+        }
+    }
+    for (const file of matrix.files) {
+        const hasAllRequired = file.required_lenses.every((lens) => file.completed_lenses.includes(lens));
+        if (file.audit_status === "excluded") {
+            continue;
+        }
+        if (hasAllRequired && file.required_lenses.length > 0) {
+            file.audit_status = "complete";
+        }
+        else if (file.reviewed_line_ranges.length > 0) {
+            file.audit_status = "partial";
+        }
+    }
+}
+export function findUncoveredFiles(matrix) {
+    return matrix.files.filter((file) => {
+        if (file.audit_status === "excluded")
+            return false;
+        return file.audit_status !== "complete";
+    });
+}
+export function buildRequeueTargets(matrix) {
+    return matrix.files
+        .filter((file) => file.audit_status !== "excluded")
+        .map((file) => ({
+        path: file.path,
+        missing_lenses: file.required_lenses.filter((lens) => !file.completed_lenses.includes(lens)),
+    }))
+        .filter((item) => item.missing_lenses.length > 0);
+}

package/dist/extractors/bucketing.d.ts

@@ -0,0 +1,7 @@
+export type FileBucket = "runtime" | "interface" | "data_layer" | "security_sensitive" | "concurrency_state" | "tests" | "tooling_scripts" | "config_deployment" | "docs_specs" | "generated_vendor" | "unknown";
+export interface BucketAssignment {
+    path: string;
+    buckets: FileBucket[];
+    rationale: string[];
+}
+export declare function bucketFile(path: string): BucketAssignment;

package/dist/extractors/bucketing.js

@@ -0,0 +1,72 @@
+function addBucket(buckets, rationale, bucket, reason) {
+    if (!buckets.has(bucket)) {
+        buckets.add(bucket);
+        rationale.push(reason);
+    }
+}
+export function bucketFile(path) {
+    const normalized = path.toLowerCase();
+    const buckets = new Set();
+    const rationale = [];
+    if (normalized.includes("test") ||
+        normalized.includes("spec") ||
+        normalized.includes("__tests__")) {
+        addBucket(buckets, rationale, "tests", "path suggests tests");
+    }
+    if (normalized.includes("route") ||
+        normalized.includes("controller") ||
+        normalized.includes("handler") ||
+        normalized.includes("api/")) {
+        addBucket(buckets, rationale, "interface", "path suggests interface code");
+    }
+    if (normalized.includes("model") ||
+        normalized.includes("schema") ||
+        normalized.includes("migration") ||
+        normalized.includes("seed") ||
+        normalized.includes("db/")) {
+        addBucket(buckets, rationale, "data_layer", "path suggests data-layer code");
+    }
+    if (normalized.includes("auth") ||
+        normalized.includes("secret") ||
+        normalized.includes("token") ||
+        normalized.includes("permission") ||
+        normalized.includes("session")) {
+        addBucket(buckets, rationale, "security_sensitive", "path suggests security-sensitive code");
+    }
+    if (normalized.includes("queue") ||
+        normalized.includes("worker") ||
+        normalized.includes("job") ||
+        normalized.includes("cache") ||
+        normalized.includes("retry") ||
+        normalized.includes("lock")) {
+        addBucket(buckets, rationale, "concurrency_state", "path suggests concurrency or stateful behavior");
+    }
+    if (normalized.includes("script") ||
+        normalized.startsWith("scripts/") ||
+        normalized.startsWith("bin/")) {
+        addBucket(buckets, rationale, "tooling_scripts", "path suggests tooling or scripts");
+    }
+    if (normalized.includes("docker") ||
+        normalized.includes("terraform") ||
+        normalized.includes("deploy") ||
+        normalized.includes("workflow") ||
+        normalized.includes("k8s") ||
+        normalized.endsWith(".yml") ||
+        normalized.endsWith(".yaml")) {
+        addBucket(buckets, rationale, "config_deployment", "path suggests config or deployment artifact");
+    }
+    if (normalized.endsWith(".md") || normalized.startsWith("docs/")) {
+        addBucket(buckets, rationale, "docs_specs", "path suggests documentation");
+    }
+    if (normalized.includes("vendor") || normalized.includes("generated")) {
+        addBucket(buckets, rationale, "generated_vendor", "path suggests generated or vendored content");
+    }
+    if (buckets.size === 0) {
+        addBucket(buckets, rationale, "runtime", "default runtime classification");
+    }
+    return {
+        path,
+        buckets: [...buckets],
+        rationale,
+    };
+}

package/dist/extractors/disposition.d.ts

@@ -0,0 +1,4 @@
+import type { RepoManifest } from "../types.js";
+import type { FileDisposition, FileDispositionStatus } from "../types/disposition.js";
+export declare function buildFileDisposition(repoManifest: RepoManifest): FileDisposition;
+export declare function isAuditExcludedStatus(status: FileDispositionStatus): boolean;

package/dist/extractors/disposition.js

@@ -0,0 +1,41 @@
+function inferDisposition(path) {
+    const normalized = path.toLowerCase();
+    if (normalized.startsWith("dist/") || normalized.startsWith("build/")) {
+        return { path, status: "generated", reason: "Build output path." };
+    }
+    if (normalized.includes("vendor") || normalized.includes("third_party")) {
+        return { path, status: "vendor", reason: "Vendor or third-party path." };
+    }
+    if (normalized.endsWith(".png") ||
+        normalized.endsWith(".jpg") ||
+        normalized.endsWith(".jpeg") ||
+        normalized.endsWith(".gif") ||
+        normalized.endsWith(".pdf") ||
+        normalized.endsWith(".zip")) {
+        return {
+            path,
+            status: "binary",
+            reason: "Non-source binary-like artifact.",
+        };
+    }
+    if (normalized.endsWith(".md") || normalized.startsWith("docs/")) {
+        return { path, status: "doc_only", reason: "Documentation artifact." };
+    }
+    return {
+        path,
+        status: "included",
+        reason: "Default included source or config artifact.",
+    };
+}
+export function buildFileDisposition(repoManifest) {
+    return {
+        files: repoManifest.files.map((file) => inferDisposition(file.path)),
+    };
+}
+export function isAuditExcludedStatus(status) {
+    return (status === "excluded" ||
+        status === "generated" ||
+        status === "vendor" ||
+        status === "binary" ||
+        status === "doc_only");
+}

package/dist/extractors/fileInventory.d.ts

@@ -0,0 +1,7 @@
+import type { RepoManifest } from "../types.js";
+export interface InventoryInputFile {
+    path: string;
+    size_bytes: number;
+    hash?: string;
+}
+export declare function buildRepoManifest(repositoryName: string, files: InventoryInputFile[]): RepoManifest;

package/dist/extractors/fileInventory.js

@@ -0,0 +1,44 @@
+function inferLanguage(path) {
+    const ext = path.split(".").pop()?.toLowerCase();
+    switch (ext) {
+        case "ts":
+        case "tsx":
+            return "typescript";
+        case "js":
+        case "jsx":
+            return "javascript";
+        case "py":
+            return "python";
+        case "go":
+            return "go";
+        case "rs":
+            return "rust";
+        case "java":
+            return "java";
+        case "cs":
+            return "csharp";
+        case "json":
+            return "json";
+        case "yml":
+        case "yaml":
+            return "yaml";
+        case "md":
+            return "markdown";
+        default:
+            return "unknown";
+    }
+}
+export function buildRepoManifest(repositoryName, files) {
+    return {
+        repository: {
+            name: repositoryName,
+        },
+        generated_at: new Date().toISOString(),
+        files: files.map((file) => ({
+            path: file.path,
+            language: inferLanguage(file.path),
+            size_bytes: file.size_bytes,
+            hash: file.hash,
+        })),
+    };
+}

package/dist/extractors/flows.d.ts

@@ -0,0 +1,5 @@
+import type { RepoManifest } from "../types.js";
+import type { FileDisposition } from "../types/disposition.js";
+import type { CriticalFlowManifest } from "../types/flows.js";
+import type { SurfaceManifest } from "../types/surfaces.js";
+export declare function buildCriticalFlowManifest(repoManifest: RepoManifest, surfaceManifest: SurfaceManifest, disposition?: FileDisposition): CriticalFlowManifest;

package/dist/extractors/flows.js

@@ -0,0 +1,125 @@
+import { isAuditExcludedStatus } from "./disposition.js";
+function inferConcerns(paths) {
+    const concerns = new Set();
+    for (const path of paths) {
+        const normalized = path.toLowerCase();
+        if (normalized.includes("auth") ||
+            normalized.includes("token") ||
+            normalized.includes("session"))
+            concerns.add("security");
+        if (normalized.includes("db") ||
+            normalized.includes("model") ||
+            normalized.includes("schema") ||
+            normalized.includes("migration") ||
+            normalized.includes("invoice") ||
+            normalized.includes("payment"))
+            concerns.add("data_integrity");
+        if (normalized.includes("worker") ||
+            normalized.includes("job") ||
+            normalized.includes("retry") ||
+            normalized.includes("queue"))
+            concerns.add("reliability");
+        if (normalized.includes("api") ||
+            normalized.includes("route") ||
+            normalized.includes("controller"))
+            concerns.add("correctness");
+    }
+    return concerns.size > 0 ? [...concerns] : ["correctness"];
+}
+function relatedPaths(entry, availablePaths) {
+    const normalized = entry.toLowerCase();
+    const linked = new Set([entry]);
+    for (const path of availablePaths) {
+        const lower = path.toLowerCase();
+        if (path === entry)
+            continue;
+        if ((normalized.includes("auth") || normalized.includes("session")) &&
+            (lower.includes("auth") ||
+                lower.includes("session") ||
+                lower.includes("token") ||
+                lower.includes("user"))) {
+            linked.add(path);
+        }
+        if ((normalized.includes("billing") ||
+            normalized.includes("invoice") ||
+            normalized.includes("payment")) &&
+            (lower.includes("billing") ||
+                lower.includes("invoice") ||
+                lower.includes("payment") ||
+                lower.includes("ledger") ||
+                lower.includes("subscription"))) {
+            linked.add(path);
+        }
+        if ((normalized.includes("job") ||
+            normalized.includes("worker") ||
+            normalized.includes("queue")) &&
+            (lower.includes("queue") ||
+                lower.includes("retry") ||
+                lower.includes("worker") ||
+                lower.includes("job") ||
+                lower.includes("task"))) {
+            linked.add(path);
+        }
+        if ((normalized.includes("deploy") || normalized.includes("docker")) &&
+            (lower.includes("deploy") ||
+                lower.includes("docker") ||
+                lower.includes("workflow") ||
+                lower.includes("k8s") ||
+                lower.includes("terraform"))) {
+            linked.add(path);
+        }
+    }
+    return [...linked].sort((a, b) => a.localeCompare(b));
+}
+function dedupeFlows(flows) {
+    const seen = new Set();
+    const deduped = [];
+    for (const flow of flows) {
+        const signature = `${flow.name}|${flow.paths.join(",")}|${flow.concerns.join(",")}`;
+        if (seen.has(signature))
+            continue;
+        seen.add(signature);
+        deduped.push(flow);
+    }
+    return deduped;
+}
+export function buildCriticalFlowManifest(repoManifest, surfaceManifest, disposition) {
+    const dispositionMap = new Map(disposition?.files.map((item) => [item.path, item.status]) ?? []);
+    const availablePaths = repoManifest.files
+        .map((file) => file.path)
+        .filter((path) => {
+        const status = dispositionMap.get(path);
+        return !(status && isAuditExcludedStatus(status));
+    });
+    const flows = [];
+    for (const surface of surfaceManifest.surfaces) {
+        const entry = surface.entrypoint;
+        const paths = relatedPaths(entry, availablePaths);
+        flows.push({
+            id: `flow:${surface.id.replace(/[^a-zA-Z0-9:_-]/g, "-")}`,
+            name: `${surface.kind} flow for ${entry}`,
+            entrypoints: [entry],
+            paths,
+            concerns: inferConcerns(paths),
+            notes: [
+                "Heuristic critical-flow inference from detected surfaces and related paths.",
+            ],
+        });
+    }
+    for (const path of availablePaths) {
+        const lower = path.toLowerCase();
+        if (lower.includes("migration") ||
+            lower.includes("schema") ||
+            lower.includes("seed")) {
+            flows.push({
+                id: `flow:data:${path.replace(/[^a-zA-Z0-9:_-]/g, "-")}`,
+                name: `data evolution flow for ${path}`,
+                entrypoints: [path],
+                paths: relatedPaths(path, availablePaths),
+                concerns: ["data_integrity", "reliability"],
+                notes: ["Heuristic data-evolution flow."],
+            });
+        }
+    }
+    return { flows: dedupeFlows(flows) };
+}

package/dist/extractors/fsIntake.d.ts

@@ -0,0 +1,8 @@
+import type { RepoManifest } from "../types.js";
+export interface IntakeOptions {
+    root: string;
+    ignore?: string[];
+    hash_files?: boolean;
+    max_file_size_bytes?: number;
+}
+export declare function buildRepoManifestFromFs(options: IntakeOptions): Promise<RepoManifest>;

package/dist/extractors/fsIntake.js

@@ -0,0 +1,66 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { join, relative, resolve } from "node:path";
+import { buildRepoManifest } from "./fileInventory.js";
+const DEFAULT_IGNORES = [
+    ".git",
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+    ".turbo",
+    ".artifacts",
+    ".audit-artifacts",
+    ".agent",
+    ".claude",
+    "coverage",
+];
+function normalizePath(path) {
+    return path.replaceAll("\\", "/");
+}
+function shouldIgnore(relativePath, ignores) {
+    const normalized = normalizePath(relativePath);
+    return ignores.some((ignore) => {
+        const value = normalizePath(ignore);
+        return normalized === value || normalized.startsWith(`${value}/`);
+    });
+}
+async function maybeHashFile(path, enabled) {
+    if (!enabled)
+        return undefined;
+    const content = await readFile(path);
+    return createHash("sha256").update(content).digest("hex");
+}
+async function walk(root, current, ignores, hashFiles, maxFileSizeBytes, results) {
+    const entries = await readdir(current, { withFileTypes: true });
+    for (const entry of entries) {
+        const absolutePath = join(current, entry.name);
+        const relativePath = normalizePath(relative(root, absolutePath));
+        if (!relativePath || shouldIgnore(relativePath, ignores)) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            await walk(root, absolutePath, ignores, hashFiles, maxFileSizeBytes, results);
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        const info = await stat(absolutePath);
+        const hash = info.size <= maxFileSizeBytes
+            ? await maybeHashFile(absolutePath, hashFiles)
+            : undefined;
+        results.push({
+            path: relativePath,
+            size_bytes: info.size,
+            hash,
+        });
+    }
+}
+export async function buildRepoManifestFromFs(options) {
+    const root = resolve(options.root);
+    const ignore = [...DEFAULT_IGNORES, ...(options.ignore ?? [])];
+    const files = [];
+    await walk(root, root, ignore, options.hash_files ?? false, options.max_file_size_bytes ?? 1024 * 1024, files);
+    return buildRepoManifest(root.split(/[\\/]/).pop() ?? "repo", files);
+}

package/dist/extractors/graph.d.ts

@@ -0,0 +1,4 @@
+import type { RepoManifest } from "../types.js";
+import type { FileDisposition } from "../types/disposition.js";
+import type { GraphBundle } from "../types/graph.js";
+export declare function buildGraphBundle(repoManifest: RepoManifest, disposition?: FileDisposition): GraphBundle;

package/dist/extractors/graph.js

@@ -0,0 +1,46 @@
+import { isAuditExcludedStatus } from "./disposition.js";
+export function buildGraphBundle(repoManifest, disposition) {
+    const imports = [];
+    const routes = [];
+    const dispositionMap = new Map(disposition?.files.map((item) => [item.path, item.status]) ?? []);
+    for (const file of repoManifest.files) {
+        const status = dispositionMap.get(file.path);
+        if (status && isAuditExcludedStatus(status)) {
+            continue;
+        }
+        const normalized = file.path.toLowerCase();
+        if (normalized.includes("api/") || normalized.includes("route")) {
+            routes.push({
+                path: `/${file.path.replaceAll("/", "_")}`,
+                handler: file.path,
+                method: "GET",
+            });
+        }
+        const parts = file.path.split("/");
+        if (parts.length > 2) {
+            imports.push({
+                from: file.path,
+                to: `${parts[0]}/${parts[1]}`,
+                kind: "heuristic-container-edge",
+            });
+        }
+        if (normalized.includes("auth") &&
+            normalized.includes("session") === false) {
+            for (const other of repoManifest.files) {
+                if (other.path === file.path)
+                    continue;
+                const otherStatus = dispositionMap.get(other.path);
+                if (otherStatus && isAuditExcludedStatus(otherStatus))
+                    continue;
+                if (other.path.toLowerCase().includes("session")) {
+                    imports.push({
+                        from: file.path,
+                        to: other.path,
+                        kind: "heuristic-auth-session-link",
+                    });
+                }
+            }
+        }
+    }
+    return { graphs: { imports, routes } };
+}

package/dist/extractors/ignore.d.ts

@@ -0,0 +1 @@
+export declare function loadIgnoreFile(root: string, fileName?: string): Promise<string[]>;

package/dist/extractors/ignore.js

@@ -0,0 +1,17 @@
+import { access, readFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { join } from "node:path";
+export async function loadIgnoreFile(root, fileName = ".auditorignore") {
+    const path = join(root, fileName);
+    try {
+        await access(path, constants.F_OK);
+    }
+    catch {
+        return [];
+    }
+    const content = await readFile(path, "utf8");
+    return content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith("#"));
+}

package/dist/extractors/risk.d.ts

@@ -0,0 +1,5 @@
+import type { UnitManifest } from "../types.js";
+import type { ExternalAnalyzerResults } from "../types/externalAnalyzer.js";
+import type { CriticalFlowManifest } from "../types/flows.js";
+import type { RiskRegister } from "../types/risk.js";
+export declare function buildRiskRegister(unitManifest: UnitManifest, criticalFlows?: CriticalFlowManifest, externalAnalyzerResults?: ExternalAnalyzerResults): RiskRegister;

package/dist/extractors/risk.js

@@ -0,0 +1,45 @@
+export function buildRiskRegister(unitManifest, criticalFlows, externalAnalyzerResults) {
+    const flowMap = new Map();
+    for (const flow of criticalFlows?.flows ?? []) {
+        for (const path of flow.paths) {
+            flowMap.set(path, (flowMap.get(path) ?? 0) + 1);
+        }
+    }
+    const externalByPath = new Map();
+    for (const item of externalAnalyzerResults?.results ?? []) {
+        externalByPath.set(item.path, (externalByPath.get(item.path) ?? 0) + 1);
+    }
+    const items = unitManifest.units.map((unit) => {
+        const signals = [];
+        if ((unit.risk_score ?? 0) >= 5)
+            signals.push("high_bucket_density");
+        if (unit.required_lenses.includes("security"))
+            signals.push("security_relevant");
+        if (unit.required_lenses.includes("data_integrity"))
+            signals.push("writes_or_persistence");
+        if (unit.required_lenses.includes("config_deployment"))
+            signals.push("operational_surface");
+        const flowHits = unit.files.reduce((sum, path) => sum + (flowMap.get(path) ?? 0), 0);
+        if (flowHits > 0) {
+            signals.push("critical_flow_member");
+        }
+        const externalHits = unit.files.reduce((sum, path) => sum + (externalByPath.get(path) ?? 0), 0);
+        if (externalHits > 0) {
+            signals.push("external_analyzer_signal");
+        }
+        return {
+            unit_id: unit.unit_id,
+            risk_score: (unit.risk_score ?? 0) + flowHits + externalHits,
+            signals,
+            notes: [
+                "Initial heuristic risk scoring.",
+                ...(externalHits > 0
+                    ? [
+                        `External analyzer signals affecting ${externalHits} path match(es).`,
+                    ]
+                    : []),
+            ],
+        };
+    });
+    return { items };
+}

package/dist/extractors/surfaces.d.ts

@@ -0,0 +1,4 @@
+import type { RepoManifest } from "../types.js";
+import type { FileDisposition } from "../types/disposition.js";
+import type { SurfaceManifest } from "../types/surfaces.js";
+export declare function buildSurfaceManifest(repoManifest: RepoManifest, disposition?: FileDisposition): SurfaceManifest;