comindly-api 0.5.0-beta.7

comindly's API: the requests and answers of an engine's /api/v1, shared by the engine and the command line.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

//! The ledger and conventions (`/api/v1/ledger`, `/remember`, `/review`, `/erase`,
//! `/conventions`), and the queries of the read commands' answers (`/api/v1/answer/*`).

use std::collections::BTreeMap;

use serde::{Deserialize, Serialize};

pub use crate::conventions::{Convention, Manual};
pub use crate::ledger::Entry;
pub use crate::preflight::Change;

/// `GET /api/v1/conventions?repo=`.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct RepoQuery {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub repo: Option<String>,
}

/// The conventions in effect, and the measured ones a person hid.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Conventions {
    pub conventions: Vec<ShownConvention>,
    pub hidden: Vec<Manual>,
    /// Per repository, its commit page on GitHub or GitLab without the commit (append it).
    pub commit_urls: BTreeMap<String, String>,
}

/// A convention with the handle edits use.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ShownConvention {
    #[serde(flatten)]
    pub convention: Convention,
    pub id: String,
    /// `Always`, `Usually`, `Often` or `Sometimes`; none for the team's own.
    pub strength: Option<String>,
    /// What it was measured from, e.g. `Followed by 412 of the 530 functions with parameters.`
    pub evidence: Option<String>,
    /// Too few instances to call it settled.
    pub few: bool,
}

/// `POST /api/v1/conventions`: `add`, `edit`, `hide` or `restore`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ConventionChange {
    pub action: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub repo: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub dimension: Option<String>,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub rule: String,
}

/// `POST /api/v1/review`: `confirm`, `archive`, `invalidate`, … a record by id or id prefix.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ReviewRequest {
    pub id: String,
    pub action: String,
    #[serde(default)]
    pub reason: String,
}

/// `POST /api/v1/remember`: a record written by a person.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RememberRequest {
    pub kind: String,
    /// Symbols the record is about: ids, names or `Class.method`.
    pub on: Vec<String>,
    pub title: String,
    #[serde(default)]
    pub body: String,
    #[serde(default)]
    pub trigger: Option<String>,
    #[serde(default)]
    pub evidence: Vec<String>,
    #[serde(default)]
    pub fields: BTreeMap<String, String>,
    /// Code that shaped the record, stored with the indexed commit.
    #[serde(default)]
    pub snippets: Vec<crate::ledger::Snippet>,
}

/// The new record's id.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Remembered {
    pub ok: bool,
    pub id: String,
}

/// `answer/find` and `answer/search`: `repos` is a comma-separated list.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AnswerQuery {
    pub q: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub repos: Option<String>,
    /// Only repositories of these teams: comma-separated names, `none` for unlabelled ones.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub teams: Option<String>,
}

/// `answer/why`, `answer/flow` and `answer/explore`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AnswerFocus {
    pub focus: String,
}

/// `answer/hook`: `event` is `session-start` or `pre-edit`; `seen` the record ids shown already, comma-separated.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct HookQuery {
    pub event: String,
    pub cwd: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub path: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub seen: Option<String>,
}

/// `answer/ledger`.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct LedgerQuery {
    #[serde(default)]
    pub inbox: bool,
    #[serde(default)]
    pub check: bool,
}

/// `answer/contracts`.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ContractsQuery {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub kind: Option<String>,
    #[serde(default)]
    pub dangling: bool,
}

/// `answer/stats`: `repos` is a comma-separated list.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct StatsQuery {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub repos: Option<String>,
}

/// `answer/packages`.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct PackagesQuery {
    #[serde(default)]
    pub skew: bool,
}

/// `POST answer/preflight`: the changed lines, read from git by the caller.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PreflightRequest {
    pub changes: Vec<Change>,
}