refactor: rewrite CLI and internal architecture #41

mvhutz · 2026-02-07T03:24:35Z

mvhutz commented

2026-02-07 03:24:35 +00:00

Description

The old architecture used a monolithic main() with a custom arg parser, an event-emitter-based runtime, and a plugin system for optional features.
This PR rewrites the CLI and internal architecture to be modular, extensible, and built around a registry of interchangeable components.

Replace custom CLI arg parsing with Cobra subcommands (convert, reduce, engine list).
Introduce a registry system (internal/registry) for marshalers, codecs, and engines, with BFS-based conversion path resolution.
Add type-erased adapter layer (internal/cli) with Repr, Engine, Process, Marshaler, and Conversion interfaces wrapping generic pkg/ types.
Replace the event-emitter-based Runtime with a simpler Engine/Process model (pkg/engine).
Add generic Codec[T, U] and Marshaler[T] interfaces (pkg/codec).
Merge saccharine/token sub-package into saccharine and rename scanner functions from parse* to scan*.
Make saccharine-to-lambda conversion bidirectional (encode and decode).
Add lambda.Marshaler and saccharine.Marshaler implementing codec.Marshaler.
Remove old infrastructure: pkg/runtime, pkg/expr, internal/plugins, internal/statistics.
Add make lint target and update golangci-lint config.

Decisions

Cobra was chosen for the CLI framework to support nested subcommands and standard flag handling.
The registry uses BFS to find conversion paths between representations, allowing multi-hop conversions without hardcoding routes.
Type erasure via cli.Repr (wrapping any) enables the registry to work with heterogeneous types while keeping pkg/ generics type-safe.
The old plugin/event system was removed entirely rather than adapted, since the new Process model can support hooks differently in the future.

Benefits

Subcommands make the CLI self-documenting and easier to extend with new functionality.
The registry pattern decouples representations, conversions, and engines, making it trivial to add new ones.
BFS conversion routing means adding a single codec automatically enables transitive conversions.
Simpler Engine/Process model reduces complexity compared to the event-emitter runtime.
Consolidating the token sub-package reduces import depth and package sprawl.

Checklist

Code follows conventional commit format.
Branch follows naming convention (<type>/<description>). Always use underscores.
Tests pass (if applicable).
Documentation updated (if applicable).

## Description The old architecture used a monolithic `main()` with a custom arg parser, an event-emitter-based runtime, and a plugin system for optional features. This PR rewrites the CLI and internal architecture to be modular, extensible, and built around a registry of interchangeable components. - Replace custom CLI arg parsing with Cobra subcommands (`convert`, `reduce`, `engine list`). - Introduce a registry system (`internal/registry`) for marshalers, codecs, and engines, with BFS-based conversion path resolution. - Add type-erased adapter layer (`internal/cli`) with `Repr`, `Engine`, `Process`, `Marshaler`, and `Conversion` interfaces wrapping generic `pkg/` types. - Replace the event-emitter-based `Runtime` with a simpler `Engine`/`Process` model (`pkg/engine`). - Add generic `Codec[T, U]` and `Marshaler[T]` interfaces (`pkg/codec`). - Merge `saccharine/token` sub-package into `saccharine` and rename scanner functions from `parse*` to `scan*`. - Make saccharine-to-lambda conversion bidirectional (encode and decode). - Add `lambda.Marshaler` and `saccharine.Marshaler` implementing `codec.Marshaler`. - Remove old infrastructure: `pkg/runtime`, `pkg/expr`, `internal/plugins`, `internal/statistics`. - Add `make lint` target and update golangci-lint config. ### Decisions - Cobra was chosen for the CLI framework to support nested subcommands and standard flag handling. - The registry uses BFS to find conversion paths between representations, allowing multi-hop conversions without hardcoding routes. - Type erasure via `cli.Repr` (wrapping `any`) enables the registry to work with heterogeneous types while keeping `pkg/` generics type-safe. - The old plugin/event system was removed entirely rather than adapted, since the new `Process` model can support hooks differently in the future. ## Benefits - Subcommands make the CLI self-documenting and easier to extend with new functionality. - The registry pattern decouples representations, conversions, and engines, making it trivial to add new ones. - BFS conversion routing means adding a single codec automatically enables transitive conversions. - Simpler `Engine`/`Process` model reduces complexity compared to the event-emitter runtime. - Consolidating the `token` sub-package reduces import depth and package sprawl. ## Checklist - [x] Code follows conventional commit format. - [x] Branch follows naming convention (`<type>/<description>`). Always use underscores. - [ ] Tests pass (if applicable). - [ ] Documentation updated (if applicable).

mvhutz added 14 commits 2026-02-07 03:24:35 +00:00

feat: repr, codec 0ec52008bb

feat: cli versions 0cdce0e42c

feat: registry, normalorder engine, lambda codec and marshaler 68cc1624c7

feat: saccharine marshaler 31924237b2

feat: new system ca1bb2ffa8

style: no debug commands dc872d15ae

style: codec -> conversion 5f6a9f9663

feat: engine -> process, engine is now a factory for a proces 22e8a99362

feat: some basic commands 7750d8615f

fix: convert style 36c0eede06

fix: silence usage, and no double errors 53042ea26d