Skip to content

Commit 0dace31

Browse files
NikolaRHristovNikolaRHristov
committed
1 parent 22d2196 commit 0dace31

1 file changed

Lines changed: 128 additions & 0 deletions

File tree

‎Documentation/GitHub/DeepDive.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Output — Deep Dive
2+
3+
This document provides the technical foundation for the Output build artifact
4+
management package within the Land ecosystem. **Output** orchestrates compilation
5+
of VSCode's TypeScript source and CodeEditorLand editor code into JavaScript
6+
bundles consumed by Sky, Wind, and Cocoon.
7+
8+
---
9+
10+
## Architecture
11+
12+
Output is a JavaScript/TypeScript build package that wraps esbuild. It supports
13+
two compiler modes — the default esbuild pipeline and an optional Rest
14+
(OXC-based) pipeline — selectable at build time through environment variables.
15+
16+
```mermaid
17+
graph TB
18+
subgraph "Output — Build Orchestration"
19+
PrepublishSh["prepublishOnly.sh\nBuild entry script"]
20+
RunSh["Run.sh\nDevelopment watch script"]
21+
OutputTS["Source/ESBuild/Output.ts\nesbuild configuration"]
22+
RestPlugin["Source/ESBuild/RestPlugin.ts\nRest compiler plugin"]
23+
end
24+
25+
subgraph "Compiler Paths"
26+
ESBuildPath["esbuild\n(default)"]
27+
RestPath["Rest compiler binary\n(Compiler=Rest)"]
28+
end
29+
30+
subgraph "Source Inputs"
31+
MicrosoftVSCode["Dependency/Microsoft/VSCode/\nVSCode platform source"]
32+
CodeEditorLand["Dependency/CodeEditorLand/Editor/\nEditor customizations"]
33+
end
34+
35+
subgraph "Build Output"
36+
RestIntermediate["Target/Rest/Microsoft/VSCode/\nRest intermediate output"]
37+
FinalTarget["Target/Microsoft/VSCode/\nMerged final artifacts"]
38+
end
39+
40+
PrepublishSh --> OutputTS
41+
OutputTS --> ESBuildPath
42+
OutputTS --> RestPlugin
43+
RestPlugin --> RestPath
44+
MicrosoftVSCode --> ESBuildPath
45+
CodeEditorLand --> ESBuildPath
46+
ESBuildPath --> FinalTarget
47+
RestPath --> RestIntermediate
48+
RestIntermediate --> FinalTarget
49+
```
50+
51+
---
52+
53+
## Key Modules
54+
55+
| Path | Description |
56+
| :--- | :--- |
57+
| `Source/prepublishOnly.sh` | Main build script; sets environment and invokes esbuild configuration |
58+
| `Source/Run.sh` | Development watch script for incremental builds |
59+
| `Source/ESBuild/Output.ts` | esbuild programmatic configuration: format, platform, target, plugin wiring |
60+
| `Source/ESBuild/RestPlugin.ts` | esbuild plugin that intercepts TypeScript files and delegates to Rest binary |
61+
| `Source/ESBuild/Microsoft/` | esbuild entry point configurations for VSCode platform bundles |
62+
| `Source/ESBuild/CodeEditorLand/` | esbuild entry point configurations for editor customization bundles |
63+
| `Source/ESBuild/Exclude/` | Module exclusion rules for platform-incompatible VSCode code paths |
64+
| `Configuration/ESBuild/Microsoft/VSCode.js` | esbuild config for the Microsoft/VSCode dependency |
65+
| `Configuration/ESBuild/CodeEditorLand/Editor.js` | esbuild config for the CodeEditorLand/Editor dependency |
66+
| `Target/Microsoft/VSCode/` | Final merged JavaScript artifacts consumed at runtime |
67+
68+
---
69+
70+
## Data Flow
71+
72+
```mermaid
73+
sequenceDiagram
74+
participant Script as prepublishOnly.sh
75+
participant ESBuild as esbuild
76+
participant RestPlugin as RestPlugin
77+
participant RestBin as Rest Binary
78+
participant Target as Target Directory
79+
80+
Script->>ESBuild: Build(config, plugins=[RestPlugin])
81+
82+
alt Compiler = esbuild (default)
83+
ESBuild->>Target: Write JavaScript bundles directly
84+
else Compiler = Rest
85+
ESBuild->>RestPlugin: onLoad .ts files
86+
RestPlugin->>RestBin: Invoke Rest compiler (subprocess)
87+
RestBin->>RestPlugin: JavaScript text
88+
RestPlugin->>ESBuild: Return transformed source
89+
ESBuild->>Target: Write merged bundles
90+
end
91+
92+
Note over Target: Target/Microsoft/VSCode/\nconsumed by Sky, Wind, Cocoon
93+
```
94+
95+
**Artifact merge sequence (Rest mode):**
96+
97+
1. Rest compiles TypeScript source into `Target/Rest/Microsoft/VSCode/`.
98+
2. esbuild reads Rest output through `RestPlugin` interception.
99+
3. esbuild applies bundling, tree-shaking, and merging.
100+
4. Final artifacts land in `Target/Microsoft/VSCode/`.
101+
102+
---
103+
104+
## Integration Points
105+
106+
| Connecting Element | Direction | Mechanism | Description |
107+
| :--- | :--- | :--- | :--- |
108+
| **Rest** | Consumer | Process invocation | `RestPlugin.ts` spawns the Rest binary as a child process per TypeScript file |
109+
| **Sky** | Provider | `@codeeditorland/output` npm package | Sky imports VSCode core UI components from the Output package artifacts |
110+
| **Wind** | Provider | `@codeeditorland/output` npm package | Wind imports VSCode workbench service implementations from Output artifacts |
111+
| **Cocoon** | Provider | File path reference | Cocoon loads JavaScript modules from `Target/Microsoft/VSCode/` at startup |
112+
113+
---
114+
115+
## Configuration
116+
117+
| Variable | Default | Description |
118+
| :--- | :--- | :--- |
119+
| `Compiler` | `esbuild` | Set to `Rest` to enable OXC-based TypeScript compilation |
120+
| `REST_BINARY_PATH` | auto-detect | Override path to the Rest compiler binary |
121+
| `REST_OPTIONS` | empty | Additional flags passed to the Rest compiler |
122+
| `REST_VERBOSE` | `false` | Enable verbose Rest compiler logging for troubleshooting |
123+
| `Dependency` | `Microsoft/VSCode` | Source dependency directory to process |
124+
| `NODE_ENV` | `production` | Controls source map generation (`development` enables maps) |
125+
126+
The `Compiler=Rest` path produces identical JavaScript semantics to the esbuild
127+
path while running 2-3x faster on TypeScript-heavy codebases, at the cost of
128+
relying on the Rest binary being available in the build environment.

0 commit comments

Comments
 (0)