@maycombhq/sdk 2.0.0-beta.3 → 2.0.0-beta.30
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/npm/core/ai-decisions.d.ts +373 -0
- package/npm/core/api.d.ts +15888 -3797
- package/npm/core/app-memory.d.ts +69 -0
- package/npm/core/assistant-actor.d.ts +28 -7
- package/npm/core/audit.d.ts +174 -0
- package/npm/core/canary.d.ts +369 -0
- package/npm/core/cancel.d.ts +20 -0
- package/npm/core/catalog.d.ts +220 -66
- package/npm/core/change-types-migrate.d.ts +14 -0
- package/npm/core/cite.d.ts +88 -6
- package/npm/core/contract-check.d.ts +276 -0
- package/npm/core/curated.d.ts +10 -0
- package/npm/core/decision-batches.d.ts +29 -0
- package/npm/core/declarable-routes.d.ts +52 -0
- package/npm/core/declared-links.d.ts +210 -0
- package/npm/core/eol.d.ts +5 -0
- package/npm/core/fact-paths.d.ts +14 -0
- package/npm/core/facts-callers.d.ts +23 -1
- package/npm/core/facts-carry.d.ts +8 -2
- package/npm/core/facts-deps.d.ts +85 -0
- package/npm/core/facts-join-prototype.d.ts +66 -4
- package/npm/core/facts-join-vendor.d.ts +67 -7
- package/npm/core/facts-join.d.ts +476 -2
- package/npm/core/facts-terms.d.ts +108 -0
- package/npm/core/facts.d.ts +155 -1
- package/npm/core/field-places.d.ts +109 -0
- package/npm/core/file-pool.d.ts +84 -0
- package/npm/core/fs.d.ts +205 -7
- package/npm/core/glob-plain.d.ts +34 -0
- package/npm/core/glob.d.ts +14 -0
- package/npm/core/hash-cache.d.ts +53 -0
- package/npm/core/host-questions.d.ts +273 -1
- package/npm/core/identity.d.ts +20 -8
- package/npm/core/index.d.ts +38 -0
- package/npm/core/initialisms.d.ts +62 -0
- package/npm/core/kept-files.d.ts +17 -0
- package/npm/core/light.d.ts +5 -0
- package/npm/core/link-candidates.d.ts +224 -0
- package/npm/core/link-evidence.d.ts +212 -0
- package/npm/core/log.d.ts +2 -0
- package/npm/core/manifest-edit.d.ts +83 -6
- package/npm/core/merge.d.ts +28 -0
- package/npm/core/metarepo.d.ts +26 -1
- package/npm/core/migrate.d.ts +3 -2
- package/npm/core/org-notes.d.ts +180 -0
- package/npm/core/orgpack-defaults.d.ts +30 -6
- package/npm/core/orgpack-load.d.ts +24 -0
- package/npm/core/paths.d.ts +23 -0
- package/npm/core/printer.d.ts +18 -0
- package/npm/core/process-trees.d.ts +109 -0
- package/npm/core/profile-migrate.d.ts +13 -0
- package/npm/core/question-order.d.ts +23 -0
- package/npm/core/question-owners.d.ts +57 -0
- package/npm/core/question-proposals.d.ts +77 -0
- package/npm/core/question-roles.d.ts +84 -0
- package/npm/core/questions.d.ts +123 -6
- package/npm/core/record-cache.d.ts +122 -2
- package/npm/core/repo-files.d.ts +66 -0
- package/npm/core/repo-reads.d.ts +44 -0
- package/npm/core/roles-migrate.d.ts +10 -0
- package/npm/core/run-log.d.ts +341 -0
- package/npm/core/runtime-migrate.d.ts +18 -0
- package/npm/core/schema/ai.d.ts +61 -13
- package/npm/core/schema/common.d.ts +32 -8
- package/npm/core/schema/component-type.d.ts +193 -0
- package/npm/core/schema/conventions.d.ts +80 -0
- package/npm/core/schema/dialect.d.ts +12 -12
- package/npm/core/schema/fact-corrections.d.ts +112 -2
- package/npm/core/schema/facts.d.ts +743 -23
- package/npm/core/schema/frameworks.d.ts +12 -12
- package/npm/core/schema/kinds.d.ts +230 -66
- package/npm/core/schema/orgpack.d.ts +248 -24
- package/npm/core/schema/question.d.ts +281 -5
- package/npm/core/schema/reading-rules.d.ts +51 -0
- package/npm/core/schema/repo-type.d.ts +20 -2
- package/npm/core/schema/review.d.ts +30 -9
- package/npm/core/schema/scan-verify.d.ts +77 -0
- package/npm/core/schema/version.d.ts +4 -1
- package/npm/core/schema/workspace.d.ts +29 -11
- package/npm/core/setup-edit.d.ts +107 -0
- package/npm/core/shared-maps.d.ts +146 -0
- package/npm/core/stack-helpers.d.ts +32 -0
- package/npm/core/version-order.d.ts +14 -0
- package/npm/fs-repo.d.ts +2 -1
- package/npm/index.js +14248 -6710
- package/npm/listing.d.ts +14 -0
- package/npm/sandbox.d.ts +2 -1
- package/package.json +1 -1
package/npm/core/facts-join.d.ts
CHANGED
|
@@ -37,6 +37,24 @@ import type { Fact, FactOf } from "./schema/facts.js";
|
|
|
37
37
|
* and a route that forwards back into a gateway already in the path is a question (`cycle`), not
|
|
38
38
|
* a loop; a walk that runs past the bound is a question too. The join stops at the last gateway
|
|
39
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
|
+
* The path suffix (an Apigee proxy to its service): a forwarding call cited in a bundle whose
|
|
45
|
+
* path no entry serves in the same shape is joined per route of its proxy (the route it is from,
|
|
46
|
+
* else the proxy's flows, else its `<BasePath>/**`) at the target's path with the route's suffix
|
|
47
|
+
* after it (none when `target.copy.pathsuffix` is false; everything under it for a pass-through),
|
|
48
|
+
* matched against the service's entries with its base path taken off: the manifest's, an
|
|
49
|
+
* exposure's, its context and servlet path settings, else the longest overlap, a guess
|
|
50
|
+
* (`joined-by-path-overlap`). Each such join cites the route (`forRoute`) and the base (`base`).
|
|
51
|
+
*
|
|
52
|
+
* Placeholders (J0): a base URL, host or topic written as `${X}`, `${X:default}` or `env:X` is
|
|
53
|
+
* each value the config facts setting `X` give it, read in the caller's repo and in any repo of
|
|
54
|
+
* the estate whose setting is for the caller's component (its folder, its deployment, its
|
|
55
|
+
* `component` or `target`); a placeholder nothing sets takes its default. Every value a manifest
|
|
56
|
+
* host or base path claims is accepted, values claimed by different repos are asked, and the join
|
|
57
|
+
* cites the lines used (`through`). No model.
|
|
40
58
|
*
|
|
41
59
|
* Pure: the same facts and answers give the same result, whatever order the repos come in.
|
|
42
60
|
*/
|
|
@@ -47,10 +65,21 @@ export interface JoinRepo {
|
|
|
47
65
|
component?: string;
|
|
48
66
|
/** Hosts the repo answers on (repos.manifest.yaml). */
|
|
49
67
|
hosts?: readonly string[];
|
|
50
|
-
/**
|
|
68
|
+
/** The path its routes sit under on its hosts, when they are shared (ADR 0134). */
|
|
69
|
+
basePath?: string;
|
|
70
|
+
/** Modules with hosts of their own (ADR 0057), and their base paths (ADR 0134). */
|
|
51
71
|
modules?: readonly {
|
|
52
72
|
component: string;
|
|
53
73
|
hosts: readonly string[];
|
|
74
|
+
basePath?: string;
|
|
75
|
+
}[];
|
|
76
|
+
/**
|
|
77
|
+
* Beta.25 (ADR 0192 addendum): every module the manifest lists, by its folder, hosts or not: a
|
|
78
|
+
* build fact (`artifact`, `dependency`) that names no component is its build file's module's.
|
|
79
|
+
*/
|
|
80
|
+
moduleDirs?: readonly {
|
|
81
|
+
path: string;
|
|
82
|
+
component: string;
|
|
54
83
|
}[];
|
|
55
84
|
/** An API gateway (the manifest's `type: gateway`): its entries are routes it forwards. */
|
|
56
85
|
gateway?: boolean;
|
|
@@ -90,6 +119,10 @@ export interface GatewayHop {
|
|
|
90
119
|
call: FactEnd;
|
|
91
120
|
/** The config fact (a TargetServer, a KVM entry) that ties the forwarding call to its host. */
|
|
92
121
|
tie?: FactEnd;
|
|
122
|
+
/** J0: the config facts that set the tie's placeholder, as `FactJoin.through`. */
|
|
123
|
+
through?: FactEnd[];
|
|
124
|
+
/** J1: the exposure facts the forwarding call's host or base path came from, as `FactJoin.exposedBy`. */
|
|
125
|
+
exposedBy?: FactEnd[];
|
|
93
126
|
/** The catalog GatewayRoute of the route. */
|
|
94
127
|
route: string;
|
|
95
128
|
/** The auth a caller meets at this hop, when the route's facts say (A-gateway2). */
|
|
@@ -98,6 +131,27 @@ export interface GatewayHop {
|
|
|
98
131
|
scopes?: string[];
|
|
99
132
|
/** Which side this gateway faces, when the manifest or the proxy's virtual host says. */
|
|
100
133
|
facing?: GatewayFacing;
|
|
134
|
+
/** The base path the service behind this hop serves under, as `FactJoin.base`. */
|
|
135
|
+
base?: JoinBase;
|
|
136
|
+
}
|
|
137
|
+
/**
|
|
138
|
+
* The base path a service's entries sit under that the join took off the path an Apigee proxy
|
|
139
|
+
* forwards before matching them (the path suffix): the manifest's `basePath`, an exposure's
|
|
140
|
+
* (`deploy`: an OpenShift Route's or an Ingress's path), the service's own context path and
|
|
141
|
+
* servlet path settings (`config`), or, with none of those, the longest run of the target's path
|
|
142
|
+
* that starts the entry's (`overlap`, a guess: `joined-by-path-overlap`). `by` is the facts it
|
|
143
|
+
* came from (none for the manifest or an overlap).
|
|
144
|
+
*/
|
|
145
|
+
export interface JoinBase {
|
|
146
|
+
path: string;
|
|
147
|
+
/**
|
|
148
|
+
* `url`: nothing names the base, and one route's whole URL (the target's path and the flow's
|
|
149
|
+
* suffix) ends in exactly one entry's whole path, at least one of the target's own segments
|
|
150
|
+
* included: code at both ends, not a guess. `overlap` is that for a pass-through (every entry
|
|
151
|
+
* under a guessed base), a guess.
|
|
152
|
+
*/
|
|
153
|
+
from: "manifest" | "deploy" | "config" | "url" | "overlap";
|
|
154
|
+
by?: FactEnd[];
|
|
101
155
|
}
|
|
102
156
|
/** One end of a join: a fact, its repo and component, and the line it cites. */
|
|
103
157
|
export interface FactEnd {
|
|
@@ -107,28 +161,167 @@ export interface FactEnd {
|
|
|
107
161
|
/** path:line of the fact's citation. */
|
|
108
162
|
at: string;
|
|
109
163
|
}
|
|
164
|
+
/**
|
|
165
|
+
* F3: the target a person gave a call by answering "None of these": nothing in the estate
|
|
166
|
+
* answers it. Not a name (no fact id has brackets), so it never names a component, and the call
|
|
167
|
+
* is neither joined by path nor asked again.
|
|
168
|
+
*/
|
|
169
|
+
export declare const NO_TARGET = "(none)";
|
|
170
|
+
/**
|
|
171
|
+
* J1 (ADR 0143, beta.10): a Kubernetes Service's in-cluster address as an exposure's `host` is
|
|
172
|
+
* written, `<name>.<namespace>.svc.cluster.local`, with `:<port>` when the Service's port is
|
|
173
|
+
* cited: its name, namespace and port, or undefined for any other host.
|
|
174
|
+
*/
|
|
175
|
+
export declare function clusterServiceAddress(host: string): {
|
|
176
|
+
name: string;
|
|
177
|
+
namespace: string;
|
|
178
|
+
port?: number;
|
|
179
|
+
} | undefined;
|
|
180
|
+
/**
|
|
181
|
+
* Every name a call reaches a Service by inside the cluster (J1): the whole address, `.svc`,
|
|
182
|
+
* `<name>.<namespace>` and the bare `<name>` (from its own namespace), each with the port when
|
|
183
|
+
* one is cited. The bare name is the short one: a join by it is a guess (`joined-by-service-name`)
|
|
184
|
+
* unless the caller's own namespace is cited and is the Service's (`isShortServiceHost`).
|
|
185
|
+
*/
|
|
186
|
+
export declare function clusterServiceHosts(a: {
|
|
187
|
+
name: string;
|
|
188
|
+
namespace: string;
|
|
189
|
+
port?: number;
|
|
190
|
+
}): string[];
|
|
191
|
+
/**
|
|
192
|
+
* Whether a name `clusterServiceHosts` gives is the short one: the bare `<name>`, which the
|
|
193
|
+
* cluster's DNS resolves only from the caller's own namespace. `<name>.<namespace>` resolves from
|
|
194
|
+
* any namespace through the search path, so it names the Service as surely as `.svc` does.
|
|
195
|
+
*/
|
|
196
|
+
export declare const isShortServiceHost: (host: string) => boolean;
|
|
197
|
+
/** Whether a base path is written as a regular expression (J1): `/forge/limits(/|$)(.*)`. */
|
|
198
|
+
export declare const isPatternPath: (path: string) => boolean;
|
|
199
|
+
/**
|
|
200
|
+
* A base path's plain prefix (J1): the segments before the first one a regular expression's
|
|
201
|
+
* pattern is in, `/forge/limits(/|$)(.*)` giving `/forge/limits`. A plain path is itself.
|
|
202
|
+
*/
|
|
203
|
+
export declare function plainPathPrefix(path: string): string;
|
|
204
|
+
/** F2: an Interface's flags when nobody named its callee: found by path, or by a host's first label. */
|
|
205
|
+
export declare const JOINED_BY_PATH = "joined-by-path";
|
|
206
|
+
export declare const JOINED_BY_LABEL = "joined-by-label";
|
|
207
|
+
/**
|
|
208
|
+
* C1 (ADR 0135): how a join nobody had to guess found its callee, as the Interface's flags, so
|
|
209
|
+
* the app can say why two services are linked from the record alone: a person's answer, the
|
|
210
|
+
* component or the repo the call names, or a host the manifest lists. A publish joined to its
|
|
211
|
+
* listener carries none (its `via`, the bus, says it). These say how, never that something is
|
|
212
|
+
* missing: the guesses (`joined-by-path`, `joined-by-label`) are the only join flags that are gaps.
|
|
213
|
+
*/
|
|
214
|
+
export declare const JOINED_BY_ANSWER = "joined-by-answer";
|
|
215
|
+
export declare const JOINED_BY_NAME = "joined-by-name";
|
|
216
|
+
export declare const JOINED_BY_REPO = "joined-by-repo";
|
|
217
|
+
export declare const JOINED_BY_HOST = "joined-by-host";
|
|
218
|
+
/**
|
|
219
|
+
* A call whose host nothing resolves, joined to a gateway proxy's flow by its whole path: the one
|
|
220
|
+
* proxy whose cited `<BasePath>` starts it, the one flow of its method under it. Code at both
|
|
221
|
+
* ends: a how, never a guess. Beta.25: verified only for a gateway's forwarding call that names
|
|
222
|
+
* no host (a chained proxy); a call whose host nothing resolves is inferred, `joined-by-path` first.
|
|
223
|
+
*/
|
|
224
|
+
export declare const JOINED_BY_BASE_PATH = "joined-by-base-path";
|
|
225
|
+
/**
|
|
226
|
+
* J0, J1: the guesses a join by host can rest on, though the host itself was cited. The setting
|
|
227
|
+
* that gave the host is a platform-wide one nobody aimed at the caller (`setsForAll`), or one that
|
|
228
|
+
* is the caller's only because a folder of its file is named like it (`apps/<component>/...`); or
|
|
229
|
+
* the host or base path is an exposure fact's that an open `host-conflict` or `base-path-conflict`
|
|
230
|
+
* finding disputes. A join with one is `inferred`, flagged with it, as a join by path is.
|
|
231
|
+
*/
|
|
232
|
+
export declare const JOINED_BY_PLATFORM_SETTING = "joined-by-platform-setting";
|
|
233
|
+
export declare const JOINED_BY_FOLDER_NAME = "joined-by-folder-name";
|
|
234
|
+
export declare const JOINED_DESPITE_CONFLICT = "joined-despite-conflict";
|
|
235
|
+
/**
|
|
236
|
+
* J1 (beta.10): a call that reached a Kubernetes Service by its bare name,
|
|
237
|
+
* which resolves to that Service only from a pod of its own namespace, with no cited namespace
|
|
238
|
+
* of the caller's own (its own Service's in-cluster address) the same as the Service's. The
|
|
239
|
+
* `<name>.<namespace>` and the whole `<name>.<namespace>.svc[.cluster.local]` address are no guess.
|
|
240
|
+
*/
|
|
241
|
+
export declare const JOINED_BY_SERVICE_NAME = "joined-by-service-name";
|
|
242
|
+
/** G1 (ADR 0174): a person paired the call with this entry on the canvas. */
|
|
243
|
+
export declare const JOINED_BY_PERSON = "joined-by-person";
|
|
244
|
+
/**
|
|
245
|
+
* An Apigee proxy's forwarding call matched the service's entry only by taking off the front of
|
|
246
|
+
* the target's path that nothing names as the service's base path (no manifest `basePath`, no
|
|
247
|
+
* Route or Ingress path, no context path setting): `/forge-limits/v3/limits` and the suffix
|
|
248
|
+
* `/check` against `/limits/check`. A guess, so the link is inferred; the Interface's flag only,
|
|
249
|
+
* not one of `JOIN_GUESS_FLAGS` (the local API's guesses), and its how is the host's.
|
|
250
|
+
*/
|
|
251
|
+
export declare const JOINED_BY_PATH_OVERLAP = "joined-by-path-overlap";
|
|
252
|
+
/** How many entries a `<BasePath>/**` pass-through links to at most, in path order. */
|
|
253
|
+
export declare const MAX_PASS_THROUGH_LINKS = 50;
|
|
254
|
+
/**
|
|
255
|
+
* ADR 0181: the AI decided the link (a pairing, or a target answer), applied by Atticus from its
|
|
256
|
+
* run without a person. A how, never a person's word: the Interface is inferred, its evidence is
|
|
257
|
+
* `source: ai` with the run, and plans and checks tell it from a person's.
|
|
258
|
+
*/
|
|
259
|
+
export declare const JOINED_BY_AI = "joined-by-ai";
|
|
260
|
+
/** The guesses of J0 and J1 a join by host can carry (`FactJoin.guesses`). */
|
|
261
|
+
export type JoinHostGuess = typeof JOINED_BY_PLATFORM_SETTING | typeof JOINED_BY_FOLDER_NAME | typeof JOINED_DESPITE_CONFLICT | typeof JOINED_BY_SERVICE_NAME;
|
|
262
|
+
/**
|
|
263
|
+
* Every flag that says a link is a guess (F2, J0, J1): the only join flags that are gaps. A reader
|
|
264
|
+
* that treats a guessed link apart (the critic, a change's impact, the measure, J6) reads these.
|
|
265
|
+
*/
|
|
266
|
+
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"];
|
|
267
|
+
export type JoinGuessFlag = (typeof JOIN_GUESS_FLAGS)[number];
|
|
268
|
+
/** Flags that say how a link was made and nothing more: never a gap (C1, ADR 0135). */
|
|
269
|
+
export declare const JOIN_HOW_FLAGS: ReadonlySet<string>;
|
|
270
|
+
/**
|
|
271
|
+
* ADR 0160 (O3): a call left to another team's system that an entry of the team's shared map
|
|
272
|
+
* answers (`shared-maps.ts`). A how, never a guess.
|
|
273
|
+
*/
|
|
274
|
+
export declare const JOINED_TO_SHARED_MAP = "joined-to-shared-map";
|
|
110
275
|
/**
|
|
111
276
|
* How the callee was found: `answer` (a person named it), `named` (the call's `to` names the
|
|
112
277
|
* component), `repo` (its `to` names the repo), `host` (a host or base URL the manifest lists,
|
|
113
278
|
* or the component's own name as the host), `path` (no target named: the only entry of the
|
|
114
279
|
* estate that serves it), `topic` (a listener of the published topic).
|
|
115
280
|
*/
|
|
116
|
-
export type JoinHow = "answer" | "named" | "repo" | "host" | "path" | "topic";
|
|
281
|
+
export type JoinHow = "answer" | "named" | "repo" | "host" | "base-path" | "path" | "topic";
|
|
117
282
|
export interface FactJoin {
|
|
118
283
|
call: FactEnd;
|
|
119
284
|
entry: FactEnd;
|
|
120
285
|
/** The config fact that gives the call's base URL, when one ties the call to the host. */
|
|
121
286
|
tie?: FactEnd;
|
|
287
|
+
/**
|
|
288
|
+
* J0: where the tie's value is a placeholder (`${PAYMENTS_URL}`, `${X:default}`, `env:X`), or a
|
|
289
|
+
* topic is, the config facts that set it, in the caller's repo or in a deploy or config repo of
|
|
290
|
+
* the estate, each environment's line the join used; with every other tie that gave the same
|
|
291
|
+
* callee. Left out when the value is written where the call reads it.
|
|
292
|
+
*/
|
|
293
|
+
through?: FactEnd[];
|
|
294
|
+
/** J0: the config facts that set a listener's placeholder topic (`${LEDGER_TOPIC}`). */
|
|
295
|
+
entryThrough?: FactEnd[];
|
|
122
296
|
how: JoinHow;
|
|
297
|
+
/**
|
|
298
|
+
* J1 (ADR 0143): the exposure facts (a Route's, an Ingress's, a Helm value's, a proxy's
|
|
299
|
+
* BasePath) whose host or base path the call's matched, when the manifest alone didn't give
|
|
300
|
+
* them. Left out when the manifest's hosts and base paths were all it took.
|
|
301
|
+
*/
|
|
302
|
+
exposedBy?: FactEnd[];
|
|
123
303
|
/**
|
|
124
304
|
* A join by path (the join fallback): nobody named the callee, so it is inferred. `within`
|
|
125
305
|
* says where the one entry that serves the call was found: the caller's own repo first, else
|
|
126
306
|
* the estate; `named` is the target the call gave, when it named one the estate doesn't have.
|
|
307
|
+
* Beta.25: also a join by a proxy's BasePath (`how: "base-path"`) whose caller's host nothing
|
|
308
|
+
* resolves (`within: "estate"`): the path is code at both ends, the host a guess.
|
|
127
309
|
*/
|
|
128
310
|
inferred?: {
|
|
129
311
|
within: "repo" | "estate";
|
|
130
312
|
named?: string;
|
|
131
313
|
};
|
|
314
|
+
/**
|
|
315
|
+
* F2: the host named no repo; its first label happened to be a component's name. A guess, so
|
|
316
|
+
* the Interface is inferred and flagged `joined-by-label`.
|
|
317
|
+
*/
|
|
318
|
+
byLabel?: true;
|
|
319
|
+
/**
|
|
320
|
+
* J0, J1: what the join by host (or a topic) guessed on the way, though the host was cited: a
|
|
321
|
+
* platform-wide setting, a setting's folder name, or an exposure an open finding disputes. The
|
|
322
|
+
* Interface is inferred and flagged with each. Left out when nothing was guessed.
|
|
323
|
+
*/
|
|
324
|
+
guesses?: JoinHostGuess[];
|
|
132
325
|
/**
|
|
133
326
|
* The gateway hops the call went through to reach `entry`, in the order it meets them
|
|
134
327
|
* (A-gateway, many hops in A-gateway2); `path` is what the last hop's target receives. Left
|
|
@@ -146,6 +339,46 @@ export interface FactJoin {
|
|
|
146
339
|
path: string;
|
|
147
340
|
/** The catalog Interface of the join. */
|
|
148
341
|
interface: string;
|
|
342
|
+
/**
|
|
343
|
+
* G1 (ADR 0174): a person paired the call with this entry; who did. ADR 0181: `ai` when the
|
|
344
|
+
* pairing is the AI's (written by Atticus from that run), never a person's word. `call` is set
|
|
345
|
+
* when the pairing was a gateway hop's forwarding call (the line the person's evidence cites):
|
|
346
|
+
* a hop a person paired makes the whole walked link that person's pairing.
|
|
347
|
+
*/
|
|
348
|
+
paired?: {
|
|
349
|
+
by: string;
|
|
350
|
+
ai?: JoinAi;
|
|
351
|
+
call?: FactEnd;
|
|
352
|
+
};
|
|
353
|
+
/** ADR 0181: the target answer that joined it was the AI's, from that run. */
|
|
354
|
+
aiAnswer?: JoinAi;
|
|
355
|
+
/**
|
|
356
|
+
* ADR 0181 (ninth UX walk): a gateway hop on the way (`gateway`) was joined by the AI (its
|
|
357
|
+
* forwarding call's pairing or target answer), so the whole link is the AI's: `call` is that
|
|
358
|
+
* hop's forwarding call, the line the AI's evidence cites.
|
|
359
|
+
*/
|
|
360
|
+
aiHop?: JoinAi & {
|
|
361
|
+
call: FactEnd;
|
|
362
|
+
};
|
|
363
|
+
/**
|
|
364
|
+
* An Apigee proxy's forwarding call (the path suffix): the proxy's route whose requests it
|
|
365
|
+
* carries, when the path the target receives is the target's path and this route's suffix (or,
|
|
366
|
+
* for a `<BasePath>/**` pass-through, everything under the target's path). A call that serves
|
|
367
|
+
* several routes has a join per route.
|
|
368
|
+
*/
|
|
369
|
+
forRoute?: FactEnd;
|
|
370
|
+
/** The service's base path the join took off before matching its entry (the path suffix). */
|
|
371
|
+
base?: JoinBase;
|
|
372
|
+
/**
|
|
373
|
+
* The setting that keeps the proxy's path suffix off (`target.copy.pathsuffix` false, in a
|
|
374
|
+
* JavaScript or AssignMessage policy), so the target receives its own path as it is.
|
|
375
|
+
*/
|
|
376
|
+
suffixOff?: FactEnd;
|
|
377
|
+
}
|
|
378
|
+
/** ADR 0181: the AI run a decision came from. */
|
|
379
|
+
export interface JoinAi {
|
|
380
|
+
runtime: string;
|
|
381
|
+
run: string;
|
|
149
382
|
}
|
|
150
383
|
export interface FactJoinAsk {
|
|
151
384
|
call: FactEnd;
|
|
@@ -160,6 +393,58 @@ export interface FactJoinAsk {
|
|
|
160
393
|
/** The entries that could answer (none for an unknown host). */
|
|
161
394
|
candidates: FactEnd[];
|
|
162
395
|
}
|
|
396
|
+
/**
|
|
397
|
+
* J1 (ADR 0143): what an exposure fact says that the estate can't take as it is. `no-component`:
|
|
398
|
+
* its `exposes` names no component or repo of the estate, so nothing is joined by it.
|
|
399
|
+
* `host-conflict`: the manifest lists hosts for the component and the fact's is none of them;
|
|
400
|
+
* `base-path-conflict`: the manifest gives a base path and the fact another. Both values are
|
|
401
|
+
* joined in a conflict; the finding asks a person to settle it, and neither silently wins.
|
|
402
|
+
*/
|
|
403
|
+
export type ExposureFinding = {
|
|
404
|
+
reason: "no-component";
|
|
405
|
+
exposure: FactEnd;
|
|
406
|
+
names: string;
|
|
407
|
+
message: string;
|
|
408
|
+
} | {
|
|
409
|
+
reason: "host-conflict" | "base-path-conflict";
|
|
410
|
+
exposure: FactEnd;
|
|
411
|
+
/** The repo the component is of, and the component. */
|
|
412
|
+
repo: string;
|
|
413
|
+
component: string;
|
|
414
|
+
/** The fact's host or base path. */
|
|
415
|
+
fact: string;
|
|
416
|
+
/** What repos.manifest.yaml says instead. */
|
|
417
|
+
manifest: string[];
|
|
418
|
+
message: string;
|
|
419
|
+
};
|
|
420
|
+
/** J2: a call left to a system outside the estate (a vendor, a cloud service), with the name it gave. */
|
|
421
|
+
export interface FactJoinOutside {
|
|
422
|
+
call: FactEnd;
|
|
423
|
+
target: string;
|
|
424
|
+
}
|
|
425
|
+
/**
|
|
426
|
+
* Why the join left a call it neither joined, asked about nor left to an outside system (with
|
|
427
|
+
* `explain`), in its own words, at the point it gave up:
|
|
428
|
+
* - `no-host`: no host, base or target in the code, and no entry of the estate serves its path;
|
|
429
|
+
* - `unresolved-placeholder`: the host or base it names (a placeholder or a config key) no
|
|
430
|
+
* setting resolves (J0), and no entry serves its path;
|
|
431
|
+
* - `host-no-route`: a host the manifest or an exposure lists, and no route there serves its path
|
|
432
|
+
* or method; `label-no-route`: the same for a host's first label naming a component;
|
|
433
|
+
* - `target-no-route`: the repo or component it names (or a person's answer names) has no entry
|
|
434
|
+
* serving it;
|
|
435
|
+
* - `generic-path`: a health, status or metrics path with no target, which every service serves;
|
|
436
|
+
* - `answered-none`: a person answered that nothing in the estate answers it;
|
|
437
|
+
* - `topic-unheard`: a publish no listener's topic matches; `topic-unresolved`: a placeholder
|
|
438
|
+
* topic no setting resolves (J0);
|
|
439
|
+
* - `type-not-joined`: a call of a type the join doesn't join (`SERVES`).
|
|
440
|
+
*/
|
|
441
|
+
export declare const JOIN_LEFT_REASONS: readonly ["no-host", "unresolved-placeholder", "host-no-route", "label-no-route", "target-no-route", "generic-path", "answered-none", "topic-unheard", "topic-unresolved", "type-not-joined"];
|
|
442
|
+
export type JoinLeftReason = (typeof JOIN_LEFT_REASONS)[number];
|
|
443
|
+
/** A call the join left, and why (with `explain`). */
|
|
444
|
+
export interface FactJoinLeft {
|
|
445
|
+
call: FactEnd;
|
|
446
|
+
reason: JoinLeftReason;
|
|
447
|
+
}
|
|
163
448
|
/** A call whose named target (a repo or component of the estate) has no entry for it. */
|
|
164
449
|
export interface FactJoinMiss {
|
|
165
450
|
call: FactEnd;
|
|
@@ -197,11 +482,46 @@ export interface FactsJoinResult {
|
|
|
197
482
|
misses: FactJoinMiss[];
|
|
198
483
|
lineage: FieldLink[];
|
|
199
484
|
gaps: FieldGap[];
|
|
485
|
+
/** J2: the calls left to a system outside the estate, by the name each gave; left out when none. */
|
|
486
|
+
outside?: FactJoinOutside[];
|
|
487
|
+
/** J1: exposure facts that conflict with the manifest or name no component; left out when none. */
|
|
488
|
+
exposure?: ExposureFinding[];
|
|
489
|
+
/** With `explain`: every call left, with why; left out otherwise. */
|
|
490
|
+
left?: FactJoinLeft[];
|
|
491
|
+
}
|
|
492
|
+
/**
|
|
493
|
+
* G1 (ADR 0174): a person paired a call with an API of another box on the canvas: the entry of a
|
|
494
|
+
* repo it reaches (by id, else by method and path when a read gave it another id), or an outside
|
|
495
|
+
* system's operation. Written as a `link` line in the caller's corrections file.
|
|
496
|
+
*/
|
|
497
|
+
export interface PersonPair {
|
|
498
|
+
/** The repo whose entry the call reaches; or `system` for an outside system. */
|
|
499
|
+
repo?: string;
|
|
500
|
+
system?: string;
|
|
501
|
+
/** The entry's fact id when it was paired. */
|
|
502
|
+
entry?: string;
|
|
503
|
+
method?: string;
|
|
504
|
+
path: string;
|
|
505
|
+
by: string;
|
|
506
|
+
/** ADR 0181: the pairing is the AI's, with its run; joined `joined-by-ai`. */
|
|
507
|
+
ai?: JoinAi;
|
|
508
|
+
/**
|
|
509
|
+
* Review round 48: a person said the call reaches none (their `unlink` is the newest): no
|
|
510
|
+
* pairing, and an AI answer naming a target doesn't join it (a person's answer still does).
|
|
511
|
+
*/
|
|
512
|
+
none?: boolean;
|
|
200
513
|
}
|
|
201
514
|
export interface JoinFactsInput {
|
|
202
515
|
repos: readonly JoinRepo[];
|
|
203
516
|
/** A person's answer naming the repo or component a call goes to: repo → call fact id → name. */
|
|
204
517
|
targets?: Readonly<Record<string, Readonly<Record<string, string>>>>;
|
|
518
|
+
/**
|
|
519
|
+
* ADR 0181: of `targets`, those the AI answered (repo → call fact id → its run): joined
|
|
520
|
+
* `joined-by-ai`, never `joined-by-answer`, so no reader takes them as a person's word.
|
|
521
|
+
*/
|
|
522
|
+
aiTargets?: Readonly<Record<string, Readonly<Record<string, JoinAi>>>>;
|
|
523
|
+
/** G1: a person's pairings, caller repo → call fact id → what it reaches. They outrank answers. */
|
|
524
|
+
pairs?: Readonly<Record<string, Readonly<Record<string, PersonPair>>>>;
|
|
205
525
|
/**
|
|
206
526
|
* Outside systems (the org pack's vendors), by id: a call whose `to` names one keeps it and
|
|
207
527
|
* is never joined by path to an entry of the estate.
|
|
@@ -213,6 +533,19 @@ export interface JoinFactsInput {
|
|
|
213
533
|
* leaves the hop a plain gateway.
|
|
214
534
|
*/
|
|
215
535
|
facing?: FacingWords;
|
|
536
|
+
/**
|
|
537
|
+
* The folders of a gateway's proxy bundles (ADR 0147, the org pack's conventions.yaml): an
|
|
538
|
+
* entry cited under one is a gateway route whatever its repo. Default `APIGEE_BUNDLE`'s.
|
|
539
|
+
*/
|
|
540
|
+
bundleFolders?: readonly string[];
|
|
541
|
+
/**
|
|
542
|
+
* G4: follow a call through the gateway routes it lands on to the service behind them (the
|
|
543
|
+
* stack helper `gateway-walk`). False: a call is joined to the route it lands on, in the
|
|
544
|
+
* gateway's repo, and the route's forwarding call is joined on its own. Default true.
|
|
545
|
+
*/
|
|
546
|
+
walkGateways?: boolean;
|
|
547
|
+
/** Say why each call left unjoined, unasked and not outside was left (`left`). Default false. */
|
|
548
|
+
explain?: boolean;
|
|
216
549
|
}
|
|
217
550
|
type Entry = FactOf<"entry">;
|
|
218
551
|
type Call = FactOf<"call">;
|
|
@@ -229,10 +562,104 @@ export declare function routeScore(called: string, served: string): number;
|
|
|
229
562
|
export declare function nameScore(called: string, served: string): number;
|
|
230
563
|
/** The question for a call no single repo answers: the same words as the facts-targets question. */
|
|
231
564
|
export declare function callTargetQuestion(f: Call, component: string): string;
|
|
565
|
+
/**
|
|
566
|
+
* The question for a gateway's forwarding call whose host nothing resolves. A host still written
|
|
567
|
+
* as a token (`@targetUrl@`, `{{host}}`, `${HOST}`) is most often one a deploy tool's file sets
|
|
568
|
+
* per environment (the Apigee config plugin's `config.json`), which a read before beta.24 didn't
|
|
569
|
+
* record: the next step it says is to read the gateway repo again, never a guess at a repo.
|
|
570
|
+
*/
|
|
571
|
+
export declare function forwardHostQuestion(host: string, repo: string, prefix?: string): string;
|
|
232
572
|
/** The question for a call whose gateway routes lead back where they came from (A-gateway2). */
|
|
233
573
|
export declare function gatewayCycleQuestion(f: Call, component: string, gateway: string): string;
|
|
574
|
+
/**
|
|
575
|
+
* A host's registrable domain (`northwind.example` for `api.northwind.example`,
|
|
576
|
+
* `northwind.co.uk` for `api.northwind.co.uk`), or undefined for a name the outside rule can't
|
|
577
|
+
* place: one label, `localhost`, an address, a private or in-cluster name (`.corp`, `.svc`), a
|
|
578
|
+
* Service and its namespace (`wallets.payments`, `wallets.qa`, `forge-wallets.dev`: two labels
|
|
579
|
+
* whose last is no `PUBLIC_TLDS` name). A wildcard and a port are left off.
|
|
580
|
+
*/
|
|
581
|
+
export declare function registrableDomain(host: string): string | undefined;
|
|
582
|
+
/**
|
|
583
|
+
* The host a call goes to as the join reads it (P1): the call's own host, else the host of the
|
|
584
|
+
* config fact its `base` names (the first by id), else the base itself; `host:port` when the text
|
|
585
|
+
* writes a port. Undefined when nothing names one (a relative call, a `${PLACEHOLDER}` base with
|
|
586
|
+
* no key that reads as a host). The measure uses it to tell which outside system took a call.
|
|
587
|
+
*/
|
|
588
|
+
export declare function callHostOf(f: Call, repoFacts: readonly Fact[]): string | undefined;
|
|
589
|
+
/** How a host nothing the join reads gives a value is worded (`unsetHostOf`). */
|
|
590
|
+
export type UnsetHostForm = "token" | "variable" | "setting" | "set";
|
|
591
|
+
/**
|
|
592
|
+
* What the join knows of the settings when it words an unset host: the names its settings have
|
|
593
|
+
* (`settingNameKey` of each config fact's key, the estate's), and whether the call's repo has
|
|
594
|
+
* settings with camelCase keys (the review of 5cc4ce87: then a camelCase name is a setting's).
|
|
595
|
+
*/
|
|
596
|
+
export interface UnsetHostSettings {
|
|
597
|
+
names?: ReadonlySet<string>;
|
|
598
|
+
camel?: boolean;
|
|
599
|
+
}
|
|
600
|
+
/** A setting's key in camelCase (`ledgerUrl`, `forge.ledgerUrl`): a lower letter, then an upper. */
|
|
601
|
+
export declare const camelSettingKey: (key: string) => boolean;
|
|
602
|
+
/**
|
|
603
|
+
* The owner, 2026-11-19 (ADR 0195, the beta.28.1 addendum's sub-addendum): a host nothing the
|
|
604
|
+
* join reads gives a value, by how it is written. `token`: a build, deploy or config token
|
|
605
|
+
* (`@name@`, `${NAME}`, `${forge.ledger.url}`, `$NAME`, `%NAME%`), asked about as "a deploy token
|
|
606
|
+
* nothing sets". `variable`: a variable of the code's (`${baseUrl}`, `${this.cfg.url}`,
|
|
607
|
+
* `${process.env.X}`, Kotlin's and Groovy's `$baseUrl`, PowerShell's `$env:X`), asked about as "a
|
|
608
|
+
* variable Atticus couldn't find the value of". Only as the whole host (the scheme aside), read at
|
|
609
|
+
* the start of the value or after a scheme or a space (a loose end's raw names its method first).
|
|
610
|
+
* Camel Simple's names (`${header.x}`, `${body}`) are the route's message, and none.
|
|
611
|
+
*
|
|
612
|
+
* The review of 5cc4ce87 (I2), given what the join knows of the settings: `set`, a name a setting
|
|
613
|
+
* of the estate has (`settings.names`), whatever its form: never "a deploy token nothing sets",
|
|
614
|
+
* since a setting has that key, but one that gave no host for this call; and `setting`, a
|
|
615
|
+
* camelCase name (`${ledgerUrl}`, `$ledgerUrl`) nothing sets, where the call's repo has settings
|
|
616
|
+
* with camelCase keys (`settings.camel`): worded as a setting, else as a variable of the code's.
|
|
617
|
+
* `name` is the setting's name the host is written with (`FORGE_LEDGER_URL` of
|
|
618
|
+
* `%FORGE_LEDGER_URL%`).
|
|
619
|
+
*/
|
|
620
|
+
export declare function unsetHostOf(value: string | undefined, settings?: UnsetHostSettings): {
|
|
621
|
+
host: string;
|
|
622
|
+
form: UnsetHostForm;
|
|
623
|
+
name: string;
|
|
624
|
+
} | undefined;
|
|
625
|
+
/** The question for a call whose whole host nothing gives a value, worded by its form. */
|
|
626
|
+
export declare function unsetHostQuestion(host: string, form: UnsetHostForm, repo: string, name?: string): string;
|
|
627
|
+
export declare function placeholderIn(s: string | undefined): {
|
|
628
|
+
name: string;
|
|
629
|
+
fallback?: string;
|
|
630
|
+
before: string;
|
|
631
|
+
after: string;
|
|
632
|
+
} | undefined;
|
|
633
|
+
/**
|
|
634
|
+
* A setting's name as a placeholder finds it: letter case, `.`, `-`, `_` and list brackets aside,
|
|
635
|
+
* as Spring's relaxed binding reads `PAYMENTS_URL` for `${payments.url}`.
|
|
636
|
+
*/
|
|
637
|
+
export declare const settingNameKey: (name: string) => string;
|
|
638
|
+
/**
|
|
639
|
+
* J0: an environment variable a Deployment sets `valueFrom` a ConfigMap's or a Secret's key, as
|
|
640
|
+
* the reader writes it: `configMapKeyRef:<name>/<key>` or `secretKeyRef:<name>/<key>`.
|
|
641
|
+
*/
|
|
642
|
+
export declare function keyRefIn(s: string | undefined): {
|
|
643
|
+
secret: boolean;
|
|
644
|
+
name: string;
|
|
645
|
+
key: string;
|
|
646
|
+
} | undefined;
|
|
234
647
|
/** Join every call of the estate's facts to the entry that serves it, or say why not. */
|
|
235
648
|
export declare function joinFacts(input: JoinFactsInput): FactsJoinResult;
|
|
649
|
+
/**
|
|
650
|
+
* Beta.28.1 (the review of "nothing slow runs silently"): joinFacts, giving way every
|
|
651
|
+
* JOIN_YIELD_EVERY calls, so a caller that awaits `tick` between (joinFactsAsync) lets a
|
|
652
|
+
* heartbeat, a Console line or a Stop through during a long join. The same join either way.
|
|
653
|
+
*/
|
|
654
|
+
export declare function joinFactsAsync(input: JoinFactsInput, tick: () => Promise<void>): Promise<FactsJoinResult>;
|
|
655
|
+
/** How many calls the join reads between two points where it gives way. */
|
|
656
|
+
export declare const JOIN_YIELD_EVERY = 200;
|
|
657
|
+
/** Work written as steps (a generator that yields where it may give way), run to its end. */
|
|
658
|
+
export declare function runSteps<T>(g: Generator<void, T, void>): T;
|
|
659
|
+
/** The same, awaiting `tick` at each point it may give way. */
|
|
660
|
+
export declare function runStepsAsync<T>(g: Generator<void, T, void>, tick: () => Promise<void>): Promise<T>;
|
|
661
|
+
/** joinFacts as steps: see joinFactsAsync. */
|
|
662
|
+
export declare function joinFactsSteps(input: JoinFactsInput): Generator<void, FactsJoinResult, void>;
|
|
236
663
|
/** The path a joined Interface records: the entry's, normalised (a gRPC or SOAP name as written). */
|
|
237
664
|
export declare function servedPath(e: Entry): string;
|
|
238
665
|
/** A gateway route's GatewayRoute id: `gw-<component>-<method>-<path>`, no dots (as a hop names one). */
|
|
@@ -245,6 +672,53 @@ export declare function gatewayRouteId(n: {
|
|
|
245
672
|
* `<BasePath>`), else its whole path.
|
|
246
673
|
*/
|
|
247
674
|
export declare function basePathOf(e: Entry): string;
|
|
675
|
+
/**
|
|
676
|
+
* What a join guessed, as flags in `JOIN_GUESS_FLAGS`' order: by path, by a host's first label
|
|
677
|
+
* (F2), by a platform-wide setting or a setting's folder name (J0), despite an open finding or
|
|
678
|
+
* by a Service's short name (J1). Empty for a join nobody had to guess.
|
|
679
|
+
*/
|
|
680
|
+
export declare function joinGuessesOf(j: Pick<FactJoin, "inferred" | "byLabel" | "guesses">): JoinGuessFlag[];
|
|
681
|
+
/**
|
|
682
|
+
* Whether an Apigee forwarding call on the way matched its entry only by a guessed base path
|
|
683
|
+
* (`joined-by-path-overlap`): the join's own, or a gateway hop's.
|
|
684
|
+
*/
|
|
685
|
+
export declare const isOverlapJoin: (j: {
|
|
686
|
+
base?: JoinBase | undefined;
|
|
687
|
+
gateway?: readonly {
|
|
688
|
+
base?: JoinBase | undefined;
|
|
689
|
+
}[] | undefined;
|
|
690
|
+
}) => boolean;
|
|
691
|
+
/** Whether a join guessed its callee anywhere on the way (`joinGuessesOf` gives how). */
|
|
692
|
+
export declare const isGuessedJoin: (j: Pick<FactJoin, "inferred" | "byLabel" | "guesses"> & {
|
|
693
|
+
base?: JoinBase | undefined;
|
|
694
|
+
gateway?: readonly {
|
|
695
|
+
base?: JoinBase | undefined;
|
|
696
|
+
}[] | undefined;
|
|
697
|
+
}) => boolean;
|
|
698
|
+
/**
|
|
699
|
+
* How a join found its callee, as its Interface's flags (C1, ADR 0135): a guess by its own F2
|
|
700
|
+
* flags alone (`JOIN_GUESS_FLAGS`: by path or label, F2; by a platform setting or a folder name,
|
|
701
|
+
* J0; despite a conflict or by a Service's short name, J1), any other by how it was made
|
|
702
|
+
* (`joined-by-answer`, `-name`, `-repo`, `-host`); a publish joined to its listener has none.
|
|
703
|
+
*/
|
|
704
|
+
/** ADR 0181: the AI run behind a join's own pairing or target answer, if the AI made it. */
|
|
705
|
+
export declare const aiOfJoin: (j: Pick<FactJoin, "how" | "paired"> & {
|
|
706
|
+
aiAnswer?: JoinAi | undefined;
|
|
707
|
+
}) => JoinAi | undefined;
|
|
708
|
+
export declare function joinFlagsOf(j: Pick<FactJoin, "how" | "inferred" | "byLabel" | "guesses" | "paired"> & {
|
|
709
|
+
aiAnswer?: JoinAi | undefined;
|
|
710
|
+
aiHop?: JoinAi | undefined;
|
|
711
|
+
base?: JoinBase | undefined;
|
|
712
|
+
gateway?: readonly {
|
|
713
|
+
base?: JoinBase | undefined;
|
|
714
|
+
}[] | undefined;
|
|
715
|
+
}): string[];
|
|
716
|
+
/**
|
|
717
|
+
* A shared link's flags (ADR 0135, section 5): each once, the union of its joins'. A verified link
|
|
718
|
+
* lists how its cited joins were made first, then the guesses its other calls rest on; an
|
|
719
|
+
* inferred one its guesses first, so the first flag says what the link rests on either way.
|
|
720
|
+
*/
|
|
721
|
+
export declare function sharedLinkFlags(flags: readonly string[], confidence: string): string[];
|
|
248
722
|
/**
|
|
249
723
|
* The joins as C1 records: an Interface per call joined to an entry (a publish to each
|
|
250
724
|
* listener, as the merge would pair them), citing the caller's call, the config that ties it to
|