@notrealstudio/nr-md 0.1.1 → 0.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Denis Vinogradsky
+Copyright (c) 2026 Julian Garrett / Not Real Studio
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/includes.d.ts

@@ -3,6 +3,26 @@ export interface IncludeOptions {
     maxDepth?: number;
     /** Active sigil — only this sigil's includes are resolved. */
     sigil?: '$' | '@';
+    /**
+     * Canonical id (e.g. file path) of the root document. Passed to
+     * `resolvePath` as `from` for top-level includes.
+     */
+    from?: string;
+    /**
+     * Map a target as written in document `from` to a canonical id. When set,
+     * `readFile` receives the id (not the raw target), nested includes resolve
+     * against the file they are written in, and cycles are detected by id.
+     * `undefined` = not found (include left as-is). Without it targets are
+     * passed through verbatim (legacy behaviour).
+     */
+    resolvePath?: (target: string, from: string | undefined) => string | undefined;
+    /** On cycle: 'keep' (default) leaves the include as-is, 'throw' raises IncludeCycleError. */
+    onCycle?: 'keep' | 'throw';
+}
+/** Include cycle. `chain` — ids from the first repeated one back to itself. */
+export declare class IncludeCycleError extends Error {
+    readonly chain: string[];
+    constructor(chain: string[]);
 }
 /**
  * Resolve file includes in text. Replaces `$[[path]]` / `$[[path#section]]`

package/dist/includes.js

@@ -1,6 +1,43 @@
 // File includes: $[[path]] / @[[path]] preprocessor (format-spec §2.6).
 // Text-level substitution BEFORE parsing. Recursive with cycle detection.
 // Supports sections: $[[path#section]], $[[#section]] (from current text).
+// Path resolution is the caller's: `resolvePath(target, from)` makes nested
+// includes relative to the file they are written in (the core stays IO-free).
+/** Include cycle. `chain` — ids from the first repeated one back to itself. */
+export class IncludeCycleError extends Error {
+    chain;
+    constructor(chain) {
+        super(`include cycle: ${chain.join(' -> ')}`);
+        this.name = 'IncludeCycleError';
+        this.chain = chain;
+    }
+}
+function makeCtx(readFile, opts) {
+    return {
+        readFile,
+        sigil: opts?.sigil ?? '$',
+        maxDepth: opts?.maxDepth ?? 10,
+        resolvePath: opts?.resolvePath,
+        onCycle: opts?.onCycle ?? 'keep',
+        stack: opts?.from !== undefined && opts.resolvePath ? [opts.from] : [],
+    };
+}
+/** Resolve target → id; `undefined` = not found. */
+function toId(ctx, target) {
+    if (!ctx.resolvePath)
+        return target;
+    const from = ctx.stack.length ? ctx.stack[ctx.stack.length - 1] : undefined;
+    return ctx.resolvePath(target, from);
+}
+/** true — cycle, include must be left as-is (or it threw). */
+function isCycle(ctx, id) {
+    const at = ctx.stack.indexOf(id);
+    if (at < 0)
+        return false;
+    if (ctx.onCycle === 'throw')
+        throw new IncludeCycleError([...ctx.stack.slice(at), id]);
+    return true;
+}
 /**
  * Resolve file includes in text. Replaces `$[[path]]` / `$[[path#section]]`
  * with file/section content, recursively. Cycle detection by path.
@@ -11,17 +48,13 @@
  * Async version: resolveIncludesAsync.
  */
 export function resolveIncludes(text, readFile, opts) {
-    const sigil = opts?.sigil ?? '$';
-    const maxDepth = opts?.maxDepth ?? 10;
-    return expand(text, readFile, sigil, maxDepth, new Set(), 0, text);
+    return expand(text, makeCtx(readFile, opts), 0, text);
 }
 /**
  * Async version — readFile returns Promise.
  */
 export async function resolveIncludesAsync(text, readFile, opts) {
-    const sigil = opts?.sigil ?? '$';
-    const maxDepth = opts?.maxDepth ?? 10;
-    return expandAsync(text, readFile, sigil, maxDepth, new Set(), 0, text);
+    return expandAsync(text, makeCtx(readFile, opts), 0, text);
 }
 // ---------- Extract section from markdown ----------
 /**
@@ -69,7 +102,8 @@ function headingLevel(line) {
     return i;
 }
 // ---------- Sync expand ----------
-function expand(text, readFile, sigil, maxDepth, visited, depth, currentText) {
+function expand(text, ctx, depth, currentText) {
+    const { sigil, maxDepth } = ctx;
     if (depth > maxDepth)
         return text;
     let out = '';
@@ -116,12 +150,12 @@ function expand(text, readFile, sigil, maxDepth, visited, depth, currentText) {
                 }
                 continue;
             }
-            // Cycle detection
-            if (visited.has(filePath)) {
+            const id = toId(ctx, filePath);
+            if (id === undefined || isCycle(ctx, id)) {
                 out += text.slice(start, i);
                 continue;
             }
-            const content = readFile(filePath);
+            const content = ctx.readFile(id);
             if (content === undefined) {
                 out += text.slice(start, i);
                 continue;
@@ -137,9 +171,13 @@ function expand(text, readFile, sigil, maxDepth, visited, depth, currentText) {
                 result = extracted;
             }
             // Recurse
-            visited.add(filePath);
-            out += expand(result, readFile, sigil, maxDepth, visited, depth + 1, content);
-            visited.delete(filePath);
+            ctx.stack.push(id);
+            try {
+                out += expand(result, ctx, depth + 1, content);
+            }
+            finally {
+                ctx.stack.pop();
+            }
             continue;
         }
         out += text[i];
@@ -148,7 +186,8 @@ function expand(text, readFile, sigil, maxDepth, visited, depth, currentText) {
     return out;
 }
 // ---------- Async expand ----------
-async function expandAsync(text, readFile, sigil, maxDepth, visited, depth, currentText) {
+async function expandAsync(text, ctx, depth, currentText) {
+    const { sigil, maxDepth } = ctx;
     if (depth > maxDepth)
         return text;
     // Collect all include positions first, then resolve in order
@@ -188,11 +227,12 @@ async function expandAsync(text, readFile, sigil, maxDepth, visited, depth, curr
                 out += extracted ?? text.slice(start, i);
                 continue;
             }
-            if (visited.has(filePath)) {
+            const id = toId(ctx, filePath);
+            if (id === undefined || isCycle(ctx, id)) {
                 out += text.slice(start, i);
                 continue;
             }
-            const content = await readFile(filePath);
+            const content = await ctx.readFile(id);
             if (content === undefined) {
                 out += text.slice(start, i);
                 continue;
@@ -206,9 +246,13 @@ async function expandAsync(text, readFile, sigil, maxDepth, visited, depth, curr
                 }
                 result = extracted;
             }
-            visited.add(filePath);
-            out += await expandAsync(result, readFile, sigil, maxDepth, visited, depth + 1, content);
-            visited.delete(filePath);
+            ctx.stack.push(id);
+            try {
+                out += await expandAsync(result, ctx, depth + 1, content);
+            }
+            finally {
+                ctx.stack.pop();
+            }
             continue;
         }
         out += text[i];

package/dist/index.d.ts

@@ -6,6 +6,6 @@ export { serialize, serializeValue, serializeTable, serializeTypedTable, parseTa
 export type { TableSerializeOptions, TableRecord } from './serialize.js';
 export { parseHeaderCell, emitHeaderCell, coerceTyped, tableSchema, TableParseError } from './typed-header.js';
 export type { TypedColumn, ColumnType, JSONSchema } from './typed-header.js';
-export { resolveIncludes, resolveIncludesAsync, extractSection } from './includes.js';
+export { resolveIncludes, resolveIncludesAsync, extractSection, IncludeCycleError } from './includes.js';
 export type { IncludeOptions } from './includes.js';
 export type { Sigil, ParseOptions, SerializeOptions, Document, Block, Attribute, Pos, AttributeValue, BodyValue, Scalar, ListItem, Json5Object, Json5Value, InterpolatedValue, InterpolationSpan, } from './types.js';

package/dist/index.js

@@ -20,4 +20,4 @@ export { serialize, serializeValue, serializeTable, serializeTypedTable, parseTa
 // ---------- Typed tbl header + tableSchema (serialize-spec §2.3) ----------
 export { parseHeaderCell, emitHeaderCell, coerceTyped, tableSchema, TableParseError } from './typed-header.js';
 // ---------- Includes (format-spec §2.6) ----------
-export { resolveIncludes, resolveIncludesAsync, extractSection } from './includes.js';
+export { resolveIncludes, resolveIncludesAsync, extractSection, IncludeCycleError } from './includes.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notrealstudio/nr-md",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Markdown as structured data: headings become blocks, $key: value lines become attributes. Parser and serializer for the mdd/mdz block grammar.",
   "keywords": [
     "markdown",
@@ -34,7 +34,8 @@
   "scripts": {
     "build": "tsc",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "prepublishOnly": "node -e \"const p=require('./package.json');const bad=Object.entries({...p.dependencies,...p.peerDependencies}).filter(([,v])=>String(v).startsWith('file:'));if(bad.length){console.error('publish blocked: file: deps '+bad.map(([k])=>k).join(', '));process.exit(1)}\""
   },
   "dependencies": {
     "@notrealstudio/nr-json5": "^0.1.1"