mdeval 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Hiroki Osame <hiroki.osame@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+<p align="center">
+	<img width="160" src=".github/logo.webp">
+</p>
+<h1 align="center">mdeval</h1>
+
+Ever wanted dynamic values in your Markdown — package versions, star counts, computed tables — without a separate generation script that's easy to forget about?
+
+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.
+
+## Install
+
+```bash
+npm i mdeval
+```
+
+## Quick start
+
+mdeval adds two types of HTML comments to your Markdown:
+
+A **script block** is where you write JavaScript. It starts with `<!--mdeval` followed by a newline:
+
+```markdown
+<!--mdeval
+import fs from 'node:fs/promises';
+const pkg = JSON.parse(await fs.readFile('package.json', 'utf8'));
+-->
+```
+
+Full Node.js, ESM imports, and top-level `await` are supported.
+
+A **value marker** is where the result appears. It starts with `<!--mdeval ` (with a space) followed by a JavaScript expression:
+
+```markdown
+Version: <!--mdeval pkg.version-->1.0.0<!--/mdeval-->
+```
+
+The `1.0.0` between `-->` and `<!--/mdeval-->` is the current value — it gets overwritten with the result of `pkg.version` every time you run mdeval:
+
+```bash
+mdeval README.md
+```
+
+The file is updated in-place. You can pass multiple files at once: `mdeval README.md docs/*.md`
+
+## Notes
+
+- A file can have **multiple script blocks** — they're merged into one module, so variables and imports are shared. We recommend placing them at the top to signal the file has generated content.
+
+- Markers can be **self-contained** — no script block needed:
+
+  ```markdown
+  <!--mdeval (() => 2 + 2)()-->4<!--/mdeval-->
+  ```
+
+  In large documents, this IIFE pattern lets you keep logic next to the marker it serves instead of in a distant script block.
+
+- If your value starts with a heading, list, or other block element, wrap it with **`block()`** so it renders on its own line. `block()` is a global helper that adds newlines before and after the value.
+
+- You can **import from other `.md` files**. Only the script blocks are executed — no markers are processed:
+
+  ```markdown
+  <!--mdeval
+  import { version } from './data.md';
+  -->
+  ```
+
+  This lets you share constants and logic across multiple markdown files.
+
+- When processing multiple files (`mdeval a.md b.md`), all files **share the same Node.js runtime** — including the module cache, `globalThis`, and `process.env`. This is the same behavior as any Node.js program using `import()`.
+
+## Caveats
+
+- Script code **cannot contain `-->`** — it closes the HTML comment. Rewrite `x-- > y` as `x -= 1; x > y`.
+- Scripts are **JavaScript only** — no TypeScript.
+- Values **cannot contain `<!--mdeval `** or **`<!--/mdeval-->`** — mdeval will throw to prevent document corruption.
+
+## Tip: md-pen
+
+[md-pen](https://github.com/privatenumber/md-pen) provides typed utilities for generating tables, lists, and other Markdown structures — useful when markers need to produce formatted output:
+
+```markdown
+<!--mdeval
+import { table, bold, link } from 'md-pen';
+const deps = [['cleye', '^2.3.0'], ['md-pen', '^0.0.2']];
+const depsTable = table(deps.map(([name, v]) => [
+  link(`https://npm.im/${name}`, bold(name)), v
+]));
+-->
+
+<!--mdeval block(depsTable)-->
+| Package | Version |
+| - | - |
+| [__cleye__](https://npm.im/cleye) | ^2.3.0 |
+| [__md-pen__](https://npm.im/md-pen) | ^0.0.2 |
+<!--/mdeval-->
+```
+
+## Agent Skills
+
+This package ships with a built-in [agent skill](./skills/mdeval/SKILL.md) for AI coding assistants. Set up [`skills-npm`](https://github.com/antfu/skills-npm) to automatically discover it.

package/dist/cli.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+var h=Object.defineProperty;var a=(r,o)=>h(r,"name",{value:o,configurable:!0});import{register as g}from"node:module";import u from"node:fs/promises";import w from"node:path";import{cli as E}from"cleye";import{pathToFileURL as y}from"node:url";import{p as M,b as $,E as R,M as b,C,a as S}from"./parse-markdown-ChGEvmW3.mjs";import"md4x";const k=a(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"?JSON.stringify(r):String(r)},"coerceValue"),v=a(async(r,o)=>{const{markers:e}=M(r);if(e.length===0)return r;const n=await import(y(o).href),f=$(e),m=new Map,d=a((t,l)=>{const i=m.get(t);if(i!==void 0)return i;const s=k(n[`${R}${t}`]);if(s.includes(b)||s.includes(`${C}
+`)||s.includes(S))throw new Error(`Expression "${l}" produced a value containing mdeval comment syntax, which would corrupt the document on re-parse`);return m.set(t,s),s},"resolveValue"),c=[];let p=0;for(const t of e){const l=f.get(t.expression),i=d(l,t.expression);c.push(r.slice(p,t.contentStart),i),p=t.contentEnd}return c.push(r.slice(p)),c.join("")},"processSource");g("#md-loader",import.meta.url),globalThis.block=r=>`
+${String(r)}
+`;const x=E({name:"mdeval",parameters:["<files...>"]});await Promise.all(x._.files.map(async r=>{try{const o=w.resolve(r),e=await u.readFile(o,"utf8"),n=await v(e,o);n!==e&&(await u.writeFile(o,n,"utf8"),console.log(`Updated: ${r}`))}catch(o){console.error(`Error processing ${r}:`,o instanceof Error?o.message:o),process.exitCode=1}}));

package/dist/md-loader.mjs

@@ -0,0 +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};

package/dist/parse-markdown-ChGEvmW3.mjs

@@ -0,0 +1,3 @@
+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};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "mdeval",
+  "version": "1.0.0",
+  "description": "Evaluate JavaScript in markdown HTML comments and interpolate results in-place",
+  "keywords": [
+    "markdown",
+    "eval",
+    "interpolation",
+    "dynamic",
+    "readme"
+  ],
+  "license": "MIT",
+  "repository": "privatenumber/mdeval",
+  "author": {
+    "name": "Hiroki Osame",
+    "email": "hiroki.osame@gmail.com"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "type": "module",
+  "bin": "./dist/cli.mjs",
+  "imports": {
+    "#md-loader": "./dist/md-loader.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "cleye": "^2.3.0",
+    "md4x": "^0.0.25"
+  }
+}

package/skills/mdeval/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: mdeval
+description: Evaluates JavaScript in markdown HTML comments and interpolates results in-place. Use when editing markdown files that contain mdeval script blocks or value markers, when the user wants computed/dynamic values in markdown, or when maintaining README badges, version numbers, or stats.
+---
+
+# mdeval
+
+## Syntax
+
+Two types of HTML comments — invisible when rendered:
+
+| Type | Syntax | Purpose |
+|------|--------|---------|
+| 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.
+
+## Marker Expressions
+
+Any JavaScript expression valid on the right side of `const x =`:
+
+| Expression | Example |
+|------------|---------|
+| Variable | `<!--mdeval name-->value<!--/mdeval-->` |
+| Property access | `<!--mdeval data.version-->value<!--/mdeval-->` |
+| Computation | `<!--mdeval items.length + " items"-->value<!--/mdeval-->` |
+| IIFE | `<!--mdeval (() => { const x = 1 + 1; return x; })()-->value<!--/mdeval-->` |
+
+Duplicate expressions across markers are evaluated once and reused.
+
+## Value Coercion
+
+| Type | Result |
+|------|--------|
+| `string` | As-is |
+| `number`, `boolean`, `bigint` | `String(value)` |
+| `object`, `array` | `JSON.stringify(value)` |
+| `undefined`, `null` | Error |
+
+## Patterns
+
+### Read package.json
+
+````markdown
+<!--mdeval
+import fs from 'node:fs/promises';
+const pkg = JSON.parse(await fs.readFile('package.json', 'utf8'));
+-->
+
+Version: <!--mdeval pkg.version-->0.0.0<!--/mdeval-->
+````
+
+### Import from other .md files
+
+Only script blocks are executed — markers are not processed:
+
+````markdown
+<!--mdeval
+import { version } from './data.md';
+-->
+
+<!--mdeval version-->1.0.0<!--/mdeval-->
+````
+
+### Generate Markdown with md-pen
+
+Use [md-pen](https://github.com/privatenumber/md-pen) for formatted output (tables, lists, headings):
+
+````markdown
+<!--mdeval
+import { table, bold, link } from 'md-pen';
+const deps = [['cleye', '^2.3.0'], ['md-pen', '^0.0.2']];
+const depsTable = table(deps.map(([name, v]) => [link(`https://npm.im/${name}`, bold(name)), v]));
+-->
+
+<!--mdeval block(depsTable)-->
+| Package | Version |
+| - | - |
+| [__cleye__](https://npm.im/cleye) | ^2.3.0 |
+<!--/mdeval-->
+````
+
+## Gotchas
+
+**Block-level values need `block()`.** Without it, block elements don't render:
+
+````markdown
+<!-- ❌ Heading stays on same line as comment, won't render -->
+<!--mdeval heading-->### Title<!--/mdeval-->
+
+<!-- ✅ block() adds newlines so the heading renders correctly -->
+<!--mdeval block(heading)-->
+### Title
+<!--/mdeval-->
+````
+
+**Script code cannot contain `-->`** — it closes the HTML comment:
+
+````markdown
+<!-- ❌ --> in the string literal closes the comment prematurely -->
+<!--mdeval
+const x = "<!--/mdeval-->";
+-->
+
+<!-- ✅ Build the string without --> -->
+<!--mdeval
+const x = String.fromCharCode(45, 45, 62);
+-->
+````
+
+**Values cannot contain mdeval syntax.** Producing `<!--mdeval ` or `<!--/mdeval-->` in a value throws an error to prevent document corruption on re-parse.
+
+**Place scripts at the top.** Order doesn't affect execution — scripts can appear after the markers that reference them — but top placement signals the file contains generated content.
+
+**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.