docs(project): fix package documentation inconsistencies and regenerate coupling report#1902
Merged
josecelano merged 16 commits intoJun 11, 2026
Conversation
There was a problem hiding this comment.
Pull request overview
This PR performs documentation maintenance for EPIC #1669 (“Overhaul: packages”) by aligning package/architecture docs with the current workspace structure, adding a workspace dependency Mermaid diagram, and adding updated workspace coupling reports for tracking dependency reductions over time.
Changes:
- Updated package documentation (
docs/packages.md,packages/AGENTS.md, EPIC checklist) to remove/rename “ghost” packages and reflect extracted crates. - Added a new Mermaid dependency diagram for workspace packages and external
torrust-*crates. - Added/updated workspace coupling report artifacts (baseline + regenerated).
Reviewed changes
Copilot reviewed 6 out of 7 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
project-words.txt |
Adds “leafification” to the project dictionary. |
packages/AGENTS.md |
Updates architecture diagram and package catalog/extracted packages tables. |
docs/packages.md |
Updates workspace package listing, package catalog, and extracted packages table. |
docs/media/packages/dependencies-workspace-packages.md |
Adds a new Mermaid diagram of workspace package dependencies. |
docs/issues/open/1669-overhaul-packages/workspace-coupling-report-2026-06-10.md |
Adds regenerated coupling report for 2026-06-10. |
docs/issues/open/1669-overhaul-packages/workspace-coupling-report-2026-05-19.md |
Adds/preserves baseline coupling report for 2026-05-19. |
docs/issues/open/1669-overhaul-packages/EPIC.md |
Adds links and a documentation audit checklist to keep docs aligned with reality. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Thin dependencies: 6 edges identified with easy elimination paths - Cluster dependencies: 3 architectural concern areas documented - Layer violation: tracker-core -> configuration Driver enum flagged - Prioritization table with estimated effort per improvement item
- docs/issues/open/1669-overhaul-packages/workspace-coupling-report-2026-06-10.md: add YAML frontmatter for consistency with other issue artifacts - docs/packages.md: remove InfoHash from primitives description (it is an external dependency, not re-exported) - packages/AGENTS.md: remove InfoHash from primitives description; add located-error to the Extracted Packages table (it was in the ASCII diagram but missing from the table)
- workspace-coupling-report-2026-06-10.md: correct the e2e-tools finding (uses torrust_tracker_lib:: not torrust_tracker::, so the scan missed it) - docs/packages.md: automatic formatting alignment fix
- docs/packages.md: fix tracker-client label (it is a library crate, not a CLI client; the CLI client is at console/tracker-client) - workspace-coupling-report-2026-06-10.md: fix config dep note (still depends on primitives for AnnouncePolicy) - dependencies-workspace-packages.md: add YAML frontmatter with semantic-links for docs graph consistency
Split into "worth investigating" (actionable) and "acceptable" (not worth addressing) to clarify which edges are real problems vs architecturally expected. Remove tracker-core → events from prioritization table accordingly.
Re-exporting RecvError through an intermediate package would create a hidden transitive dependency. Better to keep the direct and honest declaration.
Subissue of EPIC torrust#1669. Covers removal of the udp-protocol re-export of PeerId/PeerClient with scope and ACs for all 4 consumers. Update coupling report to reference the draft spec.
Moves axum-server -> TslConfig from "worth investigating" to "acceptable" with links to DEC-08 decision record and closed issue torrust#1860. Removes from prioritization table accordingly.
…ale layer violation - docs/issues/drafts/1669-move-driver-enum-to-primitives.md: new draft spec for moving Driver enum from configuration to primitives - workspace-coupling-report-2026-06-10.md: add new "Domain concept misplacement" section for Driver; remove stale "Layer violation" section; update prioritization table
- DECISIONS.md: add DEC-11 documenting the decision to accept the udp-server -> client-lib dependency for health checks - workspace-coupling-report: update acceptable deps to reference DEC-11
…eport - DECISIONS.md: add DEC-12 documenting the decision to accept http-tracker-core -> tracker-core coupling as by design - workspace-coupling-report: update cluster dep finding with import breakdown and reference to DEC-12
- DECISIONS.md: add DEC-13 for relocating server test environment infrastructure to src/testing/ - Replace combined axum-rest-api-server draft with 3 focused relocation drafts (one per server package) and updated rest-api-core production decoupling draft - Add explicit dependency relationships between subissues
…d draft references
Member
Author
|
ACK 4d686fe |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documentation maintenance and coupling analysis across EPIC #1669.
Package docs fixes
packages/AGENTS.mdand the dependency diagram; add documentation audit checklist to the Scope sectiontorrent-repositorydirectory, add missinge2e-tools,events,persistence-benchmark,swarm-coordination-registry; fix Package Catalog entriestorrent-repositoryfrom diagram and catalog; fixprimitivesdescription; remove extracted packages table (redundant — extracted crates are normal Cargo dependencies)Dependency diagram
docs/media/packages/dependencies-workspace-packages.mdshowing all 22 workspace packages across 7 layers plus 7 externaltorrust-*cratesWorkspace coupling reports
workspace-coupling-report-2026-05-19.mdworkspace-coupling-report-2026-06-10.mdwith:Draft subissues created (EPIC #1669)
udp-protocolPeerId re-export —docs/issues/drafts/1669-remove-udp-protocol-peer-id-re-export.mdDriverenum toprimitives—docs/issues/drafts/1669-move-driver-enum-to-primitives.mdrest-api-corefrom UDP internals (production code) —docs/issues/drafts/1669-decouple-rest-api-core-from-udp-internals.mdaxum-rest-api-servertest environment —docs/issues/drafts/1669-relocate-axum-rest-api-server-test-environment.mdudp-servertest environment —docs/issues/drafts/1669-relocate-udp-server-test-environment.mdaxum-http-servertest environment —docs/issues/drafts/1669-relocate-http-server-test-environment.mdDecisions recorded
http-tracker-core→tracker-corecoupling as by designsrc/testing/Copilot PR review comments
All 11 Copilot review comments resolved with fixes and explanations.
Verification
cargo machete— passlinter all— passcargo test --doc --workspace— pass