How objectionary/eoc works
1. This repository is a Node.js-based command-line toolkit for EO. Its main role is orchestration: it does not implement the EO language itself, but coordinates parsing, compilation, packaging, testing, and documentation workflows around EO sources.
2. The top-level runtime entrypoint is in src/eoc.js, with shared support code in src/version.js, src/parser-version.js, src/elapsed.js, src/tinted-console.js, src/demand.js, and src/files.js. These utilities handle CLI behavior, versioning, logging, timing, argument validation, and filesystem work.
3. The core architecture is command-driven. src/commands/ contains one module per subcommand, so the CLI is split into small execution units such as parse, assemble, resolve, transpile, compile, link, dataize, test, lint, clean, docs, latex, print, register, foreign, normalize, and generate_comments.
4. The main EO pipeline is staged and file-based:
EO source files are discovered/registered, parsed into XMIR, optionally assembled and optimized, dependencies are resolved, XMIR is transpiled to a target language, that target is compiled to binaries, binaries are linked, and then objects are dataized or tested. The repository is clearly organized around these intermediate artifacts, especially EO source, XMIR, generated source code, and compiled outputs.
5. There are two backend families under src/commands/java/ and src/commands/js/. They mirror the same pipeline concepts but target different runtimes/toolchains. This indicates the project is not a single compiler, but a front-end that can drive multiple execution backends.
6. The jeo subcommands are a separate interoperability boundary. src/commands/jeo/assemble.js and src/commands/jeo/disassemble.js convert between Java .class files and XMIR, relying on the external jeo-maven-plugin. This is an important bridge between the EO ecosystem and Java bytecode.
7. Several commands are analysis or source-transformation tools rather than build steps. lint, fmt, normalize, foreign, audit, docs, latex, print, and generate_comments work on EO/XMIR and the repository’s generated artifacts. normalize explicitly depends on an external phino tool, so it is another external-process boundary.
8. Java execution is mediated through local tooling wrappers. The presence of src/jdk.js, src/mvnw.js, mvnw/, and Maven wrapper metadata shows that the CLI shells out to a managed Java toolchain instead of embedding a compiler/runtime. That makes Java availability a runtime dependency of the architecture.
9. The repository also contains packaging and distribution definitions that sit outside the runtime flow: Homebrew formulas in Formula/, a Nix flake (flake.nix/flake.lock), and npm packaging scripts. The README confirms the tool can be installed via npm, Homebrew, or Nix, so deployment is multi-channel but still centered on the same CLI.
10. Test structure mirrors the command layout. test/commands/ contains focused unit/integration coverage for each command family, while itest/ contains EO programs used for end-to-end scenarios. The tests validate the command pipeline and the generated artifacts rather than only internal functions.
11. Tooling and quality gates are part of the repo architecture. Grunt is the main task runner, ESLint is used for JS linting, and there is a custom ESLint plugin in eslintPlugin/. The .github/workflows/ directory shows separate CI jobs for linting, tests, typos, markdown, shell scripts, YAML, and release/package maintenance.
12. A notable filesystem boundary is the src/resources/ directory, which includes xmir-transformer.xsl. That suggests some transformations are template/XSL-based rather than purely JavaScript logic, reinforcing that the CLI is an orchestration layer over multiple transformation technologies.
13. In diagram terms, the central node is the CLI dispatcher in src/eoc.js, feeding into command modules. From there, the dominant data flow is EO source files to XMIR, then to language-specific outputs, then to binaries and runtime dataization. Secondary flows handle docs, formatting, cataloging, and repository maintenance.
Main entry points: commands Commands · js JS backend · java Java backend · transpile.js Transpile
Components 23
CLI core
Entry point and shared command-line support
- eoc.js · Top-level dispatcher for the command-line tool
src/eoc.js - Shared utils · Versioning, logging, timing, validation, and filesystem helpers
Pipeline
EO source to runtime artifact flow
- Commands · Top-level command modules for parsing, building, docs, and maintenance
src/commands - Parse · Parses EO sources into XMIR
src/commands/parse.js - Register · Discovers and registers EO sources
src/commands/register.js - Assemble · Builds or transforms XMIR during the EO pipeline
src/commands/assemble.js - Resolve · Resolves dependencies in the XMIR-based pipeline
src/commands/java/resolve.js - Transpile · Converts XMIR into target-language source code
src/commands/java/transpile.js - Compile · Compiles generated source into executables or class files
src/commands/java/compile.js - Link · Links compiled artifacts into runnable outputs
src/commands/java/link.js - Dataize · Runs EO objects and extracts results
src/commands/java/dataize.js - Test · Exercises the staged build and runtime flow
src/commands/java/test.js
Backends
Runtime-specific command families
- JS backend · JavaScript-targeted pipeline implementation
src/commands/js - Java backend · Java-targeted pipeline implementation
src/commands/java
Interop
Bridges to external toolchains and bytecode
- JEo bridge · Converts between Java class files and XMIR
src/commands/jeo - Java wrappers · Managed wrappers around JDK and Maven tooling
src/jdk.js - XSL resources · Template and transformation assets such as xmir-transformer.xsl
src/resources/xmir-transformer.xsl
Tooling
Repository maintenance and quality gates
- Maintenance · Linting, formatting, docs, normalization, and cleanup commands
src/commands - ESLint plugin · Custom lint rules for repository-specific JavaScript checks
eslintPlugin/index.js - CI workflows · GitHub Actions jobs for lint, tests, release, and hygiene
.github/workflows
Tests
Command and integration coverage
- Command tests · Focused tests for command modules and pipeline behavior
test/commands - EO scenarios · End-to-end EO programs used for integration testing
itest
Distribution
Packaging and release definitions
- Packaging · Homebrew, Nix, npm, and release packaging definitions
Formula
Connections 33
- eoc.js → Shared utils: uses · Dispatcher relies on shared CLI utilities
- eoc.js → Commands: dispatches · Routes subcommands to command modules
- Commands → Parse: includes · Command registry includes parse
- Commands → Register: includes · Command registry includes register
- Commands → Assemble: includes · Command registry includes assemble
- Commands → Resolve: includes · Command registry includes resolve
- Commands → Transpile: includes · Command registry includes transpile
- Commands → Compile: includes · Command registry includes compile
- Commands → Link: includes · Command registry includes link
- Commands → Dataize: includes · Command registry includes dataize
- Commands → Test: includes · Command registry includes test
- Java backend → Resolve: implements · Java backend provides resolve stage
- Java backend → Transpile: implements · Java backend provides transpile stage
- Java backend → Compile: implements · Java backend provides compile stage
- Java backend → Link: implements · Java backend provides link stage
- Java backend → Dataize: implements · Java backend provides dataize stage
- Java backend → Test: implements · Java backend provides test stage
- JS backend → Resolve: implements · JS backend mirrors resolve stage
- JS backend → Transpile: implements · JS backend mirrors transpile stage
- JS backend → Compile: implements · JS backend mirrors compile stage
- JS backend → Link: implements · JS backend mirrors link stage
- JS backend → Dataize: implements · JS backend mirrors dataize stage
- JS backend → Test: implements · JS backend mirrors test stage
- JEo bridge → Java wrappers: uses · JEo bridge shells out through managed Java tooling
- JEo bridge → Assemble: bridges · Converts class files into XMIR via assembly
- JEo bridge → Transpile: bridges · Connects bytecode world back to EO compilation flow
- Maintenance → XSL resources: uses · Maintenance commands consume transformation resources
- Maintenance → ESLint plugin: uses · Lint command set is extended by custom rules
- CI workflows → Command tests: runs · CI executes command-level test suites
- CI workflows → Packaging: checks · CI covers packaging and release hygiene
- Command tests → Commands: covers · Tests validate the command-driven architecture
- EO scenarios → Test: exercises · EO scenarios drive end-to-end testing
- Packaging → eoc.js: distributes · Packaging centers on the CLI entrypoint