mdeval 1.1.0 → 1.3.0

package/README.md

@@ -7,6 +7,8 @@ Ever wanted dynamic values in your Markdown — package versions, star counts, c
 
 mdeval embeds JavaScript directly in your Markdown using HTML comments. The logic lives right next to the content it produces, and the file renders normally everywhere — GitHub, editors, any Markdown viewer — because HTML comments are invisible.
 
+Any value that matters — a dependency count, a version string, a benchmark result — is computed, not typed. Whether written by a person or an AI agent, the expression shows the work and anyone can verify it. Re-run `mdeval` and every value updates.
+
 ## Install
 
 ```bash
@@ -40,7 +42,9 @@ The `1.0.0` between `-->` and `<!--/mdeval-->` is the current value — it gets
 mdeval README.md
 ```
 
-The file is updated in-place. You can pass multiple files at once: `mdeval README.md docs/*.md`
+The file is updated in-place. You can pass multiple files or glob patterns: `mdeval README.md "docs/**/*.md"`.
+
+`node_modules` and hidden directories are automatically excluded from glob expansion.
 
 ## Notes
 
@@ -49,7 +53,11 @@ The file is updated in-place. You can pass multiple files at once: `mdeval READM
 - Markers can be **self-contained** — no script block needed:
 
   ```markdown
