@geml/geml 1.3.2 → 1.4.2

package/codemap/foldings.mjs

@@ -1,110 +1,110 @@
-// foldings.geml — the visible, human-owned config for codemap ceremony folding.
-// GEML (dogfooded; the viewer renders it): a meta header, three bullet-list
-// sections (fold-prefixes / source-roots / test-roots) and an options section.
-// Read via the bundled parser; group-id shared-prefix stripping stays
-// algorithmic (only its on/off toggle lives here).
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { parse } from "../dist/geml.js";
-import { deriveFoldLayers, DEFAULT_SOURCE_ROOTS, DEFAULT_TEST_ROOTS, LANG_FOLD_PREFIXES } from "./normalize.mjs";
-
-const SECTIONS = { "fold-prefixes": "foldPrefixes", "source-roots": "sourceRoots", "test-roots": "testRoots", "module-roots": "moduleRoots" };
-// Plain text of a bullet-list item. GEML list items carry `.text`; fall back to
-// joining inline `.value`s if a build ever changes that shape.
-const itemText = (it) => (typeof it.text === "string" ? it.text : (it.inlines ?? []).map((n) => n.value ?? "").join("")).trim();
-
-export function parseFoldings(text) {
-  const doc = parse(text);
-  // A malformed hand-edit must fail LOUDLY, not silently drop every rule: the
-  // caller (loadOrSeedFoldings) catches this and falls back to the defaults.
-  // An intentionally empty file carries NO error diagnostics and yields empty
-  // sections — the "fold nothing" off-switch, a deliberately different outcome.
-  const errs = doc.diagnostics.filter((d) => d.severity === "error");
-  if (errs.length) throw new Error(`invalid GEML in foldings config: ${errs[0].message} (line ${errs[0].line})`);
-  const cfg = { foldPrefixes: [], sourceRoots: [], testRoots: [], moduleRoots: [], stripSharedPrefix: true };
-  let section = null;
-  for (const b of doc.children) {
-    if (b.kind === "heading") { section = b.text.trim().toLowerCase(); continue; }
-    if (b.kind !== "list") continue;
-    const items = b.items.map(itemText).filter(Boolean);
-    if (Object.hasOwn(SECTIONS, section)) cfg[SECTIONS[section]] = items;
-    else if (section === "options") {
-      for (const it of items) {
-        const m = it.match(/^strip-shared-prefix\s*:\s*(on|off|true|false)$/i);
-        if (m) cfg.stripSharedPrefix = /^(on|true)$/i.test(m[1]);
-      }
-    }
-  }
-  return cfg;
-}
-
-export function serializeFoldings(cfg) {
-  const list = (xs) => xs.map((x) => `- ${x}`).join("\n");
-  return [
-    "=== meta",
-    'title = "codemap foldings"',
-    "===",
-    "",
-    "Ceremony folded out of module display names. Seeded on first build; edit",
-    "freely — build never rewrites this. The shared package prefix (group-ids",
-    "like com/acme/app) is stripped automatically and needs no entry here; set",
-    "strip-shared-prefix to off under Options to disable it.",
-    "",
-    "Add a directory under module-roots to force it to display as its own",
-    "module — for a submodule a build tool declares centrally but whose folder",
-    "carries no manifest, or any layout the detector cannot see.",
-    "",
-    "## fold-prefixes",
-    "",
-    list(cfg.foldPrefixes),
-    "",
-    "## source-roots",
-    "",
-    list(cfg.sourceRoots),
-    "",
-    "## test-roots",
-    "",
-    list(cfg.testRoots),
-    "",
-    "## module-roots",
-    "",
-    list(cfg.moduleRoots ?? []),
-    "",
-    "## options",
-    "",
-    `- strip-shared-prefix: ${cfg.stripSharedPrefix ? "on" : "off"}`,
-    "",
-  ].join("\n");
-}
-
-// Seeded config for a first build: structural fold-layers (above-root
-// ceremony dirs, derived from the discovered module roots) unioned with
-// known per-language ceremony (Cargo's `crates/`). Source/test roots always
-// start from the same global defaults — the human edits foldings.geml from
-// there; the build never rewrites it once it exists.
-export function defaultFoldings({ moduleRoots, languages }) {
-  const langPrefixes = (languages ?? []).flatMap((l) => LANG_FOLD_PREFIXES[l] ?? []);
-  const foldPrefixes = [...new Set([...deriveFoldLayers(moduleRoots ?? []), ...langPrefixes])].sort();
-  return { foldPrefixes, sourceRoots: [...DEFAULT_SOURCE_ROOTS], testRoots: [...DEFAULT_TEST_ROOTS], moduleRoots: [], stripSharedPrefix: true };
-}
-
-// Read <outDir>/_index/foldings.geml, or seed it on first build. Write-once:
-// an existing file is the human's — we read it and never rewrite it (the
-// refresh.json contract). A missing or unreadable file never crashes the
-// build: seed/fall back to defaults and say so. Returns { config, seeded }.
-export function loadOrSeedFoldings({ outDir, moduleRoots, languages }) {
-  const path = join(outDir, "_index", "foldings.geml");
-  if (existsSync(path)) {
-    try { return { config: parseFoldings(readFileSync(path, "utf8")), seeded: false }; }
-    catch (e) {
-      console.error(`warning: ignoring ${path} (${e.message}) — using default foldings; fix the file to re-enable your edits.`);
-      return { config: defaultFoldings({ moduleRoots, languages }), seeded: false };
-    }
-  }
-  const config = defaultFoldings({ moduleRoots, languages });
-  try {
-    mkdirSync(join(outDir, "_index"), { recursive: true });
-    writeFileSync(path, serializeFoldings(config));
-  } catch (e) { console.error(`warning: could not seed ${path} (${e.message}).`); }
-  return { config, seeded: true };
-}
+// foldings.geml — the visible, human-owned config for codemap ceremony folding.
+// GEML (dogfooded; the viewer renders it): a meta header, three bullet-list
+// sections (fold-prefixes / source-roots / test-roots) and an options section.
+// Read via the bundled parser; group-id shared-prefix stripping stays
+// algorithmic (only its on/off toggle lives here).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "../dist/geml.js";
+import { deriveFoldLayers, DEFAULT_SOURCE_ROOTS, DEFAULT_TEST_ROOTS, LANG_FOLD_PREFIXES } from "./normalize.mjs";
+
+const SECTIONS = { "fold-prefixes": "foldPrefixes", "source-roots": "sourceRoots", "test-roots": "testRoots", "module-roots": "moduleRoots" };
+// Plain text of a bullet-list item. GEML list items carry `.text`; fall back to
+// joining inline `.value`s if a build ever changes that shape.
+const itemText = (it) => (typeof it.text === "string" ? it.text : (it.inlines ?? []).map((n) => n.value ?? "").join("")).trim();
+
+export function parseFoldings(text) {
+  const doc = parse(text);
+  // A malformed hand-edit must fail LOUDLY, not silently drop every rule: the
+  // caller (loadOrSeedFoldings) catches this and falls back to the defaults.
+  // An intentionally empty file carries NO error diagnostics and yields empty
+  // sections — the "fold nothing" off-switch, a deliberately different outcome.
+  const errs = doc.diagnostics.filter((d) => d.severity === "error");
+  if (errs.length) throw new Error(`invalid GEML in foldings config: ${errs[0].message} (line ${errs[0].line})`);
+  const cfg = { foldPrefixes: [], sourceRoots: [], testRoots: [], moduleRoots: [], stripSharedPrefix: true };
+  let section = null;
+  for (const b of doc.children) {
+    if (b.kind === "heading") { section = b.text.trim().toLowerCase(); continue; }
+    if (b.kind !== "list") continue;
+    const items = b.items.map(itemText).filter(Boolean);
+    if (Object.hasOwn(SECTIONS, section)) cfg[SECTIONS[section]] = items;
+    else if (section === "options") {
+      for (const it of items) {
+        const m = it.match(/^strip-shared-prefix\s*:\s*(on|off|true|false)$/i);
+        if (m) cfg.stripSharedPrefix = /^(on|true)$/i.test(m[1]);
+      }
+    }
+  }
+  return cfg;
+}
+
+export function serializeFoldings(cfg) {
+  const list = (xs) => xs.map((x) => `- ${x}`).join("\n");
+  return [
+    "=== meta",
+    'title = "codemap foldings"',
+    "===",
+    "",
+    "Ceremony folded out of module display names. Seeded on first build; edit",
+    "freely — build never rewrites this. The shared package prefix (group-ids",
+    "like com/acme/app) is stripped automatically and needs no entry here; set",
+    "strip-shared-prefix to off under Options to disable it.",
+    "",
+    "Add a directory under module-roots to force it to display as its own",
+    "module — for a submodule a build tool declares centrally but whose folder",
+    "carries no manifest, or any layout the detector cannot see.",
+    "",
+    "## fold-prefixes",
+    "",
+    list(cfg.foldPrefixes),
+    "",
+    "## source-roots",
+    "",
+    list(cfg.sourceRoots),
+    "",
+    "## test-roots",
+    "",
+    list(cfg.testRoots),
+    "",
+    "## module-roots",
+    "",
+    list(cfg.moduleRoots ?? []),
+    "",
+    "## options",
+    "",
+    `- strip-shared-prefix: ${cfg.stripSharedPrefix ? "on" : "off"}`,
+    "",
+  ].join("\n");
+}
+
+// Seeded config for a first build: structural fold-layers (above-root
+// ceremony dirs, derived from the discovered module roots) unioned with
+// known per-language ceremony (Cargo's `crates/`). Source/test roots always
+// start from the same global defaults — the human edits foldings.geml from
+// there; the build never rewrites it once it exists.
+export function defaultFoldings({ moduleRoots, languages }) {
+  const langPrefixes = (languages ?? []).flatMap((l) => LANG_FOLD_PREFIXES[l] ?? []);
+  const foldPrefixes = [...new Set([...deriveFoldLayers(moduleRoots ?? []), ...langPrefixes])].sort();
+  return { foldPrefixes, sourceRoots: [...DEFAULT_SOURCE_ROOTS], testRoots: [...DEFAULT_TEST_ROOTS], moduleRoots: [], stripSharedPrefix: true };
+}
+
+// Read <outDir>/_index/foldings.geml, or seed it on first build. Write-once:
+// an existing file is the human's — we read it and never rewrite it (the
+// refresh.json contract). A missing or unreadable file never crashes the
+// build: seed/fall back to defaults and say so. Returns { config, seeded }.
+export function loadOrSeedFoldings({ outDir, moduleRoots, languages }) {
+  const path = join(outDir, "_index", "foldings.geml");
+  if (existsSync(path)) {
+    try { return { config: parseFoldings(readFileSync(path, "utf8")), seeded: false }; }
+    catch (e) {
+      console.error(`warning: ignoring ${path} (${e.message}) — using default foldings; fix the file to re-enable your edits.`);
+      return { config: defaultFoldings({ moduleRoots, languages }), seeded: false };
+    }
+  }
+  const config = defaultFoldings({ moduleRoots, languages });
+  try {
+    mkdirSync(join(outDir, "_index"), { recursive: true });
+    writeFileSync(path, serializeFoldings(config));
+  } catch (e) { console.error(`warning: could not seed ${path} (${e.message}).`); }
+  return { config, seeded: true };
+}

