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

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 (54) hide show
  1. package/npm/core/ai-decisions.d.ts +360 -0
  2. package/npm/core/api.d.ts +5806 -1212
  3. package/npm/core/audit.d.ts +165 -0
  4. package/npm/core/catalog.d.ts +220 -66
  5. package/npm/core/contract-check.d.ts +261 -0
  6. package/npm/core/decision-batches.d.ts +29 -0
  7. package/npm/core/declared-links.d.ts +62 -0
  8. package/npm/core/eol.d.ts +5 -0
  9. package/npm/core/fact-paths.d.ts +14 -0
  10. package/npm/core/facts-callers.d.ts +2 -0
  11. package/npm/core/facts-join-prototype.d.ts +66 -4
  12. package/npm/core/facts-join-vendor.d.ts +20 -2
  13. package/npm/core/facts-join.d.ts +320 -1
  14. package/npm/core/facts-terms.d.ts +108 -0
  15. package/npm/core/fs.d.ts +23 -4
  16. package/npm/core/host-questions.d.ts +93 -1
  17. package/npm/core/index.d.ts +22 -0
  18. package/npm/core/link-candidates.d.ts +103 -0
  19. package/npm/core/link-evidence.d.ts +212 -0
  20. package/npm/core/manifest-edit.d.ts +53 -4
  21. package/npm/core/merge.d.ts +28 -0
  22. package/npm/core/metarepo.d.ts +18 -1
  23. package/npm/core/migrate.d.ts +3 -2
  24. package/npm/core/org-notes.d.ts +180 -0
  25. package/npm/core/orgpack-defaults.d.ts +22 -6
  26. package/npm/core/orgpack-load.d.ts +19 -0
  27. package/npm/core/profile-migrate.d.ts +11 -0
  28. package/npm/core/question-order.d.ts +23 -0
  29. package/npm/core/question-owners.d.ts +53 -0
  30. package/npm/core/question-proposals.d.ts +77 -0
  31. package/npm/core/question-roles.d.ts +24 -0
  32. package/npm/core/questions.d.ts +85 -6
  33. package/npm/core/repo-reads.d.ts +44 -0
  34. package/npm/core/roles-migrate.d.ts +9 -0
  35. package/npm/core/runtime-migrate.d.ts +18 -0
  36. package/npm/core/schema/ai.d.ts +57 -9
  37. package/npm/core/schema/common.d.ts +32 -8
  38. package/npm/core/schema/component-type.d.ts +193 -0
  39. package/npm/core/schema/conventions.d.ts +80 -0
  40. package/npm/core/schema/fact-corrections.d.ts +96 -2
  41. package/npm/core/schema/facts.d.ts +410 -1
  42. package/npm/core/schema/kinds.d.ts +230 -66
  43. package/npm/core/schema/orgpack.d.ts +110 -7
  44. package/npm/core/schema/question.d.ts +228 -5
  45. package/npm/core/schema/reading-rules.d.ts +51 -0
  46. package/npm/core/schema/repo-type.d.ts +20 -2
  47. package/npm/core/schema/review.d.ts +7 -7
  48. package/npm/core/schema/scan-verify.d.ts +87 -45
  49. package/npm/core/schema/version.d.ts +4 -1
  50. package/npm/core/schema/workspace.d.ts +29 -11
  51. package/npm/core/shared-maps.d.ts +146 -0
  52. package/npm/core/stack-helpers.d.ts +32 -0
  53. package/npm/index.js +5614 -2343
  54. package/package.json +1 -1
@@ -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 {
@@ -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;