@maycombhq/sdk 2.0.0-beta.2 → 2.0.0-beta.22
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/npm/core/ai-decisions.d.ts +373 -0
- package/npm/core/api.d.ts +5890 -1210
- package/npm/core/audit.d.ts +165 -0
- package/npm/core/catalog.d.ts +220 -66
- package/npm/core/cite.d.ts +20 -4
- package/npm/core/contract-check.d.ts +261 -0
- package/npm/core/decision-batches.d.ts +29 -0
- package/npm/core/declared-links.d.ts +62 -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 +2 -0
- package/npm/core/facts-carry.d.ts +8 -2
- package/npm/core/facts-join-prototype.d.ts +66 -4
- package/npm/core/facts-join-vendor.d.ts +20 -2
- package/npm/core/facts-join.d.ts +325 -1
- package/npm/core/facts-terms.d.ts +108 -0
- package/npm/core/fs.d.ts +40 -4
- package/npm/core/glob.d.ts +14 -0
- package/npm/core/host-questions.d.ts +93 -1
- package/npm/core/identity.d.ts +28 -0
- package/npm/core/index.d.ts +24 -0
- package/npm/core/link-candidates.d.ts +103 -0
- package/npm/core/link-evidence.d.ts +212 -0
- package/npm/core/manifest-edit.d.ts +53 -4
- package/npm/core/merge.d.ts +28 -0
- package/npm/core/metarepo.d.ts +18 -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 +22 -6
- package/npm/core/orgpack-load.d.ts +19 -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/question-roles.d.ts +24 -0
- package/npm/core/questions.d.ts +90 -6
- package/npm/core/repo-files.d.ts +60 -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 +18 -0
- package/npm/core/schema/ai.d.ts +57 -9
- 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/fact-corrections.d.ts +105 -2
- package/npm/core/schema/facts.d.ts +410 -1
- package/npm/core/schema/kinds.d.ts +230 -66
- package/npm/core/schema/orgpack.d.ts +159 -19
- package/npm/core/schema/question.d.ts +228 -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 +7 -7
- package/npm/core/schema/scan-verify.d.ts +87 -45
- package/npm/core/schema/version.d.ts +4 -1
- package/npm/core/schema/workspace.d.ts +29 -11
- package/npm/core/shared-maps.d.ts +146 -0
- package/npm/core/stack-helpers.d.ts +32 -0
- package/npm/fs-repo.d.ts +2 -1
- package/npm/index.js +6194 -2542
- package/npm/listing.d.ts +14 -0
- package/package.json +1 -1
package/npm/core/facts-join.d.ts
CHANGED
|
@@ -37,6 +37,16 @@ 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
|
+
* 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.
|
|
40
50
|
*
|
|
41
51
|
* Pure: the same facts and answers give the same result, whatever order the repos come in.
|
|
42
52
|
*/
|
|
@@ -47,10 +57,13 @@ export interface JoinRepo {
|
|
|
47
57
|
component?: string;
|
|
48
58
|
/** Hosts the repo answers on (repos.manifest.yaml). */
|
|
49
59
|
hosts?: readonly string[];
|
|
50
|
-
/**
|
|
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). */
|
|
51
63
|
modules?: readonly {
|
|
52
64
|
component: string;
|
|
53
65
|
hosts: readonly string[];
|
|
66
|
+
basePath?: string;
|
|
54
67
|
}[];
|
|
55
68
|
/** An API gateway (the manifest's `type: gateway`): its entries are routes it forwards. */
|
|
56
69
|
gateway?: boolean;
|
|
@@ -90,6 +103,10 @@ export interface GatewayHop {
|
|
|
90
103
|
call: FactEnd;
|
|
91
104
|
/** The config fact (a TargetServer, a KVM entry) that ties the forwarding call to its host. */
|
|
92
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[];
|
|
93
110
|
/** The catalog GatewayRoute of the route. */
|
|
94
111
|
route: string;
|
|
95
112
|
/** The auth a caller meets at this hop, when the route's facts say (A-gateway2). */
|
|
@@ -107,6 +124,100 @@ export interface FactEnd {
|
|
|
107
124
|
/** path:line of the fact's citation. */
|
|
108
125
|
at: string;
|
|
109
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
|
+
/** G1 (ADR 0174): a person paired the call with this entry on the canvas. */
|
|
199
|
+
export declare const JOINED_BY_PERSON = "joined-by-person";
|
|
200
|
+
/**
|
|
201
|
+
* ADR 0181: the AI decided the link (a pairing, or a target answer), applied by Atticus from its
|
|
202
|
+
* run without a person. A how, never a person's word: the Interface is inferred, its evidence is
|
|
203
|
+
* `source: ai` with the run, and plans and checks tell it from a person's.
|
|
204
|
+
*/
|
|
205
|
+
export declare const JOINED_BY_AI = "joined-by-ai";
|
|
206
|
+
/** The guesses of J0 and J1 a join by host can carry (`FactJoin.guesses`). */
|
|
207
|
+
export type JoinHostGuess = typeof JOINED_BY_PLATFORM_SETTING | typeof JOINED_BY_FOLDER_NAME | typeof JOINED_DESPITE_CONFLICT | typeof JOINED_BY_SERVICE_NAME;
|
|
208
|
+
/**
|
|
209
|
+
* Every flag that says a link is a guess (F2, J0, J1): the only join flags that are gaps. A reader
|
|
210
|
+
* that treats a guessed link apart (the critic, a change's impact, the measure, J6) reads these.
|
|
211
|
+
*/
|
|
212
|
+
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"];
|
|
213
|
+
export type JoinGuessFlag = (typeof JOIN_GUESS_FLAGS)[number];
|
|
214
|
+
/** Flags that say how a link was made and nothing more: never a gap (C1, ADR 0135). */
|
|
215
|
+
export declare const JOIN_HOW_FLAGS: ReadonlySet<string>;
|
|
216
|
+
/**
|
|
217
|
+
* ADR 0160 (O3): a call left to another team's system that an entry of the team's shared map
|
|
218
|
+
* answers (`shared-maps.ts`). A how, never a guess.
|
|
219
|
+
*/
|
|
220
|
+
export declare const JOINED_TO_SHARED_MAP = "joined-to-shared-map";
|
|
110
221
|
/**
|
|
111
222
|
* How the callee was found: `answer` (a person named it), `named` (the call's `to` names the
|
|
112
223
|
* component), `repo` (its `to` names the repo), `host` (a host or base URL the manifest lists,
|
|
@@ -119,7 +230,22 @@ export interface FactJoin {
|
|
|
119
230
|
entry: FactEnd;
|
|
120
231
|
/** The config fact that gives the call's base URL, when one ties the call to the host. */
|
|
121
232
|
tie?: FactEnd;
|
|
233
|
+
/**
|
|
234
|
+
* J0: where the tie's value is a placeholder (`${PAYMENTS_URL}`, `${X:default}`, `env:X`), or a
|
|
235
|
+
* topic is, the config facts that set it, in the caller's repo or in a deploy or config repo of
|
|
236
|
+
* the estate, each environment's line the join used; with every other tie that gave the same
|
|
237
|
+
* callee. Left out when the value is written where the call reads it.
|
|
238
|
+
*/
|
|
239
|
+
through?: FactEnd[];
|
|
240
|
+
/** J0: the config facts that set a listener's placeholder topic (`${LEDGER_TOPIC}`). */
|
|
241
|
+
entryThrough?: FactEnd[];
|
|
122
242
|
how: JoinHow;
|
|
243
|
+
/**
|
|
244
|
+
* J1 (ADR 0143): the exposure facts (a Route's, an Ingress's, a Helm value's, a proxy's
|
|
245
|
+
* BasePath) whose host or base path the call's matched, when the manifest alone didn't give
|
|
246
|
+
* them. Left out when the manifest's hosts and base paths were all it took.
|
|
247
|
+
*/
|
|
248
|
+
exposedBy?: FactEnd[];
|
|
123
249
|
/**
|
|
124
250
|
* A join by path (the join fallback): nobody named the callee, so it is inferred. `within`
|
|
125
251
|
* says where the one entry that serves the call was found: the caller's own repo first, else
|
|
@@ -129,6 +255,17 @@ export interface FactJoin {
|
|
|
129
255
|
within: "repo" | "estate";
|
|
130
256
|
named?: string;
|
|
131
257
|
};
|
|
258
|
+
/**
|
|
259
|
+
* F2: the host named no repo; its first label happened to be a component's name. A guess, so
|
|
260
|
+
* the Interface is inferred and flagged `joined-by-label`.
|
|
261
|
+
*/
|
|
262
|
+
byLabel?: true;
|
|
263
|
+
/**
|
|
264
|
+
* J0, J1: what the join by host (or a topic) guessed on the way, though the host was cited: a
|
|
265
|
+
* platform-wide setting, a setting's folder name, or an exposure an open finding disputes. The
|
|
266
|
+
* Interface is inferred and flagged with each. Left out when nothing was guessed.
|
|
267
|
+
*/
|
|
268
|
+
guesses?: JoinHostGuess[];
|
|
132
269
|
/**
|
|
133
270
|
* The gateway hops the call went through to reach `entry`, in the order it meets them
|
|
134
271
|
* (A-gateway, many hops in A-gateway2); `path` is what the last hop's target receives. Left
|
|
@@ -146,6 +283,32 @@ export interface FactJoin {
|
|
|
146
283
|
path: string;
|
|
147
284
|
/** The catalog Interface of the join. */
|
|
148
285
|
interface: string;
|
|
286
|
+
/**
|
|
287
|
+
* G1 (ADR 0174): a person paired the call with this entry; who did. ADR 0181: `ai` when the
|
|
288
|
+
* pairing is the AI's (written by Atticus from that run), never a person's word. `call` is set
|
|
289
|
+
* when the pairing was a gateway hop's forwarding call (the line the person's evidence cites):
|
|
290
|
+
* a hop a person paired makes the whole walked link that person's pairing.
|
|
291
|
+
*/
|
|
292
|
+
paired?: {
|
|
293
|
+
by: string;
|
|
294
|
+
ai?: JoinAi;
|
|
295
|
+
call?: FactEnd;
|
|
296
|
+
};
|
|
297
|
+
/** ADR 0181: the target answer that joined it was the AI's, from that run. */
|
|
298
|
+
aiAnswer?: JoinAi;
|
|
299
|
+
/**
|
|
300
|
+
* ADR 0181 (ninth UX walk): a gateway hop on the way (`gateway`) was joined by the AI (its
|
|
301
|
+
* forwarding call's pairing or target answer), so the whole link is the AI's: `call` is that
|
|
302
|
+
* hop's forwarding call, the line the AI's evidence cites.
|
|
303
|
+
*/
|
|
304
|
+
aiHop?: JoinAi & {
|
|
305
|
+
call: FactEnd;
|
|
306
|
+
};
|
|
307
|
+
}
|
|
308
|
+
/** ADR 0181: the AI run a decision came from. */
|
|
309
|
+
export interface JoinAi {
|
|
310
|
+
runtime: string;
|
|
311
|
+
run: string;
|
|
149
312
|
}
|
|
150
313
|
export interface FactJoinAsk {
|
|
151
314
|
call: FactEnd;
|
|
@@ -160,6 +323,58 @@ export interface FactJoinAsk {
|
|
|
160
323
|
/** The entries that could answer (none for an unknown host). */
|
|
161
324
|
candidates: FactEnd[];
|
|
162
325
|
}
|
|
326
|
+
/**
|
|
327
|
+
* J1 (ADR 0143): what an exposure fact says that the estate can't take as it is. `no-component`:
|
|
328
|
+
* its `exposes` names no component or repo of the estate, so nothing is joined by it.
|
|
329
|
+
* `host-conflict`: the manifest lists hosts for the component and the fact's is none of them;
|
|
330
|
+
* `base-path-conflict`: the manifest gives a base path and the fact another. Both values are
|
|
331
|
+
* joined in a conflict; the finding asks a person to settle it, and neither silently wins.
|
|
332
|
+
*/
|
|
333
|
+
export type ExposureFinding = {
|
|
334
|
+
reason: "no-component";
|
|
335
|
+
exposure: FactEnd;
|
|
336
|
+
names: string;
|
|
337
|
+
message: string;
|
|
338
|
+
} | {
|
|
339
|
+
reason: "host-conflict" | "base-path-conflict";
|
|
340
|
+
exposure: FactEnd;
|
|
341
|
+
/** The repo the component is of, and the component. */
|
|
342
|
+
repo: string;
|
|
343
|
+
component: string;
|
|
344
|
+
/** The fact's host or base path. */
|
|
345
|
+
fact: string;
|
|
346
|
+
/** What repos.manifest.yaml says instead. */
|
|
347
|
+
manifest: string[];
|
|
348
|
+
message: string;
|
|
349
|
+
};
|
|
350
|
+
/** J2: a call left to a system outside the estate (a vendor, a cloud service), with the name it gave. */
|
|
351
|
+
export interface FactJoinOutside {
|
|
352
|
+
call: FactEnd;
|
|
353
|
+
target: string;
|
|
354
|
+
}
|
|
355
|
+
/**
|
|
356
|
+
* Why the join left a call it neither joined, asked about nor left to an outside system (with
|
|
357
|
+
* `explain`), in its own words, at the point it gave up:
|
|
358
|
+
* - `no-host`: no host, base or target in the code, and no entry of the estate serves its path;
|
|
359
|
+
* - `unresolved-placeholder`: the host or base it names (a placeholder or a config key) no
|
|
360
|
+
* setting resolves (J0), and no entry serves its path;
|
|
361
|
+
* - `host-no-route`: a host the manifest or an exposure lists, and no route there serves its path
|
|
362
|
+
* or method; `label-no-route`: the same for a host's first label naming a component;
|
|
363
|
+
* - `target-no-route`: the repo or component it names (or a person's answer names) has no entry
|
|
364
|
+
* serving it;
|
|
365
|
+
* - `generic-path`: a health, status or metrics path with no target, which every service serves;
|
|
366
|
+
* - `answered-none`: a person answered that nothing in the estate answers it;
|
|
367
|
+
* - `topic-unheard`: a publish no listener's topic matches; `topic-unresolved`: a placeholder
|
|
368
|
+
* topic no setting resolves (J0);
|
|
369
|
+
* - `type-not-joined`: a call of a type the join doesn't join (`SERVES`).
|
|
370
|
+
*/
|
|
371
|
+
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"];
|
|
372
|
+
export type JoinLeftReason = (typeof JOIN_LEFT_REASONS)[number];
|
|
373
|
+
/** A call the join left, and why (with `explain`). */
|
|
374
|
+
export interface FactJoinLeft {
|
|
375
|
+
call: FactEnd;
|
|
376
|
+
reason: JoinLeftReason;
|
|
377
|
+
}
|
|
163
378
|
/** A call whose named target (a repo or component of the estate) has no entry for it. */
|
|
164
379
|
export interface FactJoinMiss {
|
|
165
380
|
call: FactEnd;
|
|
@@ -197,11 +412,46 @@ export interface FactsJoinResult {
|
|
|
197
412
|
misses: FactJoinMiss[];
|
|
198
413
|
lineage: FieldLink[];
|
|
199
414
|
gaps: FieldGap[];
|
|
415
|
+
/** J2: the calls left to a system outside the estate, by the name each gave; left out when none. */
|
|
416
|
+
outside?: FactJoinOutside[];
|
|
417
|
+
/** J1: exposure facts that conflict with the manifest or name no component; left out when none. */
|
|
418
|
+
exposure?: ExposureFinding[];
|
|
419
|
+
/** With `explain`: every call left, with why; left out otherwise. */
|
|
420
|
+
left?: FactJoinLeft[];
|
|
421
|
+
}
|
|
422
|
+
/**
|
|
423
|
+
* G1 (ADR 0174): a person paired a call with an API of another box on the canvas: the entry of a
|
|
424
|
+
* repo it reaches (by id, else by method and path when a read gave it another id), or an outside
|
|
425
|
+
* system's operation. Written as a `link` line in the caller's corrections file.
|
|
426
|
+
*/
|
|
427
|
+
export interface PersonPair {
|
|
428
|
+
/** The repo whose entry the call reaches; or `system` for an outside system. */
|
|
429
|
+
repo?: string;
|
|
430
|
+
system?: string;
|
|
431
|
+
/** The entry's fact id when it was paired. */
|
|
432
|
+
entry?: string;
|
|
433
|
+
method?: string;
|
|
434
|
+
path: string;
|
|
435
|
+
by: string;
|
|
436
|
+
/** ADR 0181: the pairing is the AI's, with its run; joined `joined-by-ai`. */
|
|
437
|
+
ai?: JoinAi;
|
|
438
|
+
/**
|
|
439
|
+
* Review round 48: a person said the call reaches none (their `unlink` is the newest): no
|
|
440
|
+
* pairing, and an AI answer naming a target doesn't join it (a person's answer still does).
|
|
441
|
+
*/
|
|
442
|
+
none?: boolean;
|
|
200
443
|
}
|
|
201
444
|
export interface JoinFactsInput {
|
|
202
445
|
repos: readonly JoinRepo[];
|
|
203
446
|
/** A person's answer naming the repo or component a call goes to: repo → call fact id → name. */
|
|
204
447
|
targets?: Readonly<Record<string, Readonly<Record<string, string>>>>;
|
|
448
|
+
/**
|
|
449
|
+
* ADR 0181: of `targets`, those the AI answered (repo → call fact id → its run): joined
|
|
450
|
+
* `joined-by-ai`, never `joined-by-answer`, so no reader takes them as a person's word.
|
|
451
|
+
*/
|
|
452
|
+
aiTargets?: Readonly<Record<string, Readonly<Record<string, JoinAi>>>>;
|
|
453
|
+
/** G1: a person's pairings, caller repo → call fact id → what it reaches. They outrank answers. */
|
|
454
|
+
pairs?: Readonly<Record<string, Readonly<Record<string, PersonPair>>>>;
|
|
205
455
|
/**
|
|
206
456
|
* Outside systems (the org pack's vendors), by id: a call whose `to` names one keeps it and
|
|
207
457
|
* is never joined by path to an entry of the estate.
|
|
@@ -213,6 +463,19 @@ export interface JoinFactsInput {
|
|
|
213
463
|
* leaves the hop a plain gateway.
|
|
214
464
|
*/
|
|
215
465
|
facing?: FacingWords;
|
|
466
|
+
/**
|
|
467
|
+
* The folders of a gateway's proxy bundles (ADR 0147, the org pack's conventions.yaml): an
|
|
468
|
+
* entry cited under one is a gateway route whatever its repo. Default `APIGEE_BUNDLE`'s.
|
|
469
|
+
*/
|
|
470
|
+
bundleFolders?: readonly string[];
|
|
471
|
+
/**
|
|
472
|
+
* G4: follow a call through the gateway routes it lands on to the service behind them (the
|
|
473
|
+
* stack helper `gateway-walk`). False: a call is joined to the route it lands on, in the
|
|
474
|
+
* gateway's repo, and the route's forwarding call is joined on its own. Default true.
|
|
475
|
+
*/
|
|
476
|
+
walkGateways?: boolean;
|
|
477
|
+
/** Say why each call left unjoined, unasked and not outside was left (`left`). Default false. */
|
|
478
|
+
explain?: boolean;
|
|
216
479
|
}
|
|
217
480
|
type Entry = FactOf<"entry">;
|
|
218
481
|
type Call = FactOf<"call">;
|
|
@@ -231,6 +494,39 @@ export declare function nameScore(called: string, served: string): number;
|
|
|
231
494
|
export declare function callTargetQuestion(f: Call, component: string): string;
|
|
232
495
|
/** The question for a call whose gateway routes lead back where they came from (A-gateway2). */
|
|
233
496
|
export declare function gatewayCycleQuestion(f: Call, component: string, gateway: string): string;
|
|
497
|
+
/**
|
|
498
|
+
* The host a call goes to as the join reads it (P1): the call's own host, else the host of the
|
|
499
|
+
* config fact its `base` names (the first by id), else the base itself; `host:port` when the text
|
|
500
|
+
* writes a port. Undefined when nothing names one (a relative call, a `${PLACEHOLDER}` base with
|
|
501
|
+
* no key that reads as a host). The measure uses it to tell which outside system took a call.
|
|
502
|
+
*/
|
|
503
|
+
export declare function callHostOf(f: Call, repoFacts: readonly Fact[]): string | undefined;
|
|
504
|
+
/**
|
|
505
|
+
* J0: a config placeholder: `${X}` or Spring's `${X:default}` anywhere in a value (a URL may be
|
|
506
|
+
* written around it, `https://${HOST}/v2`), `env:X` as the whole value, or a build or deploy
|
|
507
|
+
* token `@X@` (Maven filtering, a gateway bundle's token replace from CI properties). With two in one value
|
|
508
|
+
* (`${SCHEME}://${HOST}/v1`) this is the first, the rest left in `after`.
|
|
509
|
+
*/
|
|
510
|
+
export declare function placeholderIn(s: string | undefined): {
|
|
511
|
+
name: string;
|
|
512
|
+
fallback?: string;
|
|
513
|
+
before: string;
|
|
514
|
+
after: string;
|
|
515
|
+
} | undefined;
|
|
516
|
+
/**
|
|
517
|
+
* A setting's name as a placeholder finds it: letter case, `.`, `-`, `_` and list brackets aside,
|
|
518
|
+
* as Spring's relaxed binding reads `PAYMENTS_URL` for `${payments.url}`.
|
|
519
|
+
*/
|
|
520
|
+
export declare const settingNameKey: (name: string) => string;
|
|
521
|
+
/**
|
|
522
|
+
* J0: an environment variable a Deployment sets `valueFrom` a ConfigMap's or a Secret's key, as
|
|
523
|
+
* the reader writes it: `configMapKeyRef:<name>/<key>` or `secretKeyRef:<name>/<key>`.
|
|
524
|
+
*/
|
|
525
|
+
export declare function keyRefIn(s: string | undefined): {
|
|
526
|
+
secret: boolean;
|
|
527
|
+
name: string;
|
|
528
|
+
key: string;
|
|
529
|
+
} | undefined;
|
|
234
530
|
/** Join every call of the estate's facts to the entry that serves it, or say why not. */
|
|
235
531
|
export declare function joinFacts(input: JoinFactsInput): FactsJoinResult;
|
|
236
532
|
/** The path a joined Interface records: the entry's, normalised (a gRPC or SOAP name as written). */
|
|
@@ -245,6 +541,34 @@ export declare function gatewayRouteId(n: {
|
|
|
245
541
|
* `<BasePath>`), else its whole path.
|
|
246
542
|
*/
|
|
247
543
|
export declare function basePathOf(e: Entry): string;
|
|
544
|
+
/**
|
|
545
|
+
* What a join guessed, as flags in `JOIN_GUESS_FLAGS`' order: by path, by a host's first label
|
|
546
|
+
* (F2), by a platform-wide setting or a setting's folder name (J0), despite an open finding or
|
|
547
|
+
* by a Service's short name (J1). Empty for a join nobody had to guess.
|
|
548
|
+
*/
|
|
549
|
+
export declare function joinGuessesOf(j: Pick<FactJoin, "inferred" | "byLabel" | "guesses">): JoinGuessFlag[];
|
|
550
|
+
/** Whether a join guessed its callee anywhere on the way (`joinGuessesOf` gives how). */
|
|
551
|
+
export declare const isGuessedJoin: (j: Pick<FactJoin, "inferred" | "byLabel" | "guesses">) => boolean;
|
|
552
|
+
/**
|
|
553
|
+
* How a join found its callee, as its Interface's flags (C1, ADR 0135): a guess by its own F2
|
|
554
|
+
* flags alone (`JOIN_GUESS_FLAGS`: by path or label, F2; by a platform setting or a folder name,
|
|
555
|
+
* J0; despite a conflict or by a Service's short name, J1), any other by how it was made
|
|
556
|
+
* (`joined-by-answer`, `-name`, `-repo`, `-host`); a publish joined to its listener has none.
|
|
557
|
+
*/
|
|
558
|
+
/** ADR 0181: the AI run behind a join's own pairing or target answer, if the AI made it. */
|
|
559
|
+
export declare const aiOfJoin: (j: Pick<FactJoin, "how" | "paired"> & {
|
|
560
|
+
aiAnswer?: JoinAi | undefined;
|
|
561
|
+
}) => JoinAi | undefined;
|
|
562
|
+
export declare function joinFlagsOf(j: Pick<FactJoin, "how" | "inferred" | "byLabel" | "guesses" | "paired"> & {
|
|
563
|
+
aiAnswer?: JoinAi | undefined;
|
|
564
|
+
aiHop?: JoinAi | undefined;
|
|
565
|
+
}): string[];
|
|
566
|
+
/**
|
|
567
|
+
* A shared link's flags (ADR 0135, section 5): each once, the union of its joins'. A verified link
|
|
568
|
+
* lists how its cited joins were made first, then the guesses its other calls rest on; an
|
|
569
|
+
* inferred one its guesses first, so the first flag says what the link rests on either way.
|
|
570
|
+
*/
|
|
571
|
+
export declare function sharedLinkFlags(flags: readonly string[], confidence: string): string[];
|
|
248
572
|
/**
|
|
249
573
|
* The joins as C1 records: an Interface per call joined to an entry (a publish to each
|
|
250
574
|
* listener, as the merge would pair them), citing the caller's call, the config that ties it to
|
|
@@ -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;
|
package/npm/core/fs.d.ts
CHANGED
|
@@ -6,6 +6,17 @@
|
|
|
6
6
|
* it is retried a few times before giving up.
|
|
7
7
|
*/
|
|
8
8
|
export declare function writeFileAtomic(path: string, data: string | Uint8Array): Promise<void>;
|
|
9
|
+
/** A file changed on disk between being read and being written back: nothing was written. */
|
|
10
|
+
export declare class FileChangedError extends Error {
|
|
11
|
+
readonly path: string;
|
|
12
|
+
constructor(path: string);
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Write a file back only when it still holds what the change was made from (`before`, the text
|
|
16
|
+
* as read; undefined when it wasn't there), so an edit made meanwhile (another request, the CLI,
|
|
17
|
+
* an editor) is never overwritten: that throws FileChangedError instead.
|
|
18
|
+
*/
|
|
19
|
+
export declare function writeFileIfUnchanged(path: string, before: string | undefined, data: string): Promise<void>;
|
|
9
20
|
export declare function renameRetrying(from: string, to: string, tries?: number): Promise<void>;
|
|
10
21
|
export interface LockInfo {
|
|
11
22
|
pid: number;
|
|
@@ -15,12 +26,16 @@ export interface LockInfo {
|
|
|
15
26
|
}
|
|
16
27
|
export declare class LockHeldError extends Error {
|
|
17
28
|
readonly held: LockInfo;
|
|
18
|
-
|
|
29
|
+
readonly file?: string | undefined;
|
|
30
|
+
constructor(held: LockInfo, file?: string | undefined);
|
|
19
31
|
}
|
|
20
32
|
/** Where a metarepo's locks live: .atticus/locks/, on this machine only (git-ignored). */
|
|
21
33
|
export declare const lockFileOf: (root: string, name: string) => string;
|
|
22
34
|
/** Read a lock: undefined when free; `stale` when its process is gone (it was cut short). */
|
|
23
|
-
export declare function readLock(root: string, name: string
|
|
35
|
+
export declare function readLock(root: string, name: string, o?: {
|
|
36
|
+
maxAgeMs?: number;
|
|
37
|
+
now?: () => Date;
|
|
38
|
+
}): Promise<(LockInfo & {
|
|
24
39
|
stale: boolean;
|
|
25
40
|
}) | undefined>;
|
|
26
41
|
/**
|
|
@@ -28,17 +43,38 @@ export declare function readLock(root: string, name: string): Promise<(LockInfo
|
|
|
28
43
|
* gone was cut short (a crash, a closed terminal); it is taken over and reported as
|
|
29
44
|
* `interrupted`, so the caller can say the last run didn't finish.
|
|
30
45
|
*/
|
|
31
|
-
export declare function acquireLock(root: string, name: string, what: string, now?: () => Date
|
|
46
|
+
export declare function acquireLock(root: string, name: string, what: string, now?: () => Date,
|
|
47
|
+
/** A lock older than this is taken over (Windows reuses a dead process's PID). */
|
|
48
|
+
o?: {
|
|
49
|
+
maxAgeMs?: number;
|
|
50
|
+
}): Promise<{
|
|
32
51
|
release: () => Promise<void>;
|
|
33
52
|
interrupted?: LockInfo;
|
|
34
53
|
}>;
|
|
54
|
+
/** The lock file beside a file two processes write (`<file>.lock`): no facts-folder reader takes it for a file of its own. */
|
|
55
|
+
export declare const sharedLockFileOf: (path: string) => string;
|
|
56
|
+
/**
|
|
57
|
+
* Review round 46: run `work` holding a file that another process may append to or rewrite at
|
|
58
|
+
* the same time (a repo's corrections: the app server appends, a CLI command rewrites it), so a
|
|
59
|
+
* read, change and write never loses what the other wrote meanwhile. In this process the writers
|
|
60
|
+
* of one file queue; between processes `<file>.lock` is created with `wx` (which fails when it is
|
|
61
|
+
* there), retried with a short backoff. A lock whose process is gone, or older than `staleMs`, is
|
|
62
|
+
* taken over; after `waitMs` it gives up with LockHeldError naming the holder. No `flock`, so it
|
|
63
|
+
* works the same on Windows, where a lock file being deleted can refuse for a moment (EPERM,
|
|
64
|
+
* EBUSY): those are retried.
|
|
65
|
+
*/
|
|
66
|
+
export declare function withSharedFileLock<T>(path: string, work: () => Promise<T>, o?: {
|
|
67
|
+
staleMs?: number;
|
|
68
|
+
waitMs?: number;
|
|
69
|
+
what?: string;
|
|
70
|
+
}): Promise<T>;
|
|
35
71
|
/**
|
|
36
72
|
* What stays on this machine inside .atticus/: the person's settings, the log, locks, upgrade
|
|
37
73
|
* backups, the prompt and response history (ADR 0110), what `atticus probe` measured of the
|
|
38
74
|
* person's assistant (ADR 0124 addendum A-probe) and the parses kept between runs
|
|
39
75
|
* (`cache/`, record-cache.ts).
|
|
40
76
|
*/
|
|
41
|
-
export declare const LOCAL_ONLY: readonly ["me.yaml", "logs/", "locks/", "backups/", "history/", "probe/", "cache/"];
|
|
77
|
+
export declare const LOCAL_ONLY: readonly ["me.yaml", "logs/", "locks/", "backups/", "history/", "probe/", "cache/", "map-all/"];
|
|
42
78
|
/**
|
|
43
79
|
* Make sure .atticus/.gitignore keeps this machine's files out of Git. It lives inside
|
|
44
80
|
* .atticus/, so it works the same in a metarepo and in a repo adopted in place (where Atticus
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Path globs for the code tools (grep `paths`, files, and every .gitignore line of a scanned
|
|
3
|
+
* repo), matched in linear time. A glob is compiled to a small automaton and run over the path
|
|
4
|
+
* one character at a time with a set of live states, so no glob, however its `*`s are laid out,
|
|
5
|
+
* can backtrack: these run on the main thread with no time limit (final review, 2.0.0-beta.21).
|
|
6
|
+
*/
|
|
7
|
+
export interface GlobMatcher {
|
|
8
|
+
test(path: string): boolean;
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* A glob as a matcher over a repo-relative path. A glob with no / matches a name at any depth;
|
|
12
|
+
* a leading / anchors it at the top.
|
|
13
|
+
*/
|
|
14
|
+
export declare function globMatcher(glob: string, anyDepth?: boolean): GlobMatcher;
|