docbridge 0.12.0 → 0.13.1

package/dist/index.js

@@ -175581,7 +175581,7 @@ import { join as join15, resolve as resolve5 } from "node:path";
 // package.json
 var package_default = {
   name: "docbridge",
-  version: "0.12.0",
+  version: "0.13.1",
   description: "A CLI that links Markdown specifications and code declarations. Runs on Node.js and Bun.",
   keywords: [
     "bun",
@@ -175781,7 +175781,8 @@ var KNOWN_CODE_LANGUAGES = [
   "go",
   "javascript",
   "python",
-  "ruby"
+  "ruby",
+  "java"
 ];
 function isCodeLanguage(value) {
   return KNOWN_CODE_LANGUAGES.includes(value);
@@ -175794,7 +175795,8 @@ var LANGUAGE_SUFFIXES = {
   go: [".go"],
   javascript: [".js", ".jsx", ".mjs", ".cjs"],
   python: [".py"],
-  ruby: [".rb"]
+  ruby: [".rb"],
+  java: [".java"]
 };
 var EXCLUDED_SUFFIXES = {
   typescript: [".d.ts", ".d.mts", ".d.cts"],
@@ -175804,7 +175806,8 @@ var EXCLUDED_SUFFIXES = {
   go: [],
   javascript: [],
   python: [],
-  ruby: []
+  ruby: [],
+  java: []
 };
 function codeFenceLanguage(language, filePath) {
   if (language === "typescript") {
@@ -175924,7 +175927,8 @@ var LANGUAGE_VISIBILITY = {
   go: ["exported", "unexported"],
   javascript: ["public", "protected", "private"],
   python: ["public", "private"],
-  ruby: ["public", "protected", "private"]
+  ruby: ["public", "protected", "private"],
+  java: ["public", "protected", "package", "private"]
 };
 function loadConfig(projectRoot) {
   let rawText;
@@ -176061,10 +176065,6 @@ function validateCodeEntry(language, value, diagnostics) {
 }
 function validateVisibilityOptions(language, values, target, diagnostics) {
   const allowed = LANGUAGE_VISIBILITY[language];
-  if (allowed.length === 0) {
-    diagnostics.push(configDiagnostic2("config_invalid_value", `${target}.visibility`, `\`${target}.visibility\` is not supported for ${language}.`));
-    return;
-  }
   for (const value of values) {
     if (!allowed.includes(value)) {
       diagnostics.push(configDiagnostic2("config_invalid_value", `${target}.visibility`, `Unsupported ${language} visibility: ${value}. Supported values: ${allowed.join(", ")}.`));
@@ -177775,9 +177775,6 @@ function duplicateLinkDiagnostic(source, target, location, range) {
 // src/scan/code/typescript.ts
 var typeScriptAdapter = {
   language: "typescript",
-  scanFile(filePath, content, options) {
-    return scanTypeScript(filePath, content, options);
-  },
   scanFiles(files, options) {
     return files.map(({ filePath, content }) => scanTypeScript(filePath, content, options));
   }
@@ -178246,12 +178243,9 @@ function firstToken(text) {
 import { accessSync as accessSync2, constants as constants2, existsSync as existsSync3, realpathSync as realpathSync2, statSync as statSync2 } from "node:fs";
 import { extname, isAbsolute as isAbsolute2, join as join7, resolve as resolve2 } from "node:path";
 
-// src/scan/code/worker/runtime-probe.ts
-import { spawnSync as spawnSync2 } from "node:child_process";
-
 // src/scan/code/worker/scanner-worker.ts
 var import__2020 = __toESM(require_2020(), 1);
-import { spawn, spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join as join4 } from "node:path";
@@ -178450,14 +178444,12 @@ var scanner_worker_schema_default = {
 // src/scan/code/worker/scanner-worker.ts
 var WORKER_OUTPUT_LIMIT_BYTES = 1024 * 1024 * 1024;
 var KILLED_WORKER_GRACE_MS = 500;
-function createLazyWorkerResponseValidator(compile) {
-  let validator;
-  return () => {
-    validator ??= compile();
-    return validator;
-  };
+var liveWorkers = new Map;
+var compiledResponseValidator;
+function responseValidator() {
+  compiledResponseValidator ??= compileWorkerResponseValidator();
+  return compiledResponseValidator;
 }
-var responseValidator = createLazyWorkerResponseValidator(compileWorkerResponseValidator);
 function compileWorkerResponseValidator() {
   const ajv = new import__2020.default({ allErrors: true, strict: true });
   ajv.addSchema(common_output_schema_default);
@@ -178468,13 +178460,10 @@ function compileWorkerResponseValidator() {
   });
 }
 function invokeScannerWorker(request, command, run = runScannerWorkerProcess, stripEnv = []) {
-  return interpretWorkerProcess(request, command, run(processInput(request, command, stripEnv)));
-}
-function invokeScannerWorkerAsync(request, command, runAsync = runScannerWorkerProcessAsync, stripEnv = []) {
-  const run = runAsync(processInput(request, command, stripEnv));
+  const task = run(processInput(request, command, stripEnv));
   return {
-    promise: run.promise.then((processResult) => interpretWorkerProcess(request, command, processResult)),
-    cancel: () => run.cancel()
+    promise: task.promise.then((processResult) => interpretWorkerProcess(request, command, processResult)),
+    cancel: () => task.cancel()
   };
 }
 function processInput(request, command, stripEnv) {
@@ -178550,36 +178539,6 @@ function workerTimeoutMs(fileCount) {
   return 30000 + 1000 * fileCount;
 }
 function runScannerWorkerProcess(input) {
-  const maxOutputBytes = input.maxOutputBytes ?? WORKER_OUTPUT_LIMIT_BYTES;
-  try {
-    const [executable = "", ...args] = input.command;
-    const result = spawnSync(executable, args, {
-      env: workerProcessEnv(input.stripEnv),
-      input: input.stdin,
-      encoding: "utf8",
-      maxBuffer: maxOutputBytes,
-      killSignal: "SIGKILL",
-      ...input.timeoutMs === undefined ? {} : { timeout: input.timeoutMs }
-    });
-    return syncWorkerProcessResult(result, input.timeoutMs, maxOutputBytes);
-  } catch (error) {
-    return { ok: false, kind: "start", error, stderr: "" };
-  }
-}
-function syncWorkerProcessResult(result, timeoutMs, maxOutputBytes) {
-  const stderr = result.stderr ?? "";
-  if (result.error !== undefined) {
-    return syncSpawnFailure(result.error, workerStarted(result), timeoutMs, maxOutputBytes, stderr);
-  }
-  if (Buffer.byteLength(result.stdout ?? "") + Buffer.byteLength(stderr) > maxOutputBytes) {
-    return { ok: false, kind: "execution", error: outputLimitError(maxOutputBytes), stderr };
-  }
-  if (typeof result.status !== "number") {
-    return { ok: false, kind: "execution", error: signalError(result.signal), stderr };
-  }
-  return { ok: true, exitCode: result.status, stdout: result.stdout ?? "", stderr };
-}
-function runScannerWorkerProcessAsync(input) {
   const run = deferred();
   let settled = false;
   let timer;
@@ -178589,6 +178548,9 @@ function runScannerWorkerProcessAsync(input) {
       return;
     }
     settled = true;
+    if (child !== undefined) {
+      liveWorkers.delete(child);
+    }
     clearTimeout(timer);
     clearTimeout(grace);
     complete();
@@ -178597,24 +178559,34 @@ function runScannerWorkerProcessAsync(input) {
   let child;
   try {
     const [executable = "", ...args] = input.command;
-    child = spawn(executable, args, { env: workerProcessEnv(input.stripEnv), detached: ownGroup });
+    child = spawn(executable, args, {
+      env: workerProcessEnv(input.stripEnv),
+      detached: ownGroup,
+      windowsHide: true
+    });
   } catch (error) {
     settle(() => run.resolve({ ok: false, kind: "start", error, stderr: "" }));
     return { promise: run.promise, cancel: () => {
       return;
     } };
   }
+  liveWorkers.set(child, ownGroup);
   const maxOutputBytes = input.maxOutputBytes ?? WORKER_OUTPUT_LIMIT_BYTES;
   const budget = { bytes: 0, limit: maxOutputBytes };
   const stdout = new OutputCollector(budget);
   const stderr = new OutputCollector(budget);
   let failure;
-  const kill = (reason) => {
+  let cause;
+  let exited = false;
+  const kill = (reason, why) => {
     failure ??= reason;
-    killWorker(child, ownGroup);
+    cause ??= why;
+    if (!exited) {
+      killWorker(child, ownGroup);
+    }
     grace ??= setTimeout(() => {
       closeStreams(child);
-      settle(() => run.resolve(closedProcessResult(null, null, failure, stdout, stderr)));
+      settle(() => run.resolve(closedProcessResult(null, null, failure, cause, stdout, stderr)));
     }, KILLED_WORKER_GRACE_MS);
   };
   let spawned = false;
@@ -178630,30 +178602,36 @@ function runScannerWorkerProcessAsync(input) {
   });
   child.stdout.on("data", (chunk) => {
     if (!stdout.add(chunk)) {
-      kill(outputLimitError(maxOutputBytes));
+      kill(outputLimitError(maxOutputBytes), { type: "output-limit" });
     }
   });
   child.stderr.on("data", (chunk) => {
     if (!stderr.add(chunk)) {
-      kill(outputLimitError(maxOutputBytes));
+      kill(outputLimitError(maxOutputBytes), { type: "output-limit" });
     }
   });
   child.stdin.on("error", () => {
     return;
   });
+  child.on("exit", () => {
+    exited = true;
+    liveWorkers.delete(child);
+  });
   child.on("close", (code, signal) => {
-    settle(() => run.resolve(closedProcessResult(code, signal, failure, stdout, stderr)));
+    settle(() => run.resolve(closedProcessResult(code, signal, failure, cause, stdout, stderr)));
   });
   child.stdin.end(input.stdin);
   const { timeoutMs } = input;
   if (timeoutMs !== undefined) {
-    timer = setTimeout(() => kill(timeoutError(timeoutMs)), timeoutMs);
+    timer = setTimeout(() => kill(timeoutError(timeoutMs), { type: "timeout" }), timeoutMs);
   }
   return {
     promise: run.promise,
     cancel() {
       settle(() => {
-        killWorker(child, ownGroup);
+        if (!exited) {
+          killWorker(child, ownGroup);
+        }
         closeStreams(child);
         run.reject(abortError());
       });
@@ -178693,39 +178671,36 @@ class OutputCollector {
     return Buffer.concat(this.chunks).toString("utf8");
   }
 }
-function closedProcessResult(code, signal, failure, stdout, stderr) {
+function closedProcessResult(code, signal, failure, cause, stdout, stderr) {
   if (failure !== undefined) {
-    return { ok: false, kind: "execution", error: failure, stderr: stderr.text() };
+    return {
+      ok: false,
+      kind: "execution",
+      error: failure,
+      ...cause === undefined ? {} : { cause },
+      stderr: stderr.text()
+    };
   }
   if (code === null) {
-    return { ok: false, kind: "execution", error: signalError(signal), stderr: stderr.text() };
+    return {
+      ok: false,
+      kind: "execution",
+      error: signalError(signal),
+      cause: { type: "signal", signal: signal ?? "unknown" },
+      stderr: stderr.text()
+    };
   }
   return { ok: true, exitCode: code, stdout: stdout.text(), stderr: stderr.text() };
 }
-function workerStarted(result) {
-  return typeof result.status === "number" || typeof result.signal === "string" || typeof result.pid === "number" && result.pid > 0;
-}
-function syncSpawnFailure(error, started, timeoutMs, maxOutputBytes, stderr) {
-  const code = error.code;
-  if (code === "ETIMEDOUT") {
-    return { ok: false, kind: "execution", error: timeoutError(timeoutMs ?? 0), stderr };
-  }
-  if (code === "ENOBUFS") {
-    return { ok: false, kind: "execution", error: outputLimitError(maxOutputBytes), stderr };
-  }
-  return { ok: false, kind: started ? "execution" : "start", error, stderr };
-}
 function signalError(signal) {
   const name = signal ?? "unknown";
-  return Object.assign(new Error(`worker terminated by signal ${name}`), { signal: name });
+  return new Error(`worker terminated by signal ${name}`);
 }
 function timeoutError(timeoutMs) {
-  return Object.assign(new Error(`worker timed out after ${timeoutMs} ms`), {
-    code: "ETIMEDOUT"
-  });
+  return new Error(`worker timed out after ${timeoutMs} ms`);
 }
 function outputLimitError(maxOutputBytes) {
-  return Object.assign(new Error(`worker wrote more than ${maxOutputBytes} bytes to stdout and stderr together`), { code: "ENOBUFS" });
+  return new Error(`worker wrote more than ${maxOutputBytes} bytes to stdout and stderr together`);
 }
 function validateWorkerResponse(value, request) {
   const validator = responseValidator();
@@ -178753,18 +178728,7 @@ function formatSchemaError(errors) {
   return `worker response does not match scanner-worker.schema.json at ${path}: ${error.message ?? "invalid value"}`;
 }
 function responseFilesMatchRequest(responseFiles, requestFiles) {
-  if (responseFiles.length !== requestFiles.length) {
-    return false;
-  }
-  return responseFiles.every((file, index) => {
-    if (!isRecord(file)) {
-      return false;
-    }
-    return file.filePath === requestFiles[index]?.filePath;
-  });
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+  return responseFiles.length === requestFiles.length && responseFiles.every((file, index) => file.filePath === requestFiles[index]?.filePath);
 }
 function scannerUnavailableDiagnostic(language, error, executable) {
   const label = languageLabel(language);
@@ -178803,20 +178767,17 @@ function scannerFailedDiagnostic(language, reason) {
 function languageLabel(language) {
   return language.charAt(0).toUpperCase() + language.slice(1);
 }
+function killRunningWorkers() {
+  for (const [child, ownGroup] of liveWorkers) {
+    killWorker(child, ownGroup);
+  }
+}
 
 // src/scan/code/worker/runtime-probe.ts
 var PROBE_TIMEOUT_MS = 1e4;
 var PROBE_MAX_OUTPUT_BYTES = 64 * 1024;
-function probeRuntime(command, stripEnv, spawn2 = spawnRuntimeProbe) {
-  const [executable = "", ...args] = command;
-  return classifyProbe(spawn2(executable, [...args, "--probe"], {
-    env: workerProcessEnv(stripEnv),
-    timeout: PROBE_TIMEOUT_MS,
-    maxBuffer: PROBE_MAX_OUTPUT_BYTES
-  }));
-}
-function probeRuntimeAsync(command, stripEnv, runAsync = runScannerWorkerProcessAsync) {
-  const run = runAsync({
+function probeRuntime(command, stripEnv, run = runScannerWorkerProcess) {
+  const task = run({
     command: [...command, "--probe"],
     stdin: "",
     stripEnv,
@@ -178824,49 +178785,34 @@ function probeRuntimeAsync(command, stripEnv, runAsync = runScannerWorkerProcess
     maxOutputBytes: PROBE_MAX_OUTPUT_BYTES
   });
   return {
-    promise: run.promise.then((result) => classifyProbe(spawnResultOf(result))),
-    cancel: () => run.cancel()
+    promise: task.promise.then(classifyProbe),
+    cancel: () => task.cancel()
   };
 }
-function spawnResultOf(result) {
-  if (result.ok) {
-    return { status: result.exitCode, signal: null, stdout: result.stdout, stderr: result.stderr };
-  }
-  const error = result.error instanceof Error ? result.error : new Error(reasonOf(result.error));
-  const { signal } = error;
-  if (typeof signal === "string") {
-    return { status: null, signal, stdout: "", stderr: result.stderr };
-  }
-  return { status: null, signal: null, stdout: "", stderr: result.stderr, error };
-}
 function classifyProbe(result) {
-  if (result.error !== undefined) {
-    return classifySpawnError(result.error);
-  }
-  if (result.status === null) {
-    return { kind: "failed", reason: `probe terminated by signal ${result.signal ?? "unknown"}` };
-  }
-  if (result.status !== 0) {
-    const detail = firstLine(result.stderr);
-    return {
-      kind: "failed",
-      reason: `probe exited with status ${result.status}${detail === "" ? "" : `: ${detail}`}`
-    };
-  }
-  return parseProbeOutput(result.stdout);
-}
-function classifySpawnError(error) {
-  const code = error.code;
-  if (code === "ETIMEDOUT") {
-    return { kind: "failed", reason: `probe did not finish within ${PROBE_TIMEOUT_MS / 1000} s` };
+  if (result.ok) {
+    if (result.exitCode !== 0) {
+      const detail = firstLine(result.stderr);
+      return {
+        kind: "failed",
+        reason: `probe exited with status ${result.exitCode}${detail === "" ? "" : `: ${detail}`}`
+      };
+    }
+    return parseProbeOutput(result.stdout);
   }
-  if (code === "ENOBUFS") {
-    return {
-      kind: "failed",
-      reason: `probe printed more than ${PROBE_MAX_OUTPUT_BYTES / 1024} KiB`
-    };
+  switch (result.cause?.type) {
+    case "timeout":
+      return { kind: "failed", reason: `probe did not finish within ${PROBE_TIMEOUT_MS / 1000} s` };
+    case "output-limit":
+      return {
+        kind: "failed",
+        reason: `probe printed more than ${PROBE_MAX_OUTPUT_BYTES / 1024} KiB`
+      };
+    case "signal":
+      return { kind: "failed", reason: `probe terminated by signal ${result.cause.signal}` };
+    default:
+      return { kind: "unstartable", reason: reasonOf(result.error) };
   }
-  return { kind: "unstartable", reason: reasonOf(error) };
 }
 function parseProbeOutput(stdout) {
   const text = stdout.trim();
@@ -178876,7 +178822,7 @@ function parseProbeOutput(stdout) {
   } catch {
     return malformed(text);
   }
-  if (!isRecord2(value)) {
+  if (!isRecord(value)) {
     return malformed(text);
   }
   if (value.ok === true && typeof value.runtime === "string" && typeof value.version === "string") {
@@ -178894,40 +178840,9 @@ function malformed(text) {
 function firstLine(text) {
   return text.trim().split(/\r?\n/u)[0] ?? "";
 }
-function isRecord2(value) {
+function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function spawnRuntimeProbe(executable, args, options) {
-  try {
-    const result = spawnSync2(executable, args, {
-      env: options.env,
-      timeout: options.timeout,
-      killSignal: "SIGKILL",
-      maxBuffer: options.maxBuffer,
-      input: "",
-      encoding: "utf8",
-      windowsHide: true
-    });
-    const stdout = result.stdout ?? "";
-    const stderr = result.stderr ?? "";
-    const error = result.error === undefined && Buffer.byteLength(stdout) + Buffer.byteLength(stderr) > options.maxBuffer ? Object.assign(new Error("probe output exceeded maxBuffer"), { code: "ENOBUFS" }) : result.error;
-    return {
-      status: result.status,
-      signal: result.signal,
-      stdout,
-      stderr,
-      ...error === undefined ? {} : { error }
-    };
-  } catch (error) {
-    return {
-      status: null,
-      signal: null,
-      stdout: "",
-      stderr: "",
-      error: error instanceof Error ? error : new Error(String(error))
-    };
-  }
-}
 
 // src/scan/code/worker/scanner-executable.ts
 import { accessSync, chmodSync, constants, existsSync as existsSync2, statSync } from "node:fs";
@@ -179139,22 +179054,12 @@ function rememberProbe(key, generation, outcome) {
 function resolveRuntimeWorkerCommand(language, options) {
   const env = options.env ?? process.env;
   const probe = options.probe ?? probeRuntime;
-  const steps = resolutionSteps(language, options, env);
-  let step = steps.next();
-  while (step.done !== true) {
-    step = steps.next(cachedProbe(step.value, env, probe));
-  }
-  return step.value;
-}
-function resolveRuntimeWorkerCommandAsync(language, options) {
-  const env = options.env ?? process.env;
-  const probeAsync = options.probeAsync ?? probeRuntimeAsync;
   return cancelableSequence(async (run) => {
     const steps = resolutionSteps(language, options, env);
     let step = steps.next();
     while (step.done !== true) {
       const request = step.value;
-      step = steps.next(await run(() => cachedProbeAsync(request, env, probeAsync)));
+      step = steps.next(await run(() => cachedProbe(request, env, probe)));
     }
     return step.value;
   });
@@ -179262,24 +179167,13 @@ function isExecutableFile(path, platform) {
   }
 }
 function cachedProbe({ command, stripEnv }, env, probe) {
-  const key = probeCacheKey(command, env);
-  const cached = probeCache.get(key);
-  if (cached !== undefined) {
-    return cached;
-  }
-  const generation = probeCacheGeneration;
-  const outcome = probe(command, stripEnv);
-  rememberProbe(key, generation, outcome);
-  return outcome;
-}
-function cachedProbeAsync({ command, stripEnv }, env, probeAsync) {
   const key = probeCacheKey(command, env);
   const cached = probeCache.get(key);
   if (cached !== undefined) {
     return settledCancelable(cached);
   }
   const generation = probeCacheGeneration;
-  return mapCancelable(probeAsync(command, stripEnv), (outcome) => {
+  return mapCancelable(probe(command, stripEnv), (outcome) => {
     rememberProbe(key, generation, outcome);
     return outcome;
   });
@@ -179326,7 +179220,7 @@ function failure(spec, language, code, reason) {
     diagnostic: {
       severity: "error",
       code,
-      ...isCodeLanguage(language) ? { language } : {},
+      language,
       target: language,
       message: `${spec.label} scanner worker ${state}: ${reason}`
     }
@@ -179335,16 +179229,12 @@ function failure(spec, language, code, reason) {
 
 // src/scan/code/dispatch.ts
 function createScannerWorkerAdapter(language, command, adapterOptions = {}) {
-  const { commandAsync } = adapterOptions;
-  const bound = (context) => boundWorkerAdapter(language, workerCommand(command(context)), adapterOptions).adapter;
-  const prepare = (context) => mapCancelable(commandAsync?.(context) ?? settledCancelable(command(context)), (value) => boundWorkerAdapter(language, workerCommand(value), adapterOptions));
+  const resolve3 = (context) => typeof command === "function" ? settledCancelable(command(context)) : command.commandAsync(context);
+  const prepare = (context) => mapCancelable(resolve3(context), (value) => boundWorkerAdapter(language, workerCommand(value), adapterOptions));
   const scanBatchAsync = (files, options, context) => {
     if (files.length === 0) {
       return settledCancelable([]);
     }
-    if (commandAsync === undefined) {
-      return bound(context).scanFilesAsync(files, options, context);
-    }
     return cancelableSequence(async (step) => {
       const { adapter } = await step(() => prepare(context));
       return step(() => adapter.scanFilesAsync(files, options, context));
@@ -179352,8 +179242,6 @@ function createScannerWorkerAdapter(language, command, adapterOptions = {}) {
   };
   return {
     language,
-    scanFile: (filePath, content, options, context) => bound(context).scanFile(filePath, content, options, context),
-    scanFiles: (files, options, context) => files.length === 0 ? [] : bound(context).scanFiles(files, options, context),
     scanFilesAsync: scanBatchAsync,
     prepare
   };
@@ -179363,20 +179251,6 @@ function boundWorkerAdapter(language, resolved, adapterOptions) {
   const runtime = resolved.ok ? resolved.runtime : [];
   const adapter = {
     language,
-    scanFile(filePath, content, options, context) {
-      const [scan] = adapter.scanFiles([{ filePath, content }], options, context);
-      return scan ?? emptyScan(language, filePath);
-    },
-    scanFiles(files, options, context) {
-      if (files.length === 0) {
-        return [];
-      }
-      if (!resolved.ok) {
-        return failedBatch(language, files, resolved.diagnostic);
-      }
-      const result = invokeScannerWorker(workerRequest(language, files, options, context, adapterOptions), resolved.command, adapterOptions.run, resolved.stripEnv);
-      return result.ok ? result.codeFiles : failedBatch(language, files, result.diagnostic);
-    },
     scanFilesAsync(files, options, context) {
       if (files.length === 0) {
         return settledCancelable([]);
@@ -179384,36 +179258,28 @@ function boundWorkerAdapter(language, resolved, adapterOptions) {
       if (!resolved.ok) {
         return settledCancelable(failedBatch(language, files, resolved.diagnostic));
       }
-      const task = invokeScannerWorkerAsync(workerRequest(language, files, options, context, adapterOptions), resolved.command, adapterOptions.runAsync, resolved.stripEnv);
+      const task = invokeScannerWorker(workerRequest(language, files, options, context, adapterOptions), resolved.command, adapterOptions.run, resolved.stripEnv);
       return mapCancelable(task, (result) => result.ok ? result.codeFiles : failedBatch(language, files, result.diagnostic));
     },
     prepare: () => settledCancelable({ argv, runtime, adapter })
   };
   return { argv, runtime, adapter };
 }
-function scanCodeFiles(projectRoot, files, codeInclude, read, options = {}) {
-  const plan = planCodeScan(files, codeInclude, read, options.onContent);
-  const context = scanContext(projectRoot, options);
-  for (const batch of plan.batches) {
-    const adapter = options.adapters?.[batch.language] ?? builtInAdapters[batch.language];
-    fillBatch(plan, batch, adapter.scanFiles(batch.files, batch.options, context));
-  }
-  return assemblePlan(plan);
-}
 function scanContext(projectRoot, options) {
   return options.scanners === undefined ? { projectRoot } : { projectRoot, scanners: options.scanners };
 }
-function scanCodeFilesAsync(projectRoot, files, codeInclude, read, options = {}) {
+function scanCodeFiles(projectRoot, files, codeInclude, read, options = {}) {
   const plan = planCodeScan(files, codeInclude, read, options.onContent);
   const context = scanContext(projectRoot, options);
   return cancelableSequence(async (step) => {
     const cache = new Map;
     for (const batch of plan.batches) {
       const base = options.adapters?.[batch.language] ?? builtInAdapters[batch.language];
-      const prepare = base.prepare?.bind(base);
-      const { argv, runtime, adapter } = prepare === undefined ? { argv: [], adapter: base } : await step(() => prepare(context));
-      const keys = batch.files.map((file) => codeScanCacheKey(batch.language, file.filePath, file.content, batch.options, argv, runtime));
-      const cached = keys.map((key) => options.cache?.get(key));
+      const { argv, runtime, adapter } = "scanFilesAsync" in base ? await step(() => base.prepare(context)) : { argv: [], adapter: base };
+      const keys = options.cache === undefined ? [] : batch.files.map((file) => codeScanCacheKey(batch.language, file.filePath, file.content, batch.options, argv, runtime));
+      const cached = options.cache === undefined ? batch.files.map(() => {
+        return;
+      }) : keys.map((key) => options.cache?.get(key));
       const missing = batch.files.filter((_, index) => cached[index] === undefined);
       const scanned = missing.length === 0 ? [] : await step(() => scanFilesAsync(adapter, missing, batch.options, context));
       let next = 0;
@@ -179421,7 +179287,7 @@ function scanCodeFilesAsync(projectRoot, files, codeInclude, read, options = {})
       fillBatch(plan, batch, results);
       results.forEach((scan, index) => {
         const key = keys[index];
-        if (scan !== undefined && key !== undefined && isReusableScan(scan)) {
+        if (options.cache !== undefined && scan !== undefined && key !== undefined && isReusableScan(scan)) {
           cache.set(key, scan);
         }
       });
@@ -179430,7 +179296,7 @@ function scanCodeFilesAsync(projectRoot, files, codeInclude, read, options = {})
   });
 }
 function scanFilesAsync(adapter, files, options, context) {
-  return adapter.scanFilesAsync?.(files, options, context) ?? settledCancelable(adapter.scanFiles(files, options, context));
+  return "scanFilesAsync" in adapter ? adapter.scanFilesAsync(files, options, context) : settledCancelable(adapter.scanFiles(files, options, context));
 }
 var builtInAdapters = {
   typescript: typeScriptAdapter,
@@ -179440,14 +179306,17 @@ var builtInAdapters = {
   go: createScannerWorkerAdapter("go", () => resolveScannerWorkerCommand("go")),
   javascript: javaScriptAdapter,
   python: runtimeWorkerAdapter("python"),
-  ruby: runtimeWorkerAdapter("ruby")
+  ruby: runtimeWorkerAdapter("ruby"),
+  java: runtimeWorkerAdapter("java")
 };
 function runtimeWorkerAdapter(language) {
   const resolution = ({ projectRoot, scanners }) => {
     const command = scanners?.[language]?.command;
     return command === undefined ? { projectRoot } : { projectRoot, command };
   };
-  return createScannerWorkerAdapter(language, (context) => resolveRuntimeWorkerCommand(language, resolution(context)), { commandAsync: (context) => resolveRuntimeWorkerCommandAsync(language, resolution(context)) });
+  return createScannerWorkerAdapter(language, {
+    commandAsync: (context) => resolveRuntimeWorkerCommand(language, resolution(context))
+  });
 }
 function planCodeScan(files, codeInclude, read, onContent) {
   const slots = [];
@@ -179768,37 +179637,28 @@ function flushDanglingWith(pending, diagnostics, message) {
 // src/query/project-scan.ts
 function scanProject(options) {
   const loaded = loadProjectScan(options, options.keepContent === true);
-  if (!loaded.ok) {
-    return loaded;
-  }
-  const { inputs } = loaded;
-  const codeScan = scanCodeFiles(options.projectRoot, inputs.codeFiles, inputs.config.include.code, inputs.readFile, codeScanOptions(inputs, options));
-  const docReads = readDocFiles(inputs, options);
-  return { ok: true, scan: finishProjectScan(inputs, codeScan, docReads, options.buildGraph) };
-}
-function scanProjectAsync(options) {
-  const loaded = loadProjectScan(options, true);
   if (!loaded.ok) {
     return cancelableSequence(async () => loaded);
   }
   const { inputs } = loaded;
-  const fingerprint = JSON.stringify(inputs.config);
-  const sameConfiguration = options.cache.fingerprint === fingerprint;
-  if (!sameConfiguration && options.cache.fingerprint !== "") {
+  const previousCache = options.cache;
+  const fingerprint = previousCache === undefined ? undefined : JSON.stringify(inputs.config);
+  const sameConfiguration = previousCache !== undefined && previousCache.fingerprint === fingerprint;
+  if (previousCache !== undefined && !sameConfiguration && previousCache.fingerprint !== "") {
     options.onConfigurationChange?.();
   }
-  const codeScan = scanCodeFilesAsync(options.projectRoot, inputs.codeFiles, inputs.config.include.code, inputs.readFile, {
+  const codeScan = scanCodeFiles(options.projectRoot, inputs.codeFiles, inputs.config.include.code, inputs.readFile, {
     ...codeScanOptions(inputs, options),
-    ...sameConfiguration ? { cache: options.cache.entries } : {}
+    ...previousCache === undefined ? {} : { cache: sameConfiguration ? previousCache.entries : new Map }
   });
   const docReads = readDocFiles(inputs, options);
   return cancelableSequence(async (step) => {
     const { cache, ...code } = await step(codeScan);
-    const scan = finishProjectScan(inputs, code, docReads, true);
+    const scan = finishProjectScan(inputs, code, docReads, options.buildGraph);
     return {
       ok: true,
       scan,
-      cache: { fingerprint, entries: cache }
+      cache: { fingerprint: fingerprint ?? "", entries: cache }
     };
   });
 }
@@ -179903,19 +179763,12 @@ class Project {
     this.overlay.delete(relPath);
     this.overlayRevision += 1;
   }
-  resolve() {
-    const outcome = scanProject({
-      ...this.scanSources(this.overlay),
-      buildGraph: true,
-      keepContent: true
-    });
-    this.current = resolvedState(outcome);
-    return this.current;
-  }
   resolveAsync() {
     const revision = this.overlayRevision;
-    const scan = scanProjectAsync({
+    const scan = scanProject({
       ...this.scanSources(new Map(this.overlay)),
+      buildGraph: true,
+      keepContent: true,
       cache: this.cache,
       onConfigurationChange: clearRuntimeProbeCache
     });
@@ -180414,12 +180267,12 @@ function fullChangeText(changes) {
 }
 
 // src/query/check.ts
-function check(options) {
+async function check(options) {
   const audit = options.audit ?? false;
-  const outcome = scanProject({
+  const outcome = await scanProject({
     projectRoot: options.projectRoot,
     ...options.adapters === undefined ? {} : { adapters: options.adapters }
-  });
+  }).promise;
   if (!outcome.ok) {
     const sorted = sortDiagnostics(outcome.diagnostics);
     return { diagnostics: sorted, summary: summarizeDiagnostics(sorted) };
@@ -180493,8 +180346,8 @@ function collectGateViolations(result) {
   }
   return violations;
 }
-function related(options) {
-  const outcome = scanProject({ projectRoot: options.projectRoot, buildGraph: true });
+async function related(options) {
+  const outcome = await scanProject({ projectRoot: options.projectRoot, buildGraph: true }).promise;
   if (!outcome.ok) {
     return { ok: false, diagnostics: outcome.diagnostics };
   }
@@ -180552,12 +180405,12 @@ function computeContext(graph, contentByFile, inputFiles) {
     summary: { inputFiles: inputSet.size, contexts: contexts.length }
   };
 }
-function context(options) {
-  const outcome = scanProject({
+async function context(options) {
+  const outcome = await scanProject({
     projectRoot: options.projectRoot,
     buildGraph: true,
     keepContent: true
-  });
+  }).promise;
   if (!outcome.ok) {
     return { ok: false, diagnostics: outcome.diagnostics };
   }
@@ -180631,12 +180484,12 @@ function compareBlocks(left, right) {
 }
 
 // src/query/graph-output.ts
-function graph(options) {
-  const outcome = scanProject({
+async function graph(options) {
+  const outcome = await scanProject({
     projectRoot: options.projectRoot,
     buildGraph: true,
     keepContent: true
-  });
+  }).promise;
   if (!outcome.ok) {
     return { ok: false, diagnostics: outcome.diagnostics };
   }
@@ -181131,13 +180984,6 @@ class CliError extends Error {
   }
 }
 
-class InitCliError extends CliError {
-  constructor(message, guidance) {
-    super(message, guidance);
-    this.name = "InitCliError";
-  }
-}
-
 class DiagnosticOutputError extends Error {
   constructor(message) {
     super(message);
@@ -181743,6 +181589,7 @@ var DART_PATTERNS = ["lib/**/*.dart"];
 var RUST_PATTERNS = ["src/**/*.rs", "*/src/**/*.rs"];
 var GO_PATTERNS = ["*.go", "cmd/**/*.go", "internal/**/*.go", "pkg/**/*.go"];
 var RUBY_PATTERNS = ["lib/**/*.rb", "app/**/*.rb"];
+var JAVA_PATTERNS = ["src/main/java/**/*.java", "src/**/*.java"];
 var LANGUAGE_PATTERNS = {
   typescript: TYPESCRIPT_PATTERNS,
   swift: SWIFT_PATTERNS,
@@ -181750,7 +181597,8 @@ var LANGUAGE_PATTERNS = {
   rust: RUST_PATTERNS,
   go: GO_PATTERNS,
   javascript: JAVASCRIPT_PATTERNS,
-  ruby: RUBY_PATTERNS
+  ruby: RUBY_PATTERNS,
+  java: JAVA_PATTERNS
 };
 var EXCLUDED_CODE_SEGMENTS = {
   typescript: ["__tests__", "tests", "test"],
@@ -181760,7 +181608,8 @@ var EXCLUDED_CODE_SEGMENTS = {
   go: ["vendor", "testdata"],
   javascript: ["__tests__", "tests", "test"],
   python: ["tests", "venv", "dist", "site-packages"],
-  ruby: ["spec", "test", "vendor"]
+  ruby: ["spec", "test", "vendor"],
+  java: ["target", "src/test"]
 };
 var TEST_FILE_PATTERNS = {
   typescript: /\.(?:test|spec)\.[cm]?tsx?$/u,
@@ -181939,7 +181788,8 @@ function scriptPatterns(language) {
 }
 function activeCodePatterns(projectRoot, language) {
   const candidates = language === "python" ? pythonPatterns(projectRoot) : LANGUAGE_PATTERNS[language];
-  return candidates.filter((pattern) => countCodeFiles(projectRoot, [pattern], language) > 0);
+  const active = candidates.filter((pattern) => countCodeFiles(projectRoot, [pattern], language) > 0);
+  return language === "java" ? active.slice(0, 1) : active;
 }
 function pythonPatterns(projectRoot) {
   let entries;
@@ -181965,7 +181815,8 @@ function countCodeFiles(projectRoot, patterns, language) {
 function isExcludedCodeFile(filePath, language) {
   const lower = filePath.toLowerCase();
   const segments = filePath.split("/");
-  if (hasExcludedSuffix(language, lower) || TEST_FILE_PATTERNS[language]?.test(lower) === true || EXCLUDED_CODE_SEGMENTS[language].some((segment) => segments.includes(segment))) {
+  const delimited = `/${filePath}/`;
+  if (hasExcludedSuffix(language, lower) || TEST_FILE_PATTERNS[language]?.test(lower) === true || EXCLUDED_CODE_SEGMENTS[language].some((run) => delimited.includes(`/${run}/`))) {
     return true;
   }
   if (segments.some((segment) => ["generated", "gen", ".dart_tool", "build"].includes(segment.toLowerCase()))) {
@@ -182091,7 +181942,6 @@ function readFileOrUndefined(path) {
 }
 
 // src/setup/init-plan.ts
-var CONFIG_FILE_NAME2 = "docbridge.config.json";
 var INIT_SKILL_NAMES = ["docbridge"];
 var LEGACY_SKILL_NAMES = [
   "docbridge-adopt",
@@ -182259,7 +182109,7 @@ function planConfigOperations(input) {
   return [
     {
       action,
-      path: CONFIG_FILE_NAME2,
+      path: CONFIG_FILE_NAME,
       content,
       reason: "Create docbridge.config.json from discovered scope."
     }
@@ -182411,7 +182261,7 @@ function resolveInitWithAgentTarget(discovery, options) {
   return { target: discovery.agent.defaultTarget, error: undefined };
 }
 function readExistingConfig(projectRoot) {
-  const configPath = join12(projectRoot, CONFIG_FILE_NAME2);
+  const configPath = join12(projectRoot, CONFIG_FILE_NAME);
   let rawText;
   try {
     rawText = readFileSync7(configPath, "utf8");
@@ -182489,7 +182339,7 @@ function parseInitOptions(args, command) {
     if (arg === "--root") {
       const root = args[index + 1];
       if (root === undefined) {
-        throw new InitCliError("--root requires a path.", rootPathGuidance(command));
+        throw new CliError("--root requires a path.", rootPathGuidance(command));
       }
       options.root = root;
       index += 1;
@@ -182498,22 +182348,22 @@ function parseInitOptions(args, command) {
     if (arg === "--agent-target") {
       const target = args[index + 1];
       if (target === undefined) {
-        throw new InitCliError("--agent-target requires a value.", agentTargetGuidance(command));
+        throw new CliError("--agent-target requires a value.", agentTargetGuidance(command));
       }
       if (!AGENT_TARGETS.has(target)) {
-        throw new InitCliError(`Unknown agent target: ${target}. Supported values: codex, claude, both${command === "init" ? ", none" : ""}.`, agentTargetGuidance(command));
+        throw new CliError(`Unknown agent target: ${target}. Supported values: codex, claude, both${command === "init" ? ", none" : ""}.`, agentTargetGuidance(command));
       }
       if (command === "init-with-agent" && target === "none") {
-        throw new InitCliError("init-with-agent requires an agent target other than none.", agentTargetGuidance(command));
+        throw new CliError("init-with-agent requires an agent target other than none.", agentTargetGuidance(command));
       }
       options.agentTarget = target;
       index += 1;
       continue;
     }
     if (arg.startsWith("--")) {
-      throw new InitCliError(`Unknown option: ${arg}`, commandHelpGuidance(command));
+      throw new CliError(`Unknown option: ${arg}`, commandHelpGuidance(command));
     }
-    throw new InitCliError(`Unexpected argument: ${arg}`, commandHelpGuidance(command));
+    throw new CliError(`Unexpected argument: ${arg}`, commandHelpGuidance(command));
   }
   return options;
 }
@@ -182600,19 +182450,19 @@ function resolveConfirmedScope(input) {
     };
   }
   if (!input.prompts.isInteractive) {
-    throw new InitCliError("Interactive setup requires a TTY. Re-run with --yes for non-interactive mode.");
+    throw new CliError("Interactive setup requires a TTY. Re-run with --yes for non-interactive mode.");
   }
   if (input.discovery.docs.ambiguous) {
     const choices = input.discovery.docs.candidates.map((candidate) => candidate.pattern);
     if (choices.length === 0) {
-      throw new InitCliError("Docs scope is ambiguous and no candidates were detected. Create docbridge.config.json manually.");
+      throw new CliError("Docs scope is ambiguous and no candidates were detected. Create docbridge.config.json manually.");
     }
     const docsPattern2 = input.prompts.select("Choose docs scope:", choices, choices[0] ?? "");
     const languages2 = selectLanguages(input.discovery.code.languages, input.prompts);
     return { docsPattern: docsPattern2, languages: languages2 };
   }
   if (input.discovery.docs.recommended === undefined) {
-    throw new InitCliError("Docs scope could not be determined.");
+    throw new CliError("Docs scope could not be determined.");
   }
   let docsPattern = input.discovery.docs.recommended.pattern;
   if (!input.prompts.confirm(`Use docs scope ${docsPattern}?`, true)) {
@@ -182646,7 +182496,7 @@ function selectLanguages(languages, prompts) {
     }
   }
   if (selected.length === 0) {
-    throw new InitCliError("At least one supported code language must remain in scope.");
+    throw new CliError("At least one supported code language must remain in scope.");
   }
   return selected;
 }
@@ -182676,10 +182526,10 @@ function resolveProjectRoot(root, command) {
   try {
     stats = statSync4(projectRoot);
   } catch {
-    throw new InitCliError(`Root path does not exist: ${root}`, rootPathGuidance(command));
+    throw new CliError(`Root path does not exist: ${root}`, rootPathGuidance(command));
   }
   if (!stats.isDirectory()) {
-    throw new InitCliError(`Root path is not a directory: ${root}`, rootPathGuidance(command));
+    throw new CliError(`Root path is not a directory: ${root}`, rootPathGuidance(command));
   }
   return projectRoot;
 }
@@ -182955,8 +182805,7 @@ function planUpgrade(input) {
     pending,
     messages,
     nextSteps: buildNextSteps({ mode, cli, options: input.options, pending }),
-    requiresConfirmation: mode === "apply" && !input.options.dryRun && !input.options.yes && operations.some((operation) => operation.action === "overwrite" || operation.action === "remove"),
-    exitCode: 0
+    requiresConfirmation: mode === "apply" && !input.options.dryRun && !input.options.yes && operations.some((operation) => operation.action === "overwrite" || operation.action === "remove")
   };
 }
 function planOperations(input) {
@@ -183139,7 +182988,7 @@ function runUpgrade(options, io, initRuntime, runtime) {
   });
   if (plan.mode === "check" || options.dryRun) {
     io.stdout(formatUpgradePlan(plan));
-    return plan.exitCode;
+    return 0;
   }
   return applyUpgrade(projectRoot, packageRoot, plan, io, initRuntime);
 }
@@ -183157,7 +183006,7 @@ function applyUpgrade(projectRoot, packageRoot, plan, io, initRuntime) {
     applySkillOperation(projectRoot, packageRoot, operation);
   }
   io.stdout(formatUpgradePlan(plan));
-  return plan.exitCode;
+  return 0;
 }
 function parseAgentTarget(value) {
   if (value === undefined) {
@@ -183182,6 +183031,31 @@ function resolveProjectRoot2(root) {
   return projectRoot;
 }
 
+// src/cli/worker-signals.ts
+async function killingWorkersOnSignal(scan) {
+  const signals = process.platform === "win32" ? ["SIGINT", "SIGTERM"] : ["SIGINT", "SIGTERM", "SIGHUP"];
+  const handlers = new Map;
+  const remove = () => {
+    for (const [signal, handler] of handlers) {
+      process.off(signal, handler);
+    }
+  };
+  for (const signal of signals) {
+    const handler = () => {
+      killRunningWorkers();
+      remove();
+      process.kill(process.pid, signal);
+    };
+    handlers.set(signal, handler);
+    process.on(signal, handler);
+  }
+  try {
+    return await scan();
+  } finally {
+    remove();
+  }
+}
+
 // src/cli/index.ts
 var VERSION = package_default.version;
 function parseCheckOptions(args) {
@@ -183209,9 +183083,9 @@ function resolveProjectRoot3(root, command) {
   }
   return projectRoot;
 }
-function runCheck(options, io) {
+async function runCheck(options, io) {
   const projectRoot = resolveProjectRoot3(options.root, "check");
-  const result = check({ projectRoot, audit: options.audit });
+  const result = await killingWorkersOnSignal(() => check({ projectRoot, audit: options.audit }));
   if (options.json) {
     io.stdout(`${JSON.stringify(result, null, 2)}
 `);
@@ -183232,7 +183106,7 @@ See \`docbridge docs show troubleshooting\` for diagnostic codes and fixes.
   }
   return result.summary.errors > 0 ? 1 : 0;
 }
-function runFileCommand(command, options, io, execute, render) {
+async function runFileCommand(command, options, io, execute, render) {
   const projectRoot = resolveProjectRoot3(options.root, command);
   const inputFiles = [...options.files];
   if (options.stdin) {
@@ -183240,7 +183114,7 @@ function runFileCommand(command, options, io, execute, render) {
     inputFiles.push(...readStdin().split(`
 `));
   }
-  const outcome = execute(projectRoot, inputFiles);
+  const outcome = await killingWorkersOnSignal(async () => execute(projectRoot, inputFiles));
   if (!outcome.ok) {
     throw new DiagnosticOutputError(outcome.diagnostics.map(formatDiagnostic).join(`
 `));
@@ -183261,7 +183135,7 @@ function writeStructuredResult(result, options) {
 `);
   }
 }
-function runRelated(options, io) {
+async function runRelated(options, io) {
   if (!options.stdin && options.files.length === 0) {
     throw new CliError("No input files were provided.", missingInputGuidance("related"));
   }
@@ -183290,7 +183164,7 @@ function runRelated(options, io) {
     return 0;
   });
 }
-function runContext(options, io) {
+async function runContext(options, io) {
   if (!options.stdin && options.files.length === 0) {
     throw new CliError("No input files were provided.", missingInputGuidance("context"));
   }
@@ -183304,7 +183178,7 @@ function runContext(options, io) {
     return 0;
   });
 }
-function runGraph(options, io) {
+async function runGraph(options, io) {
   return runFileCommand("graph", options, io, (projectRoot, inputFiles) => graph({ projectRoot, inputFiles, includeContent: options.includeContent }), (result, projectRoot, inputFiles) => {
     const normalizedInputFiles = normalizeChangedPaths(projectRoot, inputFiles);
     writeStructuredResult(result, {
@@ -183358,7 +183232,7 @@ var COMMAND_HANDLERS = {
     return 0;
   }
 };
-function run(argv, io = {
+async function run(argv, io = {
   stdout: (text) => process.stdout.write(text),
   stderr: (text) => process.stderr.write(text)
 }, initRuntime = { prompts: createDefaultPrompts() }, cliRuntime = {}) {
@@ -183380,7 +183254,7 @@ function run(argv, io = {
       return 0;
     }
     if (isSubcommand(command)) {
-      const exitCode = COMMAND_HANDLERS[command](rest, io, initRuntime, cliRuntime);
+      const exitCode = await COMMAND_HANDLERS[command](rest, io, initRuntime, cliRuntime);
       writeUpdateNotice(argv, io, initRuntime, cliRuntime);
       return exitCode;
     }
@@ -183445,7 +183319,7 @@ if (__require.main == __require.module) {
   const argv = process.argv.slice(2);
   const isTty = process.stderr.isTTY === true;
   const latest = await resolveLatestForInvocation(argv, process.env, isTty);
-  process.exitCode = run(argv, {
+  process.exitCode = await run(argv, {
     stdout: (text) => process.stdout.write(text),
     stderr: (text) => process.stderr.write(text)
   }, { prompts: createDefaultPrompts() }, { ...latest !== undefined ? { latest } : {}, env: process.env, isTty });