@maycombhq/sdk 2.0.0-beta.26 → 2.0.0-beta.27.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/npm/core/api.d.ts +1620 -37
- package/npm/core/audit.d.ts +9 -0
- package/npm/core/canary.d.ts +369 -0
- package/npm/core/cite.d.ts +55 -0
- package/npm/core/curated.d.ts +10 -0
- package/npm/core/facts-join-vendor.d.ts +47 -5
- package/npm/core/facts-join.d.ts +1 -1
- package/npm/core/index.d.ts +2 -0
- package/npm/core/light.d.ts +3 -1
- package/npm/core/manifest-edit.d.ts +10 -0
- package/npm/core/metarepo.d.ts +1 -1
- package/npm/core/process-trees.d.ts +86 -0
- package/npm/core/questions.d.ts +8 -0
- package/npm/core/run-log.d.ts +173 -7
- package/npm/index.js +3788 -2939
- package/package.json +1 -1
package/npm/core/audit.d.ts
CHANGED
|
@@ -95,6 +95,14 @@ export declare function serializeAuditFile(file: AuditFileT): string;
|
|
|
95
95
|
* (a correction) is their word already, and one not yet checked isn't kept; neither is drawn.
|
|
96
96
|
*/
|
|
97
97
|
export declare function auditCandidates(facts: readonly Fact[]): AuditItemT[];
|
|
98
|
+
declare function shuffled<T extends {
|
|
99
|
+
id: string;
|
|
100
|
+
}>(list: readonly T[], seed: string): T[];
|
|
101
|
+
/**
|
|
102
|
+
* The same shuffle for another draw (ADR 0196, the canaries' words and removals): by id, then the
|
|
103
|
+
* seeded generator, so the same list and seed give the same order on any machine.
|
|
104
|
+
*/
|
|
105
|
+
export declare const seededShuffle: typeof shuffled;
|
|
98
106
|
/**
|
|
99
107
|
* A reproducible random sample: `size` facts and `size` links (all of them when there are
|
|
100
108
|
* fewer), the same for the same candidates and seed whatever order they come in.
|
|
@@ -163,3 +171,4 @@ export declare function auditItemHolds(i: AuditItemT, facts: ReadonlyMap<string,
|
|
|
163
171
|
* `verified: sample` where the facts are read for a person (the facts file keeps `line`).
|
|
164
172
|
*/
|
|
165
173
|
export declare function sampleConfirmed(audit: AuditFileT | undefined, facts: readonly Fact[]): Set<string>;
|
|
174
|
+
export {};
|
|
@@ -0,0 +1,369 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { type AuditPrecision } from "./audit.js";
|
|
3
|
+
import type { Fact } from "./schema/facts.js";
|
|
4
|
+
/**
|
|
5
|
+
* Canaries (plan item Z2, ADR 0196): in a scratch copy of a repo, never committed, Atticus plants
|
|
6
|
+
* a few synthetic entries, calls, topics and config keys and comments out a few real ones the
|
|
7
|
+
* verified facts cite. The person's assistant reads the copy as it reads any repo; the reader
|
|
8
|
+
* must find the planted and miss the removed. That gives recall, and a fabrication rate the
|
|
9
|
+
* verifier can't see (a claim about a line that is there but commented out passes the check that
|
|
10
|
+
* the value is on the line), on the organisation's own code, with nobody labelling anything.
|
|
11
|
+
* Misreadings of real lines are the sample audit's (P3, ADR 0148); the two side by side say how
|
|
12
|
+
* often a claim graded as backed is wrong (the silent error rate, as two numbers, never pooled).
|
|
13
|
+
*
|
|
14
|
+
* Pure: the caller plants, reads and writes the files. Nothing here names a stack or framework;
|
|
15
|
+
* the templates that plant are `@maycombhq/verify`'s.
|
|
16
|
+
*/
|
|
17
|
+
/**
|
|
18
|
+
* Where a canary's reports are kept, relative to the root: `reports/canaries`, or
|
|
19
|
+
* `.atticus/reports/canaries` when Atticus is adopted in a repo. One file per run,
|
|
20
|
+
* `<date>-<repo>.yaml`; the only thing a canary writes in the metarepo.
|
|
21
|
+
*/
|
|
22
|
+
export declare const canaryReportsRelOf: (root: string) => string;
|
|
23
|
+
/**
|
|
24
|
+
* A repo's name as a canary takes it (review of ADR 0196): letters, digits, `.`, `_` and `-`,
|
|
25
|
+
* starting with a letter or digit, and never `..`, so no name reaches outside the folder it
|
|
26
|
+
* names a file in; and no Windows device name (`con`, `nul.txt`), as the run folder holds the
|
|
27
|
+
* copy as `<repo>/` and a report is named after the repo.
|
|
28
|
+
*/
|
|
29
|
+
export declare const isCanaryRepoName: (repo: string) => boolean;
|
|
30
|
+
/**
|
|
31
|
+
* The folder every run folder is made in, right in the system's temporary folder: made 0700 and
|
|
32
|
+
* this user's own, so no other user can make or swap a run folder in it (review of ADR 0196). Its
|
|
33
|
+
* name, like a run folder's, says nothing of a canary: a run folder is the read's workspace.
|
|
34
|
+
*/
|
|
35
|
+
export declare const CANARY_READS_DIR = "atticus-reads";
|
|
36
|
+
/**
|
|
37
|
+
* A metarepo's id in a run folder's name: the first 8 characters of its state folder's name
|
|
38
|
+
* (`metarepoStateDir`, ADR 0186), so a run folder is known as this metarepo's and no other's.
|
|
39
|
+
*/
|
|
40
|
+
export declare const isCanaryMetarepoId: (id: string) => boolean;
|
|
41
|
+
/** The start of a run folder's name: `<repo>-<id8>-`, then the six characters mkdtemp adds. */
|
|
42
|
+
export declare const canaryRunPrefix: (repo: string, id: string) => string;
|
|
43
|
+
/**
|
|
44
|
+
* Whether a folder's base name is a run folder of this repo's and this metarepo's,
|
|
45
|
+
* `<repo>-<id8>-XXXXXX`: neutral on purpose (review of ADR 0196), as the folder is the workspace
|
|
46
|
+
* the read is made in.
|
|
47
|
+
*/
|
|
48
|
+
export declare const isCanaryRunName: (name: string, repo: string, id: string) => boolean;
|
|
49
|
+
/** The repo and metarepo id a run folder's base name is of, or undefined when it is no run's. */
|
|
50
|
+
export declare function canaryRunOf(name: string): {
|
|
51
|
+
repo: string;
|
|
52
|
+
id: string;
|
|
53
|
+
} | undefined;
|
|
54
|
+
/** What a planted item stands for: a route served, a call made, a topic, a config key. */
|
|
55
|
+
export declare const CANARY_WHATS: readonly ["entry", "call", "topic-in", "topic-out", "config"];
|
|
56
|
+
export type CanaryWhat = (typeof CANARY_WHATS)[number];
|
|
57
|
+
export declare const CanaryPlanted: z.ZodObject<{
|
|
58
|
+
id: z.ZodString;
|
|
59
|
+
kind: z.ZodEnum<{
|
|
60
|
+
config: "config";
|
|
61
|
+
entry: "entry";
|
|
62
|
+
call: "call";
|
|
63
|
+
}>;
|
|
64
|
+
what: z.ZodEnum<{
|
|
65
|
+
config: "config";
|
|
66
|
+
entry: "entry";
|
|
67
|
+
call: "call";
|
|
68
|
+
"topic-in": "topic-in";
|
|
69
|
+
"topic-out": "topic-out";
|
|
70
|
+
}>;
|
|
71
|
+
stack: z.ZodString;
|
|
72
|
+
file: z.ZodString;
|
|
73
|
+
line: z.ZodNumber;
|
|
74
|
+
claim: z.ZodString;
|
|
75
|
+
needle: z.ZodString;
|
|
76
|
+
}, z.core.$strict>;
|
|
77
|
+
export type CanaryPlantedT = z.infer<typeof CanaryPlanted>;
|
|
78
|
+
export declare const CanaryRemoved: z.ZodObject<{
|
|
79
|
+
id: z.ZodString;
|
|
80
|
+
fact: z.ZodString;
|
|
81
|
+
kind: z.ZodString;
|
|
82
|
+
file: z.ZodString;
|
|
83
|
+
line: z.ZodNumber;
|
|
84
|
+
claim: z.ZodString;
|
|
85
|
+
value: z.ZodString;
|
|
86
|
+
needle: z.ZodString;
|
|
87
|
+
how: z.ZodLiteral<"commented">;
|
|
88
|
+
}, z.core.$strict>;
|
|
89
|
+
export type CanaryRemovedT = z.infer<typeof CanaryRemoved>;
|
|
90
|
+
/** An item a stack's template has that wasn't planted, and why (the repo couldn't serve it). */
|
|
91
|
+
export declare const CanarySkipped: z.ZodObject<{
|
|
92
|
+
stack: z.ZodString;
|
|
93
|
+
what: z.ZodEnum<{
|
|
94
|
+
config: "config";
|
|
95
|
+
entry: "entry";
|
|
96
|
+
call: "call";
|
|
97
|
+
"topic-in": "topic-in";
|
|
98
|
+
"topic-out": "topic-out";
|
|
99
|
+
}>;
|
|
100
|
+
reason: z.ZodString;
|
|
101
|
+
}, z.core.$strict>;
|
|
102
|
+
export type CanarySkippedT = z.infer<typeof CanarySkipped>;
|
|
103
|
+
/**
|
|
104
|
+
* The answer key a plant keeps on this machine (never in the copy, never in the metarepo). The
|
|
105
|
+
* run folder is kept by its base name only, `<repo>-<id8>-XXXXXX` (review of ADR 0196): its path
|
|
106
|
+
* is rebuilt under `<temporary folder>/atticus-reads` and checked (the metarepo's id included)
|
|
107
|
+
* before anything in it is read, written or deleted, so a key edited by hand can't point anywhere
|
|
108
|
+
* else.
|
|
109
|
+
*/
|
|
110
|
+
export declare const CanaryKey: z.ZodObject<{
|
|
111
|
+
schema: z.ZodLiteral<1>;
|
|
112
|
+
repo: z.ZodString;
|
|
113
|
+
seed: z.ZodString;
|
|
114
|
+
commit: z.ZodOptional<z.ZodString>;
|
|
115
|
+
run: z.ZodString;
|
|
116
|
+
reads: z.ZodOptional<z.ZodString>;
|
|
117
|
+
stacks: z.ZodArray<z.ZodString>;
|
|
118
|
+
planted: z.ZodArray<z.ZodObject<{
|
|
119
|
+
id: z.ZodString;
|
|
120
|
+
kind: z.ZodEnum<{
|
|
121
|
+
config: "config";
|
|
122
|
+
entry: "entry";
|
|
123
|
+
call: "call";
|
|
124
|
+
}>;
|
|
125
|
+
what: z.ZodEnum<{
|
|
126
|
+
config: "config";
|
|
127
|
+
entry: "entry";
|
|
128
|
+
call: "call";
|
|
129
|
+
"topic-in": "topic-in";
|
|
130
|
+
"topic-out": "topic-out";
|
|
131
|
+
}>;
|
|
132
|
+
stack: z.ZodString;
|
|
133
|
+
file: z.ZodString;
|
|
134
|
+
line: z.ZodNumber;
|
|
135
|
+
claim: z.ZodString;
|
|
136
|
+
needle: z.ZodString;
|
|
137
|
+
}, z.core.$strict>>;
|
|
138
|
+
removed: z.ZodArray<z.ZodObject<{
|
|
139
|
+
id: z.ZodString;
|
|
140
|
+
fact: z.ZodString;
|
|
141
|
+
kind: z.ZodString;
|
|
142
|
+
file: z.ZodString;
|
|
143
|
+
line: z.ZodNumber;
|
|
144
|
+
claim: z.ZodString;
|
|
145
|
+
value: z.ZodString;
|
|
146
|
+
needle: z.ZodString;
|
|
147
|
+
how: z.ZodLiteral<"commented">;
|
|
148
|
+
}, z.core.$strict>>;
|
|
149
|
+
skipped: z.ZodDefault<z.ZodArray<z.ZodObject<{
|
|
150
|
+
stack: z.ZodString;
|
|
151
|
+
what: z.ZodEnum<{
|
|
152
|
+
config: "config";
|
|
153
|
+
entry: "entry";
|
|
154
|
+
call: "call";
|
|
155
|
+
"topic-in": "topic-in";
|
|
156
|
+
"topic-out": "topic-out";
|
|
157
|
+
}>;
|
|
158
|
+
reason: z.ZodString;
|
|
159
|
+
}, z.core.$strict>>>;
|
|
160
|
+
at: z.ZodString;
|
|
161
|
+
}, z.core.$strict>;
|
|
162
|
+
export type CanaryKeyT = z.infer<typeof CanaryKey>;
|
|
163
|
+
/** A share with its count and the Wilson interval at 95% (null with nothing to count). */
|
|
164
|
+
export declare const CanaryRate: z.ZodObject<{
|
|
165
|
+
k: z.ZodNumber;
|
|
166
|
+
n: z.ZodNumber;
|
|
167
|
+
rate: z.ZodNullable<z.ZodNumber>;
|
|
168
|
+
low: z.ZodNullable<z.ZodNumber>;
|
|
169
|
+
high: z.ZodNullable<z.ZodNumber>;
|
|
170
|
+
}, z.core.$strict>;
|
|
171
|
+
export type CanaryRateT = z.infer<typeof CanaryRate>;
|
|
172
|
+
export declare const CanaryReport: z.ZodObject<{
|
|
173
|
+
schema: z.ZodLiteral<1>;
|
|
174
|
+
repo: z.ZodString;
|
|
175
|
+
commit: z.ZodOptional<z.ZodString>;
|
|
176
|
+
seed: z.ZodString;
|
|
177
|
+
at: z.ZodString;
|
|
178
|
+
by: z.ZodString;
|
|
179
|
+
stacks: z.ZodArray<z.ZodString>;
|
|
180
|
+
read: z.ZodObject<{
|
|
181
|
+
facts: z.ZodNumber;
|
|
182
|
+
kept: z.ZodNumber;
|
|
183
|
+
rejected: z.ZodNumber;
|
|
184
|
+
unread: z.ZodDefault<z.ZodNumber>;
|
|
185
|
+
}, z.core.$strict>;
|
|
186
|
+
planted: z.ZodArray<z.ZodObject<{
|
|
187
|
+
kind: z.ZodEnum<{
|
|
188
|
+
config: "config";
|
|
189
|
+
entry: "entry";
|
|
190
|
+
call: "call";
|
|
191
|
+
}>;
|
|
192
|
+
id: z.ZodString;
|
|
193
|
+
what: z.ZodEnum<{
|
|
194
|
+
config: "config";
|
|
195
|
+
entry: "entry";
|
|
196
|
+
call: "call";
|
|
197
|
+
"topic-in": "topic-in";
|
|
198
|
+
"topic-out": "topic-out";
|
|
199
|
+
}>;
|
|
200
|
+
stack: z.ZodString;
|
|
201
|
+
result: z.ZodEnum<{
|
|
202
|
+
rejected: "rejected";
|
|
203
|
+
found: "found";
|
|
204
|
+
missed: "missed";
|
|
205
|
+
}>;
|
|
206
|
+
}, z.core.$strict>>;
|
|
207
|
+
skipped: z.ZodDefault<z.ZodArray<z.ZodObject<{
|
|
208
|
+
stack: z.ZodString;
|
|
209
|
+
what: z.ZodEnum<{
|
|
210
|
+
config: "config";
|
|
211
|
+
entry: "entry";
|
|
212
|
+
call: "call";
|
|
213
|
+
"topic-in": "topic-in";
|
|
214
|
+
"topic-out": "topic-out";
|
|
215
|
+
}>;
|
|
216
|
+
reason: z.ZodString;
|
|
217
|
+
}, z.core.$strict>>>;
|
|
218
|
+
removed: z.ZodArray<z.ZodObject<{
|
|
219
|
+
file: z.ZodString;
|
|
220
|
+
value: z.ZodString;
|
|
221
|
+
line: z.ZodNumber;
|
|
222
|
+
kind: z.ZodString;
|
|
223
|
+
id: z.ZodString;
|
|
224
|
+
fact: z.ZodString;
|
|
225
|
+
claim: z.ZodString;
|
|
226
|
+
how: z.ZodLiteral<"commented">;
|
|
227
|
+
result: z.ZodEnum<{
|
|
228
|
+
absent: "absent";
|
|
229
|
+
rejected: "rejected";
|
|
230
|
+
kept: "kept";
|
|
231
|
+
elsewhere: "elsewhere";
|
|
232
|
+
}>;
|
|
233
|
+
by: z.ZodOptional<z.ZodString>;
|
|
234
|
+
}, z.core.$strict>>;
|
|
235
|
+
recall: z.ZodObject<{
|
|
236
|
+
k: z.ZodNumber;
|
|
237
|
+
n: z.ZodNumber;
|
|
238
|
+
rate: z.ZodNullable<z.ZodNumber>;
|
|
239
|
+
low: z.ZodNullable<z.ZodNumber>;
|
|
240
|
+
high: z.ZodNullable<z.ZodNumber>;
|
|
241
|
+
}, z.core.$strict>;
|
|
242
|
+
fabrication: z.ZodObject<{
|
|
243
|
+
k: z.ZodNumber;
|
|
244
|
+
n: z.ZodNumber;
|
|
245
|
+
rate: z.ZodNullable<z.ZodNumber>;
|
|
246
|
+
low: z.ZodNullable<z.ZodNumber>;
|
|
247
|
+
high: z.ZodNullable<z.ZodNumber>;
|
|
248
|
+
}, z.core.$strict>;
|
|
249
|
+
passed: z.ZodObject<{
|
|
250
|
+
k: z.ZodNumber;
|
|
251
|
+
n: z.ZodNumber;
|
|
252
|
+
rate: z.ZodNullable<z.ZodNumber>;
|
|
253
|
+
low: z.ZodNullable<z.ZodNumber>;
|
|
254
|
+
high: z.ZodNullable<z.ZodNumber>;
|
|
255
|
+
}, z.core.$strict>;
|
|
256
|
+
}, z.core.$strict>;
|
|
257
|
+
export type CanaryReportT = z.infer<typeof CanaryReport>;
|
|
258
|
+
export declare function parseCanaryReport(text: string): {
|
|
259
|
+
ok: true;
|
|
260
|
+
report: CanaryReportT;
|
|
261
|
+
} | {
|
|
262
|
+
ok: false;
|
|
263
|
+
issues: string[];
|
|
264
|
+
};
|
|
265
|
+
export declare const serializeCanaryReport: (r: CanaryReportT) => string;
|
|
266
|
+
/** Lowercase, every run of other characters one `-`: `W1_W2_URL`, `w1.w2-url` and `w1-w2-url` alike. */
|
|
267
|
+
export declare const foldCanary: (s: string) => string;
|
|
268
|
+
/** The words of a fact's claim a canary is matched on: its path, topic, key, name and cited value. */
|
|
269
|
+
export declare function canaryClaimText(f: Fact): string;
|
|
270
|
+
/**
|
|
271
|
+
* What a fact claims, as a removed fact is matched on: an entry's or call's method and path, its
|
|
272
|
+
* parameters left out (`get ledger-v1-transfers-param`; the path alone with no method), a config
|
|
273
|
+
* key exactly, else its cited value, folded. Second review of ADR 0196: the method is part of it,
|
|
274
|
+
* so `PUT /users` beside a removed `GET /users` is no claim of it.
|
|
275
|
+
*/
|
|
276
|
+
export declare function canaryNeedleOf(f: Fact): string;
|
|
277
|
+
/** Whether a fact is about a planted item: its kind, with the item's own words in its claim. */
|
|
278
|
+
export declare const plantedBy: (p: Pick<CanaryPlantedT, "kind" | "needle">, f: Fact) => boolean;
|
|
279
|
+
/**
|
|
280
|
+
* How a fact claims a removed one (second review of ADR 0196): `near` when it is of its kind,
|
|
281
|
+
* cites the commented line or one either side (the verifier's window), by its cite or a
|
|
282
|
+
* `cite.with` part, and claims the same: the same needle (method and path, or the key exactly).
|
|
283
|
+
* `value` when it claims it by its cited value only: it cites that very line with that value, or
|
|
284
|
+
* (an entry or call) its path is the value with the same method (a path the read wrote without
|
|
285
|
+
* the base the removed fact put in front). `elsewhere` when it has the same needle but cites
|
|
286
|
+
* neither the line nor one beside it, so may well be about another line (never counted as passed).
|
|
287
|
+
* A claim that merely holds the removed value (`/users/:id` beside a removed `/users`, a key
|
|
288
|
+
* `url-fallback` beside a removed `url`) is none of these: a fact of the line beside it.
|
|
289
|
+
*/
|
|
290
|
+
export declare function removedMatch(r: CanaryRemovedT, f: Fact): "near" | "value" | "elsewhere" | undefined;
|
|
291
|
+
/** Whether a fact claims a removed one: at its line (`near`, by needle or value) or `elsewhere`. */
|
|
292
|
+
export declare function removedBy(r: CanaryRemovedT, f: Fact): "near" | "elsewhere" | undefined;
|
|
293
|
+
export declare function canaryRate(k: number, n: number): CanaryRateT;
|
|
294
|
+
/**
|
|
295
|
+
* Score a read of the copy against the key: each planted item found by a kept fact, by a
|
|
296
|
+
* rejected one only, or missed; each removed one absent, still claimed at its line by a kept fact
|
|
297
|
+
* (a silent fabrication), claimed there only by a rejected one (the verifier caught it), or named
|
|
298
|
+
* only by a fact cited elsewhere. One fact answers for one item at most (review of ADR 0196): the
|
|
299
|
+
* planted items are matched in order, each to the first fact not yet taken, then the removed ones
|
|
300
|
+
* in passes, strongest match first (`removedMatch`). Recall and the fabrication rate with their
|
|
301
|
+
* intervals.
|
|
302
|
+
*/
|
|
303
|
+
export declare function scoreCanary(key: Pick<CanaryKeyT, "repo" | "commit" | "seed" | "stacks" | "planted" | "removed"> & {
|
|
304
|
+
skipped?: CanaryKeyT["skipped"];
|
|
305
|
+
}, read: {
|
|
306
|
+
kept: readonly Fact[];
|
|
307
|
+
rejected: readonly Fact[];
|
|
308
|
+
unread?: number;
|
|
309
|
+
}, o: {
|
|
310
|
+
at: string;
|
|
311
|
+
by: string;
|
|
312
|
+
}): CanaryReportT;
|
|
313
|
+
/**
|
|
314
|
+
* How often a claim graded as backed is wrong (ADR 0196, as revised on review): two numbers side
|
|
315
|
+
* by side, each with its count and interval, never pooled into one. Their samples are of different
|
|
316
|
+
* things (real lines a person answered; lines Atticus took out), and a pooled figure let the
|
|
317
|
+
* canaries' found plants, right by construction, pad its denominator.
|
|
318
|
+
*/
|
|
319
|
+
export interface SilentErrorRate {
|
|
320
|
+
/** The audit misread rate: kept facts and backed links answered wrong, of those answered. */
|
|
321
|
+
misread: CanaryRateT;
|
|
322
|
+
/**
|
|
323
|
+
* The canary pass-through rate: lines taken out that the read still claimed at their place and
|
|
324
|
+
* the verifier kept, of the lines taken out (less those a fact names only elsewhere).
|
|
325
|
+
*/
|
|
326
|
+
passed: CanaryRateT;
|
|
327
|
+
/** Planted items found, summed over the latest run of each repo. */
|
|
328
|
+
recall: CanaryRateT;
|
|
329
|
+
/** Removed lines the read still claimed, kept or not. */
|
|
330
|
+
fabrication: CanaryRateT;
|
|
331
|
+
/** Removed lines a reader claimed that the verifier refused: flagged, so no silent error. */
|
|
332
|
+
caught: number;
|
|
333
|
+
/** Removed lines a fact named only elsewhere: in neither count. */
|
|
334
|
+
elsewhere: number;
|
|
335
|
+
repos: {
|
|
336
|
+
audited: number;
|
|
337
|
+
canaries: number;
|
|
338
|
+
};
|
|
339
|
+
/** What the canaries' numbers cover: each stack planted in, with the items planted there. */
|
|
340
|
+
covers: {
|
|
341
|
+
stack: string;
|
|
342
|
+
what: CanaryWhat[];
|
|
343
|
+
}[];
|
|
344
|
+
}
|
|
345
|
+
/** Each stack the reports planted in, with the items planted there, in a fixed order. */
|
|
346
|
+
export declare function canaryCovers(reports: readonly {
|
|
347
|
+
planted: readonly {
|
|
348
|
+
stack: string;
|
|
349
|
+
what: CanaryWhat;
|
|
350
|
+
}[];
|
|
351
|
+
}[]): {
|
|
352
|
+
stack: string;
|
|
353
|
+
what: CanaryWhat[];
|
|
354
|
+
}[];
|
|
355
|
+
/**
|
|
356
|
+
* The two numbers (ADR 0196): the audit misread rate, from the sample audit's answers on kept
|
|
357
|
+
* facts and on links joined by something other than a guess (a misread real line, P3); and the
|
|
358
|
+
* canary pass-through rate, from the latest canary of each repo (a removed line still claimed and
|
|
359
|
+
* kept is a fabrication the verifier passed, Z2). A guessed link, a planted item missed and a
|
|
360
|
+
* fabrication the verifier refused are not silent: they are flagged or absent, the system working.
|
|
361
|
+
*/
|
|
362
|
+
export declare function silentErrorRate(audit: {
|
|
363
|
+
precision: AuditPrecision;
|
|
364
|
+
repos: number;
|
|
365
|
+
} | undefined, canaries: readonly CanaryReportT[]): SilentErrorRate;
|
|
366
|
+
/** The latest report of each repo, by when it was scored. */
|
|
367
|
+
export declare function latestCanaries(reports: readonly CanaryReportT[]): CanaryReportT[];
|
|
368
|
+
/** Whether a name is one of Windows' device names, which no canary takes on any system. */
|
|
369
|
+
export declare const isWindowsDeviceName: (name: string) => boolean;
|
package/npm/core/cite.d.ts
CHANGED
|
@@ -42,6 +42,19 @@ export declare function quoteNotRequired(path: string, line: string): boolean;
|
|
|
42
42
|
* 46): a stream's name after `:` (`.env::$DATA` is `.env`) and trailing dots and spaces dropped.
|
|
43
43
|
*/
|
|
44
44
|
export declare function isSecretPath(path: string): boolean;
|
|
45
|
+
/**
|
|
46
|
+
* Beta.27 review: the well-known token prefixes, whatever follows them (TOKEN_SHAPES want the
|
|
47
|
+
* whole token, so a token cut short or typed in part passes them): a Git host's personal, project
|
|
48
|
+
* and deploy tokens, a package registry's, a model hub's, a payment provider's secret, restricted,
|
|
49
|
+
* publishable and webhook keys, a chat workspace's bot, user and app tokens, a cloud's access key
|
|
50
|
+
* ids, API keys and OAuth access tokens, a JWT's header, a mail service's key, a point-of-sale
|
|
51
|
+
* provider's access and secret keys, a telephony provider's API key and account ids, a data
|
|
52
|
+
* platform's token, a storage account's key in a connection string, a shared access signature,
|
|
53
|
+
* and a bearer or Basic authorization. One list: a run's title (run-log.ts) drops a word with one.
|
|
54
|
+
*/
|
|
55
|
+
export declare const TOKEN_PREFIXES: readonly RegExp[];
|
|
56
|
+
/** Whether a text holds one of TOKEN_PREFIXES anywhere (beta.27 review). */
|
|
57
|
+
export declare const hasTokenPrefix: (text: string) => boolean;
|
|
45
58
|
/**
|
|
46
59
|
* Whether a text holds a secret by its shape alone, whatever names it (beta.24 review): a URL's
|
|
47
60
|
* password (`jdbc:postgresql://user:pass@host`), a bearer or Basic token or one of the well-known token
|
|
@@ -52,6 +65,23 @@ export declare function isSecretPath(path: string): boolean;
|
|
|
52
65
|
export declare function hasSecretShape(text: string, o?: {
|
|
53
66
|
basic?: boolean;
|
|
54
67
|
}): boolean;
|
|
68
|
+
/**
|
|
69
|
+
* Beta.27 re-review: a text with what hasSecretShape finds in it masked (`***`, keeping what names
|
|
70
|
+
* it): a URL's password, a bearer or Basic token, the well-known token shapes. A run's log line
|
|
71
|
+
* goes through it, so an echoed error ("Can't read <root>/AKIA…") never keeps a key.
|
|
72
|
+
*/
|
|
73
|
+
export declare function maskSecretShapes(text: string, mask?: string): string;
|
|
74
|
+
/**
|
|
75
|
+
* Review of beta.24: whether a key is itself a secret, so naming its line by it would show one: a
|
|
76
|
+
* well-known token shape (an access key id written as a credentials file's key), a run of 24 hex
|
|
77
|
+
* digits or more (a random id, a digest), a run of 16 letters and digits or more that switches
|
|
78
|
+
* between them as a random token does (`q7Xf3Kd9…`), or (round 4) 32 characters or more of one
|
|
79
|
+
* piece (no `_`, `-` or `.`) in base64's or hex's alphabet, digits and letters both, or 32
|
|
80
|
+
* characters or more of base64url's alphabet with digits and both cases.
|
|
81
|
+
* A key of words, however abbreviated (`MSSQL_SA_PWD_2019`, `x509Certificate2Path`), is shown.
|
|
82
|
+
* Beta.27: here in core (it was the verifier's), so a run's title drops a value shaped so too.
|
|
83
|
+
*/
|
|
84
|
+
export declare function keyIsSecret(key: string): boolean;
|
|
55
85
|
/**
|
|
56
86
|
* Redact the secrets on a line, keeping what names them: a value after a secret-looking key
|
|
57
87
|
* (at the line's start, whatever the value; anywhere on it, a quoted literal), a setter's
|
|
@@ -79,3 +109,28 @@ export declare function quoteHoldsSecret(quote: string): boolean;
|
|
|
79
109
|
*/
|
|
80
110
|
export declare function partsBuildWord(claim: string, parts: readonly string[], lines: readonly string[]): boolean;
|
|
81
111
|
export declare function partsNamePath(lines: readonly string[], path: string): boolean;
|
|
112
|
+
/**
|
|
113
|
+
* Whether a part's value or line, or a code line in the cite window, declares a conventional
|
|
114
|
+
* route, one whose action is its method's name (third and fourth reviews of ADR 0196): a template
|
|
115
|
+
* with an action token (`{controller}/{action}/{id}`, `{controller=Home}/{action=Index}/{id?}`,
|
|
116
|
+
* attribute routing's `[action]`, on the class or the method's own `[Route("[action]")]`), a call
|
|
117
|
+
* that sets the default template (`MapDefaultControllerRoute()`), or a DRF `@action(` that sets no
|
|
118
|
+
* `url_path=` (its path is the method's name). `[controller]` alone is not one: an attribute route
|
|
119
|
+
* names its action in its own attribute, not by the method.
|
|
120
|
+
*
|
|
121
|
+
* A text may hold several lines, a window joined with `\n` (fifth review): a DRF `@action(` is
|
|
122
|
+
* read to its closing parenthesis, so a `url_path=` on a line below it, inside the call, makes it
|
|
123
|
+
* none; one the window doesn't close is read as far as the window goes.
|
|
124
|
+
*/
|
|
125
|
+
export declare function declaresConventionalRoute(texts: readonly string[]): boolean;
|
|
126
|
+
/**
|
|
127
|
+
* The piece of an HTTP route put together from parts that only a commented-out mapping writes
|
|
128
|
+
* (third review of ADR 0196), or undefined. A piece the parts' lines don't name, which a comment
|
|
129
|
+
* line in the cite window writes as a path (`// @GetMapping("/balances")`) while no code line there
|
|
130
|
+
* does, is named by that comment, not by the code: a method `balances()` under it, with the class's
|
|
131
|
+
* `/api` a part, names no `/api/balances`. Anywhere else an identifier names a piece as the path
|
|
132
|
+
* check always let it (a gRPC stub, a WCF call, a conventional route's action, a constant).
|
|
133
|
+
*/
|
|
134
|
+
export declare function pathPieceOnlyInComment(rawNear: readonly string[],
|
|
135
|
+
/** Whether a line of the window (and its index in it) is all comment. */
|
|
136
|
+
isComment: (l: string, i: number) => boolean, partLines: readonly string[], path: string): string | undefined;
|
package/npm/core/curated.d.ts
CHANGED
|
@@ -34,4 +34,14 @@ export interface CuratedResult {
|
|
|
34
34
|
suppressed: string[];
|
|
35
35
|
problems: CuratedProblem[];
|
|
36
36
|
}
|
|
37
|
+
/** Decisions apply oldest first by the instant their `at` names (an offset is allowed, so
|
|
38
|
+
* text order isn't time order), then by id; an `at` that doesn't parse sorts by its text after
|
|
39
|
+
* every one that does. */
|
|
40
|
+
export declare function byDecisionTime(a: {
|
|
41
|
+
at: string;
|
|
42
|
+
id: string;
|
|
43
|
+
}, b: {
|
|
44
|
+
at: string;
|
|
45
|
+
id: string;
|
|
46
|
+
}): number;
|
|
37
47
|
export declare function applyCurated(records: CatalogRecord[], decisions: readonly CatalogRecord[]): CuratedResult;
|
|
@@ -13,11 +13,23 @@ import { type FactEnd, type JoinRepo } from "./facts-join.js";
|
|
|
13
13
|
* name written in a host label (api.northwindpay.example → Northwind Pay), as the merge does.
|
|
14
14
|
* A call whose host no vendor claims is left alone: it is the join's, never guessed.
|
|
15
15
|
*
|
|
16
|
+
* Beta.27 (a user's estate): a target URL written as a deploy token (`@targetVendorUrl@`) is
|
|
17
|
+
* each value the config facts setting that token give it, per environment, as the join reads it;
|
|
18
|
+
* and the path the vendor receives is the target URL's own path (`/api/v1`) with the path the
|
|
19
|
+
* route forwards after it. A host an estate repo's manifest lists is the estate's, never a
|
|
20
|
+
* vendor's, whatever the profile's aliases say; a base that is a config key of the repo is never
|
|
21
|
+
* read as a host itself; and a call the estate join joined to an entry (a service's call to the
|
|
22
|
+
* gateway's own base path) reaches the vendor through that route, never directly.
|
|
23
|
+
*
|
|
16
24
|
* Then the operation: the vendor's operations of the same method whose path, with the spec's
|
|
17
|
-
* server path in front or without it, has the call's shape
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
25
|
+
* server path in front or without it, has the call's shape: a path parameter (`{version}`,
|
|
26
|
+
* `{account_guid}`) stands for any one segment, and a literal segment is preferred over a
|
|
27
|
+
* parameter where both fit (`/accounts/balances` over `/accounts/{account_guid}`), as OpenAPI
|
|
28
|
+
* routes. One is a match; none is a gap (the vendor's spec doesn't publish what the gateway
|
|
29
|
+
* forwards); two or more equally good is a question. A route that forwards a wildcard (a `*`
|
|
30
|
+
* segment, or `**` at the end) reaches every operation under it by design: each is a match
|
|
31
|
+
* (`wildcard`), never a question. Pure and deterministic: the same facts, answers and operations
|
|
32
|
+
* give the same result, whatever order they come in.
|
|
21
33
|
*/
|
|
22
34
|
/** One operation a vendor publishes, as intake reads it from the vendor's spec. */
|
|
23
35
|
export interface JoinVendorOperation {
|
|
@@ -66,8 +78,19 @@ export interface VendorCallMatch {
|
|
|
66
78
|
/** The vendor operation's Endpoint id. */
|
|
67
79
|
operation: string;
|
|
68
80
|
method?: string;
|
|
69
|
-
/** The path the gateway forwards to. */
|
|
81
|
+
/** The path the gateway forwards to: the target URL's own path in front, when it has one. */
|
|
70
82
|
path: string;
|
|
83
|
+
/**
|
|
84
|
+
* The environment whose target URL gives `path` (its config fact's `env`), when the settings
|
|
85
|
+
* name one: of those whose path reaches the operation, the prod-like one, else the first by
|
|
86
|
+
* name (`preferredEnvironment`).
|
|
87
|
+
*/
|
|
88
|
+
env?: string;
|
|
89
|
+
/**
|
|
90
|
+
* Beta.27: the route forwards a wildcard (`/accounts/*`), so it reaches every operation under
|
|
91
|
+
* it; this is one of them (the call has a match for each).
|
|
92
|
+
*/
|
|
93
|
+
wildcard?: true;
|
|
71
94
|
/**
|
|
72
95
|
* ADR 0142: a service's own call to another team's system, not a gateway's forwarding call;
|
|
73
96
|
* `route` is then the entry the call is made under, when it names one.
|
|
@@ -82,6 +105,8 @@ export interface VendorCallGap {
|
|
|
82
105
|
vendor: string;
|
|
83
106
|
method?: string;
|
|
84
107
|
path: string;
|
|
108
|
+
/** The environment whose target path `path` is (see `VendorCallMatch.env`). */
|
|
109
|
+
env?: string;
|
|
85
110
|
message: string;
|
|
86
111
|
}
|
|
87
112
|
/** A forwarding call two or more of the vendor's operations answer equally well. */
|
|
@@ -92,6 +117,8 @@ export interface VendorCallAsk {
|
|
|
92
117
|
question: string;
|
|
93
118
|
/** The operations' Endpoint ids, sorted. */
|
|
94
119
|
candidates: string[];
|
|
120
|
+
/** The environment whose target path the question is about (see `VendorCallMatch.env`). */
|
|
121
|
+
env?: string;
|
|
95
122
|
}
|
|
96
123
|
export interface VendorJoinResult {
|
|
97
124
|
matches: VendorCallMatch[];
|
|
@@ -105,6 +132,21 @@ export interface JoinVendorOperationsInput {
|
|
|
105
132
|
targets?: Readonly<Record<string, Readonly<Record<string, string>>>>;
|
|
106
133
|
/** The gateway bundle folders, as given to `joinFacts` (ADR 0147). */
|
|
107
134
|
bundleFolders?: readonly string[];
|
|
135
|
+
/**
|
|
136
|
+
* Beta.27: the estate join's joins. A call joined to an entry of the estate (a service's call
|
|
137
|
+
* to the gateway's own host and base path, joined to the proxy's route) goes there: the route
|
|
138
|
+
* forwards it on, so it is never a direct call to the vendor.
|
|
139
|
+
*/
|
|
140
|
+
joined?: readonly {
|
|
141
|
+
call: FactEnd;
|
|
142
|
+
}[];
|
|
108
143
|
}
|
|
144
|
+
/**
|
|
145
|
+
* The review of beta.27: the environment whose target URL a match, gap or drawn arrow takes its
|
|
146
|
+
* path from when the environments' settings differ: the first by name of the prod-like ones (a
|
|
147
|
+
* name with `pd`, `prod`, `prd` or `production` as a word of its own: `prod`, `us-prd`, `prod1`),
|
|
148
|
+
* else the first by name. Undefined when none is named.
|
|
149
|
+
*/
|
|
150
|
+
export declare function preferredEnvironment(envs: readonly string[]): string | undefined;
|
|
109
151
|
/** Match every gateway forwarding call that goes to a vendor to the vendor operation it reaches. */
|
|
110
152
|
export declare function joinVendorOperations(input: JoinVendorOperationsInput): VendorJoinResult;
|
package/npm/core/facts-join.d.ts
CHANGED
|
@@ -568,7 +568,7 @@ export declare function callTargetQuestion(f: Call, component: string): string;
|
|
|
568
568
|
* per environment (the Apigee config plugin's `config.json`), which a read before beta.24 didn't
|
|
569
569
|
* record: the next step it says is to read the gateway repo again, never a guess at a repo.
|
|
570
570
|
*/
|
|
571
|
-
export declare function forwardHostQuestion(host: string, repo: string): string;
|
|
571
|
+
export declare function forwardHostQuestion(host: string, repo: string, prefix?: string): string;
|
|
572
572
|
/** The question for a call whose gateway routes lead back where they came from (A-gateway2). */
|
|
573
573
|
export declare function gatewayCycleQuestion(f: Call, component: string, gateway: string): string;
|
|
574
574
|
/**
|
package/npm/core/index.d.ts
CHANGED
|
@@ -17,6 +17,7 @@ export * from "./link-evidence.js";
|
|
|
17
17
|
export * from "./shared-maps.js";
|
|
18
18
|
export * from "./contract-check.js";
|
|
19
19
|
export * from "./audit.js";
|
|
20
|
+
export * from "./canary.js";
|
|
20
21
|
export * from "./stack-helpers.js";
|
|
21
22
|
export * from "./cite.js";
|
|
22
23
|
export * from "./catalog.js";
|
|
@@ -83,6 +84,7 @@ export * from "./setup-edit.js";
|
|
|
83
84
|
export * from "./schema/spec.js";
|
|
84
85
|
export * from "./specs.js";
|
|
85
86
|
export * from "./cancel.js";
|
|
87
|
+
export * from "./process-trees.js";
|
|
86
88
|
export * from "./assistant-actor.js";
|
|
87
89
|
export * from "./link-candidates.js";
|
|
88
90
|
export * from "./ai-decisions.js";
|
package/npm/core/light.d.ts
CHANGED
|
@@ -6,5 +6,7 @@
|
|
|
6
6
|
*/
|
|
7
7
|
export { SCHEMA_VERSION } from "./schema/version.js";
|
|
8
8
|
export { createLog, logFileOf, NO_LOG, type Log, type LogEntry, type LogLevel } from "./log.js";
|
|
9
|
-
export { recordedCommand, startTerminalRun, type TerminalRunRecorder } from "./run-log.js";
|
|
9
|
+
export { recordedCommand, retitleTerminalRuns, runLogKept, runTitle, startTerminalRun, TITLE_VALUE_FLAGS, type TerminalRunRecorder, } from "./run-log.js";
|
|
10
10
|
export { printToCurrent, withPrinter } from "./printer.js";
|
|
11
|
+
export { atticusHandles, onAtticusSignal } from "./process-trees.js";
|
|
12
|
+
export { keyIsSecret } from "./cite.js";
|
|
@@ -61,6 +61,16 @@ export declare function addManifestRepos(root: string, platform: string, entries
|
|
|
61
61
|
* profile, ADR 0009). Only the id changes; the files filed under it are the caller's to move.
|
|
62
62
|
*/
|
|
63
63
|
export declare function renameManifestRepo(root: string, repo: string, to: string): Promise<ManifestFile>;
|
|
64
|
+
/**
|
|
65
|
+
* ADR 0195 (the rename computes before it writes): the manifest that lists a repo, with its
|
|
66
|
+
* text now and its text with the id moved (comments, order and line endings kept), checked as
|
|
67
|
+
* `renameManifestRepo` checks it, and nothing written. The caller writes `next` to `file.path`.
|
|
68
|
+
*/
|
|
69
|
+
export declare function renamedManifest(root: string, repo: string, to: string): Promise<{
|
|
70
|
+
file: ManifestFile;
|
|
71
|
+
text: string;
|
|
72
|
+
next: string;
|
|
73
|
+
}>;
|
|
64
74
|
/**
|
|
65
75
|
* Rewrite every manifest at a version below `to` (the current one when left out) at that
|
|
66
76
|
* version, keeping its comments and order (ADR 0009, 0128, 0134). Nothing a person wrote
|
package/npm/core/metarepo.d.ts
CHANGED
|
@@ -47,7 +47,7 @@ export declare function evidenceDirOf(root: string): string;
|
|
|
47
47
|
* person's corrections, the verifier's report, and the read plan of a repo read in parts
|
|
48
48
|
* (addendum A-ledger). None of them is a facts file of its own.
|
|
49
49
|
*/
|
|
50
|
-
export declare const FACTS_COMPANIONS: readonly [".questions.jsonl", ".rejected.jsonl", ".reviewed.jsonl", ".corrections.jsonl", ".verify.yaml", ".read-plan.yaml", ".audit.yaml", ".contracts.yaml", ".specs.yaml", ".gaps.md"];
|
|
50
|
+
export declare const FACTS_COMPANIONS: readonly [".questions.jsonl", ".rejected.jsonl", ".reviewed.jsonl", ".corrections.jsonl", ".verify.yaml", ".read-plan.yaml", ".audit.yaml", ".contracts.yaml", ".specs.yaml", ".gaps.md", ".crosscheck.yaml"];
|
|
51
51
|
/**
|
|
52
52
|
* The repo a file in the facts folder belongs to, and whether it is the repo's facts file
|
|
53
53
|
* (`<repo>.jsonl`) or one of its companions; undefined for any other file. Every place that lists
|