@geml/geml 1.7.0 → 1.7.2

package/README.md

@@ -96,8 +96,11 @@ Every command reads a file path, or `-` for stdin. Exit codes: `0` ok ·
 ```sh
 geml doc.geml                       # document-model JSON (default --to json)
 geml doc.geml --to md|html|geml     # convert; geml notes.md -> GEML
+geml list   doc.geml                # CALL FIRST: every block, its address, kind, line range
+geml find   "text" doc.geml|dir     # search block CONTENT -> file<TAB>address; exit 1 = no hit
 geml get    doc.geml ['<selector>'] # list addressable blocks, or print what the selector matches
-geml set    doc.geml '<selector>' [--head|--body] [--in F[#src]]   # replace ONE block's content
+geml get    doc.geml '#sec' --intro # a section cuts three ways: --head | --intro | --body
+geml set    doc.geml '<selector>' [--head|--intro|--body] [--in F[#src]]   # replace ONE block's content
 geml add    doc.geml (--append|--before #id|--after #id) [--in F[#src]]   # insert a fragment
 geml delete doc.geml '#id' ['#id2' …]     # remove one or more blocks
 geml rename doc.geml '#old' '#new'        # rename an id + every reference to it
@@ -126,9 +129,22 @@ The agent loop: `geml get` a block → `set`/`add`/`delete`/`rename` it →
 
 `get` answers with N contents when N match (document order, count on stderr);
 `set` writes ONE block, so a selector matching several is refused (exit 2) with
-the unique address of each candidate. `--head` is the head line, `--body` the
-body; both round-trip — `geml get f X --body | geml set f X --body` leaves the
-file byte-identical.
+the unique address of each candidate. A section cuts three ways: `--head` is the
+heading line, `--intro` its opening region — everything under it up to its first
+subheading — and `--body` everything under it, so `--body` always contains
+`--intro`, and equals it when the section has no subheading. All three
+round-trip — `geml get f X --body | geml set f X --body` leaves the file
+byte-identical — and `--intro` is how a section's opening is edited without
+pulling its subsections into context. A block has no intro; asking for one is a
+usage error rather than a quiet fall back to the body.
+
+A write is refused when it would break the document, never merely because it
+removes something. A replacement that drops blocks is carried out and the
+dropped blocks are named on stderr — unnamed ones counted, references left
+dangling reported — with `geml revert` as the way back. That is the same stance
+`delete` takes, so removing content has one rule rather than two, and no region
+becomes uneditable because something inside it happens to carry an id. The
+round trip above drops nothing: the blocks came back in the text you sent.
 
 A `@<hex>` **content address** is the first 8 hex of the SHA-256 of the block's
 own text (line endings normalized to LF, no trailing newline), with `~1`, `~2`…

package/codemap/build.mjs

@@ -36,7 +36,7 @@
 //
 // After building, run:  geml codemap verify <out-dir>
 import { writeFileSync, mkdirSync, existsSync, readFileSync, statSync } from "node:fs";
-import { join, resolve, basename, dirname, relative } from "node:path";
+import { join, resolve, basename, dirname, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { execFileSync, spawnSync } from "node:child_process";
 import { emit } from "./emit.mjs";
@@ -100,7 +100,7 @@ if (root && !inputs.length) {
   const { files, manifests, pkgs } = collectSourceFiles(rootAbs);
   const excluder = makeExcluder({
     root: rootAbs, globs: excludeGlobs0, gitignore: !args.includes("--no-gitignore"),
-    files: [...files, ...manifests, ...pkgs], exec: execFileSync,
+    files: [...files, ...manifests, ...pkgs], run: execFileSync,
   });
   const jobs = detectLanguages(rootAbs, { files, manifests, pkgs, excluder });
   detectedLanguages = [...new Set(jobs.map((j) => j.language))];
@@ -136,7 +136,10 @@ if (root && !inputs.length) {
   // PATH (npx / joern) whose .cmd/.bat shim uses %~dp0 breaks if the name is
   // quoted — cmd then resolves %~dp0 against the cwd, not the shim's dir. A
   // spaced launcher PATH is a full path, so quoting it keeps %~dp0 correct.
-  const q = (s) => (/[\s"]/.test(String(s)) ? `"${String(s).replace(/"/g, '\\"')}"` : String(s));
+  // WHEN it does quote, it defers to shq below: escaping only `"` left a
+  // trailing backslash (a path ending `...\`) escaping our own closing quote,
+  // which merges the next token into this one. Same CRT rules, one source.
+  const q = (s) => (/[\s"]/.test(String(s)) ? shq(s) : String(s));
   // Hardened quote for command ARGUMENTS on win32. Node does NOT escape args
   // under shell:true — it only concatenates them (Node DEP0190) — so an
   // unquoted argument such as a source directory named `a&calc` reaching the
@@ -378,7 +381,7 @@ const excluder = makeExcluder({
   globs: excludeGlobs,
   gitignore: !args.includes("--no-gitignore"),
   files: [...new Set(symbols.map((s) => s.file))],
-  exec: execFileSync,
+  run: execFileSync,
 });
 const kept = symbols.filter((s) => !excluder(s.file));
 const excludedCount = symbols.length - kept.length;
@@ -391,7 +394,7 @@ if (root && !recordRecipe && !entryHints.length) {
   const c = collectSourceFiles(rootAbs);
   const excl = makeExcluder({
     root: rootAbs, globs: excludeGlobs, gitignore: !args.includes("--no-gitignore"),
-    files: [...c.files, ...c.manifests, ...c.pkgs], exec: execFileSync,
+    files: [...c.files, ...c.manifests, ...c.pkgs], run: execFileSync,
   });
   entryHints = detectEntries(rootAbs, {
     files: c.files.filter((f) => !excl(f)),
@@ -420,7 +423,18 @@ try {
   const { edges: httpEdges, audit } = buildCrossStackOverlay({
     symbols,
     files: scanFiles,
-    readText: (rel) => { try { return readFileSync(join(rootAbs, ...rel.split("/")), "utf8"); } catch { return null; } },
+    // `rel` is indexer OUTPUT, not a path this build authored, so a `..`
+    // segment must not turn a source read into an escape from the scanned
+    // root. Same gate the document resolver uses: resolve first, then require
+    // the result to BE the root or sit under it — compared with the separator,
+    // so a sibling named `<root>-evil` is not mistaken for a child.
+    readText: (rel) => {
+      try {
+        const p = resolve(rootAbs, ...String(rel).split("/"));
+        if (p !== rootAbs && !p.startsWith(rootAbs + sep)) return null;
+        return readFileSync(p, "utf8");
+      } catch { return null; }
+    },
   });
   for (const e of httpEdges) edges.push(e);
   if (httpEdges.length) {

package/codemap/exclude.mjs

@@ -15,17 +15,17 @@ import { execFileSync as _execFileSync } from "node:child_process";
 // Minimal gitignore-flavoured glob: `**` spans path separators, `*` stays
 // within a segment, everything else is literal. Anchored to the whole path.
 export function globToRegExp(glob) {
+  // The glob comes from a `--exclude` argument, so nothing in it may reach the
+  // compiled pattern as *syntax*. Split on the wildcards, keeping them (the
+  // capture group), which leaves the array strictly alternating: even indices
+  // are literal text, odd indices are `*`, `**` or `**/`. Literals go through a
+  // total regex-metacharacter escape; wildcards map to fixed patterns. Neither
+  // path can carry an unescaped metacharacter through.
+  const parts = String(glob).split(/(\*\*\/?|\*)/);
   let re = "";
-  for (let i = 0; i < glob.length; i++) {
-    const c = glob[i];
-    if (c === "*") {
-      if (glob[i + 1] === "*") { re += ".*"; i++; if (glob[i + 1] === "/") i++; }
-      else re += "[^/]*";
-    } else if ("\\^$+?.()|{}[]".includes(c)) {
-      re += "\\" + c;
-    } else {
-      re += c;
-    }
+  for (let i = 0; i < parts.length; i++) {
+    if (i % 2 === 0) re += parts[i].replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    else re += parts[i] === "*" ? "[^/]*" : ".*"; // `**` and `**/` span separators
   }
   return new RegExp("^" + re + "$");
 }
@@ -33,10 +33,14 @@ export function globToRegExp(glob) {
 // Ask git which of `files` it ignores. Returns a Set of the ignored paths.
 // check-ignore exits 1 when nothing matches and 128 when git is unavailable /
 // the dir is not a repo — both mean "ignore nothing", not a build failure.
-export function gitIgnored(root, files, exec = _execFileSync) {
+// The injected runner is named `run`, not `exec`: it is always an execFile-shaped
+// (program, args[]) call that spawns NO shell, whereas a callback named `exec`
+// reads — to a human skimming, and to a static analyser — as the shell-string
+// child_process API. The name should not imply the dangerous one.
+export function gitIgnored(root, files, run = _execFileSync) {
   if (!files.length) return new Set();
   try {
-    const out = exec("git", ["-C", root, "check-ignore", "--stdin"], { input: files.join("\n"), encoding: "utf8" });
+    const out = run("git", ["-C", root, "check-ignore", "--stdin"], { input: files.join("\n"), encoding: "utf8" });
     return new Set(out.split(/\r?\n/).filter(Boolean));
   } catch (e) {
     const out = e && e.stdout ? String(e.stdout) : "";
@@ -45,8 +49,8 @@ export function gitIgnored(root, files, exec = _execFileSync) {
 }
 
 // Build a predicate (file) => shouldExclude.
-export function makeExcluder({ root, globs = [], gitignore = true, files = [], exec } = {}) {
+export function makeExcluder({ root, globs = [], gitignore = true, files = [], run } = {}) {
   const res = globs.map(globToRegExp);
-  const ignored = gitignore ? gitIgnored(root, files, exec) : new Set();
+  const ignored = gitignore ? gitIgnored(root, files, run) : new Set();
   return (file) => ignored.has(file) || res.some((r) => r.test(file));
 }

package/codemap/refresh.mjs

@@ -95,7 +95,10 @@ let trusted = isRecipeTrusted(fingerprint);
 //     full path is quoted), every argument via shq (ALWAYS double-quoted, so
 //     cmd.exe treats & | < > ( ) ^ and whitespace as literal). An injected
 //     metachar inside a dir-name argument is therefore inert.
-const q = (s) => (/[\s"]/.test(String(s)) ? `"${String(s).replace(/"/g, '\\"')}"` : String(s));
+// q quotes only when it must; WHEN it does it defers to shq, so a program path
+// ending in a backslash cannot escape our own closing quote and swallow the
+// next token. One set of CRT rules, in one place.
+const q = (s) => (/[\s"]/.test(String(s)) ? shq(s) : String(s));
 const shq = (s) => `"${String(s).replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1')}"`;
 // Human-readable render of a step for the log / refusal message — DISPLAY ONLY,
 // never executed. Falls back to String() for a stale (non-structured) step.

package/codemap/verify.mjs

@@ -37,7 +37,10 @@ if (!cli) cli = existsSync(localParser) ? localParser : "geml";
 // `.geml` filename containing & | ( ) would otherwise break out and inject.
 // cmd.exe treats those metacharacters and whitespace as literal inside quotes;
 // CRT rules for embedded " / trailing \.
-const q = (s) => (/[\s"]/.test(String(s)) ? `"${String(s).replace(/"/g, '\\"')}"` : String(s));
+// q quotes only when it must; WHEN it does it defers to shq, so a program path
+// ending in a backslash cannot escape our own closing quote and swallow the
+// next token. One set of CRT rules, in one place.
+const q = (s) => (/[\s"]/.test(String(s)) ? shq(s) : String(s));
 const shq = (s) => `"${String(s).replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1')}"`;
 // A codemap document's `src=` routes are written relative to the indexed
 // SOURCE root (`geml-parser/src/attrs.ts` from a document two levels down), so

package/dist/block-edit.js

@@ -25,6 +25,20 @@ function splitLines(source) {
 function stripEnding(line) {
     return line.replace(/(\r\n|\r|\n)$/, "");
 }
+// A local mirror of geml.ts's trimSpaceTabEnd — geml.ts already imports THIS
+// module (normalizeBlockId), so importing back would close a cycle. Linear on
+// purpose: `/[ \t]+$/` restarts the run at every index inside a run that never
+// reaches the end of the line, which is quadratic in the line's length.
+function trimSpaceTabEnd(s) {
+    let i = s.length;
+    while (i > 0) {
+        const c = s.charCodeAt(i - 1);
+        if (c !== 0x20 && c !== 0x09)
+            break;
+        i--;
+    }
+    return i === s.length ? s : s.slice(0, i);
+}
 // Rewrite the id inside a `{…}` attribute block to `#newId`, keeping the braces
 // and every other class/attr byte. If no id is present, insert `#newId` as the
 // first token. The id token sits at a token boundary (`{` or whitespace) and
@@ -98,7 +112,7 @@ export function normalizeBlockId(blockSrc, newId) {
         const openLen = /^=+/.exec(f[1])[0].length;
         for (let j = hi + 1; j < lines.length; j++) {
             const ct = stripEnding(lines[j]);
-            const trimmed = ct.replace(/[ \t]+$/, "");
+            const trimmed = trimSpaceTabEnd(ct);
             if (/^=+$/.test(trimmed) && trimmed.length === openLen)
                 break; // plain close: done
             const cm = /^(={3,}[ \t]+#)([^\s}]+)([ \t]*)$/.exec(ct);

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};