Skip to main content
Welcome. This site supports keyboard navigation and screen readers. Press ? at any time for keyboard shortcuts. Press [ to focus the sidebar, ] to focus the content. High-contrast themes are available via the toolbar.
serard@dev00:~/cv

Ide.Dsl — Build: writing the full-blown meta-DSL

The bridge

The companion Meta Ide.Dsl design series delivered the design — seven articles, one type-checked prototype, every speculative passage labelled as such. This series delivers its written counterpart to the code: fifteen articles (08 → 22), roughly 56 000 words, the imagined production of @frenchexdev/ide-dsl, @frenchexdev/ide-forge, @frenchexdev/ide-runtime and a requirements-ide.vsix walked through end-to-end in prose. Same register as the design series: > Proposal (write-in-public) where something is not yet settled, code snippets type-checked by lifting only what needs to be verified into content/blog/ide-dsl/assets/*.ts.

The scope is honest and bounded. This series is not a shipped codebase — it is a written walk-through of what shipping it would look like, pinned at every turn to the monorepo patterns already in place in packages/requirements/ and packages/typed-fsm/. The editorial branding Ide.Dsl stays the title and category; the package names (@frenchexdev/ide-dsl, @frenchexdev/ide-forge, @frenchexdev/ide-runtime) appear as rhetorical anchors — they name the objects the series reasons about, without pretending the series has also implemented them.

The running example is not a toy

The target DSL is @frenchexdev/requirements from the first keystroke. No traffic-light FSM first, no intermediate step on typed-fsm, no hello-world detour. The requirements DSL carries fifteen entity kinds, six decorators, five built-in style presets, JSON-Schema binding, branded primitives, and EARS statement parsing; the IDE surface for it is exactly the kind of thing a meta-DSL has to dilute across many articles to stay honest.

Choosing it as the running example is a deliberate pedagogical commitment. A reader who has only ever seen toy DSLs in tutorials has never seen the part where a meta-DSL earns its keep — the part where the TextMate grammar disagrees with the typing, where the LSP needs information the extractor discarded, where the IR has to carry four things the emitters can read but never mutate. That part is present from article 01. The fifteen-article sequence is a deliberate dilution of that complexity, slice by slice.

The living fixture, when one is needed, is an excerpt of packages/requirements/requirements/features/compliance-core.ts — a real monorepo file, cited across articles to exercise each IDE service in prose. Article 14 is not a climactic reveal but the honest stitching: the install of the .vsix, the open of packages/requirements/, the npx requirements compliance --strict that stays green through IDE-driven edits — all walked through as prose, the same way the design series walked through the requirements-ide.spec.ts artefact without ever running it.

Reading paths

  • Builder path — 08 → 09 → 10 → 11 → 14: decorators, extractor, IR, emitter registry, LSP server emitter. Gives you the spine of ide-forge end-to-end.
  • Tester path — 19 → 18 → 17: the port-driven test strategy, then rename/refs, then completion. Starts from the pyramid, works down into services.
  • End-to-end user path — 20 → 21: packaging, then the dog-food install on packages/requirements. Shortest path to "I can use this today".
  • Retrospective — 22: what stayed open, Monaco and JetBrains targets, runtime-reflection alternatives and why codegen won.

None of these is a short version. Each article commits to roughly 4 000 words with the Requirement → Feature → AC → Unit test chain as its spine, two to three mermaid diagrams, a SOLID lens and a DRY lens, and a cross-link back to its design-series counterpart.

The five pillars still hold — under load

Pillar Under load this means
SOLID Each emitter is discussed as one strategy in an EmitterRegistry that mirrors ScaffolderRegistry. Open/closed by construction, not by comment.
DRY LanguageIR is the single source of truth. Seven emitters read it, never each other. A grammar change touches the IR, not the manifest emitter.
Unit tests Three layers — extractor (ts-morph input → IR), emitters (IR → in-memory FS), LSP integration (headless vscode-languageclient round-trip). Zero describe/it; every test snippet is @FeatureTest + @Verifies.
Dog-fooding Every article opens on an id: 'FEAT-IDEDSL-NN' Feature satisfying a named Requirement; each AC is exhibited inline and verified by a written @FeatureTest/@Verifies snippet.
Requirements DSL as pivot The whole bridge walks the imagined production of requirements-ide.vsix. The DSL you learned about in the design series is the DSL whose extension is written about here.

Package map

Diagram
Figure 1 — Package map. ide-dsl exposes decorators and IR types; ide-forge consumes them at compile time; ide-runtime ships inside every generated extension; requirements-ide is the first consumer.

Five pillars × fifteen articles

The matrix below is the map of cross-references — not a checklist. A reader who cares about, say, testing can jump straight to the relevant section of every article. Cells stay short; the articles fill them in.

Pillar / Article 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15
SOLID decorators as SRP extractor SRP IR as open/closed axis registry OCP core manifest SRP snippet/exec SRP LSP server SRP host ISP diagnostics SRP completion SRP navigation SRP port segregation packaging SRP end-to-end LSP governance
DRY fragment registry AST walk once IR contract core one emitter per kind one manifest source one snippet source one server scaffold one host boot one validator chain one completion pipeline one symbol index InMemoryFileSystem reuse one vsce call one .vsix one IR across targets
Unit tests decorator round-trip AST→IR snapshots IR schema fuzz emitter snapshots manifest ajv tests snippet snapshots handler wiring host boot tests diagnostic property tests completion ranking tests rename symmetry test pyramid core vsix smoke dog-food install open questions
Dog-fooding FEAT-IDEDSL-01 FEAT-IDEDSL-02 FEAT-IDEDSL-03 FEAT-IDEDSL-04 FEAT-IDEDSL-05 FEAT-IDEDSL-06 FEAT-IDEDSL-07 FEAT-IDEDSL-08 FEAT-IDEDSL-09 FEAT-IDEDSL-10 FEAT-IDEDSL-11 compliance --strict vsix compliance mise en abyme retrospective
Requirements DSL as pivot decorators mirror @Satisfies/@Refines extracts requirements-ide.spec.ts IR carries EARS patterns grammar for EARS verbs manifest for .feat.ts snippet: scaffold a Feature server for REQ-IDs host activates on .feat.ts orphan-Feature diagnostic EARS-pattern completion go-to-definition on REQ-ID dog-food every layer install on packages/requirements compliance --strict stays green through IDE edits next DSLs (typed-fsm, metacratie)

Article index

Part I — Foundations (3 articles)

  1. 01 — Bootstrapping @frenchexdev/ide-dsl — package skeleton, six TC39-standard decorators, module-load registry, REQ-IDEDSL-DECORATORS-STANDARD.
  2. 02 — The extractor — ts-morph walk, SourceReader port, decorator-by-decorator extraction, ParseError with source ranges.
  3. 03 — LanguageIR as contract — ajv-validated JSON schema, branded primitives, golden-snapshot tests, $schemaVersion: '2026-04-14'.

Part II — Emitters (5 articles)

  1. 04 — EmitterRegistry + grammar emitter — registry mirroring ScaffolderRegistry; TextMate grammar JSON from @Token[]; semantic-tokens fallback.
  2. 05 — Manifest emitter — package.json contributes.*, activation events, ajv validation against VSCode's published schema.
  3. 06 — Snippets + commands + task provider — @Snippet to .code-snippets, @Executor to contributes.commands + generated TaskProvider.
  4. 07 — LSP server emitter — vscode-languageserver scaffold per extension, one handler file per @LspFeature.
  5. 08 — Extension host + client — extension.ts activate/deactivate, vscode-languageclient boot, IR-driven activation events.

Part III — LSP handlers (3 articles)

  1. 09 — Diagnostics pipeline — @Rule validators, debounced reparse, publishDiagnostics with related information.
  2. 10 — Completion, hover, signature help — context-sensitive completion, doc-comments captured in IR, parametric-rule signature help.
  3. 11 — Navigation — go-to-definition, find-references, rename, workspace symbols; symbol index maintained on change.

Part IV — Packaging & Testing (2 articles)

  1. 12 — Testing the full stack — three layers + @vscode/test-electron, ≥95 %/file, fast-check invariants, requirements compliance --strict green.
  2. 13 — Packaging .vsix + publishing — vsce package, marketplace metadata, CI-less flow matching the project posture.

Part V — End-to-end & retrospective (2 articles)

  1. 14 — Shipping requirements-ide.vsix — install the extension, open packages/requirements/, edit through the IDE, compliance stays green.
  2. 15 — What stayed open — Monaco and JetBrains targets, reflect-metadata alternative, watch mode, governance, next bridge series.

Cadence and scope

Roughly two to three working days per article — one for code, one for prose, half for mermaids and review. Total around thirty-five to forty working days end-to-end. Each article ships with its code green before the prose is merged; every mermaid is validated by scripts/validate-mermaid-captions.ts and cached by scripts/lib/mermaid-manifest.ts. No CI/CD — local build, push to main, Vercel serves.

When article 15 lands, the Ide.Dsl side of the @frenchexdev/* ecosystem is closed: the requirements DSL has an extension, the extension compiled itself from a decorator spec, every feature has a test, and the test framework used to verify it is the same one the extension is serving. That circle is the point of the series.

⬇ Download