How minirang/jeomlang works
1. What this repo is
- This is a small language ecosystem centered on Jeom: a language/runtime implementation, its standard library, examples, docs, and a couple of browser-based surfaces for running or presenting it.
- The architecture is split between the execution core and multiple tooling/UI layers that consume that core.
2. Core runtime
- core/engine.js is the main execution engine for Jeom.
- core/cli.js is the command-line entry point that wraps the engine and exposes it to local users.
- This is the primary backend boundary: source programs flow into the engine, and results/errors come back out through the CLI or other consumers.
3. Language standard library and sample programs
- stdlib/std.jeom is the built-in standard library shipped with the language.
- examples/*.jeom are canonical programs demonstrating syntax and runtime behavior (calculator, factorial, Fibonacci, Hanoi, etc.).
- These files show the expected input format for the engine and act as integration smoke tests for language features.
4. Specification and documentation
- docs/SPEC.md is the authoritative language specification.
- docs/CHANGELOG.md tracks user-visible release changes.
- GRAMMAR.md likely describes the parsing grammar, making it a key artifact for understanding language syntax and parser boundaries.
5. Browser IDE
- ide/src/ide.ts is the TypeScript source for the in-browser IDE.
- ide/dist/ide.js is the built client bundle, while ide/index.html and ide/ide.css provide the shell and styling.
- This subsystem is a separate frontend boundary that likely lets users edit/run Jeom code without the CLI.
6. Public homepage / landing site
- home/index.html, home/index.js, and home/style.css make up a lightweight static site.
- assets/img contains shared imagery used by the public-facing pages.
- This is presentation-only and separate from the language runtime and IDE.
7. Shared frontend components
- shared/custom-elements.js contains reusable web components or UI primitives shared across browser surfaces.
- This suggests some deliberate front-end reuse between the homepage and IDE, reducing duplication at the UI boundary.
8. Developer tooling
- tools/formatter/formatter.py is a Python-based formatter for Jeom source, indicating language tooling is not limited to JavaScript/TypeScript.
- tools/vscode-extension/ suggests an editor integration exists or is being scaffolded, though the presence of temp implies it may be incomplete or transitional.
- These tools consume the same language syntax/spec as the core runtime but are outside the execution path.
9. Build and deployment
- package.json, tsconfig.json, and the checked-in ide/dist/ide.js indicate a build step for the TypeScript frontend.
- vercel.json suggests at least one static deployment target, likely for the homepage and/or IDE.
- .github/workflows/update-changelog.yml automates release-note maintenance.
10. Repository shape and boundaries
- The repo is intentionally multi-surface: runtime, CLI, docs/spec, examples, web IDE, homepage, and tooling.
- The main data flow is: Jeom source code → core engine/runtime → output/errors, with the same language definition reused by docs, formatter, IDE, and examples.
- In an architecture diagram, the core engine should sit at the center, with the CLI and browser IDE as separate clients, and the standard library/examples/docs/tooling as supporting layers around it.
Main entry points: engine.js Engine · SPEC.md Spec · custom-elements.js Shared UI · GRAMMAR.md Grammar
Components 16
Runtime
Language execution core and entrypoints
Language Spec
Grammar, standard library, and example programs
Browser UI
Web surfaces built around the language
- IDE Source · TypeScript source for the browser IDE
ide/src/ide.ts - IDE Bundle · Built client bundle for the IDE
ide/dist/ide.js - IDE Shell · HTML and CSS shell for the browser IDE
ide/index.html - Homepage · Public landing page and supporting script/style
home/index.html - Shared UI · Reusable browser UI primitives
shared/custom-elements.js
Docs
Project and release documentation
Tooling
Developer and editor integrations
Ops
Build, package, and deployment config
- Changelog CI · GitHub Actions workflow for changelog updates
.github/workflows/update-changelog.yml - Deploy · Deployment configuration for static surfaces
vercel.json
Connections 18
- CLI → Engine: invokes · CLI delegates program execution to the runtime
- Stdlib → Engine: loads · Standard library is executed or imported by the engine
- Examples → Engine: exercises · Example programs are canonical inputs for the runtime
- Grammar → Spec: informs · Grammar is part of the language definition and supports the spec
- Spec → Engine: defines · Specification constrains engine behavior
- Grammar → Engine: parses · Grammar guides parsing and syntax handling in the runtime
- IDE Source → IDE Bundle: builds · TypeScript source compiles into the browser bundle
- IDE Shell → IDE Bundle: hosts · HTML shell loads the built IDE client
- Shared UI → IDE Shell: shared with · Browser UI primitives are reused in the IDE surface
- Shared UI → Homepage: shared with · Reusable components also support the homepage
- IDE Source → Engine: runs code · IDE is a browser-facing client of the runtime
- Homepage → Shared UI: uses · Homepage consumes shared frontend components
- Formatter → Spec: follows · Formatter implements the language rules described by the spec
- Formatter → Grammar: follows · Formatter also depends on syntax structure
- VS Code → Spec: integrates · Editor tooling is aligned with the language definition
- Changelog CI → Changelog: updates · Automation maintains release notes
- Deploy → Homepage: deploys · Static hosting config targets the public site
- Deploy → IDE Shell: deploys · Static hosting config also supports the IDE surface