Auto-discover driver configs + workspace cross-index (references, defs, symbols)

Two features, one shared foundation:

1. Driver config auto-discovery. Mudlib checkouts usually carry their
   config at config.<name> (root) or etc/config.<name> (the fluffos
   testsuite uses etc/config.test). lpcc.findDriverConfigs() scans both
   spots and validates by CONTENT ('mudlib directory' + 'master file'
   lines; values strip trailing '# comment #' chatter), returning
   {configFile, runCwd, mudlibRoot} -- runCwd is the checkout root
   (a relative 'mudlib directory' is driver-cwd-relative), mudlibRoot
   the resolved mudlib dir. Both the extension and the LSP server chain
   it after the explicit setting and the .lpc/config scaffold, so a
   plain mudlib checkout gets compiler diagnostics with zero settings;
   VS Code additionally offers ONCE per workspace to persist the
   discovered config into workspace settings, and lpc.initConfig offers
   the discovered config before scaffolding. Fixed along the way:
   debugLogPath() resolved a mudlib-relative configFile against the
   process cwd (same bug as includeDirs earlier) and ignored trailing
   config comments.

2. Workspace cross-index (server/indexer.js, vscode-free + dependency-
   injected). Definitions indexed eagerly (tokenize+outline of every
   .lpc/.c/.h under each workspace folder at 'initialized', re-indexed
   from live buffers); references resolved on demand (\bword\b content
   prefilter, then tokenize only matching files) so memory stays flat.
   Serves: cross-file go-to-definition (falls back from the local
   outline), workspace-wide find-references (live buffers beat disk),
   workspace/symbol (Ctrl+T), and completion items for symbols from
   never-opened files. Caps: 20k files / 1MB each; skips dotdirs,
   node_modules, .lpc/.

Verification (all green):
- test.mjs: discovery unit fixtures (content validation, decoys,
  comment stripping) + indexer units (build/update/live-buffer
  override; #define-body mentions deliberately don't count -- one
  directive token).
- test-lsp.mjs (22 checks): cross-file definition into a never-opened
  file, 3-location cross-file references, workspace/symbol, workspace
  completion, and lpcc diagnostics through an AUTO-DISCOVERED
  etc/config.* with no configFile setting (second workspace folder).
- test-nvim.lua (14 checks, real client): ASSERT_EQ resolving into
  include/tests.h via the 761-file testsuite index; corpus-scale
  workspace/symbol (100+ do_tests hits).
- Full corpus sweep: 762 files, all three phases, 0 failures.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AXqX4Kf55ArA39suS9cdCv

Author: claude

AGENTS.md

@@ -109,7 +109,20 @@ Don't "fix" that validation.
 
 `extension/config.js` resolves lpcc settings with defaults:
 `lpc.lpcc.path` unset → bundled `bin/lpcc.js` (wasm, run via node);
-`lpc.lpcc.configFile` unset → `<workspace>/.lpc/config`. The
+`lpc.lpcc.configFile` unset → `<workspace>/.lpc/config`, then
+AUTO-DISCOVERY (`lpcc.findDriverConfigs`): mudlib checkouts usually carry
+their driver config at `config.<name>` (root) or `etc/config.<name>` --
+naming is a convention, so CONTENT is the authority (a real config has
+`mudlib directory :` + `master file :` lines; values carry trailing
+`# comment #` chatter that must be stripped). Discovery returns
+`{configFile, runCwd, mudlibRoot}` -- runCwd is the checkout root (a
+relative `mudlib directory` is driver-cwd-relative), mudlibRoot the
+resolved mudlib dir; `runStage` runs lpcc from `runCwd || mudlibRoot`.
+Both the extension (config.js) and the server (resolveLpcc) apply the
+same chain; VS Code additionally shows a one-time-per-workspace prompt
+(`suggestAutoConfig`) offering to persist the discovered config into
+workspace settings, and `lpc.initConfig` offers the discovered config
+before falling back to scaffolding. The
 `lpc.initConfig` command scaffolds that config from
 `makeScaffoldFiles()` in lpcc.js (kept vscode-free so tests and the
 phase-2 LSP can use it). Scaffold facts learned empirically against a
