Skip to content

Commit 36bbd6d

Browse files
NikolaRHristovNikolaRHristov
committed
docs(Output): Complete README rewrite to concise benefit-focused format
Trim README from ~370 lines to ~55 lines. Remove exhaustive technical documentation on Rest compiler integration, build pipeline architecture, comparison tables, troubleshooting guides, and directory structure. Retain only: one-paragraph description, three-item benefits list ("deterministic builds," "plugin-routed architecture," "checksum verification"), development reference, license, and See Also links. Continues the benefit-focused rewrite from previous commit, matching the website's outcome-oriented direction.
1 parent 9148bc0 commit 36bbd6d

1 file changed

Lines changed: 21 additions & 337 deletions

File tree

‎README.md‎

Lines changed: 21 additions & 337 deletions
Original file line numberDiff line numberDiff line change
@@ -33,371 +33,55 @@ Land
3333
</tr>
3434
</table>
3535

36-
---
37-
38-
# **Output** ⚫
39-
40-
The Build Output & Artifact Management for Land 🏞️
41-
42-
[![License: CC0-1.0](https://img.shields.io/badge/License-CC0_1.0-lightgrey.svg)](https://github.com/CodeEditorLand/Land/tree/Current/LICENSE)
43-
[![NPM Version](https://img.shields.io/npm/v/@codeeditorland/output.svg)](https://www.npmjs.com/package/@codeeditorland/output)
44-
[![esbuild Version](https://img.shields.io/badge/esbuild-0.25.x-blue.svg)](https://esbuild.github.io/)
45-
[![Rest Compiler](https://img.shields.io/badge/Rest-OXC-orange.svg)](https://oxc.rs/)
46-
47-
**Output** is the build output and artifact management package for the **Land
48-
Code Editor**. It handles compilation, processing, and distribution of source
49-
code from VSCode, CodeEditorLand Editor, and the Rest compiler pipeline.
50-
51-
**What Output gives you:**
52-
53-
1. **Two compilers, one pipeline.** Both esbuild and Rest (OXC) produce
54-
artifacts through the same build system. Migrate incrementally.
55-
2. **Ready-to-run bundles.** Sky, Wind, and Cocoon consume Output's JavaScript
56-
artifacts directly. No post-processing, no manual wiring.
57-
3. **Incremental migration.** Switch individual modules from esbuild to Rest
58-
one at a time. The plugin architecture handles the routing.
59-
4. **Reproducible output.** Deterministic build configs and artifact checksums.
60-
Same commit always produces the same bundles.
61-
62-
---
63-
64-
## Key Features 🔐
65-
66-
- **Dual-Compiler Support:** Seamlessly switch between esbuild (default) and
67-
Rest (OXC-powered) compilers via environment variables.
68-
- **Rest Plugin Integration:** Custom esbuild plugin that intercepts TypeScript
69-
compilation and delegates to the Rest compiler.
70-
- **Source Map Generation:** Full support for development source maps with
71-
configurable generation strategies.
72-
- **Artifact Merging:** Intelligent merging of Rest compiler output with esbuild
73-
bundles for hybrid workflows.
74-
- **Verbose Logging:** Comprehensive build diagnostics with configurable
75-
verbosity levels for troubleshooting.
76-
- **Path Override:** Flexible binary path configuration for Rest compiler
77-
discovery in diverse environments.
7836

7937
---
8038

81-
## Core Architecture Principles 🏗️
82-
83-
| Principle | Description | Key Components Involved |
84-
| :---------------- | :-------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------- |
85-
| **Compatibility** | Maintain backward compatibility with esbuild while enabling Rest compiler adoption through plugin architecture. | `Source/ESBuild/RestPlugin.ts`, `Source/prepublishOnly.sh` |
86-
| **Modularity** | Separation of concerns between build orchestration, compiler plugins, and artifact management. | `Source/ESBuild/Output.ts`, `Source/ESBuild/RestPlugin.ts` |
87-
| **Performance** | Leverage Rest's OXC-based compiler for 10-100x speedup on TypeScript transpilation tasks. | Rest compiler integration, parallel processing |
88-
| **Flexibility** | Environment-driven configuration enables different build strategies per deployment scenario. | `Compiler` environment variable, `REST_*` variables |
89-
| **Observability** | Comprehensive logging and diagnostics for build process visibility and troubleshooting. | `REST_VERBOSE`, `REST_OPTIONS` configuration |
90-
91-
---
92-
93-
## Rest Compiler Integration ⛱️
94-
95-
The Rest compiler integration enables OXC-based TypeScript compilation as an
96-
alternative or complement to esbuild. This section provides an overview of the
97-
integration architecture, usage patterns, and comparison with esbuild.
98-
99-
### Overview of OXC-Based Compilation 📖
100-
101-
Rest leverages the **OXC (Oxidation Compiler)** ecosystem, a high-performance
102-
JavaScript/TypeScript toolchain written in Rust. The OXC stack provides:
103-
104-
- **`oxc_parser`**: Ultra-fast JavaScript/TypeScript parser with ESTree
105-
compatibility
106-
- **`oxc_transformer`**: AST transformation engine supporting TypeScript, JSX,
107-
and modern ECMAScript features
108-
- **`oxc_codegen`**: Efficient code generation from AST
109-
- **`oxc_semantic`**: Semantic analysis and symbol table construction
110-
111-
When `Compiler=Rest` is configured, the build pipeline intercepts TypeScript
112-
file processing and delegates to the Rest compiler before merging results back
113-
into the esbuild output stream.
114-
115-
### Build Pipeline Architecture
116-
117-
#### Standard Pipeline (esbuild only)
118-
119-
```
120-
Source/ → esbuild → Configuration/ → Target/
121-
```
122-
123-
#### Rest Compiler Pipeline (hybrid)
124-
125-
```
126-
Source/ → esbuild → Configuration/ → Target/
127-
Dependency/ → Rest → Target/Rest/ → Configuration/ → Target/
128-
```
129-
130-
### Usage Instructions 🚀
131-
132-
#### Enabling Rest Compiler
133-
134-
Set the `Compiler` environment variable to `Rest` before invoking the build:
135-
136-
```bash
137-
# Use Rest compiler for TypeScript transpilation
138-
export Compiler=Rest
139-
npm run prepublishOnly
140-
```
141-
142-
#### Development Mode with Rest
143-
144-
```bash
145-
export NODE_ENV=development
146-
export Compiler=Rest
147-
npm run Run
148-
```
149-
150-
#### Production Build with Rest
151-
152-
```bash
153-
export NODE_ENV=production
154-
export Compiler=Rest
155-
npm run prepublishOnly
156-
```
157-
158-
### Build Output Location
159-
160-
Rest compiler output is placed in the following location before being processed:
161-
162-
```
163-
Target/Rest/Microsoft/VSCode/
164-
```
165-
166-
After Rest processing, artifacts are merged into the final output at:
167-
168-
```
169-
Target/Microsoft/VSCode/
170-
```
171-
172-
### Configuration Options
173-
174-
| Variable | Default | Description |
175-
| :----------------- | :----------------- | :------------------------------------------------ |
176-
| `Compiler` | `esbuild` | Compiler to use (`esbuild` or `Rest`) |
177-
| `REST_BINARY_PATH` | auto-detect | Override Rest binary location |
178-
| `REST_OPTIONS` | empty | Additional Rest compiler flags |
179-
| `REST_VERBOSE` | `false` | Enable verbose Rest logging |
180-
| `Dependency` | `Microsoft/VSCode` | Source dependency to process |
181-
| `NODE_ENV` | `production` | Build environment (`development` or `production`) |
182-
183-
### Rest Compiler Comparison: esbuild vs Rest
184-
185-
| Feature | esbuild | Rest (OXC) |
186-
| :--------------------- | :---------------------- | :------------------------- |
187-
| **Implementation** | Go-based | Rust-based (OXC) |
188-
| **TypeScript Support** | Full | Full |
189-
| **Speed** | Very Fast (10-100x tsc) | Ultra-Fast (parallel, OXC) |
190-
| **Source Maps** | Yes | Yes |
191-
| **Tree Shaking** | Yes | Yes |
192-
| **Plugin System** | Rich ecosystem | Emerging |
193-
| **Best For** | General bundling | TypeScript-heavy projects |
194-
| **Watch Mode** | Yes | Yes (via notify) |
195-
| **Minification** | Yes | Yes (oxc_minifier) |
196-
197-
### Decision Matrix: When to Use Rest
198-
199-
> [!NOTE] Use Rest compiler when:
200-
>
201-
> - Your project has heavy TypeScript usage
202-
> - You need maximum build performance
203-
> - You want to leverage OXC's semantic analysis
204-
> - You're building for production with minification requirements
205-
206-
> [!TODO] Consider esbuild when:
207-
>
208-
> - You rely on specific esbuild plugins
209-
> - Your project is primarily JavaScript
210-
> - You need mature plugin ecosystem support
211-
> - Build speed is less critical than compatibility
212-
213-
### Troubleshooting Rest Compiler 🔍
214-
215-
#### Rest Binary Not Found
216-
217-
Set `REST_BINARY_PATH` to the location of the Rest binary:
218-
219-
```bash
220-
export REST_BINARY_PATH=/usr/local/bin/rest
221-
```
39+
# **Output**&#x2001;⚫
22240

223-
#### Compilation Errors
41+
> **Build processes that produce different artifacts depending on the machine, CI environment, or implicit tool versions make debugging production issues impossible.**
22442
225-
Enable verbose logging for detailed Rest compiler output:
43+
_"Same commit. Same output. Every time."_
22644

227-
```bash
228-
export REST_VERBOSE=true
229-
```
230-
231-
#### Source Maps Not Generated
232-
233-
Ensure development mode or explicit source map configuration:
234-
235-
```bash
236-
export NODE_ENV=development
237-
```
238-
239-
---
240-
241-
## Compilation Pipeline
242-
243-
### Standard Pipeline (esbuild)
244-
245-
```
246-
Source/ → esbuild → Configuration/ → Target/
247-
```
248-
249-
### Rest Compiler Pipeline
250-
251-
When using the Rest compiler (`Compiler=Rest`), an additional stage is added:
252-
253-
```
254-
Source/ → esbuild → Configuration/ → Target/
255-
Dependency/ → Rest → Target/Rest/ → Configuration/ → Target/
256-
```
257-
258-
---
259-
260-
## Directory Structure 📁
261-
262-
```
263-
Element/Output/
264-
├── Source/
265-
│ ├── ESBuild/
266-
│ │ ├── Output.ts # ESBuild configuration
267-
│ │ └── RestPlugin.ts # Rest compiler plugin
268-
│ ├── prepublishOnly.sh # Build orchestration
269-
│ └── Run.sh # Development watch script
270-
├── Configuration/
271-
│ └── ESBuild/
272-
│ ├── Microsoft/VSCode.js
273-
│ └── CodeEditorLand/Editor.js
274-
├── Target/
275-
│ ├── Rest/ # Rest compiler output (when Compiler=Rest)
276-
│ │ └── Microsoft/
277-
│ │ └── VSCode/
278-
│ └── Microsoft/ # Final merged output
279-
│ └── VSCode/
280-
└── package.json
281-
```
282-
283-
---
284-
285-
## Scripts 📝
286-
287-
| Script | Description |
288-
| :----------------------- | :------------------------------ |
289-
| `npm run prepublishOnly` | Run full build process |
290-
| `npm run Run` | Run in watch mode (development) |
291-
292-
---
293-
294-
## Architecture
295-
296-
### ESBuild Configuration
297-
298-
[`Source/ESBuild/Output.ts`](https://github.com/CodeEditorLand/Output/tree/Current/Source/ESBuild/Output.ts)
299-
configures esbuild with:
300-
301-
- ESM format output
302-
- Node.js platform
303-
- ES Next target
304-
- Conditional Rest plugin integration
305-
306-
### Rest Plugin
307-
308-
[`Source/ESBuild/RestPlugin.ts`](https://github.com/CodeEditorLand/Output/tree/Current/Source/ESBuild/RestPlugin.ts)
309-
provides:
310-
311-
- TypeScript file interception
312-
- Rest compiler invocation
313-
- Source map generation (when enabled)
314-
- Fallback to esbuild on errors
315-
316-
---
317-
318-
## Getting Started 🚀
319-
320-
### Installation 📥
321-
322-
```sh
323-
pnpm add @codeeditorland/output
324-
```
325-
326-
### Basic Usage 🚀
327-
328-
```bash
329-
# Default esbuild build
330-
npm run prepublishOnly
331-
332-
# Rest compiler build
333-
export Compiler=Rest
334-
npm run prepublishOnly
335-
```
336-
337-
---
338-
339-
## Development Tools 🔧
340-
341-
This project leverages the **Depth-Aware Skill System** for efficient
342-
development workflows. The system adapts skill behavior based on usage
343-
frequency, providing quick initial checks and progressively more comprehensive
344-
analysis.
345-
346-
### Quick Start with Skills
347-
348-
- **Level 1 (First Run):** Quick scan — fastest execution, focused scope
349-
- **Level 2 (Second Run):** Detailed analysis — broader coverage
350-
- **Level 3 (Third Run):** Deep dive — comprehensive review
351-
- **Level 4 (Fourth+ Run):** Strategic analysis — system-wide patterns
352-
353-
For detailed guidance on using the depth-aware skill system, see:
354-
355-
- [`Documentation/SkillSystem.md`](../../Documentation/SkillSystem.md) —
356-
Complete system overview
357-
- [`.roo/skills/DEPTH-MANAGEMENT.md`](../../.roo/skills/DEPTH-MANAGEMENT.md) —
358-
Technical management guide
359-
360-
### Common Development Tasks
45+
[![License: CC0-1.0](https://img.shields.io/badge/License-CC0_1.0-lightgrey.svg)](https://github.com/CodeEditorLand/Land/tree/Current/LICENSE)
46+
[![NPM Version](https://img.shields.io/npm/v/@codeeditorland/output.svg)](https://www.npmjs.com/package/@codeeditorland/output)
47+
[<img src="https://editor.land/Image/esbuild.svg" width="14" alt="esbuild" />](https://esbuild.github.io/)&#x2001;[![esbuild Version](https://img.shields.io/badge/esbuild-0.25.x-blue.svg)](https://esbuild.github.io/)
48+
[<img src="https://editor.land/Image/OXC.svg" width="14" alt="OXC" />](https://oxc.rs/)&#x2001;[![Rest Compiler](https://img.shields.io/badge/Rest-OXC-orange.svg)](https://oxc.rs/)
36149

362-
| Task | Command | Depth Level |
363-
| --------------------------------- | ------------------------------------ | ----------- |
364-
| Quick build verification | `workflow-check-build-status` | Level 1 |
365-
| Rest compiler integration | `workflow-rest-compiler-integration` | Level 2 |
366-
| Output directory structure review | `history-output-directory-structure` | Level 3 |
367-
| Architecture documentation sync | `knowledge-element-architecture` | Level 4 |
50+
Output processes TypeScript from VS Code, Land, and the Rest compiler into fully bundled artifacts through a plugin-routed architecture. Every bundle is deterministic and checksum-verified. The same commit always produces the same output.
36851

36952
---
37053

371-
## References 📚
54+
## What It Does&#x2001;🔐
37255

373-
- [Rest Compiler Documentation](../Rest/README.md)
374-
- [OXC Documentation](https://oxc.rs/)
375-
- [esbuild Documentation](https://esbuild.github.io/)
56+
- **Deterministic builds.** Same commit always produces the same checksum-verified output.
57+
- **Plugin-routed architecture.** Each source type (VS Code, Land, Rest) takes its own path.
58+
- **Checksum verification.** Every artifact is verified after generation.
37659

37760
---
37861

379-
## License ⚖️
62+
## Development&#x2001;🛠️
38063

381-
This project is licensed under Creative Commons CC0.
382-
383-
See the LICENSE file for details.
64+
Output is a component of the Land workspace. Follow the
65+
[Land Repository](https://github.com/CodeEditorLand/Land) instructions to
66+
build and run.
38467

38568
---
38669

387-
## Changelog 📜
70+
## License&#x2001;⚖️
38871

389-
Stay updated with our progress! See [`CHANGELOG.md`](../../CHANGELOG.md) for a
390-
history of changes specific to **Output**.
72+
CC0 1.0 Universal. Public domain. No restrictions.
73+
[LICENSE](https://github.com/CodeEditorLand/Output/tree/Current/LICENSE)
39174

39275
---
39376

394-
39577
## See Also
39678

79+
- [Output Documentation](https://editor.land/Doc/output)
39780
- [Architecture Overview](https://editor.land/Doc/architecture)
39881
- [Rest](https://github.com/CodeEditorLand/Rest)
39982
- [Cocoon](https://github.com/CodeEditorLand/Cocoon)
40083

84+
40185
## Funding & Acknowledgements 🙏🏻
40286

40387
Code Editor Land is funded through the NGI0 Commons Fund, established by NLnet

0 commit comments

Comments
 (0)