# objectionary/eoc architecture

> Architecture diagram of the GitHub repository objectionary/eoc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/objectionary/eoc
- Repository: https://github.com/objectionary/eoc

## Overview

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: [`src/commands`](https://github.com/objectionary/eoc/tree/master/src/commands) (Commands), [`src/commands/js`](https://github.com/objectionary/eoc/tree/master/src/commands/js) (JS backend), [`src/commands/java`](https://github.com/objectionary/eoc/tree/master/src/commands/java) (Java backend), [`src/commands/java/transpile.js`](https://github.com/objectionary/eoc/blob/master/src/commands/java/transpile.js) (Transpile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI core"]
  node_src_eoc["eoc.js<br/>CLI entrypoint<br/>[eoc.js]"]
  node_src_shared["Shared utils<br/>CLI support"]
end

subgraph group_pipeline["Pipeline"]
  node_cmd_root["Commands<br/>subcommand set"]
  node_cmd_parse["Parse<br/>EO ingest<br/>[parse.js]"]
  node_cmd_register["Register<br/>EO catalog<br/>[register.js]"]
  node_cmd_assemble["Assemble<br/>XMIR transform<br/>[assemble.js]"]
  node_cmd_resolve["Resolve<br/>dependency stage<br/>[resolve.js]"]
  node_cmd_transpile["Transpile<br/>codegen stage<br/>[transpile.js]"]
  node_cmd_compile["Compile<br/>binary stage<br/>[compile.js]"]
  node_cmd_link["Link<br/>packaging stage<br/>[link.js]"]
  node_cmd_dataize["Dataize<br/>runtime exec<br/>[dataize.js]"]
  node_cmd_test["Test<br/>pipeline check<br/>[test.js]"]
end

subgraph group_backends["Backends"]
  node_cmd_js["JS backend<br/>runtime family"]
  node_cmd_java["Java backend<br/>runtime family"]
end

subgraph group_interop["Interop"]
  node_cmd_jeo["JEo bridge<br/>bytecode bridge"]
  node_src_java_tools["Java wrappers<br/>external toolchain<br/>[jdk.js]"]
  node_src_resources["XSL resources<br/>transform assets"]
end

subgraph group_tooling["Tooling"]
  node_src_maintenance["Maintenance<br/>repo tools"]
  node_eslint_plugin["ESLint plugin<br/>lint extension<br/>[index.js]"]
  node_ci["CI workflows<br/>automation<br/>[workflows]"]
end

subgraph group_tests["Tests"]
  node_tests_cmd["Command tests<br/>test suite"]
  node_tests_itest["EO scenarios<br/>integration suite"]
end

subgraph group_distribution["Distribution"]
  node_pkg["Packaging<br/>distribution"]
end

node_src_eoc -->|"uses"| node_src_shared
node_src_eoc -->|"dispatches"| node_cmd_root
node_cmd_root -->|"includes"| node_cmd_parse
node_cmd_root -->|"includes"| node_cmd_register
node_cmd_root -->|"includes"| node_cmd_assemble
node_cmd_root -->|"includes"| node_cmd_resolve
node_cmd_root -->|"includes"| node_cmd_transpile
node_cmd_root -->|"includes"| node_cmd_compile
node_cmd_root -->|"includes"| node_cmd_link
node_cmd_root -->|"includes"| node_cmd_dataize
node_cmd_root -->|"includes"| node_cmd_test
node_cmd_java -->|"implements"| node_cmd_resolve
node_cmd_java -->|"implements"| node_cmd_transpile
node_cmd_java -->|"implements"| node_cmd_compile
node_cmd_java -->|"implements"| node_cmd_link
node_cmd_java -->|"implements"| node_cmd_dataize
node_cmd_java -->|"implements"| node_cmd_test
node_cmd_js -->|"implements"| node_cmd_resolve
node_cmd_js -->|"implements"| node_cmd_transpile
node_cmd_js -->|"implements"| node_cmd_compile
node_cmd_js -->|"implements"| node_cmd_link
node_cmd_js -->|"implements"| node_cmd_dataize
node_cmd_js -->|"implements"| node_cmd_test
node_cmd_jeo -->|"uses"| node_src_java_tools
node_cmd_jeo -->|"bridges"| node_cmd_assemble
node_cmd_jeo -->|"bridges"| node_cmd_transpile
node_src_maintenance -->|"uses"| node_src_resources
node_src_maintenance -->|"uses"| node_eslint_plugin
node_ci -->|"runs"| node_tests_cmd
node_ci -.->|"checks"| node_pkg
node_tests_cmd -->|"covers"| node_cmd_root
node_tests_itest -->|"exercises"| node_cmd_test
node_pkg -.->|"distributes"| node_src_eoc

click node_src_eoc "https://github.com/objectionary/eoc/blob/master/src/eoc.js"
click node_cmd_root "https://github.com/objectionary/eoc/tree/master/src/commands"
click node_cmd_parse "https://github.com/objectionary/eoc/blob/master/src/commands/parse.js"
click node_cmd_register "https://github.com/objectionary/eoc/blob/master/src/commands/register.js"
click node_cmd_assemble "https://github.com/objectionary/eoc/blob/master/src/commands/assemble.js"
click node_cmd_resolve "https://github.com/objectionary/eoc/blob/master/src/commands/java/resolve.js"
click node_cmd_transpile "https://github.com/objectionary/eoc/blob/master/src/commands/java/transpile.js"
click node_cmd_compile "https://github.com/objectionary/eoc/blob/master/src/commands/java/compile.js"
click node_cmd_link "https://github.com/objectionary/eoc/blob/master/src/commands/java/link.js"
click node_cmd_dataize "https://github.com/objectionary/eoc/blob/master/src/commands/java/dataize.js"
click node_cmd_test "https://github.com/objectionary/eoc/blob/master/src/commands/java/test.js"
click node_cmd_js "https://github.com/objectionary/eoc/tree/master/src/commands/js"
click node_cmd_java "https://github.com/objectionary/eoc/tree/master/src/commands/java"
click node_cmd_jeo "https://github.com/objectionary/eoc/tree/master/src/commands/jeo"
click node_src_java_tools "https://github.com/objectionary/eoc/blob/master/src/jdk.js"
click node_src_resources "https://github.com/objectionary/eoc/blob/master/src/resources/xmir-transformer.xsl"
click node_src_maintenance "https://github.com/objectionary/eoc/tree/master/src/commands"
click node_eslint_plugin "https://github.com/objectionary/eoc/blob/master/eslintPlugin/index.js"
click node_ci "https://github.com/objectionary/eoc/blob/master/.github/workflows"
click node_tests_cmd "https://github.com/objectionary/eoc/tree/master/test/commands"
click node_tests_itest "https://github.com/objectionary/eoc/tree/master/itest"
click node_pkg "https://github.com/objectionary/eoc/tree/master/Formula"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_eoc,node_src_shared,node_pkg toneBlue
class node_cmd_root,node_cmd_parse,node_cmd_register,node_cmd_assemble,node_cmd_resolve,node_cmd_transpile,node_cmd_compile,node_cmd_link,node_cmd_dataize,node_cmd_test toneAmber
class node_cmd_js,node_cmd_java toneMint
class node_cmd_jeo,node_src_java_tools,node_src_resources toneRose
class node_src_maintenance,node_eslint_plugin,node_ci toneIndigo
class node_tests_cmd,node_tests_itest toneTeal
```

## Components

### CLI core

Entry point and shared command-line support

- [eoc.js](https://github.com/objectionary/eoc/blob/master/src/eoc.js): CLI entrypoint · Top-level dispatcher for the command-line tool · `src/eoc.js`
- **Shared utils**: CLI support · Versioning, logging, timing, validation, and filesystem helpers

### Pipeline

EO source to runtime artifact flow

- [Commands](https://github.com/objectionary/eoc/tree/master/src/commands): subcommand set · Top-level command modules for parsing, building, docs, and maintenance · `src/commands`
- [Parse](https://github.com/objectionary/eoc/blob/master/src/commands/parse.js): EO ingest · Parses EO sources into XMIR · `src/commands/parse.js`
- [Register](https://github.com/objectionary/eoc/blob/master/src/commands/register.js): EO catalog · Discovers and registers EO sources · `src/commands/register.js`
- [Assemble](https://github.com/objectionary/eoc/blob/master/src/commands/assemble.js): XMIR transform · Builds or transforms XMIR during the EO pipeline · `src/commands/assemble.js`
- [Resolve](https://github.com/objectionary/eoc/blob/master/src/commands/java/resolve.js): dependency stage · Resolves dependencies in the XMIR-based pipeline · `src/commands/java/resolve.js`
- [Transpile](https://github.com/objectionary/eoc/blob/master/src/commands/java/transpile.js): codegen stage · Converts XMIR into target-language source code · `src/commands/java/transpile.js`
- [Compile](https://github.com/objectionary/eoc/blob/master/src/commands/java/compile.js): binary stage · Compiles generated source into executables or class files · `src/commands/java/compile.js`
- [Link](https://github.com/objectionary/eoc/blob/master/src/commands/java/link.js): packaging stage · Links compiled artifacts into runnable outputs · `src/commands/java/link.js`
- [Dataize](https://github.com/objectionary/eoc/blob/master/src/commands/java/dataize.js): runtime exec · Runs EO objects and extracts results · `src/commands/java/dataize.js`
- [Test](https://github.com/objectionary/eoc/blob/master/src/commands/java/test.js): pipeline check · Exercises the staged build and runtime flow · `src/commands/java/test.js`

### Backends

Runtime-specific command families

- [JS backend](https://github.com/objectionary/eoc/tree/master/src/commands/js): runtime family · JavaScript-targeted pipeline implementation · `src/commands/js`
- [Java backend](https://github.com/objectionary/eoc/tree/master/src/commands/java): runtime family · Java-targeted pipeline implementation · `src/commands/java`

### Interop

Bridges to external toolchains and bytecode

- [JEo bridge](https://github.com/objectionary/eoc/tree/master/src/commands/jeo): bytecode bridge · Converts between Java class files and XMIR · `src/commands/jeo`
- [Java wrappers](https://github.com/objectionary/eoc/blob/master/src/jdk.js): external toolchain · Managed wrappers around JDK and Maven tooling · `src/jdk.js`
- [XSL resources](https://github.com/objectionary/eoc/blob/master/src/resources/xmir-transformer.xsl): transform assets · Template and transformation assets such as xmir-transformer.xsl · `src/resources/xmir-transformer.xsl`

### Tooling

Repository maintenance and quality gates

- [Maintenance](https://github.com/objectionary/eoc/tree/master/src/commands): repo tools · Linting, formatting, docs, normalization, and cleanup commands · `src/commands`
- [ESLint plugin](https://github.com/objectionary/eoc/blob/master/eslintPlugin/index.js): lint extension · Custom lint rules for repository-specific JavaScript checks · `eslintPlugin/index.js`
- [CI workflows](https://github.com/objectionary/eoc/blob/master/.github/workflows): automation · GitHub Actions jobs for lint, tests, release, and hygiene · `.github/workflows`

### Tests

Command and integration coverage

- [Command tests](https://github.com/objectionary/eoc/tree/master/test/commands): test suite · Focused tests for command modules and pipeline behavior · `test/commands`
- [EO scenarios](https://github.com/objectionary/eoc/tree/master/itest): integration suite · End-to-end EO programs used for integration testing · `itest`

### Distribution

Packaging and release definitions

- [Packaging](https://github.com/objectionary/eoc/tree/master/Formula): distribution · Homebrew, Nix, npm, and release packaging definitions · `Formula`

## Connections

- 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