-  <!--mdeval (() => 2 + 2)()-->4<!--/mdeval-->
+  <!--mdeval (() => {
+    const n = 3;
+    if (n % 2 === 0) { return 'even' }
+    return 'odd'
+  })()-->odd<!--/mdeval-->
   ```
 
   In large documents, this IIFE pattern lets you keep logic next to the marker it serves instead of in a distant script block.

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-var d=Object.defineProperty;var p=(r,o)=>d(r,"name",{value:o,configurable:!0});import{register as u}from"node:module";import l from"node:fs/promises";import g from"node:path";import{cli as h}from"cleye";import{$ as w}from"zx";import{pathToFileURL as E}from"node:url";import{p as y,b as $,E as b,M as x,C as M,a as S}from"./parse-markdown-ChGEvmW3.mjs";import"md4x";const P=p(r=>{if(r==null)throw new Error(`Cannot interpolate ${r} \u2014 this is likely a bug in your script`);return typeof r=="string"?r:typeof r=="object"?Symbol.toPrimitive in r?String(r):JSON.stringify(r):String(r)},"coerceValue"),R=p(async(r,o)=>{const{markers:t}=y(r);if(t.length===0)return r;const s=await import(E(o).href),m=$(t),f=await Promise.all(Array.from(m).map(async([e,c])=>{const i=P(await s[`${b}${c}`]);if(i.includes(x)||i.includes(`${M}
-`)||i.includes(S))throw new Error(`Expression "${e}" produced a value containing mdeval comment syntax, which would corrupt the document on re-parse`);return i})),n=[];let a=0;for(const e of t){const c=m.get(e.expression);n.push(r.slice(a,e.contentStart),f[c]),a=e.contentEnd}return n.push(r.slice(a)),n.join("")},"processSource");u("#md-loader",import.meta.url),globalThis.block=r=>`
-${String(r)}
-`,globalThis.$=w;const T=h({name:"mdeval",parameters:["<files...>"]});await Promise.all(T._.files.map(async r=>{try{const o=g.resolve(r),t=await l.readFile(o,"utf8"),s=await R(t,o);s!==t&&(await l.writeFile(o,s,"utf8"),console.log(`Updated: ${r}`))}catch(o){console.error(`Error processing ${r}:`,o instanceof Error?o.message:o),process.exitCode=1}}));
+var M=Object.defineProperty;var p=(o,r)=>M(o,"name",{value:r,configurable:!0});import m from"node:fs/promises";import $ from"node:path";import{cli as b}from"cleye";import{glob as x}from"tinyglobby";import{$ as S}from"zx";import{p as d,b as O,E as _,M as f,C as k,a as g,c as C,i as P}from"./parse-markdown-BBzZcXPS.mjs";import{register as R}from"node:module";import{pathToFileURL as T}from"node:url";import"md4x";const N=p(o=>{if(o==null)throw new Error(`Cannot interpolate ${o} \u2014 this is likely a bug in your script`);return typeof o=="string"?o:typeof o=="object"?Symbol.toPrimitive in o?String(o):JSON.stringify(o):String(o)},"coerceValue");R("#md-loader",import.meta.url);const v=p(async(o,r)=>{const{markers:t}=d(o);if(t.length===0)return o;const i=await import(T(r).href),n=O(t),w=await Promise.all(Array.from(n).map(async([e,l])=>{const s=N(await i[`${_}${l}`]);if(s.includes(f)||s.includes(`${k}
+`)||s.includes(g))throw new Error(`Expression "${e}" produced a value containing mdeval comment syntax, which would corrupt the document on re-parse`);return s})),a=[];let c=0;for(const e of t){const l=f.length+e.expression.length+C.length,s=e.start+l,E=e.end-g.length,y=n.get(e.expression);a.push(o.slice(c,s),w[y]),c=E}return a.push(o.slice(c)),a.join("")},"processSource");globalThis.block=o=>`
+${String(o)}
+`,globalThis.$=S;const A=b({name:"mdeval",parameters:["<files...>"]}),u=A._.files,F=u.some(o=>o.includes("node_modules")),h=await x(u,{ignore:F?[]:["**/node_modules/**"]});h.length===0&&(console.error("No files matched the given patterns"),process.exit(1)),await Promise.all(h.map(async o=>{try{const r=$.resolve(o),t=await m.readFile(r,"utf8"),i=d(t);P(t,i)&&console.warn(`Warning: ${o} has no markdown content outside of mdeval blocks`);const n=await v(t,r);n!==t&&(await m.writeFile(r,n,"utf8"),console.log(`Updated: ${o}`))}catch(r){console.error(`Error processing ${o}:`,r instanceof Error?r.message:r),process.exitCode=1}}));

package/dist/md-loader.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-var p=Object.defineProperty;var i=(r,o)=>p(r,"name",{value:o,configurable:!0});import c from"node:fs/promises";import{fileURLToPath as m}from"node:url";import{p as f,b as u,E as d}from"./parse-markdown-ChGEvmW3.mjs";import"md4x";const l=i((r,o)=>{const t=r.join(`
-`),s=u(o);if(s.size===0)return t;const e=[...s].map(([n,a])=>`export const ${d}${a} = ${n};`);return`${t}
-${e.join(`
-`)}`},"generateModule"),$=i(async(r,o,t)=>{if(!r.endsWith(".md"))return t(r,o);const s=await c.readFile(m(r),"utf8"),{scriptBlocks:e,markers:n}=f(s);return e.length===0&&n.length===0?t(r,o):{format:"module",source:l(e,n),shortCircuit:!0}},"load");export{$ as load};
+var p=Object.defineProperty;var i=(r,o)=>p(r,"name",{value:o,configurable:!0});import c from"node:fs/promises";import{fileURLToPath as m}from"node:url";import{p as f,b as u,E as d}from"./parse-markdown-BBzZcXPS.mjs";import"md4x";const l=i((r,o)=>{const e=r.map(t=>t.content).join(`
+`),s=u(o);if(s.size===0)return e;const n=[...s].map(([t,a])=>`export const ${d}${a} = ${t};`);return`${e}
+${n.join(`
+`)}`},"generateModule"),$=i(async(r,o,e)=>{if(!r.endsWith(".md"))return e(r,o);const s=await c.readFile(m(r),"utf8"),{scriptBlocks:n,markers:t}=f(s);return n.length===0&&t.length===0?e(r,o):{format:"module",source:l(n,t),shortCircuit:!0}},"load");export{$ as load};

package/dist/parse-markdown-BBzZcXPS.mjs

@@ -0,0 +1,3 @@
+var _=Object.defineProperty;var d=(n,t)=>_(n,"name",{value:t,configurable:!0});import{parseAST as R}from"md4x";const E="mdeval",O=`<!--${E}`,u=`${O} `,M=`<!--/${E}-->`,y=`__${E}_`,m="-->",k=`${E}
+`,C=d(n=>{const t=new Map;for(const{expression:r}of n)t.has(r)||t.set(r,t.size);return t},"buildExpressionMap"),P=d((n,t)=>{const r=[],f=[];let l=0;const e=d(s=>{if(!Array.isArray(s))return;const[h,,...a]=s;if(h==="code"){const i=a[0];if(typeof i=="string"&&i.length>0){const c=t.indexOf(i,l);if(c!==-1){f.push([c,c+i.length]),l=c+i.length;return}const o=i.split(`
+`).filter(g=>g.length>0);if(o.length>0){const g=t.indexOf(o[0],l);if(g!==-1){let p=g+o[0].length;for(let x=1;x<o.length;x+=1){const A=t.indexOf(o[x],p);A!==-1&&(p=A+o[x].length)}f.push([g,p]),l=p}}}return}if(h===null&&typeof a[0]=="string"){const i=a[0],c=`<!--${i}-->`,o=t.indexOf(c,l);i.startsWith(k)&&o!==-1&&r.push({content:i.slice(k.length),start:o,end:o+c.length}),o!==-1&&(l=o+c.length);return}for(const i of a)Array.isArray(i)&&e(i)},"walk");for(const s of n.nodes)e(s);return{scriptBlocks:r,codeRanges:f}},"walkAst"),S=d((n,t)=>{let r=0;const f=d(s=>{for(;r<t.length&&t[r][1]<=s;)r+=1;if(r>=t.length)return!1;const[h,a]=t[r];return s>=h&&s<a},"isInCode"),l=[];let e=0;for(;e<n.length;){const s=n.indexOf(u,e);if(s===-1)break;const h=s+u.length,a=n.indexOf(m,h);if(a===-1)break;const i=a+m.length,c=n.indexOf(M,i);if(c===-1){e=i;continue}const o=c+M.length;f(s)||l.push({expression:n.slice(h,a),start:s,end:o}),e=o}return l},"findMarkers"),w=d(n=>{if(!n.includes(O))return{scriptBlocks:[],markers:[]};const t=R(n),{scriptBlocks:r,codeRanges:f}=P(t,n);return{scriptBlocks:r,markers:S(n,f)}},"parseMarkdown"),I=d((n,{scriptBlocks:t,markers:r})=>{if(t.length===0&&r.length===0)return!1;const f=[...t.map(e=>[e.start,e.end]),...r.map(e=>[e.start,e.end])].sort((e,s)=>e[0]-s[0]);let l=0;for(const[e,s]of f){if(n.slice(l,e).trim()!=="")return!1;l=s}return n.slice(l).trim()===""},"isOnlyMdeval");export{O as C,y as E,u as M,M as a,C as b,m as c,I as i,w as p};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdeval",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Evaluate JavaScript in markdown HTML comments and interpolate results in-place",
   "keywords": [
     "markdown",
@@ -30,6 +30,7 @@
   "dependencies": {
     "cleye": "^2.3.0",
     "md4x": "^0.0.25",
+    "tinyglobby": "^0.2.15",
     "zx": "8.8.5-lite"
   }
 }

package/skills/mdeval/SKILL.md

@@ -5,6 +5,13 @@ description: Evaluates JavaScript in markdown HTML comments and interpolates res
 
 # mdeval
 
+## When to use
+
+- Markdown contains values derived from code, files, APIs, or shell commands
+- README stats, version numbers, dependency counts, or computed tables
+- Any value where accuracy matters — counts, sizes, dates, calculations
+- Auditable content — the expression proves the value is correct, not just asserted
+
 ## Syntax
 
 Two types of HTML comments — invisible when rendered:
@@ -14,7 +21,7 @@ Two types of HTML comments — invisible when rendered:
 | Script block | `<!--mdeval\n...\n-->` | Define variables, imports, logic. Starts with `<!--mdeval` + newline |
 | Value marker | `<!--mdeval EXPR-->value<!--/mdeval-->` | Interpolate expression result. Starts with `<!--mdeval ` + space |
 
-Script blocks run as ESM with full Node.js access and top-level `await`. All blocks in a file merge into one module — imports and variables are shared across blocks and markers. `import.meta` points to the markdown file.
+Script blocks run as ESM with full Node.js access and top-level `await`. All blocks in a file merge into one module — imports and variables are shared across blocks and markers. `import.meta` points to the markdown file. Marker expressions are auto-awaited, so promises resolve automatically.
 
 ## Marker Expressions
 
@@ -36,10 +43,38 @@ Duplicate expressions across markers are evaluated once and reused.
 | `string` | As-is |
 | `number`, `boolean`, `bigint` | `String(value)` |
 | `object`, `array` | `JSON.stringify(value)` |
+| object with `Symbol.toPrimitive` | `String(value)` (e.g. zx `ProcessOutput`) |
+| `Promise` | Auto-awaited, then coerced |
 | `undefined`, `null` | Error |
 
+## Globals
+
+| Global | Description |
+|--------|-------------|
+| `block(value)` | Wraps value with newlines for block-level rendering |
+| `$` | [zx](https://google.github.io/zx/) shell — run commands via tagged templates: `` $`git branch` `` |
+
+## CLI
+
+```bash
+mdeval README.md                    # single file
+mdeval README.md docs/guide.md      # multiple files
+mdeval "docs/**/*.md"               # glob pattern
+mdeval "**/*.md"                    # recursive — node_modules and dotdirs auto-excluded
+```
+
+Supports full glob syntax including `**` recursive, `{a,b}` brace expansion, and `!` negation.
+
+`node_modules` and hidden directories (`.git`, `.next`, etc.) are automatically excluded from glob expansion. No need to manually negate them. To explicitly include `node_modules`, reference it in the pattern: `mdeval "node_modules/pkg/*.md"`.
+
 ## Patterns
 
+### Shell commands
+
+````markdown
+<!--mdeval $`git branch --show-current`-->main<!--/mdeval-->
+````
+
 ### Read package.json
 
 ````markdown
@@ -116,3 +151,5 @@ const x = String.fromCharCode(45, 45, 62);
 **Use IIFEs to co-locate logic.** In large docs, keep marker-specific computation inline instead of in a distant script block: `<!--mdeval (() => { ... })()-->`.
 
 **Markers in code blocks are safe.** Fenced, indented, and inline code won't be touched — safe to document mdeval syntax in your own README.
+
+**Never create a .md file with only a script block and no real content.** Markdown files must contain actual prose/documentation. For shared logic or utilities, create a `.js` or `.ts` file and import it from your markdown instead.

package/dist/parse-markdown-ChGEvmW3.mjs

@@ -1,3 +0,0 @@
-var _=Object.defineProperty;var d=(s,t)=>_(s,"name",{value:t,configurable:!0});import{parseAST as R}from"md4x";const x="mdeval",k=`<!--${x}`,O=`${k} `,M=`<!--/${x}-->`,C=`__${x}_`,A="-->",m=`${x}
-`,P=d(s=>{const t=new Map;for(const{expression:e}of s)t.has(e)||t.set(e,t.size);return t},"buildExpressionMap"),S=d((s,t)=>{const e=[],a=[];let l=0;const f=d(r=>{if(!Array.isArray(r))return;const[h,,...c]=r;if(h==="code"){const n=c[0];if(typeof n=="string"&&n.length>0){const o=t.indexOf(n,l);if(o!==-1){a.push([o,o+n.length]),l=o+n.length;return}const i=n.split(`
-`).filter(p=>p.length>0);if(i.length>0){const p=t.indexOf(i[0],l);if(p!==-1){let g=p+i[0].length;for(let E=1;E<i.length;E+=1){const u=t.indexOf(i[E],g);u!==-1&&(g=u+i[E].length)}a.push([p,g]),l=g}}}return}if(h===null&&typeof c[0]=="string"){const n=c[0];n.startsWith(m)&&e.push(n.slice(m.length));const o=`<!--${n}-->`,i=t.indexOf(o,l);i!==-1&&(l=i+o.length);return}for(const n of c)Array.isArray(n)&&f(n)},"walk");for(const r of s.nodes)f(r);return{scriptBlocks:e,codeRanges:a}},"walkAst"),w=d((s,t)=>{let e=0;const a=d(r=>{for(;e<t.length&&t[e][1]<=r;)e+=1;if(e>=t.length)return!1;const[h,c]=t[e];return r>=h&&r<c},"isInCode"),l=[];let f=0;for(;f<s.length;){const r=s.indexOf(O,f);if(r===-1)break;const h=r+O.length,c=s.indexOf(A,h);if(c===-1)break;const n=c+A.length,o=s.indexOf(M,n);if(o===-1){f=n;continue}const i=o+M.length;a(r)||l.push({expression:s.slice(h,c),contentStart:n,contentEnd:o}),f=i}return l},"findMarkers"),y=d(s=>{if(!s.includes(k))return{scriptBlocks:[],markers:[]};const t=R(s),{scriptBlocks:e,codeRanges:a}=S(t,s);return{scriptBlocks:e,markers:w(s,a)}},"parseMarkdown");export{k as C,C as E,O as M,M as a,P as b,y as p};