@geml/geml 1.5.0 → 1.6.0

package/README.md

@@ -21,7 +21,8 @@ print("hi")
 ===
 ```
 
-- **Addressable** — every block has an `#id`; `geml get` / `geml set '#id'`
+- **Addressable** — every block can be named: an `#id`, or a content address for
+  the ones nobody named; `geml get` / `geml set '<selector>'`
   read or patch one section without re-emitting the whole file (on this repo's
   own spec, ~**66× less context** than shipping the whole document).
 - **Verifiable** — references are checked at build time (a dangling `#id` is an
@@ -95,20 +96,50 @@ 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 get    doc.geml ['#id']        # list addressable ids, or print one block (heading id = its section)
-geml set    doc.geml '#id' [--head|--body] [--in F[#src]]   # replace a block's content (id kept)
+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 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
 geml revert doc.geml '#id' [--rev -1]     # undo a block: splice / resurrect / remove
 geml check  doc.geml [--root <dir>]       # validate only: diagnostics + exit code (--json for the array)
-geml history <commit|verify|show|restore|log> doc.geml [...]   # .gemlhistory version sidecar
+geml history <save|get|restore|verify> doc.geml [...]   # .gemlhistory version sidecar (get = list revisions, or print one)
 geml codemap <build|verify|render|serve|refresh|find|mcp>      # your codebase's call graph as GEML docs
 geml --help | --version             # --version --json prints {"parser","spec"}
 ```
 
 The agent loop: `geml get` a block → `set`/`add`/`delete`/`rename` it →
-`geml check` → `geml history commit` — small, precise, verifiable edits.
+`geml check` → `geml history save` — small, precise, verifiable edits.
+
+### Selectors
+
+`get` and `set` take the same selector, which is a **filter over blocks**:
+
+| Selector | Matches |
+|---|---|
+| *(omitted)* | nothing — `get` **lists** every addressable block, one per line, by its shortest unique address |
+| `#id` | that block. A heading id addresses its **whole section** |
+| `'## Heading'` | a heading line copied out of the document, resolved to its id |
+| `'=== note'` | **every** `note` block — 0..N of them |
+| `'=== note@a3f9c1d2'` | one block by CONTENT, for blocks that carry no `#id` |
+| `'@a3f9c1d2'` | the same, with the type check dropped |
+
+`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.
+
+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`…
+distinguishing byte-identical blocks. Read them out of `geml get doc.geml` —
+they are printed for every block that has no `#id`. Being content-derived, an
+address **goes stale when the block changes** and then fails with exit 1 rather
+than silently addressing a different block: it doubles as a precondition. That
+also means `set` through one prints the new address on stderr. The exact hash
+input is pinned in
+[the selector design doc](../docs/design/specs/2026-08-04-geml-get-set-selector-design-change.md)
+§3.4 so a second implementation computes the same values.
 
 Conversion is one entry — `geml <file> [--to json|html|md|geml]`; the input
 format is inferred (`--from` overrides > extension > GEML), the target is `--to`
@@ -143,7 +174,7 @@ that did not exist then. So each forward edit has an inverse:
 | `rename #old #new` | `rename #new #old` (self-inverse) |
 
 `revert` reads the `.gemlhistory` sidecar, so `set`/`delete`/`add` undo needs a
-prior `geml history commit`; `rename` is its own inverse and needs no history.
+prior `geml history save`; `rename` is its own inverse and needs no history.
 
 A **heading's** `#id` addresses its whole **section** — the heading line through
 the line before the next heading of the same-or-higher level — so the prose

package/codemap/build.mjs

@@ -501,7 +501,7 @@ console.error(
 );
 
 // --history: snapshot every changed document into its .gemlhistory sidecar —
-// the graph's own architectural history (geml history log / revert per node).
+// the graph's own architectural history (geml history get / revert per node).
 // Targets = documents rewritten this build, plus any document that has no
 // sidecar yet (first run, or --history adopted later).
 if (args.includes("--history")) {
@@ -510,7 +510,7 @@ if (args.includes("--history")) {
     console.error("--history needs the built parser (cd geml-parser && npm install && npm run build)");
     process.exit(1);
   }
-  const { commit, isCurrent } = await import(`file://${histMod.replace(/\\/g, "/")}`);
+  const { save, isCurrent } = await import(`file://${histMod.replace(/\\/g, "/")}`);
   const message = flag("-m", flag("--message", "graph build"));
   const targets = new Set(stats.writtenDocs);
   for (const d of stats.allDocs) {
@@ -518,7 +518,7 @@ if (args.includes("--history")) {
     const gemlPath = join(outDir, d);
     const sidecar = gemlPath.replace(/\.geml$/, ".gemlhistory");
     // No sidecar yet, or the sidecar tip drifted from the file (a previous
-    // commit attempt was refused): both need a snapshot even though this build
+    // save was refused): both need a snapshot even though this build
     // did not rewrite the document.
     if (!existsSync(sidecar) || !isCurrent(sidecar, gemlPath)) targets.add(d);
   }
@@ -527,10 +527,10 @@ if (args.includes("--history")) {
   for (const d of [...targets].sort()) {
     const gemlPath = join(outDir, d);
     try {
-      commit({ gemlPath, historyPath: gemlPath.replace(/\.geml$/, ".gemlhistory"), summary: message });
+      save({ gemlPath, historyPath: gemlPath.replace(/\.geml$/, ".gemlhistory"), summary: message });
       committed++;
     } catch (e) {
-      // One document's history refusing a commit (e.g. the round-trip gate)
+      // One document's history refusing a save (e.g. the round-trip gate)
       // must not abort the build or the other documents' snapshots. The
       // failing document's previous revision stays intact.
       histFailed.push(d);

package/dist/diagnostics.d.ts

@@ -1,4 +1,4 @@
-export type DiagnosticCode = "unterminated-block" | "unknown-block-type" | "block-nesting-too-deep" | "list-nesting-too-deep" | "inline-nesting-too-deep" | "duplicate-id" | "unresolved-reference" | "unresolved-footnote" | "unresolved-cross-document-reference" | "unresolvable-document" | "unchecked-cross-document-reference" | "embed-missing-src" | "ignored-embed-body" | "transclusion-cycle" | "embed-target-not-geml" | "media-target-is-document" | "inline-transclusion-not-inline" | "unsafe-embed-scheme" | "source-attr-conflict" | "unresolvable-table-source" | "table-source-not-a-table" | "unknown-metadata-reference" | "table-src-and-body" | "unknown-table-format" | "bad-compute-formula" | "unlexable-compute-formula" | "compute-error" | "bad-summary-entry" | "summary-unknown-column" | "unlexable-summary-expression" | "summary-error" | "bad-span" | "span-outside-table" | "unknown-diagram-format" | "ignored-diagram-body" | "code-graph-missing-src" | "code-graph-unresolvable-document" | "chart-missing-data" | "chart-data-not-a-table" | "chart-missing-type" | "chart-unknown-type" | "chart-unknown-rows-scope" | "chart-missing-channel" | "chart-empty-channel" | "chart-unknown-column" | "chart-unused-channel" | "chart-missing-summary-row" | "chart-summary-row-unavailable" | "chart-non-numeric-value";
+export type DiagnosticCode = "unterminated-block" | "unknown-block-type" | "unknown-attribute" | "block-nesting-too-deep" | "list-nesting-too-deep" | "inline-nesting-too-deep" | "duplicate-id" | "unresolved-reference" | "unresolved-footnote" | "unresolved-cross-document-reference" | "unresolvable-document" | "unchecked-cross-document-reference" | "embed-missing-src" | "ignored-embed-body" | "transclusion-cycle" | "embed-target-not-geml" | "media-target-is-document" | "inline-transclusion-not-inline" | "unsafe-embed-scheme" | "unresolvable-table-source" | "table-source-not-a-table" | "unknown-metadata-reference" | "table-src-and-body" | "unknown-table-format" | "bad-compute-formula" | "unlexable-compute-formula" | "compute-error" | "compute-non-numeric-cell" | "compute-not-a-number" | "bad-summary-entry" | "summary-unknown-column" | "unlexable-summary-expression" | "summary-error" | "unknown-diagram-format" | "ignored-diagram-body" | "code-graph-missing-src" | "code-graph-unresolvable-document" | "chart-missing-data" | "chart-data-not-a-table" | "chart-missing-type" | "chart-unknown-type" | "chart-unknown-rows-scope" | "chart-missing-channel" | "chart-empty-channel" | "chart-unknown-column" | "chart-unused-channel" | "chart-missing-summary-row" | "chart-summary-row-unavailable" | "chart-non-numeric-value";
 export interface Diagnostic {
     severity: "error" | "warning";
     code: DiagnosticCode;

package/dist/diagnostics.js

@@ -15,6 +15,7 @@
 export const SEVERITY = {
     "unterminated-block": "error",
     "unknown-block-type": "warning",
+    "unknown-attribute": "warning",
     "block-nesting-too-deep": "error",
     "list-nesting-too-deep": "error",
     "inline-nesting-too-deep": "error",
@@ -31,7 +32,6 @@ export const SEVERITY = {
     "media-target-is-document": "error",
     "inline-transclusion-not-inline": "error",
     "unsafe-embed-scheme": "error",
-    "source-attr-conflict": "error",
     "unresolvable-table-source": "error",
     "table-source-not-a-table": "error",
     "unknown-metadata-reference": "error",
@@ -40,12 +40,12 @@ export const SEVERITY = {
     "bad-compute-formula": "error",
     "unlexable-compute-formula": "error",
     "compute-error": "error",
+    "compute-non-numeric-cell": "warning",
+    "compute-not-a-number": "warning",
     "bad-summary-entry": "error",
     "summary-unknown-column": "error",
     "unlexable-summary-expression": "error",
     "summary-error": "error",
-    "bad-span": "error",
-    "span-outside-table": "warning",
     "unknown-diagram-format": "warning",
     "ignored-diagram-body": "warning",
     "code-graph-missing-src": "warning",