docs(readme): document crate layout and parsing-vs-rendering boundary (FJ-19) #18

Merged

David merged 1 commit from docs/document-crate-layout-parsing-rendering-boundary-fj-19 into main

2026-05-27 02:57:17 +02:00

David commented

2026-05-27 01:29:33 +02:00

Owner

What

Adds an Architecture section to README.md documenting the Cargo workspace layout and the parsing-vs-rendering crate boundary, so the fj-client / fj-core reuse contract is discoverable from the project's main entry point rather than only from a crates/fj-core/src/lib.rs docstring. Resolves FJ-19.

Changes

Documents the three workspace members and their roles: fj-client (connection / credentials / keys.json / client construction / URL+SSH resolution), fj-core (CLI-agnostic domain operations returning forgejo-api structs, the issue-template parser, shared types like RepoName), and fj (the binary: clap, crossterm, fluent, interactive prompts, all rendering).
States that fj-client / fj-core are CLI-free and the dependency target for the planned Forgejo MCP, banning clap / crossterm / fluent-*, and reproduces the cargo tree ... | grep -E 'clap|crossterm|fluent' verify grep verbatim so the README and the verify check agree.
Calls out comrak as the one intentional exception: it powers the issue-template parser in fj-core (parsing, which an MCP consumer needs) and is deliberately not part of the grep; ANSI / terminal markdown rendering stays in the fj binary.
Shows how a downstream app references the crates via a git dependency pinned to a release tag (v0.6.0), with the Forgejo Cargo package registry noted as an optional path.

Acceptance criteria

README documents the three crates and their roles.
States fj-client / fj-core are CLI-free and reusable (MCP target), banning clap / crossterm / fluent-*.
Explicitly notes comrak is allowed in fj-core as the issue-template parser; rendering stays in fj.
Shows how a downstream app references the crates (git dependency; Forgejo Cargo registry as optional path).
CLI-free grep reconciled to ban clap / crossterm / fluent only: the documented grep in CLAUDE.md:24 already excludes comrak, and the README now states the same rule, so README and verify check agree. Confirmed cargo tree -p fj-client -p fj-core -e normal | grep -E 'clap|crossterm|fluent' returns nothing.

Notes

Docs-only change; no Rust touched. Committed with a bare #FJ-19 reference (no State Done trailer): the Forgejo VCS integration applies commit commands at push time, so a State Done trailer would resolve the issue before review. Per the YouTrack workflow, State Done is set manually after a human merges.

## What Adds an **Architecture** section to `README.md` documenting the Cargo workspace layout and the parsing-vs-rendering crate boundary, so the `fj-client` / `fj-core` reuse contract is discoverable from the project's main entry point rather than only from a `crates/fj-core/src/lib.rs` docstring. Resolves FJ-19. ## Changes - Documents the three workspace members and their roles: `fj-client` (connection / credentials / `keys.json` / client construction / URL+SSH resolution), `fj-core` (CLI-agnostic domain operations returning `forgejo-api` structs, the issue-template parser, shared types like `RepoName`), and `fj` (the binary: clap, crossterm, fluent, interactive prompts, all rendering). - States that `fj-client` / `fj-core` are CLI-free and the dependency target for the planned Forgejo MCP, banning `clap` / `crossterm` / `fluent-*`, and reproduces the `cargo tree ... | grep -E 'clap|crossterm|fluent'` verify grep verbatim so the README and the verify check agree. - Calls out `comrak` as the one intentional exception: it powers the issue-template parser in `fj-core` (parsing, which an MCP consumer needs) and is deliberately not part of the grep; ANSI / terminal markdown rendering stays in the `fj` binary. - Shows how a downstream app references the crates via a git dependency pinned to a release tag (`v0.6.0`), with the Forgejo Cargo package registry noted as an optional path. ## Acceptance criteria - [x] README documents the three crates and their roles. - [x] States `fj-client` / `fj-core` are CLI-free and reusable (MCP target), banning `clap` / `crossterm` / `fluent-*`. - [x] Explicitly notes `comrak` is allowed in `fj-core` as the issue-template parser; rendering stays in `fj`. - [x] Shows how a downstream app references the crates (git dependency; Forgejo Cargo registry as optional path). - [x] CLI-free grep reconciled to ban `clap` / `crossterm` / `fluent` only: the documented grep in `CLAUDE.md:24` already excludes `comrak`, and the README now states the same rule, so README and verify check agree. Confirmed `cargo tree -p fj-client -p fj-core -e normal | grep -E 'clap|crossterm|fluent'` returns nothing. ## Notes Docs-only change; no Rust touched. Committed with a bare `#FJ-19` reference (no `State Done` trailer): the Forgejo VCS integration applies commit commands at push time, so a `State Done` trailer would resolve the issue before review. Per the YouTrack workflow, `State Done` is set manually after a human merges.

David added 1 commit

2026-05-27 01:29:33 +02:00

docs(readme): document crate layout and parsing-vs-rendering boundary

Check / fmt + clippy + build + tests (pull_request) Successful in 37s

Details

Create release / Create release from merged PR (pull_request) Has been skipped

Details

faf6b7bcda

Add an Architecture section to README.md so the workspace layout and the fj-client / fj-core reuse contract are discoverable from the project's main entry point instead of only a lib.rs docstring.

The section documents the three workspace members and their roles, states that fj-client and fj-core are CLI-free and the dependency target for the planned Forgejo MCP (banning clap / crossterm / fluent-*), and gives the cargo tree verify grep verbatim so the README and the verify check agree. It calls out comrak as the one intentional exception: it powers the issue-template parser in fj-core (parsing, which an MCP consumer needs) and is deliberately not in the grep, while ANSI / terminal markdown rendering stays in the fj binary. It also shows how a downstream app references the crates via a git dependency pinned to a release tag, with the Forgejo Cargo package registry as an optional path.

#FJ-19