@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,482 @@
|
|
|
1
|
+
import type { CatalogRecord } from "./catalog.js";
|
|
2
|
+
import type { Fact, FactOf } from "./schema/facts.js";
|
|
3
|
+
/**
|
|
4
|
+
* The estate join from facts (ADR 0124 addendum C-join): every call a repo's facts name, joined
|
|
5
|
+
* to the entry of the repo that serves it, deterministically and with a citation at both ends.
|
|
6
|
+
*
|
|
7
|
+
* Which repo a call goes to is read, in order, from: a person's answer; the call's `to` (a
|
|
8
|
+
* component, or a repo, of the estate); the host, or the base URL a config fact gives, that a
|
|
9
|
+
* repo lists in the manifest (or a host whose first label is a component). A host nobody lists
|
|
10
|
+
* is asked (`Which repo answers on <host>?`), never guessed, and a call whose `to` names an
|
|
11
|
+
* outside system (or names something outside the estate and has a host) is left to that name.
|
|
12
|
+
* A call with no host whose `to` names nothing in the estate (a relative call whose reader
|
|
13
|
+
* guessed a name), or that names nothing, joins the one entry of the caller's own repo that
|
|
14
|
+
* serves that method and path (or gRPC/SOAP name) in the same shape, else the one of the
|
|
15
|
+
* estate, marked inferred; two or more is a question. A publish joins every listener of its topic.
|
|
16
|
+
*
|
|
17
|
+
* Then the fields that cross: a caller's request fields to the callee entry's, the callee's
|
|
18
|
+
* response fields back, a message's to the listener's, by name (last dotted part, case, `_`
|
|
19
|
+
* and `-` aside), each with the column the receiving side stores it in when a store under the
|
|
20
|
+
* entry writes it (the field's `mappedTo`, else by name). A sent field nothing takes is a gap.
|
|
21
|
+
*
|
|
22
|
+
* Through a gateway (ADR 0124 addendum A-gateway): a call that lands on a gateway's route (an
|
|
23
|
+
* entry of a repo the manifest types `gateway`, or one cited in an Apigee bundle) whose
|
|
24
|
+
* forwarding calls (`from` the route) all join one entry joins that entry, with the path the
|
|
25
|
+
* service receives after the gateway's rewrite, and keeps the hop (the route, its forwarding
|
|
26
|
+
* call and the TargetServer or KVM config that ties it to a host). A route whose forwarding call
|
|
27
|
+
* is asked or missed, or that forwards to several services, is joined at the gateway, as before.
|
|
28
|
+
* A base whose config values (one per environment) are hosts different repos answer on is asked,
|
|
29
|
+
* never one of them guessed.
|
|
30
|
+
*
|
|
31
|
+
* Through several gateways (A-gateway2): where a route forwards into another gateway's route, the
|
|
32
|
+
* walk goes on, so `gateway` is the hops in order (caller → gateway A → gateway B → service) and
|
|
33
|
+
* `path` is what the last one's target receives. Each hop keeps its own auth and the `scopes` its
|
|
34
|
+
* route demands, and is marked `internal` or `external` when something says which: the repo's
|
|
35
|
+
* manifest type (`gateway-external`, `gateway-internal`), else the proxy's own `VirtualHost`
|
|
36
|
+
* config fact. Nothing says, the hop is just a gateway. The walk is bounded (`MAX_GATEWAY_HOPS`)
|
|
37
|
+
* and a route that forwards back into a gateway already in the path is a question (`cycle`), not
|
|
38
|
+
* a loop; a walk that runs past the bound is a question too. The join stops at the last gateway
|
|
39
|
+
* whose next hop is asked, missed or forwards to several services, exactly as one hop does.
|
|
40
|
+
* The walk is a stack helper, optional (G4; `walkGateways: false`, or ATTICUS_HELPERS_OFF=
|
|
41
|
+
* gateway-walk): without it a call is joined to the route it lands on, and each route's
|
|
42
|
+
* forwarding call to its service on its own, so the chain is there in two links, not one.
|
|
43
|
+
*
|
|
44
|
+
* Placeholders (J0): a base URL, host or topic written as `${X}`, `${X:default}` or `env:X` is
|
|
45
|
+
* each value the config facts setting `X` give it, read in the caller's repo and in any repo of
|
|
46
|
+
* the estate whose setting is for the caller's component (its folder, its deployment, its
|
|
47
|
+
* `component` or `target`); a placeholder nothing sets takes its default. Every value a manifest
|
|
48
|
+
* host or base path claims is accepted, values claimed by different repos are asked, and the join
|
|
49
|
+
* cites the lines used (`through`). No model.
|
|
50
|
+
*
|
|
51
|
+
* Pure: the same facts and answers give the same result, whatever order the repos come in.
|
|
52
|
+
*/
|
|
53
|
+
export interface JoinRepo {
|
|
54
|
+
repo: string;
|
|
55
|
+
facts: readonly Fact[];
|
|
56
|
+
/** The component a fact with none belongs to (the manifest's); the repo when left out. */
|
|
57
|
+
component?: string;
|
|
58
|
+
/** Hosts the repo answers on (repos.manifest.yaml). */
|
|
59
|
+
hosts?: readonly string[];
|
|
60
|
+
/** The path its routes sit under on its hosts, when they are shared (ADR 0134). */
|
|
61
|
+
basePath?: string;
|
|
62
|
+
/** Modules with hosts of their own (ADR 0057), and their base paths (ADR 0134). */
|
|
63
|
+
modules?: readonly {
|
|
64
|
+
component: string;
|
|
65
|
+
hosts: readonly string[];
|
|
66
|
+
basePath?: string;
|
|
67
|
+
}[];
|
|
68
|
+
/** An API gateway (the manifest's `type: gateway`): its entries are routes it forwards. */
|
|
69
|
+
gateway?: boolean;
|
|
70
|
+
/**
|
|
71
|
+
* Which side of the organisation this gateway faces, when the manifest's repo type says
|
|
72
|
+
* (`gateway-external`, `gateway-internal`): a hop through it is marked so (A-gateway2). Left
|
|
73
|
+
* out, the proxy's own `VirtualHost` config fact is read instead, and failing that the hop is
|
|
74
|
+
* just a gateway.
|
|
75
|
+
*/
|
|
76
|
+
facing?: GatewayFacing;
|
|
77
|
+
}
|
|
78
|
+
/** An Apigee proxy or shared flow bundle's file: its entries are gateway routes whatever the repo. */
|
|
79
|
+
export declare const APIGEE_BUNDLE: RegExp;
|
|
80
|
+
/** Whether a gateway hop stays inside the organisation or faces a partner or the internet. */
|
|
81
|
+
export type GatewayFacing = "internal" | "external";
|
|
82
|
+
/**
|
|
83
|
+
* How far the walk through gateways goes before it gives up and asks (A-gateway2). Four is a
|
|
84
|
+
* gateway at each of three boundaries and one more: past that, nobody means it.
|
|
85
|
+
*/
|
|
86
|
+
export declare const MAX_GATEWAY_HOPS = 4;
|
|
87
|
+
/** The words a `VirtualHost` (or a manifest repo type) uses for each side (A-gateway2). */
|
|
88
|
+
export interface FacingWords {
|
|
89
|
+
internal: readonly string[];
|
|
90
|
+
external: readonly string[];
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* The default words, overridable per estate (`joinFacts`'s `facing`), because which virtual host
|
|
94
|
+
* means which side is each estate's own convention. A value that says neither leaves the hop a
|
|
95
|
+
* plain gateway: the join never guesses from a basepath or a host's shape.
|
|
96
|
+
*/
|
|
97
|
+
export declare const FACING_WORDS: FacingWords;
|
|
98
|
+
/** The hop a call takes through a gateway: the route it lands on and the call that forwards it. */
|
|
99
|
+
export interface GatewayHop {
|
|
100
|
+
/** The gateway's route (its entry fact). */
|
|
101
|
+
entry: FactEnd;
|
|
102
|
+
/** The gateway's forwarding call, whose path is the one the next hop or the service receives. */
|
|
103
|
+
call: FactEnd;
|
|
104
|
+
/** The config fact (a TargetServer, a KVM entry) that ties the forwarding call to its host. */
|
|
105
|
+
tie?: FactEnd;
|
|
106
|
+
/** J0: the config facts that set the tie's placeholder, as `FactJoin.through`. */
|
|
107
|
+
through?: FactEnd[];
|
|
108
|
+
/** J1: the exposure facts the forwarding call's host or base path came from, as `FactJoin.exposedBy`. */
|
|
109
|
+
exposedBy?: FactEnd[];
|
|
110
|
+
/** The catalog GatewayRoute of the route. */
|
|
111
|
+
route: string;
|
|
112
|
+
/** The auth a caller meets at this hop, when the route's facts say (A-gateway2). */
|
|
113
|
+
auth?: string;
|
|
114
|
+
/** The scopes this hop's route demands of the caller's token, in the facts' order (A-gateway2). */
|
|
115
|
+
scopes?: string[];
|
|
116
|
+
/** Which side this gateway faces, when the manifest or the proxy's virtual host says. */
|
|
117
|
+
facing?: GatewayFacing;
|
|
118
|
+
}
|
|
119
|
+
/** One end of a join: a fact, its repo and component, and the line it cites. */
|
|
120
|
+
export interface FactEnd {
|
|
121
|
+
repo: string;
|
|
122
|
+
fact: string;
|
|
123
|
+
component: string;
|
|
124
|
+
/** path:line of the fact's citation. */
|
|
125
|
+
at: string;
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* F3: the target a person gave a call by answering "None of these": nothing in the estate
|
|
129
|
+
* answers it. Not a name (no fact id has brackets), so it never names a component, and the call
|
|
130
|
+
* is neither joined by path nor asked again.
|
|
131
|
+
*/
|
|
132
|
+
export declare const NO_TARGET = "(none)";
|
|
133
|
+
/**
|
|
134
|
+
* J1 (ADR 0143, beta.10): a Kubernetes Service's in-cluster address as an exposure's `host` is
|
|
135
|
+
* written, `<name>.<namespace>.svc.cluster.local`, with `:<port>` when the Service's port is
|
|
136
|
+
* cited: its name, namespace and port, or undefined for any other host.
|
|
137
|
+
*/
|
|
138
|
+
export declare function clusterServiceAddress(host: string): {
|
|
139
|
+
name: string;
|
|
140
|
+
namespace: string;
|
|
141
|
+
port?: number;
|
|
142
|
+
} | undefined;
|
|
143
|
+
/**
|
|
144
|
+
* Every name a call reaches a Service by inside the cluster (J1): the whole address, `.svc`,
|
|
145
|
+
* `<name>.<namespace>` and the bare `<name>` (from its own namespace), each with the port when
|
|
146
|
+
* one is cited. The bare name is the short one: a join by it is a guess (`joined-by-service-name`)
|
|
147
|
+
* unless the caller's own namespace is cited and is the Service's (`isShortServiceHost`).
|
|
148
|
+
*/
|
|
149
|
+
export declare function clusterServiceHosts(a: {
|
|
150
|
+
name: string;
|
|
151
|
+
namespace: string;
|
|
152
|
+
port?: number;
|
|
153
|
+
}): string[];
|
|
154
|
+
/**
|
|
155
|
+
* Whether a name `clusterServiceHosts` gives is the short one: the bare `<name>`, which the
|
|
156
|
+
* cluster's DNS resolves only from the caller's own namespace. `<name>.<namespace>` resolves from
|
|
157
|
+
* any namespace through the search path, so it names the Service as surely as `.svc` does.
|
|
158
|
+
*/
|
|
159
|
+
export declare const isShortServiceHost: (host: string) => boolean;
|
|
160
|
+
/** Whether a base path is written as a regular expression (J1): `/forge/limits(/|$)(.*)`. */
|
|
161
|
+
export declare const isPatternPath: (path: string) => boolean;
|
|
162
|
+
/**
|
|
163
|
+
* A base path's plain prefix (J1): the segments before the first one a regular expression's
|
|
164
|
+
* pattern is in, `/forge/limits(/|$)(.*)` giving `/forge/limits`. A plain path is itself.
|
|
165
|
+
*/
|
|
166
|
+
export declare function plainPathPrefix(path: string): string;
|
|
167
|
+
/** F2: an Interface's flags when nobody named its callee: found by path, or by a host's first label. */
|
|
168
|
+
export declare const JOINED_BY_PATH = "joined-by-path";
|
|
169
|
+
export declare const JOINED_BY_LABEL = "joined-by-label";
|
|
170
|
+
/**
|
|
171
|
+
* C1 (ADR 0135): how a join nobody had to guess found its callee, as the Interface's flags, so
|
|
172
|
+
* the app can say why two services are linked from the record alone: a person's answer, the
|
|
173
|
+
* component or the repo the call names, or a host the manifest lists. A publish joined to its
|
|
174
|
+
* listener carries none (its `via`, the bus, says it). These say how, never that something is
|
|
175
|
+
* missing: the guesses (`joined-by-path`, `joined-by-label`) are the only join flags that are gaps.
|
|
176
|
+
*/
|
|
177
|
+
export declare const JOINED_BY_ANSWER = "joined-by-answer";
|
|
178
|
+
export declare const JOINED_BY_NAME = "joined-by-name";
|
|
179
|
+
export declare const JOINED_BY_REPO = "joined-by-repo";
|
|
180
|
+
export declare const JOINED_BY_HOST = "joined-by-host";
|
|
181
|
+
/**
|
|
182
|
+
* J0, J1: the guesses a join by host can rest on, though the host itself was cited. The setting
|
|
183
|
+
* that gave the host is a platform-wide one nobody aimed at the caller (`setsForAll`), or one that
|
|
184
|
+
* is the caller's only because a folder of its file is named like it (`apps/<component>/...`); or
|
|
185
|
+
* the host or base path is an exposure fact's that an open `host-conflict` or `base-path-conflict`
|
|
186
|
+
* finding disputes. A join with one is `inferred`, flagged with it, as a join by path is.
|
|
187
|
+
*/
|
|
188
|
+
export declare const JOINED_BY_PLATFORM_SETTING = "joined-by-platform-setting";
|
|
189
|
+
export declare const JOINED_BY_FOLDER_NAME = "joined-by-folder-name";
|
|
190
|
+
export declare const JOINED_DESPITE_CONFLICT = "joined-despite-conflict";
|
|
191
|
+
/**
|
|
192
|
+
* J1 (beta.10): a call that reached a Kubernetes Service by its bare name,
|
|
193
|
+
* which resolves to that Service only from a pod of its own namespace, with no cited namespace
|
|
194
|
+
* of the caller's own (its own Service's in-cluster address) the same as the Service's. The
|
|
195
|
+
* `<name>.<namespace>` and the whole `<name>.<namespace>.svc[.cluster.local]` address are no guess.
|
|
196
|
+
*/
|
|
197
|
+
export declare const JOINED_BY_SERVICE_NAME = "joined-by-service-name";
|
|
198
|
+
/** The guesses of J0 and J1 a join by host can carry (`FactJoin.guesses`). */
|
|
199
|
+
export type JoinHostGuess = typeof JOINED_BY_PLATFORM_SETTING | typeof JOINED_BY_FOLDER_NAME | typeof JOINED_DESPITE_CONFLICT | typeof JOINED_BY_SERVICE_NAME;
|
|
200
|
+
/**
|
|
201
|
+
* Every flag that says a link is a guess (F2, J0, J1): the only join flags that are gaps. A reader
|
|
202
|
+
* that treats a guessed link apart (the critic, a change's impact, the measure, J6) reads these.
|
|
203
|
+
*/
|
|
204
|
+
export declare const JOIN_GUESS_FLAGS: readonly ["joined-by-path", "joined-by-label", "joined-by-platform-setting", "joined-by-folder-name", "joined-despite-conflict", "joined-by-service-name"];
|
|
205
|
+
export type JoinGuessFlag = (typeof JOIN_GUESS_FLAGS)[number];
|
|
206
|
+
/** Flags that say how a link was made and nothing more: never a gap (C1, ADR 0135). */
|
|
207
|
+
export declare const JOIN_HOW_FLAGS: ReadonlySet<string>;
|
|
208
|
+
/**
|
|
209
|
+
* ADR 0160 (O3): a call left to another team's system that an entry of the team's shared map
|
|
210
|
+
* answers (`shared-maps.ts`). A how, never a guess.
|
|
211
|
+
*/
|
|
212
|
+
export declare const JOINED_TO_SHARED_MAP = "joined-to-shared-map";
|
|
213
|
+
/**
|
|
214
|
+
* How the callee was found: `answer` (a person named it), `named` (the call's `to` names the
|
|
215
|
+
* component), `repo` (its `to` names the repo), `host` (a host or base URL the manifest lists,
|
|
216
|
+
* or the component's own name as the host), `path` (no target named: the only entry of the
|
|
217
|
+
* estate that serves it), `topic` (a listener of the published topic).
|
|
218
|
+
*/
|
|
219
|
+
export type JoinHow = "answer" | "named" | "repo" | "host" | "path" | "topic";
|
|
220
|
+
export interface FactJoin {
|
|
221
|
+
call: FactEnd;
|
|
222
|
+
entry: FactEnd;
|
|
223
|
+
/** The config fact that gives the call's base URL, when one ties the call to the host. */
|
|
224
|
+
tie?: FactEnd;
|
|
225
|
+
/**
|
|
226
|
+
* J0: where the tie's value is a placeholder (`${PAYMENTS_URL}`, `${X:default}`, `env:X`), or a
|
|
227
|
+
* topic is, the config facts that set it, in the caller's repo or in a deploy or config repo of
|
|
228
|
+
* the estate, each environment's line the join used; with every other tie that gave the same
|
|
229
|
+
* callee. Left out when the value is written where the call reads it.
|
|
230
|
+
*/
|
|
231
|
+
through?: FactEnd[];
|
|
232
|
+
/** J0: the config facts that set a listener's placeholder topic (`${LEDGER_TOPIC}`). */
|
|
233
|
+
entryThrough?: FactEnd[];
|
|
234
|
+
how: JoinHow;
|
|
235
|
+
/**
|
|
236
|
+
* J1 (ADR 0143): the exposure facts (a Route's, an Ingress's, a Helm value's, a proxy's
|
|
237
|
+
* BasePath) whose host or base path the call's matched, when the manifest alone didn't give
|
|
238
|
+
* them. Left out when the manifest's hosts and base paths were all it took.
|
|
239
|
+
*/
|
|
240
|
+
exposedBy?: FactEnd[];
|
|
241
|
+
/**
|
|
242
|
+
* A join by path (the join fallback): nobody named the callee, so it is inferred. `within`
|
|
243
|
+
* says where the one entry that serves the call was found: the caller's own repo first, else
|
|
244
|
+
* the estate; `named` is the target the call gave, when it named one the estate doesn't have.
|
|
245
|
+
*/
|
|
246
|
+
inferred?: {
|
|
247
|
+
within: "repo" | "estate";
|
|
248
|
+
named?: string;
|
|
249
|
+
};
|
|
250
|
+
/**
|
|
251
|
+
* F2: the host named no repo; its first label happened to be a component's name. A guess, so
|
|
252
|
+
* the Interface is inferred and flagged `joined-by-label`.
|
|
253
|
+
*/
|
|
254
|
+
byLabel?: true;
|
|
255
|
+
/**
|
|
256
|
+
* J0, J1: what the join by host (or a topic) guessed on the way, though the host was cited: a
|
|
257
|
+
* platform-wide setting, a setting's folder name, or an exposure an open finding disputes. The
|
|
258
|
+
* Interface is inferred and flagged with each. Left out when nothing was guessed.
|
|
259
|
+
*/
|
|
260
|
+
guesses?: JoinHostGuess[];
|
|
261
|
+
/**
|
|
262
|
+
* The gateway hops the call went through to reach `entry`, in the order it meets them
|
|
263
|
+
* (A-gateway, many hops in A-gateway2); `path` is what the last hop's target receives. Left
|
|
264
|
+
* out when the call reaches the entry directly.
|
|
265
|
+
*/
|
|
266
|
+
gateway?: GatewayHop[];
|
|
267
|
+
/**
|
|
268
|
+
* Every scope the call's token must hold to get through, the hops' in order, each once
|
|
269
|
+
* (A-gateway2). Left out when no hop demands one.
|
|
270
|
+
*/
|
|
271
|
+
scopes?: string[];
|
|
272
|
+
callType: string;
|
|
273
|
+
method?: string;
|
|
274
|
+
/** The path, gRPC or SOAP name, or topic the entry serves, as the entry writes it. */
|
|
275
|
+
path: string;
|
|
276
|
+
/** The catalog Interface of the join. */
|
|
277
|
+
interface: string;
|
|
278
|
+
}
|
|
279
|
+
export interface FactJoinAsk {
|
|
280
|
+
call: FactEnd;
|
|
281
|
+
/**
|
|
282
|
+
* `unknown-host`: no repo lists the host; `ambiguous`: more than one entry could answer;
|
|
283
|
+
* `cycle`: the gateway routes the call passes through lead back into a gateway it has already
|
|
284
|
+
* been through, so where the call ends can't be read from the facts (A-gateway2).
|
|
285
|
+
*/
|
|
286
|
+
reason: "unknown-host" | "ambiguous" | "cycle";
|
|
287
|
+
host?: string;
|
|
288
|
+
question: string;
|
|
289
|
+
/** The entries that could answer (none for an unknown host). */
|
|
290
|
+
candidates: FactEnd[];
|
|
291
|
+
}
|
|
292
|
+
/**
|
|
293
|
+
* J1 (ADR 0143): what an exposure fact says that the estate can't take as it is. `no-component`:
|
|
294
|
+
* its `exposes` names no component or repo of the estate, so nothing is joined by it.
|
|
295
|
+
* `host-conflict`: the manifest lists hosts for the component and the fact's is none of them;
|
|
296
|
+
* `base-path-conflict`: the manifest gives a base path and the fact another. Both values are
|
|
297
|
+
* joined in a conflict; the finding asks a person to settle it, and neither silently wins.
|
|
298
|
+
*/
|
|
299
|
+
export type ExposureFinding = {
|
|
300
|
+
reason: "no-component";
|
|
301
|
+
exposure: FactEnd;
|
|
302
|
+
names: string;
|
|
303
|
+
message: string;
|
|
304
|
+
} | {
|
|
305
|
+
reason: "host-conflict" | "base-path-conflict";
|
|
306
|
+
exposure: FactEnd;
|
|
307
|
+
/** The repo the component is of, and the component. */
|
|
308
|
+
repo: string;
|
|
309
|
+
component: string;
|
|
310
|
+
/** The fact's host or base path. */
|
|
311
|
+
fact: string;
|
|
312
|
+
/** What repos.manifest.yaml says instead. */
|
|
313
|
+
manifest: string[];
|
|
314
|
+
message: string;
|
|
315
|
+
};
|
|
316
|
+
/** J2: a call left to a system outside the estate (a vendor, a cloud service), with the name it gave. */
|
|
317
|
+
export interface FactJoinOutside {
|
|
318
|
+
call: FactEnd;
|
|
319
|
+
target: string;
|
|
320
|
+
}
|
|
321
|
+
/** A call whose named target (a repo or component of the estate) has no entry for it. */
|
|
322
|
+
export interface FactJoinMiss {
|
|
323
|
+
call: FactEnd;
|
|
324
|
+
target: string;
|
|
325
|
+
message: string;
|
|
326
|
+
}
|
|
327
|
+
export interface FieldEnd {
|
|
328
|
+
repo: string;
|
|
329
|
+
fact: string;
|
|
330
|
+
name: string;
|
|
331
|
+
}
|
|
332
|
+
/** A field crossing a join: the sender's field, the receiver's, and where the receiver stores it. */
|
|
333
|
+
export interface FieldLink {
|
|
334
|
+
interface: string;
|
|
335
|
+
side: "request" | "response" | "message";
|
|
336
|
+
from: FieldEnd;
|
|
337
|
+
to: FieldEnd;
|
|
338
|
+
column?: {
|
|
339
|
+
table: string;
|
|
340
|
+
name: string;
|
|
341
|
+
fact?: string;
|
|
342
|
+
how: "mapped" | "name";
|
|
343
|
+
};
|
|
344
|
+
}
|
|
345
|
+
/** A field sent (or expected back) that the other side's facts don't have. */
|
|
346
|
+
export interface FieldGap {
|
|
347
|
+
interface: string;
|
|
348
|
+
side: "request" | "response" | "message";
|
|
349
|
+
field: FieldEnd;
|
|
350
|
+
message: string;
|
|
351
|
+
}
|
|
352
|
+
export interface FactsJoinResult {
|
|
353
|
+
joins: FactJoin[];
|
|
354
|
+
asks: FactJoinAsk[];
|
|
355
|
+
misses: FactJoinMiss[];
|
|
356
|
+
lineage: FieldLink[];
|
|
357
|
+
gaps: FieldGap[];
|
|
358
|
+
/** J2: the calls left to a system outside the estate, by the name each gave; left out when none. */
|
|
359
|
+
outside?: FactJoinOutside[];
|
|
360
|
+
/** J1: exposure facts that conflict with the manifest or name no component; left out when none. */
|
|
361
|
+
exposure?: ExposureFinding[];
|
|
362
|
+
}
|
|
363
|
+
export interface JoinFactsInput {
|
|
364
|
+
repos: readonly JoinRepo[];
|
|
365
|
+
/** A person's answer naming the repo or component a call goes to: repo → call fact id → name. */
|
|
366
|
+
targets?: Readonly<Record<string, Readonly<Record<string, string>>>>;
|
|
367
|
+
/**
|
|
368
|
+
* Outside systems (the org pack's vendors), by id: a call whose `to` names one keeps it and
|
|
369
|
+
* is never joined by path to an entry of the estate.
|
|
370
|
+
*/
|
|
371
|
+
outside?: readonly string[];
|
|
372
|
+
/**
|
|
373
|
+
* The words this estate's virtual hosts and gateway repo types use for each side of the
|
|
374
|
+
* organisation (A-gateway2). The defaults are `FACING_WORDS`; a value matching neither list
|
|
375
|
+
* leaves the hop a plain gateway.
|
|
376
|
+
*/
|
|
377
|
+
facing?: FacingWords;
|
|
378
|
+
/**
|
|
379
|
+
* The folders of a gateway's proxy bundles (ADR 0147, the org pack's conventions.yaml): an
|
|
380
|
+
* entry cited under one is a gateway route whatever its repo. Default `APIGEE_BUNDLE`'s.
|
|
381
|
+
*/
|
|
382
|
+
bundleFolders?: readonly string[];
|
|
383
|
+
/**
|
|
384
|
+
* G4: follow a call through the gateway routes it lands on to the service behind them (the
|
|
385
|
+
* stack helper `gateway-walk`). False: a call is joined to the route it lands on, in the
|
|
386
|
+
* gateway's repo, and the route's forwarding call is joined on its own. Default true.
|
|
387
|
+
*/
|
|
388
|
+
walkGateways?: boolean;
|
|
389
|
+
}
|
|
390
|
+
type Entry = FactOf<"entry">;
|
|
391
|
+
type Call = FactOf<"call">;
|
|
392
|
+
/** A field's name as compared: its last dotted part, letter case, `_` and `-` aside. */
|
|
393
|
+
export declare const fieldNameKey: (name: string) => string;
|
|
394
|
+
/**
|
|
395
|
+
* How well a called path matches a served one: 1000 the same; 500 less one for each served
|
|
396
|
+
* parameter standing for a literal of the call; 100 and up a catch-all route whose fixed part
|
|
397
|
+
* starts the call; the length of the shorter when it ends the other with a plain segment (a
|
|
398
|
+
* context path or base path in front); else 0.
|
|
399
|
+
*/
|
|
400
|
+
export declare function routeScore(called: string, served: string): number;
|
|
401
|
+
/** How well a called gRPC or SOAP name matches a served one: the same, or the same short service and method. */
|
|
402
|
+
export declare function nameScore(called: string, served: string): number;
|
|
403
|
+
/** The question for a call no single repo answers: the same words as the facts-targets question. */
|
|
404
|
+
export declare function callTargetQuestion(f: Call, component: string): string;
|
|
405
|
+
/** The question for a call whose gateway routes lead back where they came from (A-gateway2). */
|
|
406
|
+
export declare function gatewayCycleQuestion(f: Call, component: string, gateway: string): string;
|
|
407
|
+
/**
|
|
408
|
+
* The host a call goes to as the join reads it (P1): the call's own host, else the host of the
|
|
409
|
+
* config fact its `base` names (the first by id), else the base itself; `host:port` when the text
|
|
410
|
+
* writes a port. Undefined when nothing names one (a relative call, a `${PLACEHOLDER}` base with
|
|
411
|
+
* no key that reads as a host). The measure uses it to tell which outside system took a call.
|
|
412
|
+
*/
|
|
413
|
+
export declare function callHostOf(f: Call, repoFacts: readonly Fact[]): string | undefined;
|
|
414
|
+
/**
|
|
415
|
+
* J0: a config placeholder: `${X}` or Spring's `${X:default}` anywhere in a value (a URL may be
|
|
416
|
+
* written around it, `https://${HOST}/v2`), or `env:X` as the whole value. With two in one value
|
|
417
|
+
* (`${SCHEME}://${HOST}/v1`) this is the first, the rest left in `after`.
|
|
418
|
+
*/
|
|
419
|
+
export declare function placeholderIn(s: string | undefined): {
|
|
420
|
+
name: string;
|
|
421
|
+
fallback?: string;
|
|
422
|
+
before: string;
|
|
423
|
+
after: string;
|
|
424
|
+
} | undefined;
|
|
425
|
+
/**
|
|
426
|
+
* A setting's name as a placeholder finds it: letter case, `.`, `-`, `_` and list brackets aside,
|
|
427
|
+
* as Spring's relaxed binding reads `PAYMENTS_URL` for `${payments.url}`.
|
|
428
|
+
*/
|
|
429
|
+
export declare const settingNameKey: (name: string) => string;
|
|
430
|
+
/**
|
|
431
|
+
* J0: an environment variable a Deployment sets `valueFrom` a ConfigMap's or a Secret's key, as
|
|
432
|
+
* the reader writes it: `configMapKeyRef:<name>/<key>` or `secretKeyRef:<name>/<key>`.
|
|
433
|
+
*/
|
|
434
|
+
export declare function keyRefIn(s: string | undefined): {
|
|
435
|
+
secret: boolean;
|
|
436
|
+
name: string;
|
|
437
|
+
key: string;
|
|
438
|
+
} | undefined;
|
|
439
|
+
/** Join every call of the estate's facts to the entry that serves it, or say why not. */
|
|
440
|
+
export declare function joinFacts(input: JoinFactsInput): FactsJoinResult;
|
|
441
|
+
/** The path a joined Interface records: the entry's, normalised (a gRPC or SOAP name as written). */
|
|
442
|
+
export declare function servedPath(e: Entry): string;
|
|
443
|
+
/** A gateway route's GatewayRoute id: `gw-<component>-<method>-<path>`, no dots (as a hop names one). */
|
|
444
|
+
export declare function gatewayRouteId(n: {
|
|
445
|
+
component: string;
|
|
446
|
+
fact: Entry;
|
|
447
|
+
}): string;
|
|
448
|
+
/**
|
|
449
|
+
* A route's base path: the part of its citation (`cite.with`) its path starts with (an Apigee
|
|
450
|
+
* `<BasePath>`), else its whole path.
|
|
451
|
+
*/
|
|
452
|
+
export declare function basePathOf(e: Entry): string;
|
|
453
|
+
/**
|
|
454
|
+
* What a join guessed, as flags in `JOIN_GUESS_FLAGS`' order: by path, by a host's first label
|
|
455
|
+
* (F2), by a platform-wide setting or a setting's folder name (J0), despite an open finding or
|
|
456
|
+
* by a Service's short name (J1). Empty for a join nobody had to guess.
|
|
457
|
+
*/
|
|
458
|
+
export declare function joinGuessesOf(j: Pick<FactJoin, "inferred" | "byLabel" | "guesses">): JoinGuessFlag[];
|
|
459
|
+
/** Whether a join guessed its callee anywhere on the way (`joinGuessesOf` gives how). */
|
|
460
|
+
export declare const isGuessedJoin: (j: Pick<FactJoin, "inferred" | "byLabel" | "guesses">) => boolean;
|
|
461
|
+
/**
|
|
462
|
+
* How a join found its callee, as its Interface's flags (C1, ADR 0135): a guess by its own F2
|
|
463
|
+
* flags alone (`JOIN_GUESS_FLAGS`: by path or label, F2; by a platform setting or a folder name,
|
|
464
|
+
* J0; despite a conflict or by a Service's short name, J1), any other by how it was made
|
|
465
|
+
* (`joined-by-answer`, `-name`, `-repo`, `-host`); a publish joined to its listener has none.
|
|
466
|
+
*/
|
|
467
|
+
export declare function joinFlagsOf(j: Pick<FactJoin, "how" | "inferred" | "byLabel" | "guesses">): string[];
|
|
468
|
+
/**
|
|
469
|
+
* A shared link's flags (ADR 0135, section 5): each once, the union of its joins'. A verified link
|
|
470
|
+
* lists how its cited joins were made first, then the guesses its other calls rest on; an
|
|
471
|
+
* inferred one its guesses first, so the first flag says what the link rests on either way.
|
|
472
|
+
*/
|
|
473
|
+
export declare function sharedLinkFlags(flags: readonly string[], confidence: string): string[];
|
|
474
|
+
/**
|
|
475
|
+
* The joins as C1 records: an Interface per call joined to an entry (a publish to each
|
|
476
|
+
* listener, as the merge would pair them), citing the caller's call, the config that ties it to
|
|
477
|
+
* the host and the callee's entry; and a FieldMapping per field that crosses, and
|
|
478
|
+
* per column the receiving side stores a field in. Mappings by name are inferred, by `mappedTo`
|
|
479
|
+
* verified.
|
|
480
|
+
*/
|
|
481
|
+
export declare function joinRecords(result: FactsJoinResult, repos: readonly JoinRepo[]): CatalogRecord[];
|
|
482
|
+
export {};
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
import type { CatalogRecord } from "./catalog.js";
|
|
2
|
+
import { type FactEnd, type FactsJoinResult, type JoinRepo } from "./facts-join.js";
|
|
3
|
+
import type { TermRole } from "./schema/facts.js";
|
|
4
|
+
/**
|
|
5
|
+
* The organisation's terms across the estate (ADR 0163). A `term` fact records an identifier of
|
|
6
|
+
* the organisation's own (a CMDB id, an application id) as a repo writes it, with the role a note
|
|
7
|
+
* or the file's own words give it: `owner` (the value names the repo's own system), `consumer`
|
|
8
|
+
* (it names a system the repo lets in), `none` or `unknown`. Atticus knows no term; it only
|
|
9
|
+
* compares the values the facts cite, word for word:
|
|
10
|
+
*
|
|
11
|
+
* - an owner value ties its repo to its system;
|
|
12
|
+
* - a consumer value points to the repo whose owner value is the same;
|
|
13
|
+
* - the same value in two repos that no owner and consumer explain is a possible link: inferred,
|
|
14
|
+
* flagged, shown for a person to confirm;
|
|
15
|
+
* - a repo's consumers are who its routes let in: on a gateway they become AccessGrants on its
|
|
16
|
+
* routes, so the critic names them when a route changes;
|
|
17
|
+
* - and they are checked against the calls the join found: a repo calling the routes whose owner
|
|
18
|
+
* value isn't listed is a finding, a listed consumer that makes no call is a note.
|
|
19
|
+
*
|
|
20
|
+
* Pure: the same facts and join give the same result.
|
|
21
|
+
*/
|
|
22
|
+
/** A term as one repo writes it. */
|
|
23
|
+
export interface TermSeen extends FactEnd {
|
|
24
|
+
term: string;
|
|
25
|
+
value: string;
|
|
26
|
+
role: TermRole;
|
|
27
|
+
/** path:line of the line that gives it its role. */
|
|
28
|
+
meaningAt?: string;
|
|
29
|
+
/** The note's key, or its words quoted. */
|
|
30
|
+
note?: string;
|
|
31
|
+
}
|
|
32
|
+
/** A consumer a repo lists, and the repo whose own value it is, when one says so. */
|
|
33
|
+
export interface TermConsumer {
|
|
34
|
+
listedBy: TermSeen;
|
|
35
|
+
owner?: TermSeen;
|
|
36
|
+
}
|
|
37
|
+
/** The flag a possible link by a shared value carries: a guess for a person to confirm. */
|
|
38
|
+
export declare const LINKED_BY_TERM_VALUE = "linked-by-term-value";
|
|
39
|
+
/** The same value in two or more repos, which no owner and its consumers explain. */
|
|
40
|
+
export interface PossibleTermLink {
|
|
41
|
+
value: string;
|
|
42
|
+
seen: TermSeen[];
|
|
43
|
+
inferred: true;
|
|
44
|
+
flag: typeof LINKED_BY_TERM_VALUE;
|
|
45
|
+
}
|
|
46
|
+
/** A consumer let in to a route: an access grant, read from the route repo's term facts. */
|
|
47
|
+
export interface TermGrant {
|
|
48
|
+
route: FactEnd;
|
|
49
|
+
gatewayRoute: string;
|
|
50
|
+
consumer: TermSeen;
|
|
51
|
+
owner?: TermSeen;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* What the consumers a repo lists say against the calls the join found. `caller-not-listed`: a
|
|
55
|
+
* repo calls its routes and none of its own values is listed (a finding); `caller-no-id`: a repo
|
|
56
|
+
* calls them and no fact of it names its own value, so whether it is listed is unknown (a note,
|
|
57
|
+
* review 12); `listed-no-call`: a listed consumer's repo is known and makes no call into them (a
|
|
58
|
+
* note).
|
|
59
|
+
*/
|
|
60
|
+
export type TermAccessFinding = {
|
|
61
|
+
reason: "caller-not-listed" | "caller-no-id";
|
|
62
|
+
repo: string;
|
|
63
|
+
route: FactEnd;
|
|
64
|
+
call: FactEnd;
|
|
65
|
+
/** The caller's own values (owner terms), none of which is listed. */
|
|
66
|
+
callerValues: string[];
|
|
67
|
+
message: string;
|
|
68
|
+
} | {
|
|
69
|
+
reason: "listed-no-call";
|
|
70
|
+
repo: string;
|
|
71
|
+
consumer: TermSeen;
|
|
72
|
+
owner: TermSeen;
|
|
73
|
+
message: string;
|
|
74
|
+
};
|
|
75
|
+
export interface TermsResult {
|
|
76
|
+
/** Every term of the estate, by repo and fact id. */
|
|
77
|
+
terms: TermSeen[];
|
|
78
|
+
consumers: TermConsumer[];
|
|
79
|
+
possible: PossibleTermLink[];
|
|
80
|
+
grants: TermGrant[];
|
|
81
|
+
access: TermAccessFinding[];
|
|
82
|
+
}
|
|
83
|
+
export interface JoinTermsInput {
|
|
84
|
+
repos: readonly JoinRepo[];
|
|
85
|
+
/** The estate's join (`joinFacts`), whole: the calls into each repo's routes come from it. */
|
|
86
|
+
join?: FactsJoinResult;
|
|
87
|
+
/** The gateway bundle folders (ADR 0147), as given to `joinFacts`. */
|
|
88
|
+
bundleFolders?: readonly string[];
|
|
89
|
+
}
|
|
90
|
+
/** Who owns, lists and shares each value, and what the lists say against the calls. */
|
|
91
|
+
export declare function joinTerms(input: JoinTermsInput): TermsResult;
|
|
92
|
+
/** The flag a term's AccessGrant carries beside its `caller:<term>`, so it is told apart. */
|
|
93
|
+
export declare const termFlag: (term: string) => string;
|
|
94
|
+
/**
|
|
95
|
+
* The consumers a gateway repo's term facts list, as C1 AccessGrants on its routes (ADR 0163):
|
|
96
|
+
* one per consumer and route, the subject the value as written, the resource the route's
|
|
97
|
+
* GatewayRoute, cited on the value's line and the line giving it its role. `caller:<term>` lets
|
|
98
|
+
* the critic name them as a route's consumers when the route changes, as it names a route's own
|
|
99
|
+
* callers (A-callers). C1 as it is: no schema change.
|
|
100
|
+
*/
|
|
101
|
+
export declare function termGrantRecords(result: TermsResult, repos: readonly JoinRepo[], o?: {
|
|
102
|
+
only?: readonly string[];
|
|
103
|
+
}): CatalogRecord[];
|
|
104
|
+
/**
|
|
105
|
+
* The flag an owner term gives its repo's Component (ADR 0163): `term:<term>=<value>`, the
|
|
106
|
+
* identifier the organisation knows the system by. `flags` is C1's existing optional field.
|
|
107
|
+
*/
|
|
108
|
+
export declare const ownerTermFlag: (term: string, value: string) => string;
|