@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
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
import { type LineChange } from "./manifest-edit.js";
|
|
2
|
+
import { type ArrowEnd, type DeclaredLink } from "./schema/orgpack.js";
|
|
3
|
+
/**
|
|
4
|
+
* G3 (ADR 0174): what a person declares on the canvas that the code can't show, written to the
|
|
5
|
+
* profile that has the system, comments and order kept, for review. A topic the system publishes
|
|
6
|
+
* or listens on goes under its `topics` (ADR 0162: a publish or listener of the estate with no
|
|
7
|
+
* counterpart lands on it, marked declared); a call it makes to a gateway route goes under its
|
|
8
|
+
* `calls` (A-callers). Who declared it and when is the line's comment. Nothing here is a fact.
|
|
9
|
+
*/
|
|
10
|
+
export type Declared = {
|
|
11
|
+
kind: "topic";
|
|
12
|
+
system: string;
|
|
13
|
+
topic: string;
|
|
14
|
+
side: "publishes" | "listens";
|
|
15
|
+
} | {
|
|
16
|
+
kind: "call";
|
|
17
|
+
system: string;
|
|
18
|
+
route: string;
|
|
19
|
+
}
|
|
20
|
+
/** ADR 0200: several gateway routes in one write, one line each. */
|
|
21
|
+
| {
|
|
22
|
+
kind: "call";
|
|
23
|
+
system: string;
|
|
24
|
+
routes: readonly string[];
|
|
25
|
+
};
|
|
26
|
+
export interface DeclaredOnFile {
|
|
27
|
+
kind: "topic" | "call";
|
|
28
|
+
system: string;
|
|
29
|
+
/** The topic, or the route. */
|
|
30
|
+
value: string;
|
|
31
|
+
/** publishes or listens, for a topic declared from the canvas. */
|
|
32
|
+
side?: "publishes" | "listens";
|
|
33
|
+
/** Who declared it and when, from its comment; none for a line a person wrote by hand. */
|
|
34
|
+
by?: string;
|
|
35
|
+
at?: string;
|
|
36
|
+
}
|
|
37
|
+
export declare class DeclareError extends Error {
|
|
38
|
+
readonly code: "not-found" | "invalid" | "exists";
|
|
39
|
+
constructor(code: "not-found" | "invalid" | "exists", message: string);
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* The re-review of beta.28.1: a short hash of the System as the canvas added it, in its comment,
|
|
43
|
+
* so Undo takes it away only while it is still exactly that (no field a person changed since).
|
|
44
|
+
*/
|
|
45
|
+
export declare const addedHash: (s: Record<string, unknown>) => string;
|
|
46
|
+
export declare const addedComment: (by: string, at: string, hash: string) => string;
|
|
47
|
+
/** The comment a declaration carries: which side, who and when. */
|
|
48
|
+
export declare const declaredComment: (by: string, at: string, side?: "publishes" | "listens") => string;
|
|
49
|
+
/**
|
|
50
|
+
* Write a declaration (or, with `preview`, say the lines it changes). The profile moves to
|
|
51
|
+
* version 2 when a topic needs it; the whole profile is checked before it is written.
|
|
52
|
+
*/
|
|
53
|
+
export declare function declareLink(root: string, d: Declared, o: {
|
|
54
|
+
by: string;
|
|
55
|
+
at: string;
|
|
56
|
+
preview?: boolean;
|
|
57
|
+
/**
|
|
58
|
+
* Beta.28.1 (field report 4): a system no profile has yet, which the canvas draws for a repo
|
|
59
|
+
* the manifest lists with no System of the profiles (the box takes the repo's id, or the
|
|
60
|
+
* manifest's `system`): added to its platform's profile in the same write, so a person
|
|
61
|
+
* declaring a link from that box never has to make the System first.
|
|
62
|
+
*/
|
|
63
|
+
create?: {
|
|
64
|
+
platform: string;
|
|
65
|
+
name?: string;
|
|
66
|
+
owner?: string;
|
|
67
|
+
};
|
|
68
|
+
}): Promise<{
|
|
69
|
+
rel: string;
|
|
70
|
+
changes: LineChange[];
|
|
71
|
+
written: boolean;
|
|
72
|
+
/** Beta.28: the file's bytes this write started from (what a take-back puts back). */
|
|
73
|
+
before: string;
|
|
74
|
+
/** The bytes it wrote (what a take-back expects to find). */
|
|
75
|
+
wrote?: string;
|
|
76
|
+
/** Beta.28.1: the system added to the profile first (`create`), when it had none. */
|
|
77
|
+
created?: string;
|
|
78
|
+
}>;
|
|
79
|
+
/**
|
|
80
|
+
* Beta.28.1 (field hunt G5): `after`, a whole document as the yaml library writes it, with every
|
|
81
|
+
* line it has unchanged from `before` (the file as written, LF) given back as `before` wrote it:
|
|
82
|
+
* a flow list's padding (`[dv, qa, prod]`), its quotes, its spacing. `before` as the library
|
|
83
|
+
* writes it is lined up with `before` line for line (the library keeps the lines and comments of
|
|
84
|
+
* a document it only reads); a line of `after` that is one of those, in order, is that line of
|
|
85
|
+
* `before`. Where the two don't line up (the library joined or split a line), `after` as it is.
|
|
86
|
+
*/
|
|
87
|
+
export declare function keepUntouchedLines(written: string, after: string): string;
|
|
88
|
+
/**
|
|
89
|
+
* Undo: remove a declared topic or call from the system's list, exactly that one. Beta.28 (the
|
|
90
|
+
* review of Edit the map): only that item's lines go (and the list's key when it was the last),
|
|
91
|
+
* every other byte of the profile as it was: its comments, its flow lists, its version.
|
|
92
|
+
*/
|
|
93
|
+
export declare function undeclareLink(root: string, d: {
|
|
94
|
+
kind: "topic" | "call";
|
|
95
|
+
system: string;
|
|
96
|
+
value: string;
|
|
97
|
+
}, o?: {
|
|
98
|
+
/** A pairing or an answer names the system: a System the canvas added for it stays. */
|
|
99
|
+
inUse?: boolean;
|
|
100
|
+
}): Promise<{
|
|
101
|
+
rel: string;
|
|
102
|
+
changes: LineChange[];
|
|
103
|
+
before: string;
|
|
104
|
+
wrote: string;
|
|
105
|
+
/** S3: the System the canvas added, taken away with its last declaration. */
|
|
106
|
+
removed?: string;
|
|
107
|
+
}>;
|
|
108
|
+
/** A system's declarations, with who and when where the canvas wrote them. */
|
|
109
|
+
export declare function declaredOf(root: string, system: string): Promise<{
|
|
110
|
+
rel?: string;
|
|
111
|
+
list: DeclaredOnFile[];
|
|
112
|
+
}>;
|
|
113
|
+
/** A declared arrow as a person asks for it: the two ends, why, and whether it is built yet. */
|
|
114
|
+
export interface ArrowAsked {
|
|
115
|
+
from: ArrowEnd;
|
|
116
|
+
to: ArrowEnd;
|
|
117
|
+
why: string;
|
|
118
|
+
planned?: boolean;
|
|
119
|
+
}
|
|
120
|
+
/** One declared arrow as the profiles hold it, with the file it is in. */
|
|
121
|
+
export interface DeclaredArrow extends DeclaredLink {
|
|
122
|
+
platform: string;
|
|
123
|
+
/** The profile, relative to the metarepo's org pack: `profiles/<platform>/profile.yaml`. */
|
|
124
|
+
file: string;
|
|
125
|
+
}
|
|
126
|
+
/** Every declared arrow of the profiles, in the profiles' order then the file's. */
|
|
127
|
+
export declare function declaredArrows(op: {
|
|
128
|
+
profiles: readonly {
|
|
129
|
+
platform: string;
|
|
130
|
+
profile?: {
|
|
131
|
+
links?: readonly DeclaredLink[];
|
|
132
|
+
};
|
|
133
|
+
}[];
|
|
134
|
+
}): DeclaredArrow[];
|
|
135
|
+
/**
|
|
136
|
+
* ADR 0204 1.4: write a declared arrow as one item of the profile's `links` (or, with `preview`,
|
|
137
|
+
* say the lines it changes), in `platform`'s profile: the caller's, else the callee's (the caller
|
|
138
|
+
* works it out). The profile moves to version 3 (the number only); comments and order are kept,
|
|
139
|
+
* and the write is refused whole if the file changed since it was read, or if the pair is listed.
|
|
140
|
+
*/
|
|
141
|
+
export declare function declareArrow(root: string, a: ArrowAsked, o: {
|
|
142
|
+
by: string;
|
|
143
|
+
at: string;
|
|
144
|
+
platform: string;
|
|
145
|
+
preview?: boolean;
|
|
146
|
+
/**
|
|
147
|
+
* ADR 0204 3.1 (`add-system`): a system only the code names, added to this profile's systems
|
|
148
|
+
* in the same write as the arrow, with who and when on its id (as the canvas adds one).
|
|
149
|
+
*/
|
|
150
|
+
addSystem?: {
|
|
151
|
+
id: string;
|
|
152
|
+
name: string;
|
|
153
|
+
boundary: "vendor" | "internal";
|
|
154
|
+
};
|
|
155
|
+
}): Promise<{
|
|
156
|
+
rel: string;
|
|
157
|
+
changes: LineChange[];
|
|
158
|
+
written: boolean;
|
|
159
|
+
before: string;
|
|
160
|
+
wrote?: string;
|
|
161
|
+
/** The version the profile was at, when this write raised it (Undo puts it back). */
|
|
162
|
+
raisedFrom?: number;
|
|
163
|
+
}>;
|
|
164
|
+
/**
|
|
165
|
+
* ADR 0204 1.7 and 2.4: take one declared arrow out of `platform`'s profile (Retire the declared
|
|
166
|
+
* arrow, Undo, Remove it): exactly that item's lines, and the `links:` key when it was the last;
|
|
167
|
+
* every other byte as it was, the version too. `preview` says the lines and writes nothing.
|
|
168
|
+
*/
|
|
169
|
+
export declare function retireArrow(root: string, a: {
|
|
170
|
+
from: ArrowEnd;
|
|
171
|
+
to: ArrowEnd;
|
|
172
|
+
}, o: {
|
|
173
|
+
platform: string;
|
|
174
|
+
preview?: boolean;
|
|
175
|
+
/**
|
|
176
|
+
* Undo (ADR 0204 2.4): the version the arrow's write raised the profile from, put back on
|
|
177
|
+
* its own line when no arrow is left, so the file is again exactly as it was.
|
|
178
|
+
*/
|
|
179
|
+
lowerTo?: number;
|
|
180
|
+
}): Promise<{
|
|
181
|
+
rel: string;
|
|
182
|
+
changes: LineChange[];
|
|
183
|
+
written: boolean;
|
|
184
|
+
before: string;
|
|
185
|
+
wrote: string;
|
|
186
|
+
/**
|
|
187
|
+
* The second review of ADR 0204: an Undo's `lowerTo` below what the profile now needs (a topic
|
|
188
|
+
* added since needs version 2): the profile stays at the version it needs, said in these words.
|
|
189
|
+
*/
|
|
190
|
+
keptAt?: {
|
|
191
|
+
version: number;
|
|
192
|
+
why: string;
|
|
193
|
+
};
|
|
194
|
+
}>;
|
|
195
|
+
/**
|
|
196
|
+
* ADR 0204 2.4: Undo of an arrow whose write added a system (`addSystem`): the system goes too,
|
|
197
|
+
* only while it is still exactly as added (its fields hash to its comment's), nothing else names
|
|
198
|
+
* it in the profile and (`inUse`, ADR 0174, the second review) no pairing or answered question
|
|
199
|
+
* names it: the caller works that out from the estate. Else it is left, with why, said by the
|
|
200
|
+
* caller.
|
|
201
|
+
*/
|
|
202
|
+
export declare function removeAddedSystem(root: string, o: {
|
|
203
|
+
platform: string;
|
|
204
|
+
system: string;
|
|
205
|
+
inUse?: boolean;
|
|
206
|
+
}): Promise<{
|
|
207
|
+
removed: boolean;
|
|
208
|
+
rel: string;
|
|
209
|
+
why?: "changed" | "named" | "in-use";
|
|
210
|
+
}>;
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A file rewritten keeps its line endings: a Windows file's CRLF stays CRLF (where Git doesn't
|
|
3
|
+
* normalise them, the whole file would otherwise show as changed in the upgrade's pull request).
|
|
4
|
+
*/
|
|
5
|
+
export declare function keepLineEndings(was: string, now: string): string;
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A file path as Atticus reads it: with `/` only (ADR 0124 addendum W-paths). A facts line
|
|
3
|
+
* written on Windows can cite `src\main\App.java`; every reader of the facts file (the facts
|
|
4
|
+
* parser, the corrections file, the reviewed list, the reader's answer) passes what it reads
|
|
5
|
+
* through here, so the verifier, the join's folder and bundle rules and every record see one
|
|
6
|
+
* form, whichever OS wrote the line.
|
|
7
|
+
*/
|
|
8
|
+
export declare const forwardSlashes: (path: string) => string;
|
|
9
|
+
/**
|
|
10
|
+
* A parsed facts line (or a correction, or any JSON beside them) with every `file` it carries,
|
|
11
|
+
* at any depth (`cite.file`, `cite.with[].file`, an auth's, a scope's, a caller's), written with
|
|
12
|
+
* `/`. Nothing else changes: a claimed path or key is not a file. Returns a copy.
|
|
13
|
+
*/
|
|
14
|
+
export declare function normalizeFactPaths<T>(json: T): T;
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { CatalogRecord } from "./catalog.js";
|
|
2
2
|
import { type FacingWords, type FactEnd, type FactsJoinResult, type GatewayFacing, type JoinRepo } from "./facts-join.js";
|
|
3
|
-
import type { CallerKind } from "./schema/facts.js";
|
|
3
|
+
import type { CallerKind, FactOf } from "./schema/facts.js";
|
|
4
4
|
import type { Profile } from "./schema/orgpack.js";
|
|
5
5
|
/**
|
|
6
6
|
* Who a gateway route lets in (ADR 0124 addendum A-callers). A route's own files usually name
|
|
@@ -119,12 +119,34 @@ export interface JoinCallersInput {
|
|
|
119
119
|
declared?: readonly DeclaredCallInput[];
|
|
120
120
|
/** The estate's facing words, as given to `joinFacts`. */
|
|
121
121
|
facing?: FacingWords;
|
|
122
|
+
/** The gateway bundle folders, as given to `joinFacts` (ADR 0147). */
|
|
123
|
+
bundleFolders?: readonly string[];
|
|
122
124
|
}
|
|
123
125
|
/** Every call a person declared in the org pack's profiles, one per route or identity named. */
|
|
124
126
|
export declare function declaredCallsOf(profiles: readonly {
|
|
125
127
|
platform: string;
|
|
126
128
|
profile?: Profile;
|
|
127
129
|
}[]): DeclaredCallInput[];
|
|
130
|
+
/**
|
|
131
|
+
* Whether the route a person named (a declared call's `route`) is this gateway route: its handler
|
|
132
|
+
* (`proxy/flow`, any case), or `METHOD /path` as the gateway serves it (ANY for a route read with
|
|
133
|
+
* no method; a trailing slash is neither here nor there). The one rule, for the join and for the
|
|
134
|
+
* routes offered to declare (ADR 0200).
|
|
135
|
+
*/
|
|
136
|
+
export declare function declaredRouteMatches(route: {
|
|
137
|
+
handler?: string | undefined;
|
|
138
|
+
method?: string | undefined;
|
|
139
|
+
path: string;
|
|
140
|
+
}, said: string): boolean;
|
|
141
|
+
/**
|
|
142
|
+
* The entry facts of the estate that are gateway routes (A-callers): every entry of a gateway
|
|
143
|
+
* repo, and any repo's entry cited under a proxy bundle folder. The one rule, for the join and
|
|
144
|
+
* for the routes offered to declare (ADR 0200).
|
|
145
|
+
*/
|
|
146
|
+
export declare function gatewayRouteFacts(repos: readonly JoinRepo[], bundleFolders?: readonly string[]): {
|
|
147
|
+
repo: string;
|
|
148
|
+
fact: FactOf<"entry">;
|
|
149
|
+
}[];
|
|
128
150
|
/** Who each gateway route of the estate lets in, and the chain from each declared caller. */
|
|
129
151
|
export declare function joinCallers(input: JoinCallersInput): CallersResult;
|
|
130
152
|
/** A chain in one line: `Harbor Desk (declared; app harbor-desk-portal) → edge-gateway … → …`. */
|
|
@@ -6,13 +6,19 @@ import type { Fact } from "./schema/facts.js";
|
|
|
6
6
|
* that was edited, renamed or deleted is read again. Pure: the diff comes from the git adapter
|
|
7
7
|
* (`changedFiles` in @maycombhq/workspace), so the same facts and the same diff split the same way.
|
|
8
8
|
*/
|
|
9
|
-
/** One file changed between two commits, as `git diff --
|
|
9
|
+
/** One file changed between two commits, as `git diff --raw -M` says it. */
|
|
10
10
|
export interface FileChange {
|
|
11
11
|
status: "added" | "modified" | "deleted" | "renamed" | "copied" | "type-changed";
|
|
12
12
|
/** The path at the newer commit (a deleted file's path at the older one). */
|
|
13
13
|
path: string;
|
|
14
14
|
/** A rename's or copy's path at the older commit. */
|
|
15
15
|
from?: string;
|
|
16
|
+
/**
|
|
17
|
+
* Review round 49: the path is a submodule's gitlink (mode 160000 at either commit), so the
|
|
18
|
+
* diff names the folder, not the files in it that changed. Every cited file under it is read
|
|
19
|
+
* again.
|
|
20
|
+
*/
|
|
21
|
+
gitlink?: boolean;
|
|
16
22
|
}
|
|
17
23
|
/** Why a fact must be read again: the first file it cites that changed, and how. */
|
|
18
24
|
export interface StaleCite {
|
|
@@ -24,7 +30,7 @@ export interface StaleCite {
|
|
|
24
30
|
}
|
|
25
31
|
/**
|
|
26
32
|
* The files a fact rests on: its cite and the cite's `with` parts, an entry's `authCite` (ADR
|
|
27
|
-
* 0124 addendum A-read), and for a flow every step's and error path's cite and parts. Unique and
|
|
33
|
+
* 0124 addendum A-read) and a call's `authCite` and `tlsCite` (ADR 0163), with their parts, and for a flow every step's and error path's cite and parts. Unique and
|
|
28
34
|
* sorted, except that a fact's own cited file comes first for a non-flow fact.
|
|
29
35
|
*/
|
|
30
36
|
export declare function citedFiles(f: Fact): string[];
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import type { FactEnd, JoinRepo } from "./facts-join.js";
|
|
2
|
+
import type { DependencyScope } from "./schema/facts.js";
|
|
3
|
+
/**
|
|
4
|
+
* The estate's build dependencies (ADR 0192): a component's `dependency` fact that names the
|
|
5
|
+
* coordinates (group and name) another component's `artifact` fact publishes is a "depends on"
|
|
6
|
+
* link from the one to the other, with a cited line at both ends: the dependency's in the
|
|
7
|
+
* depending build file, the published coordinates' in the library's. Matching is by those
|
|
8
|
+
* coordinates alone, letter case aside: no group prefix, naming convention or repo type says
|
|
9
|
+
* what is the organisation's own; what some repo of the estate publishes is.
|
|
10
|
+
*
|
|
11
|
+
* - A dependency on coordinates nobody in the estate publishes (a vendor SDK, an open-source
|
|
12
|
+
* library) draws nothing and asks nothing: it is counted in `outside`.
|
|
13
|
+
* - A test-scoped dependency draws nothing (`test`): it builds the tests, not the component.
|
|
14
|
+
* - Coordinates two components publish draw nothing either: they are `ambiguous`, for a person.
|
|
15
|
+
* - A component's dependency on its own coordinates draws nothing.
|
|
16
|
+
*
|
|
17
|
+
* The library's own calls are the library's: nothing here touches a call, and nothing of the
|
|
18
|
+
* library is given to the components that depend on it. Pure: the same facts give the same
|
|
19
|
+
* links, whatever order the repos come in.
|
|
20
|
+
*/
|
|
21
|
+
/** One end of a "depends on" link: its fact, and every line the claim rests on (`file:line`). */
|
|
22
|
+
export interface DependencyEnd extends FactEnd {
|
|
23
|
+
lines: string[];
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Review of beta.25: one dependency fact a link rests on, with the coordinates it names (a link
|
|
27
|
+
* between two components holds every coordinate one builds on of the other's: `kit-api` and
|
|
28
|
+
* `kit-core` of component `kit` are one arrow).
|
|
29
|
+
*/
|
|
30
|
+
export interface DependencyFactEnd extends DependencyEnd {
|
|
31
|
+
group: string;
|
|
32
|
+
name: string;
|
|
33
|
+
version?: string;
|
|
34
|
+
/** Its scope, when not compile. */
|
|
35
|
+
scope?: DependencyScope;
|
|
36
|
+
}
|
|
37
|
+
export interface DependencyLink {
|
|
38
|
+
/** The dependency fact, in the component that builds on the library (the first by id). */
|
|
39
|
+
from: DependencyEnd;
|
|
40
|
+
/**
|
|
41
|
+
* Beta.25: every dependency fact the link rests on, `from` first, each with its lines: two
|
|
42
|
+
* module poms of one component, a `<profile>`'s copy, `implementation` and `runtimeOnly` of the
|
|
43
|
+
* same coordinates, and (review of beta.25) every other coordinate of the same library
|
|
44
|
+
* component, each with its coordinates. The link goes only once each of them is wrong.
|
|
45
|
+
*/
|
|
46
|
+
facts?: (DependencyEnd & Partial<Pick<DependencyFactEnd, "group" | "name" | "version" | "scope">>)[];
|
|
47
|
+
/** The artifact fact, in the library's component, that publishes the coordinates. */
|
|
48
|
+
to: DependencyEnd;
|
|
49
|
+
/**
|
|
50
|
+
* Review of beta.25: every artifact fact of the library's component a dependency on the link
|
|
51
|
+
* names, `to` first (one per coordinate).
|
|
52
|
+
*/
|
|
53
|
+
published?: DependencyEnd[];
|
|
54
|
+
group: string;
|
|
55
|
+
name: string;
|
|
56
|
+
/**
|
|
57
|
+
* The dependency's declared scope, when it says one other than compile; on a link merged from
|
|
58
|
+
* several facts (review of beta.25), only when every one of them has it, else left out.
|
|
59
|
+
*/
|
|
60
|
+
scope?: DependencyScope;
|
|
61
|
+
/** The version the dependency declares, when it says one. */
|
|
62
|
+
version?: string;
|
|
63
|
+
}
|
|
64
|
+
/** Coordinates two or more components of the estate publish: nothing is drawn to either. */
|
|
65
|
+
export interface AmbiguousCoordinates {
|
|
66
|
+
group: string;
|
|
67
|
+
name: string;
|
|
68
|
+
by: FactEnd[];
|
|
69
|
+
}
|
|
70
|
+
export interface DependencyJoinResult {
|
|
71
|
+
links: DependencyLink[];
|
|
72
|
+
ambiguous: AmbiguousCoordinates[];
|
|
73
|
+
/** Dependencies on coordinates nobody in the estate publishes: drawn as nothing. */
|
|
74
|
+
outside: number;
|
|
75
|
+
/** Test-scoped dependencies on the estate's own coordinates: drawn as nothing. */
|
|
76
|
+
test: number;
|
|
77
|
+
}
|
|
78
|
+
export declare function joinDependencies(input: {
|
|
79
|
+
repos: readonly JoinRepo[];
|
|
80
|
+
}): DependencyJoinResult;
|
|
81
|
+
/**
|
|
82
|
+
* The id a "depends on" link is known by, for a view's join: stable across reads of one pom, and
|
|
83
|
+
* (review of beta.25) one per pair of components, as the join makes one link per pair.
|
|
84
|
+
*/
|
|
85
|
+
export declare const dependencyLinkId: (l: Pick<DependencyLink, "from" | "to">) => string;
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { type FactEnd, type JoinHow, type JoinRepo } from "./facts-join.js";
|
|
1
|
+
import { type FactEnd, type JoinHow, type FacingWords, type JoinRepo } from "./facts-join.js";
|
|
2
2
|
import { type JoinVendor, type JoinVendorOperation } from "./facts-join-vendor.js";
|
|
3
3
|
import type { Fact, FactOf } from "./schema/facts.js";
|
|
4
4
|
/**
|
|
@@ -55,6 +55,10 @@ export interface PrototypeVendorField {
|
|
|
55
55
|
name: string;
|
|
56
56
|
type?: string;
|
|
57
57
|
required?: boolean;
|
|
58
|
+
/** The values the spec's `enum` lists (ADR 0142). */
|
|
59
|
+
enum?: readonly string[];
|
|
60
|
+
/** Where a request field travels (`header` makes it a header, ADR 0142). */
|
|
61
|
+
in?: string;
|
|
58
62
|
/** spec path:line of the property. */
|
|
59
63
|
at?: string;
|
|
60
64
|
}
|
|
@@ -62,18 +66,30 @@ export interface PrototypeVendorOperation extends JoinVendorOperation {
|
|
|
62
66
|
auth?: string;
|
|
63
67
|
scopes?: readonly string[];
|
|
64
68
|
fields?: readonly PrototypeVendorField[];
|
|
69
|
+
/** The error statuses the spec lists (4xx, 5xx), each with its line (ADR 0142). */
|
|
70
|
+
errors?: readonly {
|
|
71
|
+
status: string;
|
|
72
|
+
at?: string;
|
|
73
|
+
}[];
|
|
65
74
|
}
|
|
66
|
-
/**
|
|
75
|
+
/**
|
|
76
|
+
* A vendor, or another team's system (O2, `boundary: internal`), with its published operations
|
|
77
|
+
* and their fields (ADR 0130's reading of its spec).
|
|
78
|
+
*/
|
|
67
79
|
export interface PrototypeVendor extends JoinVendor {
|
|
68
80
|
operations: readonly PrototypeVendorOperation[];
|
|
69
81
|
}
|
|
70
|
-
export type PrototypeDifferenceKind = "field-missing" | "field-type" | "field-required" | "scope-missing" | "auth";
|
|
82
|
+
export type PrototypeDifferenceKind = "field-missing" | "field-type" | "field-required" | "field-enum" | "header-missing" | "header-required" | "error-missing" | "error-unhandled" | "scope-missing" | "auth";
|
|
71
83
|
/** One way the estate (or the vendor) serves an operation other than as the prototype needs. */
|
|
72
84
|
export interface PrototypeDifference {
|
|
73
85
|
kind: PrototypeDifferenceKind;
|
|
74
86
|
side?: "request" | "response";
|
|
75
87
|
field?: string;
|
|
76
88
|
scope?: string;
|
|
89
|
+
/** field-enum: the value one side lists and the other doesn't. */
|
|
90
|
+
value?: string;
|
|
91
|
+
/** error-missing, error-unhandled: the status. */
|
|
92
|
+
status?: string;
|
|
77
93
|
/** What the prototype says, and the line it says it on. */
|
|
78
94
|
prototype: {
|
|
79
95
|
value: string;
|
|
@@ -120,8 +136,13 @@ export interface PrototypeCall {
|
|
|
120
136
|
method: string;
|
|
121
137
|
path: string;
|
|
122
138
|
at?: string;
|
|
123
|
-
/**
|
|
139
|
+
/**
|
|
140
|
+
* The estate's repos that forward to this vendor already: where the new route goes. For
|
|
141
|
+
* another team's system, the repos that call it already.
|
|
142
|
+
*/
|
|
124
143
|
through: string[];
|
|
144
|
+
/** `internal`: another team's system, which the change calls as it publishes it (O2). */
|
|
145
|
+
boundary?: "vendor" | "internal";
|
|
125
146
|
};
|
|
126
147
|
/** Two or more estate entries serve it equally well: a person says which. */
|
|
127
148
|
candidates?: FactEnd[];
|
|
@@ -156,6 +177,10 @@ export interface ComparePrototypeInput {
|
|
|
156
177
|
vendors?: readonly PrototypeVendor[];
|
|
157
178
|
/** The org pack's outside systems (vendors' ids and names), as the estate join takes them. */
|
|
158
179
|
outside?: readonly string[];
|
|
180
|
+
/** The org pack's facing words (ADR 0147), as the estate join takes them. */
|
|
181
|
+
facing?: FacingWords;
|
|
182
|
+
/** The org pack's gateway bundle folders (ADR 0147), as the estate join takes them. */
|
|
183
|
+
bundleFolders?: readonly string[];
|
|
159
184
|
}
|
|
160
185
|
/** The words of the comparison, in one place: the CLI, the attached document and the app say these. */
|
|
161
186
|
export declare const PROTOTYPE_WORDS: {
|
|
@@ -165,6 +190,16 @@ export declare const PROTOTYPE_WORDS: {
|
|
|
165
190
|
ambiguous: (what: string, who: string, n: number) => string;
|
|
166
191
|
new: (what: string, who: string) => string;
|
|
167
192
|
vendor: (what: string, who: string, name: string, op: string, at: string, through: string[]) => string;
|
|
193
|
+
team: (what: string, who: string, name: string, op: string, at: string, through: string[]) => string;
|
|
194
|
+
enumNotTaken: (name: string, v: string, at: string, repo: string, theirs: string[], theirAt: string) => string;
|
|
195
|
+
enumNotReturned: (name: string, v: string, at: string, repo: string, theirs: string[], theirAt: string) => string;
|
|
196
|
+
enumUnhandled: (name: string, v: string, theirAt: string, repo: string, mine: string[], at: string) => string;
|
|
197
|
+
headerMissing: (side: string, name: string, at: string, repo: string, theirs: string[]) => string;
|
|
198
|
+
headerRequired: (name: string, theirAt: string, repo: string) => string;
|
|
199
|
+
errorMissing: (status: string, at: string, repo: string, theirs: string[]) => string;
|
|
200
|
+
errorUnhandled: (status: string, theirAt: string, repo: string, mine: string[]) => string;
|
|
201
|
+
architectureHeading: string;
|
|
202
|
+
architectureIntro: (repo: string) => string;
|
|
168
203
|
fieldMissing: (side: string, name: string, at: string, repo: string) => string;
|
|
169
204
|
fieldType: (side: string, name: string, mine: string, at: string, repo: string, theirs: string, raw: string, theirAt: string) => string;
|
|
170
205
|
fieldRequired: (side: string, name: string, mine: boolean, at: string, repo: string, theirAt: string) => string;
|
|
@@ -172,6 +207,33 @@ export declare const PROTOTYPE_WORDS: {
|
|
|
172
207
|
auth: (mine: string, at: string, repo: string, theirs: string, theirAt: string) => string;
|
|
173
208
|
left: (what: string, who: string) => string;
|
|
174
209
|
};
|
|
210
|
+
/**
|
|
211
|
+
* The family a declared type belongs to, compared across languages; undefined when unsure. The
|
|
212
|
+
* contract check (ADR 0164) reads it too, with protobuf's and Avro's scalar names.
|
|
213
|
+
*/
|
|
214
|
+
export declare function typeFamily(t: string | undefined): string | undefined;
|
|
215
|
+
/**
|
|
216
|
+
* The values an enum field's `type` lists (ADR 0142), as the facts write it: a union of quoted
|
|
217
|
+
* literals (`"captured" | "failed"`), a named list (`ChargeStatus(CAPTURED|FAILED)`,
|
|
218
|
+
* `enum(EUR, USD)`), or the values alone (`EUR|USD`). Undefined when the type lists none: a
|
|
219
|
+
* plain `String`, or an enum named but not listed, whose values are unknown.
|
|
220
|
+
*/
|
|
221
|
+
export declare function enumValues(type: string | undefined): string[] | undefined;
|
|
222
|
+
export declare const isHeaderName: (name: string) => boolean;
|
|
175
223
|
/** Compare a prototype's calls with what the estate and the vendors serve. */
|
|
176
224
|
export declare function comparePrototype(input: ComparePrototypeInput): PrototypeComparison;
|
|
225
|
+
/**
|
|
226
|
+
* The calls nothing in the estate serves, for the architecture stage (ADR 0142): a section of the
|
|
227
|
+
* attached comparison, each call with what it sends and reads, cited. Where each goes is that
|
|
228
|
+
* stage's to decide, so the footprint gains nothing from them; the stage reads this section back
|
|
229
|
+
* (`readPrototypeArchitecture`) and is told to place each one. Empty when nothing is new.
|
|
230
|
+
*/
|
|
231
|
+
export declare function prototypeArchitectureSection(c: PrototypeComparison,
|
|
232
|
+
/** The prototype's facts, for the fields each call carries. */
|
|
233
|
+
facts: readonly Fact[]): string[];
|
|
234
|
+
/**
|
|
235
|
+
* The calls an attached comparison lists for the architecture stage, as written (with the
|
|
236
|
+
* `[file:line]` an attached file's read text puts before each line, when it has one).
|
|
237
|
+
*/
|
|
238
|
+
export declare function readPrototypeArchitecture(text: string): string[];
|
|
177
239
|
export {};
|
|
@@ -13,11 +13,23 @@ import { type FactEnd, type JoinRepo } from "./facts-join.js";
|
|
|
13
13
|
* name written in a host label (api.northwindpay.example → Northwind Pay), as the merge does.
|
|
14
14
|
* A call whose host no vendor claims is left alone: it is the join's, never guessed.
|
|
15
15
|
*
|
|
16
|
+
* Beta.27 (a user's estate): a target URL written as a deploy token (`@targetVendorUrl@`) is
|
|
17
|
+
* each value the config facts setting that token give it, per environment, as the join reads it;
|
|
18
|
+
* and the path the vendor receives is the target URL's own path (`/api/v1`) with the path the
|
|
19
|
+
* route forwards after it. A host an estate repo's manifest lists is the estate's, never a
|
|
20
|
+
* vendor's, whatever the profile's aliases say; a base that is a config key of the repo is never
|
|
21
|
+
* read as a host itself; and a call the estate join joined to an entry (a service's call to the
|
|
22
|
+
* gateway's own base path) reaches the vendor through that route, never directly.
|
|
23
|
+
*
|
|
16
24
|
* Then the operation: the vendor's operations of the same method whose path, with the spec's
|
|
17
|
-
* server path in front or without it, has the call's shape
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
25
|
+
* server path in front or without it, has the call's shape: a path parameter (`{version}`,
|
|
26
|
+
* `{account_guid}`) stands for any one segment, and a literal segment is preferred over a
|
|
27
|
+
* parameter where both fit (`/accounts/balances` over `/accounts/{account_guid}`), as OpenAPI
|
|
28
|
+
* routes. One is a match; none is a gap (the vendor's spec doesn't publish what the gateway
|
|
29
|
+
* forwards); two or more equally good is a question. A route that forwards a wildcard (a `*`
|
|
30
|
+
* segment, or `**` at the end) reaches every operation under it by design: each is a match
|
|
31
|
+
* (`wildcard`), never a question. Pure and deterministic: the same facts, answers and operations
|
|
32
|
+
* give the same result, whatever order they come in.
|
|
21
33
|
*/
|
|
22
34
|
/** One operation a vendor publishes, as intake reads it from the vendor's spec. */
|
|
23
35
|
export interface JoinVendorOperation {
|
|
@@ -31,10 +43,21 @@ export interface JoinVendorOperation {
|
|
|
31
43
|
/** spec path:line of the operation. */
|
|
32
44
|
cite?: string;
|
|
33
45
|
}
|
|
34
|
-
/**
|
|
46
|
+
/**
|
|
47
|
+
* A vendor, or any other system outside the estate that publishes a spec (O2: another team's,
|
|
48
|
+
* boundary `internal`), and what the join needs to find its calls: its names, its hosts and its
|
|
49
|
+
* operations.
|
|
50
|
+
*/
|
|
35
51
|
export interface JoinVendor {
|
|
36
|
-
/** The org pack's system id
|
|
52
|
+
/** The org pack's system id: a vendor's, or another outside system's. */
|
|
37
53
|
system: string;
|
|
54
|
+
/**
|
|
55
|
+
* The system's boundary in the profile. `internal` (another team's system, ADR 0142): the
|
|
56
|
+
* estate's services call it themselves, not through the external gateway, so a service's own
|
|
57
|
+
* call to it is matched too (`direct` on the match). Left out, or `vendor`: only a gateway's
|
|
58
|
+
* forwarding calls are matched, as ADR 0130 says.
|
|
59
|
+
*/
|
|
60
|
+
boundary?: "vendor" | "internal";
|
|
38
61
|
/** Its name and aliases, as the org pack writes them. */
|
|
39
62
|
names: readonly string[];
|
|
40
63
|
/** The hosts its spec's servers name, and any host the org pack gives it (patterns allowed). */
|
|
@@ -55,8 +78,24 @@ export interface VendorCallMatch {
|
|
|
55
78
|
/** The vendor operation's Endpoint id. */
|
|
56
79
|
operation: string;
|
|
57
80
|
method?: string;
|
|
58
|
-
/** The path the gateway forwards to. */
|
|
81
|
+
/** The path the gateway forwards to: the target URL's own path in front, when it has one. */
|
|
59
82
|
path: string;
|
|
83
|
+
/**
|
|
84
|
+
* The environment whose target URL gives `path` (its config fact's `env`), when the settings
|
|
85
|
+
* name one: of those whose path reaches the operation, the prod-like one, else the first by
|
|
86
|
+
* name (`preferredEnvironment`).
|
|
87
|
+
*/
|
|
88
|
+
env?: string;
|
|
89
|
+
/**
|
|
90
|
+
* Beta.27: the route forwards a wildcard (`/accounts/*`), so it reaches every operation under
|
|
91
|
+
* it; this is one of them (the call has a match for each).
|
|
92
|
+
*/
|
|
93
|
+
wildcard?: true;
|
|
94
|
+
/**
|
|
95
|
+
* ADR 0142: a service's own call to another team's system, not a gateway's forwarding call;
|
|
96
|
+
* `route` is then the entry the call is made under, when it names one.
|
|
97
|
+
*/
|
|
98
|
+
direct?: true;
|
|
60
99
|
}
|
|
61
100
|
/** A forwarding call to an operation the vendor's spec doesn't publish. */
|
|
62
101
|
export interface VendorCallGap {
|
|
@@ -66,6 +105,8 @@ export interface VendorCallGap {
|
|
|
66
105
|
vendor: string;
|
|
67
106
|
method?: string;
|
|
68
107
|
path: string;
|
|
108
|
+
/** The environment whose target path `path` is (see `VendorCallMatch.env`). */
|
|
109
|
+
env?: string;
|
|
69
110
|
message: string;
|
|
70
111
|
}
|
|
71
112
|
/** A forwarding call two or more of the vendor's operations answer equally well. */
|
|
@@ -76,6 +117,8 @@ export interface VendorCallAsk {
|
|
|
76
117
|
question: string;
|
|
77
118
|
/** The operations' Endpoint ids, sorted. */
|
|
78
119
|
candidates: string[];
|
|
120
|
+
/** The environment whose target path the question is about (see `VendorCallMatch.env`). */
|
|
121
|
+
env?: string;
|
|
79
122
|
}
|
|
80
123
|
export interface VendorJoinResult {
|
|
81
124
|
matches: VendorCallMatch[];
|
|
@@ -87,6 +130,23 @@ export interface JoinVendorOperationsInput {
|
|
|
87
130
|
vendors: readonly JoinVendor[];
|
|
88
131
|
/** A person's answer naming the repo or system a call goes to: repo → call fact id → name. */
|
|
89
132
|
targets?: Readonly<Record<string, Readonly<Record<string, string>>>>;
|
|
133
|
+
/** The gateway bundle folders, as given to `joinFacts` (ADR 0147). */
|
|
134
|
+
bundleFolders?: readonly string[];
|
|
135
|
+
/**
|
|
136
|
+
* Beta.27: the estate join's joins. A call joined to an entry of the estate (a service's call
|
|
137
|
+
* to the gateway's own host and base path, joined to the proxy's route) goes there: the route
|
|
138
|
+
* forwards it on, so it is never a direct call to the vendor.
|
|
139
|
+
*/
|
|
140
|
+
joined?: readonly {
|
|
141
|
+
call: FactEnd;
|
|
142
|
+
}[];
|
|
90
143
|
}
|
|
144
|
+
/**
|
|
145
|
+
* The review of beta.27: the environment whose target URL a match, gap or drawn arrow takes its
|
|
146
|
+
* path from when the environments' settings differ: the first by name of the prod-like ones (a
|
|
147
|
+
* name with `pd`, `prod`, `prd` or `production` as a word of its own: `prod`, `us-prd`, `prod1`),
|
|
148
|
+
* else the first by name. Undefined when none is named.
|
|
149
|
+
*/
|
|
150
|
+
export declare function preferredEnvironment(envs: readonly string[]): string | undefined;
|
|
91
151
|
/** Match every gateway forwarding call that goes to a vendor to the vendor operation it reaches. */
|
|
92
152
|
export declare function joinVendorOperations(input: JoinVendorOperationsInput): VendorJoinResult;
|