docbridge 0.11.0 → 0.13.0

package/dist/index.js

@@ -169132,11 +169132,11 @@ var require_codegen = __commonJS((exports) => {
       const rhs = this.rhs === undefined ? "" : ` = ${this.rhs}`;
       return `${varKind} ${this.name}${rhs};` + _n;
     }
-    optimizeNames(names, constants2) {
+    optimizeNames(names, constants) {
       if (!names[this.name.str])
         return;
       if (this.rhs)
-        this.rhs = optimizeExpr(this.rhs, names, constants2);
+        this.rhs = optimizeExpr(this.rhs, names, constants);
       return this;
     }
     get names() {
@@ -169154,10 +169154,10 @@ var require_codegen = __commonJS((exports) => {
     render({ _n }) {
       return `${this.lhs} = ${this.rhs};` + _n;
     }
-    optimizeNames(names, constants2) {
+    optimizeNames(names, constants) {
       if (this.lhs instanceof code_1.Name && !names[this.lhs.str] && !this.sideEffects)
         return;
-      this.rhs = optimizeExpr(this.rhs, names, constants2);
+      this.rhs = optimizeExpr(this.rhs, names, constants);
       return this;
     }
     get names() {
@@ -169223,8 +169223,8 @@ var require_codegen = __commonJS((exports) => {
     optimizeNodes() {
       return `${this.code}` ? this : undefined;
     }
-    optimizeNames(names, constants2) {
-      this.code = optimizeExpr(this.code, names, constants2);
+    optimizeNames(names, constants) {
+      this.code = optimizeExpr(this.code, names, constants);
       return this;
     }
     get names() {
@@ -169254,12 +169254,12 @@ var require_codegen = __commonJS((exports) => {
       }
       return nodes.length > 0 ? this : undefined;
     }
-    optimizeNames(names, constants2) {
+    optimizeNames(names, constants) {
       const { nodes } = this;
       let i = nodes.length;
       while (i--) {
         const n = nodes[i];
-        if (n.optimizeNames(names, constants2))
+        if (n.optimizeNames(names, constants))
           continue;
         subtractNames(names, n.names);
         nodes.splice(i, 1);
@@ -169316,12 +169316,12 @@ var require_codegen = __commonJS((exports) => {
         return;
       return this;
     }
-    optimizeNames(names, constants2) {
+    optimizeNames(names, constants) {
       var _a;
-      this.else = (_a = this.else) === null || _a === undefined ? undefined : _a.optimizeNames(names, constants2);
-      if (!(super.optimizeNames(names, constants2) || this.else))
+      this.else = (_a = this.else) === null || _a === undefined ? undefined : _a.optimizeNames(names, constants);
+      if (!(super.optimizeNames(names, constants) || this.else))
         return;
-      this.condition = optimizeExpr(this.condition, names, constants2);
+      this.condition = optimizeExpr(this.condition, names, constants);
       return this;
     }
     get names() {
@@ -169346,10 +169346,10 @@ var require_codegen = __commonJS((exports) => {
     render(opts) {
       return `for(${this.iteration})` + super.render(opts);
     }
-    optimizeNames(names, constants2) {
-      if (!super.optimizeNames(names, constants2))
+    optimizeNames(names, constants) {
+      if (!super.optimizeNames(names, constants))
         return;
-      this.iteration = optimizeExpr(this.iteration, names, constants2);
+      this.iteration = optimizeExpr(this.iteration, names, constants);
       return this;
     }
     get names() {
@@ -169387,10 +169387,10 @@ var require_codegen = __commonJS((exports) => {
     render(opts) {
       return `for(${this.varKind} ${this.name} ${this.loop} ${this.iterable})` + super.render(opts);
     }
-    optimizeNames(names, constants2) {
-      if (!super.optimizeNames(names, constants2))
+    optimizeNames(names, constants) {
+      if (!super.optimizeNames(names, constants))
         return;
-      this.iterable = optimizeExpr(this.iterable, names, constants2);
+      this.iterable = optimizeExpr(this.iterable, names, constants);
       return this;
     }
     get names() {
@@ -169435,11 +169435,11 @@ var require_codegen = __commonJS((exports) => {
       (_b = this.finally) === null || _b === undefined || _b.optimizeNodes();
       return this;
     }
-    optimizeNames(names, constants2) {
+    optimizeNames(names, constants) {
       var _a, _b;
-      super.optimizeNames(names, constants2);
-      (_a = this.catch) === null || _a === undefined || _a.optimizeNames(names, constants2);
-      (_b = this.finally) === null || _b === undefined || _b.optimizeNames(names, constants2);
+      super.optimizeNames(names, constants);
+      (_a = this.catch) === null || _a === undefined || _a.optimizeNames(names, constants);
+      (_b = this.finally) === null || _b === undefined || _b.optimizeNames(names, constants);
       return this;
     }
     get names() {
@@ -169713,7 +169713,7 @@ var require_codegen = __commonJS((exports) => {
   function addExprNames(names, from) {
     return from instanceof code_1._CodeOrName ? addNames(names, from.names) : names;
   }
-  function optimizeExpr(expr, names, constants2) {
+  function optimizeExpr(expr, names, constants) {
     if (expr instanceof code_1.Name)
       return replaceName(expr);
     if (!canOptimize(expr))
@@ -169728,14 +169728,14 @@ var require_codegen = __commonJS((exports) => {
       return items;
     }, []));
     function replaceName(n) {
-      const c = constants2[n.str];
+      const c = constants[n.str];
       if (c === undefined || names[n.str] !== 1)
         return n;
       delete names[n.str];
       return c;
     }
     function canOptimize(e) {
-      return e instanceof code_1._Code && e._items.some((c) => c instanceof code_1.Name && names[c.str] === 1 && constants2[c.str] !== undefined);
+      return e instanceof code_1._Code && e._items.some((c) => c instanceof code_1.Name && names[c.str] === 1 && constants[c.str] !== undefined);
     }
   }
   function subtractNames(names, from) {
@@ -170197,8 +170197,8 @@ var require_dataType = __commonJS((exports) => {
     return types;
   }
   exports.getSchemaTypes = getSchemaTypes;
-  function getJSONTypes(ts2) {
-    const types = Array.isArray(ts2) ? ts2 : ts2 ? [ts2] : [];
+  function getJSONTypes(ts3) {
+    const types = Array.isArray(ts3) ? ts3 : ts3 ? [ts3] : [];
     if (types.every(rules_1.isJSONType))
       return types;
     throw new Error("type must be JSONType or JSONType[]: " + types.join(","));
@@ -171223,18 +171223,18 @@ var require_validate = __commonJS((exports) => {
     });
     narrowSchemaTypes(it, types);
   }
-  function checkMultipleTypes(it, ts2) {
-    if (ts2.length > 1 && !(ts2.length === 2 && ts2.includes("null"))) {
+  function checkMultipleTypes(it, ts3) {
+    if (ts3.length > 1 && !(ts3.length === 2 && ts3.includes("null"))) {
       strictTypesError(it, "use allowUnionTypes to allow union type keyword");
     }
   }
-  function checkKeywordTypes(it, ts2) {
+  function checkKeywordTypes(it, ts3) {
     const rules = it.self.RULES.all;
     for (const keyword in rules) {
       const rule = rules[keyword];
       if (typeof rule == "object" && (0, applicability_1.shouldUseRule)(it.schema, rule)) {
         const { type } = rule.definition;
-        if (type.length && !type.some((t) => hasApplicableType(ts2, t))) {
+        if (type.length && !type.some((t) => hasApplicableType(ts3, t))) {
           strictTypesError(it, `missing type "${type.join(",")}" for keyword "${keyword}"`);
         }
       }
@@ -171243,18 +171243,18 @@ var require_validate = __commonJS((exports) => {
   function hasApplicableType(schTs, kwdT) {
     return schTs.includes(kwdT) || kwdT === "number" && schTs.includes("integer");
   }
-  function includesType(ts2, t) {
-    return ts2.includes(t) || t === "integer" && ts2.includes("number");
+  function includesType(ts3, t) {
+    return ts3.includes(t) || t === "integer" && ts3.includes("number");
   }
   function narrowSchemaTypes(it, withTypes) {
-    const ts2 = [];
+    const ts3 = [];
     for (const t of it.dataTypes) {
       if (includesType(withTypes, t))
-        ts2.push(t);
+        ts3.push(t);
       else if (withTypes.includes("integer") && t === "number")
-        ts2.push("integer");
+        ts3.push("integer");
     }
-    it.dataTypes = ts2;
+    it.dataTypes = ts3;
   }
   function strictTypesError(it, msg) {
     const schemaPath = it.schemaEnv.baseId + it.errSchemaPath;
@@ -175576,12 +175576,12 @@ var require_2020 = __commonJS((exports, module) => {
 });
 
 // src/cli/index.ts
-import { existsSync as existsSync6, readFileSync as readFileSync9, statSync as statSync5 } from "node:fs";
-import { join as join14, resolve as resolve4 } from "node:path";
+import { existsSync as existsSync7, readFileSync as readFileSync9, statSync as statSync6 } from "node:fs";
+import { join as join15, resolve as resolve5 } from "node:path";
 // package.json
 var package_default = {
   name: "docbridge",
-  version: "0.11.0",
+  version: "0.13.0",
   description: "A CLI that links Markdown specifications and code declarations. Runs on Node.js and Bun.",
   keywords: [
     "bun",
@@ -175716,15 +175716,8 @@ function collectFiles(projectRoot, patterns) {
       if (!stat.isFile()) {
         continue;
       }
-      for (const pattern of patterns) {
-        if (!matchGlob(pattern, relPath)) {
-          continue;
-        }
-        if (isCodePattern(pattern) && relPath.endsWith(".d.ts")) {
-          continue;
-        }
+      if (patterns.some((pattern) => matchGlob(pattern, relPath))) {
         matched.add(relPath);
-        break;
       }
     }
   };
@@ -175748,9 +175741,6 @@ function readManagedFile(projectRoot, relativePath) {
     };
   }
 }
-function isCodePattern(pattern) {
-  return pattern.endsWith(".ts");
-}
 function globToRegExp(pattern) {
   const segments = pattern.split("/");
   const parts = [];
@@ -175788,11 +175778,49 @@ var KNOWN_CODE_LANGUAGES = [
   "swift",
   "dart",
   "rust",
-  "go"
+  "go",
+  "javascript",
+  "python",
+  "ruby",
+  "java"
 ];
 function isCodeLanguage(value) {
   return KNOWN_CODE_LANGUAGES.includes(value);
 }
+var LANGUAGE_SUFFIXES = {
+  typescript: [".ts", ".tsx", ".mts", ".cts"],
+  swift: [".swift"],
+  dart: [".dart"],
+  rust: [".rs"],
+  go: [".go"],
+  javascript: [".js", ".jsx", ".mjs", ".cjs"],
+  python: [".py"],
+  ruby: [".rb"],
+  java: [".java"]
+};
+var EXCLUDED_SUFFIXES = {
+  typescript: [".d.ts", ".d.mts", ".d.cts"],
+  swift: [],
+  dart: [],
+  rust: [],
+  go: [],
+  javascript: [],
+  python: [],
+  ruby: [],
+  java: []
+};
+function codeFenceLanguage(language, filePath) {
+  if (language === "typescript") {
+    return filePath.endsWith(".tsx") ? "tsx" : "ts";
+  }
+  if (language === "javascript") {
+    return filePath.endsWith(".jsx") ? "jsx" : "js";
+  }
+  return language;
+}
+function hasExcludedSuffix(language, relPath) {
+  return EXCLUDED_SUFFIXES[language].some((suffix) => relPath.endsWith(suffix));
+}
 function collectCodeFiles(projectRoot, codeInclude) {
   const collected = [];
   const seen = new Set;
@@ -175801,7 +175829,7 @@ function collectCodeFiles(projectRoot, codeInclude) {
     if (entry === undefined) {
       continue;
     }
-    for (const relPath of collectFiles(projectRoot, entry.patterns)) {
+    for (const relPath of collectLanguageFiles(projectRoot, language, entry.patterns)) {
       if (seen.has(relPath)) {
         continue;
       }
@@ -175819,7 +175847,7 @@ function codeFileOwners(projectRoot, codeInclude) {
     if (entry === undefined) {
       continue;
     }
-    for (const relPath of collectFiles(projectRoot, entry.patterns)) {
+    for (const relPath of collectLanguageFiles(projectRoot, language, entry.patterns)) {
       const existing = owners.get(relPath);
       if (existing === undefined) {
         owners.set(relPath, [language]);
@@ -175830,28 +175858,77 @@ function codeFileOwners(projectRoot, codeInclude) {
   }
   return owners;
 }
+function collectLanguageFiles(projectRoot, language, patterns) {
+  return collectFiles(projectRoot, patterns).filter((relPath) => !hasExcludedSuffix(language, relPath));
+}
+
+// src/config/scanner-runtimes.ts
+var RUNTIME_WORKER_LANGUAGES = ["python", "ruby", "java"];
+var KNOWN_RUNTIME_ENTRY_KEYS = new Set(["command"]);
+function validateScannerRuntimes(value, diagnostics) {
+  if (!isPlainObject(value)) {
+    diagnostics.push(configDiagnostic("config_invalid_value", "scanners", "`scanners` must be an object keyed by runtime-backed language."));
+    return {};
+  }
+  const result = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (!isRuntimeWorkerLanguage(key)) {
+      diagnostics.push(configDiagnostic("config_unknown_key", `scanners.${key}`, `Unknown scanner runtime: ${key}. Supported runtimes: ${RUNTIME_WORKER_LANGUAGES.join(", ")}.`));
+      continue;
+    }
+    const command = validateRuntimeEntry(key, entry, diagnostics);
+    if (command !== undefined) {
+      result[key] = { command };
+    }
+  }
+  return result;
+}
+function validateRuntimeEntry(language, value, diagnostics) {
+  const target = `scanners.${language}`;
+  if (!isPlainObject(value)) {
+    diagnostics.push(configDiagnostic("config_invalid_value", target, `\`${target}\` must be an object with a \`command\` array.`));
+    return;
+  }
+  for (const key of Object.keys(value)) {
+    if (!KNOWN_RUNTIME_ENTRY_KEYS.has(key)) {
+      diagnostics.push(configDiagnostic("config_unknown_key", `${target}.${key}`, `Unknown configuration key under \`${target}\`: ${key}`));
+    }
+  }
+  const command = value.command;
+  if (!Array.isArray(command) || command.length === 0 || !command.every((part) => typeof part === "string" && part !== "")) {
+    diagnostics.push(configDiagnostic("config_invalid_value", `${target}.command`, `\`${target}.command\` must be a non-empty array of non-empty strings: the runtime executable followed by its arguments.`));
+    return;
+  }
+  return command;
+}
+function isRuntimeWorkerLanguage(value) {
+  return RUNTIME_WORKER_LANGUAGES.includes(value);
+}
+function configDiagnostic(code, target, message) {
+  return { severity: "error", code, target, message };
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 
 // src/config/config.ts
 var CONFIG_FILE_NAME = "docbridge.config.json";
 var EMPTY_CONFIG = {
   include: { code: {}, docs: [] }
 };
-var KNOWN_TOP_LEVEL_KEYS = new Set(["$schema", "include"]);
+var KNOWN_TOP_LEVEL_KEYS = new Set(["$schema", "include", "scanners"]);
 var KNOWN_INCLUDE_KEYS = new Set(["code", "docs"]);
 var KNOWN_CODE_ENTRY_KEYS = new Set(["patterns", "visibility"]);
-var LANGUAGE_SUFFIX = {
-  typescript: ".ts",
-  swift: ".swift",
-  dart: ".dart",
-  rust: ".rs",
-  go: ".go"
-};
 var LANGUAGE_VISIBILITY = {
   typescript: ["public", "protected", "private"],
   swift: ["public", "open", "internal"],
   dart: ["public"],
   rust: ["pub", "private"],
-  go: ["exported", "unexported"]
+  go: ["exported", "unexported"],
+  javascript: ["public", "protected", "private"],
+  python: ["public", "private"],
+  ruby: ["public", "protected", "private"],
+  java: ["public", "protected", "package", "private"]
 };
 function loadConfig(projectRoot) {
   let rawText;
@@ -175880,7 +175957,7 @@ function resolveConfig(rawText) {
       config: EMPTY_CONFIG,
       ok: false,
       diagnostics: [
-        configDiagnostic("config_file_invalid", CONFIG_FILE_NAME, `${CONFIG_FILE_NAME} was not found. DocBridge requires a configuration file.`)
+        configDiagnostic2("config_file_invalid", CONFIG_FILE_NAME, `${CONFIG_FILE_NAME} was not found. DocBridge requires a configuration file.`)
       ]
     };
   }
@@ -175893,57 +175970,61 @@ function resolveConfig(rawText) {
       config: EMPTY_CONFIG,
       ok: false,
       diagnostics: [
-        configDiagnostic("config_file_invalid", CONFIG_FILE_NAME, `Failed to parse ${CONFIG_FILE_NAME}: ${reason}`)
+        configDiagnostic2("config_file_invalid", CONFIG_FILE_NAME, `Failed to parse ${CONFIG_FILE_NAME}: ${reason}`)
       ]
     };
   }
   const diagnostics = [];
-  if (!isPlainObject(parsed)) {
-    diagnostics.push(configDiagnostic("config_invalid_value", CONFIG_FILE_NAME, "Configuration must be a JSON object."));
+  if (!isPlainObject2(parsed)) {
+    diagnostics.push(configDiagnostic2("config_invalid_value", CONFIG_FILE_NAME, "Configuration must be a JSON object."));
     return { config: EMPTY_CONFIG, diagnostics, ok: false };
   }
   for (const key of Object.keys(parsed)) {
     if (!KNOWN_TOP_LEVEL_KEYS.has(key)) {
-      diagnostics.push(configDiagnostic("config_unknown_key", key, `Unknown top-level configuration key: ${key}`));
+      diagnostics.push(configDiagnostic2("config_unknown_key", key, `Unknown top-level configuration key: ${key}`));
     }
   }
   if ("$schema" in parsed && typeof parsed.$schema !== "string") {
-    diagnostics.push(configDiagnostic("config_invalid_value", "$schema", "`$schema` must be a string."));
+    diagnostics.push(configDiagnostic2("config_invalid_value", "$schema", "`$schema` must be a string."));
   }
+  const scanners = "scanners" in parsed ? validateScannerRuntimes(parsed.scanners, diagnostics) : undefined;
   const include = parsed.include;
-  if (!isPlainObject(include)) {
-    diagnostics.push(configDiagnostic("config_invalid_value", "include", "`include` must be an object with `code` and `docs`."));
+  if (!isPlainObject2(include)) {
+    diagnostics.push(configDiagnostic2("config_invalid_value", "include", "`include` must be an object with `code` and `docs`."));
     return { config: EMPTY_CONFIG, diagnostics, ok: false };
   }
   for (const key of Object.keys(include)) {
     if (!KNOWN_INCLUDE_KEYS.has(key)) {
-      diagnostics.push(configDiagnostic("config_unknown_key", `include.${key}`, `Unknown configuration key under \`include\`: ${key}`));
+      diagnostics.push(configDiagnostic2("config_unknown_key", `include.${key}`, `Unknown configuration key under \`include\`: ${key}`));
     }
   }
   const code = validateCodeInclude(include.code, diagnostics);
-  validatePatternArray(include.docs, "docs", ".md", false, diagnostics);
+  validatePatternArray(include.docs, "docs", [".md"], [], diagnostics);
   const ok = diagnostics.length === 0;
-  const config = ok ? { include: { code, docs: include.docs } } : EMPTY_CONFIG;
+  const config = ok ? {
+    include: { code, docs: include.docs },
+    ...scanners === undefined ? {} : { scanners }
+  } : EMPTY_CONFIG;
   return { config, diagnostics, ok };
 }
 function validateCodeInclude(value, diagnostics) {
   if (Array.isArray(value)) {
-    diagnostics.push(configDiagnostic("config_invalid_value", "include.code", '`include.code` must be a language-keyed object such as `{ "typescript": { "patterns": ["src/**/*.ts"] } }`, not an array.'));
+    diagnostics.push(configDiagnostic2("config_invalid_value", "include.code", '`include.code` must be a language-keyed object such as `{ "typescript": { "patterns": ["src/**/*.ts"] } }`, not an array.'));
     return {};
   }
-  if (!isPlainObject(value)) {
-    diagnostics.push(configDiagnostic("config_invalid_value", "include.code", "`include.code` must be a language-keyed object."));
+  if (!isPlainObject2(value)) {
+    diagnostics.push(configDiagnostic2("config_invalid_value", "include.code", "`include.code` must be a language-keyed object."));
     return {};
   }
   const keys = Object.keys(value);
   if (keys.length === 0) {
-    diagnostics.push(configDiagnostic("config_invalid_value", "include.code", "`include.code` must configure at least one language."));
+    diagnostics.push(configDiagnostic2("config_invalid_value", "include.code", "`include.code` must configure at least one language."));
     return {};
   }
   const result = {};
   for (const key of keys) {
     if (!isCodeLanguage(key)) {
-      diagnostics.push(configDiagnostic("config_invalid_value", `include.code.${key}`, `Unknown code language: ${key}. Supported languages: ${KNOWN_CODE_LANGUAGES.join(", ")}.`));
+      diagnostics.push(configDiagnostic2("config_invalid_value", `include.code.${key}`, `Unknown code language: ${key}. Supported languages: ${KNOWN_CODE_LANGUAGES.join(", ")}.`));
       continue;
     }
     const entry = validateCodeEntry(key, value[key], diagnostics);
@@ -175955,20 +176036,20 @@ function validateCodeInclude(value, diagnostics) {
 }
 function validateCodeEntry(language, value, diagnostics) {
   const target = `include.code.${language}`;
-  if (!isPlainObject(value)) {
-    diagnostics.push(configDiagnostic("config_invalid_value", target, `\`${target}\` must be an object with a \`patterns\` array. Shorthand arrays are not supported.`));
+  if (!isPlainObject2(value)) {
+    diagnostics.push(configDiagnostic2("config_invalid_value", target, `\`${target}\` must be an object with a \`patterns\` array. Shorthand arrays are not supported.`));
     return;
   }
   for (const key of Object.keys(value)) {
     if (!KNOWN_CODE_ENTRY_KEYS.has(key)) {
-      diagnostics.push(configDiagnostic("config_unknown_key", `${target}.${key}`, `Unknown configuration key under \`${target}\`: ${key}`));
+      diagnostics.push(configDiagnostic2("config_unknown_key", `${target}.${key}`, `Unknown configuration key under \`${target}\`: ${key}`));
     }
   }
   const before = diagnostics.length;
-  validatePatternArray(value.patterns, `code.${language}.patterns`, LANGUAGE_SUFFIX[language], language === "typescript", diagnostics);
+  validatePatternArray(value.patterns, `code.${language}.patterns`, LANGUAGE_SUFFIXES[language], EXCLUDED_SUFFIXES[language], diagnostics);
   if ("visibility" in value) {
     if (!isStringArray(value.visibility)) {
-      diagnostics.push(configDiagnostic("config_invalid_value", `${target}.visibility`, `\`${target}.visibility\` must be an array of strings.`));
+      diagnostics.push(configDiagnostic2("config_invalid_value", `${target}.visibility`, `\`${target}.visibility\` must be an array of strings.`));
     } else {
       validateVisibilityOptions(language, value.visibility, target, diagnostics);
     }
@@ -175985,47 +176066,49 @@ function validateCodeEntry(language, value, diagnostics) {
 function validateVisibilityOptions(language, values, target, diagnostics) {
   const allowed = LANGUAGE_VISIBILITY[language];
   if (allowed.length === 0) {
-    diagnostics.push(configDiagnostic("config_invalid_value", `${target}.visibility`, `\`${target}.visibility\` is not supported for ${language}.`));
+    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(configDiagnostic("config_invalid_value", `${target}.visibility`, `Unsupported ${language} visibility: ${value}. Supported values: ${allowed.join(", ")}.`));
+      diagnostics.push(configDiagnostic2("config_invalid_value", `${target}.visibility`, `Unsupported ${language} visibility: ${value}. Supported values: ${allowed.join(", ")}.`));
     }
   }
 }
-function validatePatternArray(value, field, requiredSuffix, excludeDeclarationFiles, diagnostics) {
+function validatePatternArray(value, field, suffixes, excludedSuffixes, diagnostics) {
   const target = `include.${field}`;
   if (!Array.isArray(value)) {
-    diagnostics.push(configDiagnostic("config_invalid_value", target, `\`${target}\` must be a non-empty array of strings.`));
+    diagnostics.push(configDiagnostic2("config_invalid_value", target, `\`${target}\` must be a non-empty array of strings.`));
     return;
   }
   if (value.length === 0) {
-    diagnostics.push(configDiagnostic("config_invalid_value", target, `\`${target}\` must contain at least one pattern.`));
+    diagnostics.push(configDiagnostic2("config_invalid_value", target, `\`${target}\` must contain at least one pattern.`));
     return;
   }
   for (const pattern of value) {
     if (typeof pattern !== "string") {
-      diagnostics.push(configDiagnostic("config_invalid_value", target, `\`${target}\` patterns must be strings.`));
+      diagnostics.push(configDiagnostic2("config_invalid_value", target, `\`${target}\` patterns must be strings.`));
       continue;
     }
     const globResult = validateGlobPattern(pattern);
     if (!globResult.ok) {
-      diagnostics.push(configDiagnostic("config_invalid_value", pattern, `Invalid pattern in \`${target}\`: ${globResult.message}`));
+      diagnostics.push(configDiagnostic2("config_invalid_value", pattern, `Invalid pattern in \`${target}\`: ${globResult.message}`));
       continue;
     }
-    const suffixError = checkSuffix(pattern, requiredSuffix, excludeDeclarationFiles);
+    const suffixError = checkPatternSuffix(pattern, suffixes, excludedSuffixes);
     if (suffixError !== undefined) {
-      diagnostics.push(configDiagnostic("config_invalid_value", pattern, suffixError));
+      diagnostics.push(configDiagnostic2("config_invalid_value", pattern, suffixError));
     }
   }
 }
-function checkSuffix(pattern, requiredSuffix, excludeDeclarationFiles) {
-  if (!pattern.endsWith(requiredSuffix)) {
-    return `Pattern must end with \`${requiredSuffix}\`.`;
+function checkPatternSuffix(pattern, suffixes, excludedSuffixes) {
+  if (!suffixes.some((suffix) => pattern.endsWith(suffix))) {
+    const listed = suffixes.map((suffix) => `\`${suffix}\``).join(", ");
+    return suffixes.length === 1 ? `Pattern must end with ${listed}.` : `Pattern must end with one of ${listed}.`;
   }
-  if (excludeDeclarationFiles && pattern.endsWith(".d.ts")) {
-    return "Pattern must not target `.d.ts` declaration files.";
+  const excluded = excludedSuffixes.find((suffix) => pattern.endsWith(suffix));
+  if (excluded !== undefined) {
+    return `Pattern must not target \`${excluded}\` declaration files.`;
   }
   return;
 }
@@ -176033,15 +176116,15 @@ function detectLanguageOverlap(projectRoot, code) {
   const diagnostics = [];
   for (const [relPath, owners] of codeFileOwners(projectRoot, code)) {
     if (owners.length > 1) {
-      diagnostics.push(configDiagnostic("config_invalid_value", relPath, `Code file ${relPath} matches multiple configured languages (${owners.join(", ")}). Each code file must belong to exactly one language.`));
+      diagnostics.push(configDiagnostic2("config_invalid_value", relPath, `Code file ${relPath} matches multiple configured languages (${owners.join(", ")}). Each code file must belong to exactly one language.`));
     }
   }
   return diagnostics;
 }
-function configDiagnostic(code, target, message) {
+function configDiagnostic2(code, target, message) {
   return { severity: "error", code, target, message };
 }
-function isPlainObject(value) {
+function isPlainObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isStringArray(value) {
@@ -176568,6 +176651,11 @@ function positionOf(range) {
 // src/lsp/server.ts
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
+// src/shared/error.ts
+function reasonOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
 // src/lsp/position.ts
 function toLspPosition(position) {
   return { line: position.line - 1, character: position.column - 1 };
@@ -176951,32 +177039,27 @@ function renderCodeSignatures(state, counterparts) {
     const signature = content === undefined || symbol.signatureRange === undefined ? "" : withoutLeadingComments(sliceSourceRange(content, symbol.signatureRange).content, symbol.language).trimEnd();
     const fenced = signature.length > 0 ? `
 
-\`\`\`${FENCE_LANGUAGE[symbol.language]}
+\`\`\`${codeFenceLanguage(symbol.language, symbol.filePath)}
 ${signature}
 \`\`\`` : "";
     blocks.push(`**${symbol.endpoint}**${fenced}`);
   }
   return blocks.length > 0 ? blocks.join(DIVIDER) : null;
 }
-var FENCE_LANGUAGE = {
-  typescript: "ts",
-  swift: "swift",
-  dart: "dart",
-  rust: "rust",
-  go: "go"
-};
 var NESTED_BLOCK_COMMENTS = new Set(["swift", "dart", "rust"]);
+var HASH_LINE_COMMENTS = new Set(["python", "ruby"]);
 function withoutLeadingComments(text, language) {
+  const lineComment = HASH_LINE_COMMENTS.has(language) ? "#" : "//";
   let index = 0;
   for (;; ) {
     while (index < text.length && /\s/.test(text[index] ?? "")) {
       index += 1;
     }
-    if (text.startsWith("//", index)) {
+    if (text.startsWith(lineComment, index)) {
       const newline = text.indexOf(`
 `, index);
       index = newline === -1 ? text.length : newline + 1;
-    } else if (text.startsWith("/*", index)) {
+    } else if (lineComment === "//" && text.startsWith("/*", index)) {
       index = blockCommentEnd(text, index, NESTED_BLOCK_COMMENTS.has(language));
     } else {
       return text.slice(index);
@@ -177517,24 +177600,205 @@ function manifestLink(source, target, entry, side) {
   };
 }
 
+// src/shared/cancelable.ts
+function deferred() {
+  let settle;
+  const promise = new Promise((resolve2, reject) => {
+    settle = { resolve: resolve2, reject };
+  });
+  return {
+    promise,
+    resolve: (value) => settle?.resolve(value),
+    reject: (error) => settle?.reject(error)
+  };
+}
+function settledCancelable(value) {
+  return { promise: Promise.resolve(value), cancel: () => {
+    return;
+  } };
+}
+function mapCancelable(task, map) {
+  const mapped = deferred();
+  let cancelled = false;
+  task.promise.then((value) => {
+    if (cancelled) {
+      throw abortError();
+    }
+    return map(value);
+  }).then(mapped.resolve, mapped.reject);
+  return {
+    promise: mapped.promise,
+    cancel() {
+      cancelled = true;
+      mapped.reject(abortError());
+      task.cancel();
+    }
+  };
+}
+function abortError() {
+  const error = new Error("The operation was cancelled");
+  error.name = "AbortError";
+  return error;
+}
+function isAbortError(error) {
+  return error instanceof Error && error.name === "AbortError";
+}
+function cancelableSequence(body) {
+  const outcome = deferred();
+  let cancelled = false;
+  let running;
+  const step = async (next) => {
+    if (cancelled) {
+      if (typeof next !== "function") {
+        next.promise.catch(() => {
+          return;
+        });
+        next.cancel();
+      }
+      throw abortError();
+    }
+    const task = typeof next === "function" ? next() : next;
+    running = task;
+    try {
+      return await task.promise;
+    } finally {
+      if (running === task) {
+        running = undefined;
+      }
+    }
+  };
+  (async () => body(step))().then(outcome.resolve, outcome.reject);
+  return {
+    promise: outcome.promise,
+    cancel() {
+      if (cancelled) {
+        return;
+      }
+      cancelled = true;
+      outcome.reject(abortError());
+      running?.cancel();
+    }
+  };
+}
+
+// src/scan/code/scan-cache.ts
+import { createHash } from "node:crypto";
+function emptyCodeScanCache() {
+  return { fingerprint: "", entries: new Map };
+}
+function codeScanCacheKey(language, filePath, content, options, argv, runtime = []) {
+  const contentHash = createHash("sha256").update(content).digest("hex");
+  return JSON.stringify([
+    language,
+    filePath,
+    contentHash,
+    options.visibility ?? null,
+    argv,
+    runtime
+  ]);
+}
+function isReusableScan(scan) {
+  return !scan.diagnostics.some((diagnostic) => diagnostic.code === "code_scanner_unavailable" || diagnostic.code === "code_scanner_failed");
+}
+
 // src/scan/code/typescript.ts
+var import_typescript2 = __toESM(require_typescript(), 1);
+
+// src/scan/code/typescript-diagnostics.ts
 var import_typescript = __toESM(require_typescript(), 1);
-var LANGUAGE = "typescript";
+function scriptLanguage(filePath) {
+  return LANGUAGE_SUFFIXES.javascript.some((suffix) => filePath.endsWith(suffix)) ? "javascript" : "typescript";
+}
+var LABEL = {
+  typescript: "TypeScript",
+  javascript: "JavaScript"
+};
+var SUPPORTED_DECLARATIONS = {
+  typescript: "Supported declarations are top-level exported function, class, interface, type, single-declarator const, enum, and named default function or class, plus the identifier-named members of a class, interface, or object type alias.",
+  javascript: "Supported declarations are top-level ESM-exported function, class, single-declarator const, let, or var, and named default function or class, plus the identifier-named members of a class. CommonJS assignments are not declarations."
+};
+function parseErrorDiagnostic(filePath, sourceFile, diagnostic) {
+  const location = { filePath, line: 1, column: 1 };
+  if (diagnostic !== undefined && diagnostic.start !== undefined && diagnostic.file !== undefined) {
+    const { line, character } = sourceFile.getLineAndCharacterOfPosition(diagnostic.start);
+    location.line = line + 1;
+    location.column = character + 1;
+  }
+  const language = scriptLanguage(filePath);
+  const detail = diagnostic === undefined ? `${LABEL[language]} file has a syntactic parse error.` : import_typescript.default.flattenDiagnosticMessageText(diagnostic.messageText, `
+`);
+  return {
+    severity: "error",
+    code: "code_parse_error",
+    language,
+    target: filePath,
+    message: `${LABEL[language]} parse error: ${detail}`,
+    location
+  };
+}
+function unsupportedDeclarationDiagnostic(filePath, location) {
+  const language = scriptLanguage(filePath);
+  return {
+    severity: "warning",
+    code: "unsupported_declaration",
+    language,
+    target: filePath,
+    message: `@doc is attached to an unsupported declaration. ${SUPPORTED_DECLARATIONS[language]}`,
+    location
+  };
+}
+function duplicateCodeSymbolDiagnostic(endpoint, location, range) {
+  const diagnostic = {
+    severity: "error",
+    code: "duplicate_code_symbol",
+    language: scriptLanguage(location.filePath),
+    target: endpoint,
+    message: `Multiple @doc-annotated declarations expose the same code endpoint ${endpoint}.`,
+    location
+  };
+  if (range !== undefined) {
+    diagnostic.range = range;
+  }
+  return diagnostic;
+}
+function duplicateLinkDiagnostic(source, target, location, range) {
+  const diagnostic = {
+    severity: "warning",
+    code: "duplicate_link",
+    target,
+    source,
+    message: `Duplicate @doc link from ${source} to ${target}.`,
+    location
+  };
+  if (range !== undefined) {
+    diagnostic.range = range;
+  }
+  return diagnostic;
+}
+
+// src/scan/code/typescript.ts
 var typeScriptAdapter = {
-  language: LANGUAGE,
+  language: "typescript",
   scanFile(filePath, content, options) {
     return scanTypeScript(filePath, content, options);
+  },
+  scanFiles(files, options) {
+    return files.map(({ filePath, content }) => scanTypeScript(filePath, content, options));
   }
 };
+var javaScriptAdapter = {
+  ...typeScriptAdapter,
+  language: "javascript"
+};
 var DEFAULT_MEMBER_VISIBILITY = ["public", "protected"];
 function scanTypeScript(filePath, content, options = {}) {
   const visibility = new Set(options.visibility ?? DEFAULT_MEMBER_VISIBILITY);
-  const sourceFile = import_typescript.default.createSourceFile(filePath, content, import_typescript.default.ScriptTarget.Latest, true, import_typescript.default.ScriptKind.TS);
-  const parseDiagnostics = getParseDiagnostics(sourceFile);
-  if (parseDiagnostics.length > 0) {
-    const first = parseDiagnostics[0];
+  const sourceFile = import_typescript2.default.createSourceFile(filePath, content, import_typescript2.default.ScriptTarget.Latest, true, scriptKindOf(filePath));
+  const syntaxErrors = syntaxDiagnostics(sourceFile);
+  if (syntaxErrors.length > 0) {
+    const first = syntaxErrors[0];
     return {
-      language: LANGUAGE,
+      language: scriptLanguage(filePath),
       filePath,
       symbols: [],
       undocumentedSymbols: [],
@@ -177604,11 +177868,13 @@ function scanTypeScript(filePath, content, options = {}) {
       }
       const parsed = parseLinkTarget(docTag.rawTarget, parseOptions);
       if (!parsed.ok) {
-        diagnostics.push(parsed.diagnostic);
+        diagnostics.push(linkDiagnostic(filePath, parsed.diagnostic));
         continue;
       }
       if (linkTargetsSeen.has(docTag.rawTarget)) {
-        diagnostics.push(duplicateLinkDiagnostic(endpoint, docTag.rawTarget, docTag.location, docTag.targetRange));
+        const { rawTarget, location, targetRange } = docTag;
+        const duplicate = duplicateLinkDiagnostic(endpoint, rawTarget, location, targetRange);
+        diagnostics.push(linkDiagnostic(filePath, duplicate));
         continue;
       }
       linkTargetsSeen.add(docTag.rawTarget);
@@ -177624,7 +177890,7 @@ function scanTypeScript(filePath, content, options = {}) {
     }
   }
   return {
-    language: LANGUAGE,
+    language: scriptLanguage(filePath),
     filePath,
     symbols,
     undocumentedSymbols,
@@ -177632,15 +177898,60 @@ function scanTypeScript(filePath, content, options = {}) {
     diagnostics
   };
 }
+function linkDiagnostic(filePath, diagnostic) {
+  if (scriptLanguage(filePath) !== "javascript") {
+    return diagnostic;
+  }
+  const { severity, code, ...rest } = diagnostic;
+  return { severity, code, language: "javascript", ...rest };
+}
+function scriptKindOf(filePath) {
+  if (scriptLanguage(filePath) === "javascript") {
+    return filePath.endsWith(".jsx") ? import_typescript2.default.ScriptKind.JSX : import_typescript2.default.ScriptKind.JS;
+  }
+  return filePath.endsWith(".tsx") ? import_typescript2.default.ScriptKind.TSX : import_typescript2.default.ScriptKind.TS;
+}
+function syntaxDiagnostics(sourceFile) {
+  const parseDiagnostics = getParseDiagnostics(sourceFile);
+  if (parseDiagnostics.length > 0 || scriptLanguage(sourceFile.fileName) !== "javascript") {
+    return parseDiagnostics;
+  }
+  return javaScriptGrammarDiagnostics(sourceFile);
+}
 function getParseDiagnostics(sourceFile) {
   const withDiagnostics = sourceFile;
   return withDiagnostics.parseDiagnostics ?? [];
 }
+function javaScriptGrammarDiagnostics(sourceFile) {
+  const { fileName } = sourceFile;
+  const host = {
+    getSourceFile: (name) => name === fileName ? sourceFile : undefined,
+    fileExists: (name) => name === fileName,
+    readFile: () => {
+      return;
+    },
+    writeFile: () => {
+      return;
+    },
+    getDefaultLibFileName: () => "lib.d.ts",
+    getCurrentDirectory: () => "/",
+    getCanonicalFileName: (name) => name,
+    useCaseSensitiveFileNames: () => true,
+    getNewLine: () => `
+`
+  };
+  const program = import_typescript2.default.createProgram({
+    rootNames: [fileName],
+    options: { allowJs: true, noLib: true, noResolve: true, types: [] },
+    host
+  });
+  return program.getSyntacticDiagnostics(sourceFile);
+}
 function collectDocTags(filePath, sourceFile, statement) {
   const node = jsDocCarrier(statement);
   const location = locationOf(filePath, sourceFile, statement);
   const tags = [];
-  for (const tag of import_typescript.default.getJSDocTags(node)) {
+  for (const tag of import_typescript2.default.getJSDocTags(node)) {
     if (tag.tagName.escapedText !== "doc") {
       continue;
     }
@@ -177659,7 +177970,7 @@ function collectDocTags(filePath, sourceFile, statement) {
   return tags;
 }
 function jsDocCarrier(statement) {
-  if (import_typescript.default.isVariableStatement(statement)) {
+  if (import_typescript2.default.isVariableStatement(statement)) {
     const declaration = statement.declarationList.declarations[0];
     if (declaration !== undefined) {
       return declaration;
@@ -177705,11 +178016,11 @@ function collectMemberDeclarations(filePath, sourceFile, statement, visibility,
   }
 }
 function diagnoseParameterProperties(filePath, sourceFile, member, diagnostics) {
-  if (!import_typescript.default.isConstructorDeclaration(member)) {
+  if (!import_typescript2.default.isConstructorDeclaration(member)) {
     return;
   }
   for (const parameter of member.parameters) {
-    if (!import_typescript.default.isParameterPropertyDeclaration(parameter, member)) {
+    if (!import_typescript2.default.isParameterPropertyDeclaration(parameter, member)) {
       continue;
     }
     if (collectDocTags(filePath, sourceFile, parameter).length > 0) {
@@ -177725,22 +178036,22 @@ function describeContainer(statement) {
   return { name: supportedNameNode(statement)?.text ?? null, members };
 }
 function containerMembers(statement) {
-  if (import_typescript.default.isClassDeclaration(statement)) {
+  if (import_typescript2.default.isClassDeclaration(statement)) {
     return statement.members;
   }
-  if (import_typescript.default.isInterfaceDeclaration(statement)) {
+  if (import_typescript2.default.isInterfaceDeclaration(statement)) {
     return statement.members;
   }
-  if (import_typescript.default.isEnumDeclaration(statement)) {
+  if (import_typescript2.default.isEnumDeclaration(statement)) {
     return statement.members;
   }
-  if (import_typescript.default.isTypeAliasDeclaration(statement)) {
-    return import_typescript.default.isTypeLiteralNode(statement.type) ? statement.type.members : null;
+  if (import_typescript2.default.isTypeAliasDeclaration(statement)) {
+    return import_typescript2.default.isTypeLiteralNode(statement.type) ? statement.type.members : null;
   }
-  if (import_typescript.default.isVariableStatement(statement)) {
+  if (import_typescript2.default.isVariableStatement(statement)) {
     const declarations = statement.declarationList.declarations;
     const initializer = declarations.length === 1 ? declarations[0]?.initializer : undefined;
-    return initializer !== undefined && import_typescript.default.isClassExpression(initializer) ? initializer.members : null;
+    return initializer !== undefined && import_typescript2.default.isClassExpression(initializer) ? initializer.members : null;
   }
   return null;
 }
@@ -177762,24 +178073,24 @@ function describeMember(filePath, sourceFile, containerName, member, docTags) {
   };
 }
 function isVisibleMember(member, visibility) {
-  if (hasModifier(member, import_typescript.default.SyntaxKind.PrivateKeyword)) {
+  if (hasModifier(member, import_typescript2.default.SyntaxKind.PrivateKeyword)) {
     return visibility.has("private");
   }
-  if (hasModifier(member, import_typescript.default.SyntaxKind.ProtectedKeyword)) {
+  if (hasModifier(member, import_typescript2.default.SyntaxKind.ProtectedKeyword)) {
     return visibility.has("protected");
   }
   return visibility.has("public");
 }
 function memberIdentity(sourceFile, member) {
-  if (import_typescript.default.isConstructorDeclaration(member)) {
-    const keyword = member.getChildren(sourceFile).find((child) => child.kind === import_typescript.default.SyntaxKind.ConstructorKeyword);
+  if (import_typescript2.default.isConstructorDeclaration(member)) {
+    const keyword = member.getChildren(sourceFile).find((child) => child.kind === import_typescript2.default.SyntaxKind.ConstructorKeyword);
     return keyword === undefined ? null : { name: "constructor", nameRange: rangeOfNode(sourceFile, keyword) };
   }
-  if (!import_typescript.default.isMethodDeclaration(member) && !import_typescript.default.isPropertyDeclaration(member) && !import_typescript.default.isGetAccessorDeclaration(member) && !import_typescript.default.isSetAccessorDeclaration(member) && !import_typescript.default.isMethodSignature(member) && !import_typescript.default.isPropertySignature(member)) {
+  if (!import_typescript2.default.isMethodDeclaration(member) && !import_typescript2.default.isPropertyDeclaration(member) && !import_typescript2.default.isGetAccessorDeclaration(member) && !import_typescript2.default.isSetAccessorDeclaration(member) && !import_typescript2.default.isMethodSignature(member) && !import_typescript2.default.isPropertySignature(member)) {
     return null;
   }
   const name = member.name;
-  return import_typescript.default.isIdentifier(name) ? { name: name.text, nameRange: rangeOfNode(sourceFile, name) } : null;
+  return import_typescript2.default.isIdentifier(name) ? { name: name.text, nameRange: rangeOfNode(sourceFile, name) } : null;
 }
 function memberSignatureEndOffset(sourceFile, member) {
   const body = member.body;
@@ -177788,28 +178099,28 @@ function memberSignatureEndOffset(sourceFile, member) {
 function supportedNameNode(statement) {
   const isExported = hasExportModifier(statement);
   const isDefault = hasDefaultModifier(statement);
-  if (import_typescript.default.isFunctionDeclaration(statement)) {
+  if (import_typescript2.default.isFunctionDeclaration(statement)) {
     if (!isExported || statement.name === undefined) {
       return null;
     }
     return statement.name;
   }
-  if (import_typescript.default.isClassDeclaration(statement)) {
+  if (import_typescript2.default.isClassDeclaration(statement)) {
     if (!isExported || statement.name === undefined) {
       return null;
     }
     return statement.name;
   }
-  if (import_typescript.default.isInterfaceDeclaration(statement)) {
+  if (import_typescript2.default.isInterfaceDeclaration(statement)) {
     return isExported && !isDefault ? statement.name : null;
   }
-  if (import_typescript.default.isTypeAliasDeclaration(statement)) {
+  if (import_typescript2.default.isTypeAliasDeclaration(statement)) {
     return isExported && !isDefault ? statement.name : null;
   }
-  if (import_typescript.default.isEnumDeclaration(statement)) {
+  if (import_typescript2.default.isEnumDeclaration(statement)) {
     return isExported && !isDefault ? statement.name : null;
   }
-  if (import_typescript.default.isVariableStatement(statement)) {
+  if (import_typescript2.default.isVariableStatement(statement)) {
     if (!isExported) {
       return null;
     }
@@ -177819,23 +178130,23 @@ function supportedNameNode(statement) {
       return null;
     }
     const name = declaration.name;
-    return import_typescript.default.isIdentifier(name) ? name : null;
+    return import_typescript2.default.isIdentifier(name) ? name : null;
   }
   return null;
 }
 function hasExportModifier(statement) {
-  return hasModifier(statement, import_typescript.default.SyntaxKind.ExportKeyword);
+  return hasModifier(statement, import_typescript2.default.SyntaxKind.ExportKeyword);
 }
 function hasDefaultModifier(statement) {
-  return hasModifier(statement, import_typescript.default.SyntaxKind.DefaultKeyword);
+  return hasModifier(statement, import_typescript2.default.SyntaxKind.DefaultKeyword);
 }
 function hasModifier(node, kind) {
-  const modifiers = import_typescript.default.canHaveModifiers(node) ? import_typescript.default.getModifiers(node) : undefined;
+  const modifiers = import_typescript2.default.canHaveModifiers(node) ? import_typescript2.default.getModifiers(node) : undefined;
   return modifiers?.some((modifier) => modifier.kind === kind) ?? false;
 }
 function declarationLocation(filePath, sourceFile, node) {
-  const carrier = import_typescript.default.isVariableStatement(node) ? node.declarationList.declarations[0] : node;
-  const name = carrier === undefined ? undefined : import_typescript.default.getNameOfDeclaration(carrier);
+  const carrier = import_typescript2.default.isVariableStatement(node) ? node.declarationList.declarations[0] : node;
+  const name = carrier === undefined ? undefined : import_typescript2.default.getNameOfDeclaration(carrier);
   return locationOf(filePath, sourceFile, name ?? node);
 }
 function locationOf(filePath, sourceFile, node) {
@@ -177854,13 +178165,13 @@ function rangeOfNode(sourceFile, node) {
   return rangeFromOffsets(sourceFile, node.getStart(sourceFile), node.getEnd());
 }
 function signatureEndOffset(sourceFile, statement) {
-  if (import_typescript.default.isFunctionDeclaration(statement) && statement.body !== undefined) {
+  if (import_typescript2.default.isFunctionDeclaration(statement) && statement.body !== undefined) {
     return statement.body.getStart(sourceFile);
   }
-  if (import_typescript.default.isClassDeclaration(statement)) {
+  if (import_typescript2.default.isClassDeclaration(statement)) {
     return classBodyStartOffset(sourceFile, statement) ?? statement.getEnd();
   }
-  if (import_typescript.default.isVariableStatement(statement)) {
+  if (import_typescript2.default.isVariableStatement(statement)) {
     return variableSignatureEndOffset(sourceFile, statement) ?? statement.getEnd();
   }
   return statement.getEnd();
@@ -177876,13 +178187,13 @@ function variableSignatureEndOffset(sourceFile, statement) {
   if (initializer === undefined) {
     return;
   }
-  if ((import_typescript.default.isArrowFunction(initializer) || import_typescript.default.isFunctionExpression(initializer)) && import_typescript.default.isBlock(initializer.body)) {
+  if ((import_typescript2.default.isArrowFunction(initializer) || import_typescript2.default.isFunctionExpression(initializer)) && import_typescript2.default.isBlock(initializer.body)) {
     return initializer.body.getStart(sourceFile);
   }
-  if (import_typescript.default.isObjectLiteralExpression(initializer)) {
+  if (import_typescript2.default.isObjectLiteralExpression(initializer)) {
     return initializer.getStart(sourceFile);
   }
-  if (import_typescript.default.isClassExpression(initializer)) {
+  if (import_typescript2.default.isClassExpression(initializer)) {
     return classBodyStartOffset(sourceFile, initializer);
   }
   return;
@@ -177897,7 +178208,7 @@ function targetRangeOf(sourceFile, tag, rawTarget) {
 function makeCodeSymbol(filePath, endpoint, declaration) {
   const symbol = {
     kind: "code",
-    language: LANGUAGE,
+    language: scriptLanguage(filePath),
     filePath,
     symbolName: declaration.symbolName,
     canonicalId: declaration.canonicalId,
@@ -177934,224 +178245,20 @@ function firstToken(text) {
   }
   return trimmed.split(/\s+/)[0];
 }
-function parseErrorDiagnostic(filePath, sourceFile, diagnostic) {
-  const location = { filePath, line: 1, column: 1 };
-  if (diagnostic !== undefined && diagnostic.start !== undefined && diagnostic.file !== undefined) {
-    const { line, character } = sourceFile.getLineAndCharacterOfPosition(diagnostic.start);
-    location.line = line + 1;
-    location.column = character + 1;
-  }
-  const detail = diagnostic === undefined ? "TypeScript file has a syntactic parse error." : import_typescript.default.flattenDiagnosticMessageText(diagnostic.messageText, `
-`);
-  return {
-    severity: "error",
-    code: "code_parse_error",
-    language: LANGUAGE,
-    target: filePath,
-    message: `TypeScript parse error: ${detail}`,
-    location
-  };
-}
-function unsupportedDeclarationDiagnostic(filePath, location) {
-  return {
-    severity: "warning",
-    code: "unsupported_declaration",
-    language: LANGUAGE,
-    target: filePath,
-    message: "@doc is attached to an unsupported declaration. Supported declarations are top-level exported function, class, interface, type, single-declarator const, enum, and named default function or class, plus the identifier-named members of a class, interface, or object type alias.",
-    location
-  };
-}
-function duplicateCodeSymbolDiagnostic(endpoint, location, range) {
-  const diagnostic = {
-    severity: "error",
-    code: "duplicate_code_symbol",
-    language: LANGUAGE,
-    target: endpoint,
-    message: `Multiple @doc-annotated declarations expose the same code endpoint ${endpoint}.`,
-    location
-  };
-  if (range !== undefined) {
-    diagnostic.range = range;
-  }
-  return diagnostic;
-}
-function duplicateLinkDiagnostic(source, target, location, range) {
-  const diagnostic = {
-    severity: "warning",
-    code: "duplicate_link",
-    target,
-    source,
-    message: `Duplicate @doc link from ${source} to ${target}.`,
-    location
-  };
-  if (range !== undefined) {
-    diagnostic.range = range;
-  }
-  return diagnostic;
-}
 
-// src/scan/code/worker/scanner-executable.ts
-import { accessSync, chmodSync, constants, existsSync as existsSync2, statSync } from "node:fs";
-import { join as join5 } from "node:path";
+// src/scan/code/worker/runtime-worker.ts
+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/shared/error.ts
-function reasonOf(error) {
-  return error instanceof Error ? error.message : String(error);
-}
+// src/scan/code/worker/runtime-probe.ts
+import { spawnSync as spawnSync2 } from "node:child_process";
 
-// src/shared/package-root.ts
-import { existsSync, realpathSync } from "node:fs";
+// src/scan/code/worker/scanner-worker.ts
+var import__2020 = __toESM(require_2020(), 1);
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { dirname, join as join4 } from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
-function resolvePackageRoot(moduleUrl = import.meta.url) {
-  const modulePath = fileURLToPath2(moduleUrl);
-  let resolved;
-  try {
-    resolved = realpathSync(modulePath);
-  } catch {
-    resolved = modulePath;
-  }
-  let dir = dirname(resolved);
-  for (;; ) {
-    if (existsSync(join4(dir, "templates", "skills"))) {
-      return dir;
-    }
-    const parent = dirname(dir);
-    if (parent === dir) {
-      return dir;
-    }
-    dir = parent;
-  }
-}
-
-// src/scan/code/worker/scanner-executable.ts
-var SUPPORTED_SCANNER_PLATFORM_KEYS = ["darwin-arm64", "linux-x64"];
-var SCANNER_EXECUTABLE_NAMES = {
-  swift: "docbridge-swift-scanner",
-  dart: "docbridge_dart_scanner",
-  rust: "docbridge-rust-scanner",
-  go: "docbridge-go-scanner"
-};
-function scannerPlatformKey() {
-  return `${process.platform}-${process.arch}`;
-}
-function scannerExecutableName(language) {
-  return SCANNER_EXECUTABLE_NAMES[language];
-}
-function resolveScannerWorkerCommand(language, options = {}) {
-  const platformKey = options.platformKey ?? scannerPlatformKey();
-  const platformSupported = isSupportedScannerPlatformKey(platformKey);
-  const candidates = scannerExecutableCandidates(language, platformKey, platformSupported, options);
-  const found = candidates.find((candidate) => existsSync2(candidate));
-  if (found !== undefined) {
-    const repair = ensureExecutable(found, options.chmod ?? chmodSync);
-    if (!repair.ok) {
-      return { ok: false, diagnostic: scannerUnavailableDiagnostic(language, repair.reason) };
-    }
-    return { ok: true, command: [found] };
-  }
-  if (!platformSupported) {
-    return {
-      ok: false,
-      diagnostic: scannerUnavailableDiagnostic(language, `platform ${platformKey} is unsupported; supported platforms: ${SUPPORTED_SCANNER_PLATFORM_KEYS.join(", ")}`)
-    };
-  }
-  return {
-    ok: false,
-    diagnostic: scannerUnavailableDiagnostic(language, `missing ${scannerExecutableName(language)} for platform ${platformKey}; supported platforms: ${SUPPORTED_SCANNER_PLATFORM_KEYS.join(", ")}`)
-  };
-}
-function scannerExecutableCandidates(language, platformKey, platformSupported, options) {
-  const sourceRoot = options.sourceRoot ?? sourceRootPath();
-  const distRoot = options.distRoot ?? distRootPath();
-  const executable = scannerExecutableName(language);
-  if (language === "swift") {
-    return [
-      join5(sourceRoot, "packages/swift-scanner/.build/release", executable),
-      join5(sourceRoot, "packages/swift-scanner/.build/debug", executable),
-      ...platformSupported ? [join5(distRoot, "bin", platformKey, executable)] : []
-    ];
-  }
-  if (language === "rust") {
-    return [
-      join5(sourceRoot, "packages/rust-scanner/target/release", executable),
-      join5(sourceRoot, "packages/rust-scanner/target/debug", executable),
-      ...platformSupported ? [join5(distRoot, "bin", platformKey, executable)] : []
-    ];
-  }
-  if (language === "go") {
-    return [
-      join5(sourceRoot, "packages/go-scanner/bin", executable),
-      ...platformSupported ? [join5(distRoot, "bin", platformKey, executable)] : []
-    ];
-  }
-  return [
-    join5(sourceRoot, "packages/dart-scanner/bin", executable),
-    ...platformSupported ? [join5(distRoot, "bin", platformKey, executable)] : []
-  ];
-}
-function ensureExecutable(path, chmod) {
-  let mode;
-  try {
-    mode = statSync(path).mode;
-  } catch (error) {
-    return { ok: false, reason: `cannot stat ${path}: ${reasonOf(error)}` };
-  }
-  if (isExecutableByThisProcess(path)) {
-    return { ok: true };
-  }
-  try {
-    chmod(path, mode | 73);
-  } catch (error) {
-    return {
-      ok: false,
-      reason: `${path} is not executable (mode ${formatMode(mode)}) and the executable ` + `bit could not be restored: ${reasonOf(error)}; run \`chmod +x ${path}\` ` + `or reinstall DocBridge into a writable location`
-    };
-  }
-  return { ok: true };
-}
-function isExecutableByThisProcess(path) {
-  try {
-    accessSync(path, constants.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function formatMode(mode) {
-  return `0${(mode & 4095).toString(8).padStart(3, "0")}`;
-}
-function isSupportedScannerPlatformKey(platformKey) {
-  return SUPPORTED_SCANNER_PLATFORM_KEYS.includes(platformKey);
-}
-function scannerRootsFromModuleUrl(moduleUrl) {
-  const packageRoot = resolvePackageRoot(moduleUrl);
-  return { distRoot: join5(packageRoot, "dist"), sourceRoot: packageRoot };
-}
-function sourceRootPath() {
-  return scannerRootsFromModuleUrl(import.meta.url).sourceRoot;
-}
-function distRootPath() {
-  return scannerRootsFromModuleUrl(import.meta.url).distRoot;
-}
-function scannerUnavailableDiagnostic(language, reason) {
-  const label = language.charAt(0).toUpperCase() + language.slice(1);
-  return {
-    severity: "error",
-    code: "code_scanner_unavailable",
-    language,
-    target: language,
-    message: `${label} scanner worker is unavailable: ${reason}`
-  };
-}
-
-// src/scan/code/worker/scanner-worker.ts
-var import__2020 = __toESM(require_2020(), 1);
-import { spawnSync } from "node:child_process";
-import { mkdirSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname as dirname2, join as join6 } from "node:path";
 // schemas/common-output.schema.json
 var common_output_schema_default = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -178199,7 +178306,17 @@ var common_output_schema_default = {
         target: { type: "string" },
         language: {
           type: "string",
-          enum: ["typescript", "swift", "dart", "rust", "go"]
+          enum: [
+            "typescript",
+            "swift",
+            "dart",
+            "rust",
+            "go",
+            "javascript",
+            "python",
+            "ruby",
+            "java"
+          ]
         },
         source: { type: "string" },
         message: { type: "string" },
@@ -178219,7 +178336,7 @@ var scanner_worker_schema_default = {
   $defs: {
     language: {
       type: "string",
-      enum: ["typescript", "swift", "dart", "rust", "go"]
+      enum: ["typescript", "swift", "dart", "rust", "go", "javascript", "python", "ruby", "java"]
     },
     codeSymbol: {
       type: "object",
@@ -178335,6 +178452,8 @@ 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 () => {
@@ -178352,15 +178471,29 @@ function compileWorkerResponseValidator() {
     $ref: "#/$defs/response"
   });
 }
-function invokeScannerWorker(request, command, run = runScannerWorkerProcess) {
-  const processResult = run({
+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));
+  return {
+    promise: run.promise.then((processResult) => interpretWorkerProcess(request, command, processResult)),
+    cancel: () => run.cancel()
+  };
+}
+function processInput(request, command, stripEnv) {
+  return {
     command,
-    stdin: JSON.stringify(request)
-  });
+    stdin: JSON.stringify(request),
+    stripEnv,
+    timeoutMs: workerTimeoutMs(request.files.length)
+  };
+}
+function interpretWorkerProcess(request, command, processResult) {
   if (!processResult.ok) {
     return {
       ok: false,
-      diagnostic: scannerUnavailableDiagnostic2(request.language, processResult.error, command[0]),
+      diagnostic: processResult.kind === "execution" ? scannerFailedDiagnostic(request.language, reasonOf(processResult.error)) : scannerUnavailableDiagnostic(request.language, processResult.error, command[0]),
       stderr: processResult.stderr
     };
   }
@@ -178401,43 +178534,203 @@ function invokeScannerWorker(request, command, run = runScannerWorkerProcess) {
 }
 function clangModuleCachePath() {
   const owner = typeof process.getuid === "function" ? process.getuid() : "shared";
-  return join6(tmpdir(), `docbridge-clang-module-cache-${owner}`);
+  return join4(tmpdir(), `docbridge-clang-module-cache-${owner}`);
+}
+function workerProcessEnv(stripEnv = [], platform = process.platform) {
+  const moduleCachePath = clangModuleCachePath();
+  mkdirSync(moduleCachePath, { recursive: true });
+  const fold = platform === "win32" ? (name) => name.toUpperCase() : (name) => name;
+  const stripped = new Set(stripEnv.map(fold));
+  const env = {};
+  for (const [name, value] of Object.entries(process.env)) {
+    if (value !== undefined && !stripped.has(fold(name))) {
+      env[name] = value;
+    }
+  }
+  env.CLANG_MODULE_CACHE_PATH = moduleCachePath;
+  return env;
+}
+function workerTimeoutMs(fileCount) {
+  return 30000 + 1000 * fileCount;
 }
 function runScannerWorkerProcess(input) {
+  const maxOutputBytes = input.maxOutputBytes ?? WORKER_OUTPUT_LIMIT_BYTES;
   try {
-    const moduleCachePath = clangModuleCachePath();
-    mkdirSync(moduleCachePath, { recursive: true });
     const [executable = "", ...args] = input.command;
     const result = spawnSync(executable, args, {
-      env: {
-        ...process.env,
-        CLANG_MODULE_CACHE_PATH: moduleCachePath
-      },
+      env: workerProcessEnv(input.stripEnv),
       input: input.stdin,
       encoding: "utf8",
-      maxBuffer: 1024 * 1024 * 1024
+      maxBuffer: maxOutputBytes,
+      killSignal: "SIGKILL",
+      ...input.timeoutMs === undefined ? {} : { timeout: input.timeoutMs }
     });
-    const stderr = result.stderr ?? "";
-    if (result.error !== undefined) {
-      return { ok: false, error: result.error, stderr };
-    }
-    if (result.status === null) {
-      return {
-        ok: false,
-        error: new Error(`worker terminated by signal ${result.signal ?? "unknown"}`),
-        stderr
-      };
+    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;
+  let grace;
+  const settle = (complete) => {
+    if (settled) {
+      return;
     }
-    return {
-      ok: true,
-      exitCode: result.status,
-      stdout: result.stdout ?? "",
-      stderr
-    };
+    settled = true;
+    clearTimeout(timer);
+    clearTimeout(grace);
+    complete();
+  };
+  const ownGroup = process.platform !== "win32";
+  let child;
+  try {
+    const [executable = "", ...args] = input.command;
+    child = spawn(executable, args, { env: workerProcessEnv(input.stripEnv), detached: ownGroup });
   } catch (error) {
-    return { ok: false, error, stderr: "" };
+    settle(() => run.resolve({ ok: false, kind: "start", error, stderr: "" }));
+    return { promise: run.promise, cancel: () => {
+      return;
+    } };
+  }
+  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) => {
+    failure ??= reason;
+    killWorker(child, ownGroup);
+    grace ??= setTimeout(() => {
+      closeStreams(child);
+      settle(() => run.resolve(closedProcessResult(null, null, failure, stdout, stderr)));
+    }, KILLED_WORKER_GRACE_MS);
+  };
+  let spawned = false;
+  child.on("spawn", () => {
+    spawned = true;
+  });
+  child.on("error", (error) => {
+    if (!spawned) {
+      settle(() => run.resolve({ ok: false, kind: "start", error, stderr: stderr.text() }));
+      return;
+    }
+    failure ??= error;
+  });
+  child.stdout.on("data", (chunk) => {
+    if (!stdout.add(chunk)) {
+      kill(outputLimitError(maxOutputBytes));
+    }
+  });
+  child.stderr.on("data", (chunk) => {
+    if (!stderr.add(chunk)) {
+      kill(outputLimitError(maxOutputBytes));
+    }
+  });
+  child.stdin.on("error", () => {
+    return;
+  });
+  child.on("close", (code, signal) => {
+    settle(() => run.resolve(closedProcessResult(code, signal, failure, stdout, stderr)));
+  });
+  child.stdin.end(input.stdin);
+  const { timeoutMs } = input;
+  if (timeoutMs !== undefined) {
+    timer = setTimeout(() => kill(timeoutError(timeoutMs)), timeoutMs);
+  }
+  return {
+    promise: run.promise,
+    cancel() {
+      settle(() => {
+        killWorker(child, ownGroup);
+        closeStreams(child);
+        run.reject(abortError());
+      });
+    }
+  };
+}
+function killWorker(child, ownGroup) {
+  if (ownGroup && child.pid !== undefined) {
+    try {
+      process.kill(-child.pid, "SIGKILL");
+      return;
+    } catch {}
+  }
+  child.kill("SIGKILL");
+}
+function closeStreams(child) {
+  child.stdin.destroy();
+  child.stdout.destroy();
+  child.stderr.destroy();
+}
+
+class OutputCollector {
+  budget;
+  chunks = [];
+  constructor(budget) {
+    this.budget = budget;
+  }
+  add(chunk) {
+    this.budget.bytes += chunk.byteLength;
+    if (this.budget.bytes > this.budget.limit) {
+      return false;
+    }
+    this.chunks.push(chunk);
+    return true;
+  }
+  text() {
+    return Buffer.concat(this.chunks).toString("utf8");
   }
 }
+function closedProcessResult(code, signal, failure, stdout, stderr) {
+  if (failure !== undefined) {
+    return { ok: false, kind: "execution", error: failure, stderr: stderr.text() };
+  }
+  if (code === null) {
+    return { ok: false, kind: "execution", error: signalError(signal), 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 });
+}
+function timeoutError(timeoutMs) {
+  return Object.assign(new Error(`worker timed out after ${timeoutMs} ms`), {
+    code: "ETIMEDOUT"
+  });
+}
+function outputLimitError(maxOutputBytes) {
+  return Object.assign(new Error(`worker wrote more than ${maxOutputBytes} bytes to stdout and stderr together`), { code: "ENOBUFS" });
+}
 function validateWorkerResponse(value, request) {
   const validator = responseValidator();
   if (!validator(value)) {
@@ -178463,117 +178756,768 @@ function formatSchemaError(errors) {
   const path = error.instancePath || "/";
   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;
+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);
+}
+function scannerUnavailableDiagnostic(language, error, executable) {
+  const label = languageLabel(language);
+  return {
+    severity: "error",
+    code: "code_scanner_unavailable",
+    language,
+    target: language,
+    message: `${label} scanner worker is unavailable: ${spawnFailureReason(error, executable)}`
+  };
+}
+function spawnFailureReason(error, executable) {
+  const reason = reasonOf(error);
+  if (!isExecDenied(error) || executable === undefined) {
+    return reason;
+  }
+  return `${reason}; the scanner is executable but ${dirname(executable)} refuses to ` + `execute it, which a \`noexec\` mount does. Install DocBridge as a project ` + `dependency, or point the installer cache at an exec-capable directory, ` + `instead of running through \`bunx\``;
+}
+function isExecDenied(error) {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  const code = error.code;
+  return code === "EACCES" || code === "EPERM";
+}
+function scannerFailedDiagnostic(language, reason) {
+  const label = languageLabel(language);
+  return {
+    severity: "error",
+    code: "code_scanner_failed",
+    language,
+    target: language,
+    message: `${label} scanner worker failed: ${reason}`
+  };
+}
+function languageLabel(language) {
+  return language.charAt(0).toUpperCase() + language.slice(1);
+}
+
+// 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({
+    command: [...command, "--probe"],
+    stdin: "",
+    stripEnv,
+    timeoutMs: PROBE_TIMEOUT_MS,
+    maxOutputBytes: PROBE_MAX_OUTPUT_BYTES
+  });
+  return {
+    promise: run.promise.then((result) => classifyProbe(spawnResultOf(result))),
+    cancel: () => run.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 (code === "ENOBUFS") {
+    return {
+      kind: "failed",
+      reason: `probe printed more than ${PROBE_MAX_OUTPUT_BYTES / 1024} KiB`
+    };
+  }
+  return { kind: "unstartable", reason: reasonOf(error) };
+}
+function parseProbeOutput(stdout) {
+  const text = stdout.trim();
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return malformed(text);
+  }
+  if (!isRecord2(value)) {
+    return malformed(text);
+  }
+  if (value.ok === true && typeof value.runtime === "string" && typeof value.version === "string") {
+    return { kind: "ok", runtime: value.runtime, version: value.version };
+  }
+  if (value.ok === false && typeof value.reason === "string") {
+    return { kind: "rejected", reason: value.reason };
+  }
+  return malformed(text);
+}
+function malformed(text) {
+  const shown = text.length > 200 ? `${text.slice(0, 200)}...` : text;
+  return { kind: "failed", reason: `malformed probe output: ${JSON.stringify(shown)}` };
+}
+function firstLine(text) {
+  return text.trim().split(/\r?\n/u)[0] ?? "";
+}
+function isRecord2(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";
+import { join as join6 } from "node:path";
+
+// src/shared/package-root.ts
+import { existsSync, realpathSync } from "node:fs";
+import { dirname as dirname2, join as join5 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+function resolvePackageRoot(moduleUrl = import.meta.url) {
+  const modulePath = fileURLToPath2(moduleUrl);
+  let resolved;
+  try {
+    resolved = realpathSync(modulePath);
+  } catch {
+    resolved = modulePath;
+  }
+  let dir = dirname2(resolved);
+  for (;; ) {
+    if (existsSync(join5(dir, "templates", "skills"))) {
+      return dir;
+    }
+    const parent = dirname2(dir);
+    if (parent === dir) {
+      return dir;
+    }
+    dir = parent;
+  }
+}
+
+// src/scan/code/worker/scanner-executable.ts
+var SUPPORTED_SCANNER_PLATFORM_KEYS = ["darwin-arm64", "linux-x64"];
+var SCANNER_EXECUTABLE_NAMES = {
+  swift: "docbridge-swift-scanner",
+  dart: "docbridge_dart_scanner",
+  rust: "docbridge-rust-scanner",
+  go: "docbridge-go-scanner"
+};
+function scannerPlatformKey() {
+  return `${process.platform}-${process.arch}`;
+}
+function scannerExecutableName(language) {
+  return SCANNER_EXECUTABLE_NAMES[language];
+}
+function resolveScannerWorkerCommand(language, options = {}) {
+  const platformKey = options.platformKey ?? scannerPlatformKey();
+  const platformSupported = isSupportedScannerPlatformKey(platformKey);
+  const candidates = scannerExecutableCandidates(language, platformKey, platformSupported, options);
+  const found = candidates.find((candidate) => existsSync2(candidate));
+  if (found !== undefined) {
+    const repair = ensureExecutable(found, options.chmod ?? chmodSync);
+    if (!repair.ok) {
+      return { ok: false, diagnostic: scannerUnavailableDiagnostic2(language, repair.reason) };
+    }
+    return { ok: true, command: [found] };
+  }
+  if (!platformSupported) {
+    return {
+      ok: false,
+      diagnostic: scannerUnavailableDiagnostic2(language, `platform ${platformKey} is unsupported; supported platforms: ${SUPPORTED_SCANNER_PLATFORM_KEYS.join(", ")}`)
+    };
+  }
+  return {
+    ok: false,
+    diagnostic: scannerUnavailableDiagnostic2(language, `missing ${scannerExecutableName(language)} for platform ${platformKey}; supported platforms: ${SUPPORTED_SCANNER_PLATFORM_KEYS.join(", ")}`)
+  };
+}
+function scannerExecutableCandidates(language, platformKey, platformSupported, options) {
+  const sourceRoot = options.sourceRoot ?? sourceRootPath();
+  const distRoot = options.distRoot ?? distRootPath();
+  const executable = scannerExecutableName(language);
+  if (language === "swift") {
+    return [
+      join6(sourceRoot, "packages/swift-scanner/.build/release", executable),
+      join6(sourceRoot, "packages/swift-scanner/.build/debug", executable),
+      ...platformSupported ? [join6(distRoot, "bin", platformKey, executable)] : []
+    ];
+  }
+  if (language === "rust") {
+    return [
+      join6(sourceRoot, "packages/rust-scanner/target/release", executable),
+      join6(sourceRoot, "packages/rust-scanner/target/debug", executable),
+      ...platformSupported ? [join6(distRoot, "bin", platformKey, executable)] : []
+    ];
+  }
+  if (language === "go") {
+    return [
+      join6(sourceRoot, "packages/go-scanner/bin", executable),
+      ...platformSupported ? [join6(distRoot, "bin", platformKey, executable)] : []
+    ];
+  }
+  return [
+    join6(sourceRoot, "packages/dart-scanner/bin", executable),
+    ...platformSupported ? [join6(distRoot, "bin", platformKey, executable)] : []
+  ];
+}
+function ensureExecutable(path, chmod) {
+  let mode;
+  try {
+    mode = statSync(path).mode;
+  } catch (error) {
+    return { ok: false, reason: `cannot stat ${path}: ${reasonOf(error)}` };
+  }
+  if (isExecutableByThisProcess(path)) {
+    return { ok: true };
+  }
+  try {
+    chmod(path, mode | 73);
+  } catch (error) {
+    return {
+      ok: false,
+      reason: `${path} is not executable (mode ${formatMode(mode)}) and the executable ` + `bit could not be restored: ${reasonOf(error)}; run \`chmod +x ${path}\` ` + `or reinstall DocBridge into a writable location`
+    };
+  }
+  return { ok: true };
+}
+function isExecutableByThisProcess(path) {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function formatMode(mode) {
+  return `0${(mode & 4095).toString(8).padStart(3, "0")}`;
+}
+function isSupportedScannerPlatformKey(platformKey) {
+  return SUPPORTED_SCANNER_PLATFORM_KEYS.includes(platformKey);
+}
+function scannerRootsFromModuleUrl(moduleUrl) {
+  const packageRoot = resolvePackageRoot(moduleUrl);
+  return { distRoot: join6(packageRoot, "dist"), sourceRoot: packageRoot };
+}
+function sourceRootPath() {
+  return scannerRootsFromModuleUrl(import.meta.url).sourceRoot;
+}
+function distRootPath() {
+  return scannerRootsFromModuleUrl(import.meta.url).distRoot;
+}
+function scannerUnavailableDiagnostic2(language, reason) {
+  const label = language.charAt(0).toUpperCase() + language.slice(1);
+  return {
+    severity: "error",
+    code: "code_scanner_unavailable",
+    language,
+    target: language,
+    message: `${label} scanner worker is unavailable: ${reason}`
+  };
+}
+
+// src/scan/code/worker/runtime-worker.ts
+var RUNTIME_WORKERS = {
+  python: {
+    label: "Python",
+    runtimeName: "CPython",
+    runtimeId: "cpython",
+    floor: [3, 10],
+    floorText: "3.10",
+    candidates: (platform) => platform === "win32" ? [["py", "-3"], ["python"]] : [["python3"], ["python"]],
+    flags: ["-I", "-S"],
+    stripEnv: ["PYTHONPATH", "PYTHONSTARTUP", "PYTHONHOME", "PYTHONSAFEPATH"],
+    entrypoint: {
+      source: "packages/python-scanner/docbridge_python_scanner.py",
+      dist: "workers/python/docbridge_python_scanner.py"
+    }
+  },
+  ruby: {
+    label: "Ruby",
+    runtimeName: "CRuby",
+    runtimeId: "cruby",
+    floor: [3, 3],
+    floorText: "3.3",
+    candidates: () => [["ruby"]],
+    flags: ["--disable=gems,did_you_mean,error_highlight", "-W0"],
+    stripEnv: ["RUBYOPT", "RUBYLIB", "PRISM_FFI_BACKEND"],
+    entrypoint: {
+      source: "packages/ruby-scanner/bin/docbridge-ruby-scanner",
+      dist: "workers/ruby/bin/docbridge-ruby-scanner"
+    }
+  },
+  java: {
+    label: "Java",
+    runtimeName: "JDK",
+    runtimeId: "jdk",
+    floor: [17, 0],
+    floorText: "17",
+    candidates: () => [["java"]],
+    flags: ["-Xshare:auto", "-XX:TieredStopAtLevel=1", "-XX:+UseSerialGC", "-jar"],
+    stripEnv: ["JAVA_TOOL_OPTIONS", "JDK_JAVA_OPTIONS", "_JAVA_OPTIONS"],
+    entrypoint: {
+      source: "packages/java-scanner/build/docbridge-java-scanner.jar",
+      dist: "workers/java/docbridge-java-scanner.jar"
+    },
+    buildHint: "run `just build-java-scanner` in a source checkout"
+  }
+};
+var probeCache = new Map;
+var probeCacheGeneration = 0;
+function clearRuntimeProbeCache() {
+  probeCache.clear();
+  probeCacheGeneration += 1;
+}
+function rememberProbe(key, generation, outcome) {
+  if (generation === probeCacheGeneration) {
+    probeCache.set(key, 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)));
+    }
+    return step.value;
+  });
+}
+function* resolutionSteps(language, options, env) {
+  const spec = RUNTIME_WORKERS[language];
+  const entrypoint = findEntrypoint(spec, options);
+  if (!entrypoint.ok) {
+    return failure(spec, language, "code_scanner_unavailable", entrypoint.reason);
+  }
+  const platform = options.platform ?? process.platform;
+  const commandFor = (runtime) => [...runtime, ...spec.flags, entrypoint.path];
+  const usable = (command, runtime, verdict) => ({
+    ok: true,
+    command,
+    stripEnv: spec.stripEnv,
+    runtime: [verdict.runtime, verdict.version, locateExecutable(runtime[0] ?? "", env, platform)]
+  });
+  const override = explicitOverride(language, options, env);
+  if (override !== undefined) {
+    const runtime = override.argv.map((part, index) => index === 0 ? resolveExecutable(part, options.projectRoot) : part);
+    const command = commandFor(runtime);
+    const verdict = judge(spec, yield { command, stripEnv: spec.stripEnv });
+    if (verdict.ok) {
+      return usable(command, runtime, verdict);
+    }
+    return failure(spec, language, verdict.code, `${override.source} (${runtime.join(" ")}) ${verdict.reason}; no other runtime is tried ` + `while ${override.source} is set`);
+  }
+  const rejections = [];
+  for (const runtime of spec.candidates(platform)) {
+    const command = commandFor(runtime);
+    const verdict = judge(spec, yield { command, stripEnv: spec.stripEnv });
+    if (verdict.ok) {
+      return usable(command, runtime, verdict);
+    }
+    rejections.push({ runtime, verdict });
+  }
+  const outcomes = rejections.map(({ runtime, verdict }) => `${runtime.join(" ")} ${verdict.reason}`).join("; ");
+  const code = rejections.find(({ verdict }) => verdict.startable)?.verdict.code ?? "code_scanner_unavailable";
+  return failure(spec, language, code, `no usable ${spec.runtimeName} ${spec.floorText} or later found: ${outcomes}. Install ` + `${spec.runtimeName} ${spec.floorText} or later, or set scanners.${language}.command or ` + `${environmentVariable(language)}`);
+}
+function findEntrypoint(spec, options) {
+  const roots = scannerRootsFromModuleUrl(import.meta.url);
+  const source = join7(options.sourceRoot ?? roots.sourceRoot, spec.entrypoint.source);
+  const dist = join7(options.distRoot ?? roots.distRoot, spec.entrypoint.dist);
+  const found = [source, dist].find((path) => existsSync3(path));
+  if (found !== undefined) {
+    return { ok: true, path: found };
+  }
+  const hint = spec.buildHint === undefined ? "" : `; ${spec.buildHint}`;
+  return {
+    ok: false,
+    reason: `the bundled worker is missing; looked for ${source} and ${dist}${hint}`
+  };
+}
+function explicitOverride(language, options, env) {
+  if (options.command !== undefined && options.command.length > 0) {
+    return { source: `scanners.${language}.command`, argv: options.command };
+  }
+  const variable = environmentVariable(language);
+  const value = env[variable];
+  if (value !== undefined && value !== "") {
+    return { source: variable, argv: [value] };
+  }
+  return;
+}
+function environmentVariable(language) {
+  return `DOCBRIDGE_${language.toUpperCase()}_RUNTIME`;
+}
+function resolveExecutable(executable, projectRoot) {
+  if (isAbsolute2(executable) || !/[/\\]/u.test(executable)) {
+    return executable;
+  }
+  return resolve2(projectRoot, executable);
+}
+function locateExecutable(executable, env, platform) {
+  const candidates = /[/\\]/u.test(executable) ? [executable] : pathCandidates(executable, env, platform);
+  const found = candidates.find((candidate) => isExecutableFile(candidate, platform));
+  if (found === undefined) {
+    return executable;
   }
-  return responseFiles.every((file, index) => {
-    if (!isRecord(file)) {
+  try {
+    return realpathSync2(found);
+  } catch {
+    return found;
+  }
+}
+function pathCandidates(name, env, platform) {
+  const windows = platform === "win32";
+  const directories = (env.PATH ?? "").split(windows ? ";" : ":").filter((dir) => dir !== "");
+  const extensions = windows && extname(name) === "" ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";") : [""];
+  return directories.flatMap((directory) => extensions.map((extension) => join7(directory, `${name}${extension}`)));
+}
+function isExecutableFile(path, platform) {
+  try {
+    if (!statSync2(path).isFile()) {
       return false;
     }
-    return file.filePath === requestFiles[index]?.filePath;
-  });
+    if (platform !== "win32") {
+      accessSync2(path, constants2.X_OK);
+    }
+    return true;
+  } catch {
+    return false;
+  }
 }
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+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 scannerUnavailableDiagnostic2(language, error, executable) {
-  const label = languageLabel(language);
-  return {
-    severity: "error",
-    code: "code_scanner_unavailable",
-    language,
-    target: language,
-    message: `${label} scanner worker is unavailable: ${spawnFailureReason(error, executable)}`
-  };
+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) => {
+    rememberProbe(key, generation, outcome);
+    return outcome;
+  });
 }
-function spawnFailureReason(error, executable) {
-  const reason = reasonOf(error);
-  if (!isExecDenied(error) || executable === undefined) {
-    return reason;
+function probeCacheKey(command, env) {
+  const docbridgeVariables = Object.entries(env).filter(([name]) => name.startsWith("DOCBRIDGE_")).toSorted(([left], [right]) => left.localeCompare(right));
+  return JSON.stringify([command, env.PATH ?? "", docbridgeVariables]);
+}
+function judge(spec, outcome) {
+  switch (outcome.kind) {
+    case "unstartable":
+      return rejected("code_scanner_unavailable", false, `could not be started: ${outcome.reason}`);
+    case "failed":
+      return rejected("code_scanner_failed", true, `failed its probe: ${outcome.reason}`);
+    case "rejected":
+      return rejected("code_scanner_unavailable", true, `is not a usable ${spec.runtimeName} ${spec.floorText} or later: ${outcome.reason}`);
+    case "ok":
+      return judgeVersion(spec, outcome.runtime, outcome.version);
   }
-  return `${reason}; the scanner is executable but ${dirname2(executable)} refuses to ` + `execute it, which a \`noexec\` mount does. Install DocBridge as a project ` + `dependency, or point the installer cache at an exec-capable directory, ` + `instead of running through \`bunx\``;
 }
-function isExecDenied(error) {
-  if (!(error instanceof Error)) {
-    return false;
+function judgeVersion(spec, runtime, version) {
+  if (runtime !== spec.runtimeId) {
+    return rejected("code_scanner_unavailable", true, `reports runtime ${runtime} ${version}, not ${spec.runtimeName}`);
   }
-  const code = error.code;
-  return code === "EACCES" || code === "EPERM";
+  const match = /^(\d+)(?:\.(\d+))?/u.exec(version);
+  if (match === null) {
+    return rejected("code_scanner_failed", true, `reported an unreadable version: ${version}`);
+  }
+  const major = Number(match[1]);
+  const minor = Number(match[2] ?? "0");
+  const [floorMajor, floorMinor] = spec.floor;
+  if (major < floorMajor || major === floorMajor && minor < floorMinor) {
+    return rejected("code_scanner_unavailable", true, `is ${spec.runtimeName} ${version}, below the ${spec.floorText} floor`);
+  }
+  return { ok: true, runtime, version };
 }
-function scannerFailedDiagnostic(language, reason) {
-  const label = languageLabel(language);
+function rejected(code, startable, reason) {
+  return { ok: false, code, startable, reason };
+}
+function failure(spec, language, code, reason) {
+  const state = code === "code_scanner_unavailable" ? "is unavailable" : "failed";
   return {
-    severity: "error",
-    code: "code_scanner_failed",
-    language,
-    target: language,
-    message: `${label} scanner worker failed: ${reason}`
+    ok: false,
+    diagnostic: {
+      severity: "error",
+      code,
+      language,
+      target: language,
+      message: `${spec.label} scanner worker ${state}: ${reason}`
+    }
   };
 }
-function languageLabel(language) {
-  return language.charAt(0).toUpperCase() + language.slice(1);
-}
 
 // 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 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));
+    });
+  };
   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
+  };
+}
+function boundWorkerAdapter(language, resolved, adapterOptions) {
+  const argv = resolved.ok ? resolved.command : [];
+  const runtime = resolved.ok ? resolved.runtime : [];
+  const adapter = {
     language,
     scanFile(filePath, content, options, context) {
-      const commandResolution = normalizeScannerCommand(command(context.projectRoot));
-      if (!commandResolution.ok) {
-        return {
-          ...emptyScan(language, filePath),
-          diagnostics: [fileScopedScannerDiagnostic(commandResolution.diagnostic, filePath)]
-        };
+      const [scan] = adapter.scanFiles([{ filePath, content }], options, context);
+      return scan ?? emptyScan(language, filePath);
+    },
+    scanFiles(files, options, context) {
+      if (files.length === 0) {
+        return [];
       }
-      const result = invokeScannerWorker({
-        schemaVersion: 1,
-        requestId: adapterOptions.requestId?.() ?? crypto.randomUUID(),
-        language,
-        projectRoot: context.projectRoot,
-        files: [{ filePath, content }],
-        options
-      }, commandResolution.command, adapterOptions.run);
-      if (result.ok) {
-        const scan = result.codeFiles[0];
-        return scan ?? emptyScan(language, filePath);
+      if (!resolved.ok) {
+        return failedBatch(language, files, resolved.diagnostic);
       }
-      return {
-        ...emptyScan(language, filePath),
-        diagnostics: [fileScopedScannerDiagnostic(result.diagnostic, filePath)]
-      };
-    }
+      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([]);
+      }
+      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);
+      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 codeFiles = [];
-  const diagnostics = [];
+  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 = {}) {
+  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 missing = batch.files.filter((_, index) => cached[index] === undefined);
+      const scanned = missing.length === 0 ? [] : await step(() => scanFilesAsync(adapter, missing, batch.options, context));
+      let next = 0;
+      const results = cached.map((hit) => hit ?? scanned[next++]);
+      fillBatch(plan, batch, results);
+      results.forEach((scan, index) => {
+        const key = keys[index];
+        if (scan !== undefined && key !== undefined && isReusableScan(scan)) {
+          cache.set(key, scan);
+        }
+      });
+    }
+    return { ...assemblePlan(plan), cache };
+  });
+}
+function scanFilesAsync(adapter, files, options, context) {
+  return adapter.scanFilesAsync?.(files, options, context) ?? settledCancelable(adapter.scanFiles(files, options, context));
+}
+var builtInAdapters = {
+  typescript: typeScriptAdapter,
+  swift: createScannerWorkerAdapter("swift", () => resolveScannerWorkerCommand("swift")),
+  dart: createScannerWorkerAdapter("dart", () => resolveScannerWorkerCommand("dart")),
+  rust: createScannerWorkerAdapter("rust", () => resolveScannerWorkerCommand("rust")),
+  go: createScannerWorkerAdapter("go", () => resolveScannerWorkerCommand("go")),
+  javascript: javaScriptAdapter,
+  python: runtimeWorkerAdapter("python"),
+  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)) });
+}
+function planCodeScan(files, codeInclude, read, onContent) {
+  const slots = [];
+  const batches = new Map;
   for (const { language, relPath } of files) {
     const result = read(relPath);
     if (!result.ok) {
-      diagnostics.push(result.diagnostic);
+      slots.push({ read: false, diagnostic: result.diagnostic });
       continue;
     }
-    options.onContent?.(relPath, result.content);
-    const adapter = options.adapters?.[language] ?? builtInAdapters[language];
-    const entry = codeInclude[language];
-    const scanOptions = entry?.visibility !== undefined ? { visibility: entry.visibility } : {};
-    const scan = adapter.scanFile(relPath, result.content, scanOptions, {
-      projectRoot
-    });
+    onContent?.(relPath, result.content);
+    let batch = batches.get(language);
+    if (batch === undefined) {
+      batch = { language, options: scanOptionsFor(codeInclude, language), files: [], slots: [] };
+      batches.set(language, batch);
+    }
+    batch.files.push({ filePath: relPath, content: result.content });
+    batch.slots.push(slots.length);
+    slots.push({ read: true, language, relPath });
+  }
+  return { slots, batches: [...batches.values()] };
+}
+function fillBatch(plan, batch, results) {
+  batch.slots.forEach((slotIndex, resultIndex) => {
+    const slot = plan.slots[slotIndex];
+    const scan = results[resultIndex];
+    if (slot?.read === true && scan !== undefined) {
+      slot.scan = scan;
+    }
+  });
+}
+function assemblePlan(plan) {
+  const codeFiles = [];
+  const diagnostics = [];
+  for (const slot of plan.slots) {
+    if (!slot.read) {
+      diagnostics.push(slot.diagnostic);
+      continue;
+    }
+    const scan = slot.scan ?? emptyScan(slot.language, slot.relPath);
     diagnostics.push(...scan.diagnostics);
     codeFiles.push(scan);
   }
   return { codeFiles, diagnostics };
 }
-var builtInAdapters = {
-  typescript: typeScriptAdapter,
-  swift: createScannerWorkerAdapter("swift", () => resolveScannerWorkerCommand("swift")),
-  dart: createScannerWorkerAdapter("dart", () => resolveScannerWorkerCommand("dart")),
-  rust: createScannerWorkerAdapter("rust", () => resolveScannerWorkerCommand("rust")),
-  go: createScannerWorkerAdapter("go", () => resolveScannerWorkerCommand("go"))
-};
+function scanOptionsFor(codeInclude, language) {
+  const visibility = codeInclude[language]?.visibility;
+  return visibility !== undefined ? { visibility } : {};
+}
+function workerRequest(language, files, options, context, adapterOptions) {
+  return {
+    schemaVersion: 1,
+    requestId: adapterOptions.requestId?.() ?? crypto.randomUUID(),
+    language,
+    projectRoot: context.projectRoot,
+    files: files.map(({ filePath, content }) => ({ filePath, content })),
+    options
+  };
+}
+function failedBatch(language, files, diagnostic) {
+  return files.map(({ filePath }) => ({
+    ...emptyScan(language, filePath),
+    diagnostics: [{ ...diagnostic, target: filePath }]
+  }));
+}
 function emptyScan(language, filePath) {
   return {
     language,
@@ -178584,11 +179528,16 @@ function emptyScan(language, filePath) {
     diagnostics: []
   };
 }
-function fileScopedScannerDiagnostic(diagnostic, filePath) {
-  return { ...diagnostic, target: filePath };
-}
-function normalizeScannerCommand(value) {
-  return Array.isArray(value) ? { ok: true, command: value } : value;
+function workerCommand(value) {
+  if (Array.isArray(value)) {
+    return { ok: true, command: value, stripEnv: [], runtime: [] };
+  }
+  return value.ok ? {
+    ok: true,
+    command: value.command,
+    stripEnv: value.stripEnv ?? [],
+    runtime: value.runtime ?? []
+  } : value;
 }
 
 // src/scan/markdown/markdown.ts
@@ -178823,6 +179772,42 @@ 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 !== "") {
+    options.onConfigurationChange?.();
+  }
+  const codeScan = scanCodeFilesAsync(options.projectRoot, inputs.codeFiles, inputs.config.include.code, inputs.readFile, {
+    ...codeScanOptions(inputs, options),
+    ...sameConfiguration ? { cache: options.cache.entries } : {}
+  });
+  const docReads = readDocFiles(inputs, options);
+  return cancelableSequence(async (step) => {
+    const { cache, ...code } = await step(codeScan);
+    const scan = finishProjectScan(inputs, code, docReads, true);
+    return {
+      ok: true,
+      scan,
+      cache: { fingerprint, entries: cache }
+    };
+  });
+}
+function loadProjectScan(options, keepContent) {
   const configResult = loadConfig(options.projectRoot);
   if (!configResult.ok) {
     return { ok: false, diagnostics: configResult.diagnostics };
@@ -178832,32 +179817,51 @@ function scanProject(options) {
     return { ok: false, diagnostics: [...configResult.diagnostics, ...manifestResult.diagnostics] };
   }
   const collectCode = options.collectCode ?? collectCodeFiles;
-  const collectDocs = options.collectDocs ?? collectFiles;
-  const readFile = options.readFile ?? ((relPath) => readManagedFile(options.projectRoot, relPath));
-  const diagnostics = [
-    ...configResult.diagnostics,
-    ...manifestResult.diagnostics
-  ];
-  const contentByFile = options.keepContent ? new Map : undefined;
-  const codeScan = scanCodeFiles(options.projectRoot, collectCode(options.projectRoot, configResult.config.include.code), configResult.config.include.code, readFile, {
+  return {
+    ok: true,
+    inputs: {
+      config: configResult.config,
+      manifest: manifestResult.manifest,
+      diagnostics: [...configResult.diagnostics, ...manifestResult.diagnostics],
+      codeFiles: collectCode(options.projectRoot, configResult.config.include.code),
+      readFile: options.readFile ?? ((relPath) => readManagedFile(options.projectRoot, relPath)),
+      contentByFile: keepContent ? new Map : undefined
+    }
+  };
+}
+function codeScanOptions(inputs, options) {
+  const { contentByFile } = inputs;
+  const { scanners } = inputs.config;
+  return {
     ...contentByFile === undefined ? {} : { onContent: (relPath, content) => contentByFile.set(relPath, content) },
-    ...options.adapters === undefined ? {} : { adapters: options.adapters }
+    ...options.adapters === undefined ? {} : { adapters: options.adapters },
+    ...scanners === undefined ? {} : { scanners }
+  };
+}
+function readDocFiles(inputs, options) {
+  const collectDocs = options.collectDocs ?? collectFiles;
+  return collectDocs(options.projectRoot, inputs.config.include.docs).map((relPath) => {
+    const read = inputs.readFile(relPath);
+    if (read.ok) {
+      inputs.contentByFile?.set(relPath, read.content);
+    }
+    return { relPath, read };
   });
-  diagnostics.push(...codeScan.diagnostics);
+}
+function finishProjectScan(inputs, codeScan, docReads, buildGraph) {
+  const diagnostics = [...inputs.diagnostics, ...codeScan.diagnostics];
   const docFiles = [];
-  for (const relPath of collectDocs(options.projectRoot, configResult.config.include.docs)) {
-    const read = readFile(relPath);
+  for (const { relPath, read } of docReads) {
     if (!read.ok) {
       diagnostics.push(read.diagnostic);
       continue;
     }
-    contentByFile?.set(relPath, read.content);
     const scan2 = scanMarkdown(relPath, read.content);
     diagnostics.push(...scan2.diagnostics);
     docFiles.push(scan2);
   }
   const applied = applyLinkManifest({
-    manifest: manifestResult.manifest,
+    manifest: inputs.manifest,
     codeFiles: codeScan.codeFiles,
     docFiles,
     scanDiagnostics: diagnostics
@@ -178869,25 +179873,26 @@ function scanProject(options) {
     docFiles: applied.docFiles,
     diagnostics
   };
-  if (contentByFile !== undefined) {
-    scan.contentByFile = contentByFile;
+  if (inputs.contentByFile !== undefined) {
+    scan.contentByFile = inputs.contentByFile;
   }
-  if (options.buildGraph === true) {
+  if (buildGraph === true) {
     scan.graph = buildLinkGraph(codeFiles, applied.docFiles);
   }
-  return {
-    ok: true,
-    scan
-  };
+  return scan;
 }
 
 // src/lsp/project.ts
 class Project {
   projectRoot;
+  options;
   overlay = new Map;
+  overlayRevision = 0;
   current = emptyState();
-  constructor(projectRoot) {
+  cache = emptyCodeScanCache();
+  constructor(projectRoot, options = {}) {
     this.projectRoot = projectRoot;
+    this.options = options;
   }
   get root() {
     return this.projectRoot;
@@ -178897,48 +179902,57 @@ class Project {
   }
   setOverlay(relPath, content) {
     this.overlay.set(relPath, content);
+    this.overlayRevision += 1;
   }
   clearOverlay(relPath) {
     this.overlay.delete(relPath);
+    this.overlayRevision += 1;
   }
   resolve() {
     const outcome = scanProject({
-      projectRoot: this.projectRoot,
-      collectCode: (_projectRoot, include) => this.collectCode(include),
-      collectDocs: (_projectRoot, patterns) => this.collect(patterns, false),
-      readFile: (relPath) => this.readContent(relPath),
+      ...this.scanSources(this.overlay),
       buildGraph: true,
       keepContent: true
     });
-    if (!outcome.ok) {
-      this.current = {
-        ...emptyState(),
-        diagnostics: sortDiagnostics(outcome.diagnostics)
-      };
+    this.current = resolvedState(outcome);
+    return this.current;
+  }
+  resolveAsync() {
+    const revision = this.overlayRevision;
+    const scan = scanProjectAsync({
+      ...this.scanSources(new Map(this.overlay)),
+      cache: this.cache,
+      onConfigurationChange: clearRuntimeProbeCache
+    });
+    let cancelled = false;
+    const promise = scan.promise.then((outcome) => {
+      if (cancelled || revision !== this.overlayRevision) {
+        throw abortError();
+      }
+      if (outcome.ok) {
+        this.cache = outcome.cache;
+      }
+      this.current = resolvedState(outcome);
       return this.current;
-    }
-    const {
-      codeFiles,
-      docFiles,
-      diagnostics: scanDiagnostics,
-      contentByFile,
-      graph
-    } = outcome.scan;
-    const relationship = resolveLinks({
-      codeFiles,
-      docFiles,
-      scanDiagnostics,
-      audit: false
     });
-    this.current = {
-      graph,
-      index: buildPositionIndex(graph),
-      diagnostics: sortDiagnostics([...scanDiagnostics, ...relationship]),
-      contentByFile
+    return {
+      promise,
+      cancel() {
+        cancelled = true;
+        scan.cancel();
+      }
     };
-    return this.current;
   }
-  collectCode(codeInclude) {
+  scanSources(overlay) {
+    return {
+      projectRoot: this.projectRoot,
+      collectCode: (_projectRoot, include) => this.collectCode(include, overlay),
+      collectDocs: (_projectRoot, patterns) => this.collectDocs(patterns, overlay),
+      readFile: (relPath) => this.readContent(relPath, overlay),
+      ...this.options.adapters === undefined ? {} : { adapters: this.options.adapters }
+    };
+  }
+  collectCode(codeInclude, overlay) {
     const onDisk = collectCodeFiles(this.projectRoot, codeInclude);
     const seen = new Set(onDisk.map((file) => file.relPath));
     const all = [...onDisk];
@@ -178947,11 +179961,11 @@ class Project {
       if (entry === undefined) {
         continue;
       }
-      for (const relPath of this.overlay.keys()) {
+      for (const relPath of overlay.keys()) {
         if (seen.has(relPath)) {
           continue;
         }
-        if (language === "typescript" && relPath.endsWith(".d.ts")) {
+        if (hasExcludedSuffix(language, relPath)) {
           continue;
         }
         if (entry.patterns.some((pattern) => matchGlob(pattern, relPath))) {
@@ -178962,22 +179976,19 @@ class Project {
     }
     return all.toSorted((left, right) => comparePaths(left.relPath, right.relPath));
   }
-  readContent(relPath) {
-    const overlaid = this.overlay.get(relPath);
+  readContent(relPath, overlay) {
+    const overlaid = overlay.get(relPath);
     if (overlaid !== undefined) {
       return { ok: true, content: overlaid };
     }
     return readManagedFile(this.projectRoot, relPath);
   }
-  collect(patterns, isCode) {
+  collectDocs(patterns, overlay) {
     const paths = new Set(collectFiles(this.projectRoot, patterns));
-    for (const relPath of this.overlay.keys()) {
+    for (const relPath of overlay.keys()) {
       if (paths.has(relPath)) {
         continue;
       }
-      if (isCode && relPath.endsWith(".d.ts")) {
-        continue;
-      }
       if (patterns.some((pattern) => matchGlob(pattern, relPath))) {
         paths.add(relPath);
       }
@@ -178985,6 +179996,19 @@ class Project {
     return [...paths].toSorted(comparePaths);
   }
 }
+function resolvedState(outcome) {
+  if (!outcome.ok) {
+    return { ...emptyState(), diagnostics: sortDiagnostics(outcome.diagnostics) };
+  }
+  const { codeFiles, docFiles, diagnostics: scanDiagnostics, contentByFile, graph } = outcome.scan;
+  const relationship = resolveLinks({ codeFiles, docFiles, scanDiagnostics, audit: false });
+  return {
+    graph,
+    index: buildPositionIndex(graph),
+    diagnostics: sortDiagnostics([...scanDiagnostics, ...relationship]),
+    contentByFile
+  };
+}
 function emptyState() {
   const graph = buildLinkGraph([], []);
   return {
@@ -178995,6 +180019,74 @@ function emptyState() {
   };
 }
 
+// src/lsp/scheduler.ts
+class RescanScheduler {
+  options;
+  generation = 0;
+  dirty = false;
+  debounce;
+  active;
+  stopped = false;
+  constructor(options) {
+    this.options = options;
+  }
+  request(when) {
+    if (this.stopped) {
+      return;
+    }
+    this.generation += 1;
+    this.dirty = true;
+    this.active?.task.cancel();
+    this.clearDebounce();
+    if (when === "debounced") {
+      const handle = this.options.timers.setTimeout(() => {
+        this.debounce = undefined;
+        this.startIfReady();
+      }, this.options.debounceMs);
+      this.debounce = { handle };
+      return;
+    }
+    this.startIfReady();
+  }
+  stop() {
+    this.stopped = true;
+    this.clearDebounce();
+    this.active?.task.cancel();
+  }
+  startIfReady() {
+    if (this.stopped || !this.dirty || this.active !== undefined || this.debounce !== undefined) {
+      return;
+    }
+    this.dirty = false;
+    const active = { generation: this.generation, task: this.options.scan() };
+    this.active = active;
+    active.task.promise.then((state) => this.settle(active, () => this.accept(active, state)), (error) => this.settle(active, () => this.fail(error)));
+  }
+  settle(active, report) {
+    if (this.active === active) {
+      this.active = undefined;
+    }
+    report();
+    this.startIfReady();
+  }
+  accept(active, state) {
+    if (!this.stopped && active.generation === this.generation) {
+      this.options.onState(state);
+    }
+  }
+  fail(error) {
+    if (!isAbortError(error)) {
+      this.options.onError(error);
+    }
+  }
+  clearDebounce() {
+    if (this.debounce !== undefined) {
+      this.options.timers.clearTimeout(this.debounce.handle);
+      this.debounce = undefined;
+    }
+  }
+}
+
 // src/lsp/transport.ts
 var HEADER_SEPARATOR = `\r
 \r
@@ -179062,6 +180154,10 @@ function parseContentLength(headerText) {
 }
 
 // src/lsp/server.ts
+var GLOBAL_TIMERS = {
+  setTimeout: (callback, ms) => setTimeout(callback, ms),
+  clearTimeout: (handle) => clearTimeout(handle)
+};
 var CAPABILITIES = {
   textDocumentSync: 1,
   hoverProvider: true,
@@ -179072,44 +180168,55 @@ var CAPABILITIES = {
 class Server {
   send;
   project = null;
+  scheduler = null;
   openFiles = new Set;
-  dirty = true;
-  timer = null;
   shuttingDown = false;
   makeProject;
   debounceMs;
   onExit;
+  timers;
+  onScanError;
   constructor(send, options = {}) {
     this.send = send;
     this.makeProject = options.makeProject ?? ((root) => new Project(root));
     this.debounceMs = options.debounceMs ?? 50;
     this.onExit = options.onExit ?? ((code) => process.exit(code));
+    this.timers = options.timers ?? GLOBAL_TIMERS;
+    this.onScanError = options.onScanError ?? ((error) => process.stderr.write(`docbridge lsp: scan failed: ${reasonOf(error)}
+`));
   }
   handle(message) {
     switch (message.method) {
       case "initialize":
         this.respond(message.id, { capabilities: CAPABILITIES });
-        this.project = this.makeProject(resolveRoot(message.params));
+        this.start(this.makeProject(resolveRoot(message.params)));
         break;
       case "initialized":
-        this.flush();
+        this.scheduler?.request("now");
         break;
       case "shutdown":
         this.shuttingDown = true;
-        this.clearTimer();
+        this.scheduler?.stop();
         this.respond(message.id, null);
         break;
       case "exit":
+        this.scheduler?.stop();
         this.onExit(this.shuttingDown ? 0 : 1);
         break;
       case "textDocument/didOpen":
-        this.onDidOpen(message.params);
+        if (!this.shuttingDown) {
+          this.onDidOpen(message.params);
+        }
         break;
       case "textDocument/didChange":
-        this.onDidChange(message.params);
+        if (!this.shuttingDown) {
+          this.onDidChange(message.params);
+        }
         break;
       case "textDocument/didClose":
-        this.onDidClose(message.params);
+        if (!this.shuttingDown) {
+          this.onDidClose(message.params);
+        }
         break;
       case "textDocument/hover":
         this.respond(message.id, this.onHover(message.params));
@@ -179126,6 +180233,16 @@ class Server {
         }
     }
   }
+  start(project) {
+    this.project = project;
+    this.scheduler = new RescanScheduler({
+      scan: () => project.resolveAsync(),
+      onState: (state) => this.publishOpenFiles(state),
+      onError: this.onScanError,
+      debounceMs: this.debounceMs,
+      timers: this.timers
+    });
+  }
   onDidOpen(params) {
     const doc = textDocument(params);
     const rel = this.relPath(doc?.uri);
@@ -179135,8 +180252,7 @@ class Server {
     }
     this.openFiles.add(rel);
     this.project.setOverlay(rel, text);
-    this.dirty = true;
-    this.flush();
+    this.scheduler?.request("now");
   }
   onDidChange(params) {
     const record = params;
@@ -179147,7 +180263,7 @@ class Server {
       return;
     }
     this.project.setOverlay(rel, text);
-    this.scheduleFlush();
+    this.scheduler?.request("debounced");
   }
   onDidClose(params) {
     const doc = textDocument(params);
@@ -179157,9 +180273,8 @@ class Server {
     }
     this.openFiles.delete(rel);
     this.project.clearOverlay(rel);
-    this.dirty = true;
     this.publish(rel, []);
-    this.flush();
+    this.scheduler?.request("now");
   }
   onHover(params) {
     const located = this.locate(params);
@@ -179198,7 +180313,6 @@ class Server {
     if (rel === undefined || this.project === null || typeof position?.line !== "number" || typeof position?.character !== "number") {
       return null;
     }
-    this.flush();
     return {
       state: this.project.state,
       rel,
@@ -179206,28 +180320,14 @@ class Server {
       position: fromLspPosition({ line: position.line, character: position.character })
     };
   }
-  scheduleFlush() {
-    this.dirty = true;
-    this.clearTimer();
-    this.timer = setTimeout(() => {
-      this.timer = null;
-      this.flush();
-    }, this.debounceMs);
-  }
-  flush() {
-    this.clearTimer();
-    if (this.project === null || !this.dirty) {
-      return;
-    }
-    this.dirty = false;
-    const state = this.project.resolve();
+  publishOpenFiles(state) {
     for (const rel of this.openFiles) {
       const content = state.contentByFile.get(rel) ?? "";
       this.publish(rel, diagnosticsForFile(state.diagnostics, rel, content));
     }
   }
   publish(rel, diagnostics) {
-    if (this.project === null) {
+    if (this.project === null || this.shuttingDown) {
       return;
     }
     this.send({
@@ -179248,12 +180348,6 @@ class Server {
     }
     this.send({ jsonrpc: "2.0", id, result });
   }
-  clearTimer() {
-    if (this.timer !== null) {
-      clearTimeout(this.timer);
-      this.timer = null;
-    }
-  }
 }
 function resolveRoot(params) {
   const record = params;
@@ -179347,7 +180441,7 @@ function check(options) {
 }
 
 // src/query/related.ts
-import { isAbsolute as isAbsolute2, relative as relative2 } from "node:path";
+import { isAbsolute as isAbsolute3, relative as relative2 } from "node:path";
 function normalizeChangedPaths(projectRoot, paths) {
   const normalized = new Set;
   for (const raw of paths) {
@@ -179355,7 +180449,7 @@ function normalizeChangedPaths(projectRoot, paths) {
     if (trimmed === "") {
       continue;
     }
-    const relativized = isAbsolute2(trimmed) ? relative2(projectRoot, trimmed) : trimmed;
+    const relativized = isAbsolute3(trimmed) ? relative2(projectRoot, trimmed) : trimmed;
     normalized.add(relativized.replace(/^(\.\/)+/, ""));
   }
   return [...normalized];
@@ -179777,7 +180871,7 @@ function comparePairs(left, right) {
 // src/setup/update-cache.ts
 import { mkdirSync as mkdirSync2, readFileSync as readFileSync4, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname as dirname3, join as join7 } from "node:path";
+import { dirname as dirname3, join as join8 } from "node:path";
 var UPDATE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
 var UPDATE_CACHE_SCHEMA_VERSION = 1;
 function resolveUpdateCachePath(env = process.env, home = homedir()) {
@@ -179785,8 +180879,8 @@ function resolveUpdateCachePath(env = process.env, home = homedir()) {
   if (explicit !== undefined && explicit.length > 0) {
     return explicit;
   }
-  const cacheRoot = env.XDG_CACHE_HOME !== undefined && env.XDG_CACHE_HOME.length > 0 ? env.XDG_CACHE_HOME : join7(home, ".cache");
-  return join7(cacheRoot, "docbridge", "update-check.json");
+  const cacheRoot = env.XDG_CACHE_HOME !== undefined && env.XDG_CACHE_HOME.length > 0 ? env.XDG_CACHE_HOME : join8(home, ".cache");
+  return join8(cacheRoot, "docbridge", "update-check.json");
 }
 function readUpdateCache(path) {
   let rawText;
@@ -180030,7 +181124,7 @@ function isEnabledFlag(value) {
 
 // src/cli/docs.ts
 import { readdirSync as readdirSync2, readFileSync as readFileSync5 } from "node:fs";
-import { join as join8 } from "node:path";
+import { join as join9 } from "node:path";
 
 // src/cli/errors.ts
 class CliError extends Error {
@@ -180201,7 +181295,7 @@ function parseDocument(name, source) {
   };
 }
 function createFileDocumentationReader(packageRoot) {
-  const docsRoot = join8(packageRoot, "docs", "user");
+  const docsRoot = join9(packageRoot, "docs", "user");
   function documents() {
     let fileNames;
     try {
@@ -180214,7 +181308,7 @@ function createFileDocumentationReader(packageRoot) {
     }
     return fileNames.map((fileName) => {
       const name = fileName.slice(0, -".md".length);
-      return parseDocument(name, readFileSync5(join8(docsRoot, fileName), "utf8"));
+      return parseDocument(name, readFileSync5(join9(docsRoot, fileName), "utf8"));
     });
   }
   return {
@@ -180611,12 +181705,12 @@ function hasHelpFlag(args) {
 }
 
 // src/cli/init.ts
-import { readFileSync as readFileSync8, statSync as statSync3, writeFileSync as writeFileSync2 } from "node:fs";
-import { join as join12, resolve as resolve2 } from "node:path";
+import { readFileSync as readFileSync8, statSync as statSync4, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join13, resolve as resolve3 } from "node:path";
 
 // src/setup/init-discovery.ts
-import { existsSync as existsSync3, readdirSync as readdirSync3, statSync as statSync2 } from "node:fs";
-import { basename, dirname as dirname4, join as join9 } from "node:path";
+import { existsSync as existsSync4, readdirSync as readdirSync3, statSync as statSync3 } from "node:fs";
+import { basename, dirname as dirname4, join as join10 } from "node:path";
 var HIGH_CONFIDENCE_DIR_NAMES = new Set([
   "docs/specs",
   "specs",
@@ -180646,22 +181740,42 @@ var EXCLUDED_DIR_SEGMENTS = new Set([
   "contributing"
 ]);
 var IGNORED_WALK_SEGMENTS = new Set(["node_modules", ".git", "dist", "build"]);
-var TYPESCRIPT_PATTERNS = [
-  "src/**/*.ts",
-  "lib/**/*.ts",
-  "packages/*/src/**/*.ts",
-  "apps/*/src/**/*.ts"
-];
+var SCRIPT_SOURCE_ROOTS = ["src", "lib", "packages/*/src", "apps/*/src"];
+var TYPESCRIPT_PATTERNS = scriptPatterns("typescript");
+var JAVASCRIPT_PATTERNS = scriptPatterns("javascript");
 var SWIFT_PATTERNS = ["Sources/**/*.swift", "*/Sources/**/*.swift"];
 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,
   dart: DART_PATTERNS,
   rust: RUST_PATTERNS,
-  go: GO_PATTERNS
+  go: GO_PATTERNS,
+  javascript: JAVASCRIPT_PATTERNS,
+  ruby: RUBY_PATTERNS,
+  java: JAVA_PATTERNS
+};
+var EXCLUDED_CODE_SEGMENTS = {
+  typescript: ["__tests__", "tests", "test"],
+  swift: ["Tests", "tests"],
+  dart: ["test"],
+  rust: ["target", "tests", "benches", "examples"],
+  go: ["vendor", "testdata"],
+  javascript: ["__tests__", "tests", "test"],
+  python: ["tests", "venv", "dist", "site-packages"],
+  ruby: ["spec", "test", "vendor"],
+  java: ["target", "src/test"]
+};
+var TEST_FILE_PATTERNS = {
+  typescript: /\.(?:test|spec)\.[cm]?tsx?$/u,
+  swift: /tests\.swift$/u,
+  dart: /_test\.dart$/u,
+  go: /_test\.go$/u,
+  javascript: /\.(?:test|spec)\.[cm]?jsx?$/u
 };
 function discoverRepository(projectRoot) {
   return {
@@ -180745,8 +181859,8 @@ function discoverCodeScope(projectRoot) {
   };
 }
 function discoverAgentTarget(projectRoot) {
-  const hasAgentsDir = existsSync3(join9(projectRoot, ".agents"));
-  const hasClaudeDir = existsSync3(join9(projectRoot, ".claude"));
+  const hasAgentsDir = existsSync4(join10(projectRoot, ".agents"));
+  const hasClaudeDir = existsSync4(join10(projectRoot, ".claude"));
   let defaultTarget = "none";
   let recommendedTarget = "none";
   let message;
@@ -180773,7 +181887,7 @@ function discoverAgentTarget(projectRoot) {
   };
 }
 function collectMarkdownFiles(projectRoot, currentDir = ".") {
-  const absoluteDir = join9(projectRoot, currentDir);
+  const absoluteDir = join10(projectRoot, currentDir);
   let entries;
   try {
     entries = readdirSync3(absoluteDir);
@@ -180787,10 +181901,10 @@ function collectMarkdownFiles(projectRoot, currentDir = ".") {
     if (segments.some((segment) => IGNORED_WALK_SEGMENTS.has(segment) || segment.startsWith("."))) {
       continue;
     }
-    const absolutePath = join9(projectRoot, relPath);
+    const absolutePath = join10(projectRoot, relPath);
     let stats;
     try {
-      stats = statSync2(absolutePath);
+      stats = statSync3(absolutePath);
     } catch {
       continue;
     }
@@ -180828,8 +181942,23 @@ function scoreDocsDirectory(directory) {
   }
   return score;
 }
+function scriptPatterns(language) {
+  return SCRIPT_SOURCE_ROOTS.flatMap((root) => LANGUAGE_SUFFIXES[language].map((suffix) => `${root}/**/*${suffix}`));
+}
 function activeCodePatterns(projectRoot, language) {
-  return LANGUAGE_PATTERNS[language].filter((pattern) => countCodeFiles(projectRoot, [pattern], language) > 0);
+  const candidates = language === "python" ? pythonPatterns(projectRoot) : LANGUAGE_PATTERNS[language];
+  const active = candidates.filter((pattern) => countCodeFiles(projectRoot, [pattern], language) > 0);
+  return language === "java" ? active.slice(0, 1) : active;
+}
+function pythonPatterns(projectRoot) {
+  let entries;
+  try {
+    entries = readdirSync3(projectRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const packages = entries.filter((entry) => entry.isDirectory() && entry.name !== "src" && !entry.name.startsWith(".") && !IGNORED_WALK_SEGMENTS.has(entry.name) && existsSync4(join10(projectRoot, entry.name, "__init__.py"))).map((entry) => entry.name).toSorted();
+  return ["src/**/*.py", ...packages.map((name) => `${name}/**/*.py`)];
 }
 function countCodeFiles(projectRoot, patterns, language) {
   const seen = new Set;
@@ -180845,33 +181974,9 @@ function countCodeFiles(projectRoot, patterns, language) {
 function isExcludedCodeFile(filePath, language) {
   const lower = filePath.toLowerCase();
   const segments = filePath.split("/");
-  if (language === "typescript") {
-    if (lower.endsWith(".d.ts")) {
-      return true;
-    }
-    if (lower.endsWith(".test.ts") || lower.endsWith(".spec.ts") || segments.includes("__tests__") || segments.includes("tests") || segments.includes("test")) {
-      return true;
-    }
-  }
-  if (language === "swift") {
-    if (lower.endsWith("tests.swift") || segments.includes("Tests") || segments.includes("tests")) {
-      return true;
-    }
-  }
-  if (language === "dart") {
-    if (lower.endsWith("_test.dart") || segments.includes("test")) {
-      return true;
-    }
-  }
-  if (language === "rust") {
-    if (segments.includes("target") || segments.includes("tests") || segments.includes("benches") || segments.includes("examples")) {
-      return true;
-    }
-  }
-  if (language === "go") {
-    if (lower.endsWith("_test.go") || segments.includes("vendor") || segments.includes("testdata")) {
-      return true;
-    }
+  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()))) {
     return true;
@@ -180880,17 +181985,17 @@ function isExcludedCodeFile(filePath, language) {
 }
 
 // src/setup/init-plan.ts
-import { existsSync as existsSync4, readdirSync as readdirSync5, readFileSync as readFileSync7 } from "node:fs";
-import { join as join11, relative as relative3 } from "node:path";
+import { existsSync as existsSync5, readdirSync as readdirSync5, readFileSync as readFileSync7 } from "node:fs";
+import { join as join12, relative as relative3 } from "node:path";
 
 // src/setup/skill-assets.ts
 import { cpSync, lstatSync as lstatSync2, mkdirSync as mkdirSync3, readdirSync as readdirSync4, readFileSync as readFileSync6, rmSync } from "node:fs";
-import { join as join10 } from "node:path";
+import { join as join11 } from "node:path";
 function classifyManagedPath(projectRoot, relativePath) {
   const segments = relativePath.split(/[/\\]/).filter((segment) => segment.length > 0);
   let current = projectRoot;
   for (const [index, segment] of segments.entries()) {
-    current = join10(current, segment);
+    current = join11(current, segment);
     const isLast = index === segments.length - 1;
     let stats;
     try {
@@ -180937,7 +182042,7 @@ function compareSkillTree(installedDir, templateDir) {
       continue;
     }
     installedFiles.delete(file);
-    if (readFileOrUndefined(join10(installedDir, file)) !== readFileOrUndefined(join10(templateDir, file))) {
+    if (readFileOrUndefined(join11(installedDir, file)) !== readFileOrUndefined(join11(templateDir, file))) {
       modified.push(file);
     }
   }
@@ -180948,7 +182053,7 @@ function applySkillOperation(projectRoot, packageRoot, operation) {
     return;
   }
   const kind = classifyManagedPath(projectRoot, operation.path);
-  const destinationDir = join10(projectRoot, operation.path);
+  const destinationDir = join11(projectRoot, operation.path);
   if (operation.action === "remove") {
     if (kind === "directory") {
       rmSync(destinationDir, { recursive: true, force: true });
@@ -180966,7 +182071,7 @@ function applySkillOperation(projectRoot, packageRoot, operation) {
     rmSync(destinationDir, { recursive: true, force: true });
   }
   mkdirSync3(destinationDir, { recursive: true });
-  cpSync(join10(packageRoot, "templates", "skills", skillName), destinationDir, {
+  cpSync(join11(packageRoot, "templates", "skills", skillName), destinationDir, {
     recursive: true,
     force: true
   });
@@ -180974,7 +182079,7 @@ function applySkillOperation(projectRoot, packageRoot, operation) {
 function collectSkillFiles(root, prefix, files) {
   let entries;
   try {
-    entries = readdirSync4(join10(root, prefix), { withFileTypes: true });
+    entries = readdirSync4(join11(root, prefix), { withFileTypes: true });
   } catch {
     return;
   }
@@ -181085,14 +182190,14 @@ function buildConfigFromScope(scope) {
   };
 }
 function listDistributableSkills(packageRoot) {
-  const skillsRoot = join11(packageRoot, "templates", "skills");
+  const skillsRoot = join12(packageRoot, "templates", "skills");
   let entries;
   try {
     entries = readdirSync5(skillsRoot);
   } catch {
     return [];
   }
-  return entries.filter((entry) => entry.startsWith("docbridge")).filter((entry) => existsSync4(join11(skillsRoot, entry, "SKILL.md"))).toSorted();
+  return entries.filter((entry) => entry.startsWith("docbridge")).filter((entry) => existsSync5(join12(skillsRoot, entry, "SKILL.md"))).toSorted();
 }
 function formatInitPlan(plan) {
   const lines = [];
@@ -181197,7 +182302,7 @@ function planSkillOperations(input) {
       if (!availableSkills.has(skillName)) {
         continue;
       }
-      const destinationDir = join11(input.projectRoot, destination, skillName);
+      const destinationDir = join12(input.projectRoot, destination, skillName);
       const path = relative3(input.projectRoot, destinationDir);
       const kind = classifyManagedPath(input.projectRoot, path);
       if (kind !== "absent" && kind !== "directory") {
@@ -181236,7 +182341,7 @@ function planLegacySkillOperations(input) {
   const operations = [];
   const leftover = [];
   for (const skillName of LEGACY_SKILL_NAMES) {
-    const destinationDir = join11(input.projectRoot, input.destination, skillName);
+    const destinationDir = join12(input.projectRoot, input.destination, skillName);
     const path = relative3(input.projectRoot, destinationDir);
     const kind = classifyManagedPath(input.projectRoot, path);
     if (kind === "absent") {
@@ -181316,7 +182421,7 @@ function resolveInitWithAgentTarget(discovery, options) {
   return { target: discovery.agent.defaultTarget, error: undefined };
 }
 function readExistingConfig(projectRoot) {
-  const configPath = join11(projectRoot, CONFIG_FILE_NAME2);
+  const configPath = join12(projectRoot, CONFIG_FILE_NAME2);
   let rawText;
   try {
     rawText = readFileSync7(configPath, "utf8");
@@ -181567,7 +182672,7 @@ function executePlan(projectRoot, plan, packageRoot) {
   }
 }
 function executeFileOperation(projectRoot, operation) {
-  const absolutePath = join12(projectRoot, operation.path);
+  const absolutePath = join13(projectRoot, operation.path);
   if (operation.action === "create" && operation.content !== undefined) {
     writeFileSync2(absolutePath, operation.content, "utf8");
   }
@@ -181576,10 +182681,10 @@ function executeFileOperation(projectRoot, operation) {
   }
 }
 function resolveProjectRoot(root, command) {
-  const projectRoot = resolve2(root);
+  const projectRoot = resolve3(root);
   let stats;
   try {
-    stats = statSync3(projectRoot);
+    stats = statSync4(projectRoot);
   } catch {
     throw new InitCliError(`Root path does not exist: ${root}`, rootPathGuidance(command));
   }
@@ -181614,24 +182719,12 @@ ${block.content}`;
   const fence = codeFence(block.content);
   return `${header}
 
-${fence}${fenceLanguage(block.language)}
+${fence}${fenceLanguage(block)}
 ${block.content}
 ${fence}`;
 }
-function fenceLanguage(language) {
-  if (language === "swift") {
-    return "swift";
-  }
-  if (language === "dart") {
-    return "dart";
-  }
-  if (language === "rust") {
-    return "rust";
-  }
-  if (language === "go") {
-    return "go";
-  }
-  return "ts";
+function fenceLanguage(block) {
+  return block.language === undefined ? "ts" : codeFenceLanguage(block.language, block.filePath);
 }
 function codeFence(content) {
   let longestRun = 0;
@@ -181763,12 +182856,12 @@ function formatRelatedSummary(summary) {
 }
 
 // src/cli/upgrade.ts
-import { statSync as statSync4 } from "node:fs";
-import { resolve as resolve3 } from "node:path";
+import { statSync as statSync5 } from "node:fs";
+import { resolve as resolve4 } from "node:path";
 
 // src/setup/upgrade-plan.ts
-import { existsSync as existsSync5 } from "node:fs";
-import { join as join13, relative as relative4 } from "node:path";
+import { existsSync as existsSync6 } from "node:fs";
+import { join as join14, relative as relative4 } from "node:path";
 var MANAGED_SKILL_NAME = INIT_SKILL_NAMES[0];
 function reportCliVersion(currentVersion, latest) {
   if (latest.status !== "ok") {
@@ -181786,7 +182879,7 @@ function resolveUpgradeAgentTarget(discovery, explicitTarget) {
   return explicitTarget ?? discovery.agent.defaultTarget;
 }
 function inspectManagedSkill(input) {
-  const destinationDir = join13(input.projectRoot, input.destination, MANAGED_SKILL_NAME);
+  const destinationDir = join14(input.projectRoot, input.destination, MANAGED_SKILL_NAME);
   const path = toRootRelative(input.projectRoot, destinationDir);
   const empty = {
     destination: input.destination,
@@ -181802,7 +182895,7 @@ function inspectManagedSkill(input) {
   if (!input.templateAvailable) {
     return { ...empty, state: "template-missing" };
   }
-  const comparison = compareSkillTree(destinationDir, join13(input.packageRoot, "templates", "skills", MANAGED_SKILL_NAME));
+  const comparison = compareSkillTree(destinationDir, join14(input.packageRoot, "templates", "skills", MANAGED_SKILL_NAME));
   const drifted = comparison.modified.length > 0 || comparison.missing.length > 0 || comparison.extra.length > 0;
   return {
     destination: input.destination,
@@ -181816,13 +182909,13 @@ function inspectManagedSkill(input) {
 function inspectLegacySkills(projectRoot, destination) {
   const reports = [];
   for (const skillName of LEGACY_SKILL_NAMES) {
-    const destinationDir = join13(projectRoot, destination, skillName);
+    const destinationDir = join14(projectRoot, destination, skillName);
     const path = toRootRelative(projectRoot, destinationDir);
     const kind = classifyManagedPath(projectRoot, path);
     if (kind === "absent") {
       continue;
     }
-    if (kind === "symlinked-parent" && !existsSync5(destinationDir)) {
+    if (kind === "symlinked-parent" && !existsSync6(destinationDir)) {
       continue;
     }
     reports.push({ path, kind });
@@ -182086,10 +183179,10 @@ function parseAgentTarget(value) {
   return value;
 }
 function resolveProjectRoot2(root) {
-  const projectRoot = resolve3(root);
+  const projectRoot = resolve4(root);
   let stats;
   try {
-    stats = statSync4(projectRoot);
+    stats = statSync5(projectRoot);
   } catch {
     throw new CliError(`Root path does not exist: ${root}`, rootPathGuidance("upgrade"));
   }
@@ -182114,10 +183207,10 @@ function parseGraphOptions(args) {
   return parseCommandOptions("graph", args);
 }
 function resolveProjectRoot3(root, command) {
-  const projectRoot = resolve4(root);
+  const projectRoot = resolve5(root);
   let stats;
   try {
-    stats = statSync5(projectRoot);
+    stats = statSync6(projectRoot);
   } catch {
     throw new CliError(`Root path does not exist: ${root}`, rootPathGuidance(command));
   }
@@ -182241,7 +183334,7 @@ function repairGuidanceFor(diagnostics, projectRoot) {
   if (invalid.length === 0) {
     return;
   }
-  return existsSync6(join14(projectRoot, CONFIG_FILE_NAME)) ? configRepairGuidance() : configSetupGuidance();
+  return existsSync7(join15(projectRoot, CONFIG_FILE_NAME)) ? configRepairGuidance() : configSetupGuidance();
 }
 function unknownCommandGuidance(command) {
   const suggestion = nearestMatch(command, SUBCOMMANDS);
@@ -182316,7 +183409,7 @@ function run(argv, io = {
 function rootOptionOf(argv, currentDirectory) {
   const flagIndex = argv.indexOf("--root");
   const value = flagIndex === -1 ? undefined : argv[flagIndex + 1];
-  return value === undefined ? currentDirectory : resolve4(currentDirectory, value);
+  return value === undefined ? currentDirectory : resolve5(currentDirectory, value);
 }
 function writeUpdateNotice(argv, io, initRuntime, cliRuntime) {
   const latest = cliRuntime.latest;