Skip to content
Sign in

flagon-io/g1t

public
0

g1t/crates/contracts/src/about.rs

390 lines13,741 bytesCodeBlame
1//! A repository's About, as its Files page shows it beside the files: what
2//! its files say about it (its license, its security policy and the
3//! languages it is written in), who made it (its contributors), who starred
4//! it, and its releases. Methods of the repos service.
5//!
6//! What is read from history and files is worked out in the background for
7//! the default branch's head and kept by commit (services/repos/src/stats.rs),
8//! never on the way to a page: an answer can be for an older commit
9//! (`commit` is not `head`) while the newer one is worked out, or `pending`
10//! when nothing has been worked out yet.
11
12use serde::{Deserialize, Serialize};
13
14use crate::repos::{RepoPath, Repo};
15use crate::{User, Viewer};
16
17/// One language's share of a repository's code, by bytes.
18#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
19#[serde(rename_all = "camelCase")]
20pub struct LanguageShare {
21 pub name: String,
22 /// `#rrggbb`, the color it is known by; null for one without.
23 pub color: Option<String>,
24 pub bytes: u64,
25 /// Of the bytes counted, to one decimal place.
26 pub percent: f64,
27}
28
29/// The license a repository's LICENSE (or COPYING) file holds.
30#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
31#[serde(rename_all = "camelCase")]
32pub struct License {
33 /// Its SPDX identifier, such as `MIT` or `Apache-2.0`; null when the
34 /// text is not one g1t recognizes.
35 pub spdx_id: Option<String>,
36 /// What people call it: "MIT License", or "Other" when unrecognized.
37 pub name: String,
38 /// The file it was read from, from the root: `LICENSE`.
39 pub path: String,
40}
41
42/// Who a contributor is: a person with an account (their commits' address
43/// is one they confirmed), g1t itself, or an author g1t cannot match to an
44/// account.
45#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
46#[serde(rename_all = "snake_case")]
47pub enum ContributorKind {
48 User,
49 G1t,
50 Author,
51}
52
53/// Commits in one week, the week named by its Monday (`YYYY-MM-DD`, UTC).
54#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
55pub struct WeekCommits {
56 pub week: String,
57 pub commits: u32,
58}
59
60/// Someone whose commits are on the default branch.
61#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
62#[serde(rename_all = "camelCase")]
63pub struct Contributor {
64 pub kind: ContributorKind,
65 /// Their username for a `user` (and `g1t` for g1t); the name on their
66 /// commits otherwise.
67 pub name: String,
68 /// The account's username, for a `user`.
69 #[serde(default)]
70 pub username: Option<String>,
71 /// The uploaded avatar's hash, for a `user` who has one.
72 #[serde(default)]
73 pub avatar: Option<String>,
74 pub commits: u32,
75 /// RFC 3339: their first and latest commit read.
76 pub first_at: String,
77 pub last_at: String,
78 /// Their commits by week, oldest first, the weeks with none left out.
79 /// Only for the most active contributors (`MAX_CONTRIBUTOR_WEEKS` of
80 /// them); empty for the rest and in the About summary.
81 #[serde(default)]
82 pub weeks: Vec<WeekCommits>,
83}
84
85/// The most contributors kept for a repository.
86pub const MAX_CONTRIBUTORS: usize = 500;
87/// The contributors whose commits are kept week by week.
88pub const MAX_CONTRIBUTOR_WEEKS: usize = 100;
89/// The contributors the About summary names.
90pub const ABOUT_CONTRIBUTORS: usize = 14;
91
92/// Where an answer worked out from the default branch stands.
93#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
94#[serde(rename_all = "camelCase")]
95pub struct Freshness {
96 /// The default branch's head now; null for an empty repository.
97 pub head: Option<String>,
98 /// The commit the answer was worked out for; null when none has been.
99 pub commit: Option<String>,
100 /// RFC 3339: when it was.
101 pub computed_at: Option<String>,
102 /// Nothing has been worked out yet; it is under way. Ask again shortly.
103 pub pending: bool,
104 /// The history or the files were too large to read in full, so the
105 /// answer counts what was read.
106 pub partial: bool,
107}
108
109/// `languages`: a repository's languages by bytes, largest first.
110#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
111#[serde(rename_all = "camelCase")]
112pub struct Languages {
113 #[serde(flatten)]
114 pub freshness: Freshness,
115 pub languages: Vec<LanguageShare>,
116}
117
118/// `contributors`: everyone whose commits are on the default branch, most
119/// commits first, and the repository's commits by week.
120#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
121#[serde(rename_all = "camelCase")]
122pub struct Contributors {
123 #[serde(flatten)]
124 pub freshness: Freshness,
125 /// How many there are; `contributors` lists at most `MAX_CONTRIBUTORS`.
126 pub total: u32,
127 /// The commits read.
128 pub commits: u32,
129 pub contributors: Vec<Contributor>,
130 /// Every commit read, by week, oldest first, including empty weeks.
131 pub weeks: Vec<WeekCommits>,
132}
133
134/// A release: a tag, published with a title and notes.
135#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
136#[serde(rename_all = "camelCase")]
137pub struct Release {
138 /// `rel_…`.
139 pub id: String,
140 pub tag_name: String,
141 /// The commit the tag named when the release was made.
142 pub target: String,
143 /// Its title; the tag's name when it has none.
144 pub name: Option<String>,
145 /// Its notes, Markdown.
146 pub body: String,
147 /// Seen only by those who can push until it is published.
148 pub draft: bool,
149 /// Not ready for everyone: never the latest release.
150 pub prerelease: bool,
151 /// The username of who made it.
152 pub author: Option<String>,
153 /// RFC 3339.
154 pub created_at: String,
155 /// RFC 3339; null while it is a draft.
156 pub published_at: Option<String>,
157 /// Whether it is the latest release: the newest published one that is
158 /// neither a draft nor a prerelease.
159 #[serde(default)]
160 pub latest: bool,
161}
162
163/// The longest release title, and the longest notes.
164pub const MAX_RELEASE_NAME_CHARS: usize = 200;
165pub const MAX_RELEASE_BODY_CHARS: usize = 125_000;
166
167/// Someone who starred a repository.
168#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
169#[serde(rename_all = "camelCase")]
170pub struct Stargazer {
171 pub username: String,
172 pub avatar: Option<String>,
173 /// RFC 3339.
174 pub starred_at: String,
175}
176
177/// A repository someone starred.
178#[derive(Clone, Debug, Serialize, Deserialize)]
179#[serde(rename_all = "camelCase")]
180pub struct StarredRepo {
181 pub repo: Repo,
182 /// RFC 3339.
183 pub starred_at: String,
184 pub stars: u64,
185}
186
187/// Whether the viewer starred a repository, and how many have.
188#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
189#[serde(rename_all = "camelCase")]
190pub struct Stars {
191 pub starred: bool,
192 pub stars: u64,
193}
194
195/// The About of a repository's Files page, in one answer: what is kept for
196/// the default branch's head, the stars and the releases.
197#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
198#[serde(rename_all = "camelCase")]
199pub struct RepoAbout {
200 #[serde(flatten)]
201 pub freshness: Freshness,
202 pub license: Option<License>,
203 /// The path of its security policy (SECURITY.md at the root, or in
204 /// `.g1t`, `.github` or `docs`), when it has one.
205 pub security_policy: Option<String>,
206 pub languages: Vec<LanguageShare>,
207 /// How many contributors there are, and the most active
208 /// (`ABOUT_CONTRIBUTORS`), without their weeks.
209 pub contributors: u32,
210 pub top_contributors: Vec<Contributor>,
211 pub stars: u64,
212 pub starred: bool,
213 /// Published releases the viewer can see, drafts left out unless they
214 /// can push.
215 pub releases: u64,
216 pub latest_release: Option<Release>,
217}
218
219/// `about`, `languages`, `contributors`, `license`, `stars` and
220/// `releases`: one repository, for the viewer. `about` returns
221/// `Outcome<RepoAbout>`, `languages` `Outcome<Languages>`, `contributors`
222/// `Outcome<Contributors>`, `license` `Outcome<Option<License>>`, `stars`
223/// `Outcome<Stars>` and `releases` `Outcome<Vec<Release>>` (newest first,
224/// at most 100).
225#[derive(Debug, Serialize, Deserialize)]
226pub struct RepoViewArgs {
227 pub path: RepoPath,
228 pub viewer: Viewer,
229}
230
231/// `star`: stars the repository for the actor, or takes their star back.
232/// Returns `Outcome<Stars>`.
233#[derive(Debug, Serialize, Deserialize)]
234pub struct StarArgs {
235 pub path: RepoPath,
236 pub actor: User,
237 pub starred: bool,
238}
239
240/// `stargazers`: who starred a repository, newest first, 100 a page;
241/// `page` from 1. Returns `Outcome<Vec<Stargazer>>`.
242#[derive(Debug, Serialize, Deserialize)]
243pub struct StargazersArgs {
244 pub path: RepoPath,
245 pub viewer: Viewer,
246 #[serde(default)]
247 pub page: Option<u32>,
248}
249
250/// `starred`: the repositories a person starred that the viewer can see,
251/// newest first, at most 100. The person by `username`. Returns
252/// `Vec<StarredRepo>`; empty for an unknown person.
253#[derive(Debug, Serialize, Deserialize)]
254pub struct StarredArgs {
255 pub username: String,
256 pub viewer: Viewer,
257}
258
259/// `release`: one release, by `id` or `tag`, or with `latest` the latest
260/// one. Returns `Outcome<Release>`.
261#[derive(Debug, Serialize, Deserialize)]
262pub struct ReleaseArgs {
263 pub path: RepoPath,
264 pub viewer: Viewer,
265 #[serde(default)]
266 pub id: Option<String>,
267 #[serde(default)]
268 pub tag: Option<String>,
269 #[serde(default)]
270 pub latest: bool,
271}
272
273/// `create_release`: a release of `tag_name`. A tag that does not exist
274/// yet is made at `target` (a branch or commit; the default branch when
275/// absent). Needs the Write role. Returns `Outcome<Release>`.
276#[derive(Debug, Serialize, Deserialize)]
277#[serde(rename_all = "camelCase")]
278pub struct CreateReleaseArgs {
279 pub path: RepoPath,
280 pub actor: User,
281 pub tag_name: String,
282 #[serde(default)]
283 pub target: Option<String>,
284 #[serde(default)]
285 pub name: Option<String>,
286 #[serde(default)]
287 pub body: Option<String>,
288 #[serde(default)]
289 pub draft: bool,
290 #[serde(default)]
291 pub prerelease: bool,
292}
293
294/// `update_release`: changes whichever of a release's title, notes, draft
295/// and prerelease are given; an empty title clears it. Publishing a draft
296/// sets `published_at`. Needs the Write role. Returns `Outcome<Release>`.
297#[derive(Debug, Serialize, Deserialize)]
298pub struct UpdateReleaseArgs {
299 pub path: RepoPath,
300 pub actor: User,
301 pub id: String,
302 #[serde(default)]
303 pub name: Option<String>,
304 #[serde(default)]
305 pub body: Option<String>,
306 #[serde(default)]
307 pub draft: Option<bool>,
308 #[serde(default)]
309 pub prerelease: Option<bool>,
310}
311
312/// `delete_release`: deletes a release; its tag stays. Needs the Write
313/// role. Returns `Outcome<bool>`.
314#[derive(Debug, Serialize, Deserialize)]
315pub struct DeleteReleaseArgs {
316 pub path: RepoPath,
317 pub actor: User,
318 pub id: String,
319}
320
321/// Monday of the week `rfc3339` falls in (UTC), as `YYYY-MM-DD`; None when
322/// it cannot be read.
323pub fn week_of(rfc3339: &str) -> Option<String> {
324 let days = days_from_civil_str(rfc3339.get(..10)?)?;
325 // 1970-01-01 was a Thursday: day 0 is three days after a Monday.
326 let monday = days - (days + 3).rem_euclid(7);
327 Some(civil_from_days(monday))
328}
329
330/// The Monday after `week` (a Monday, `YYYY-MM-DD`).
331pub fn next_week(week: &str) -> Option<String> {
332 Some(civil_from_days(days_from_civil_str(week)? + 7))
333}
334
335fn days_from_civil_str(date: &str) -> Option<i64> {
336 let mut parts = date.splitn(3, '-');
337 let year: i64 = parts.next()?.parse().ok()?;
338 let month: i64 = parts.next()?.parse().ok()?;
339 let day: i64 = parts.next()?.parse().ok()?;
340 if !(1..=12).contains(&month) || !(1..=31).contains(&day) {
341 return None;
342 }
343 // Howard Hinnant's days_from_civil.
344 let y = if month <= 2 { year - 1 } else { year };
345 let era = y.div_euclid(400);
346 let yoe = y - era * 400;
347 let mp = (month + 9) % 12;
348 let doy = (153 * mp + 2) / 5 + day - 1;
349 let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
350 Some(era * 146_097 + doe - 719_468)
351}
352
353fn civil_from_days(days: i64) -> String {
354 let z = days + 719_468;
355 let era = z.div_euclid(146_097);
356 let doe = z - era * 146_097;
357 let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
358 let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
359 let mp = (5 * doy + 2) / 153;
360 let day = doy - (153 * mp + 2) / 5 + 1;
361 let month = if mp < 10 { mp + 3 } else { mp - 9 };
362 let year = yoe + era * 400 + i64::from(month <= 2);
363 format!("{year:04}-{month:02}-{day:02}")
364}
365
366#[cfg(test)]
367mod tests {
368 use super::*;
369
370 #[test]
371 fn a_week_is_named_by_its_monday() {
372 // 2026-10-07 is a Wednesday.
373 assert_eq!(week_of("2026-10-07T10:00:00Z").as_deref(), Some("2026-10-05"));
374 assert_eq!(week_of("2026-10-05T00:00:00Z").as_deref(), Some("2026-10-05"));
375 assert_eq!(week_of("2026-10-11T23:59:59Z").as_deref(), Some("2026-10-05"));
376 assert_eq!(week_of("2026-01-01T00:00:00Z").as_deref(), Some("2025-12-29"));
377 assert_eq!(week_of("1970-01-01T00:00:00Z").as_deref(), Some("1969-12-29"));
378 assert_eq!(week_of("nonsense"), None);
379 assert_eq!(next_week("2025-12-29").as_deref(), Some("2026-01-05"));
380 }
381
382 #[test]
383 fn the_about_is_camel_case_between_services() {
384 let about = RepoAbout { contributors: 3, ..RepoAbout::default() };
385 let value = serde_json::to_value(&about).unwrap();
386 assert_eq!(value["topContributors"], serde_json::json!([]));
387 assert_eq!(value["pending"], false);
388 assert_eq!(value["securityPolicy"], serde_json::Value::Null);
389 }
390}