aontu AGENTS.md

Aontu — agent & contributor guide

Aontu is a JSON structure unifier (a purpose-specific dialect inspired by CUE). This repository ships two implementations kept in parity:

• TypeScript in ts/ — the canonical implementation.
• Go in go/ — a port that mirrors the TypeScript semantics.

Three decisions govern everything below and are recorded in ADR.md: ADR-001 (the two implementations stay at full parity, proved by the shared spec), ADR-002 (coverage stays at 100 % in both, with every exclusion justified in the source), and ADR-003 (where a host subsystem supplies semantics, Aontu defines the meaning and rewrites the input rather than trusting the host). Read those before proposing a change that touches one implementation only, that adds code no test reaches, or that hands a value to a host library to interpret.

The structural layout follows voxgig/util: top-level ts/ and go/ siblings and a fan-out Makefile. On top of that, this repo adds a shared, data-driven test suite so both implementations are checked against the same cases.

CI note: the workflow lives at .github/workflows/build.yml and runs three jobs — build-ts, build-go, and coverage (the ADR-002 floor). Editing anything under .github/workflows/ needs the GitHub workflow OAuth scope, so a push that touches it must come from an account that has the scope.

Repository layout

.
├── ADR.md               # architecture decision record (the fundamentals)
├── AGENTS.md            # this file
├── CLAUDE.md            # pointer to AGENTS.md
├── Makefile             # fans out to ts/ and go/
├── README.md
├── docs/
│   ├── design/          # design notes — the why behind settled decisions
│   ├── lsp.md           # language server reference
│   └── shared-spec.md   # the shared TSV test format
├── editors/             # editor plugins (VS Code, Emacs, Vim) → aontu-lsp
├── test/
│   └── spec/            # shared test cases — *.tsv (language-agnostic)
│       └── divergent.tsv  # the parity ledger (commentary only, no rows)
├── ts/                  # canonical TypeScript implementation
│   ├── package.json     # `bin`: aontu -> bin/aontu.js, aontu-lsp -> bin/aontu-lsp.js
│   ├── src/             # source incl. cli.ts, lsp.ts, lsp-server.ts (+ src/tsconfig.json -> ../dist)
│   ├── test/            # tests (+ test/tsconfig.json -> ../dist-test)
│   ├── dist/            # committed compiled JS + .d.ts (incl. cli.js)
│   └── dist-test/       # committed compiled tests (the run target)
└── go/                  # Go port
    ├── go.mod           # module github.com/aontu-lang/aontu/go
    ├── *.go             # package aontu (incl. check.go: Check -> []Problem)
    ├── lsp/             # LSP library (Diagnostics + Handler)
    ├── cmd/aontu/       # `aontu` CLI (package main, file/stdin/REPL)
    ├── cmd/aontu-lsp/   # `aontu-lsp` Language Server (stdio)
    ├── aontu_test.go    # Go-native sanity tests
    └── spec_test.go     # runs the shared test/spec/*.tsv suite