mvhutz/lambda
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: rewrite CLI and internal architecture (#41)

Browse Source 
## 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).

Reviewed-on: #41
Co-authored-by: M.V. Hutz <git@maximhutz.me>
Co-committed-by: M.V. Hutz <git@maximhutz.me>
This commit was merged in pull request #41.
This commit is contained in:
Maxim Hutz
2026-02-07 03:25:32 +00:00
committed by Maxim Hutz
parent f2c8d9f7d2
commit a3ee34732e
41 changed files with 1007 additions and 637 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
internal/cli/conversion.go Normal file
View File

@@ -0,0 +1,67 @@
package cli
import (
"fmt"
"git.maximhutz.com/max/lambda/pkg/codec"
)
type Conversion interface {
InType() string
OutType() string
Run(Repr) (Repr, error)
}
type forwardCodec[T, U any] struct {
codec codec.Codec[T, U]
inType, outType string
}
func (c forwardCodec[T, U]) Run(r Repr) (Repr, error) {
t, ok := r.Data().(T)
if !ok {
return nil, fmt.Errorf("could not parse '%v' as '%s'", t, c.inType)
}
u, err := c.codec.Encode(t)
if err != nil {
return nil, err
}
return NewRepr(c.outType, u), nil
}
func (c forwardCodec[T, U]) InType() string { return c.inType }
func (c forwardCodec[T, U]) OutType() string { return c.outType }
type backwardCodec[T, U any] struct {
codec codec.Codec[T, U]
inType, outType string
}
func (c backwardCodec[T, U]) Run(r Repr) (Repr, error) {
u, ok := r.Data().(U)
if !ok {
return nil, fmt.Errorf("could not parse '%v' as '%s'", r, c.outType)
}
t, err := c.codec.Decode(u)
if err != nil {
return nil, err
}
return NewRepr(c.inType, t), nil
}
func (c backwardCodec[T, U]) InType() string { return c.outType }
func (c backwardCodec[T, U]) OutType() string { return c.inType }
func ConvertCodec[T, U any](e codec.Codec[T, U], inType, outType string) []Conversion {
return []Conversion{
forwardCodec[T, U]{e, inType, outType},
backwardCodec[T, U]{e, inType, outType},
}
}

27
internal/cli/engine.go Normal file
View File

@@ -0,0 +1,27 @@
package cli
import "git.maximhutz.com/max/lambda/pkg/engine"
type Engine interface {
Load() Process
Name() string
InType() string
}
type convertedEngine[T any] struct {
engine engine.Engine[T]
name string
inType string
}
func (e convertedEngine[T]) InType() string { return e.inType }
func (e convertedEngine[T]) Name() string { return e.name }
func (e convertedEngine[T]) Load() Process {
return convertedProcess[T]{e.engine.Load(), e.inType}
}
func ConvertEngine[T any](e engine.Engine[T], name, inType string) Engine {
return &convertedEngine[T]{e, name, inType}
}

18
internal/cli/exit.go
View File

@@ -1,18 +0,0 @@
// Package "cli" provides miscellaneous helper functions.
package cli
import (
"fmt"
"os"
)
// A helper function to handle errors in the program. If it is given an error,
// the program will exist, and print the error.
func HandleError(err error) {
if err == nil {
return
}
fmt.Fprintln(os.Stderr, "ERROR:", err)
os.Exit(1)
}

45
internal/cli/marshaler.go Normal file
View File

@@ -0,0 +1,45 @@
package cli
import (
"fmt"
"reflect"
"git.maximhutz.com/max/lambda/pkg/codec"
)
type Marshaler interface {
codec.Marshaler[Repr]
InType() string
}
type convertedMarshaler[T any] struct {
codec codec.Marshaler[T]
inType string
}
func (c convertedMarshaler[T]) Decode(s string) (Repr, error) {
t, err := c.codec.Decode(s)
if err != nil {
return nil, err
}
return NewRepr(c.inType, t), nil
}
func (c convertedMarshaler[T]) Encode(r Repr) (string, error) {
t, ok := r.Data().(T)
if !ok {
dataType := reflect.TypeOf(r.Data())
allowedType := reflect.TypeFor[T]()
return "", fmt.Errorf("marshaler for '%s' cannot parse '%s'", allowedType, dataType)
}
return c.codec.Encode(t)
}
func (c convertedMarshaler[T]) InType() string { return c.inType }
func ConvertMarshaler[T any](e codec.Marshaler[T], inType string) Marshaler {
return convertedMarshaler[T]{e, inType}
}

41
internal/cli/process.go Normal file
View File

@@ -0,0 +1,41 @@
package cli
import (
"fmt"
"git.maximhutz.com/max/lambda/pkg/engine"
)
type Process interface {
engine.Process[Repr]
InType() string
}
type convertedProcess[T any] struct {
process engine.Process[T]
inType string
}
func (e convertedProcess[T]) InType() string { return e.inType }
func (b convertedProcess[T]) Get() (Repr, error) {
s, err := b.process.Get()
if err != nil {
return nil, err
}
return NewRepr(b.inType, s), nil
}
func (b convertedProcess[T]) Set(r Repr) error {
if t, ok := r.Data().(T); ok {
return b.process.Set(t)
}
return fmt.Errorf("Incorrent format '%s' for engine '%s'.", r.Id(), b.inType)
}
func (b convertedProcess[T]) Step(i int) bool {
return b.process.Step(i)
}

21
internal/cli/repr.go Normal file
View File

@@ -0,0 +1,21 @@
package cli
type Repr interface {
// Id returns to name of the objects underlying representation. If is
// assumed that if two Repr objects have the same Id(), they share the same
// representation.
Id() string
Data() any
}
type baseRepr struct {
id string
data any
}
func (r baseRepr) Id() string { return r.id }
func (r baseRepr) Data() any { return r.data }
func NewRepr(id string, data any) Repr { return baseRepr{id, data} }

23
internal/plugins/debug.go
View File

@@ -1,23 +0,0 @@
package plugins
import (
"log/slog"
"git.maximhutz.com/max/lambda/pkg/runtime"
)
type Logs struct {
logger *slog.Logger
reducer runtime.Runtime
}
func NewLogs(logger *slog.Logger, r runtime.Runtime) *Logs {
plugin := &Logs{logger, r}
r.On(runtime.StepEvent, plugin.Step)
return plugin
}
func (t *Logs) Step() {
t.logger.Info("reduction", "tree", t.reducer.Expression().String())
}

31
internal/plugins/explanation.go
View File

@@ -1,31 +0,0 @@
// Package "explanation" provides an observer to gather the reasoning during the
// reduction, and present a thorough explanation to the user for each step.
package plugins
import (
"fmt"
"git.maximhutz.com/max/lambda/pkg/runtime"
)
// Track the reductions made by a reduction process.
type Explanation struct {
reducer runtime.Runtime
}
// Attaches a new explanation tracker to a reducer.
func NewExplanation(r runtime.Runtime) *Explanation {
plugin := &Explanation{reducer: r}
r.On(runtime.StartEvent, plugin.Start)
r.On(runtime.StepEvent, plugin.Step)
return plugin
}
func (t *Explanation) Start() {
fmt.Println(t.reducer.Expression().String())
}
func (t *Explanation) Step() {
fmt.Println(" =", t.reducer.Expression().String())
}

59
internal/plugins/performance.go
View File

@@ -1,59 +0,0 @@
// Package "performance" provides a tracker to observer CPU performance during
// execution.
package plugins
import (
"os"
"path/filepath"
"runtime/pprof"
"git.maximhutz.com/max/lambda/pkg/runtime"
)
// Observes a reduction process, and publishes a CPU performance profile on
// completion.
type Performance struct {
File string
filePointer *os.File
Error error
}
// Create a performance tracker that outputs a profile to "file".
func NewPerformance(file string, process runtime.Runtime) *Performance {
plugin := &Performance{File: file}
process.On(runtime.StartEvent, plugin.Start)
process.On(runtime.StopEvent, plugin.Stop)
return plugin
}
// Begin profiling.
func (t *Performance) Start() {
var absPath string
absPath, t.Error = filepath.Abs(t.File)
if t.Error != nil {
return
}
t.Error = os.MkdirAll(filepath.Dir(absPath), 0777)
if t.Error != nil {
return
}
t.filePointer, t.Error = os.Create(absPath)
if t.Error != nil {
return
}
t.Error = pprof.StartCPUProfile(t.filePointer)
if t.Error != nil {
return
}
}
// Stop profiling.
func (t *Performance) Stop() {
pprof.StopCPUProfile()
t.filePointer.Close()
}

44
internal/plugins/statistics.go
View File

@@ -1,44 +0,0 @@
package plugins
import (
"fmt"
"os"
"time"
"git.maximhutz.com/max/lambda/internal/statistics"
"git.maximhutz.com/max/lambda/pkg/runtime"
)
// An observer, to track reduction performance.
type Statistics struct {
start time.Time
steps uint64
}
// Create a new reduction performance Statistics.
func NewStatistics(r runtime.Runtime) *Statistics {
plugin := &Statistics{}
r.On(runtime.StartEvent, plugin.Start)
r.On(runtime.StepEvent, plugin.Step)
r.On(runtime.StopEvent, plugin.Stop)
return plugin
}
func (t *Statistics) Start() {
t.start = time.Now()
t.steps = 0
}
func (t *Statistics) Step() {
t.steps++
}
func (t *Statistics) Stop() {
results := statistics.Results{
StepsTaken: t.steps,
TimeElapsed: uint64(time.Since(t.start).Milliseconds()),
}
fmt.Fprint(os.Stderr, results.String())
}

27
internal/registry/converter.go Normal file
View File

@@ -0,0 +1,27 @@
package registry
import (
"git.maximhutz.com/max/lambda/internal/cli"
)
type Converter struct {
data map[string][]cli.Conversion
}
func NewConverter() *Converter {
return &Converter{data: map[string][]cli.Conversion{}}
}
func (g *Converter) Add(c cli.Conversion) {
conversionsFromIn, ok := g.data[c.InType()]
if !ok {
conversionsFromIn = []cli.Conversion{}
}
conversionsFromIn = append(conversionsFromIn, c)
g.data[c.InType()] = conversionsFromIn
}
func (g *Converter) ConversionsFrom(t string) []cli.Conversion {
return g.data[t]
}

173
internal/registry/registry.go Normal file
View File

@@ -0,0 +1,173 @@
package registry
import (
"fmt"
"iter"
"maps"
"git.maximhutz.com/max/lambda/internal/cli"
)
type Registry struct {
marshalers map[string]cli.Marshaler
converter *Converter
engines map[string]cli.Engine
}
func New() *Registry {
return &Registry{
marshalers: map[string]cli.Marshaler{},
converter: NewConverter(),
engines: map[string]cli.Engine{},
}
}
func (r *Registry) AddConversions(conversions ...cli.Conversion) error {
for _, conversion := range conversions {
r.converter.Add(conversion)
}
return nil
}
func (r *Registry) MustAddConversions(conversions ...cli.Conversion) {
if err := r.AddConversions(conversions...); err != nil {
panic(err)
}
}
func (r *Registry) AddMarshaler(c cli.Marshaler) error {
if _, ok := r.marshalers[c.InType()]; ok {
return fmt.Errorf("marshaler for '%s' already registered", c.InType())
}
r.marshalers[c.InType()] = c
return nil
}
func (r *Registry) MustAddMarshaler(c cli.Marshaler) {
if err := r.AddMarshaler(c); err != nil {
panic(err)
}
}
func (r *Registry) AddEngine(e cli.Engine) error {
if _, ok := r.engines[e.Name()]; ok {
return fmt.Errorf("engine '%s' already registered", e.Name())
}
r.engines[e.Name()] = e
return nil
}
func (r *Registry) MustAddEngine(e cli.Engine) {
if err := r.AddEngine(e); err != nil {
panic(err)
}
}
func (r Registry) GetEngine(name string) (cli.Engine, error) {
e, ok := r.engines[name]
if !ok {
return nil, fmt.Errorf("engine '%s' not found", name)
}
return e, nil
}
func (r Registry) ListEngines() iter.Seq[cli.Engine] {
return maps.Values(r.engines)
}
func (r *Registry) GetDefaultEngine(id string) (cli.Engine, error) {
for _, engine := range r.engines {
if engine.InType() == id {
return engine, nil
}
}
return nil, fmt.Errorf("no engine for '%s'", id)
}
func (r *Registry) ConvertTo(repr cli.Repr, outType string) (cli.Repr, error) {
path, err := r.ConversionPath(repr.Id(), outType)
if err != nil {
return nil, err
}
result := repr
for _, conversion := range path {
result, err = conversion.Run(result)
if err != nil {
return nil, fmt.Errorf("converting '%s' to '%s': %w", conversion.InType(), conversion.OutType(), err)
}
}
return result, err
}
func (r *Registry) Marshal(repr cli.Repr) (string, error) {
m, ok := r.marshalers[repr.Id()]
if !ok {
return "", fmt.Errorf("no marshaler for '%s'", repr.Id())
}
return m.Encode(repr)
}
func (r *Registry) Unmarshal(s string, outType string) (cli.Repr, error) {
m, ok := r.marshalers[outType]
if !ok {
return nil, fmt.Errorf("no marshaler for '%s'", outType)
}
return m.Decode(s)
}
func reverse[T any](list []T) []T {
if list == nil {
return list
}
reversed := []T{}
for i := len(list) - 1; i >= 0; i-- {
reversed = append(reversed, list[i])
}
return reversed
}
func (r *Registry) ConversionPath(from, to string) ([]cli.Conversion, error) {
backtrack := map[string]cli.Conversion{}
iteration := []string{from}
for len(iteration) > 0 {
nextIteration := []string{}
for _, item := range iteration {
for _, conversion := range r.converter.ConversionsFrom(item) {
if _, ok := backtrack[conversion.OutType()]; ok {
continue
}
nextIteration = append(nextIteration, conversion.OutType())
backtrack[conversion.OutType()] = conversion
}
}
iteration = nextIteration
}
reversedPath := []cli.Conversion{}
current := to
for current != from {
conversion, ok := backtrack[current]
if !ok {
return nil, fmt.Errorf("no valid conversion from '%s' to '%s'", from, to)
}
reversedPath = append(reversedPath, conversion)
current = conversion.InType()
}
return reverse(reversedPath), nil
}

28
internal/statistics/statistics.go
View File

@@ -1,28 +0,0 @@
// Package "statistics" provides a way to observer reduction speed during
// execution.
package statistics
import (
"fmt"
"strings"
)
// Statistics for a specific reduction.
type Results struct {
StepsTaken uint64 // Number of steps taken during execution.
TimeElapsed uint64 // The time (ms) taken for execution to complete.
}
// Returns the average number of operations per second of the execution.
func (r Results) OpsPerSecond() float32 {
return float32(r.StepsTaken) / (float32(r.TimeElapsed) / 1000)
}
// Format the results as a string.
func (r Results) String() string {
builder := strings.Builder{}
fmt.Fprintln(&builder, "Time Spent:", r.TimeElapsed, "ms")
fmt.Fprintln(&builder, "Steps:", r.StepsTaken)
fmt.Fprintln(&builder, "Speed:", r.OpsPerSecond(), "ops")
return builder.String()
}