figdown 0.4.1 → 0.5.0

package/integrations/mcp-server/server.js

@@ -149,6 +149,36 @@ function parseFailed(label, errors) {
   );
 }
 
+// GEOMETRY-TIME REFUSAL (spec core §8, §8.4). A document whose source is
+// impeccable line by line can still describe a drawing that states something
+// it does not — a `group` band enclosing a non-member, a `pin` covering a node
+// completely. Those come from `render`, not from `parse`, and core §8 makes
+// them cost exactly what a parse error costs: nothing is drawn and no artifact
+// is written. Reporting them under the PARSE FAILED banner would send the
+// author to look for a typo on a line that has none, so they get their own
+// heading and their own remedy sentence.
+function figureRefused(label, errors) {
+  return text(
+    'FIGURE REFUSED — ' + errors.length + ' geometry-time diagnostic(s)' + (label ? ' in ' + label : '') + '.\n' +
+    'The source parses clean; the DRAWING would state something the source does not,\n' +
+    'so nothing was rendered and no artifact was written (spec core §8). Each line names\n' +
+    'the line you can act on — usually the `pin` that fixed the position.',
+    errors.join('\n')
+  );
+}
+
+// WHICH CHANNEL REFUSED. `render()` reports parse errors when there are any and
+// geometry-time diagnostics ONLY when there are none — the two are mutually
+// exclusive by construction, because nothing is rendered for a document that
+// does not parse. So asking the parser is enough to name the channel, and it
+// is asked directly rather than inferred from the message text: a banner keyed
+// on wording would go wrong the first time a message is reworded.
+function refused(label, src, errors) {
+  return figdown.parse(src).errors.length
+    ? parseFailed(label, errors)
+    : figureRefused(label, errors);
+}
+
 // `source` or `path`, never both, never neither. Returns {src, label, file} or
 // throws a message string.
 function takeSource(args, exts) {
@@ -172,8 +202,12 @@ function toolBuild(args) {
   try { s = takeSource(args, ['.fd']); } catch (m) { return toolError(m); }
 
   const opts = args.with_title === true ? { title: true } : undefined;
+  // `artifact` refuses on EITHER channel (dist 0.4): a parse error, or
+  // a geometry-time diagnostic that only `render` can see. Both give svg=null
+  // and a non-empty `errors`, so nothing below can write a picture the engine
+  // has already said is wrong.
   const { svg, errors } = figdown.artifact(s.src, opts);
-  if (errors.length) return parseFailed(s.label, errors);
+  if (errors.length) return refused(s.label, s.src, errors);
 
   const wrote = args.write === true && s.file
     ? s.file.replace(/\.fd$/, '') + '.svg'
@@ -247,9 +281,13 @@ function toolCheck(args) {
 
   if (!units.length) return text('ok: true  0 .fd file(s) found under ' + args.path + ' — nothing to check.');
 
+  // BOTH CHANNELS, because a checker that clears a document `figdown_build`
+  // then refuses is a checker that lies. `render` reports parse errors when
+  // there are any and geometry-time diagnostics (core §8) otherwise, which is
+  // exactly the set that decides whether an artifact can be written.
   const bad = [];
   for (const u of units) {
-    const errs = figdown.parse(u.src).errors;
+    const errs = figdown.render(u.src).errors;
     if (errs.length) bad.push(u.label + ':\n' + errs.map(e => '  ' + e).join('\n'));
   }
 
@@ -291,9 +329,17 @@ function toolRead(args) {
     }
     const sidecar = s.file ? s.file.replace(/\.svg$/, '.fd') : null;
     if (sidecar && fs.existsSync(sidecar) && recordedSha) {
-      const live = figdown.artifact(fs.readFileSync(sidecar, 'utf8')).svg;
+      const rebuilt = figdown.artifact(fs.readFileSync(sidecar, 'utf8'));
+      const live = rebuilt.svg;
       const liveSha = live && (live.match(/data-sha256="([0-9a-f]{64})"/) || [])[1];
-      notes.push(liveSha === recordedSha
+      // A sidecar the engine now REFUSES cannot be compared, and calling that
+      // "stale" would name the wrong defect: the .fd did not drift, it stopped
+      // being drawable. Say which it is.
+      notes.push(rebuilt.errors.length
+        ? 'SIDECAR REFUSED: ' + path.basename(sidecar) + ' no longer builds — '
+          + rebuilt.errors.length + ' diagnostic(s), so the recorded hash could not be checked:\n  '
+          + rebuilt.errors.join('\n  ')
+        : liveSha === recordedSha
         ? 'sidecar ' + path.basename(sidecar) + ' matches the artifact\'s recorded hash'
         : 'STALE ARTIFACT: ' + path.basename(sidecar) + ' has changed since this .svg was built. '
           + 'The .fd is truth — rebuild.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figdown",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "A missing edge still looks fine. Text doesn't. A closed, deterministic figure language for Markdown whose source states the meaning, so the next reader can check the figure instead of only looking at it.",
   "license": "MIT",
   "author": "FigDown <hello@figdown.org>",
@@ -32,7 +32,7 @@
     "gate:page": "node tools/page-check.js",
     "gate:shape": "node tools/shape-check.js --strict",
     "gate:strip": "node tools/strip-check.js --strict",
-    "gate:layout": "node tools/layout-lint.js --strict",
+    "gate:layout": "node tools/layout-lint.js --strict examples figures tools/layout-lint-fixtures/b66-typed-title",
     "gate:namespace": "node tools/namespace-check.js --strict",
     "gate:artifact": "node tools/artifact-check.js --strict",
     "gate:dist": "node tools/dist-check.js --strict",
@@ -48,6 +48,8 @@
     "gate:standards": "node tools/standards-check.js --strict",
     "gate:plugin": "node tools/plugin-check.js --strict",
     "gate:mcp": "node integrations/mcp-server/test.js",
+    "gate:proof": "node tools/make-proof.js --check",
+    "gate:safesvg": "node tools/safe-svg-check.js --strict",
     "gates:list": "node -e \"const s=require(process.cwd()+'/package.json').scripts||{};const g=Object.keys(s).filter(k=>k.startsWith('gate:'));if(!g.length){console.error('gates:list — no gate:* scripts found');process.exit(2);}if(process.env.GATES_JSON)console.log(JSON.stringify(g));else g.forEach(k=>console.log(k+'  ->  '+s[k]));\"",
     "test": "node -e \"const s=require(process.cwd()+'/package.json').scripts||{};const sp=require('child_process').spawnSync;const g=Object.keys(s).filter(k=>k.startsWith('gate:'));if(!g.length){console.error('npm test — no gate:* scripts found; refusing to report success');process.exit(2);}const bad=[];g.forEach(k=>{const a=s[k].split(' ');const bin=a[0]==='node'?process.execPath:a[0];console.log('');console.log('=== GATE '+k+'  ['+s[k]+'] ===');const r=sp(bin,a.slice(1),{stdio:'inherit'});if(r.error)console.error('    spawn error: '+r.error.message);const c=(r.status===null||r.status===undefined)?1:r.status;console.log('--- '+k+': '+(c===0?'PASS':'FAIL (exit '+c+')')+' ---');if(c!==0)bad.push(k+'  ['+s[k]+']  exit '+c);});console.log('');console.log('=== GATE SUMMARY: '+(g.length-bad.length)+'/'+g.length+' passed ===');if(bad.length){console.log('FAILED GATES:');bad.forEach(b=>console.log('  '+b));process.exit(1);}console.log('ALL GATES GREEN');\"",
     "gate:reference": "node tools/reference-gate.js"

package/skill/README.md

@@ -0,0 +1,130 @@
+# FigDown agent skill
+
+An installable skill that teaches an AI coding agent (Claude Code and
+compatible agent frameworks) to maintain documentation figures with
+FigDown: edit `.fd` sources, build deterministic `.svg` artifacts, and
+embed them in Markdown with the `source:` footer convention.
+
+The bundle is self-contained: `SKILL.md`, a `reference/` directory,
+`build-svg.js` (validator/renderer CLI) and `figdown.html` (the engine
+it extracts at runtime — also the editor: open it in any browser).
+
+**It is built for progressive disclosure.** `SKILL.md` is the only file
+always loaded, and it holds the workflow, the genre-independent
+language, and a **router**. Everything else is pulled on demand, and
+the routing rule is mechanical: line 1 of a `.fd` names its genre, so
+the agent knows which file it needs before it needs it.
+
+```
+SKILL.md                                 always loaded
+reference/scene.md                       genre `block` — its OWN vocabulary
+reference/bitfield.md
+reference/table.md
+reference/layout.md                      arranging a scene
+reference/reading.md                     reading a .fd for meaning
+reference/transcribe.md                  transcribing an existing figure
+reference/experimental/block.md          block's EXPERIMENTAL markers and zones
+reference/experimental/chart.md          a chart from a table (any genre
+                                         that can host one)
+reference/experimental/topology.md       the five EXPERIMENTAL genres, each
+reference/experimental/flowchart.md      declaring its OWN vocabulary in
+reference/experimental/statechart.md     its own file, so an agent can
+reference/experimental/timing.md         ignore the ones it is not using
+reference/experimental/sequence.md       — the ladder genre, and the one
+                                         whose load set has no layout file
+```
+
+`sequence` is the exception to the "genre file + layout file" pairing above:
+both of its axes are declaration order, so nothing in the layout namespace
+moves a mark there and its own file is the whole of what an author needs.
+
+**Every scene genre's file is self-sufficient (`SUBJECT-VOCABULARY-SCOPE`).** There is
+no shared scene-vocabulary file and there was never meant to be one: only
+`figdown`, `title` and `layout` are cross-genre by definition, and a word two
+genres spell the same is two independent declarations that happen to agree
+today. So an agent authoring a `topology` figure loads `topology.md` and does
+not have to follow a link into `block`'s file to find out what `bundle` means
+— which is what it used to have to do, and what it found there was written for
+a different domain. The file this list used to call
+`reference/experimental/constructs.md` was that shared file; it was removed
+with the ruling, and its contents went to the genres that own them.
+
+The `reference/` files are a generated copy of [`read/0.5/`](../read/0.5/reading.md),
+which is the source of truth; see "Keeping the bundle fresh" below. If you only
+want to READ a `.fd` from this repository, go to `read/0.5/` and install
+nothing.
+
+An agent *reading* a figure loads `SKILL.md` + `reference/reading.md`
+and nothing else; an agent authoring a `bitfield` never pays for any
+scene genre's vocabulary. `node tools/skill-coverage.js --strict` is the gate:
+it checks that every registered keyword, option key and enum value is
+taught in its genre's load set, that no retired spelling is taught, and
+that the always-loaded file stays genre-independent.
+
+## Install
+
+Two paths, one bundle. The plugin is a **wrapper**, not a second copy:
+`.claude-plugin/plugin.json` at the repository root declares
+`"skills": "./skill/"`, so the plugin ships exactly the directory documented
+here. Nothing below is duplicated anywhere.
+
+**Claude Code plugin (recommended — installs and updates itself):**
+
+```sh
+/plugin marketplace add FigDown/figdown
+/plugin install figdown@figdown
+```
+
+`/plugin marketplace update figdown` refreshes the catalogue; the plugin is
+pinned to the `version` in its manifest, so a new release arrives when that
+number changes. No submission and no review are involved: the marketplace is
+[`.claude-plugin/marketplace.json`](../.claude-plugin/marketplace.json) in this
+repository.
+
+**Copy the directory (no plugin mechanism, every project):**
+
+```sh
+cp -r skill/figdown ~/.claude/skills/figdown
+```
+
+**Copy the directory (no plugin mechanism, one project only):**
+
+```sh
+cp -r skill/figdown <your-repo>/.claude/skills/figdown
+```
+
+The copy paths remain fully supported: the bundle is self-contained, so a
+`cp` of `skill/figdown` into any skills directory works with no network, no
+repository and no manifest.
+
+Then ask the agent for a figure ("draw the ingress datapath as a
+figure in docs/arch.md") — the skill triggers on diagram/figure work
+and follows the FigDown workflow automatically. Requires Node.js for
+the build step; no other dependencies, no network.
+
+**Other agent frameworks:** nothing here is Claude-specific except the
+directory convention. `SKILL.md` and `reference/` are ordinary Markdown —
+point the agent at `skill/figdown/SKILL.md` and it follows the same router.
+[guide/agents.md](../guide/agents.md) is the orientation page that leads here;
+it teaches no syntax, because this bundle owns that.
+
+## Keeping the bundle fresh
+
+`figdown/figdown.html`, `figdown/build-svg.js` and everything under
+`figdown/reference/` are **build artifacts** regenerated from their single
+sources (`editor/figdown.html`, `tools/build-svg.js`, and — since `GENRE-REFERENCE-ADDRESS` —
+[`read/0.5/`](../read/0.5/reading.md)) — never edited by hand:
+
+```sh
+node tools/make-skill.js
+```
+
+`SKILL.md` is the one hand-maintained source left in the bundle;
+`make-skill.js` does not own it and does not delete it.
+
+**Why `reference/` is vendored rather than linked.** `read/0.5/` is where a
+reader of this repository is sent — nothing to install. This directory is
+copied out of the repository into `~/.claude/skills/`, so a path pointing back
+at `read/0.5/` would dangle the moment it is installed. The copy is therefore
+generated, and `node tools/skill-coverage.js --strict` fails on any byte of
+difference (check 0, VENDOR). Edit `read/0.5/`, then re-run `make-skill.js`.

package/skill/figdown/SKILL.md

@@ -52,6 +52,26 @@ Recover from there. On hash mismatch the `.fd` is truth: rebuild. If the hash
 matches but your drawing differs, compare `data-engine-version` — that is the
 other half of "same source → same SVG".
 
+## Repair loop, truthfulness and delivery order
+
+**Bounded repair loop.** After step 2 fails, keep fixing and rerunning only
+while each attempt's error count is a new minimum — strictly lower than
+every attempt before it. Two consecutive rounds with no improvement mean
+another identical round will not help either: stop, and report the
+remaining errors truthfully instead of trying a third time.
+
+**Truthfulness.** A run that still reports errors is never described as a
+success, in any wording. Never delete or weaken meaningful declared content
+— a node, an edge, a field, a row, a signal, whatever the genre calls it —
+merely to make the error count reach zero; removing what the figure states
+is not a repair, it is a smaller, different figure wearing the same
+filename. Once a run passes cleanly, the document is frozen: no further
+edits chasing "one more improvement."
+
+**Artifact first.** Write the file, or the fenced block, before explaining
+it. Commentary, reasoning and a description of what changed come after the
+artifact exists — never before it, and never interleaved with it.
+
 ## When the figure comes from a source
 
 Drawing is step 5 of 6. The steps before it decide what is true; the step after