@maycombhq/sdk 2.0.0-beta.1 → 2.0.0-beta.11
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/{dist → npm}/cache.d.ts +1 -1
- package/npm/core/api.d.ts +7964 -0
- package/npm/core/assistant-actor.d.ts +15 -0
- package/npm/core/audit.d.ts +153 -0
- package/npm/core/branches.d.ts +21 -0
- package/npm/core/cancel.d.ts +9 -0
- package/npm/core/catalog.d.ts +4735 -0
- package/npm/core/change-types-migrate.d.ts +10 -0
- package/npm/core/cite.d.ts +54 -0
- package/npm/core/contract-check.d.ts +251 -0
- package/npm/core/curated.d.ts +37 -0
- package/npm/core/fact-paths.d.ts +14 -0
- package/npm/core/facts-callers.d.ts +152 -0
- package/npm/core/facts-carry.d.ts +36 -0
- package/npm/core/facts-join-prototype.d.ts +239 -0
- package/npm/core/facts-join-vendor.d.ts +110 -0
- package/npm/core/facts-join.d.ts +482 -0
- package/npm/core/facts-terms.d.ts +108 -0
- package/npm/core/facts.d.ts +94 -0
- package/npm/core/fs.d.ts +47 -0
- package/npm/core/gates-migrate.d.ts +10 -0
- package/npm/core/host-questions.d.ts +111 -0
- package/npm/core/identity.d.ts +17 -0
- package/npm/core/index.d.ts +77 -0
- package/npm/core/json-schema.d.ts +20 -0
- package/npm/core/judgments.d.ts +63 -0
- package/npm/core/light.d.ts +8 -0
- package/npm/core/link-evidence.d.ts +212 -0
- package/npm/core/log.d.ts +49 -0
- package/npm/core/manifest-edit.d.ts +57 -0
- package/npm/core/merge.d.ts +85 -0
- package/npm/core/metarepo.d.ts +91 -0
- package/npm/core/migrate.d.ts +32 -0
- package/npm/core/migration-files.d.ts +13 -0
- package/npm/core/org-notes.d.ts +180 -0
- package/npm/core/orgpack-defaults.d.ts +199 -0
- package/npm/core/orgpack-load.d.ts +102 -0
- package/npm/core/profile-migrate.d.ts +11 -0
- package/npm/core/question-order.d.ts +23 -0
- package/npm/core/question-owners.d.ts +53 -0
- package/npm/core/question-proposals.d.ts +77 -0
- package/npm/core/questions.d.ts +312 -0
- package/npm/core/record-cache.d.ts +52 -0
- package/npm/core/refs.d.ts +9 -0
- package/npm/core/repo-description.d.ts +44 -0
- package/npm/core/repo-reads.d.ts +44 -0
- package/npm/core/roles-migrate.d.ts +9 -0
- package/npm/core/runtime-migrate.d.ts +11 -0
- package/npm/core/schema/ai.d.ts +397 -0
- package/npm/core/schema/change.d.ts +244 -0
- package/npm/core/schema/common.d.ts +135 -0
- package/npm/core/schema/conventions.d.ts +80 -0
- package/npm/core/schema/dialect.d.ts +801 -0
- package/npm/core/schema/executors.d.ts +396 -0
- package/npm/core/schema/fact-corrections.d.ts +56 -0
- package/npm/core/schema/facts.d.ts +1773 -0
- package/npm/core/schema/frameworks.d.ts +371 -0
- package/npm/core/schema/judgment.d.ts +77 -0
- package/npm/core/schema/kinds.d.ts +5168 -0
- package/npm/core/schema/layout.d.ts +25 -0
- package/npm/core/schema/orgpack.d.ts +1193 -0
- package/npm/core/schema/plugin.d.ts +73 -0
- package/npm/core/schema/question.d.ts +230 -0
- package/npm/core/schema/repo-type.d.ts +127 -0
- package/npm/core/schema/review.d.ts +558 -0
- package/npm/core/schema/scan-settings.d.ts +34 -0
- package/npm/core/schema/scan-verify.d.ts +535 -0
- package/npm/core/schema/spec.d.ts +269 -0
- package/npm/core/schema/version.d.ts +10 -0
- package/npm/core/schema/workspace.d.ts +330 -0
- package/npm/core/serialize.d.ts +17 -0
- package/npm/core/shared-maps.d.ts +146 -0
- package/npm/core/sources-migrate.d.ts +15 -0
- package/npm/core/specs.d.ts +66 -0
- package/npm/core/stack-helpers.d.ts +32 -0
- package/npm/core/tar-read.d.ts +13 -0
- package/npm/core/template.d.ts +101 -0
- package/npm/core/words.d.ts +13 -0
- package/npm/core/zip-read.d.ts +37 -0
- package/npm/core/zip.d.ts +13 -0
- package/npm/index.js +10097 -0
- package/{dist → npm}/plugin.d.ts +1 -1
- package/{dist → npm}/runner.d.ts +1 -1
- package/package.json +10 -11
- package/dist/cache.js +0 -115
- package/dist/cache.js.map +0 -1
- package/dist/fs-repo.js +0 -120
- package/dist/fs-repo.js.map +0 -1
- package/dist/index.js +0 -7
- package/dist/index.js.map +0 -1
- package/dist/parse-cache.js +0 -275
- package/dist/parse-cache.js.map +0 -1
- package/dist/plugin.js +0 -85
- package/dist/plugin.js.map +0 -1
- package/dist/runner.js +0 -209
- package/dist/runner.js.map +0 -1
- package/dist/sandbox.js +0 -443
- package/dist/sandbox.js.map +0 -1
- /package/{dist → npm}/fs-repo.d.ts +0 -0
- /package/{dist → npm}/index.d.ts +0 -0
- /package/{dist → npm}/parse-cache.d.ts +0 -0
- /package/{dist → npm}/sandbox.d.ts +0 -0
|
@@ -0,0 +1,239 @@
|
|
|
1
|
+
import { type FactEnd, type JoinHow, type FacingWords, type JoinRepo } from "./facts-join.js";
|
|
2
|
+
import { type JoinVendor, type JoinVendorOperation } from "./facts-join-vendor.js";
|
|
3
|
+
import type { Fact, FactOf } from "./schema/facts.js";
|
|
4
|
+
/**
|
|
5
|
+
* A prototype compared with the estate (ADR 0133). A team's working prototype (a UI, its BFF
|
|
6
|
+
* behind SSO, and the backend mocked) states exactly what a change must deliver: its screens'
|
|
7
|
+
* calls to its BFF, and its BFF's calls to the mocks. This places each of those calls in one of
|
|
8
|
+
* four groups, citing the prototype's line and, where there is one, the estate's or the vendor's:
|
|
9
|
+
*
|
|
10
|
+
* - **exists**: the estate serves it as the prototype needs (through the gateway chain, where the
|
|
11
|
+
* estate join follows one);
|
|
12
|
+
* - **changes**: the estate serves the operation, but a field the prototype sends or reads is
|
|
13
|
+
* missing or differs (type, required-ness), or the prototype's sign-on asks for a scope the
|
|
14
|
+
* estate doesn't demand, or a different auth;
|
|
15
|
+
* - **new**: nothing in the estate serves it and no vendor publishes it;
|
|
16
|
+
* - **vendor**: only a vendor's published operation provides it, so it needs a route through the
|
|
17
|
+
* external gateway (the repos that forward to that vendor already are named).
|
|
18
|
+
*
|
|
19
|
+
* Nothing new matches a call: the estate side is the estate join (`joinFacts`, ADR 0124 C-join,
|
|
20
|
+
* with its fallback by method and path and its walk through gateways), and the vendor side is
|
|
21
|
+
* ADR 0130's `joinVendorOperations`. Inside the prototype, a call is paired with the entry it
|
|
22
|
+
* lands on by `routeScore`, the join's own path rule. A prototype's facts are never projected
|
|
23
|
+
* into the catalog; they are read here, and only here.
|
|
24
|
+
*
|
|
25
|
+
* Pure and deterministic: the same facts and vendors give the same comparison, in any order.
|
|
26
|
+
*/
|
|
27
|
+
/** A repo type that marks a prototype (`prototype`, `prototype-<anything>`), from the manifest. */
|
|
28
|
+
export declare const PROTOTYPE_TYPE: RegExp;
|
|
29
|
+
/** Whether a manifest repo type is a prototype's. */
|
|
30
|
+
export declare const isPrototypeType: (type: string | undefined) => boolean;
|
|
31
|
+
/**
|
|
32
|
+
* The mock tools whose declarations mark a module as the mocked backend (a framework fact naming
|
|
33
|
+
* one, with the module as its component): MSW, WireMock, json-server, MockServer, Prism, Mirage.
|
|
34
|
+
*/
|
|
35
|
+
export declare const MOCK_FRAMEWORKS: RegExp;
|
|
36
|
+
/**
|
|
37
|
+
* A mock's file, by its path: a mocks or stubs folder, a WireMock mapping, a json-server
|
|
38
|
+
* `db.json` or `routes.json`, a Postman collection.
|
|
39
|
+
*/
|
|
40
|
+
export declare const MOCK_FILE: RegExp;
|
|
41
|
+
type Entry = FactOf<"entry">;
|
|
42
|
+
/**
|
|
43
|
+
* Whether an entry is one of the prototype's mocks: its file is a mock's, its module declares a
|
|
44
|
+
* mock tool (a framework fact with that component), or its citation's other lines hold a mock
|
|
45
|
+
* profile (`@Profile("mock")`).
|
|
46
|
+
*/
|
|
47
|
+
export declare function isMockEntry(e: Entry, facts: readonly Fact[]): boolean;
|
|
48
|
+
export declare const PROTOTYPE_GROUPS: readonly ["exists", "changes", "new", "vendor"];
|
|
49
|
+
export type PrototypeGroup = (typeof PROTOTYPE_GROUPS)[number];
|
|
50
|
+
/** `ui-bff`: a screen's call to the prototype's BFF; `bff-mock`: the BFF's call to a mock. */
|
|
51
|
+
export type PrototypeLeg = "ui-bff" | "bff-mock";
|
|
52
|
+
/** A field of a vendor operation, as intake reads it from the spec. */
|
|
53
|
+
export interface PrototypeVendorField {
|
|
54
|
+
side: "request" | "response";
|
|
55
|
+
name: string;
|
|
56
|
+
type?: string;
|
|
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;
|
|
62
|
+
/** spec path:line of the property. */
|
|
63
|
+
at?: string;
|
|
64
|
+
}
|
|
65
|
+
export interface PrototypeVendorOperation extends JoinVendorOperation {
|
|
66
|
+
auth?: string;
|
|
67
|
+
scopes?: readonly string[];
|
|
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
|
+
}[];
|
|
74
|
+
}
|
|
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
|
+
*/
|
|
79
|
+
export interface PrototypeVendor extends JoinVendor {
|
|
80
|
+
operations: readonly PrototypeVendorOperation[];
|
|
81
|
+
}
|
|
82
|
+
export type PrototypeDifferenceKind = "field-missing" | "field-type" | "field-required" | "field-enum" | "header-missing" | "header-required" | "error-missing" | "error-unhandled" | "scope-missing" | "auth";
|
|
83
|
+
/** One way the estate (or the vendor) serves an operation other than as the prototype needs. */
|
|
84
|
+
export interface PrototypeDifference {
|
|
85
|
+
kind: PrototypeDifferenceKind;
|
|
86
|
+
side?: "request" | "response";
|
|
87
|
+
field?: string;
|
|
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;
|
|
93
|
+
/** What the prototype says, and the line it says it on. */
|
|
94
|
+
prototype: {
|
|
95
|
+
value: string;
|
|
96
|
+
at: string;
|
|
97
|
+
};
|
|
98
|
+
/** What the estate says, when it says something. */
|
|
99
|
+
estate?: {
|
|
100
|
+
value: string;
|
|
101
|
+
at: string;
|
|
102
|
+
};
|
|
103
|
+
message: string;
|
|
104
|
+
}
|
|
105
|
+
/** One call of the prototype, placed. */
|
|
106
|
+
export interface PrototypeCall {
|
|
107
|
+
/** `<leg>.<method>-<path>`, stable. */
|
|
108
|
+
id: string;
|
|
109
|
+
leg: PrototypeLeg;
|
|
110
|
+
group: PrototypeGroup;
|
|
111
|
+
method?: string;
|
|
112
|
+
path: string;
|
|
113
|
+
/** The prototype's call. */
|
|
114
|
+
call: FactEnd;
|
|
115
|
+
/** The prototype's entry it lands on: the BFF's route, or the mock. */
|
|
116
|
+
lands: FactEnd;
|
|
117
|
+
/** The auth and scopes the prototype's sign-on gives the route (a BFF route only). */
|
|
118
|
+
auth?: string;
|
|
119
|
+
scopes?: string[];
|
|
120
|
+
/** What in the estate serves it (exists, changes). */
|
|
121
|
+
estate?: {
|
|
122
|
+
entry: FactEnd;
|
|
123
|
+
/** The Endpoint the estate's entry projects to. */
|
|
124
|
+
endpoint: string;
|
|
125
|
+
how: JoinHow;
|
|
126
|
+
/** The gateway routes the estate join went through to reach the entry, in order. */
|
|
127
|
+
gateway?: string[];
|
|
128
|
+
auth?: string;
|
|
129
|
+
scopes?: string[];
|
|
130
|
+
};
|
|
131
|
+
/** The vendor operation that alone provides it (vendor). */
|
|
132
|
+
vendor?: {
|
|
133
|
+
system: string;
|
|
134
|
+
name: string;
|
|
135
|
+
operation: string;
|
|
136
|
+
method: string;
|
|
137
|
+
path: string;
|
|
138
|
+
at?: string;
|
|
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
|
+
*/
|
|
143
|
+
through: string[];
|
|
144
|
+
/** `internal`: another team's system, which the change calls as it publishes it (O2). */
|
|
145
|
+
boundary?: "vendor" | "internal";
|
|
146
|
+
};
|
|
147
|
+
/** Two or more estate entries serve it equally well: a person says which. */
|
|
148
|
+
candidates?: FactEnd[];
|
|
149
|
+
differences: PrototypeDifference[];
|
|
150
|
+
sentence: string;
|
|
151
|
+
}
|
|
152
|
+
export interface PrototypeComparison {
|
|
153
|
+
prototype: string;
|
|
154
|
+
counts: Record<PrototypeGroup, number>;
|
|
155
|
+
calls: PrototypeCall[];
|
|
156
|
+
/** The estate repos the change modifies: those serving a call that changes, and the proxies a vendor call needs. */
|
|
157
|
+
repos: string[];
|
|
158
|
+
/** The estate repos that serve calls as they are. */
|
|
159
|
+
uses: string[];
|
|
160
|
+
/** The estate Endpoints that change. */
|
|
161
|
+
endpoints: string[];
|
|
162
|
+
/** The vendor operations the prototype needs routed. */
|
|
163
|
+
vendorOperations: string[];
|
|
164
|
+
vendors: string[];
|
|
165
|
+
/** Calls that land on nothing in the prototype (a sign-on server's keys, say): not compared. */
|
|
166
|
+
left: {
|
|
167
|
+
call: FactEnd;
|
|
168
|
+
why: string;
|
|
169
|
+
}[];
|
|
170
|
+
}
|
|
171
|
+
export interface ComparePrototypeInput {
|
|
172
|
+
/** The prototype's verified facts. */
|
|
173
|
+
prototype: JoinRepo;
|
|
174
|
+
/** The estate's repos as the join reads them; no prototype among them. */
|
|
175
|
+
estate: readonly JoinRepo[];
|
|
176
|
+
/** The vendors whose specs are in inputs/. */
|
|
177
|
+
vendors?: readonly PrototypeVendor[];
|
|
178
|
+
/** The org pack's outside systems (vendors' ids and names), as the estate join takes them. */
|
|
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[];
|
|
184
|
+
}
|
|
185
|
+
/** The words of the comparison, in one place: the CLI, the attached document and the app say these. */
|
|
186
|
+
export declare const PROTOTYPE_WORDS: {
|
|
187
|
+
leg: Record<PrototypeLeg, string>;
|
|
188
|
+
exists: (what: string, who: string, repo: string, served: string, at: string) => string;
|
|
189
|
+
changes: (what: string, who: string, repo: string, served: string, at: string, n: number) => string;
|
|
190
|
+
ambiguous: (what: string, who: string, n: number) => string;
|
|
191
|
+
new: (what: string, who: string) => string;
|
|
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;
|
|
203
|
+
fieldMissing: (side: string, name: string, at: string, repo: string) => string;
|
|
204
|
+
fieldType: (side: string, name: string, mine: string, at: string, repo: string, theirs: string, raw: string, theirAt: string) => string;
|
|
205
|
+
fieldRequired: (side: string, name: string, mine: boolean, at: string, repo: string, theirAt: string) => string;
|
|
206
|
+
scopeMissing: (scope: string, at: string, repo: string, theirs: string[]) => string;
|
|
207
|
+
auth: (mine: string, at: string, repo: string, theirs: string, theirAt: string) => string;
|
|
208
|
+
left: (what: string, who: string) => string;
|
|
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;
|
|
223
|
+
/** Compare a prototype's calls with what the estate and the vendors serve. */
|
|
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[];
|
|
239
|
+
export {};
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
import { type FactEnd, type JoinRepo } from "./facts-join.js";
|
|
2
|
+
/**
|
|
3
|
+
* A gateway's forwarding calls matched to the vendor operations they reach (ADR 0130). The facts
|
|
4
|
+
* join (ADR 0124, A-gateway) follows a call through a gateway to whatever in the estate answers;
|
|
5
|
+
* a forwarding call to a vendor's host has nothing in the estate behind it, so the join stops
|
|
6
|
+
* there. This reads the other side: the vendor's published operations (intake reads them from
|
|
7
|
+
* its spec in inputs/), and for each forwarding call of a gateway route, the one operation it
|
|
8
|
+
* reaches by method and path, path parameters normalised.
|
|
9
|
+
*
|
|
10
|
+
* Which vendor a call goes to is read, in order, from: a person's answer naming the vendor; the
|
|
11
|
+
* call's `to`; its host, or the hosts the config facts its base names give (an Apigee
|
|
12
|
+
* TargetServer per environment), matched to a host the vendor's spec lists, else to the vendor's
|
|
13
|
+
* name written in a host label (api.northwindpay.example → Northwind Pay), as the merge does.
|
|
14
|
+
* A call whose host no vendor claims is left alone: it is the join's, never guessed.
|
|
15
|
+
*
|
|
16
|
+
* 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. One is a match; none is a gap (the
|
|
18
|
+
* vendor's spec doesn't publish what the gateway forwards); two or more equally good is a
|
|
19
|
+
* question. Pure and deterministic: the same facts, answers and operations give the same result,
|
|
20
|
+
* whatever order they come in.
|
|
21
|
+
*/
|
|
22
|
+
/** One operation a vendor publishes, as intake reads it from the vendor's spec. */
|
|
23
|
+
export interface JoinVendorOperation {
|
|
24
|
+
/** The catalog Endpoint id of the operation. */
|
|
25
|
+
id: string;
|
|
26
|
+
method: string;
|
|
27
|
+
/** The path as the spec writes it (Swagger 2's basePath in front). */
|
|
28
|
+
path: string;
|
|
29
|
+
/** The path with the spec's server path in front (OpenAPI 3 `servers`), when it has one. */
|
|
30
|
+
fullPath?: string;
|
|
31
|
+
/** spec path:line of the operation. */
|
|
32
|
+
cite?: string;
|
|
33
|
+
}
|
|
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
|
+
*/
|
|
39
|
+
export interface JoinVendor {
|
|
40
|
+
/** The org pack's system id: a vendor's, or another outside system's. */
|
|
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";
|
|
49
|
+
/** Its name and aliases, as the org pack writes them. */
|
|
50
|
+
names: readonly string[];
|
|
51
|
+
/** The hosts its spec's servers name, and any host the org pack gives it (patterns allowed). */
|
|
52
|
+
hosts: readonly string[];
|
|
53
|
+
operations: readonly JoinVendorOperation[];
|
|
54
|
+
}
|
|
55
|
+
/** How the vendor was found: a person's `answer`, the call's `to` (`named`), or its `host`. */
|
|
56
|
+
export type VendorJoinHow = "answer" | "named" | "host";
|
|
57
|
+
export interface VendorCallMatch {
|
|
58
|
+
/** The gateway's forwarding call. */
|
|
59
|
+
call: FactEnd;
|
|
60
|
+
/** The route (entry) the forwarding call is under. */
|
|
61
|
+
route?: FactEnd;
|
|
62
|
+
/** The config fact (a TargetServer) that ties the call to the vendor's host. */
|
|
63
|
+
tie?: FactEnd;
|
|
64
|
+
vendor: string;
|
|
65
|
+
how: VendorJoinHow;
|
|
66
|
+
/** The vendor operation's Endpoint id. */
|
|
67
|
+
operation: string;
|
|
68
|
+
method?: string;
|
|
69
|
+
/** The path the gateway forwards to. */
|
|
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;
|
|
76
|
+
}
|
|
77
|
+
/** A forwarding call to an operation the vendor's spec doesn't publish. */
|
|
78
|
+
export interface VendorCallGap {
|
|
79
|
+
call: FactEnd;
|
|
80
|
+
route?: FactEnd;
|
|
81
|
+
tie?: FactEnd;
|
|
82
|
+
vendor: string;
|
|
83
|
+
method?: string;
|
|
84
|
+
path: string;
|
|
85
|
+
message: string;
|
|
86
|
+
}
|
|
87
|
+
/** A forwarding call two or more of the vendor's operations answer equally well. */
|
|
88
|
+
export interface VendorCallAsk {
|
|
89
|
+
call: FactEnd;
|
|
90
|
+
route?: FactEnd;
|
|
91
|
+
vendor: string;
|
|
92
|
+
question: string;
|
|
93
|
+
/** The operations' Endpoint ids, sorted. */
|
|
94
|
+
candidates: string[];
|
|
95
|
+
}
|
|
96
|
+
export interface VendorJoinResult {
|
|
97
|
+
matches: VendorCallMatch[];
|
|
98
|
+
gaps: VendorCallGap[];
|
|
99
|
+
asks: VendorCallAsk[];
|
|
100
|
+
}
|
|
101
|
+
export interface JoinVendorOperationsInput {
|
|
102
|
+
repos: readonly JoinRepo[];
|
|
103
|
+
vendors: readonly JoinVendor[];
|
|
104
|
+
/** A person's answer naming the repo or system a call goes to: repo → call fact id → name. */
|
|
105
|
+
targets?: Readonly<Record<string, Readonly<Record<string, string>>>>;
|
|
106
|
+
/** The gateway bundle folders, as given to `joinFacts` (ADR 0147). */
|
|
107
|
+
bundleFolders?: readonly string[];
|
|
108
|
+
}
|
|
109
|
+
/** Match every gateway forwarding call that goes to a vendor to the vendor operation it reaches. */
|
|
110
|
+
export declare function joinVendorOperations(input: JoinVendorOperationsInput): VendorJoinResult;
|