package/codemap/joern-export.sc

@@ -1,83 +1,83 @@
-// geml-code-graph Joern export (P1, DESIGN §3.4).
-// Runs INSIDE joern; emits raw method/call records as JSONL for adapters/joern.mjs.
-//
-// Parameters come from ENVIRONMENT VARIABLES, not --param: on Windows the
-// joern.bat -> repl-bridge.bat hop re-tokenizes %* and cmd.exe treats `=` as a
-// delimiter, so `--param k=v` never survives intact. Env vars pass through
-// every layer on every OS:
-//
-//   GEML_SRC=/abs/path/to/src GEML_OUT=/abs/path/to/build/raw \
-//     joern --script geml-parser/codemap/joern-export.sc
-//
-// Output:
-//   <GEML_OUT>/methods.jsonl   one record per internal method
-//   <GEML_OUT>/calls.jsonl     one record per call site, callees resolved by Joern
-//
-// Identity: methods are keyed by fullName|signature|filename — the adapter
-// mints anchors and stable ids from these; this script stays dumb on purpose.
-import java.io.{File, PrintWriter}
-
-@main def exec(): Unit = {
-  val codeDir = sys.env.getOrElse("GEML_SRC", { System.err.println("GEML_SRC not set"); sys.exit(2) })
-  val outDir = sys.env.getOrElse("GEML_OUT", { System.err.println("GEML_OUT not set"); sys.exit(2) })
-  // GEML_LANG (optional): force a frontend in mixed-language repos, where
-  // auto-detection may pick the majority language instead of the intended one.
-  // Values are Joern's --language names: JAVASRC, NEWC, PYTHONSRC, JSSRC, …
-  sys.env.get("GEML_LANG") match {
-    case Some(lang) => importCode(inputPath = codeDir, projectName = "geml-code-graph", language = lang)
-    case None       => importCode(inputPath = codeDir, projectName = "geml-code-graph")
-  }
-
-  def esc(s: String): String =
-    s.replace("\\", "\\\\").replace("\"", "\\\"")
-     .replace("\n", "\\n").replace("\r", "\\r").replace("\t", "\\t")
-  def jstr(s: String): String = "\"" + esc(s) + "\""
-
-  new File(outDir).mkdirs()
-
-  val skipName = (n: String) => n == "<global>" || n.startsWith("<operator>") || n.startsWith("<clinit>")
-
-  // ---- methods ----
-  val mOut = new PrintWriter(new File(outDir, "methods.jsonl"), "UTF-8")
-  cpg.method.filter(m => !m.isExternal && !skipName(m.name)).foreach { m =>
-    mOut.println(
-      s"""{"name":${jstr(m.name)},"fullName":${jstr(m.fullName)},"signature":${jstr(m.signature)},""" +
-      s""""file":${jstr(m.filename)},"lineStart":${m.lineNumber.map(_.toString).getOrElse("null")},""" +
-      s""""lineEnd":${m.lineNumberEnd.map(_.toString).getOrElse("null")}}"""
-    )
-  }
-  mOut.close()
-
-  // ---- calls ----
-  // For each call site inside an internal method: Joern-resolved callees.
-  // Several internal callees = dispatch candidates (the adapter keeps them ALL,
-  // per the "never force a single candidate" red line). No internal callee =
-  // unresolved from the graph's point of view (external / pointer call).
-  // Operator calls are noise (arithmetic, casts, field access) EXCEPT
-  // <operator>.pointerCall — a function-pointer invocation is a real dispatch
-  // site the graph cannot resolve statically, so it must surface as an
-  // unresolved call (blind spots are shown, not hidden). Its readable label is
-  // the source expression itself.
-  val cOut = new PrintWriter(new File(outDir, "calls.jsonl"), "UTF-8")
-  cpg.call.filterNot(c => c.name.startsWith("<operator>") && c.name != "<operator>.pointerCall").foreach { c =>
-    val caller = c.method
-    if (!caller.isExternal && !skipName(caller.name)) {
-      val callees = c.callee.l
-      val internal = callees.filter(m => !m.isExternal && !skipName(m.name))
-      val tos = internal.map(m =>
-        s"""{"fullName":${jstr(m.fullName)},"signature":${jstr(m.signature)},"file":${jstr(m.filename)}}"""
-      ).mkString("[", ",", "]")
-      val label =
-        if (c.name == "<operator>.pointerCall") c.code.takeWhile(_ != '\n').take(48)
-        else c.name
-      cOut.println(
-        s"""{"callerFullName":${jstr(caller.fullName)},"callerSignature":${jstr(caller.signature)},""" +
-        s""""callerFile":${jstr(caller.filename)},"name":${jstr(label)},""" +
-        s""""line":${c.lineNumber.map(_.toString).getOrElse("null")},"callees":$tos}"""
-      )
-    }
-  }
-  cOut.close()
-
-  println(s"geml-code-graph joern-export: done -> $outDir")
-}
+// geml-code-graph Joern export (P1, DESIGN §3.4).
+// Runs INSIDE joern; emits raw method/call records as JSONL for adapters/joern.mjs.
+//
+// Parameters come from ENVIRONMENT VARIABLES, not --param: on Windows the
+// joern.bat -> repl-bridge.bat hop re-tokenizes %* and cmd.exe treats `=` as a
+// delimiter, so `--param k=v` never survives intact. Env vars pass through
+// every layer on every OS:
+//
+//   GEML_SRC=/abs/path/to/src GEML_OUT=/abs/path/to/build/raw \
+//     joern --script geml-parser/codemap/joern-export.sc
+//
+// Output:
+//   <GEML_OUT>/methods.jsonl   one record per internal method
+//   <GEML_OUT>/calls.jsonl     one record per call site, callees resolved by Joern
+//
+// Identity: methods are keyed by fullName|signature|filename — the adapter
+// mints anchors and stable ids from these; this script stays dumb on purpose.
+import java.io.{File, PrintWriter}
+
+@main def exec(): Unit = {
+  val codeDir = sys.env.getOrElse("GEML_SRC", { System.err.println("GEML_SRC not set"); sys.exit(2) })
+  val outDir = sys.env.getOrElse("GEML_OUT", { System.err.println("GEML_OUT not set"); sys.exit(2) })
+  // GEML_LANG (optional): force a frontend in mixed-language repos, where
+  // auto-detection may pick the majority language instead of the intended one.
+  // Values are Joern's --language names: JAVASRC, NEWC, PYTHONSRC, JSSRC, …
+  sys.env.get("GEML_LANG") match {
+    case Some(lang) => importCode(inputPath = codeDir, projectName = "geml-code-graph", language = lang)
+    case None       => importCode(inputPath = codeDir, projectName = "geml-code-graph")
+  }
+
+  def esc(s: String): String =
+    s.replace("\\", "\\\\").replace("\"", "\\\"")
+     .replace("\n", "\\n").replace("\r", "\\r").replace("\t", "\\t")
+  def jstr(s: String): String = "\"" + esc(s) + "\""
+
+  new File(outDir).mkdirs()
+
+  val skipName = (n: String) => n == "<global>" || n.startsWith("<operator>") || n.startsWith("<clinit>")
+
+  // ---- methods ----
+  val mOut = new PrintWriter(new File(outDir, "methods.jsonl"), "UTF-8")
+  cpg.method.filter(m => !m.isExternal && !skipName(m.name)).foreach { m =>
+    mOut.println(
+      s"""{"name":${jstr(m.name)},"fullName":${jstr(m.fullName)},"signature":${jstr(m.signature)},""" +
+      s""""file":${jstr(m.filename)},"lineStart":${m.lineNumber.map(_.toString).getOrElse("null")},""" +
+      s""""lineEnd":${m.lineNumberEnd.map(_.toString).getOrElse("null")}}"""
+    )
+  }
+  mOut.close()
+
+  // ---- calls ----
+  // For each call site inside an internal method: Joern-resolved callees.
+  // Several internal callees = dispatch candidates (the adapter keeps them ALL,
+  // per the "never force a single candidate" red line). No internal callee =
+  // unresolved from the graph's point of view (external / pointer call).
+  // Operator calls are noise (arithmetic, casts, field access) EXCEPT
+  // <operator>.pointerCall — a function-pointer invocation is a real dispatch
+  // site the graph cannot resolve statically, so it must surface as an
+  // unresolved call (blind spots are shown, not hidden). Its readable label is
+  // the source expression itself.
+  val cOut = new PrintWriter(new File(outDir, "calls.jsonl"), "UTF-8")
+  cpg.call.filterNot(c => c.name.startsWith("<operator>") && c.name != "<operator>.pointerCall").foreach { c =>
+    val caller = c.method
+    if (!caller.isExternal && !skipName(caller.name)) {
+      val callees = c.callee.l
+      val internal = callees.filter(m => !m.isExternal && !skipName(m.name))
+      val tos = internal.map(m =>
+        s"""{"fullName":${jstr(m.fullName)},"signature":${jstr(m.signature)},"file":${jstr(m.filename)}}"""
+      ).mkString("[", ",", "]")
+      val label =
+        if (c.name == "<operator>.pointerCall") c.code.takeWhile(_ != '\n').take(48)
+        else c.name
+      cOut.println(
+        s"""{"callerFullName":${jstr(caller.fullName)},"callerSignature":${jstr(caller.signature)},""" +
+        s""""callerFile":${jstr(caller.filename)},"name":${jstr(label)},""" +
+        s""""line":${c.lineNumber.map(_.toString).getOrElse("null")},"callees":$tos}"""
+      )
+    }
+  }
+  cOut.close()
+
+  println(s"geml-code-graph joern-export: done -> $outDir")
+}