figdown 0.1.0-rc.1 → 0.1.0

package/skill/figdown/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: figdown
+description: Create and maintain documentation figures as FigDown .fd text files with deterministic SVG artifacts embedded in Markdown. Use when asked to create, edit, fix, or read diagrams/figures in docs — block and architecture diagrams, topologies, flowcharts, bit-level layouts (packet headers, hardware registers), tables, timing waveforms — or when a .md contains an SVG with a "source: *.fd" footer.
+---
+
+# FigDown — figures as text, one source, two readers
+
+A figure lives as a `.fd` text file (single source of truth). The SVG is a
+deterministic build artifact for human eyes; **you read the `.fd` for meaning —
+never OCR the SVG**. Structure (nodes, edges, fields, rows) is the content;
+placement and colour are presentation whose only job is rendering stability.
+
+**Choose the form that communicates best.** Three modes: (1) prose, list or
+table alone for linear facts, values or procedures — do not draw; (2) a figure
+alone when it is self-contained; (3) figure + prose, the common case — the
+figure carries structure and relationships, the surrounding prose carries the
+detail. When the answer involves a figure, author one. When it does not, do
+not draw out of habit. The `.fd` must carry everything the rendered figure
+conveys, and no more is owed.
+
+**Mode 3 has an authoring consequence:** if the figure is the outline, do not
+cram the whole story into it. Keep labels short and leave the detail to the
+host document. Overstuffed labels are the visible symptom of an author making
+the figure do prose's job.
+
+## Workflow
+
+1. Edit or create `X.fd` (never edit an `.svg`). A new file opens with the
+   spec provenance line, verbatim, then the header — see *The document
+   skeleton* below.
+2. Build + validate: `node <this-skill-dir>/build-svg.js X.fd`
+   Errors come as `Line N: message` — fix and rerun until `OK`. Titles are not
+   drawn by default (Markdown supplies the caption); `--with-title` opts in.
+3. Embed in Markdown — the SVG only, never `.fd` content:
+
+   ```markdown
+   ![Ingress datapath](figures/ingress.svg)
+
+   <sub>source: [figures/ingress.fd](figures/ingress.fd)</sub>
+   ```
+
+4. Keep `X.fd` and `X.svg` side by side, same basename; commit both.
+
+If a `.fd` is missing, its `.svg` carries the source verbatim, the SHA-256 of
+that source and the engine version that rendered it, in
+`<metadata id="figdown-source" data-sha256="…" data-engine-version="…">`.
+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".
+
+## Load only what you need
+
+This file is the whole genre-independent language. **Everything else is one
+lookup away, and the lookup is mechanical:** line 1 of a `.fd` names its genre,
+so you know which file you need before you need it.
+
+<!-- skill-coverage: router -->
+
+| Genre on line 1 | Load | Add only for EXPERIMENTAL constructs |
+|---|---|---|
+| `block` — architecture, dataflow, hierarchy | `reference/scene.md`, `reference/layout.md` | `reference/experimental/constructs.md` |
+| `bitfield` — packet headers, register layouts | `reference/bitfield.md` | — |
+| `table` — config, state, memory maps | `reference/table.md` | `reference/experimental/constructs.md` |
+| `topology` | `reference/scene.md`, `reference/layout.md` | `reference/experimental/topology.md`, `reference/experimental/constructs.md` |
+| `flowchart` | `reference/scene.md`, `reference/layout.md` | `reference/experimental/flowchart.md`, `reference/experimental/constructs.md` |
+| `timing` | — | `reference/experimental/timing.md` |
+
+Two more files answer a **task** rather than a genre:
+
+- **Reading a `.fd` someone else wrote, to summarise or answer from it** →
+  `reference/reading.md`. It is the contract for what you may conclude and
+  what you must not infer, and it is all you need: a reader can skip every
+  genre file above.
+- **Transcribing an existing figure** — a drawing, a screenshot, another
+  format → `reference/transcribe.md`.
+
+Pick the genre by what the figure IS, not by its subject: the left-hand
+column above says what each is for. Prefer the first three — they are the
+portable ones.
+
+## The document skeleton
+
+The grammar is **CLOSED**: an unknown line is an error, never ignored. Five
+keywords — `figdown`, `title`, `class`, `layout`, `pin` — mean the same thing
+under every genre and no genre may redefine them. Everything else belongs to a
+genre.
+
+```figdown
+# FigDown — figures as text. Spec: https://github.com/FigDown/figdown
+                            # ^ FIRST LINE of every document you write.
+                            # Verbatim, em dash included. It is a comment:
+                            # the parser ignores it. It is there because the
+                            # file travels — into a wiki, a ticket, a pasted
+                            # message — and tells whoever meets it there what
+                            # the format is and where it is defined.
+figdown 0.1 block           # REQUIRED first significant line; comments and
+                            # blanks may precede it. The genre is REQUIRED.
+                            # A later `figdown 0.1 <genre>` starts a new
+                            # section with its own genre; one file still
+                            # renders to one SVG.
+title "Some Title"          # optional; the quotes are REQUIRED
+# comments start with '#'; inside quotes the only escapes are \n \" \\
+class hot "Congested path" stroke=#dc2626   # meaning + style, declared once
+```
+
+**Quotes mark a STRING, and nothing else.** Every label is quoted, at every
+position that has one — `title "TCP Header"`, `class c "meaning"`, and the
+label of every block opener — because whitespace also separates arguments, so
+a bare token cannot hold a phrase. Everything that is *not* a string is bare:
+ids and references (`class=hot`), and every value drawn from a fixed list of
+spellings (`style=dashed`, and the header's own `figdown 0.1 <genre>`).
+Quoting one of those is a line error. Quoting a NUMBER or a point is not:
+`width="90"` and `at="(1,2)"` are legal and mean exactly what the bare forms
+mean.
+
+**`class` is how meaning survives.** Colour and shape alone assert nothing a
+reader can recover: a `class` states the meaning in text and the legend draws
+itself from it. Anything you want a reader to *conclude* goes in a label or a
+class meaning — never in a colour alone. A class with an empty meaning
+(`class c ""`) deliberately claims nothing.
+
+**Two paint channels, SVG's own**, legal on any element that has them:
+
+| Key | What it paints |
+|---|---|
+| `fill=` | the **interior** of a shape — `#rgb`, `#rrggbb`, a CSS colour name, or `transparent` |
+| `stroke=` | the **outline** of a shape, and the **whole** of a line |
+| `style=` | `solid` \| `dashed` \| `dotted` |
+| `class=` | one or more declared class ids, comma-separated: `class=hot,legacy` |
+
+A line — an edge, a marker, a ring — has no interior, so `fill=` on one is an
+error naming `stroke=`. There is **no label-colour key**: a label's colour is
+derived from the background it sits on, so light text lands on dark fills by
+itself.
+
+**`layout` and `pin`** are the layout zone. Everything from a `layout` line
+down is geometry that exists only to stabilise the `.svg`: it carries no
+meaning, no genre may put its own semantics inside it, and `pin` is the only
+directive legal there. Skip the zone when reading; see `reference/layout.md`
+when writing.
+
+## Portability: two statuses, and the parser tells you nothing
+
+Every keyword, option key and genre is either **NORMATIVE** (NORMATIVE — inside the
+v0.1 conformance surface and its compatibility promise) or **EXPERIMENTAL**
+(EXPERIMENTAL — the engine accepts it and your document keeps working, but it is
+outside both, and may change or be withdrawn in a later `0.x`).
+
+**The parser never warns**, so a line that parses tells you nothing about its
+status — this is the only signal you get. Everything reachable *only* through
+the right-hand column of the router is EXPERIMENTAL: use it when the figure needs
+it, and say so beside the figure.
+
+**Hybrid figures** (a scene and a table in one artifact): start a second
+section with its own `figdown 0.1 <genre>` header rather than nesting one
+genre's block inside another's.
+
+## Do not invent syntax
+
+If something seems missing, compose it from what exists or tell the user.
+Retired spellings are hard errors whose message names the replacement — read
+the error instead of guessing around it.
+
+## Maintaining a document written against an older version
+
+Line 1 pins the version, so never mix syntax generations in one file. When the
+language moves, a **NORMATIVE** construct ships a mechanical rewrite rule and
+you upgrade by applying the rules in order. An **EXPERIMENTAL** one carries no
+such promise: it may be withdrawn with nothing that does what it did, in which
+case the tooling reports and cannot rewrite, and a human decides what the
+figure should say instead.
+
+Full spec and docs: https://github.com/FigDown/figdown

package/skill/figdown/build-svg.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-// FigDown Stage-0 sidecar generator (R14): X.fd -> X.svg
+// FigDown sidecar generator: X.fd -> X.svg
 // Deterministic: same source -> same SVG, bit-level. The artifact embeds
-// its own source and a SHA-256 of it (spec draft section 7).
+// its own source and a SHA-256 of it (spec core §7).
 // The engine is never forked: parser+renderer are extracted from the editor
 // single file at build time (the "regenerate, don't fork" rule).
 'use strict';
@@ -24,24 +24,32 @@ function loadEngine() {
   const start = h.indexOf('const SHAPES');
   const end = h.indexOf('// 3. UI');
   if (start < 0 || end < 0) throw new Error('cannot locate engine in ' + ENGINE);
-  const factory = new Function(h.slice(start, end) + '\nreturn {parse, render};');
+  const factory = new Function(h.slice(start, end) + '\nreturn {parse, render, stackSectionSvgs, FIGDOWN_VERSION};');
   return factory();
 }
 
 function buildOne(engine, fdPath) {
   const src = fs.readFileSync(fdPath, 'utf8');
-  const { doc, errs } = engine.parse(src);
+  const parsed = engine.parse(src);
+  const errs = parsed.errs || parsed.errors || [];
+  const docs = parsed.docs && parsed.docs.length ? parsed.docs : (parsed.doc ? [parsed.doc] : []);
   if (errs.length) {
     console.error(fdPath + ':');
     for (const e of errs) console.error('  ' + e);
     return false;
   }
-  const svg = engine.render(doc, RENDER_OPTS).svg;
+  const svg = docs.length > 1
+    ? engine.stackSectionSvgs(docs.map(d => engine.render(d, RENDER_OPTS)))
+    : engine.render(docs[0], RENDER_OPTS).svg;
   const hash = crypto.createHash('sha256').update(src, 'utf8').digest('hex');
-  // render options are recorded in the artifact so a third-party rebuild
-  // (same source + same recorded options) stays bit-identical
+  // The artifact records three things (spec core §7): the SHA-256 OF THE
+  // SOURCE, the ENGINE VERSION that rendered it, and any non-default render
+  // option — so a third-party rebuild (same source + same engine version +
+  // same recorded options) stays bit-identical, and a diff between two
+  // renderings of one source has somewhere to point.
   const optAttr = RENDER_OPTS.title === true ? ' data-render-options="with-title"' : '';
-  const meta = '<metadata id="figdown-source" data-sha256="' + hash + '"' + optAttr + '><![CDATA[\n'
+  const meta = '<metadata id="figdown-source" data-sha256="' + hash + '"'
+    + ' data-engine-version="' + engine.FIGDOWN_VERSION + '"' + optAttr + '><![CDATA[\n'
     + src.replace(/]]>/g, ']]]]><![CDATA[>') + '\n]]></metadata>';
   const artifact = svg.replace(/<\/svg>$/, meta + '</svg>');
   const out = fdPath.replace(/\.fd$/, '') + '.svg';
