crates/forge/ents-forge/src/review/cli.rs
| 1 | //! `git ents review`'s argument grammar — `figue` derive definitions only. |
| 2 | //! |
| 3 | //! Per this project's engineering conventions, this module carries no |
| 4 | //! logic: every doc comment here becomes `--help` text, and `git-ents`'s |
| 5 | //! own `exe` module is the only place a [`ReviewAction`] variant is |
| 6 | //! interpreted. |
| 7 | |
| 8 | use std::path::PathBuf; |
| 9 | |
| 10 | use ents_attrs as ents; |
| 11 | use facet::Facet; |
| 12 | use figue as args; |
| 13 | |
| 14 | /// `git ents review` actions. |
| 15 | #[derive(Facet)] |
| 16 | #[repr(u8)] |
| 17 | pub enum ReviewAction { |
| 18 | /// Review a commit: a verdict plus a body, occupying two refs — the |
| 19 | /// review's own entity ref at `refs/meta/reviews/<target>/<member>`, and |
| 20 | /// a retention pin at `refs/meta/pins/reviews/<target>/<member>` keeping |
| 21 | /// the reviewed commit (and its ancestry) reachable. Re-reviewing after |
| 22 | /// the target moves advances the same two refs fast-forward rather than |
| 23 | /// minting new ones. |
| 24 | New { |
| 25 | /// Revision to review. |
| 26 | #[facet(args::named, default = "HEAD")] |
| 27 | target: String, |
| 28 | /// The review's verdict, e.g. approve or request-changes; custom |
| 29 | /// values are schema, not a platform feature. |
| 30 | #[facet(args::named)] |
| 31 | verdict: String, |
| 32 | /// The review's body text; omit to compose it in |
| 33 | /// $GIT_EDITOR/$EDITOR instead (lines starting with '#' are |
| 34 | /// stripped, and an empty body aborts the command). |
| 35 | #[facet(args::named, ents::compose)] |
| 36 | body: Option<String>, |
| 37 | /// Key to sign with; defaults to `user.signingkey`. |
| 38 | #[facet(args::named)] |
| 39 | key: Option<PathBuf>, |
| 40 | }, |
| 41 | /// Withdraw this member's own review: writes a new `Withdrawn`-state |
| 42 | /// entity onto the *same* two refs the original review occupies, |
| 43 | /// preserving its verdict and body — append-only, so the prior verdict |
| 44 | /// stays in the ref's history. Refuses when this member has no |
| 45 | /// existing review reaching `target`. |
| 46 | Withdraw { |
| 47 | /// Revision identifying the review to withdraw: resolved exactly |
| 48 | /// as `new`'s own target and re-review advance are, so a |
| 49 | /// descendant of the reviewed commit still finds it. |
| 50 | #[facet(args::named, default = "HEAD")] |
| 51 | target: String, |
| 52 | /// Key to sign with; defaults to `user.signingkey`. |
| 53 | #[facet(args::named)] |
| 54 | key: Option<PathBuf>, |
| 55 | }, |
| 56 | /// List the reviews recorded in this repository. |
| 57 | /// |
| 58 | /// With --porcelain, emits a stable machine-readable form: |
| 59 | /// blank-line-separated records, each starting with the line |
| 60 | /// `<target> <member> <reviewed> <verdict> <state>` — target the |
| 61 | /// review's full genesis-oid ref segment, reviewed the full oid of the |
| 62 | /// most recently reviewed commit — followed by the body with every |
| 63 | /// line prefixed by one tab. |
| 64 | List { |
| 65 | /// Keep only reviews of this revision. |
| 66 | #[facet(args::named)] |
| 67 | target: Option<String>, |
| 68 | /// Emit the stable machine-readable form described above. |
| 69 | #[facet(args::named, default)] |
| 70 | porcelain: bool, |
| 71 | }, |
| 72 | /// Show one review: its reviewed commit, verdict, body, and discussion |
| 73 | /// thread (comments naming it as their context). |
| 74 | Show { |
| 75 | /// The review's genesis target segment (`refs/meta/reviews/<target>/*`). |
| 76 | #[facet(args::positional)] |
| 77 | target: String, |
| 78 | /// The reviewer's member id (`refs/meta/reviews/*/<member>`). |
| 79 | #[facet(args::positional)] |
| 80 | member: String, |
| 81 | }, |
| 82 | } |