habedi-work/geolog-zeta-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
geolog-zeta-fork/AGENTS.md
Hassan Abedi 638bb6db8e Add an AGENTS.md file to project
2026-03-23 09:55:15 +01:00

6.5 KiB
Raw Blame History

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.