@maycombhq/sdk 2.0.0-beta.2 → 2.0.0-beta.22

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.
Files changed (61) hide show
  1. package/npm/core/ai-decisions.d.ts +373 -0
  2. package/npm/core/api.d.ts +5890 -1210
  3. package/npm/core/audit.d.ts +165 -0
  4. package/npm/core/catalog.d.ts +220 -66
  5. package/npm/core/cite.d.ts +20 -4
  6. package/npm/core/contract-check.d.ts +261 -0
  7. package/npm/core/decision-batches.d.ts +29 -0
  8. package/npm/core/declared-links.d.ts +62 -0
  9. package/npm/core/eol.d.ts +5 -0
  10. package/npm/core/fact-paths.d.ts +14 -0
  11. package/npm/core/facts-callers.d.ts +2 -0
  12. package/npm/core/facts-carry.d.ts +8 -2
  13. package/npm/core/facts-join-prototype.d.ts +66 -4
  14. package/npm/core/facts-join-vendor.d.ts +20 -2
  15. package/npm/core/facts-join.d.ts +325 -1
  16. package/npm/core/facts-terms.d.ts +108 -0
  17. package/npm/core/fs.d.ts +40 -4
  18. package/npm/core/glob.d.ts +14 -0
  19. package/npm/core/host-questions.d.ts +93 -1
  20. package/npm/core/identity.d.ts +28 -0
  21. package/npm/core/index.d.ts +24 -0
  22. package/npm/core/link-candidates.d.ts +103 -0
  23. package/npm/core/link-evidence.d.ts +212 -0
  24. package/npm/core/manifest-edit.d.ts +53 -4
  25. package/npm/core/merge.d.ts +28 -0
  26. package/npm/core/metarepo.d.ts +18 -1
  27. package/npm/core/migrate.d.ts +3 -2
  28. package/npm/core/org-notes.d.ts +180 -0
  29. package/npm/core/orgpack-defaults.d.ts +22 -6
  30. package/npm/core/orgpack-load.d.ts +19 -0
  31. package/npm/core/profile-migrate.d.ts +11 -0
  32. package/npm/core/question-order.d.ts +23 -0
  33. package/npm/core/question-owners.d.ts +53 -0
  34. package/npm/core/question-proposals.d.ts +77 -0
  35. package/npm/core/question-roles.d.ts +24 -0
  36. package/npm/core/questions.d.ts +90 -6
  37. package/npm/core/repo-files.d.ts +60 -0
  38. package/npm/core/repo-reads.d.ts +44 -0
  39. package/npm/core/roles-migrate.d.ts +9 -0
  40. package/npm/core/runtime-migrate.d.ts +18 -0
  41. package/npm/core/schema/ai.d.ts +57 -9
  42. package/npm/core/schema/common.d.ts +32 -8
  43. package/npm/core/schema/component-type.d.ts +193 -0
  44. package/npm/core/schema/conventions.d.ts +80 -0
  45. package/npm/core/schema/fact-corrections.d.ts +105 -2
  46. package/npm/core/schema/facts.d.ts +410 -1
  47. package/npm/core/schema/kinds.d.ts +230 -66
  48. package/npm/core/schema/orgpack.d.ts +159 -19
  49. package/npm/core/schema/question.d.ts +228 -5
  50. package/npm/core/schema/reading-rules.d.ts +51 -0
  51. package/npm/core/schema/repo-type.d.ts +20 -2
  52. package/npm/core/schema/review.d.ts +7 -7
  53. package/npm/core/schema/scan-verify.d.ts +87 -45
  54. package/npm/core/schema/version.d.ts +4 -1
  55. package/npm/core/schema/workspace.d.ts +29 -11
  56. package/npm/core/shared-maps.d.ts +146 -0
  57. package/npm/core/stack-helpers.d.ts +32 -0
  58. package/npm/fs-repo.d.ts +2 -1
  59. package/npm/index.js +6194 -2542
  60. package/npm/listing.d.ts +14 -0
  61. package/package.json +1 -1
