@geml/geml 1.1.1 → 1.3.2

package/codemap/detect.mjs

@@ -13,8 +13,9 @@
 // turns one job into the argv/env/raw a subprocess (and the refresh recipe)
 // needs — also pure. Neither ever spawns a process.
 
-import { readdirSync } from "node:fs";
+import { readdirSync, readFileSync } from "node:fs";
 import { join, relative } from "node:path";
+import { globToRegExp } from "./exclude.mjs";
 
 // Directories that never hold first-party source: pruned during the walk so a
 // vendored dependency tree or build output can't swing the extension counts
@@ -30,6 +31,7 @@ export const SKIP_DIRS = new Set([
 // over the extension count.
 const MANIFEST_LANG = {
   "tsconfig.json": "TypeScript",
+  "Cargo.toml": "Rust",
   "pom.xml": "Java",
   "build.gradle": "Java",
   "build.gradle.kts": "Java",
@@ -37,9 +39,13 @@ const MANIFEST_LANG = {
 };
 
 // Source extension -> language. scip-typescript indexes JS as well as TS, so
-// .js/.jsx map to the same TypeScript/scip job.
+// .js/.jsx map to the same TypeScript/scip job. .vue/.svelte SFCs also belong
+// to the TypeScript family: their group's job carries an `sfc` flag and the
+// build virtualizes them (codemap/sfc-virtualize.mjs) before scip runs.
 const EXT_LANG = {
   ts: "TypeScript", tsx: "TypeScript", js: "TypeScript", jsx: "TypeScript",
+  vue: "TypeScript", svelte: "TypeScript",
+  rs: "Rust",
   java: "Java",
   c: "C", h: "C",
   py: "Python",
@@ -55,12 +61,14 @@ export const isSourcePath = (p) => {
   return dot >= 0 && EXT_LANG[p.slice(dot + 1).toLowerCase()] !== undefined;
 };
 
-// Language -> indexer + Joern frontend. scip covers TypeScript/JS; everything
-// else is a Joern frontend whose --language name (UPPERCASE) we pass as
-// GEML_LANG so a mixed repo never falls back to Joern's majority-language
-// autodetect.
+// Language -> indexer + Joern frontend. scip covers TypeScript/JS (via
+// scip-typescript) and Rust (via rust-analyzer — the SCIP adapter reads both
+// symbol grammars); everything else is a Joern frontend whose --language name
+// (UPPERCASE) we pass as GEML_LANG so a mixed repo never falls back to
+// Joern's majority-language autodetect.
 export const LANG_JOB = {
   TypeScript: { indexer: "scip", gemlLang: undefined },
+  Rust: { indexer: "scip", gemlLang: undefined },
   Java: { indexer: "joern", gemlLang: "JAVASRC" },
   C: { indexer: "joern", gemlLang: "NEWC" },
   Python: { indexer: "joern", gemlLang: "PYTHONSRC" },
@@ -82,6 +90,7 @@ const extOf = (lang) => Object.keys(EXT_LANG).find((e) => EXT_LANG[e] === lang);
 export function collectSourceFiles(root, { readdir = readdirSync } = {}) {
   const files = [];      // repo-relative POSIX source files
   const manifests = [];  // repo-relative POSIX manifest files
+  const pkgs = [];       // repo-relative POSIX package.json files (TS/JS project roots)
   const walk = (dir) => {
     let ents;
     try { ents = readdir(dir, { withFileTypes: true }); } catch { return; }
@@ -93,30 +102,97 @@ export function collectSourceFiles(root, { readdir = readdirSync } = {}) {
       if (!e.isFile()) continue;
       const rel = relative(root, join(dir, e.name)).replace(/\\/g, "/");
       if (MANIFEST_LANG[e.name]) manifests.push(rel);
+      if (e.name === "package.json") pkgs.push(rel);
       const dot = e.name.lastIndexOf(".");
       const ext = dot > 0 ? e.name.slice(dot + 1).toLowerCase() : "";
       if (EXT_LANG[ext]) files.push(rel);
     }
   };
   walk(root);
-  return { files, manifests };
+  return { files, manifests, pkgs };
+}
+
+// Group the repo's TS/JS files by their NEAREST project manifest (tsconfig.json
+// or package.json) directory — scip-typescript indexes one PROJECT at a time,
+// so a monorepo of front-end apps (each its own package.json, maybe no
+// tsconfig at all) needs one indexer run per app, not one at the repo root
+// (which sees "no files got indexed"). Files with no manifest above them
+// group under the root (""). Each group also reports which SFC extensions
+// (.vue/.svelte) it contains — the sfc-flag input. Pure; exported for tests.
+export function tsProjectGroups(tsFiles, tsconfigDirs, pkgDirs) {
+  const dirs = [...new Set([...tsconfigDirs, ...pkgDirs])]
+    .sort((a, b) => b.length - a.length); // deepest first → nearest wins
+  const withTsconfig = new Set(tsconfigDirs);
+  const groups = new Map(); // subroot -> { n, sfcExts:Set }
+  for (const f of tsFiles) {
+    const home = dirs.find((d) => d === "" || f.startsWith(d + "/")) ?? "";
+    if (!groups.has(home)) groups.set(home, { n: 0, sfcExts: new Set() });
+    const g = groups.get(home);
+    g.n++;
+    const m = /\.(vue|svelte)$/i.exec(f);
+    if (m) g.sfcExts.add(m[1].toLowerCase());
+  }
+  return [...groups.keys()].sort().map((subroot) => ({
+    subroot,
+    hasTsconfig: withTsconfig.has(subroot),
+    sfcExts: [...groups.get(subroot).sfcExts].sort(),
+  }));
+}
+
+// Minimal TOML peek at a Cargo.toml's [workspace] table: its `members` /
+// `exclude` string arrays (possibly multi-line, possibly globs like
+// "crates/*"). That is exactly what decides which crate dirs one
+// `rust-analyzer scip .` run at that directory will load — full TOML parsing
+// is not needed. Returns null when the file declares no [workspace] at all.
+export function cargoWorkspace(toml) {
+  const m = /^[ \t]*\[workspace\][ \t]*\r?$/m.exec(toml);
+  if (!m) return null;
+  let body = toml.slice(m.index + m[0].length);
+  const next = /^[ \t]*\[[^\]]+\][ \t]*\r?$/m.exec(body); // next table header ends the section
+  if (next) body = body.slice(0, next.index);
+  const list = (key) => {
+    const a = new RegExp(`^[ \\t]*${key}\\s*=\\s*\\[([^\\]]*)\\]`, "m").exec(body);
+    return a ? [...a[1].matchAll(/"([^"]+)"/g)].map((x) => x[1]) : [];
+  };
+  return { members: list("members"), exclude: list("exclude") };
+}
+
+// The sfc flag for one TS project group: an SFC extension must be PRESENT in
+// the group AND its framework declared in the group's package.json (deps or
+// devDeps) — a stray .vue in a repo that never installed vue is not a Vue
+// project. `readJson` is injectable for tests.
+export function sfcFlagOf(group, pkgJsonPath, readJson) {
+  if (!group.sfcExts?.length) return undefined;
+  let pkg;
+  try { pkg = readJson(pkgJsonPath); } catch { return undefined; }
+  const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+  const frameworks = group.sfcExts.filter((ext) => deps[ext]); // ext === framework package name
+  return frameworks.length ? frameworks.join(",") : undefined;
 }
 
 // Decide the indexer jobs for `root`. Returns [] when nothing supported is
-// found. Each job: { language, indexer:"scip"|"joern", adapter, gemlLang?, signal }.
+// found. Each job: { language, indexer:"scip"|"joern", adapter, gemlLang?,
+// signal, subroot?, sfc? } — sfc ("vue"/"svelte"/"vue,svelte") marks a TS
+// project whose SFCs the build virtualizes before running scip.
 //
 // Options:
 //   excluder            (relPosixPath) => bool  — drop gitignored/--exclude paths
 //   readdir             injected fs.readdirSync (tests)
+//   readJson            injected package.json reader (tests) — sfc flag input
+//   readText            injected text reader (tests) — root Cargo.toml [workspace] peek
 //   files, manifests    precomputed (from collectSourceFiles) to skip the walk
-export function detectLanguages(root, { excluder = () => false, readdir, files, manifests } = {}) {
+export function detectLanguages(root, { excluder = () => false, readdir, readJson, readText, files, manifests, pkgs } = {}) {
+  readJson ??= (p) => JSON.parse(readFileSync(p, "utf8"));
+  readText ??= (p) => readFileSync(p, "utf8");
   if (!files || !manifests) {
     const c = collectSourceFiles(root, { readdir });
     files = files ?? c.files;
     manifests = manifests ?? c.manifests;
+    pkgs = pkgs ?? c.pkgs;
   }
   const keptFiles = files.filter((f) => !excluder(f));
   const keptManifests = manifests.filter((m) => !excluder(m));
+  const keptPkgs = (pkgs ?? []).filter((p) => !excluder(p));
 
   // 1. manifest languages — strong signal, priority over extension counts.
   const detected = new Map(); // language -> signal string
@@ -145,16 +221,99 @@ export function detectLanguages(root, { excluder = () => false, readdir, files,
   const jobs = [];
   for (const [language, signal] of detected) {
     const spec = LANG_JOB[language];
-    if (spec) jobs.push({ language, indexer: spec.indexer, adapter: spec.indexer, gemlLang: spec.gemlLang, signal });
+    if (!spec) continue;
+    if (language === "TypeScript") {
+      // One scip run per nearest-manifest project (see tsProjectGroups).
+      const isTs = (f) => /\.(ts|tsx|js|jsx|vue|svelte)$/i.test(f);
+      const dirOf = (p) => (p.includes("/") ? p.slice(0, p.lastIndexOf("/")) : "");
+      const pkgDirs = new Set(keptPkgs.map(dirOf));
+      const groups = tsProjectGroups(
+        keptFiles.filter(isTs),
+        keptManifests.filter((m) => m.endsWith("tsconfig.json")).map(dirOf),
+        [...pkgDirs],
+      );
+      for (const g of groups) {
+        // SFCs present + framework declared in the group's own package.json
+        // -> the build virtualizes this project before indexing it.
+        const sfc = pkgDirs.has(g.subroot)
+          ? sfcFlagOf(g, join(root, ...(g.subroot ? g.subroot.split("/") : []), "package.json"), readJson)
+          : undefined;
+        // A group indexes only if it's a real project: it HAS a tsconfig, or is
+        // a Vue/Svelte app (SFC) — the virtualizer gives that one a synthetic
+        // tsconfig. A tsconfig-less, non-SFC group is loose files, not a project:
+        // skip it. (We don't synthesize a config with scip's --infer-tsconfig —
+        // that swept the whole tree and littered a stub tsconfig.json.)
+        if (!g.hasTsconfig && !sfc) continue;
+        jobs.push({
+          language, indexer: spec.indexer, adapter: spec.indexer, gemlLang: spec.gemlLang,
+          subroot: g.subroot || undefined,
+          sfc,
+          signal: (g.hasTsconfig
+            ? (g.subroot ? `${g.subroot}/tsconfig.json` : "tsconfig.json")
+            // No tsconfig in THIS group (only an SFC app reaches here now — the
+            // virtualizer supplies its config): name the package.json so the
+            // signal doesn't echo some OTHER group's tsconfig.
+            : (g.subroot ? `${g.subroot}/package.json`
+              : keptPkgs.includes("package.json") ? "package.json" : `.${extOf(language)}`))
+            + (sfc ? ` +${sfc}-sfc` : ""),
+        });
+      }
+      continue;
+    }
+    if (language === "Rust") {
+      // One `rust-analyzer scip .` run loads ONE Cargo workspace: the run at
+      // the repo root covers the root package + its [workspace] members and
+      // nothing else. A crate that opted out (its own [workspace] table, e.g.
+      // a top-level cli/) or was never a member is invisible to that run — it
+      // gets its OWN run in its OWN directory. Anchors are crate-qualified
+      // ("rust-analyzer cargo <crate> …"), so merged runs never collide.
+      const dirOf = (p) => (p.includes("/") ? p.slice(0, p.lastIndexOf("/")) : "");
+      const cargoDirs = [...new Set(keptManifests.filter((m) => m.endsWith("Cargo.toml")).map(dirOf))];
+      if (!cargoDirs.length) { // extension-only signal: keep the single root run
+        jobs.push({ language, indexer: spec.indexer, adapter: spec.indexer, gemlLang: spec.gemlLang, signal });
+        continue;
+      }
+      const rootHas = cargoDirs.includes("");
+      let members = [], excluded = [];
+      if (rootHas) {
+        try {
+          const ws = cargoWorkspace(readText(join(root, "Cargo.toml")));
+          if (ws) { members = ws.members; excluded = ws.exclude; }
+        } catch { /* unreadable root manifest — treat as memberless */ }
+      }
+      const rootCovers = (d) =>
+        members.some((g) => globToRegExp(g).test(d)) && !excluded.some((g) => globToRegExp(g).test(d));
+      let standalone = cargoDirs.filter((d) => d && !(rootHas && rootCovers(d))).sort();
+      // A crate nested under another standalone crate belongs to THAT run.
+      standalone = standalone.filter((d) => !standalone.some((s) => s !== d && d.startsWith(s + "/")));
+      if (rootHas) jobs.push({ language, indexer: spec.indexer, adapter: spec.indexer, gemlLang: spec.gemlLang, signal });
+      for (const d of standalone) {
+        jobs.push({ language, indexer: spec.indexer, adapter: spec.indexer, gemlLang: spec.gemlLang, subroot: d, signal: `${d}/Cargo.toml` });
+      }
+      continue;
+    }
+    jobs.push({ language, indexer: spec.indexer, adapter: spec.indexer, gemlLang: spec.gemlLang, signal });
   }
-  // Deterministic order: scip before joern, then by GEML_LANG, then language.
+  // Deterministic order: scip before joern, then by GEML_LANG, then language;
+  // same-language projects DEEPEST subroot first — a nested project's anchors
+  // must win collisions with an enclosing one, so the merge keeps the FIRST
+  // occurrence, which must be the deeper (more precise) index.
   jobs.sort((a, b) =>
     (a.indexer === b.indexer ? 0 : a.indexer === "scip" ? -1 : 1)
     || (a.gemlLang ?? "").localeCompare(b.gemlLang ?? "")
-    || a.language.localeCompare(b.language));
+    || a.language.localeCompare(b.language)
+    || (b.subroot ?? "").length - (a.subroot ?? "").length
+    || (a.subroot ?? "").localeCompare(b.subroot ?? ""));
   return jobs;
 }
 
+// The npx -p set the SFC virtualizer needs, per framework. typescript is
+// pinned @5: typescript@latest is 7.x, which @vue/language-core rejects.
+const SFC_NPX_PKGS = {
+  vue: ["@vue/language-core"],
+  svelte: ["svelte2tsx", "svelte"],
+};
+
 // Turn one detection job into the concrete command a subprocess runs. Pure:
 // the caller supplies resolved absolute paths. `raw` is what the matching
 // adapter consumes downstream — a .scip FILE for scip, the JSONL output DIR
@@ -162,24 +321,79 @@ export function detectLanguages(root, { excluder = () => false, readdir, files,
 //   root        resolved project root (scip cwd; joern GEML_SRC)
 //   buildDir    where intermediates land (typically <out>/_build)
 //   scriptPath  resolved path to joern-export.sc
-export function indexerCommand(job, { root, buildDir, scriptPath }) {
+//   sfcScript   resolved path to sfc-virtualize.mjs (sfc jobs only)
+//
+// An sfc job returns TWO steps: `pre` (the virtualizer, run first — shadows,
+// map sidecars and a synthetic tsconfig land in `remapDir`) and the main
+// scip run, which executes IN the virtual dir against that tsconfig. The
+// build passes `remapDir` through to the scip adapter.
+export function indexerCommand(job, { root, buildDir, scriptPath, sfcScript }) {
   if (job.indexer === "scip") {
-    const raw = join(buildDir, "index.scip");
+    // One .scip per project run — a subrooted job (monorepo app, standalone
+    // crate) runs IN that directory and writes a slug-named index; the adapter
+    // re-anchors its paths via the index's metadata.project_root, so the merge
+    // stays repo-relative.
+    const slug = job.subroot ? String(job.subroot).replace(/\//g, "-") : "";
+    const subrootAbs = job.subroot ? join(root, ...String(job.subroot).split("/")) : root;
+    // rust.scip / rust-<slug>.scip next to index.scip, so a mixed TS + Rust
+    // repo never overwrites one index with the other. A subrooted Rust job is
+    // a crate OUTSIDE the root workspace: rust-analyzer runs in the crate dir.
+    if (job.language === "Rust") {
+      const raw = join(buildDir, slug ? `rust-${slug}.scip` : "rust.scip");
+      return {
+        adapter: "scip",
+        raw,
+        argv: ["rust-analyzer", "scip", ".", "--output", raw],
+        env: undefined,
+        cwd: job.subroot ? subrootAbs : root,
+      };
+    }
+    const raw = join(buildDir, slug ? `index-${slug}.scip` : "index.scip");
+    if (job.sfc) {
+      // Virtualize first, then index the virtual dir: its synthetic tsconfig
+      // covers the shadows AND the project's real TS/JS, so this ONE scip run
+      // replaces the plain per-project run.
+      const remapDir = join(buildDir, slug ? `virtual-${slug}` : "virtual-root");
+      const pkgs = [...new Set(String(job.sfc).split(",").flatMap((f) => SFC_NPX_PKGS[f] ?? []))];
+      return {
+        adapter: "scip",
+        raw,
+        remapDir,
+        pre: {
+          argv: ["npx", "-y", ...pkgs.flatMap((p) => ["-p", p]), "-p", "typescript@5", "node", sfcScript],
+          env: { GEML_SRC: subrootAbs, GEML_OUT: remapDir },
+          cwd: root,
+        },
+        argv: ["npx", "--yes", "@sourcegraph/scip-typescript", "index", "--output", raw],
+        env: undefined,
+        cwd: remapDir,
+      };
+    }
+    // A plain TS/JS project: scip-typescript reads the tsconfig in its cwd.
+    // detect only emits a scip job for a group that HAS a tsconfig (SFC apps are
+    // handled above, indexing their virtual dir's synthetic config), so there is
+    // never a config to infer — a tsconfig-less, non-SFC group is loose files,
+    // not a project, and was dropped back in detectLanguages.
     return {
       adapter: "scip",
       raw,
       argv: ["npx", "--yes", "@sourcegraph/scip-typescript", "index", "--output", raw],
       env: undefined,
-      cwd: root,
+      cwd: job.subroot ? subrootAbs : root,
     };
   }
   // joern: one output dir per frontend so several Joern jobs never clash.
   const raw = join(buildDir, `joern-${String(job.gemlLang).toLowerCase()}`);
+  // Run IN the build dir, not the repo root. Joern's importCode writes its CPG
+  // workspace to <cwd>/workspace/; anchoring cwd at buildDir keeps that cache
+  // inside .geml-code-graph/_build/workspace/ instead of scattering a stray
+  // `workspace/` at the repo root. GEML_SRC/GEML_OUT are absolute and the
+  // script path is absolute, so the move never affects what Joern reads or writes.
   return {
     adapter: "joern",
     raw,
     argv: ["joern", "--script", scriptPath],
     env: { GEML_SRC: root, GEML_OUT: raw, GEML_LANG: job.gemlLang },
-    cwd: root,
+    cwd: buildDir,
   };
 }

package/codemap/emit.mjs

@@ -18,7 +18,13 @@ import { dirname, join, posix } from "node:path";
 import { buildNormalizer } from "./normalize.mjs";
 
 const esc = (s) => String(s).replace(/`/g, "'");
-const attrVal = (s) => String(s).replace(/"/g, "'");
+// Attribute values live on the block-header LINE: a newline inside one (e.g.
+// scip's anonymous-type-literal descriptors embed the literal's multi-line
+// text in the symbol) would truncate the header mid-value — the block still
+// parses as raw text but its #id never registers, and every edge to it
+// dangles (found on next.js: `recursiveCopy().({ filter... })`). Collapse all
+// whitespace runs to single spaces alongside the quote swap.
+const attrVal = (s) => String(s).replace(/"/g, "'").replace(/\s+/g, " ");
 // Plain-text cells: no commas/newlines (CSV), and no square brackets — table
 // cells are inline-parsed, so `f[i](&x)` would otherwise read as a LINK with an
 // unresolvable target. Brackets become parens: still readable, never markup.
@@ -42,11 +48,35 @@ const slugPath = (p) => (p === "" || p === "(root)" ? "root" : p.replace(/\//g,
 const dirOf = (rel) => { const i = rel.lastIndexOf("/"); return i < 0 ? "(root)" : rel.slice(0, i); };
 const topOf = (rel) => { const i = rel.indexOf("/"); return i < 0 ? "(root)" : rel.slice(0, i); };
 
-export function emit({ symbols, edges, outDir, buildDir, repoName, container = "dir", commit, root }) {
+export function emit({ symbols, edges, outDir, buildDir, repoName, container = "dir", commit, root, foldings, entryHints }) {
   const byAnchor = new Map(symbols.map((s) => [s.anchor, s]));
   const methods = symbols.filter((s) => s.kind === "Function" || s.kind === "Test");
   const files = symbols.filter((s) => s.kind === "File");
 
+  // ---- app-entry hints (codemap/entries.mjs) ----
+  // A named hint marks its method; a file-level hint (SPA bootstrap, Nuxt app
+  // shell…) marks the file's only method, or — when the entry is top-level
+  // code with no function symbol at all — falls through to a doc-level
+  // `app-entry-file` note. The adapters' own name==="main" flag rides along;
+  // every marked entry carries `via` (the convention that identified it).
+  const fileHints = [];
+  {
+    const methodsByFile = new Map();
+    for (const s of methods) {
+      if (!methodsByFile.has(s.file)) methodsByFile.set(s.file, []);
+      methodsByFile.get(s.file).push(s);
+    }
+    for (const h of entryHints ?? []) {
+      const list = methodsByFile.get(h.file) ?? [];
+      let hit;
+      if (h.name) hit = list.find((s) => s.name === h.name || s.name.endsWith(`::${h.name}`) || s.name.endsWith(`.${h.name}`));
+      else if (list.length === 1) hit = list[0];
+      if (hit) { hit.entry = true; hit.entryVia ??= h.via; }
+      else fileHints.push(h);
+    }
+    for (const s of methods) if (s.entry && !s.entryVia) s.entryVia = "main";
+  }
+
   // ---- containers ----
   const containerOf = (s) =>
     container === "file" ? s.file : container === "module" ? topOf(s.file) : dirOf(s.file);
@@ -57,7 +87,7 @@ export function emit({ symbols, edges, outDir, buildDir, repoName, container = "
   // keys on the TRUE path (containerOf) and `src=` stays the true path — only
   // the displayed module path shortens. root may be absent (older callers / crg
   // tier): then displayOf is the identity.
-  const normMap = root ? buildNormalizer(root, methods.map(containerOf), { repoName, fileMode: container === "file" }) : new Map();
+  const normMap = root ? buildNormalizer(root, methods.map(containerOf), { repoName, fileMode: container === "file", config: foldings }) : new Map();
   const displayOf = (name) => normMap.get(name) ?? name;
   const containers = new Map(); // name -> { docName, methods[], files[] }
   const taken = new Set(["index.geml"]);
@@ -79,6 +109,16 @@ export function emit({ symbols, edges, outDir, buildDir, repoName, container = "
   for (const [name, c] of containers) {
     for (const s of [...c.methods, ...c.files]) docOfAnchor.set(s.anchor, c.docName);
   }
+  // File-level app-entry hints, grouped under the container that holds the
+  // file (a hint whose file grew no container at all has nowhere honest to
+  // land and is dropped).
+  const fileHintsByDoc = new Map(); // docName -> [{file, via}]
+  for (const h of fileHints) {
+    const c = containers.get(containerOf({ file: h.file }));
+    if (!c) continue;
+    if (!fileHintsByDoc.has(c.docName)) fileHintsByDoc.set(c.docName, []);
+    fileHintsByDoc.get(c.docName).push(h);
+  }
 
   // ---- block ids: short name when unique in its doc, else name-<sha6(anchor)> ----
   const idOf = new Map(); // anchor -> id
@@ -212,6 +252,13 @@ export function emit({ symbols, edges, outDir, buildDir, repoName, container = "
       + `module = ${csvCell(dispLabel)}\n`
       + (srcDir ? `src = ${csvCell(srcDir)}\n` : "")
       + (entries.length ? `entry = ${entries.map((s) => `#${idOf.get(s.anchor)}`).join(" ")}\n` : "")
+      // app-entry: WHERE the program starts (main, a mount, a worker handler)
+      // — a separate, much rarer list than entry= (the container's inbound
+      // call surface). File-level entries (top-level bootstrap code with no
+      // function symbol) are named by path instead of a block reference.
+      + (c.methods.some((s) => s.entry)
+        ? `app-entry = ${c.methods.filter((s) => s.entry).map((s) => `#${idOf.get(s.anchor)} (${s.entryVia})`).join(" ")}\n` : "")
+      + (fileHintsByDoc.get(doc) ?? []).map((h) => `app-entry-file = ${csvCell(h.file)} (${h.via})\n`).join("")
       + `resolution-default = ${RESOLUTION_DEFAULT}\n===\n`,
       `# ${esc(dispLabel)}\n`,
     ];
@@ -232,14 +279,15 @@ export function emit({ symbols, edges, outDir, buildDir, repoName, container = "
         chunks.push(fileSym ? `## ${esc(base)} {#${idOf.get(fileSym.anchor)}}\n` : `## ${esc(base)}\n`);
       }
       for (const s of list) {
-        const cls = `${isTestPath(s.file) ? " .test" : ""}${isLeaf(s) ? " .leaf" : ""}${isAccessor(s) ? " .accessor" : ""}${s.flow_crit ? " .flow-entry" : ""}`;
+        const cls = `${isTestPath(s.file) ? " .test" : ""}${isLeaf(s) ? " .leaf" : ""}${isAccessor(s) ? " .accessor" : ""}${s.flow_crit ? " .flow-entry" : ""}${s.entry ? " .app-entry" : ""}`;
         const src = `${s.file}${s.line_start !== undefined ? `#L${s.line_start}-${s.line_end ?? s.line_start}` : ""}`;
         // The display name rides along whenever id sanitisation changed it
         // ("RenderCtx.block" -> id RenderCtx-block): renderers label nodes
         // with the real name, ids stay reference-grammar clean.
         const id = idOf.get(s.anchor);
         const nameAttr = s.name !== id ? ` name="${attrVal(s.name)}"` : "";
-        chunks.push(`=== code {#${id}${cls}${nameAttr} src=${attrVal(src)} anchor="${attrVal(s.anchor)}"}\n===\n`);
+        const viaAttr = s.entry && s.entryVia ? ` entry-via="${attrVal(s.entryVia)}"` : "";
+        chunks.push(`=== code {#${id}${cls}${nameAttr}${viaAttr} src=${attrVal(src)} anchor="${attrVal(s.anchor)}"}\n===\n`);
       }
     }
 
@@ -301,6 +349,9 @@ export function emit({ symbols, edges, outDir, buildDir, repoName, container = "
     + (commit ? `commit = ${csvCell(commit)}\n` : "")
     + `container = ${container}\n`
     + (appEntries.length ? `entry = ${appEntries.map((a) => `${docOfAnchor.get(a)}#${idOf.get(a)}`).join(" ")}\n` : "")
+    // Documents whose app entry is FILE-level (top-level bootstrap code, no
+    // function symbol) — its own key so entry= keeps its doc#id grammar.
+    + (fileHintsByDoc.size ? `app-entry-docs = ${[...fileHintsByDoc.keys()].sort().join(" ")}\n` : "")
     + `resolution-default = ${RESOLUTION_DEFAULT}\n===\n`,
     `# Code map — ${esc(repoName)}\n`,
     csv("modules", ["module", "doc", "methods", "entries", "tests"],
@@ -326,6 +377,11 @@ export function emit({ symbols, edges, outDir, buildDir, repoName, container = "
     addLookup(s.name, s);
     const dot = s.name.indexOf(".");
     if (dot > 0 && dot < s.name.length - 1) addLookup(s.name.slice(dot + 1), s);
+    else {
+      // Rust members qualify with "::" (Widget::area) — same bare-name alias.
+      const c = s.name.indexOf("::");
+      if (c > 0 && c < s.name.length - 2) addLookup(s.name.slice(c + 2), s);
+    }
   }
   const sortedLookup = {};
   for (const name of [...lookup.keys()].sort()) {
@@ -333,6 +389,17 @@ export function emit({ symbols, edges, outDir, buildDir, repoName, container = "
   }
   writeIfChanged("_index/name-lookup.json", JSON.stringify(sortedLookup, null, 2) + "\n");
 
+  // Compact search index for the viewer's name -> node typeahead: a flat
+  // [name, doc, id] list with the (bulky) anchors dropped, so it stays small
+  // even on huge repos. Emitted as a JS global so a STATIC page can load it via
+  // `<script src>` (a file:// page can't fetch() a sibling file, but a script
+  // tag is exempt); serve also searches it server-side for big graphs.
+  const searchIndex = [];
+  for (const name of Object.keys(sortedLookup)) {
+    for (const c of sortedLookup[name]) searchIndex.push([name, c.doc, c.id]);
+  }
+  writeIfChanged("_index/search-index.js", "window.__gemlSearch=" + JSON.stringify(searchIndex) + ";\n");
+
   // ---- edges-manifest (internal) ----
   if (buildDir) {
     const manifest = {};
@@ -354,8 +421,12 @@ export function emit({ symbols, edges, outDir, buildDir, repoName, container = "
     symbols: symbols.length,
     methods: methods.length,
     edges: edges.length,
-    resolved: calls.filter((e) => e.to !== undefined && docOfAnchor.has(e.to)).length,
+    // A `calls` edge is "resolved" only when it actually yields a table row —
+    // that needs BOTH endpoints known (the calls loop above skips any edge
+    // whose FROM anchor is unknown). Counting by target alone inflated the
+    // figure for a dangling-FROM edge that produced no row.
+    resolved: calls.filter((e) => docOfAnchor.has(e.from) && e.to !== undefined && docOfAnchor.has(e.to)).length,
     leaves: methods.filter((s) => isLeaf(s)).length,
-    entries: appEntries.length,
+    entries: appEntries.length + [...fileHintsByDoc.values()].reduce((n, a) => n + a.length, 0),
   };
 }

package/codemap/entries.mjs

@@ -0,0 +1,129 @@
+// geml-code-graph app-entry detection — WHERE does this repo start running?
+//
+// Emits entry HINTS ({ file, via, name? }) from three signal tiers, each
+// carrying an honest `via` label (the codemap never claims an entry without
+// saying what convention identified it):
+//   L2 manifest/layout   Cargo [[bin]] & src/main.rs & src/bin/*, package.json
+//                        bin, wrangler.toml main, Nuxt app.vue, Next root
+//                        page, SvelteKit root route, Django manage.py,
+//                        python __main__.py
+//   L3 source markers    workers-rs #[event(...)], createApp().mount() /
+//                        createRoot() / svelte mount (SPA bootstraps),
+//                        .listen() (node servers), export default { fetch }
+//                        (JS workers), Flask()/FastAPI() apps,
+//                        @SpringBootApplication
+// (L1 — a function literally named `main` — is already flagged by the scip
+// and joern adapters at extraction time; hints here ADD to it.)
+//
+// Pure by design: given precomputed { files, manifests, pkgs } lists it walks
+// nothing; `readText`/`readJson` are injectable, and every source peek is
+// bounded to a handful of conventional entry files per project — never a
+// repo-wide grep. A hint is only emitted for files the build actually indexes
+// (present in `files`), so a pkg-bin pointing at dist/ never leaks in.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const dirOf = (p) => (p.includes("/") ? p.slice(0, p.lastIndexOf("/")) : "");
+
+export function detectEntries(root, { files = [], manifests = [], pkgs = [], readText, readJson } = {}) {
+  readText ??= (p) => readFileSync(p, "utf8");
+  readJson ??= (p) => JSON.parse(readText(p));
+  const fileSet = new Set(files);
+  const hints = [];
+  const seen = new Set();
+  const add = (file, via, name) => {
+    if (!file || !fileSet.has(file)) return;
+    const k = `${file}
${via}
${name ?? ""}`;
+    if (seen.has(k)) return;
+    seen.add(k);
+    hints.push(name ? { file, via, name } : { file, via });
+  };
+  const tryText = (rel) => {
+    try { return readText(join(root, ...rel.split("/"))); } catch { return null; }
+  };
+
+  // ---- Rust: cargo bin targets + workers-rs event handlers ----
+  for (const m of manifests.filter((x) => x.endsWith("Cargo.toml"))) {
+    const dir = dirOf(m);
+    const at = (rel) => (dir ? `${dir}/${rel}` : rel);
+    add(at("src/main.rs"), "cargo-bin", "main");
+    for (const f of files) if (f.startsWith(at("src/bin/")) && f.endsWith(".rs")) add(f, "cargo-bin", "main");
+    const toml = tryText(m);
+    if (toml) {
+      for (const b of toml.matchAll(/^\[\[bin\]\][^[]*/gm)) {
+        const p = /path\s*=\s*"([^"]+)"/.exec(b[0]);
+        if (p) add(at(p[1].replace(/\\/g, "/")), "cargo-bin", "main");
+      }
+    }
+    for (const rel of ["src/main.rs", "src/lib.rs"]) {
+      const t = fileSet.has(at(rel)) ? tryText(at(rel)) : null;
+      if (!t) continue;
+      for (const ev of t.matchAll(/#\[event\((\w+)[^)]*\)\]\s*(?:pub\s+)?(?:async\s+)?fn\s+([A-Za-z_][A-Za-z0-9_]*)/g)) {
+        add(at(rel), `worker-${ev[1]}`, ev[2]);
+      }
+    }
+  }
+
+  // ---- Node/TS/frontends: one look per package ----
+  for (const p of pkgs) {
+    const dir = dirOf(p);
+    const at = (rel) => (dir ? `${dir}/${rel}` : rel);
+    let pkg = {};
+    try { pkg = readJson(join(root, ...p.split("/"))) ?? {}; } catch { /* unreadable manifest */ }
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const norm = (v) => (typeof v === "string" ? v.replace(/^\.\//, "").replace(/\\/g, "/") : null);
+    const bins = typeof pkg.bin === "string" ? [pkg.bin] : Object.values(pkg.bin ?? {});
+    for (const b of bins) { const f = norm(b); if (f) add(at(f), "pkg-bin"); }
+    const wrangler = tryText(at("wrangler.toml"));
+    if (wrangler) {
+      const mm = /^\s*main\s*=\s*"([^"]+)"/m.exec(wrangler);
+      if (mm) add(at(norm(mm[1])), "worker-fetch");
+    }
+    // Nuxt: the app shell is the entry; individual pages are routes, not
+    // program starts — deliberately NOT flooded into app-entries.
+    if (deps.nuxt || fileSet.has(at("nuxt.config.ts")) || fileSet.has(at("nuxt.config.js"))) {
+      if (fileSet.has(at("app.vue"))) add(at("app.vue"), "nuxt-app");
+      else add(at("pages/index.vue"), "nuxt-page");
+    }
+    if (deps.next) {
+      for (const rel of ["app/page.tsx", "app/page.jsx", "src/app/page.tsx", "pages/index.tsx", "pages/index.jsx", "src/pages/index.tsx"]) {
+        if (fileSet.has(at(rel))) { add(at(rel), "next-page"); break; }
+      }
+    }
+    if (deps["@sveltejs/kit"]) add(at("src/routes/+page.svelte"), "kit-route");
+    // SPA bootstrap / server start markers — conventional entry files only.
+    for (const rel of ["src/main.ts", "src/main.tsx", "src/main.js", "src/main.jsx",
+      "src/index.ts", "src/index.tsx", "src/index.js", "index.ts", "index.js",
+      "src/server.ts", "src/server.js", "server.js", "src/app.ts", "app.js"]) {
+      const f = at(rel);
+      if (!fileSet.has(f)) continue;
+      const t = tryText(f);
+      if (!t) continue;
+      if (/createApp\s*\(/.test(t) && /\.mount\s*\(/.test(t)) add(f, "vue-mount");
+      else if (/createRoot\s*\(|ReactDOM\.render\s*\(/.test(t)) add(f, "react-mount");
+      else if (deps.svelte && /\bnew\s+\w+\s*\(\s*\{[^}]*target|\bmount\s*\(/.test(t)) add(f, "svelte-mount");
+      if (/\.listen\s*\(/.test(t)) add(f, "server-listen");
+      if (/export\s+default\s*\{[^}]*\bfetch\b/s.test(t)) add(f, "worker-fetch");
+    }
+  }
+
+  // ---- Python ----
+  for (const f of files) {
+    if (/(^|\/)manage\.py$/.test(f)) add(f, "django-manage");
+    else if (/(^|\/)__main__\.py$/.test(f)) add(f, "py-main");
+    else if (/(^|\/)(app|main|wsgi|asgi)\.py$/.test(f)) {
+      const t = tryText(f);
+      if (t && /\bFlask\s*\(|\bFastAPI\s*\(/.test(t)) add(f, "wsgi-app");
+    }
+  }
+
+  // ---- Java: Spring Boot (convention-named files only, never a repo grep) ----
+  for (const f of files) {
+    if (/Application\.java$/.test(f)) {
+      const t = tryText(f);
+      if (t && /@SpringBootApplication/.test(t)) add(f, "spring-boot", "main");
+    }
+  }
+
+  return hints;
+}