Skip to content

Commit 08a3365

Browse files
author
Alex
committed
Merge remote-tracking branch 'origin/main'
2 parents c1ced31 + 2647905 commit 08a3365

3 files changed

Lines changed: 311 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
5050
- **Token budget management** engine active for robot mode output control
5151
- **PR dispatch** refactored to use `IncludeFragment` for per-project scoping (Refs #962)
5252
- **Test ranking knowledge graph fixture** added for agent testing
53+
- **LLM cost tracking** foundation with genai fork integration (Refs #1075)
54+
- **Spec validation** report for 2026-04-29 documenting 3 fixed, 5 remaining gaps
55+
- **Documentation gap report** generated for 2026-04-29 identifying 43 warnings across workspace
56+
57+
### Fixed
58+
59+
- **`--server` flag** on listen subcommand now routes through custom error handler
5360

5461
## [1.17.0] - 2026-04-27
5562

‎doc-reports/doc-gap-report-2026-04-29.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Documentation Gap Report
2+
3+
**Generated:** 2026-04-29 11:43 CEST
4+
**Agent:** Ferrox (documentation-generator)
5+
**Workspace:** terraphim-ai
6+
7+
## Summary
8+
9+
| Category | Count | Severity |
10+
|----------|-------|----------|
11+
| Broken doc links | 14 | Medium |
12+
| Missing crate-level docs | 24 | Medium |
13+
| Unclosed HTML tags | 7 | Low |
14+
| Non-hyperlinked URLs | 6 | Low |
15+
| Links to private items | 2 | Low |
16+
17+
**Total warnings:** 43
18+
19+
---
20+
21+
## 1. Broken Documentation Links (14)
22+
23+
### terraphim_orchestrator (6 links)
24+
- `RoutingDecisionEngine::decide_route` -- unresolved link
25+
- `DispatchTask::AutoMerge` -- unresolved link (3 occurrences)
26+
- `AgentOrchestrator::poll_pending_reviews` -- links to private item `reconcile_tick`
27+
- `GateConfig` -- unresolved link
28+
- `handle_post_merge_test_gate_for_project` -- unresolved link
29+
30+
### terraphim_file_search (1 link)
31+
- `ScoringContext` -- unresolved link
32+
33+
### terraphim_service (1 link)
34+
- `kg:term` -- unresolved link (likely needs proper module path)
35+
36+
### terraphim_middleware (4 links)
37+
- `with_change_notifications` -- unresolved link
38+
- `Message` -- unclosed HTML tag (also affects rendering)
39+
40+
### terraphim_router (1 link)
41+
- `set_commit_status` -- unresolved link
42+
43+
### terraphim_tracker (1 link)
44+
- `new` -- unresolved link
45+
46+
### terraphim_persistence (2 links)
47+
- `from_serializable` -- unresolved link
48+
49+
### terraphim_rolegraph (2 links)
50+
- `HgncGene` -- unresolved link
51+
- `HgncNormalizer` -- unresolved link
52+
53+
### terraphim_types (3 links)
54+
- Multiple unresolved (see cargo fix suggestion)
55+
56+
---
57+
58+
## 2. Missing Crate-Level Documentation (24 crates)
59+
60+
The following crates lack a top-level `//!` module doc comment in `src/lib.rs`:
61+
62+
### Haystack crates
63+
- `haystack_atlassian`
64+
- `haystack_core`
65+
- `haystack_discourse`
66+
- `haystack_grepapp`
67+
- `haystack_jmap`
68+
69+
### Agent & AI crates
70+
- `terraphim_agent`
71+
- `terraphim_agent_application`
72+
- `terraphim_agent_evolution`
73+
- `terraphim_agent_messaging`
74+
- `terraphim_agent_registry`
75+
- `terraphim_agent_supervisor`
76+
77+
### Core infrastructure
78+
- `terraphim_atomic_client`
79+
- `terraphim_automata_py`
80+
- `terraphim_build_args`
81+
- `terraphim_ccusage`
82+
- `terraphim_config`
83+
- `terraphim_file_search`
84+
- `terraphim_kg_linter`
85+
- `terraphim_lsp`
86+
- `terraphim-markdown-parser`
87+
- `terraphim_mcp_server`
88+
- `terraphim_middleware`
89+
- `terraphim_onepassword_cli`
90+
- `terraphim_persistence`
91+
- `terraphim_rolegraph`
92+
- `terraphim_rolegraph_py`
93+
- `terraphim_service`
94+
- `terraphim_settings`
95+
- `terraphim_usage`
96+
97+
---
98+
99+
## 3. HTML / Rendering Issues (7)
100+
101+
### Unclosed HTML tags
102+
- `terraphim_orchestrator`: `<name>` (4 occurrences)
103+
- `terraphim_orchestrator`: `<HandoffContext>` (1 occurrence)
104+
- `terraphim_middleware`: `<Message>` (1 occurrence)
105+
- `terraphim_persistence`: `<DeviceStorage>` (2 occurrences)
106+
107+
### Non-hyperlinked URLs
108+
- `terraphim_tinyclaw` (1)
109+
- `terraphim_service` (1)
110+
- `terraphim_middleware` (3)
111+
- `terraphim_tracker` (1)
112+
- `terraphim_rolegraph` (1)
113+
- `terraphim_types` (1)
114+
115+
---
116+
117+
## 4. Recommendations
118+
119+
### Immediate (next sprint)
120+
1. Fix all broken doc links in `terraphim_orchestrator` -- 14 warnings concentrated here
121+
2. Add `//!` crate-level docs to the 5 most-used crates:
122+
- `terraphim_agent`
123+
- `terraphim_service`
124+
- `terraphim_config`
125+
- `terraphim_persistence`
126+
- `terraphim_rolegraph`
127+
128+
### Short-term
129+
3. Fix HTML tag issues (escape `<` as `\<` or use backticks)
130+
4. Run `cargo fix --lib` on `terraphim_tinyclaw`, `terraphim_middleware`, `terraphim_tracker`, `terraphim_types` for auto-fixable warnings
131+
132+
### Process
133+
5. Enable `#![warn(missing_docs)]` in CI for new crates
134+
6. Add `cargo doc --no-deps` check to pre-commit hooks
135+
136+
---
137+
138+
## Appendix: Commands Used
139+
140+
```bash
141+
# Generate warnings
142+
cargo doc --workspace --no-deps 2>&1 | grep "warning:"
143+
144+
# Check for missing crate docs
145+
for crate_dir in crates/*/; do
146+
first_line=$(head -1 "${crate_dir}src/lib.rs")
147+
[[ ! "$first_line" =~ ^//! ]] && echo "$(basename $crate_dir): missing"
148+
done
149+
150+
# Check CHANGELOG
151+
git log --oneline --since="30 days ago"
152+
```

‎reports/documentation-gap-report-20260429.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Documentation Gap Report
2+
3+
**Generated:** 2026-04-29
4+
**Agent:** documentation-generator
5+
**Scope:** Workspace-wide rustdoc analysis (`cargo rustdoc --lib -- -D missing-docs`)
6+
7+
---
8+
9+
## Executive Summary
10+
11+
| Metric | Count |
12+
|--------|-------|
13+
| Crates scanned | 9 |
14+
| Total missing documentation items | **564** |
15+
| Crates with zero missing docs | 0 |
16+
| Worst offender | terraphim_server (138 items) |
17+
18+
---
19+
20+
## Per-Crate Breakdown
21+
22+
| Crate | Missing Items | Top Category |
23+
|-------|---------------|--------------|
24+
| terraphim_server | 138 | struct field (83) |
25+
| terraphim_service | 114 | struct field (50) |
26+
| terraphim_agent | 99 | struct field (66) |
27+
| terraphim_types | 79 | struct field (33) |
28+
| terraphim_config | 38 | variant (14) |
29+
| terraphim_middleware | 40 | variant (16) |
30+
| terraphim_persistence | 30 | module (5) |
31+
| terraphim_rolegraph | 22 | constant (6) |
32+
| haystack_core | 4 | crate (1) |
33+
34+
---
35+
36+
## Critical Gaps (User-Facing Public API)
37+
38+
### terraphim_agent
39+
40+
**Missing crate-level documentation** (`src/lib.rs:1`)
41+
- The crate root has no `//!` doc comment describing the agent's purpose.
42+
43+
**Missing module documentation**
44+
- `src/lib.rs:4` -- top-level module
45+
- `src/robot/mod.rs:7` -- robot module (core public API)
46+
47+
**Missing struct documentation**
48+
- `src/service.rs:13` -- main service struct
49+
- `src/robot/budget.rs:7` -- `TokenBudget` (public API for robot mode)
50+
- `src/robot/budget.rs:19` -- `BudgetManager`
51+
- `src/repl/handler.rs:28` -- `ReplHandler` (REPL entry point)
52+
53+
**Missing enum documentation**
54+
- `src/robot/budget.rs:14` -- `BudgetStrategy`
55+
- `src/repl/commands.rs:110` -- `SessionSubcommand`
56+
- `src/repl/commands.rs:135` -- `ConfigSubcommand`
57+
- `src/repl/commands.rs:141` -- `RoleSubcommand`
58+
59+
**Missing method/function documentation**
60+
- `src/robot/budget.rs:37` -- `BudgetManager::new`
61+
- `src/robot/budget.rs:42` -- `BudgetManager::check_budget`
62+
- `src/repl/handler.rs:38` -- `ReplHandler::new_offline`
63+
- `src/repl/handler.rs:67` -- `ReplHandler::run`
64+
65+
### terraphim_server
66+
67+
**Missing crate-level documentation** (`src/lib.rs:1`)
68+
69+
**Missing module documentation**
70+
- `src/lib.rs:139` -- workflows module
71+
- Multiple workflow submodules
72+
73+
**Missing struct documentation**
74+
- `src/lib.rs:179` -- server state struct
75+
- `src/api.rs:66` -- API request/response types
76+
- `src/api.rs:231` -- additional API types
77+
78+
**Missing function documentation**
79+
- `src/lib.rs:185` -- public server function
80+
- `src/lib.rs:650` -- public utility function
81+
- 19 other public functions in API modules
82+
83+
### terraphim_service
84+
85+
**Missing crate-level documentation** (`src/lib.rs:1`)
86+
87+
**Missing module documentation** (9 modules)
88+
- All re-exported submodules lack `//!` docs
89+
90+
### terraphim_types
91+
92+
**Missing module documentation**
93+
- `src/lib.rs:100` -- types module
94+
95+
**Missing enum documentation**
96+
- `src/lib.rs:470` -- core data type enum
97+
98+
**Missing struct documentation**
99+
- `src/lib.rs:478` -- public data struct
100+
- `src/lib.rs:487` -- public data struct
101+
102+
---
103+
104+
## API Reference Snippets (Partial)
105+
106+
### terraphim_agent::robot::budget
107+
108+
```rust
109+
/// Manages token budgets for robot mode output control.
110+
pub struct BudgetManager { ... }
111+
112+
/// Strategy for enforcing token budgets.
113+
pub enum BudgetStrategy { ... }
114+
```
115+
116+
### terraphim_agent::repl
117+
118+
```rust
119+
/// Handles REPL command execution and dispatch.
120+
pub struct ReplHandler { ... }
121+
122+
/// Top-level CLI commands for the terraphim-agent REPL.
123+
pub enum Command { ... }
124+
```
125+
126+
---
127+
128+
## Recommendations
129+
130+
1. **Priority 1:** Add crate-level `//!` documentation to all 9 crates. This is the first thing users see on docs.rs.
131+
132+
2. **Priority 2:** Document all public structs and enums in `terraphim_agent::robot` and `terraphim_agent::repl`. These are user-facing CLI APIs.
133+
134+
3. **Priority 3:** Document `terraphim_server` API types (`src/api.rs`). These define the HTTP contract.
135+
136+
4. **Priority 4:** Add module-level documentation to all undocumented modules in `terraphim_service` and `terraphim_middleware`.
137+
138+
5. **Ongoing:** Enable `#![warn(missing_docs)]` at crate root to prevent regression.
139+
140+
---
141+
142+
## Changelog Updates Required
143+
144+
The following commits since the last CHANGELOG update (026c6b54f) need entries:
145+
146+
- `feat(usage):` add LLM cost tracking foundation with genai fork integration (Refs #1075)
147+
- `fix(agent):` allow --server flag on listen subcommand so custom error handler runs
148+
- `docs(spec):` validation report 2026-04-29 -- FAIL, 3 fixed 5 remaining
149+
150+
---
151+
152+
*Report generated by documentation-generator agent.*

0 commit comments

Comments
 (0)