@@ -54,20 +62,47 @@ const argv = process.argv.slice(2);
 const RENDER_OPTS = {};
 const args = argv.filter(a => {
   if (a === '--with-title') { RENDER_OPTS.title = true; return false; }
-  if (a === '--no-title') { return false; }  // the default since 0.1-dev.12 (kept for compat)
+  if (a === '--no-title') { return false; }  // already the default; accepted so old command lines keep working
   return true;
 });
 if (!args.length) {
   console.error('usage: node tools/build-svg.js [--with-title] <file.fd | dir> ...');
   process.exit(2);
 }
+// RECURSIVE. "A gate that does not recurse is a gate that lies" was written
+// for the read-only CHECKS, which read only the top level of a directory.
+// The GENERATOR had the same defect and was missed:
+// handed `examples/ figures/` it rebuilt 28 of the 66 artifacts and reported
+// success on all 28, so a version bump left 38 artifacts recording an engine
+// that no longer existed. `artifact-check.js` (which does recurse) caught it,
+// which is the division of labour working — but the generator lying is how the
+// stale artifacts got there in the first place, twice (§3.1(b)).
+function collect(a, acc) {
+  const st = fs.statSync(a);
+  if (!st.isDirectory()) { acc.push(a); return acc; }
+  for (const name of fs.readdirSync(a).sort()) {
+    if (name === 'node_modules' || name === '.git') continue;
+    const p = path.join(a, name);
+    if (fs.statSync(p).isDirectory()) collect(p, acc);
+    else if (name.endsWith('.fd')) acc.push(p);
+  }
+  return acc;
+}
+
 const engine = loadEngine();
