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

Micro-DSLs and a Shared Kernel — decomposing the IDE meta-DSL into a suite of bounded contexts

The thesis in three sentences

The meta-ide-dsl series proved that a small TypeScript meta-DSL could compile decorated spec.ts files into a VSCode extension; it landed the prototype on a single RequirementsIde class carrying six mixed-concern decorators (@Token, @Rule, @Snippet, @LspFeature, @Executor, @Language). That single-class shape works for one DSL but breaks the moment a team wants to publish only the syntax highlighting layer, swap a generator without touching the LSP, or version completion independently of refactoring. This series re-cuts the meta-DSL along DDD lines: one shared kernel (Concept, Property, AST, PatchBus, Banner, EditLog) and fourteen micro-DSLs, each a separately publishable VSCode extension, each a bounded context with its own decorator family, its own emitted artefacts, and a single justified link back to the kernel.

The framing matters and is stated once, here, to hold for the whole series: the meta-DSL is not "one DSL", it is a suite of DSLs around a kernel. The unit of release is the micro-DSL package. The unit of composition is the host (LSP, Custom Editor, Extension). The unit of evolution is the kernel — small, stable, owned under strong agreement, the way DDD prescribes. Every later article points back to this sentence when it claims a boundary is or is not justified.

Why publish the decomposition before either the build or the code

Three reasons, in increasing strategic weight.

The first is that meta-ide-dsl already paid the price of starting from the smallest viable design. Its prototype, requirements-ide.spec.ts, is honest about what it is — one class, all decorators — and honest about what it is not — a layered architecture. Writing the next series, ide-dsl/, as a fifteen-article build-in-public before pinning the architectural decomposition would have meant either (a) the build series rediscovers the decomposition mid-flight and refactors loudly, or (b) it ships the monolithic shape and earns refactoring debt at week one. Neither is acceptable for a public design exercise. The decomposition belongs in its own series so the build series can adopt it as a precondition.

The second is that decomposition is a teaching artefact, not just an architectural one. Each micro-DSL chapter exposes the same eight-section anatomy — Concern, the Surface, Kernel boundary, Emitted artefacts, Composition with peers, MPS aspect referent, Boundary justification, Requirements. Reading fourteen of them in sequence makes the shape habitual. By article 19 the reader can sketch a fifteenth micro-DSL — say, an intentions micro-DSL after MPS's intentions aspect, or a typesystem micro-DSL after MPS's type system aspect — without prompting. That is the point. The series teaches a pattern, instantiated fourteen times, not a finished catalogue.

The third is positional, against the rest of the FrenchExDev corpus. Métacratie / Compilateur argues a zoo of small DSLs is the right response to regulatory complexity. CMF Design argues the same for full-stack content management. The IDE side of that argument has so far been carried by meta-ide-dsl alone, treating IDE-tooling as a single block. This series widens the move: IDE-tooling is itself a zoo, with its own kernel and its own composition rules, and the same meta posture (one spec, many emitted artefacts, no hand-written plumbing) extends from one DSL per editor to N micro-DSLs per editor. The recursion is intentional — Ide.Dsl is itself one such Ide.Dsl.

How to read this series

Twenty-two articles split across four parts. The parts are designed so that a reader can stop after Part II and walk away with the architectural pattern; a reader who continues into Part III gets fourteen worked instances; a reader who reads through Part IV sees the suite composed end-to-end on the requirements-DSL example.

Each article number corresponds to one FEAT-MICRODSL-NN Feature declared in assets/features.ts. The series dog-foods the same Requirements DSL described in cmf-design article 13 and used by meta-ide-dsl.

Part I — The Pattern (3 articles)

  1. Why one DSL doesn't scale: the case for decomposition. The single-class spec from meta-ide-dsl as counterexample; concern coupling failure modes; the decomposition thesis.
  2. The shared kernel: DDD applied to an IDE suite. Evans' shared-kernel definition recalled; inclusion criteria; the god-object anti-pattern; what stays, what doesn't.
  3. Bounded contexts in VSCode: anti-corruption, ports, composition rules. Each micro-DSL as a bounded context; anti-corruption layer at the kernel boundary; dependency direction rules; how hosts compose without coupling.

Part II — The Kernel (2 articles)

  1. The kernel M2: @Concept, @Property, @ChildLink, @ReferenceLink. The four decorators that shape the metamodel; concept hierarchy and abstractness; constraints as validator seed; references vs. child links.
  2. The kernel runtime: PatchBus, AST, Banner, EditLog. PatchBus as single mutation path; node identity stability; Banner's idempotence pattern lifted from @frenchexdev/ts-codegen-pipeline; EditLog telemetry scoped local-only.

