ossctl_core/protocol/facts.rs
1//! Public wire DTO for the deterministic repo-fact report (`ossctl facts`).
2//!
3//! This is the versioned surface `/oss-init` (config generation) and the
4//! readiness `audit` both read, so they never disagree on maturity or the gated
5//! core (ADR-0001 §3). Its field names and shape are a faithful port of
6//! homebase's `infer-repo-facts.py` JSON — `ecosystems`, `packages`, `has_ci`,
7//! `tags`, `committers_total`/`committers_recent_year`, `inferred_maturity`, and
8//! the rest — because the prose `/oss-init` skill already relies on those exact
9//! names (SCHEMA.md §4 "maturity inference signals").
10//!
11//! Consumers read this document under the CLI's canonical `data` envelope:
12//! `{schema_version, data: <this shape>, warnings}` — the same envelope every
13//! `ossctl --json` command shares (`crate::SCHEMA_VERSION` versions that wire
14//! envelope). Unlike the contract document, the facts report has no
15//! source-level document version of its own (it is *derived*, never authored),
16//! so the envelope's `schema_version` is the single version consumers gate on.
17//!
18//! The report **reuses** [`Ecosystem`] and [`Maturity`] from the canonical
19//! contract model rather than restating their wire strings: facts and the
20//! contract must agree on `"rust"` / `"mvp"` down to the byte, and sharing the
21//! one enum is how that agreement is made structural instead of coincidental.
22
23use serde::Serialize;
24
25use crate::contract::schema::{Ecosystem, Maturity};
26
27/// The deterministic repo-fact report — a pure function of `(repo tree, git
28/// HEAD)`, emitted by `ossctl facts` and consumed by `/oss-init` and `audit`.
29///
30/// Every field is always present (an empty/unborn repo still gets a defined
31/// value for each), mirroring the Python detector's "exit 0 even for an empty
32/// repo" contract.
33// The report mirrors the Python detector's flat boolean signals; grouping them
34// into sub-structs purely to satisfy the bool-count lint would diverge the wire
35// shape from `infer-repo-facts.py` for no consumer benefit.
36#[allow(clippy::struct_excessive_bools)]
37#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
38pub struct Facts {
39 /// The canonicalized repository root the facts were gathered from.
40 pub repo_root: String,
41 /// Whether the root is inside a git work tree.
42 pub is_git: bool,
43 /// Whether the repository has at least one commit (`HEAD` resolves).
44 pub has_commits: bool,
45 /// Detected packaging ecosystems, in canonical order. `[binary]` when no
46 /// package manifest is found (a compiled-artifact-only repo).
47 pub ecosystems: Vec<Ecosystem>,
48 /// One entry per root-level package manifest that names a package (plus
49 /// `Cargo.toml`/`go.mod` always, even as a virtual workspace).
50 pub packages: Vec<Package>,
51 /// Distinct committers across all history (`git shortlog -sne --all`).
52 pub committers_total: usize,
53 /// Distinct committers within the last year — a `production` signal.
54 pub committers_recent_year: usize,
55 /// All tag names in the repository.
56 pub tags: Vec<String>,
57 /// Whether any tag parses as a `SemVer` version (a release signal).
58 pub has_semver_tag: bool,
59 /// Whether a `>=1.0` release exists — a `>=1.0` `SemVer` tag **or** a manifest
60 /// version `>=1.0`. Never probes a registry (that would need the network and
61 /// break reproducibility).
62 pub has_ge_1_0_release: bool,
63 /// Whether a CI configuration is present (`.github/workflows` holding at
64 /// least one entry, or a known single-file CI config).
65 pub has_ci: bool,
66 /// The detected dependency-update bot (`dependabot` / `renovate`), or `null`.
67 pub dependency_bot: Option<String>,
68 /// Whether an `issues/` directory is present.
69 pub has_issues_dir: bool,
70 /// `"spike"` when the README self-labels as pre-release/WIP, else `null`.
71 pub readme_self_label: Option<String>,
72 /// A short project description: the first manifest `description`, else the
73 /// first non-heading README line (both truncated to 120 characters).
74 pub description: Option<String>,
75 /// The raw truth-table signals behind [`Self::inferred_maturity`].
76 pub maturity_signals: MaturitySignals,
77 /// The inferred maturity (SCHEMA.md §4 truth table, tie → `mvp`).
78 pub inferred_maturity: Maturity,
79 /// The Rust workspace's publishable member graph — derived plumbing the
80 /// release planner needs, deliberately kept **off the JSON wire**
81 /// (`#[serde(skip)]`), `None` for a repo with no multi-crate Cargo workspace.
82 ///
83 /// It lets [`crate::release::plan`] derive the full, dependency-ordered publish
84 /// set for a multi-crate workspace: a downstream repo that declares only its bin
85 /// crate as a release target still gets its lib crate planned, lib-before-bin, so
86 /// `cargo publish` never hits an unindexed `=`-pinned sibling (the
87 /// `release-rust-workspace-multicrate` gap). Exposing it on the wire would perturb
88 /// the shared facts schema `/oss-init` and `audit` read; the plan content-addresses
89 /// the resolved *targets* it produces from this graph, so the graph itself need not
90 /// travel on the wire. Skipped fields still participate in [`PartialEq`], so it is a
91 /// faithful part of the in-process fact value.
92 #[serde(skip)]
93 pub rust_workspace: Option<RustWorkspace>,
94}
95
96/// A Rust Cargo workspace's crates.io-**publishable** members and the
97/// intra-workspace dependency edges among them — the graph the release planner
98/// derives a dependency-ordered publish set from (`release-rust-workspace-multicrate`).
99///
100/// Off-wire plumbing carried on [`Facts::rust_workspace`]; see that field for why it
101/// is not serialized. Members are listed in workspace declaration order (the planner
102/// applies the topological ordering — a dependency before its dependents); only
103/// members publishable to crates.io are included (a `publish = false` member, or one
104/// restricted to a non-crates.io registry, is dropped, matching the cargo adapter's
105/// cut-time `cargo metadata` filter).
106#[derive(Debug, Clone, PartialEq, Eq)]
107pub struct RustWorkspace {
108 /// The publishable workspace members, in declaration order.
109 pub members: Vec<WorkspaceMember>,
110}
111
112/// One crates.io-publishable Cargo workspace member and its intra-workspace
113/// (publishable) dependency crate names — a node in [`RustWorkspace`].
114#[derive(Debug, Clone, PartialEq, Eq)]
115pub struct WorkspaceMember {
116 /// The crate/package name (`[package].name`).
117 pub package: String,
118 /// The member's declared/inherited version, or `None` when unresolved.
119 pub version: Option<String>,
120 /// The names of this member's dependencies that are themselves publishable
121 /// members of the same workspace — the edges that order the publish (each of
122 /// these must be crates.io-index-visible before this member can publish). Only
123 /// normal + build dependencies gate order; dev-dependencies are excluded (they
124 /// never gate publish order and can legitimately cycle).
125 pub workspace_deps: Vec<String>,
126 /// The **literal version requirement string** this member's manifest declares
127 /// for each intra-workspace dependency that carries one, keyed by dependency
128 /// crate name (e.g. `{"octl-core": "=0.4.0"}` for `octl-core = { path = "…",
129 /// version = "=0.4.0" }`). Only edges present in [`Self::workspace_deps`] appear,
130 /// and only when the manifest declares an explicit `version` on the dependency —
131 /// a path-only or `workspace = true`-inherited edge (whose requirement is not
132 /// literally in this manifest) is **absent**, not defaulted.
133 ///
134 /// This is what makes the bump phase's pin rewrite **precise**
135 /// (`release-rust-workspace-multicrate` facet 3): the planner emits a pin rewrite
136 /// only for an edge whose requirement literally equals `=<from_version>` (the
137 /// lockstep convention), never for a caret/range/`workspace = true` edge it would
138 /// otherwise clobber. Off-wire, like the rest of [`RustWorkspace`].
139 pub dep_reqs: std::collections::BTreeMap<String, String>,
140}
141
142/// One detected package manifest and the name/version parsed from it.
143// `package` is the field name `/oss-init` reads (SCHEMA.md §4); the
144// struct-name-echo lint does not apply to a fixed wire contract.
145#[allow(clippy::struct_field_names)]
146#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
147pub struct Package {
148 /// The ecosystem this manifest belongs to.
149 pub ecosystem: Ecosystem,
150 /// The manifest filename (e.g. `Cargo.toml`, `package.json`).
151 pub manifest: String,
152 /// The package/crate name, or `null` when the manifest declares none
153 /// (a virtual `Cargo.toml` workspace, or a `go.mod` without a `module`).
154 pub package: Option<String>,
155 /// The declared version, or `null` when absent.
156 pub version: Option<String>,
157}
158
159/// The two maturity truth-table outputs (SCHEMA.md §4). Both can be `false`
160/// (the tie case), which resolves to `mvp`; they are never both `true`
161/// (`production` is checked first).
162#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
163pub struct MaturitySignals {
164 /// `>=2` recent-year committers **and** CI **and** a release gate. The
165 /// release gate is either a `>=1.0` release **or** `ZeroVer` release evidence:
166 /// a dependency-update-bot config present **and** a release cadence of `>=2`
167 /// shipped (non-prerelease, `>=0.1.0`) `SemVer` tags. The second path lets a
168 /// deliberately-pre-1.0 (`ZeroVer`) project reach `production` without a
169 /// `>=1.0` version. The shipped-release count is not a first-class field but
170 /// is recomputable from [`Facts::tags`] with the same `SemVer` parse. These
171 /// are presence/name heuristics, not proofs — `/oss-init` presents them to a
172 /// human for confirmation before they land in the contract.
173 pub production: bool,
174 /// No CI **and** no `SemVer` tag **and** (single committer **or** a README
175 /// self-label).
176 pub spike: bool,
177}