-let fail = false;
+let built = 0;
+let failed = 0;
 for (const a of args) {
-  const st = fs.statSync(a);
-  const files = st.isDirectory()
-    ? fs.readdirSync(a).filter(f => f.endsWith('.fd')).sort().map(f => path.join(a, f))
-    : [a];
-  for (const f of files) if (!buildOne(engine, f)) fail = true;
+  for (const f of collect(a, [])) { if (buildOne(engine, f)) built++; else failed++; }
 }
-process.exit(fail ? 1 : 0);
+// State the count. §3.1(d): coverage is verified as a number, not assumed —
+// compare against `find <dir> -name '*.fd' | wc -l`.
+// `built` counts artifacts WRITTEN, never files attempted: a file whose source
+// does not parse writes nothing, and counting it as built made the summary line
+// contradict the errors printed above it and the exit code below it — in CI
+// logs, and in the write->validate->fix loop this message exists to serve.
+// A failure is therefore reported as its own number, and the two together are
+// the file count to compare against.
+console.log('built ' + built + ' artifact(s) from ' + args.length + ' path argument(s)'
+  + (failed ? '  —  ' + failed + ' of ' + (built + failed) + ' .fd file(s) FAILED and wrote nothing' : ''));
+process.exit(failed ? 1 : 0);