auditor-lambda 0.3.17 → 0.3.19

package/README.md

@@ -149,6 +149,18 @@ For task-to-coverage inspection without reverse-engineering multiple artifacts:
 audit-code explain-task <task_id>
 ```
 
+To remove a leftover `.audit-artifacts/` directory from an interrupted or
+crashed audit:
+
+```bash
+audit-code cleanup
+audit-code cleanup --dry-run   # preview without deleting
+audit-code cleanup --force     # delete even if state is unknown
+```
+
+Refuses to delete if the audit state is `active` or `blocked` (resumable).
+Pass `--force` when `audit_state.json` is missing (crashed run).
+
 For a local stdio MCP server entrypoint:
 
 ```bash

package/dist/cli.js

@@ -1,4 +1,4 @@
-import { access, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { createReadStream } from "node:fs";
 import { Buffer } from "node:buffer";
 import { createHash } from "node:crypto";
@@ -308,30 +308,6 @@ async function listBatchResultFiles(batchDir) {
     }
     return files;
 }
-const PROJECT_SIGNALS = [
-    "package.json",
-    "go.mod",
-    "Cargo.toml",
-    "pom.xml",
-    "build.gradle",
-    "pyproject.toml",
-    "setup.py",
-    "setup.cfg",
-    "Makefile",
-    "CMakeLists.txt",
-];
-async function detectProjectRoot(root) {
-    for (const signal of PROJECT_SIGNALS) {
-        try {
-            await access(join(root, signal));
-            return signal;
-        }
-        catch {
-            // not found, try next
-        }
-    }
-    return null;
-}
 function buildPendingAuditTasks(bundle) {
     const completedTaskIds = new Set((bundle.audit_results ?? []).map((result) => result.task_id));
     const pendingTasks = (bundle.audit_tasks ?? []).filter((task) => task.status !== "complete" && !completedTaskIds.has(task.task_id));
@@ -606,6 +582,7 @@ export async function runSample(argv = process.argv) {
 async function cmdAdvanceAudit(argv) {
     const root = getRootDir(argv);
     const artifactsDir = getArtifactsDir(argv);
+    await cleanupStaleArtifactsDir(artifactsDir);
     await mkdir(artifactsDir, { recursive: true });
     await ensureSupervisorDirs(artifactsDir);
     let sessionConfig;
@@ -685,6 +662,7 @@ async function cmdAdvanceAudit(argv) {
 async function cmdRunToCompletion(argv) {
     const root = getRootDir(argv);
     const artifactsDir = getArtifactsDir(argv);
+    await cleanupStaleArtifactsDir(artifactsDir);
     await mkdir(artifactsDir, { recursive: true });
     await ensureSupervisorDirs(artifactsDir);
     let sessionConfig;
@@ -714,35 +692,6 @@ async function cmdRunToCompletion(argv) {
     let pendingBatchAuditResults = batchResultsDir
         ? await listBatchResultFiles(batchResultsDir)
         : [];
-    const earlyBundle = await loadArtifactBundle(artifactsDir);
-    if (!earlyBundle.unit_manifest) {
-        const foundSignal = await detectProjectRoot(root);
-        if (!foundSignal) {
-            const blocker = `No recognisable project signals found in ${root}. Expected one of: ${PROJECT_SIGNALS.join(", ")}. Check that --root points to the repository root, not a subdirectory or an unrelated path.`;
-            const earlyState = deriveAuditState(earlyBundle);
-            const blockedState = buildBlockedAuditState({
-                state: earlyState,
-                obligationId: null,
-                executor: null,
-                blocker,
-            });
-            await emitEnvelope({
-                root,
-                artifactsDir,
-                bundle: { ...earlyBundle, audit_state: blockedState },
-                audit_state: blockedState,
-                selected_obligation: null,
-                selected_executor: null,
-                progress_made: false,
-                artifacts_written: [],
-                progress_summary: blocker,
-                next_likely_step: null,
-                providerName: provider.name,
-                isConfigError: true,
-            });
-            return;
-        }
-    }
     let pendingAuditResultsPath = getFlag(argv, "--results");
     let pendingRuntimeUpdatesPath = getFlag(argv, "--updates");
     let pendingExternalAnalyzerPath = getFlag(argv, "--external-analyzer-results");
@@ -2353,6 +2302,61 @@ async function cmdSynthesize(argv) {
         progress_summary: result.progress_summary,
     }, null, 2));
 }
+async function cleanupStaleArtifactsDir(artifactsDir) {
+    let status;
+    try {
+        const state = await readJsonFile(join(artifactsDir, "audit_state.json"));
+        status = state.status;
+    }
+    catch (error) {
+        if (!isFileMissingError(error)) {
+            throw error;
+        }
+        return;
+    }
+    if (status === "complete" || status === "not_started") {
+        await rm(artifactsDir, { recursive: true, force: true });
+    }
+}
+async function cmdCleanup(argv) {
+    const artifactsDir = getArtifactsDir(argv);
+    const dryRun = hasFlag(argv, "--dry-run");
+    const force = hasFlag(argv, "--force");
+    let status;
+    try {
+        const state = await readJsonFile(join(artifactsDir, "audit_state.json"));
+        status = state.status;
+    }
+    catch (error) {
+        if (!isFileMissingError(error)) {
+            throw error;
+        }
+    }
+    const resumable = status === "active" || status === "blocked";
+    const unknown = status === undefined;
+    if ((resumable || unknown) && !force) {
+        const reason = resumable
+            ? `audit is ${status} and may be resumed`
+            : "no audit_state.json found; artifacts may be from a crashed audit";
+        console.log(JSON.stringify({
+            artifacts_dir: artifactsDir,
+            action: "skipped",
+            reason: `${reason} — use --force to delete anyway`,
+            dry_run: dryRun,
+        }, null, 2));
+        process.exitCode = 1;
+        return;
+    }
+    if (!dryRun) {
+        await rm(artifactsDir, { recursive: true, force: true });
+    }
+    console.log(JSON.stringify({
+        artifacts_dir: artifactsDir,
+        action: dryRun ? "dry-run" : "deleted",
+        status: status ?? "unknown",
+        dry_run: dryRun,
+    }, null, 2));
+}
 async function cmdMcp(argv) {
     await runAuditCodeMcpServer(argv.slice(3));
 }
@@ -2401,6 +2405,9 @@ async function main(argv) {
         case "synthesize":
             await cmdSynthesize(argv);
             return;
+        case "cleanup":
+            await cmdCleanup(argv);
+            return;
         case "mcp":
             await cmdMcp(argv);
             return;
@@ -2418,7 +2425,7 @@ async function main(argv) {
             return;
         default:
             console.error(`Unknown command: ${command}`);
-            console.error("Available commands: sample-run, advance-audit, run-to-completion, worker-run, import-external-analyzer, intake, plan, ingest-results, explain-task, update-runtime-validation, validate, validate-results, requeue, synthesize, mcp, prepare-dispatch, merge-and-ingest, submit-packet, validate-result");
+            console.error("Available commands: sample-run, advance-audit, run-to-completion, worker-run, import-external-analyzer, intake, plan, ingest-results, explain-task, update-runtime-validation, validate, validate-results, requeue, synthesize, cleanup, mcp, prepare-dispatch, merge-and-ingest, submit-packet, validate-result");
             process.exitCode = 1;
     }
 }

package/dist/extractors/browserExtension.d.ts

@@ -0,0 +1,13 @@
+import type { Lens, RepoManifest } from "../types.js";
+import type { FileDisposition } from "../types/disposition.js";
+import type { GraphBundle, GraphEdge } from "../types/graph.js";
+import type { SurfaceRecord } from "../types/surfaces.js";
+export declare const BROWSER_EXTENSION_HEURISTIC_NOTE = "Chrome extension manifest and HTML asset references were resolved deterministically from local paths; verify unusual dynamic registration manually.";
+export declare function isBrowserExtensionManifestPath(path: string): boolean;
+export declare function extractChromeExtensionManifestEdges(fromPath: string, content: string, pathLookup: Map<string, string>): GraphEdge[];
+export declare function extractHtmlResourceEdges(fromPath: string, content: string, pathLookup: Map<string, string>): GraphEdge[];
+export declare function hasBrowserExtensionManifestFile(repoManifest: RepoManifest): boolean;
+export declare function deriveBrowserExtensionLensesForPath(path: string): Lens[];
+export declare function inferBrowserExtensionUnitKind(path: string): string | undefined;
+export declare function buildBrowserExtensionSurfacesFromGraph(graphBundle: GraphBundle | undefined, disposition?: FileDisposition): SurfaceRecord[];
+export declare function chromeExtensionRiskSignalsForManifest(content: string): string[];

package/dist/extractors/browserExtension.js

@@ -0,0 +1,378 @@
+import { posix } from "node:path";
+import { isAuditExcludedStatus } from "./disposition.js";
+import { graphEdge, normalizeGraphPath, resolveCandidate, } from "./graphPathUtils.js";
+export const BROWSER_EXTENSION_HEURISTIC_NOTE = "Chrome extension manifest and HTML asset references were resolved deterministically from local paths; verify unusual dynamic registration manually.";
+const CHROME_EXTENSION_BACKGROUND_EDGE = "chrome-extension-background-link";
+const CHROME_EXTENSION_CONTENT_SCRIPT_EDGE = "chrome-extension-content-script-link";
+const CHROME_EXTENSION_CONTENT_STYLE_EDGE = "chrome-extension-content-style-link";
+const CHROME_EXTENSION_UI_PAGE_EDGE = "chrome-extension-ui-page-link";
+const CHROME_EXTENSION_WEB_ACCESSIBLE_EDGE = "chrome-extension-web-accessible-resource-link";
+const HTML_RESOURCE_EDGE = "html-resource-link";
+const CHROME_EXTENSION_EDGE_CONFIDENCE = 0.94;
+const HTML_RESOURCE_EDGE_CONFIDENCE = 0.86;
+const EXTENSION_SURFACE_EDGE_KINDS = new Set([
+    CHROME_EXTENSION_BACKGROUND_EDGE,
+    CHROME_EXTENSION_CONTENT_SCRIPT_EDGE,
+    CHROME_EXTENSION_UI_PAGE_EDGE,
+]);
+const HIGH_RISK_PERMISSION_TOKENS = [
+    "<all_urls>",
+    "activeTab",
+    "debugger",
+    "declarativeNetRequest",
+    "downloads",
+    "downloads.open",
+    "nativeMessaging",
+    "proxy",
+    "scripting",
+    "tabs",
+    "unlimitedStorage",
+    "webNavigation",
+    "webRequest",
+];
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function asString(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : undefined;
+}
+function asStringArray(value) {
+    return Array.isArray(value)
+        ? value
+            .map((item) => asString(item))
+            .filter((item) => item !== undefined)
+        : [];
+}
+function parseJsonObject(content) {
+    try {
+        const parsed = JSON.parse(content);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isBrowserExtensionManifestPath(path) {
+    return posix.basename(normalizeGraphPath(path)).toLowerCase() === "manifest.json";
+}
+function isBrowserExtensionManifest(value) {
+    return (typeof value.manifest_version === "number" &&
+        (isRecord(value.background) ||
+            Array.isArray(value.content_scripts) ||
+            isRecord(value.action) ||
+            isRecord(value.browser_action) ||
+            isRecord(value.page_action) ||
+            isRecord(value.side_panel) ||
+            isRecord(value.options_ui) ||
+            typeof value.options_page === "string" ||
+            typeof value.devtools_page === "string" ||
+            isRecord(value.chrome_url_overrides) ||
+            Array.isArray(value.web_accessible_resources)));
+}
+function localPathCandidate(specifier) {
+    const withoutQuery = specifier.trim().split(/[?#]/, 1)[0]?.trim() ?? "";
+    if (withoutQuery.length === 0 ||
+        withoutQuery.startsWith("<") ||
+        withoutQuery.includes("*") ||
+        /^[a-z][a-z0-9+.-]*:/i.test(withoutQuery) ||
+        withoutQuery.startsWith("//")) {
+        return undefined;
+    }
+    return normalizeGraphPath(withoutQuery).replace(/^\/+/, "");
+}
+function resolveLocalReference(fromPath, specifier, pathLookup) {
+    const local = localPathCandidate(specifier);
+    if (!local) {
+        return undefined;
+    }
+    const isRootRelative = specifier.trim().startsWith("/");
+    const baseDir = posix.dirname(normalizeGraphPath(fromPath));
+    const candidate = isRootRelative || baseDir === "." ? local : posix.join(baseDir, local);
+    return resolveCandidate(candidate, pathLookup);
+}
+function addManifestReference(edges, params) {
+    const target = resolveLocalReference(params.fromPath, params.specifier, params.pathLookup);
+    if (!target) {
+        return;
+    }
+    edges.push(graphEdge({
+        from: params.fromPath,
+        to: target,
+        kind: params.kind,
+        confidence: CHROME_EXTENSION_EDGE_CONFIDENCE,
+        reason: `Chrome extension manifest field '${params.field}' references '${params.specifier}'.`,
+    }));
+}
+function collectExtensionUiPageReferences(manifest) {
+    const entries = [];
+    for (const objectField of ["action", "browser_action", "page_action"]) {
+        const value = manifest[objectField];
+        if (isRecord(value)) {
+            const popup = asString(value.default_popup);
+            if (popup)
+                entries.push({ field: `${objectField}.default_popup`, specifier: popup });
+        }
+    }
+    const sidePanel = manifest.side_panel;
+    if (isRecord(sidePanel)) {
+        const path = asString(sidePanel.default_path);
+        if (path)
+            entries.push({ field: "side_panel.default_path", specifier: path });
+    }
+    const optionsPage = asString(manifest.options_page);
+    if (optionsPage)
+        entries.push({ field: "options_page", specifier: optionsPage });
+    const optionsUi = manifest.options_ui;
+    if (isRecord(optionsUi)) {
+        const page = asString(optionsUi.page);
+        if (page)
+            entries.push({ field: "options_ui.page", specifier: page });
+    }
+    const devtoolsPage = asString(manifest.devtools_page);
+    if (devtoolsPage)
+        entries.push({ field: "devtools_page", specifier: devtoolsPage });
+    const overrides = manifest.chrome_url_overrides;
+    if (isRecord(overrides)) {
+        for (const [key, value] of Object.entries(overrides)) {
+            const page = asString(value);
+            if (page)
+                entries.push({ field: `chrome_url_overrides.${key}`, specifier: page });
+        }
+    }
+    const sandbox = manifest.sandbox;
+    if (isRecord(sandbox)) {
+        asStringArray(sandbox.pages).forEach((page, index) => entries.push({ field: `sandbox.pages.${index}`, specifier: page }));
+    }
+    return entries;
+}
+function collectWebAccessibleReferences(manifest) {
+    const entries = [];
+    const resources = manifest.web_accessible_resources;
+    if (!Array.isArray(resources)) {
+        return entries;
+    }
+    resources.forEach((item, index) => {
+        if (typeof item === "string") {
+            entries.push({
+                field: `web_accessible_resources.${index}`,
+                specifier: item,
+            });
+            return;
+        }
+        if (!isRecord(item)) {
+            return;
+        }
+        asStringArray(item.resources).forEach((resource, resourceIndex) => entries.push({
+            field: `web_accessible_resources.${index}.resources.${resourceIndex}`,
+            specifier: resource,
+        }));
+    });
+    return entries;
+}
+export function extractChromeExtensionManifestEdges(fromPath, content, pathLookup) {
+    if (!isBrowserExtensionManifestPath(fromPath)) {
+        return [];
+    }
+    const manifest = parseJsonObject(content);
+    if (!manifest || !isBrowserExtensionManifest(manifest)) {
+        return [];
+    }
+    const edges = [];
+    const background = manifest.background;
+    if (isRecord(background)) {
+        const serviceWorker = asString(background.service_worker);
+        if (serviceWorker) {
+            addManifestReference(edges, {
+                fromPath,
+                field: "background.service_worker",
+                kind: CHROME_EXTENSION_BACKGROUND_EDGE,
+                specifier: serviceWorker,
+                pathLookup,
+            });
+        }
+        asStringArray(background.scripts).forEach((script, index) => addManifestReference(edges, {
+            fromPath,
+            field: `background.scripts.${index}`,
+            kind: CHROME_EXTENSION_BACKGROUND_EDGE,
+            specifier: script,
+            pathLookup,
+        }));
+    }
+    const contentScripts = manifest.content_scripts;
+    if (Array.isArray(contentScripts)) {
+        contentScripts.forEach((item, index) => {
+            if (!isRecord(item)) {
+                return;
+            }
+            asStringArray(item.js).forEach((script, scriptIndex) => addManifestReference(edges, {
+                fromPath,
+                field: `content_scripts.${index}.js.${scriptIndex}`,
+                kind: CHROME_EXTENSION_CONTENT_SCRIPT_EDGE,
+                specifier: script,
+                pathLookup,
+            }));
+            asStringArray(item.css).forEach((style, styleIndex) => addManifestReference(edges, {
+                fromPath,
+                field: `content_scripts.${index}.css.${styleIndex}`,
+                kind: CHROME_EXTENSION_CONTENT_STYLE_EDGE,
+                specifier: style,
+                pathLookup,
+            }));
+        });
+    }
+    for (const { field, specifier } of collectExtensionUiPageReferences(manifest)) {
+        addManifestReference(edges, {
+            fromPath,
+            field,
+            kind: CHROME_EXTENSION_UI_PAGE_EDGE,
+            specifier,
+            pathLookup,
+        });
+    }
+    for (const { field, specifier } of collectWebAccessibleReferences(manifest)) {
+        addManifestReference(edges, {
+            fromPath,
+            field,
+            kind: CHROME_EXTENSION_WEB_ACCESSIBLE_EDGE,
+            specifier,
+            pathLookup,
+        });
+    }
+    return edges;
+}
+function extractHtmlAttributeReferences(content, elementName, attributeName) {
+    const unquotedAttributeValue = "[^\\s\"'<>`]+";
+    const pattern = new RegExp(`<${elementName}\\b[^>]*\\b${attributeName}\\s*=\\s*(?:"([^"]+)"|'([^']+)'|(${unquotedAttributeValue}))`, "gi");
+    const values = [];
+    for (const match of content.matchAll(pattern)) {
+        const value = match[1] ?? match[2] ?? match[3];
+        if (value)
+            values.push(value);
+    }
+    return values;
+}
+export function extractHtmlResourceEdges(fromPath, content, pathLookup) {
+    const normalized = normalizeGraphPath(fromPath).toLowerCase();
+    if (!normalized.endsWith(".html") && !normalized.endsWith(".htm")) {
+        return [];
+    }
+    const references = [
+        ...extractHtmlAttributeReferences(content, "script", "src"),
+        ...extractHtmlAttributeReferences(content, "link", "href"),
+    ];
+    const edges = [];
+    for (const specifier of references) {
+        const target = resolveLocalReference(fromPath, specifier, pathLookup);
+        if (!target) {
+            continue;
+        }
+        edges.push(graphEdge({
+            from: fromPath,
+            to: target,
+            kind: HTML_RESOURCE_EDGE,
+            confidence: HTML_RESOURCE_EDGE_CONFIDENCE,
+            reason: `HTML resource attribute references '${specifier}'.`,
+        }));
+    }
+    return edges;
+}
+export function hasBrowserExtensionManifestFile(repoManifest) {
+    return repoManifest.files.some((file) => normalizeGraphPath(file.path).toLowerCase() === "manifest.json");
+}
+export function deriveBrowserExtensionLensesForPath(path) {
+    const normalized = normalizeGraphPath(path).toLowerCase();
+    if (normalized === "manifest.json") {
+        return ["security", "correctness", "config_deployment", "operability"];
+    }
+    if (normalized.startsWith("service/") ||
+        normalized.startsWith("background/") ||
+        normalized.includes("service-worker") ||
+        normalized.includes("background")) {
+        return ["security", "correctness", "reliability", "observability"];
+    }
+    if (normalized.startsWith("content/") || normalized.includes("content-script")) {
+        return ["security", "correctness", "reliability"];
+    }
+    if (normalized.includes("popup") ||
+        normalized.includes("sidebar") ||
+        normalized.includes("side-panel") ||
+        normalized.includes("panel") ||
+        normalized.endsWith(".html")) {
+        return ["security", "correctness", "maintainability"];
+    }
+    if (normalized.includes("worker")) {
+        return ["correctness", "reliability", "performance"];
+    }
+    return [];
+}
+export function inferBrowserExtensionUnitKind(path) {
+    const normalized = normalizeGraphPath(path).toLowerCase();
+    if (normalized === "manifest.json")
+        return "extension_config";
+    if (normalized.startsWith("service/") || normalized.startsWith("background/")) {
+        return "extension_background";
+    }
+    if (normalized.startsWith("content/"))
+        return "extension_content";
+    if (normalized.includes("worker"))
+        return "worker";
+    if (normalized.endsWith(".html"))
+        return "extension_ui";
+    return undefined;
+}
+function isExecutableExtensionSurfaceTarget(path) {
+    const normalized = normalizeGraphPath(path).toLowerCase();
+    return (normalized.endsWith(".js") ||
+        normalized.endsWith(".mjs") ||
+        normalized.endsWith(".cjs") ||
+        normalized.endsWith(".html") ||
+        normalized.endsWith(".htm"));
+}
+export function buildBrowserExtensionSurfacesFromGraph(graphBundle, disposition) {
+    const references = Array.isArray(graphBundle?.graphs.references)
+        ? graphBundle.graphs.references
+        : [];
+    const dispositionMap = new Map(disposition?.files.map((item) => [item.path, item.status]) ?? []);
+    const surfaces = [];
+    const seen = new Set();
+    for (const edge of references) {
+        if (!edge.kind || !EXTENSION_SURFACE_EDGE_KINDS.has(edge.kind)) {
+            continue;
+        }
+        if (!isExecutableExtensionSurfaceTarget(edge.to)) {
+            continue;
+        }
+        const status = dispositionMap.get(edge.to);
+        if (status && isAuditExcludedStatus(status)) {
+            continue;
+        }
+        const kind = edge.kind === CHROME_EXTENSION_BACKGROUND_EDGE ? "background" : "interface";
+        const key = `${kind}:${edge.to}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        surfaces.push({
+            id: `surface:${edge.to}`,
+            kind,
+            entrypoint: edge.to,
+            exposure: edge.kind === CHROME_EXTENSION_CONTENT_SCRIPT_EDGE ? "network" : "local",
+            notes: [BROWSER_EXTENSION_HEURISTIC_NOTE],
+        });
+    }
+    return surfaces.sort((a, b) => a.entrypoint.localeCompare(b.entrypoint) || a.kind.localeCompare(b.kind));
+}
+export function chromeExtensionRiskSignalsForManifest(content) {
+    const manifest = parseJsonObject(content);
+    if (!manifest || !isBrowserExtensionManifest(manifest)) {
+        return [];
+    }
+    const permissions = [
+        ...asStringArray(manifest.permissions),
+        ...asStringArray(manifest.optional_permissions),
+        ...asStringArray(manifest.host_permissions),
+    ];
+    return HIGH_RISK_PERMISSION_TOKENS.filter((token) => permissions.some((permission) => permission === token));
+}

package/dist/extractors/disposition.js

@@ -1,4 +1,4 @@
-import { isNodeModulesOrGit, isBuildOutput, isVendorPath, isBinaryArtifact, isLicensePath, isLockfilePath, isLogPath, isDocPath, isAuditArtifactPath, isGeneratedTestArtifactPath, isGeneratedInstallArtifactPath, isExamplesOrFixturesPath, normalizeExtractorPath, } from "./pathPatterns.js";
+import { isNodeModulesOrGit, isBuildOutput, isVendorPath, isBinaryArtifact, isLicensePath, isLockfilePath, isLogPath, isDocPath, isGeneratedPath, isAuditArtifactPath, isGeneratedTestArtifactPath, isGeneratedInstallArtifactPath, isExamplesOrFixturesPath, normalizeExtractorPath, } from "./pathPatterns.js";
 function inferDisposition(path) {
     const normalized = normalizeExtractorPath(path);
     if (isNodeModulesOrGit(normalized)) {
@@ -33,6 +33,13 @@ function inferDisposition(path) {
             reason: "Generated audit artifact.",
         };
     }
+    if (isGeneratedPath(normalized)) {
+        return {
+            path,
+            status: "generated",
+            reason: "Generated artifact path.",
+        };
+    }
     if (isGeneratedTestArtifactPath(normalized)) {
         return {
             path,

package/dist/extractors/fsIntake.js

@@ -11,6 +11,7 @@ const DEFAULT_IGNORES = [
     ".turbo",
     ".artifacts",
     ".audit-artifacts",
+    ".audit-code/install",
     ".agent",
     ".claude",
     "coverage",

package/dist/extractors/graph.js

@@ -2,6 +2,7 @@ import { readFile } from "node:fs/promises";
 import { isAbsolute, relative, resolve } from "node:path";
 import { posix } from "node:path";
 import { isAuditExcludedStatus } from "./disposition.js";
+import { extractChromeExtensionManifestEdges, extractHtmlResourceEdges, } from "./browserExtension.js";
 import { extractCargoWorkspaceMemberEdges, extractGoWorkspaceModuleEdges, extractMavenModuleEdges, extractPackageEntrypointEdges, extractPackageScriptEdges, extractPyprojectTestpathLinks, extractTypescriptProjectReferenceEdges, extractWorkspacePackageEdges, extractYamlPathReferenceEdges, isCargoManifestPath, isGoWorkspaceManifestPath, isMavenPomPath, isPyprojectPath, } from "./graphManifestEdges.js";
 import { graphEdge, graphLookupKey, normalizeGraphPath, resolveCandidate, } from "./graphPathUtils.js";
 import { isTestPath, normalizeExtractorPath } from "./pathPatterns.js";
@@ -10,6 +11,7 @@ const SOURCE_LANGUAGES = new Set([
     "typescript",
     "javascript",
     "json",
+    "html",
     "yaml",
     "python",
     "go",
@@ -27,6 +29,8 @@ const SOURCE_EXTENSIONS = [
     ".mjs",
     ".cjs",
     ".json",
+    ".html",
+    ".htm",
     ".yml",
     ".yaml",
     ".py",
@@ -1309,6 +1313,8 @@ export function buildGraphBundle(repoManifest, disposition, options = {}) {
             references.push(...extractReferenceEdges(file.path, content, pathLookup));
             references.push(...extractJsonSchemaReferenceEdges(file.path, content, pathLookup));
             references.push(...extractPackageEntrypointEdges(file.path, content, pathLookup));
+            references.push(...extractChromeExtensionManifestEdges(file.path, content, pathLookup));
+            references.push(...extractHtmlResourceEdges(file.path, content, pathLookup));
             references.push(...extractPackageScriptEdges(file.path, content, pathLookup));
             references.push(...extractWorkspacePackageEdges(file.path, content, pathLookup));
             references.push(...extractTypescriptProjectReferenceEdges(file.path, content, pathLookup));

package/dist/extractors/pathPatterns.js

@@ -10,6 +10,16 @@ const BINARY_EXTENSIONS = [
     ".jpg",
     ".jpeg",
     ".gif",
+    ".webp",
+    ".svg",
+    ".ico",
+    ".bmp",
+    ".avif",
+    ".wasm",
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".otf",
     ".pdf",
     ".zip",
 ];
@@ -216,7 +226,11 @@ export function isDeploymentConfigPath(normalized) {
     return hasToken(normalized, DEPLOYMENT_KEYWORDS) || endsWithAny(normalized, [".yml", ".yaml"]);
 }
 export function isGeneratedPath(normalized) {
-    return isVendorPath(normalized) || hasToken(normalized, ["generated", "autogenerated"]);
+    return (isVendorPath(normalized) ||
+        normalized.endsWith(".map") ||
+        normalized.endsWith(".wasm.mjs") ||
+        normalized.endsWith(".wasm.js") ||
+        hasToken(normalized, ["generated", "autogenerated"]));
 }
 export function isSurfacePath(normalized) {
     return (hasSegment(normalized, "api") ||

package/dist/extractors/surfaces.d.ts

@@ -1,8 +1,11 @@
 import type { RepoManifest } from "../types.js";
 import type { FileDisposition } from "../types/disposition.js";
+import type { GraphBundle } from "../types/graph.js";
 import type { SurfaceManifest } from "../types/surfaces.js";
 /**
  * Detects likely execution surfaces from file paths using the shared extractor
  * heuristics, primarily to seed later audit planning.
  */
-export declare function buildSurfaceManifest(repoManifest: RepoManifest, disposition?: FileDisposition): SurfaceManifest;
+export declare function buildSurfaceManifest(repoManifest: RepoManifest, disposition?: FileDisposition, options?: {
+    graphBundle?: GraphBundle;
+}): SurfaceManifest;

package/dist/extractors/surfaces.js

@@ -1,3 +1,4 @@
+import { buildBrowserExtensionSurfacesFromGraph } from "./browserExtension.js";
 import { isAuditExcludedStatus } from "./disposition.js";
 import { EXTRACTOR_HEURISTIC_NOTE, isBackgroundSurfacePath, isNetworkSurfacePath, isSurfacePath, normalizeExtractorPath, } from "./pathPatterns.js";
 function methodsForPath(path) {
@@ -11,9 +12,18 @@ function methodsForPath(path) {
  * Detects likely execution surfaces from file paths using the shared extractor
  * heuristics, primarily to seed later audit planning.
  */
-export function buildSurfaceManifest(repoManifest, disposition) {
+export function buildSurfaceManifest(repoManifest, disposition, options = {}) {
     const surfaces = [];
+    const seen = new Set();
     const dispositionMap = new Map(disposition?.files.map((item) => [item.path, item.status]) ?? []);
+    function addSurface(surface) {
+        const key = `${surface.kind}:${surface.entrypoint}`;
+        if (seen.has(key)) {
+            return;
+        }
+        seen.add(key);
+        surfaces.push(surface);
+    }
     for (const file of repoManifest.files) {
         const status = dispositionMap.get(file.path);
         if (status && isAuditExcludedStatus(status)) {
@@ -21,7 +31,7 @@ export function buildSurfaceManifest(repoManifest, disposition) {
         }
         const normalized = normalizeExtractorPath(file.path);
         if (isSurfacePath(normalized)) {
-            surfaces.push({
+            addSurface({
                 id: `surface:${file.path}`,
                 kind: isBackgroundSurfacePath(normalized) ? "background" : "interface",
                 entrypoint: file.path,
@@ -31,5 +41,8 @@ export function buildSurfaceManifest(repoManifest, disposition) {
             });
         }
     }
+    for (const surface of buildBrowserExtensionSurfacesFromGraph(options.graphBundle, disposition)) {
+        addSurface(surface);
+    }
     return { surfaces };
 }

package/dist/orchestrator/autoFixExecutor.js

@@ -1,3 +1,4 @@
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { isAuditExcludedStatus } from "../extractors/disposition.js";
 import { resolveNodeTool, runFirstAvailableCommand, } from "./localCommands.js";
@@ -5,6 +6,35 @@ function tryRunConfiguredFormatter(root, candidates) {
     const result = runFirstAvailableCommand(root, candidates);
     return result !== null && !result.error && result.exitCode === 0;
 }
+const PRETTIER_CONFIG_FILES = [
+    ".prettierrc",
+    ".prettierrc.json",
+    ".prettierrc.yml",
+    ".prettierrc.yaml",
+    ".prettierrc.json5",
+    ".prettierrc.js",
+    ".prettierrc.cjs",
+    ".prettierrc.mjs",
+    "prettier.config.js",
+    "prettier.config.cjs",
+    "prettier.config.mjs",
+];
+function hasPrettierConfig(root) {
+    if (PRETTIER_CONFIG_FILES.some((file) => existsSync(join(root, file)))) {
+        return true;
+    }
+    const packageJsonPath = join(root, "package.json");
+    if (!existsSync(packageJsonPath)) {
+        return false;
+    }
+    try {
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+        return packageJson.prettier !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
 export function runAutoFixExecutor(bundle, root) {
     if (!bundle.file_disposition) {
         throw new Error("Cannot run auto fix executor without file_disposition");
@@ -20,16 +50,17 @@ export function runAutoFixExecutor(bundle, root) {
     }
     const executedTools = [];
     // JS, TS, HTML, CSS, JSON, YAML, MD
-    if (extensions.has("ts") ||
-        extensions.has("js") ||
-        extensions.has("tsx") ||
-        extensions.has("jsx") ||
-        extensions.has("html") ||
-        extensions.has("css") ||
-        extensions.has("json") ||
-        extensions.has("yml") ||
-        extensions.has("yaml") ||
-        extensions.has("md")) {
+    if (hasPrettierConfig(root) &&
+        (extensions.has("ts") ||
+            extensions.has("js") ||
+            extensions.has("tsx") ||
+            extensions.has("jsx") ||
+            extensions.has("html") ||
+            extensions.has("css") ||
+            extensions.has("json") ||
+            extensions.has("yml") ||
+            extensions.has("yaml") ||
+            extensions.has("md"))) {
         if (tryRunConfiguredFormatter(root, [
             ...resolveNodeTool(root, join("node_modules", "prettier", "bin", "prettier.cjs"), ["--write", "."], "prettier --write ."),
             { command: "prettier", args: ["--write", "."], display: "prettier --write ." },

package/dist/orchestrator/internalExecutors.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { buildFileDisposition } from "../extractors/disposition.js";
+import { buildFileDisposition, isAuditExcludedStatus, } from "../extractors/disposition.js";
 import { buildGraphBundle, buildGraphBundleFromFs, } from "../extractors/graph.js";
 import { buildCriticalFlowManifest } from "../extractors/flows.js";
 import { buildRiskRegister } from "../extractors/risk.js";
@@ -123,6 +123,10 @@ export async function runIntakeExecutor(bundle, root) {
         hash_files: false,
     });
     const disposition = buildFileDisposition(repoManifest);
+    const auditableCount = disposition.files.filter((file) => !isAuditExcludedStatus(file.status)).length;
+    if (auditableCount === 0) {
+        throw new Error(`No auditable files found in ${root}. The repository may be empty, generated-only, documentation-only, or filtered by .auditorignore.`);
+    }
     return {
         updated: {
             ...bundle,
@@ -140,7 +144,6 @@ export async function runStructureExecutor(bundle, root) {
     const externalAnalyzerResults = bundle.external_analyzer_results;
     const disposition = bundle.file_disposition ?? buildFileDisposition(bundle.repo_manifest);
     const unitManifest = buildUnitManifest(bundle.repo_manifest, disposition);
-    const surfaceManifest = buildSurfaceManifest(bundle.repo_manifest, disposition);
     const graphBundle = root
         ? await buildGraphBundleFromFs(bundle.repo_manifest, root, disposition, {
             externalAnalyzerResults,
@@ -148,6 +151,7 @@ export async function runStructureExecutor(bundle, root) {
         : buildGraphBundle(bundle.repo_manifest, disposition, {
             externalAnalyzerResults,
         });
+    const surfaceManifest = buildSurfaceManifest(bundle.repo_manifest, disposition, { graphBundle });
     const criticalFlows = buildCriticalFlowManifest(bundle.repo_manifest, surfaceManifest, disposition);
     const riskRegister = buildRiskRegister(unitManifest, criticalFlows, externalAnalyzerResults);
     return {

package/dist/orchestrator/planning.js

@@ -1,5 +1,6 @@
 import { applyUnitCoverage, createCoverageMatrix, markExcludedPath, } from "../coverage.js";
 import { isAuditExcludedStatus } from "../extractors/disposition.js";
+import { hasBrowserExtensionManifestFile } from "../extractors/browserExtension.js";
 import { deriveRequiredLensesForPath } from "./unitBuilder.js";
 const CATEGORY_LENS_TABLE = [
     [["security", "secret"], ["security", "correctness"]],
@@ -47,6 +48,7 @@ function applyAnalyzerCoverage(coverage, externalAnalyzerResults) {
 }
 export function initializeCoverageFromPlan(repoManifest, unitManifest, disposition, externalAnalyzerResults) {
     const coverage = createCoverageMatrix(repoManifest.files.map((file) => file.path));
+    const isBrowserExtensionProject = hasBrowserExtensionManifestFile(repoManifest);
     const dispositionMap = new Map(disposition.files.map((item) => [item.path, item.status]));
     for (const file of repoManifest.files) {
         const status = dispositionMap.get(file.path);
@@ -66,7 +68,9 @@ export function initializeCoverageFromPlan(repoManifest, unitManifest, dispositi
     }
     for (const file of repoManifest.files) {
         const unitIds = unitIdsByPath.get(file.path) ?? [];
-        const requiredLenses = deriveRequiredLensesForPath(file.path);
+        const requiredLenses = deriveRequiredLensesForPath(file.path, {
+            isBrowserExtensionProject,
+        });
         for (const unitId of unitIds) {
             applyUnitCoverage(coverage, file.path, unitId, requiredLenses);
         }

package/dist/orchestrator/syntaxResolutionExecutor.js

@@ -15,6 +15,14 @@ const ESLINT_CONFIG_FILES = [
     ".eslintrc.yml",
     ".eslintrc.yaml",
 ];
+const TSCONFIG_FILES = [
+    "tsconfig.json",
+    "tsconfig.build.json",
+    "jsconfig.json",
+];
+function hasTypeScriptConfig(root) {
+    return TSCONFIG_FILES.some((file) => existsSync(join(root, file)));
+}
 function hasEslintConfig(root) {
     if (ESLINT_CONFIG_FILES.some((file) => existsSync(join(root, file)))) {
         return true;
@@ -109,7 +117,8 @@ function runEslint(root) {
 }
 export function runSyntaxResolutionExecutor(bundle, root) {
     const items = [];
-    if (bundle.file_disposition?.files.some((f) => f.path.endsWith(".ts"))) {
+    if (hasTypeScriptConfig(root) &&
+        bundle.file_disposition?.files.some((f) => f.path.endsWith(".ts"))) {
         items.push(...runTsc(root));
     }
     if (bundle.file_disposition?.files.some((f) => f.path.endsWith(".ts") || f.path.endsWith(".js"))) {

package/dist/orchestrator/unitBuilder.d.ts

@@ -1,5 +1,7 @@
 import type { Lens, RepoManifest, UnitManifest } from "../types.js";
 import type { FileDisposition } from "../types/disposition.js";
 export declare const LENS_ORDER: Lens[];
-export declare function deriveRequiredLensesForPath(path: string): Lens[];
+export declare function deriveRequiredLensesForPath(path: string, options?: {
+    isBrowserExtensionProject?: boolean;
+}): Lens[];
 export declare function buildUnitManifest(repoManifest: RepoManifest, disposition?: FileDisposition): UnitManifest;

package/dist/orchestrator/unitBuilder.js

@@ -1,3 +1,4 @@
+import { deriveBrowserExtensionLensesForPath, hasBrowserExtensionManifestFile, inferBrowserExtensionUnitKind, } from "../extractors/browserExtension.js";
 import { bucketFile } from "../extractors/bucketing.js";
 import { isAuditExcludedStatus } from "../extractors/disposition.js";
 import { pathTokens, normalizeExtractorPath } from "../extractors/pathPatterns.js";
@@ -14,7 +15,13 @@ const LENS_MAP = {
     generated_vendor: ["maintainability"],
     unknown: ["correctness"],
 };
-function inferUnitKind(path) {
+function inferUnitKind(path, isBrowserExtensionProject = false) {
+    if (isBrowserExtensionProject) {
+        const extensionKind = inferBrowserExtensionUnitKind(path);
+        if (extensionKind) {
+            return extensionKind;
+        }
+    }
     const normalized = path.toLowerCase();
     if (normalized.startsWith("apps/") || normalized.startsWith("services/"))
         return "service";
@@ -94,7 +101,7 @@ function applyExtensionLensGuards(path, lenses) {
     }
     return lenses;
 }
-export function deriveRequiredLensesForPath(path) {
+export function deriveRequiredLensesForPath(path, options = {}) {
     const assignment = bucketFile(path);
     const required = new Set();
     for (const bucket of assignment.buckets) {
@@ -102,6 +109,11 @@ export function deriveRequiredLensesForPath(path) {
             required.add(lens);
         }
     }
+    if (options.isBrowserExtensionProject) {
+        for (const lens of deriveBrowserExtensionLensesForPath(path)) {
+            required.add(lens);
+        }
+    }
     return applyExtensionLensGuards(path, sortLenses(required));
 }
 function inferCriticalFlows(files, requiredLenses) {
@@ -128,13 +140,14 @@ function inferCriticalFlows(files, requiredLenses) {
 }
 export function buildUnitManifest(repoManifest, disposition) {
     const units = new Map();
+    const isBrowserExtensionProject = hasBrowserExtensionManifestFile(repoManifest);
     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 (file.excluded || (status && isAuditExcludedStatus(status))) {
             continue;
         }
-        const kind = inferUnitKind(file.path);
+        const kind = inferUnitKind(file.path, isBrowserExtensionProject);
         const unitId = inferUnitId(file.path, kind);
         const existing = units.get(unitId) ?? {
             unit_id: unitId,
@@ -148,7 +161,9 @@ export function buildUnitManifest(repoManifest, disposition) {
         }
         const assignment = bucketFile(file.path);
         const required = new Set(existing.required_lenses);
-        for (const lens of deriveRequiredLensesForPath(file.path)) {
+        for (const lens of deriveRequiredLensesForPath(file.path, {
+            isBrowserExtensionProject,
+        })) {
             required.add(lens);
         }
         existing.required_lenses = sortLenses(required);

package/dist/supervisor/operatorHandoff.js

@@ -118,7 +118,7 @@ function buildInteractiveProviderHint(status, providerName, sessionConfigPath, i
         return null;
     }
     if (isConfigError) {
-        return `Configuration error: Verify --root points to a repository root (with package.json, go.mod, etc.).`;
+        return `Configuration error: Verify --root points to the intended repository root and that the tree contains auditable files.`;
     }
     const providerLabel = providerName ?? LOCAL_SUBPROCESS_PROVIDER_NAME;
     return `Provider: ${providerLabel}. For automatic LLM review, configure an interactive provider in ${sessionConfigPath}.`;

package/docs/operator-guide.md

@@ -105,12 +105,20 @@ audit-code --updates /path/to/runtime_validation_update.json
 audit-code --external-analyzer-results /path/to/external_analyzer_results.json
 audit-code explain-task <task_id>
 audit-code validate
+audit-code cleanup
 audit-code mcp
 ```
 
 `audit-code validate` checks artifact shape, cross-artifact consistency,
 session config, and explicit provider readiness.
 
+`audit-code cleanup` removes the `.audit-artifacts/` directory when safe to
+do so. It reads `audit_state.json` before acting: `complete` and `not_started`
+states are deleted unconditionally; `active` and `blocked` states are refused
+(the audit is resumable). If `audit_state.json` is missing — typically a
+crashed run — cleanup also refuses unless `--force` is passed. `--dry-run`
+previews the action without deleting anything.
+
 ## Session config
 
 Backend fallback configuration lives at:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auditor-lambda",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",