@@ -150,12 +163,25 @@ lpcc.js and the synced lib/. Facts that bite:
   warnings from /std/base64.lpc publish into nvim diagnostics on save;
   symbols/hover/definition/completion and lpc/model work on
   operators/switch.lpc.
-* References + documentHighlight are LEXICAL and document-scope: every
-  identifier token with the same spelling (comments/strings are other
-  token kinds so they never pollute). A `#define NAME` declaration
-  lives INSIDE a single directive token — `wordAtOffset()` resolves the
-  cursor within it, and `referenceSpans()` adds the name's span in the
-  directive as the declaration site (honoring includeDeclaration).
+* References + documentHighlight are LEXICAL: every identifier token
+  with the same spelling (comments/strings are other token kinds so
+  they never pollute). A `#define NAME` declaration lives INSIDE a
+  single directive token — `wordAtOffset()` resolves the cursor within
+  it, and `referenceSpans()` adds the name's span in the directive as
+  the declaration site (honoring includeDeclaration). Mentions inside a
+  `#define` BODY are part of that one directive token and deliberately
+  don't count as references.
+* The workspace cross-index (`server/indexer.js`, vscode-free +
+  dependency-injected) powers cross-file definition, workspace-wide
+  references, and workspace/symbol. Definitions are indexed EAGERLY
+  (tokenize+outline of every `.lpc`/`.c`/`.h` under each workspace
+  folder, built once at `initialized`, re-indexed from live buffers on
+  open/change/save); references are resolved ON DEMAND (cheap
+  `\bword\b` content prefilter, then tokenize only the matching files)
+  so the index stores outlines only and memory stays flat on large
+  mudlibs. Caps: 20k files, 1MB/file; skips dotdirs, node_modules,
+  `.lpc/`. The testsuite (761 files) indexes in ~1s and is the scale
+  gate (test-nvim.lua asserts corpus-scale workspace/symbol).
 * `scripts/test-lsp.mjs` is the gate: a protocol-level harness driving
   the REAL server over stdio (initialize → didOpen → diagnostics /
   symbols / formatting / hover / definition — including `#include

README.md

@@ -65,9 +65,10 @@ built on the official `vscode-languageserver` library) and uses it by
 default (`lpc.useLanguageServer`): diagnostics (structural lint as you
 type + real lpcc compiler errors on save, including in `#include`d
 files), outline/breadcrumbs, formatting, hover, go-to-definition
