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 — a meta-DSL that makes any DSL first-class in VSCode

The thesis in three sentences

Writing a VSCode extension by hand for every new DSL costs hundreds of lines of plumbing — manifest, grammar JSON, snippets file, LSP wiring, task provider — that say almost the same thing each time. A small TypeScript meta-DSL, driven by decorators on a single spec.ts file, can compile that plumbing away and leave only the domain-specific decisions visible to the author. This series designs that meta-DSL in public, without implementing it yet, and ships one type-checked prototype — requirements-ide.spec.ts — as the piece of evidence every article refers back to.

The framing matters and it is stated once, here, to hold for the whole series: the meta-DSL does not "generate an IDE". It generates a VSCode extension that makes files of a target DSL first-class in the editor — with autocompletion, refactoring, navigation, diagnostics, versioning, running — the way .cs files are first-class when you open a solution in Visual Studio, or .ts files in VSCode itself. The extension is the delivery surface; the IDE-like services are the value. The business is visible, the plumbing is hidden.

Why publish the design before the code

Two reasons, both defensive.

The first is that I have seen too many DSL projects — mine and others' — where the author wrote the DSL first, then the tooling, then discovered mid-implementation that the grammar disagreed with the intended typing, that the LSP could not surface what the decorators promised, that the executor needed information the IR had already discarded. Ordering matters. Writing the meta-DSL after having thought hard about what a DSL asks from an IDE, and after having pinned the patterns to existing monorepo code, is cheaper than discovering the same constraints during the second rewrite. Design-in-public is the honest version of that: every speculative bit is labelled > Proposal (design-in-public) so a future reader — including me — can tell what was proven from what was guessed.

The second is that the series sits at the junction of two ongoing projects. Métacratie / Compilateur builds a Roslyn-powered compiler for law in C#; Appareil et compilateur (in preparation) argues that a zoo of small DSLs, parameterised by META(Ex × Ty), is a better response to regulatory complexity than one monolithic system. Both projects need IDE support to be credible — a DSL that juristes, commoners, or civic engineers cannot use from within their editor of choice is a DSL that will not be used at all. This series answers the editor side of that question for the TypeScript half of the ecosystem, the same way the content/blog/entity-dsl/ and content/blog/distributed-task/ series answer it for the C# half via Roslyn source generators.

The seven articles

Each article number corresponds to one FEAT-ARCHPAT-NN Feature declared in assets/features.ts. An article is "accepted" when its prose verifies every one of its acceptance-criterion methods — the series dog-foods the very DSL it designs for.

  1. What is an IDE? Language services, LSP vs DAP, TextMate vs semantic tokens — bounding the target.
  2. What does a DSL need from an IDE? External vs internal DSLs, the five-service minimum-viable baseline, the case of the requirements DSL today.
  3. The trip and the guardrails. Prior art engaged at length — MPS, Roslyn source generators, the TypeScript compiler infrastructure, Langium. Answering can we emit new TS at compile time?
  4. SOLID in the monorepo patterns. What packages/requirements and packages/typed-fsm teach us, applied principle by principle.
  5. DRY and the LanguageIR as contract. Teardown of a VSCode package.json, the IR as single source of truth, when to stop factoring.
  6. Unit testing, port-driven. Testing a code generator without writing to disk — extractor snapshots, emitter maps, property tests, @FeatureTest/@Verifies throughout.
  7. The prototype and what stays open. Guided walkthrough of the requirements-ide.spec.ts artefact, honest open questions, bridge to a future implementation series.

Reading paths

  • If you want to know what the meta-DSL is: start at 07, skim the artefact, then read 03 and 04 for the justifications.
  • If you want the foundations first: 01 → 02 → 03 reads as a continuous essay on IDEs, DSLs, and the gap between them.
  • If you are here for the patterns: 04 → 05 → 06 is the SOLID / DRY / testing core, each pinned to a file in the monorepo.

None of these paths is a "short" version. The foundations path and the patterns path each run around 8 000 to 10 000 words; the full series totals roughly 20 000. Dense on purpose — same register as Métacratie / Compilateur.

Five pillars × seven articles

Every article commits to surfacing the five pillars of the series at least once. The matrix below is not a checklist — it is the map of cross-references, so that a reader who cares about, say, testing can jump straight to the relevant section of every article.

Pillar / Article 01 02 03 04 05 06 07
SOLID defining services as single responsibilities DSL contract boundaries (SRP) guardrails core strategy pattern port segregation decorator mapping
DRY LSP capability reuse DSL IDE support cost/value "no 500 LOC per DSL" avoid scaffolder duplication core — IR contract InMemoryFileSystem across test layers artefact one-file economy
Unit testing — — testability as guardrail ports split snapshotable IR core @FeatureTest dog-food
Dog-fooding — requirements DSL today business-visible posture packages/* citations compliance-core.ts as IR precedent @FeatureTest/@Verifies mise en abyme (core)
Requirements DSL as pivot — first-class case study articulates the leverage @Feature/@Satisfies SRP example compliance-core.ts cited feature-tests for codegen artefact is requirements-ide.spec.ts

What you will not find here

No working ide-forge package. No grammar files emitted. No extension published to the VSCode Marketplace. The series ends at a spec.ts that type-checks and a feature file that declares seven acceptance criteria — the design artefact.

The implementation belongs to a later, narrower series — Ide.Dsl — Build, now shipping article by article — which takes the LanguageIR defined here, walks through the extractor and the emitters in prose, specifies the tests this series sketches, and packages the requirements-ide extension end to end. That series is judged against the promises made in this one; each of its articles carries a cross-link back to the design article it satisfies.

Related reading

⬇ Download