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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
//! What:
//! One complete policy pass over the shipped policies:
//! the built-in policies,
//! then
//! the fixed argument transforms of a forwarded command,
//! then the optional policies.
//! Why:
//! Every lifecycle runs the same three stages in the same order,
//! and each stage can
//! end the pass.
//! Keeping the sequence in one place means a wrapped command and a
//! direct `git cli-git check` cannot drift apart in what they run or when they stop.
//!
//! In TS you'd write (pseudocode):
//! ```ts
//! // const result = await runPolicyEngine({ args, trigger, config, selectedPolicyIds });
//! ```
/// What:
/// `use` brings names from sibling files into this file;
/// `super::` means "the parent
/// module",
/// where every sibling file of this crate is declared.
/// Why:
/// The pass joins the stage runner,
/// the shipped checks and the fixed transforms.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// import { runPolicyStage } from './policy_engine.ts';
/// ```
use super::policy_checks::ShippedChecks;
use super::policy_engine::{StageEnd, StageRequest, StageResult, run_policy_stage};
use super::policy_events::PolicyEvent;
use super::policy_registry::{POLICY_REGISTRY, PolicyId};
use super::policy_transforms::{TransformResult, apply_fixed_transforms};
use super::policy_trigger::Trigger;
use super::repository_facts::RepositoryFacts;
/// What:
/// `OsString` is owned operating-system text of raw bytes.
/// Sibling the reader might
/// expect:
/// `String`,
/// which must be valid UTF-8.
/// Why:
/// The pass hands back the arguments Git will receive,
/// byte for byte.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// // string, but byte-preserving.
/// ```
use std::ffi::OsString;
/// What:
/// What one pass produced.
/// A `struct` is a record with named fields;
/// `Vec<T>` is an
/// owned list.
/// `#[derive(...)]` asks the compiler to generate copying,
/// debug
/// printing and `==`.
/// Why:
/// The caller needs the arguments to forward,
/// every event in emission order,
/// and
/// how the pass ended.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// type PassResult = { args: string[]; events: PolicyEvent[]; end: StageEnd };
/// ```
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct PassResult {
/// The arguments after the fixed transforms;
/// the input arguments when the pass ended
/// before or inside them.
pub arguments: Vec<OsString>,
/// Every event of the pass,
/// in emission order.
pub events: Vec<PolicyEvent>,
/// How the pass ended.
pub end: StageEnd,
}
/// What:
/// The shipped policies of one kind,
/// in registry order.
/// `optional` selects the
/// policies that are off unless the configuration lists them;
/// `Vec<PolicyId>` is the
/// owned result.
/// Why:
/// The registry is the only list of policies;
/// the two stages are its two halves,
/// so
/// a policy added there lands in exactly one stage without a second list to update.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// const policiesOfKind = (optional: boolean) => POLICY_REGISTRY.filter(p => p.offUnlessListed === optional).map(p => p.id);
/// ```
pub fn policies_of_kind(optional: bool) -> Vec<PolicyId> {
// `Vec::<PolicyId>::new()` is an empty owned list; `mut` allows pushing.
let mut policies: Vec<PolicyId> = Vec::<PolicyId>::new();
// `for descriptor in POLICY_REGISTRY` borrows each compiled-in row in order.
for descriptor in POLICY_REGISTRY {
if descriptor.off_unless_listed == optional {
policies.push(descriptor.id);
}
}
return policies;
}
/// What:
/// Run one pass for `request` over `checks`.
/// `<F: RepositoryFacts>` says the function
/// works with any one facts provider `F`;
/// `&mut ShippedChecks<F>` lends the shipped
/// policies and their provider for writing,
/// because checks cache repository facts.
/// Why:
/// The order is the installed wrapper's.
/// Built-in policies read the command before
/// it is rewritten.
/// The fixed transforms run only for a forwarded command.
/// Optional
/// policies run last.
/// A stage that did not complete ends the pass with the
/// arguments it was given,
/// and nothing after it runs.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// async function runPolicyPass(request: StageRequest, checks: ShippedChecks): Promise<PassResult>;
/// ```
pub fn run_policy_pass<F: RepositoryFacts>(
request: &StageRequest,
checks: &mut ShippedChecks<F>,
) -> PassResult {
// `.as_slice()` lends an owned list as a borrowed view.
let built_in: StageResult =
run_policy_stage(request, policies_of_kind(false).as_slice(), checks);
// `mut` allows the later stages to append their events.
let mut events: Vec<PolicyEvent> = built_in.events;
if built_in.end != StageEnd::Completed {
return PassResult {
// `.clone()` copies the untouched input arguments for the caller.
arguments: checks.arguments.clone(),
events,
end: built_in.end,
};
}
// `mut` allows the transforms to replace the arguments.
let mut arguments: Vec<OsString> = checks.arguments.clone();
if request.trigger == Trigger::PreForward {
// `&mut checks.facts` lends the provider for writing: a transform may ask Git one fact.
let transformed: TransformResult = apply_fixed_transforms(
arguments.as_slice(),
request.controls.commit_only_escaped,
&mut checks.facts,
);
// A complete transform stage reports nothing but rejections, so any event of a
// complete stage is one; an incomplete stage is handled first.
let rejected: bool = !transformed.events.is_empty();
// `.extend(list)` moves every item of `list` onto the end.
events.extend(transformed.events);
if !transformed.complete {
return PassResult {
arguments,
events,
end: StageEnd::Failed,
};
}
if rejected && !request.controls.keep_going {
return PassResult {
arguments,
events,
end: StageEnd::Stopped,
};
}
arguments = transformed.arguments;
}
let optional: StageResult =
run_policy_stage(request, policies_of_kind(true).as_slice(), checks);
events.extend(optional.events);
return PassResult {
arguments,
events,
end: optional.end,
};
}
/// Stage order,
/// stopping and argument hand-over stay out of the release executable.
#[cfg(test)]
#[path = "policy_pass_tests.rs"]
mod tests;