-(functions/globals/defines, `#include` and `inherit` targets via the
-driver config's include dirs), find-references + document highlight
-(lexical, document-scope), completion, and custom `lpc/*` requests
+(functions/globals/defines — cross-file via the workspace index — plus
+`#include` and `inherit` targets via the driver config's include dirs),
+workspace-wide find-references + document highlight, workspace symbol
+search (Ctrl+T), completion, and custom `lpc/*` requests
 (`lpc/model`, `lpc/tokens`, `lpc/ast`, `lpc/bytecode`) that serve the
 Compiler Explorer's data — the webview is a pure renderer over LSP.
 Other editors can run it standalone: `node extension/server/main.js
@@ -81,7 +82,10 @@ When the vsix is built with a wasm `lpcc` (`LPCC_WASM_DIR=<dir> node
 scripts/build.mjs`, or a `build-wasm/` build inside the submodule), the
 extension needs **no settings at all**: with `lpc.lpcc.path` unset it runs
 the bundled `bin/lpcc.js` through node, and with `lpc.lpcc.configFile`
-unset it uses `<workspace>/.lpc/config` if present. Run **"LPC:
+unset it uses `<workspace>/.lpc/config` if present — or **auto-discovers
+the mudlib's own driver config** at the usual spots (`config.<name>` at
+the workspace root, `etc/config.<name>`), validated by content, and
+offers once per workspace to persist it into the settings. Run **"LPC:
 Initialize compiler config"** once in a mudlib workspace to scaffold that
 config (a minimal `name`/`mudlib`/`master`/`include` template plus a tiny
 master object under `.lpc/` — never overwrites existing files), and

extension/config.js

@@ -16,15 +16,27 @@
 const vscode = require('vscode');
 const path = require('path');
 const fs = require('fs');
-const { makeScaffoldFiles } = require('./lpcc.js');
+const { makeScaffoldFiles, findDriverConfigs } = require('./lpcc.js');
+
+// Discovery cache: workspace root -> findDriverConfigs() result.
+const discoveryCache = new Map();
+function discover(rootDir) {
+  if (!discoveryCache.has(rootDir)) {
+    try { discoveryCache.set(rootDir, findDriverConfigs(rootDir)); }
+    catch (_e) { discoveryCache.set(rootDir, []); }
+  }
+  return discoveryCache.get(rootDir);
+}
 
 // Resolve effective lpcc settings for a document, applying the zero-setup
-// defaults. Returns {lpccPath, configFile, mudlibRoot, relPath, available}.
+// defaults. Returns {lpccPath, configFile, mudlibRoot, runCwd, relPath,
+// available}.
 function resolveLpccSettings(ctx, doc) {
   const cfg = vscode.workspace.getConfiguration('lpc', doc.uri);
   let lpccPath = cfg.get('lpcc.path', '');
   let configFile = cfg.get('lpcc.configFile', '');
   let mudlibRoot = cfg.get('mudlibRoot', '');
+  let runCwd = null;
   if (!mudlibRoot) {
     const folder = vscode.workspace.getWorkspaceFolder(doc.uri);
     mudlibRoot = folder ? folder.uri.fsPath : path.dirname(doc.uri.fsPath);
@@ -37,9 +49,73 @@ function resolveLpccSettings(ctx, doc) {
     const scaffold = path.join(mudlibRoot, '.lpc', 'config');
     if (fs.existsSync(scaffold)) configFile = scaffold;
   }
+  if (!configFile) {
+    // Zero-setup: a real driver config at a well-known spot (config.* at
+    // the root, etc/config.*) -- see lpcc.findDriverConfigs().
+    const found = discover(mudlibRoot);
+    if (found.length > 0) {
+      configFile = found[0].configFile;
+      runCwd = found[0].runCwd;
+      mudlibRoot = found[0].mudlibRoot;
+    }
+  }
   const relPath = path.relative(mudlibRoot, doc.uri.fsPath).split(path.sep).join('/');
   const available = !!(lpccPath && configFile) && !relPath.startsWith('..');
-  return { lpccPath, configFile, mudlibRoot, relPath, available };
+  return { lpccPath, configFile, mudlibRoot, runCwd, relPath, available };
+}
+
+// One-time (per workspace) suggestion: when no config is set and a real
+// driver config exists at a well-known spot, offer to persist it into the
+// workspace settings. Resolution already falls back to it silently -- the
+// prompt makes the choice explicit/visible, and lets the user pick when a
+// checkout carries several configs.
+async function suggestAutoConfig(ctx) {
+  const folder = vscode.workspace.workspaceFolders && vscode.workspace.workspaceFolders[0];
+  if (!folder) return;
+  const root = folder.uri.fsPath;
+  const cfg = vscode.workspace.getConfiguration('lpc');
+  if (cfg.get('lpcc.configFile', '')) return;               // already configured
+  if (fs.existsSync(path.join(root, '.lpc', 'config'))) return; // scaffold present
+  const stateKey = 'lpc.autoConfigSuggested:' + root;
+  if (ctx.workspaceState.get(stateKey)) return;             // asked before
+  const found = discover(root);
+  if (found.length === 0) return;
+
+  const rel = (abs) => {
+    const r = path.relative(root, abs).split(path.sep).join('/');
+    return r.startsWith('..') ? abs : r;
+  };
+  let choice = found[0];
+  const pickLabel = found.length === 1
+    ? `Use ${rel(choice.configFile)}`
+    : 'Choose config…';
+  const answer = await vscode.window.showInformationMessage(
+    `LPC: found FluffOS driver config ${rel(found[0].configFile)}` +
+    (found.length > 1 ? ` (and ${found.length - 1} more)` : '') +
+    ' — use it for compiler diagnostics and the Compiler Explorer?',
+    pickLabel, 'Not now');
+  if (answer === undefined) return;                          // dismissed: ask again later
+  await ctx.workspaceState.update(stateKey, true);
+  if (answer === 'Not now') return;
+  if (found.length > 1) {
+    const picked = await vscode.window.showQuickPick(
+      found.map((f) => ({ label: rel(f.configFile), description: f.name, f })),
+      { placeHolder: 'Driver config to use for this workspace' });
+    if (!picked) return;
+    choice = picked.f;
+  }
+  // Store workspace-relative when the mudlib root IS the workspace root
+  // (portable if settings.json is checked in; a relative configFile
+  // resolves against the lpcc cwd = mudlibRoot). If the config points the
+  // mudlib elsewhere, store both absolute so they can't drift apart.
+  const sameRoot = path.resolve(choice.mudlibRoot) === path.resolve(root);
+  await cfg.update('lpcc.configFile', sameRoot ? rel(choice.configFile) : choice.configFile,
+                   vscode.ConfigurationTarget.Workspace);
+  if (!sameRoot) {
+    await cfg.update('mudlibRoot', choice.mudlibRoot, vscode.ConfigurationTarget.Workspace);
+  }
+  vscode.window.showInformationMessage(
+    `LPC: workspace configured with ${rel(choice.configFile)}.`);
 }
 
 async function initConfigCommand(ctx) {
@@ -49,6 +125,20 @@ async function initConfigCommand(ctx) {
     return;
   }
   const root = folder.uri.fsPath;
+  // A real driver config beats a scaffold: offer it first.
+  discoveryCache.delete(root);
+  const found = discover(root);
+  if (found.length > 0 && !vscode.workspace.getConfiguration('lpc').get('lpcc.configFile', '')) {
+    const relCfg = path.relative(root, found[0].configFile).split(path.sep).join('/');
+    const use = await vscode.window.showQuickPick(
+      [`Use discovered driver config (${relCfg})`, 'Scaffold a minimal .lpc/ config'],
+      { placeHolder: 'This workspace already has a FluffOS driver config' });
+    if (use === undefined) return;
+    if (use.startsWith('Use discovered')) {
+      await ctx.workspaceState.update('lpc.autoConfigSuggested:' + root, false);
+      return suggestAutoConfig(ctx);
+    }
+  }
   const files = makeScaffoldFiles(root);
   const written = [];
   for (const [rel, content] of Object.entries(files)) {
@@ -74,4 +164,4 @@ function register(ctx) {
   return vscode.commands.registerCommand('lpc.initConfig', () => initConfigCommand(ctx));
 }
 
-module.exports = { makeScaffoldFiles, resolveLpccSettings, register };
+module.exports = { makeScaffoldFiles, resolveLpccSettings, suggestAutoConfig, register };

extension/extension.js

@@ -129,6 +129,10 @@ function activate(ctx) {
     vscode.commands.registerCommand('lpc.openExplorer', () => explorer.openExplorer(ctx)),
     lpcConfig.register(ctx));
 
+  // One-time offer to persist a discovered driver config (config.* /
+  // etc/config.*) into the workspace settings. Fire-and-forget.
+  lpcConfig.suggestAutoConfig(ctx).catch(() => {});
+
   if (lspClient.enabled()) {
     // The language server owns diagnostics, symbols, formatting, hover,
     // definition and completion; nothing else to register in-process.

extension/lpcc.js

@@ -71,7 +71,7 @@ function runStage(opts, relPath, stage) {
   return new Promise((resolve) => {
     cp.execFile(
       exe, [...baseArgs, ...flags, opts.configFile, relPath],
-      { cwd: opts.mudlibRoot, timeout: 30000, maxBuffer: 32 * 1024 * 1024 },
+      { cwd: opts.runCwd || opts.mudlibRoot, timeout: 30000, maxBuffer: 32 * 1024 * 1024 },
       (err, stdout, stderr) => {
         resolve({
           ok: !err,
@@ -86,15 +86,18 @@ function runStage(opts, relPath, stage) {
 // Where the driver's debug log lives for a config (compile diagnostics land
 // THERE, not on stderr, when the mudlib's master has no log_error apply).
 function debugLogPath(opts) {
+  const path = require('path');
   let logDir = 'log', logFile = 'debug.log';
   try {
-    const cfg = require('fs').readFileSync(opts.configFile, 'utf8');
+    // configFile may be relative to where lpcc runs (runCwd/mudlibRoot).
+    const cfgPath = path.isAbsolute(opts.configFile)
+      ? opts.configFile : path.join(opts.runCwd || opts.mudlibRoot, opts.configFile);
+    const cfg = require('fs').readFileSync(cfgPath, 'utf8');
     const d = /^log directory\s*:\s*(.+)$/m.exec(cfg);
     const f = /^debug log file\s*:\s*(.+)$/m.exec(cfg);
-    if (d) logDir = d[1].trim();
-    if (f) logFile = f[1].trim();
+    if (d) logDir = d[1].replace(/#.*$/, '').trim();
+    if (f) logFile = f[1].replace(/#.*$/, '').trim();
   } catch (_e) { /* unreadable config: defaults */ }
-  const path = require('path');
   const dir = path.isAbsolute(logDir) ? logDir : path.join(opts.mudlibRoot, logDir);
   return path.join(dir, logFile);
 }
@@ -473,6 +476,58 @@ function stripNoise(raw) {
     .replace(/^\n+/, '').replace(/\n+$/, '\n');
 }
 
+// --- driver config discovery ------------------------------------------------------
+//
+// Mudlib checkouts usually carry their driver config at a well-known spot:
+// config.<name> at the root, or etc/config.<name> (the fluffos testsuite
+// itself uses etc/config.test). Naming is only a convention, so CONTENT is
+// the authority: a real driver config has "mudlib directory :" and
+// "master file :" lines. Values may carry trailing "# comment #" chatter
+// (config.test: "mudlib directory : ./ # test #") -- stripped here.
+//
+// Returns [{configFile, mudlibRoot, runCwd, name}], scan order root then
+// etc/, alphabetical within each:
+//   configFile  -- absolute path to the config
+//   runCwd      -- where lpcc must RUN from (the checkout root: a relative
+//                  "mudlib directory" in the config is driver-cwd-relative)
+//   mudlibRoot  -- the resolved mudlib directory (base for mudlib-relative
+//                  paths: file relPaths, diagnostics, include dirs)
+function findDriverConfigs(rootDir) {
+  const fs = require('fs');
+  const path = require('path');
+  const out = [];
+  const val = (text, key) => {
+    const m = new RegExp('^' + key + '\\s*:\\s*(.+)$', 'm').exec(text);
+    return m ? m[1].replace(/#.*$/, '').trim() : null;
+  };
+  for (const sub of ['', 'etc']) {
+    const dir = path.join(rootDir, sub);
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_e) { continue; }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+      if (!e.isFile()) continue;
+      if (!/^config(\.|$)/i.test(e.name) && !/\.(cfg|conf)$/i.test(e.name)) continue;
+      const abs = path.join(dir, e.name);
+      let text;
+      try {
+        if (fs.statSync(abs).size > 256 * 1024) continue;
+        text = fs.readFileSync(abs, 'utf8');
+      } catch (_e) { continue; }
+      const mudlib = val(text, 'mudlib directory');
+      if (!mudlib || !val(text, 'master file')) continue;
+      const mudlibRoot = path.resolve(rootDir, mudlib);
+      out.push({
+        configFile: abs,
+        runCwd: rootDir,
+        mudlibRoot: fs.existsSync(mudlibRoot) ? mudlibRoot : rootDir,
+        name: val(text, 'name') || e.name,
+      });
+    }
+  }
+  return out;
+}
+
 // Pure: the scaffold file set for a mudlib root (absolute path).
 // Returned paths are relative to the mudlib root.
 function makeScaffoldFiles(mudlibAbs) {
@@ -611,4 +666,5 @@ module.exports = {
   stripNoise,
   outline,
   makeScaffoldFiles,
+  findDriverConfigs,
 };