Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions .github/workflows/check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,9 @@ jobs:
run: npm run check:sync
- name: ESLint
run: npm run lint
- name: Type check
- name: Type check (page scripts; server, tools and tests in strict mode)
run: npm run typecheck
- name: Strict type check (no new errors vs baseline)
- name: Strict type check (shared core 0 errors; rest no new errors vs baseline)
run: npm run typecheck:strict
- name: Unit tests (parsers, layout, styles, server)
run: npm test
588 changes: 395 additions & 193 deletions 3d.html

Large diffs are not rendered by default.

6 changes: 5 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Turns pasted GitHub markdown (Mermaid flowchart, sequence, state, class, ER, gan

- `index.html` — 2D isometric SVG version. Also served from zo.space API route `/flow-explainer` (not linked publicly).
- `3d.html` — Three.js version (real 3D blocks, rotatable camera). Also served via zo.space (route `/flow-explainer/:file`; Three.js 0.187.0 jsDelivr-minified in `vendor/`, imported as `./vendor/three.module.js` and served by route `/flow-explainer/vendor/:file`).
- Both files are standalone and edited directly; they share the same markdown parser, layout, panel, timeline and `#c=` client-link code (copied, not imported). The parser block (`/* ---------- markdown` … `/* ---------- layout`) and the diagram styles block are edited in `index.html` only, then copied with `python3 tools/sync-parser.py` (`--check` to verify). Non-parser fixes (render, buildScene, iconFor) still go into both files by hand.
- Both files are standalone and edited directly; they share the same markdown parser, layout, panel, timeline and `#c=` client-link code (copied, not imported). The shared core (`/* ---------- shared core:` … `/* ---------- end of diagram styles + settings`: helpers, markdown + Mermaid parsers, layout, diagram styles/settings UI) is edited in `index.html` only, then copied with `python3 tools/sync-parser.py` (`--check` to verify). Layout spacing differs per page via `IS_3D_PAGE`. Non-parser fixes (render, buildScene, iconFor) still go into both files by hand.
- Every diagram type is converted into the same `{nodes,links,steps,groups}` graph. Extra node fields: `note`, `icon` (forced emoji), `iconFallback`, `ci` (palette index), `hk` (height factor: pie, journey, xychart, sankey, packet). Graph flags: `fixed` (parser set `gx/gy`, skip `layout()`; non-pie fixed parsers call `routeFixed()` to give links `pts`: timeline, quadrant, git, xychart, block, kanban, packet), `noZones` (colour groups without zone slabs, mindmap), `diagramTitle` (used when the markdown has no heading).
- Both read the same `localStorage` key `flowx.md`; the 2D/3D button keeps the URL hash and works with both `/flow-explainer` ↔ `/flow-explainer/3d` and `index.html` ↔ `3d.html` (static hosting).
- Public repo: https://github.com/solutionforest/flow-explainer (MIT). README images in `docs/images/` were made with the Snapshot button; sample inputs in `examples/`.
Expand All @@ -21,3 +21,7 @@ Turns pasted GitHub markdown (Mermaid flowchart, sequence, state, class, ER, gan
- Icons: Settings → Icons (Show/Hide) toggles the emoji on blocks (`ICONS_ON`, `localStorage` `flowx.icons`, client links carry `&i=0` when hidden); renderers call `ICONS_ON?iconFor(n):''`.
- radar (`parseRadar`, points on a circle, `noZones`), treemap (`parseTreemap`, kanban-like columns per top section) and zenuml (`parseZen`, sequence model with a call stack) were added after the first 20 types.
- Code checks: `npm run check` = sync check + ESLint (`eslint.config.mjs`) + `tsc -p tsconfig.basic.json` (checkJs, must be 0 errors) + strict TS with baseline (`tools/typecheck-strict.mjs`, `tsc-baseline.json`; no new errors allowed, run `npm run typecheck:baseline` after fixing some). Page scripts are copied to `.check/` with line numbers kept (`tools/extract-scripts.mjs`). CI: `.github/workflows/check.yml`. In index.html the play-stop function is `stopPlay()` (avoids shadowing `window.stop`).
- Strict typing: the shared core must have 0 TypeScript strict errors (JSDoc typedefs `FxNode`, `FxLink`, `Step`, `Graph`, `Scene`, `MdDoc`, `DiagramStyle`…); `tools/typecheck-strict.mjs` fails on any core error regardless of the baseline. server.js / tools / tests are strict via `tsconfig.node.json`.
- Tests: `npm test` (node:test) — `tests/load-core.mjs` evaluates the shared core from index.html in a VM; `tests/parser.snapshot.json` pins parser output (`npm run test:update` to accept intended changes); `tests/server.test.mjs` covers routes incl. `/embed`, `/embed/3d`, trailing slashes, assets under sub-paths and private files.
- Circuit style (`circuit`): `chips` (2D `chipDetail()`, 3D `chipGeo()`), `flat` (block height factor), `labMono`/`labUpper` (plain monospace capital labels, `--d-lab`).
- server.js exports `resolveFile`/`handle` (listens only when run directly). Links are built without trailing slashes (`pageUrl()`): `/3d/` used to 404 and `/embed/…/` broke relative asset URLs.
33 changes: 21 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -245,7 +245,7 @@ If a browser has no WebGL, the 3D page opens the 2D page automatically.

Open **⚙ Settings** to change how the diagram looks. The same style is used in 2D and 3D, it is saved in your browser, and a client link opens with the style you picked.

![The ticket-order example in the five diagram styles: Original, Teal, Line Art, Blueprint and Glass](docs/images/diagram-styles.png)
![The ticket-order example in the six diagram styles: Original, Teal, Line Art, Blueprint, Glass and Circuit](docs/images/diagram-styles.png)

| Style | Look |
|---|---|
Expand All @@ -254,6 +254,7 @@ Open **⚙ Settings** to change how the diagram looks. The same style is used in
| Line Art | White blocks with bold black outlines |
| Blueprint | Dark background, cyan wireframe blocks |
| Glass | See-through blocks |
| Circuit | Dark board with flat chip-shaped blocks (inset top, pins), thin steel-blue lines and plain capital labels |

Each style is one entry in the `STYLES` list in `index.html` (background, block colours, outline, highlight, label colours, and the 3D material). To add a style, copy an entry, change the values, and run `python3 tools/sync-parser.py` so `3d.html` gets it too. The site itself always uses the Solution Forest colours; only the diagram changes.

Expand Down Expand Up @@ -314,26 +315,34 @@ Both pages share the same markdown reader, step panel, timeline, settings and cl

## Code checks

The pages have no build step, but the code inside them is checked the way a typed project would be. `npm run check` runs four steps, and GitHub Actions runs the same on every push and pull request ([`check.yml`](.github/workflows/check.yml)):
The pages have no build step, but the code inside them is checked the way a typed project would be. `npm run check` runs five steps, and GitHub Actions runs the same on every push and pull request ([`check.yml`](.github/workflows/check.yml)):

| Step | Command | What it does | Must be |
|---|---|---|---|
| Shared code in sync | `npm run check:sync` | The parser and diagram-style blocks in `3d.html` match `index.html` | in sync |
| Lint | `npm run lint` | ESLint (recommended rules plus stricter ones: no unused or undefined names, `const` where possible, `===`, no `eval`) on the page scripts, `server.js` and `tools/` | 0 problems |
| Type check | `npm run typecheck` | TypeScript reads the page scripts as JavaScript (`checkJs`) and reports wrong property names, wrong argument types and similar mistakes | 0 errors |
| Strict type check | `npm run typecheck:strict` | TypeScript `strict` mode, the closest match to PHPStan level 10: no implicit `any`, null checks, strict function types | no **new** errors |
| Shared code in sync | `npm run check:sync` | The shared core in `3d.html` matches `index.html` | in sync |
| Lint | `npm run lint` | ESLint (recommended rules plus stricter ones: no unused or undefined names, `const` where possible, `===`, no `eval`) on the page scripts, `server.js`, `tools/` and `tests/` | 0 problems |
| Type check | `npm run typecheck` | TypeScript reads the page scripts as JavaScript (`checkJs`), and checks `server.js`, `tools/` and `tests/` in **strict** mode | 0 errors |
| Strict type check | `npm run typecheck:strict` | TypeScript `strict` mode on the page scripts, the closest match to PHPStan level 10 (no implicit `any`, null checks, strict function types) | **shared core: 0 errors**; rest: no new errors |
| Unit tests | `npm test` | Node's built-in test runner: every example parses into a valid graph, each diagram type has behaviour tests, a snapshot of the parsed output catches any change, the diagram styles are complete, and `server.js` serves pages, assets and `/embed` correctly and refuses private files | all pass |

How the strict level works, like a PHPStan baseline:
- The known strict-mode errors are listed in [`tsc-baseline.json`](tsc-baseline.json), counted per file and message, not per line.
- Any error that is not in the baseline fails the check.
- After you fix some, run `npm run typecheck:baseline` so the baseline shrinks. Never grow it to hide a real problem.
**What "shared core" means.** Both pages are single files, so the code they share is one block, copied from `index.html` into `3d.html` by `python3 tools/sync-parser.py`. It covers:
- the helpers, the markdown reader and all 23 Mermaid parsers;
- the layout;
- the diagram styles and the settings / share / steps UI.

Most of the remaining errors are function parameters without type information. Adding JSDoc types (`/** @param {string} label */`) as code is touched brings the baseline down.
This block is fully typed with JSDoc (`FxNode`, `FxLink`, `Step`, `Graph`, `DiagramStyle`…) and must stay at zero strict-mode errors. That rule can't be baselined.

**The rest** (2D/3D rendering, events, snapshot) uses a PHPStan-style baseline:
- [`tsc-baseline.json`](tsc-baseline.json) lists the known strict-mode errors, counted per file and message, not per line. Any error not in the list fails.
- After you fix some, run `npm run typecheck:baseline` so the list shrinks; never grow it to hide a real problem.
- It went from 1,995 to 809 when the core was typed.

**Tests** load the shared core straight out of `index.html` into a Node VM ([`tests/load-core.mjs`](tests/load-core.mjs)), so the pages stay standalone and the logic is still testable. If you change the parser output on purpose, run `npm run test:update` and review the diff of `tests/parser.snapshot.json`.

The page code lives inside the HTML files, so [`tools/extract-scripts.mjs`](tools/extract-scripts.mjs) first copies each script into `.check/*.js`. It keeps the same line numbers, so every reported line matches `index.html` or `3d.html`.

```bash
npm install # dev tools only: eslint, typescript, @types/three
npm install # dev tools only: eslint, typescript, @types/three, @types/node
npm run check
```

Expand Down
Binary file modified docs/images/diagram-styles.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion eslint.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ export default [
{ files: ['.check/index.js'], rules: { 'no-implicit-globals': 'off' } },
{ files: ['.check/3d.js'], languageOptions: { sourceType: 'module' } },
{
files: ['server.js', 'tools/**/*.mjs', 'eslint.config.mjs'],
files: ['server.js', 'tools/**/*.mjs', 'tests/**/*.mjs', 'eslint.config.mjs'],
languageOptions: { ecmaVersion: 2023, globals: { ...globals.node } },
},
{ files: ['server.js'], languageOptions: { sourceType: 'commonjs' } },
Expand Down
Loading
Loading