diff --git a/AGENTS.md b/AGENTS.md index 78c3a62..13380c1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,10 +5,11 @@ ## Codebase Intelligence for ottyl (Repowise) -Indexed by [Repowise](https://repowise.dev). Last indexed: 2026-09-07 (commit 0c41048). Confidence: 98%. +Indexed by [Repowise](https://repowise.dev). Last indexed: 2026-09-07 (commit dbe2ea9). Confidence: 100%. ### How to work in this repo -- **Trust the index.** `verified: true` means the bytes were checked against the live tree, so never re-read those lines. Re-read only on `bounds: "approximate"`, `_meta.stale_warning`, `search_method: "bm25"` or `confidence: "low"`; `index_behind: true` alone is informational. +- **Trust the index.** `verified: true` and `_meta.complete` mean the bytes were checked against the live tree, so never re-read them. Re-read only what `bounds: "approximate"` or `_meta.stale_warning` names. `confidence` rates the prose, not the evidence: on `low` read the `fallback_targets` or `best_guesses` the reply names, and run `repowise update` and ask again if `_meta.hint` says the index is behind HEAD. `index_behind: true` alone is informational. +- **A zero carries its basis.** An empty `callers`/`callees`/`used_by` comes with a `*_basis` saying how much of that language's calls the graph resolved, so read it before concluding nothing calls a symbol. `_meta.scope_hint` names the areas the answer did not touch. - **Pre-edit, not instead-of-edit.** These tools decide *which* files to read and edit. Reading a file before you edit it is correct and expected. - **Noisy commands** (tests, builds, `git log`/`diff`, searches, listings): prefer `repowise distill `, the same command with its exit code preserved and errors-first output. A `[repowise#: N lines omitted]` marker is recoverable via `repowise expand ` (add `-q ` to filter); never re-run the command to see omitted output. - **Recording a decision** you had to reason out: `repowise decision add --title T --decision D` records it without prompting and prints the id (`--format json` to parse it back). It lands `proposed`, for a person to confirm. @@ -19,20 +20,42 @@ Indexed by [Repowise](https://repowise.dev). Last indexed: 2026-09-07 (commit 0c |------|--------------| | `get_answer(question)` | First call for any how/where/why question. Cite `confidence: "high"` or `grounding: "extracted"` directly; `degraded` means judge by `retrieval_quality`. `symbol_bodies` has live bodies. | | `get_context(targets=[...])` | Triage card for files/modules/symbols: docs, signatures, hotspot, fix history. No source bytes — `include=["skeleton"]` for the whole file verified, `["callers"|"decisions"]` for depth. Batch targets. | -| `get_symbol(id)` | **Follow-up, not an entry point** — one verified body for an id a prior response named (`path.py::Name`, `path.py:140-180`, `repowise#`). Never walk a file symbol by symbol; Read it. | +| `get_symbol(id, depth?)` | **Follow-up, not an entry point** — one verified body for an id a prior response named (`path.py::Name`, `path.py:140-180`, `repowise#`). Never walk a file symbol by symbol; Read it. | | `search_codebase(query)` | Hybrid search, auto-routed by query shape; force with `mode=symbol|path|concept|hybrid`. A hit whose `sources` are `[fts]` only has no semantic agreement, so verify it. | | `get_why(query, targets?)` | Why the code is shaped this way: decision records, git archaeology, rationale comments. Call before a refactor or a pattern divergence. | -| `get_risk(targets, changed_files?)` | What history says about touching these files. PR mode (`changed_files`) leads with a `directive`: read `will_break` / `missing_cochanges` / `missing_tests` / `tests_to_run` first. | -| `get_change_risk(revspec, extensions?, exclude_patterns?)` | Defect score for a whole commit or `base..head` range, from its diff on the live checkout. Lead with `risk_percentile`. Scores a range; `get_risk` scores paths. | +| `get_risk(targets, changed_files?, include?)` | File history and structural reach. PR mode leads with `directive`; its 0-10 structural heuristic is uncalibrated, not a probability. Read typed test recommendations and coverage state first. | +| `get_change_risk(revspec?, extensions?, exclude_patterns?)` | Deterministic live-diff review signal for a commit or range. Lead with benchmarked percentile/classification; the 0-10 diff-shape score is supporting, not a probability. `get_risk` scores paths. | | `get_health(targets?, include?)` | Defect / maintainability / performance scores and findings. Self-check the files you touched before finishing. | -| `get_dead_code()` | Confidence-tiered unreachable files / unused exports / zombie packages. For cleanup sweeps, not targeted fixes. | +| `get_dead_code(tier?, min_confidence?, safe_only?)` | Confidence-tiered unreachable files / unused exports / zombie packages. For cleanup sweeps, not targeted fixes. | | `get_overview()` | Architecture map. Call once, first, in an unfamiliar repo; skip it after that. | ### Architecture -ottyl ingests log & metric streams -> processes via Rust engine (parsing, filtering, PromQL) -> outputs visualized data via TypeScript web UI. +**Files:** 81 | **Lines:** 18237 | **Import cycles:** 1 +ottyl is a rust codebase of 81 files. Execution starts at src/main.rs, webapp/src/App.tsx, webapp/src/main.tsx. --- +*Built from the code's structure. It states what is there, not why it is that +way. ### Key modules -- `root` — What the prose above calls things, the identifier to search for, and where it lives +- `webapp/src` — webapp/src · webapp/src/components · webapp/src/lib · webapp/src/lib/api +**Language:** typescript | **Files:** 30 | **Public symbols:** 97… +- `webapp/src/lib` — webapp/src/lib · webapp/src/lib/api +**Language:** typescript | **Files:** 14 | **Public symbols:** 67 / 74 +Covers the 14 source files in 2… +- `src/engine` — src/engine +**Language:** rust | **Files:** 14 | **Public symbols:** 122 / 531 +Covers the 14 source files in src/engine +- `webapp/src/components` — webapp/src/components +**Language:** typescript | **Files:** 14 | **Public symbols:** 29 / 94 +Covers the 14 source files in… +- `src` — src · src/api · src/cli · src/config · src/flavour +**Language:** rust | **Files:** 10 | **Public symbols:** 300 / 598 +Covers the 10 source… +- `src/engine/snapshot` — src/engine/snapshot +**Language:** rust | **Files:** 6 | **Public symbols:** 0 / 139 +Covers the 6 source files in src/engine/snapshot +- `webapp` — webapp · webapp/src +**Language:** typescript | **Files:** 3 | **Public symbols:** 1 / 19 +Covers the 3 source files in 2 directories under… ### Entry points - `src/main.rs` @@ -42,19 +65,19 @@ ottyl ingests log & metric streams -> processes via Rust engine (parsing, filter ### Files that need care (bug-fix history first, then churn — check `get_risk` before editing) - `webapp/src/App.tsx` — 3 bug fixes, last fix today; 22 commits/90d - `webapp/src/components/Dashboards.tsx` — 3 bug fixes, last fix today; 17 commits/90d -- `webapp/src/lib/api.ts` — 1 bug fix, last fix today; 41 commits/90d +- `webapp/src/components/Params.tsx` — 2 bug fixes, last fix today; 15 commits/90d - `webapp/src/components/NavMenu.tsx` — 1 bug fix, last fix today; 22 commits/90d -- `webapp/src/components/Docs.tsx` — 1 bug fix, last fix today; 16 commits/90d +- `webapp/src/components/Docs.tsx` — 1 bug fix, last fix today; 17 commits/90d ### Code health -Three co-equal signals: defect risk 7.53/10 avg, hotspot health 7.15/10 (stable), worst `src/engine/snapshot/mod.rs` at 5.5/10 · maintainability 7.91/10 · performance risk 21 open static I/O-in-loop / N+1 findings. Detail: `get_health()`. +Three co-equal signals: defect risk 5.95/10 avg, hotspot health 4.94/10 (stable), worst `src/engine/snapshot/mod.rs` at 2.0/10 · maintainability 7.48/10 · performance risk 16 open static I/O-in-loop / N+1 findings. Detail: `get_health()`. Critical files: -- `webapp/src/components/NavMenu.tsx` — churn risk — impact −2.4 -- `src/engine/tests.rs` — churn risk — impact −2.4 -- `src/engine/mod.rs` — churn risk — impact −2.4 -- `src/config/mod.rs` — churn risk — impact −2.4 -- `src/api/dto.rs` — churn risk — impact −2.4 +- `webapp/src/components/LogPreview.tsx` — untested hotspot — impact −2.0 +- `webapp/src/lib/useSettingsPanel.ts` — untested hotspot — impact −2.0 +- `webapp/src/components/NavMenu.tsx` — change entropy — impact −1.3 +- `src/main.rs` — change entropy — impact −1.3 +- `webapp/src/App.tsx` — change entropy — impact −1.3 ### Commands - Build: `make build`