@@ -33,16 +33,32 @@ export declare function claimOnLines(lines: readonly string[], line: number, cla
33
33
  export declare function normalizeQuote(q: string): string;
34
34
  /** Whether a quote is the line, starts it, or sits inside it, after normalisation. */
35
35
  export declare function quoteMatches(line: string, quote: string | undefined): boolean;
36
+ /** Whether a path names a binary file by its extension (an image, an archive, a font, a build). */
37
+ export declare function isBinaryPath(path: string): boolean;
36
38
  /** A quote is not required from a binary, a notebook, a minified file, or a very long line. */
37
39
  export declare function quoteNotRequired(path: string, line: string): boolean;
38
- /** Paths whose lines are never quoted into a map. */
40
+ /**
41
+ * Paths whose lines are never quoted into a map. Each part is read as NTFS opens it (review round
42
+ * 46): a stream's name after `:` (`.env::$DATA` is `.env`) and trailing dots and spaces dropped.
43
+ */
39
44
  export declare function isSecretPath(path: string): boolean;
40
45
  /**
41
- * Redact a line that carries a secret-looking key with a literal value; a placeholder or a
42
- * reference (`${X}`, `env:X`, `vault:...`) stays, as does a line that names no such key.
43
- * A private-key block is redacted whole.
46
+ * Redact the secrets on a line, keeping what names them: a value after a secret-looking key
47
+ * (at the line's start, whatever the value; anywhere on it, a quoted literal), a setter's
48
+ * literal, a URL's password, a bearer or basic token and well-known token shapes. A
49
+ * placeholder or a reference (`${X}`, `env:X`, `vault:...`) stays, as does code that only names
50
+ * a secret word (`if (password == null)`, `tokenizer.next()`). A private-key block is redacted
51
+ * whole. A key's value is redacted to the end of the line.
44
52
  */
45
53
  export declare function redactSecrets(line: string): string;
54
+ /**
55
+ * Whether a quote redaction left as it is still holds what looks like a secret: an identifier
56
+ * with a secret word and an opaque quoted literal (8 or more characters with letters and digits,
57
+ * no spaces, not a path, URL or placeholder) on the same line, e.g.
58
+ * `creds.put(PASSWORD_KEY, "Xk9fQ2mZ7p")`. Code that only names a secret word
59
+ * (`passwordEncoder.encode(x)`, `getToken("Authorization")`) doesn't.
60
+ */
61
+ export declare function quoteHoldsSecret(quote: string): boolean;
46
62
  /**
47
63
  * Whether a word claim is put together from `cite.with` parts (ADR 0124 addendum A-derived): a
48
64
  * rake task's `namespace:task`, a key a helper prefixes (`${prefix}_conferenceCache`). Each part's
@@ -0,0 +1,261 @@
1
+ import { z } from "zod";
2
+ import type { FactEnd, FactsJoinResult } from "./facts-join.js";
3
+ import type { VendorCallMatch } from "./facts-join-vendor.js";
4
+ import type { Fact } from "./schema/facts.js";
5
+ /** A field a spec lists: a request or response property or parameter, or a message's field. */
6
+ export declare const SpecField: z.ZodObject<{
7
+ side: z.ZodEnum<{
8
+ message: "message";
9
+ request: "request";
10
+ response: "response";
11
+ }>;
12
+ name: z.ZodString;
13
+ type: z.ZodOptional<z.ZodString>;
14
+ required: z.ZodOptional<z.ZodBoolean>;
15
+ in: z.ZodOptional<z.ZodString>;
16
+ number: z.ZodOptional<z.ZodNumber>;
17
+ at: z.ZodString;
18
+ }, z.core.$strict>;
19
+ export type SpecFieldT = z.infer<typeof SpecField>;
20
+ export declare const SPEC_FORMATS: readonly ["openapi", "protobuf", "avro", "json-schema", "asyncapi"];
21
+ /**
22
+ * One operation or one message a spec file describes, as the contract check reads it. An
23
+ * operation has a method and a path (with the server's path in front); a message has the name
24
+ * of its type (a proto message's full name, an Avro record's, a JSON Schema's title) and, when
25
+ * the spec says (AsyncAPI), the topic it travels on.
26
+ */
27
+ export declare const ContractSpec: z.ZodObject<{
28
+ kind: z.ZodEnum<{
29
+ message: "message";
30
+ operation: "operation";
31
+ }>;
32
+ format: z.ZodEnum<{
33
+ openapi: "openapi";
34
+ "json-schema": "json-schema";
35
+ avro: "avro";
36
+ protobuf: "protobuf";
37
+ asyncapi: "asyncapi";
38
+ }>;
39
+ role: z.ZodEnum<{
40
+ schema: "schema";
41
+ consumer: "consumer";
42
+ own: "own";
43
+ }>;
44
+ file: z.ZodString;
45
+ line: z.ZodNumber;
46
+ method: z.ZodOptional<z.ZodString>;
47
+ path: z.ZodOptional<z.ZodString>;
48
+ entry: z.ZodOptional<z.ZodString>;
49
+ name: z.ZodOptional<z.ZodString>;
50
+ topic: z.ZodOptional<z.ZodString>;
51
+ id: z.ZodOptional<z.ZodString>;
52
+ fields: z.ZodArray<z.ZodObject<{
53
+ side: z.ZodEnum<{
54
+ message: "message";
55
+ request: "request";
56
+ response: "response";
57
+ }>;
58
+ name: z.ZodString;
59
+ type: z.ZodOptional<z.ZodString>;
60
+ required: z.ZodOptional<z.ZodBoolean>;
61
+ in: z.ZodOptional<z.ZodString>;
62
+ number: z.ZodOptional<z.ZodNumber>;
63
+ at: z.ZodString;
64
+ }, z.core.$strict>>;
65
+ errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
66
+ status: z.ZodString;
67
+ at: z.ZodString;
68
+ }, z.core.$strict>>>;
69
+ }, z.core.$strict>;
70
+ export type ContractSpecT = z.infer<typeof ContractSpec>;
71
+ /**
72
+ * The facts companion `<repo>.specs.yaml` (ADR 0164): the specs a repo's checkout holds, read at
73
+ * the facts' commit by `atticus verify <repo> --write`, so the contract check reads the same
74
+ * specs on every run without the checkout.
75
+ */
76
+ export declare const SpecsFile: z.ZodObject<{
77
+ schemaVersion: z.ZodLiteral<1>;
78
+ repo: z.ZodString;
79
+ commit: z.ZodOptional<z.ZodString>;
80
+ specs: z.ZodArray<z.ZodObject<{
81
+ kind: z.ZodEnum<{
82
+ message: "message";
83
+ operation: "operation";
84
+ }>;
85
+ format: z.ZodEnum<{
86
+ openapi: "openapi";
87
+ "json-schema": "json-schema";
88
+ avro: "avro";
89
+ protobuf: "protobuf";
90
+ asyncapi: "asyncapi";
91
+ }>;
92
+ role: z.ZodEnum<{
93
+ schema: "schema";
94
+ consumer: "consumer";
95
+ own: "own";
96
+ }>;
97
+ file: z.ZodString;
98
+ line: z.ZodNumber;
99
+ method: z.ZodOptional<z.ZodString>;
100
+ path: z.ZodOptional<z.ZodString>;
101
+ entry: z.ZodOptional<z.ZodString>;
102
+ name: z.ZodOptional<z.ZodString>;
103
+ topic: z.ZodOptional<z.ZodString>;
104
+ id: z.ZodOptional<z.ZodString>;
105
+ fields: z.ZodArray<z.ZodObject<{
106
+ side: z.ZodEnum<{
107
+ message: "message";
108
+ request: "request";
109
+ response: "response";
110
+ }>;
111
+ name: z.ZodString;
112
+ type: z.ZodOptional<z.ZodString>;
113
+ required: z.ZodOptional<z.ZodBoolean>;
114
+ in: z.ZodOptional<z.ZodString>;
115
+ number: z.ZodOptional<z.ZodNumber>;
116
+ at: z.ZodString;
117
+ }, z.core.$strict>>;
118
+ errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
119
+ status: z.ZodString;
120
+ at: z.ZodString;
121
+ }, z.core.$strict>>>;
122
+ }, z.core.$strict>>;
123
+ }, z.core.$strict>;
124
+ export type SpecsFileT = z.infer<typeof SpecsFile>;
125
+ /** The specs of a system outside the estate, taken in through intake (O2). */
126
+ export interface OutsideSpecs {
127
+ system: string;
128
+ name: string;
129
+ specs: readonly ContractSpecT[];
130
+ }
131
+ export declare const CONTRACT_KINDS: readonly ["field-missing", "field-extra", "field-not-sent", "field-required", "field-type", "field-number", "error-unlisted", "error-unanswered"];
132
+ export type ContractKind = (typeof CONTRACT_KINDS)[number];
133
+ /** One end of a comparison: who says it (a repo's code, a spec), the value, and its line. */
134
+ export interface ContractEnd {
135
+ /** The repo whose code or spec it is, or the outside system. */
136
+ repo?: string;
137
+ system?: string;
138
+ /** What this end is, in words: `forge-portal-bff's call`, `the spec forge-accounts-v1.yaml`. */
139
+ what: string;
140
+ value?: string;
141
+ /** path:line. */
142
+ at?: string;
143
+ }
144
+ export interface ContractMismatch {
145
+ /** Stable: the link, the boundary, the kind, the side and the field or status. */
146
+ id: string;
147
+ /** The catalog Interface of the link, when the join gives one. */
148
+ interface?: string;
149
+ /** Every Interface it concerns: the link's, and each gateway hop's forwarding call's. */
150
+ interfaces?: string[];
151
+ /** The call the link starts at (the publish, for a topic). */
152
+ call: FactEnd;
153
+ /** What it reaches: an entry of the estate, or an outside system. */
154
+ entry?: FactEnd;
155
+ system?: string;
156
+ /** `mismatch`: the two sides disagree; `unconfirmed`: a mapping on the way isn't traced. */
157
+ status: "mismatch" | "unconfirmed";
158
+ kind: ContractKind;
159
+ side?: "request" | "response" | "message";
160
+ field?: string;
161
+ error?: string;
162
+ /** The side that sends (or, for a response, reads) and the side that takes (or returns). */
163
+ sender: ContractEnd;
164
+ receiver: ContractEnd;
165
+ /** The mapping lines the comparison went through (`repo path:line`), in order. */
166
+ via?: string[];
167
+ /** The mapping that isn't traced, when `unconfirmed`. */
168
+ untraced?: string;
169
+ message: string;
170
+ }
171
+ /** A link compared: how many boundaries had something on both sides, and what was found. */
172
+ export interface ContractLink {
173
+ key: string;
174
+ interface?: string;
175
+ /** Every Interface the link's check concerns: its own, and each gateway hop's forwarding call's. */
176
+ interfaces?: string[];
177
+ call: FactEnd;
178
+ entry?: FactEnd;
179
+ system?: string;
180
+ kind: "rest" | "topic" | "outside";
181
+ method?: string;
182
+ path: string;
183
+ /** The gateway routes on the way, in order (`repo` of each). */
184
+ through: string[];
185
+ /** The specs read for it (`file:line`, the repo's or intake's). */
186
+ specs: string[];
187
+ /** Boundaries where both sides said something about the payload. */
188
+ compared: number;
189
+ mismatches: number;
190
+ unconfirmed: number;
191
+ }
192
+ export interface ContractCheckResult {
193
+ links: ContractLink[];
194
+ findings: ContractMismatch[];
195
+ counts: {
196
+ links: number;
197
+ compared: number;
198
+ mismatches: number;
199
+ unconfirmed: number;
200
+ /**
201
+ * ADR 0172: the calls no link starts at (not joined, not to an outside system), so nothing on
202
+ * their other side can be compared until they join.
203
+ */
204
+ unlinked: number;
205
+ };
206
+ }
207
+ export interface ContractCheckInput {
208
+ repos: readonly {
209
+ repo: string;
210
+ facts: readonly Fact[];
211
+ }[];
212
+ join: FactsJoinResult;
213
+ /** Every repo's `<repo>.specs.yaml` on file. */
214
+ specs?: readonly SpecsFileT[];
215
+ /** The specs of systems outside the estate, from intake. */
216
+ outside?: readonly OutsideSpecs[];
217
+ /** The calls to outside systems matched to their spec's operations (`joinVendorOperations`). */
218
+ vendorMatches?: readonly VendorCallMatch[];
219
+ }
220
+ /** The words of the check, in one place: the CLI, the API and the app say these. */
221
+ export declare const CONTRACT_WORDS: {
222
+ extra: (side: string, name: string, s: string, sAt: string, r: string) => string;
223
+ notSent: (side: string, name: string, r: string, rAt: string, s: string) => string;
224
+ missing: (name: string, s: string, sAt: string, r: string) => string;
225
+ messageMissing: (name: string, r: string, rAt: string, s: string) => string;
226
+ messageExtra: (name: string, s: string, sAt: string, r: string) => string;
227
+ undocumented: (name: string, r: string, rAt: string, s: string) => string;
228
+ required: (side: string, name: string, a: string, aAt: string, b: string, bAt: string) => string;
229
+ type: (side: string, name: string, a: string, at: string, aAt: string, b: string, bt: string, bAt: string) => string;
230
+ number: (n: number, a: string, an: string, aAt: string, b: string, bn: string, bAt: string) => string;
231
+ errorUnlisted: (status: string, r: string, rAt: string, s: string, spec: boolean) => string;
232
+ errorUnanswered: (status: string, s: string, sAt: string, r: string) => string;
233
+ unconfirmed: (message: string, untraced: string) => string;
234
+ };
235
+ /**
236
+ * The `transform` a reader gives the field fact that names a publish's or listener's message type
237
+ * (ADR 0164): the field's `name` is the type as the line writes it (`PaymentSettled`, the
238
+ * generated proto class or the Avro record), its `type` the full name when the code gives one
239
+ * (`forge.payments.v1.PaymentSettled`), cited where the publish or the listener names it. It is
240
+ * no field of the payload: it ties the payload to its spec.
241
+ */
242
+ export declare const MESSAGE_TYPE_TRANSFORM = "message type";
243
+ export declare const isMessageType: (f: {
244
+ side?: string;
245
+ transform?: string;
246
+ }) => boolean;
247
+ /** A `transform` that says the field travels inside the field it is mapped to (an envelope). */
248
+ export declare const ENVELOPE_TRANSFORM: RegExp;
249
+ /** Compare the payload on both sides of every link the join made, and of every call to an outside system with a spec. */
250
+ export declare function checkContracts(input: ContractCheckInput): ContractCheckResult;
251
+ /**
252
+ * ADR 0172: the calls of the estate no link starts at: a REST, SOAP or gRPC call, or a publish,
253
+ * the join neither joined nor left to an outside system. Their payload is checked once they join.
254
+ */
255
+ export declare function unlinkedCalls(input: Pick<ContractCheckInput, "repos" | "join">): FactEnd[];
256
+ /**
257
+ * The findings a newer spec of an outside system brings (ADR 0164): those against `next` that
258
+ * the same calls didn't have against `prev`, by kind, side and field. What the Outside systems
259
+ * page shows when a vendor's or a team's new spec is taken in.
260
+ */
261
+ export declare function newFindings(next: readonly ContractMismatch[], prev: readonly ContractMismatch[]): ContractMismatch[];
@@ -0,0 +1,29 @@
1
+ import { type DecisionBatchT } from "./ai-decisions.js";
2
+ /**
3
+ * ADR 0181: the batch records under `decisions/` (`.atticus/decisions/` when adopted), one file
4
+ * per batch, and the `corrections-v2` upgrade step. The lines a batch names stay in the repos'
5
+ * corrections files and the answers in the question files; the record is what Undo reads.
6
+ */
7
+ /** Where a batch's record is, relative to the root. */
8
+ export declare const batchRelOf: (root: string, id: string) => string;
9
+ /** Write a batch's record (a new one, or the same one undone). */
10
+ export declare function writeBatch(root: string, b: DecisionBatchT): Promise<string>;
11
+ /** One batch's record; undefined when there is none (or the id isn't a batch's). */
12
+ export declare function readBatch(root: string, id: string): Promise<DecisionBatchT | undefined>;
13
+ /** Every batch on record, newest first, with the files that don't read as one. */
14
+ export declare function listBatches(root: string): Promise<{
15
+ batches: DecisionBatchT[];
16
+ problems: {
17
+ file: string;
18
+ message: string;
19
+ }[];
20
+ }>;
21
+ /**
22
+ * The `corrections-v2` step (ADR 0181): a corrections line that uses version 2's fields (an AI
23
+ * pairing, a batch, a rule, a match, an unlink) but says version 1, as a hand edit might, says 2;
24
+ * every other line means the same at version 1 and is left exactly as it is. Returns the files,
25
+ * relative to the root; with dryRun, the files it would rewrite.
26
+ */
27
+ export declare function migrateCorrections(root: string, o?: {
28
+ dryRun?: boolean;
29
+ }): Promise<string[]>;
@@ -0,0 +1,62 @@
1
+ import { type LineChange } from "./manifest-edit.js";
2
+ /**
3
+ * G3 (ADR 0174): what a person declares on the canvas that the code can't show, written to the
4
+ * profile that has the system, comments and order kept, for review. A topic the system publishes
5
+ * or listens on goes under its `topics` (ADR 0162: a publish or listener of the estate with no
6
+ * counterpart lands on it, marked declared); a call it makes to a gateway route goes under its
7
+ * `calls` (A-callers). Who declared it and when is the line's comment. Nothing here is a fact.
8
+ */
9
+ export type Declared = {
10
+ kind: "topic";
11
+ system: string;
12
+ topic: string;
13
+ side: "publishes" | "listens";
14
+ } | {
15
+ kind: "call";
16
+ system: string;
17
+ route: string;
18
+ };
19
+ export interface DeclaredOnFile {
20
+ kind: "topic" | "call";
21
+ system: string;
22
+ /** The topic, or the route. */
23
+ value: string;
24
+ /** publishes or listens, for a topic declared from the canvas. */
25
+ side?: "publishes" | "listens";
26
+ /** Who declared it and when, from its comment; none for a line a person wrote by hand. */
27
+ by?: string;
28
+ at?: string;
29
+ }
30
+ export declare class DeclareError extends Error {
31
+ readonly code: "not-found" | "invalid" | "exists";
32
+ constructor(code: "not-found" | "invalid" | "exists", message: string);
33
+ }
34
+ /** The comment a declaration carries: which side, who and when. */
35
+ export declare const declaredComment: (by: string, at: string, side?: "publishes" | "listens") => string;
36
+ /**
37
+ * Write a declaration (or, with `preview`, say the lines it changes). The profile moves to
38
+ * version 2 when a topic needs it; the whole profile is checked before it is written.
39
+ */
40
+ export declare function declareLink(root: string, d: Declared, o: {
41
+ by: string;
42
+ at: string;
43
+ preview?: boolean;
44
+ }): Promise<{
45
+ rel: string;
46
+ changes: LineChange[];
47
+ written: boolean;
48
+ }>;
49
+ /** Undo: remove a declared topic or call from the system's list, exactly that one. */
50
+ export declare function undeclareLink(root: string, d: {
51
+ kind: "topic" | "call";
52
+ system: string;
53
+ value: string;
54
+ }): Promise<{
55
+ rel: string;
56
+ changes: LineChange[];
57
+ }>;
58
+ /** A system's declarations, with who and when where the canvas wrote them. */
59
+ export declare function declaredOf(root: string, system: string): Promise<{
60
+ rel?: string;
61
+ list: DeclaredOnFile[];
62
+ }>;
@@ -0,0 +1,5 @@
1
+ /**
2
+ * A file rewritten keeps its line endings: a Windows file's CRLF stays CRLF (where Git doesn't
3
+ * normalise them, the whole file would otherwise show as changed in the upgrade's pull request).
4
+ */
5
+ export declare function keepLineEndings(was: string, now: string): string;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * A file path as Atticus reads it: with `/` only (ADR 0124 addendum W-paths). A facts line
3
+ * written on Windows can cite `src\main\App.java`; every reader of the facts file (the facts
4
+ * parser, the corrections file, the reviewed list, the reader's answer) passes what it reads
5
+ * through here, so the verifier, the join's folder and bundle rules and every record see one
6
+ * form, whichever OS wrote the line.
7
+ */
8
+ export declare const forwardSlashes: (path: string) => string;
9
+ /**
10
+ * A parsed facts line (or a correction, or any JSON beside them) with every `file` it carries,
11
+ * at any depth (`cite.file`, `cite.with[].file`, an auth's, a scope's, a caller's), written with
12
+ * `/`. Nothing else changes: a claimed path or key is not a file. Returns a copy.
13
+ */
14
+ export declare function normalizeFactPaths<T>(json: T): T;
@@ -119,6 +119,8 @@ export interface JoinCallersInput {
119
119
  declared?: readonly DeclaredCallInput[];
120
120
  /** The estate's facing words, as given to `joinFacts`. */
121
121
  facing?: FacingWords;
122
+ /** The gateway bundle folders, as given to `joinFacts` (ADR 0147). */
123
+ bundleFolders?: readonly string[];
122
124
  }
123
125
  /** Every call a person declared in the org pack's profiles, one per route or identity named. */
124
126
  export declare function declaredCallsOf(profiles: readonly {
@@ -6,13 +6,19 @@ import type { Fact } from "./schema/facts.js";
6
6
  * that was edited, renamed or deleted is read again. Pure: the diff comes from the git adapter
7
7
  * (`changedFiles` in @maycombhq/workspace), so the same facts and the same diff split the same way.
8
8
  */
9
- /** One file changed between two commits, as `git diff --name-status -M` says it. */
9
+ /** One file changed between two commits, as `git diff --raw -M` says it. */
10
10
  export interface FileChange {
11
11
  status: "added" | "modified" | "deleted" | "renamed" | "copied" | "type-changed";
12
12
  /** The path at the newer commit (a deleted file's path at the older one). */
13
13
  path: string;
14
14
  /** A rename's or copy's path at the older commit. */
15
15
  from?: string;
16
+ /**
17
+ * Review round 49: the path is a submodule's gitlink (mode 160000 at either commit), so the
18
+ * diff names the folder, not the files in it that changed. Every cited file under it is read
19
+ * again.
20
+ */
21
+ gitlink?: boolean;
16
22
  }
17
23
  /** Why a fact must be read again: the first file it cites that changed, and how. */
18
24
  export interface StaleCite {
@@ -24,7 +30,7 @@ export interface StaleCite {
24
30
  }
25
31
  /**
26
32
  * The files a fact rests on: its cite and the cite's `with` parts, an entry's `authCite` (ADR
27
- * 0124 addendum A-read), and for a flow every step's and error path's cite and parts. Unique and
33
+ * 0124 addendum A-read) and a call's `authCite` and `tlsCite` (ADR 0163), with their parts, and for a flow every step's and error path's cite and parts. Unique and
28
34
  * sorted, except that a fact's own cited file comes first for a non-flow fact.
29
35
  */
30
36
  export declare function citedFiles(f: Fact): string[];
@@ -1,4 +1,4 @@
1
- import { type FactEnd, type JoinHow, type JoinRepo } from "./facts-join.js";
1
+ import { type FactEnd, type JoinHow, type FacingWords, type JoinRepo } from "./facts-join.js";
2
2
  import { type JoinVendor, type JoinVendorOperation } from "./facts-join-vendor.js";
3
3
  import type { Fact, FactOf } from "./schema/facts.js";
4
4
  /**
@@ -55,6 +55,10 @@ export interface PrototypeVendorField {
55
55
  name: string;
56
56
  type?: string;
57
57
  required?: boolean;
58
+ /** The values the spec's `enum` lists (ADR 0142). */
59
+ enum?: readonly string[];
60
+ /** Where a request field travels (`header` makes it a header, ADR 0142). */
61
+ in?: string;
58
62
  /** spec path:line of the property. */
59
63
  at?: string;
60
64
  }
@@ -62,18 +66,30 @@ export interface PrototypeVendorOperation extends JoinVendorOperation {
62
66
  auth?: string;
63
67
  scopes?: readonly string[];
64
68
  fields?: readonly PrototypeVendorField[];
69
+ /** The error statuses the spec lists (4xx, 5xx), each with its line (ADR 0142). */
70
+ errors?: readonly {
71
+ status: string;
72
+ at?: string;
73
+ }[];
65
74
  }
66
- /** A vendor with its published operations and their fields (ADR 0130's reading of its spec). */
75
+ /**
76
+ * A vendor, or another team's system (O2, `boundary: internal`), with its published operations
77
+ * and their fields (ADR 0130's reading of its spec).
78
+ */
67
79
  export interface PrototypeVendor extends JoinVendor {
68
80
  operations: readonly PrototypeVendorOperation[];
69
81
  }
70
- export type PrototypeDifferenceKind = "field-missing" | "field-type" | "field-required" | "scope-missing" | "auth";
82
+ export type PrototypeDifferenceKind = "field-missing" | "field-type" | "field-required" | "field-enum" | "header-missing" | "header-required" | "error-missing" | "error-unhandled" | "scope-missing" | "auth";
71
83
  /** One way the estate (or the vendor) serves an operation other than as the prototype needs. */
72
84
  export interface PrototypeDifference {
73
85
  kind: PrototypeDifferenceKind;
74
86
  side?: "request" | "response";
75
87
  field?: string;
76
88
  scope?: string;
89
+ /** field-enum: the value one side lists and the other doesn't. */
90
+ value?: string;
91
+ /** error-missing, error-unhandled: the status. */
92
+ status?: string;
77
93
  /** What the prototype says, and the line it says it on. */
78
94
  prototype: {
79
95
  value: string;
@@ -120,8 +136,13 @@ export interface PrototypeCall {
120
136
  method: string;
121
137
  path: string;
122
138
  at?: string;
123
- /** The estate's repos that forward to this vendor already: where the new route goes. */
139
+ /**
140
+ * The estate's repos that forward to this vendor already: where the new route goes. For
141
+ * another team's system, the repos that call it already.
142
+ */
124
143
  through: string[];
144
+ /** `internal`: another team's system, which the change calls as it publishes it (O2). */
145
+ boundary?: "vendor" | "internal";
125
146
  };
126
147
  /** Two or more estate entries serve it equally well: a person says which. */
127
148
  candidates?: FactEnd[];
@@ -156,6 +177,10 @@ export interface ComparePrototypeInput {
156
177
  vendors?: readonly PrototypeVendor[];
157
178
  /** The org pack's outside systems (vendors' ids and names), as the estate join takes them. */
158
179
  outside?: readonly string[];
180
+ /** The org pack's facing words (ADR 0147), as the estate join takes them. */
181
+ facing?: FacingWords;
182
+ /** The org pack's gateway bundle folders (ADR 0147), as the estate join takes them. */
183
+ bundleFolders?: readonly string[];
159
184
  }
160
185
  /** The words of the comparison, in one place: the CLI, the attached document and the app say these. */
161
186
  export declare const PROTOTYPE_WORDS: {
@@ -165,6 +190,16 @@ export declare const PROTOTYPE_WORDS: {
165
190
  ambiguous: (what: string, who: string, n: number) => string;
166
191
  new: (what: string, who: string) => string;
167
192
  vendor: (what: string, who: string, name: string, op: string, at: string, through: string[]) => string;
193
+ team: (what: string, who: string, name: string, op: string, at: string, through: string[]) => string;
194
+ enumNotTaken: (name: string, v: string, at: string, repo: string, theirs: string[], theirAt: string) => string;
195
+ enumNotReturned: (name: string, v: string, at: string, repo: string, theirs: string[], theirAt: string) => string;
196
+ enumUnhandled: (name: string, v: string, theirAt: string, repo: string, mine: string[], at: string) => string;
197
+ headerMissing: (side: string, name: string, at: string, repo: string, theirs: string[]) => string;
198
+ headerRequired: (name: string, theirAt: string, repo: string) => string;
199
+ errorMissing: (status: string, at: string, repo: string, theirs: string[]) => string;
200
+ errorUnhandled: (status: string, theirAt: string, repo: string, mine: string[]) => string;
201
+ architectureHeading: string;
202
+ architectureIntro: (repo: string) => string;
168
203
  fieldMissing: (side: string, name: string, at: string, repo: string) => string;
169
204
  fieldType: (side: string, name: string, mine: string, at: string, repo: string, theirs: string, raw: string, theirAt: string) => string;
170
205
  fieldRequired: (side: string, name: string, mine: boolean, at: string, repo: string, theirAt: string) => string;
@@ -172,6 +207,33 @@ export declare const PROTOTYPE_WORDS: {
172
207
  auth: (mine: string, at: string, repo: string, theirs: string, theirAt: string) => string;
173
208
  left: (what: string, who: string) => string;
174
209
  };
210
+ /**
211
+ * The family a declared type belongs to, compared across languages; undefined when unsure. The
212
+ * contract check (ADR 0164) reads it too, with protobuf's and Avro's scalar names.
213
+ */
214
+ export declare function typeFamily(t: string | undefined): string | undefined;
215
+ /**
216
+ * The values an enum field's `type` lists (ADR 0142), as the facts write it: a union of quoted
217
+ * literals (`"captured" | "failed"`), a named list (`ChargeStatus(CAPTURED|FAILED)`,
218
+ * `enum(EUR, USD)`), or the values alone (`EUR|USD`). Undefined when the type lists none: a
219
+ * plain `String`, or an enum named but not listed, whose values are unknown.
220
+ */
221
+ export declare function enumValues(type: string | undefined): string[] | undefined;
222
+ export declare const isHeaderName: (name: string) => boolean;
175
223
  /** Compare a prototype's calls with what the estate and the vendors serve. */
176
224
  export declare function comparePrototype(input: ComparePrototypeInput): PrototypeComparison;
225
+ /**
226
+ * The calls nothing in the estate serves, for the architecture stage (ADR 0142): a section of the
227
+ * attached comparison, each call with what it sends and reads, cited. Where each goes is that
228
+ * stage's to decide, so the footprint gains nothing from them; the stage reads this section back
229
+ * (`readPrototypeArchitecture`) and is told to place each one. Empty when nothing is new.
230
+ */
231
+ export declare function prototypeArchitectureSection(c: PrototypeComparison,
232
+ /** The prototype's facts, for the fields each call carries. */
233
+ facts: readonly Fact[]): string[];
234
+ /**
235
+ * The calls an attached comparison lists for the architecture stage, as written (with the
236
+ * `[file:line]` an attached file's read text puts before each line, when it has one).
237
+ */
238
+ export declare function readPrototypeArchitecture(text: string): string[];
177
239
  export {};
@@ -31,10 +31,21 @@ export interface JoinVendorOperation {
31
31
  /** spec path:line of the operation. */
32
32
  cite?: string;
33
33
  }
34
- /** A vendor and what the join needs to find its calls: its names, its hosts and its operations. */
34
+ /**
35
+ * A vendor, or any other system outside the estate that publishes a spec (O2: another team's,
36
+ * boundary `internal`), and what the join needs to find its calls: its names, its hosts and its
37
+ * operations.
38
+ */
35
39
  export interface JoinVendor {
36
- /** The org pack's system id (boundary vendor). */
40
+ /** The org pack's system id: a vendor's, or another outside system's. */
37
41
  system: string;
42
+ /**
43
+ * The system's boundary in the profile. `internal` (another team's system, ADR 0142): the
44
+ * estate's services call it themselves, not through the external gateway, so a service's own
45
+ * call to it is matched too (`direct` on the match). Left out, or `vendor`: only a gateway's
46
+ * forwarding calls are matched, as ADR 0130 says.
47
+ */
48
+ boundary?: "vendor" | "internal";
38
49
  /** Its name and aliases, as the org pack writes them. */
39
50
  names: readonly string[];
40
51
  /** The hosts its spec's servers name, and any host the org pack gives it (patterns allowed). */
@@ -57,6 +68,11 @@ export interface VendorCallMatch {
57
68
  method?: string;
58
69
  /** The path the gateway forwards to. */
59
70
  path: string;
71
+ /**
72
+ * ADR 0142: a service's own call to another team's system, not a gateway's forwarding call;
73
+ * `route` is then the entry the call is made under, when it names one.
74
+ */
75
+ direct?: true;
60
76
  }
61
77
  /** A forwarding call to an operation the vendor's spec doesn't publish. */
62
78
  export interface VendorCallGap {
@@ -87,6 +103,8 @@ export interface JoinVendorOperationsInput {
87
103
  vendors: readonly JoinVendor[];
88
104
  /** A person's answer naming the repo or system a call goes to: repo → call fact id → name. */
89
105
  targets?: Readonly<Record<string, Readonly<Record<string, string>>>>;
106
+ /** The gateway bundle folders, as given to `joinFacts` (ADR 0147). */
107
+ bundleFolders?: readonly string[];
90
108
  }
91
109
  /** Match every gateway forwarding call that goes to a vendor to the vendor operation it reaches. */
92
110
  export declare function joinVendorOperations(input: JoinVendorOperationsInput): VendorJoinResult;