Part III — The fourteen micro-DSLs (14 articles, common anatomy)

  1. Language micro-DSL. Identity: id, scopeName, extensions, comments, brackets — the language's carte d'identité.
  2. Syntax micro-DSL. Tokens, scopes, tmLanguage, semantic tokens — declarative highlighting from the M2.
  3. Completion micro-DSL. Triggers, item providers, context-aware items derived from the kernel index.
  4. Snippets micro-DSL. Prefix, body, scope, parametric placeholders — contributes.snippets from a typed surface.
  5. Hover micro-DSL. Patterns, content providers, cross-file resolution via the kernel AST.
  6. Diagnostics micro-DSL. Validators auto-derived from @Property({constraint}), severity, code actions as repair lambdas.
  7. CodeLens micro-DSL. Anchors, commands, dynamic counts driven by kernel queries.
  8. Commands micro-DSL. Id, title, when-clauses, keybindings, palette integration.
  9. Views micro-DSL. Tree views, view locations, view containers — refresh semantics from the kernel EditLog.
  10. Formatter micro-DSL. Per-Concept rules, deterministic pretty-printing, the link to projection-text round-trip.
  11. Symbols micro-DSL. Outline derived from @ChildLink cardinality, breadcrumbs, workspace symbol index.
  12. Refactoring micro-DSL. Rename, extract, inline — semantically safe transformations through PatchBus.
  13. Projection micro-DSL. Bindings Concept → render kind (text, table, diagram, form); text as first-class projection — the one bet that distinguishes the suite from MPS.
  14. Generator micro-DSL. Concept → output via @frenchexdev/ts-codegen-pipeline; why ts-morph + tagged templates replace MPS's $/$$ macros.

Part IV — Hosts and composition (3 articles)

  1. The LSP host: composing micro-DSLs server-side. The aggregation contract; why the host depends on no concrete micro-DSL; handler routing from a registry of micro-DSL contributions; performance characterisation of fan-out.
  2. The Custom Editor host: composing projections client-side (React/Vite). WebView bootstrap with Vite; React projection renderer architecture; the PatchBus bridge across the WebView boundary.
  3. Composing the Requirements IDE: case study end-to-end. The minimal compose list (six micro-DSLs around the kernel); the walk-through from Feature Concept to running VSCode extension; bridge back to meta-ide-dsl article 07 and forward to ide-dsl article 01.

Reading paths

  • If you want the pattern only: 01 → 02 → 03 → 22 reads as a 12 000-word essay on how to decompose an IDE meta-DSL with DDD discipline, with one worked composition at the end.
  • If you want the kernel design: 02 → 04 → 05 → any one micro-DSL chapter is the shortest path through the load-bearing parts.
  • If you want one micro-DSL deep-dive: pick any of 06–19 — they are designed to stand alone, each cross-linking to the kernel chapters and to the relevant MPS aspect.
  • If you are here for the projectional editing claim: 18 → 21 → 22, plus 02–03 for the kernel context, is the projection thread.
  • If you came from meta-ide-dsl: read article 01 first (it is the explicit bridge) and then jump to the chapter that addresses the decorator family from RequirementsIde you wanted to extract.

None of these paths is a "short" version. Each is dense, each holds the same register as meta-ide-dsl. The series totals roughly 50 000 words.

Five pillars × twenty-two articles

Every article surfaces five pillars at least once: DDD discipline, SOLID at the package boundary, DRY through kernel ownership, dog-fooding the Requirements DSL, and engagement with MPS (which aspect is being mirrored, what is kept, what is rejected). The matrix is large enough to live in assets/pillars-matrix.md (TODO — generated alongside the articles). The pillars are not a checklist; they are the cross-reference grid the reader uses to jump straight to the section that matters to them.

What you will not find here

  • Implementation code for the kernel or any micro-DSL. This is design-in-public. The Requirements assets in assets/features.ts are the only TypeScript that type-checks. Per packages/ts-codegen-pipeline is referenced as an existing dependency but not modified.
  • A published VSCode extension. The series describes the composition; ide-dsl/ will describe the build; a future packages-side project would ship the artefact.
  • A working WebView. Article 21 describes the host's architecture; concrete React components and Vite bundling stay in the build series.
  • A new ontology layer. The kernel reuses the M2 vocabulary established in cmf-design and in MPS, with one TypeScript-shaped spelling.

Related reading

⬇ Download