147 lines
6.5 KiB
Markdown
147 lines
6.5 KiB
Markdown
|
# AGENTS.md
|
||
|
|
|
||
|
|
This file provides guidance to coding agents collaborating on this repository.
|
||
|
|
|
||
|
|
## Mission
|
||
|
|
|
||
|
|
Geolog is a Rust codebase for geometric logic:
|
||
|
|
|
||
|
|
- a parser and pretty-printer for the Geolog language,
|
||
|
|
- an elaboration layer that turns syntax into core structures,
|
||
|
|
- a REPL and workspace/persistence layer,
|
||
|
|
- a chase/query/solver runtime,
|
||
|
|
- and an optional egui GUI behind the `gui` Cargo feature.
|
||
|
|
|
||
|
|
Priorities, in order:
|
||
|
|
|
||
|
|
1. Semantic correctness of theories, instances, queries, and chase behavior.
|
||
|
|
2. Clear boundaries between parsing, elaboration, core structures, REPL/workspace, and GUI code.
|
||
|
|
3. Focused, maintainable changes with good regression coverage.
|
||
|
|
4. Performance only after correctness and testability are preserved.
|
||
|
|
|
||
|
|
## Core Rules
|
||
|
|
|
||
|
|
- Use English for code, comments, docs, tests, and commit-facing text.
|
||
|
|
- Prefer small, targeted changes over broad rewrites.
|
||
|
|
- Fix root causes rather than layering on ad hoc workarounds.
|
||
|
|
- Keep modules decoupled: parsing in parser/lexer, semantics in `core`/`elaborate`, runtime behavior in `repl`/`query`/`solver`, presentation in `gui`.
|
||
|
|
- Do not introduce unnecessary global mutable state.
|
||
|
|
- Preserve feature gating: GUI code must remain behind the `gui` feature.
|
||
|
|
- Avoid adding dependencies unless clearly justified.
|
||
|
|
- Add comments only when they clarify non-obvious invariants, algorithms, or semantic constraints.
|
||
|
|
|
||
|
|
Quick examples:
|
||
|
|
|
||
|
|
- Good: add a targeted regression test for a chase bug in an existing GUI or unit test module.
|
||
|
|
- Good: fix a REPL/workspace bug in `src/repl.rs` or `src/store/` without refactoring unrelated parser code.
|
||
|
|
- Bad: rewrite the AST/core boundary during a small GUI task.
|
||
|
|
- Bad: mix GUI presentation logic into core semantic modules.
|
||
|
|
|
||
|
|
## Repository Layout
|
||
|
|
|
||
|
|
- `src/lib.rs`: crate entrypoint and module exports.
|
||
|
|
- `src/ast.rs`, `src/lexer.rs`, `src/parser.rs`, `src/pretty.rs`: syntax pipeline and round-tripping.
|
||
|
|
- `src/core.rs`: core semantic data structures such as signatures, theories, and structures.
|
||
|
|
- `src/elaborate/`: elaboration from AST into core representations.
|
||
|
|
- `src/repl.rs`: REPL state, command handling, and top-level execution flow.
|
||
|
|
- `src/store/`: persistence/workspace and storage-related logic.
|
||
|
|
- `src/query/`: chase, query compilation, optimization, backend execution.
|
||
|
|
- `src/solver/`: solver and tactic logic.
|
||
|
|
- `src/tensor/`: tensor-based checking/evaluation support.
|
||
|
|
- `src/gui/`: egui GUI state, panels, and visualizations.
|
||
|
|
- `src/bin/geolog.rs`: CLI/REPL binary.
|
||
|
|
- `src/bin/geolog-gui.rs`: GUI binary (requires `--features gui`).
|
||
|
|
- `examples/geolog/`: sample Geolog programs.
|
||
|
|
- `tests/`: integration, regression, unit-style cross-module, and property tests.
|
||
|
|
- `docs/`: architecture and syntax documentation.
|
||
|
|
- `proofs/`: Lean proofs and formal artifacts.
|
||
|
|
- `fuzz/`: fuzzing targets.
|
||
|
|
|
||
|
|
## Architecture Constraints
|
||
|
|
|
||
|
|
- Keep the syntax pipeline clean: text → lexer → parser → AST.
|
||
|
|
- Keep elaboration separate from parsing and separate from UI code.
|
||
|
|
- `core` types should remain usable without the GUI.
|
||
|
|
- GUI code should orchestrate and present existing behavior, not reimplement semantic logic.
|
||
|
|
- Workspace/persistence behavior belongs in `repl`/`store`, not inside GUI widgets.
|
||
|
|
- Query/chase behavior changes must preserve observable semantics and existing tests.
|
||
|
|
- If a change affects persistence or serialization, consider compatibility with existing workspace behavior.
|
||
|
|
|
||
|
|
## GUI Rules
|
||
|
|
|
||
|
|
- The GUI is optional and must compile cleanly only when the `gui` feature is enabled.
|
||
|
|
- Prefer fixing GUI bugs in `src/gui/state.rs`, `src/gui/panels/`, or `src/gui/visualizations/` before touching core logic.
|
||
|
|
- Keep GUI state transitions explicit and centralized when possible.
|
||
|
|
- Avoid hard-coding theme assumptions; UI should remain readable in the intended visual style.
|
||
|
|
- File dialog, editor, browser, inspector, console, and visualization behavior should stay consistent with REPL/workspace state.
|
||
|
|
|
||
|
|
## Testing Layout Rules
|
||
|
|
|
||
|
|
- Prefer unit tests near the code they exercise when there is already a local test module.
|
||
|
|
- Put broader cross-module coverage in `tests/`.
|
||
|
|
- Keep regression tests close to the bug they reproduce when that is the clearest fit.
|
||
|
|
- Do not add a new testing framework if existing `cargo test`, property tests, or fuzz targets are sufficient.
|
||
|
|
- If you move behavior across modules, move or rewrite the relevant tests with it.
|
||
|
|
|
||
|
|
## Workflow
|
||
|
|
|
||
|
|
Before coding:
|
||
|
|
|
||
|
|
1. Identify whether the task is parser, elaboration, runtime, persistence, solver/query, or GUI work.
|
||
|
|
2. Read the touched module and nearby tests first.
|
||
|
|
3. Check whether the change should live in `core`/`repl`/`store` rather than the GUI.
|
||
|
|
|
||
|
|
Implement and validate:
|
||
|
|
|
||
|
|
1. Make the smallest change that solves the problem.
|
||
|
|
2. Add or update tests when behavior changes or a bug is fixed.
|
||
|
|
3. Run the narrowest relevant command while iterating.
|
||
|
|
4. Run broader validation once the change is stable.
|
||
|
|
5. Update docs if user-facing behavior or workflow changed.
|
||
|
|
|
||
|
|
## Validation Commands
|
||
|
|
|
||
|
|
Use the narrowest relevant command first:
|
||
|
|
|
||
|
|
- General compile check: `cargo check`
|
||
|
|
- Full test suite: `cargo test`
|
||
|
|
- GUI compile check: `cargo check --features gui --bin geolog-gui`
|
||
|
|
- GUI-related tests: `cargo test --features gui`
|
||
|
|
- Single test/module during iteration: `cargo test <name>`
|
||
|
|
|
||
|
|
Formatting:
|
||
|
|
|
||
|
|
- Prefer formatting only touched Rust files when the repository is not already fully formatted.
|
||
|
|
- Avoid reformatting unrelated files as part of a focused bugfix.
|
||
|
|
|
||
|
|
## Testing Expectations
|
||
|
|
|
||
|
|
- No semantic bugfix is complete without appropriate validation.
|
||
|
|
- Parser/elaboration changes should preserve round-trip and error-reporting behavior where relevant.
|
||
|
|
- Query/chase/solver changes need explicit coverage because regressions can be subtle.
|
||
|
|
- GUI bugfixes should get a focused test when practical, especially for state transitions or regressions.
|
||
|
|
- Keep tests deterministic and focused on observable behavior.
|
||
|
|
|
||
|
|
## Documentation Expectations
|
||
|
|
|
||
|
|
- Update `README.md` when user workflow, CLI behavior, or GUI usage changes.
|
||
|
|
- Update `docs/ARCHITECTURE.md` or `docs/SYNTAX.md` when architectural or language behavior changes materially.
|
||
|
|
- If you find stale docs directly related to your change, fix them in the same patch.
|
||
|
|
|
||
|
|
## Review Guidelines
|
||
|
|
|
||
|
|
Review output should be concise and focus on real defects.
|
||
|
|
|
||
|
|
- `P0`: broken build, broken tests, data loss, or incorrect core semantics.
|
||
|
|
- `P1`: likely semantic regression, unsafe state transition, missing validation on risky changes.
|
||
|
|
|
||
|
|
Use this review format:
|
||
|
|
|
||
|
|
1. `Severity` (`P0`/`P1`)
|
||
|
|
2. `File:line`
|
||
|
|
3. `Issue`
|
||
|
|
4. `Why it matters`
|
||
|
|
5. `Minimal fix direction`
|
||
|
|
|
||
|
|
Do not include style-only feedback or broad praise.
|