# ExecPlans

When writing complex features or significant refactors, use an ExecPlan (as described in .agent/PLANS.md) from design to implementation.

# Expectations

When there is a clear next step towards your goal (in or out of ExecPlan), you always continue to execute it without
stopping to ask. If you have made material progress, commit a multiline checkpoint first explaining changes-so-far
in detail, especially the "why", I can get the "what" from the diff.

# Analyzer Test Guidance

When adding or refactoring analyzer tests that need small ad hoc projects, prefer the shared inline test harness in
`tests/common/inline_project.rs` over handwritten `tempdir` plus `ProjectFile::write(...)` setup.

Use `InlineTestProject` by default for tests that define a few files inline. It keeps temp-root management automatic,
hides absolute-path handling, and can infer analyzer languages from file extensions or accept an explicit language when
the test should stay single-language.

Prefer handwritten fixture directories or bespoke setup only when the test genuinely needs a larger reusable corpus or
filesystem behavior that is awkward to express inline.

# Rust CI Checks

Before pushing Rust changes, run the same core checks that CI enforces locally when practical.

At minimum, run `cargo fmt` and `cargo clippy --all-targets --all-features -- -D warnings`. If clippy fails, fix that locally before pushing rather than waiting for the CI matrix to report it back.

# Implementation details

- Prefer stack-safe iterative traversal over recursive Rust calls for analyzer tree/graph walks, especially during
  workspace initialization, parser declaration collection, usage analysis, and other paths that may touch many files or
  deeply nested ASTs. Use an explicit stack/queue or shared traversal helper unless the recursion depth is provably
  bounded and small.
- Design APIs to avoid cloning, especially in hot loops; prefer iterators/slices where possible.
- Avoid sorted data structures (e.g. BTreeMap) in favor of lighter-weight alternatives
  (HashMap) unless ordering is required for semantic correctness, or when it is preferable
  to pay the ordering cost once at insertion rather than repeatedly sorting later.
- Avoid naive use of reference counting; prefer e.g. explicit IDs and arena allocation in
  graph domains.
- The above should not be interpreted as a blanket prohibition on clone or refcounting
  when these are genuinely the best option, just be intentional rather than reaching for these
  out of habit.
