@dtmd/temper 0.0.7 → 0.0.8

package/dist/src/prose.js

@@ -1,14 +1,54 @@
 /**
  * Prose — three constructors, one field type. A member's words are data the
  * member declares: `file()` for a document that keeps its medium, `` text`…` ``
- * for short inline prose, `blocks()` for fully composed embedded-member values. Whatever
- * the constructor, the words land byte-identical to their authored text (law 5).
+ * for short inline prose, `blocks()` for a composed body that interleaves verbatim
+ * prose spans with embedded-member values in authored order. Whatever
+ * the constructor, the words land byte-identical to their authored text.
  * Interpolations in `` text`…` `` are references, two intents apart: a **mention**
  * (a {@link Mentionable}) is a declared one-way edge that moves no content, and an
  * **include** (an {@link Include}) pulls the target file's bytes into the host's emitted
- * projection. Both are authored per word and resolution-checked at emit, never mined
- * (law 8).
+ * projection. Both are authored per word and resolution-checked at emit, never mined.
  */
+/**
+ * Spell a top-level member as the {@link Mentionable} a mention carries: its
+ * `kind:name` address, its bare name the display text — the convention every
+ * corpus repeats to cite a member from prose, captured once here.
+ */
+export function mentionOf(member) {
+    return { address: `${member.kind}:${member.name}`, display: member.name };
+}
+/**
+ * Whether a mention's unresolved address **defers to the gate** rather than refusing at
+ * emit: a top-level `kind:name` address whose kind is one the program declares at a
+ * discovery locus (an `at`-locus kind) may name a member discovered on disk, so `check`
+ * owns the verdict. An embedded leaf address (a `<host>/<kind>/<key>` form, carrying a
+ * `/`), a bare requirement name (no `:`), or a kind the program does not declare has no
+ * discovery locus and stays a dangling refusal.
+ */
+export function defersToGate(address, deferrableKinds) {
+    if (address.includes("/"))
+        return false;
+    const colon = address.indexOf(":");
+    return colon > 0 && deferrableKinds.has(address.slice(0, colon));
+}
+/**
+ * Refuse a mention whose address neither resolves against the scope's `mentionable`
+ * set nor defers to the gate ({@link defersToGate}) — the one dangling-mention refusal,
+ * shared by a member-level `Text` body, a composed body's prose span, and an embedded
+ * `Text` leaf. `context` prefixes the error so it names the host.
+ *
+ * # Throws
+ * If a mention names no declared value and its address has no discovery locus.
+ */
+export function checkMentions(mentions, scope, context) {
+    for (const mention of mentions) {
+        const { address } = mention.target;
+        if (!scope.mentionable.has(address) && !defersToGate(address, scope.deferrableKinds)) {
+            throw new Error(`${context}: mention of \`${address}\` resolves to no declared value — ` +
+                `a mention cannot dangle (specs/model/contract.md).`);
+        }
+    }
+}
 /** Whether an interpolation target is an include rather than a mention. */
 function isInclude(reference) {
     return reference.kind === "include";
@@ -40,8 +80,8 @@ function dedent(text) {
         .replace(/\n[ \t]*$/, "\n");
 }
 /**
- * Declare a document whose medium is preserved — read in whole at emit
- * (posture 1). `moduleUrl` is the declaring module's own `import.meta.url`,
+ * Declare a document whose medium is preserved — read in whole at emit.
+ * `moduleUrl` is the declaring module's own `import.meta.url`,
  * so `path` resolves relative to that module, never the process cwd:
  * `file(import.meta.url, "./long.md")`.
  */
@@ -52,7 +92,7 @@ export function file(moduleUrl, path) {
  * The inline dedenting prose constructor. Interpolate {@link Reference} values — a
  * {@link Mentionable} is a mention (moves no content), an {@link Include} pulls the
  * target's bytes in; either is opt-in per word, and plain prose with zero references is
- * fully legal forever (the opt-in Decision, `20-surface.md`).
+ * fully legal forever.
  *
  * # Throws
  * If an authored chunk carries {@link MENTION_SLOT} or {@link INCLUDE_SLOT} — the markers
@@ -89,14 +129,48 @@ export function text(strings, ...targets) {
 export function include(moduleUrl, path) {
     return { kind: "include", path, moduleUrl };
 }
-/** Compose fully-typed embedded-member values into a member's body (posture 3). */
+/**
+ * Compose a member's body from ordered children: verbatim prose spans
+ * ({@link text}) and embedded-member values interleaved in authored order. A prose
+ * span rides as prose — no wrapper member is minted to carry a narrative.
+ *
+ * # Throws
+ * If a child is a {@link File} — the parameter type excludes one, so only a JS or
+ * cast caller arrives here, and the alternative is a raw crash downstream on the
+ * `leaves` a `File` has no reason to carry.
+ */
 export function blocks(...values) {
+    values.forEach((value, index) => {
+        if (isFileValue(value)) {
+            throw new Error(`blocks(): block ${index} is a \`file()\` value — a composed body admits a ` +
+                `\`text\` span or an embedded member value. A document is a member's whole ` +
+                `\`prose\` body (\`prose: file(…)\`); to pull its bytes into a composed body, ` +
+                `interpolate \`include()\` into a \`text\` span (specs/model/pipeline.md, "The SDK").`);
+        }
+    });
     return { kind: "blocks", values };
 }
+/**
+ * Whether a composed-body child is a {@link File}. A child kind may itself be named
+ * `file`, so the kind tag alone is ambiguous — an embedded value always carries
+ * `leaves`, and only a `File` anchors a `moduleUrl`.
+ */
+function isFileValue(value) {
+    const candidate = value;
+    return candidate.kind === "file" && typeof candidate.moduleUrl === "string";
+}
+/**
+ * Whether a composed-body child is a verbatim prose span rather than an embedded
+ * member value — the discriminant emit and the row builders branch on to render a
+ * span as prose and count its refs at host level, never as a nested member.
+ */
+export function isTextSpan(value) {
+    return value.kind === "text";
+}
 /**
  * Render an inline body to its final text — the display rule applied: each
  * mention slot becomes its target's display form, the surrounding words
- * untouched (law 5). The chunk count is `mentions.length + 1` by {@link text}'s
+ * untouched. The chunk count is `mentions.length + 1` by {@link text}'s
  * construction, so the walk consumes every slot.
  */
 export function renderText(prose) {
@@ -109,26 +183,22 @@ export function renderText(prose) {
 }
 /**
  * Resolve a leaf's authored value to its stored/rendered string: a bare string
- * is unchanged; a `Text` leaf is mention-resolution-checked against
- * `mentionable` (loud on a dangling address) and rendered by {@link renderText}
- * — the same rule a member-level `Text` body resolves by. `context` prefixes
- * the dangling-mention error so it names the leaf, not just the mention.
+ * is unchanged; a `Text` leaf is mention-resolution-checked against `scope`
+ * ({@link checkMentions}: loud on a dangling address, a discovery-locus one
+ * deferred) and rendered by {@link renderText} — the same rule a member-level
+ * `Text` body resolves by. `context` prefixes the dangling-mention error so it
+ * names the leaf, not just the mention.
  *
  * # Throws
- * If a mention names no declared value.
+ * If a mention names no declared value and has no discovery locus.
  */
-export function resolveLeaf(value, mentionable, context) {
+export function resolveLeaf(value, scope, context) {
     if (typeof value === "string")
         return value;
     if (value.includes.length > 0) {
         throw new Error(`${context}: an embedded-member leaf cannot carry an include — a content pull is a ` +
             `member-body intent, not a fenced-value one (specs/model/pipeline.md, "The SDK").`);
     }
-    for (const mention of value.mentions) {
-        if (!mentionable.has(mention.target.address)) {
-            throw new Error(`${context}: mention of \`${mention.target.address}\` resolves to no declared value — ` +
-                `a mention cannot dangle (specs/model/contract.md).`);
-        }
-    }
+    checkMentions(value.mentions, scope, context);
     return renderText(value);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtmd/temper",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "The temper authoring face — the six-noun model as typed modules: harness(), kind<T>(), clause values, needs, and file()/text/blocks(). Emit compiles to the declaration rows the engine reads, a byte-faithful projection, and the lock.",
   "license": "(MIT OR Apache-2.0)",
   "repository": {
@@ -45,7 +45,7 @@
     "prepublishOnly": "npm run test"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^22.20.1",
     "typescript": "^5.6.0"
   },
   "bin": {