@maycombhq/sdk 0.0.0-stage → 2.0.0-beta.10
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/LICENSE +177 -0
- package/npm/cache.d.ts +47 -0
- package/npm/core/api.d.ts +7462 -0
- package/npm/core/assistant-actor.d.ts +15 -0
- package/npm/core/audit.d.ts +153 -0
- package/npm/core/branches.d.ts +21 -0
- package/npm/core/cancel.d.ts +9 -0
- package/npm/core/catalog.d.ts +4733 -0
- package/npm/core/change-types-migrate.d.ts +10 -0
- package/npm/core/cite.d.ts +54 -0
- package/npm/core/curated.d.ts +37 -0
- package/npm/core/fact-paths.d.ts +14 -0
- package/npm/core/facts-callers.d.ts +152 -0
- package/npm/core/facts-carry.d.ts +36 -0
- package/npm/core/facts-join-prototype.d.ts +234 -0
- package/npm/core/facts-join-vendor.d.ts +110 -0
- package/npm/core/facts-join.d.ts +482 -0
- package/npm/core/facts.d.ts +94 -0
- package/npm/core/fs.d.ts +47 -0
- package/npm/core/gates-migrate.d.ts +10 -0
- package/npm/core/host-questions.d.ts +66 -0
- package/npm/core/identity.d.ts +17 -0
- package/npm/core/index.d.ts +73 -0
- package/npm/core/json-schema.d.ts +20 -0
- package/npm/core/judgments.d.ts +63 -0
- package/npm/core/light.d.ts +8 -0
- package/npm/core/link-evidence.d.ts +212 -0
- package/npm/core/log.d.ts +49 -0
- package/npm/core/manifest-edit.d.ts +57 -0
- package/npm/core/merge.d.ts +78 -0
- package/npm/core/metarepo.d.ts +91 -0
- package/npm/core/migrate.d.ts +31 -0
- package/npm/core/migration-files.d.ts +13 -0
- package/npm/core/orgpack-defaults.d.ts +199 -0
- package/npm/core/orgpack-load.d.ts +102 -0
- package/npm/core/question-order.d.ts +23 -0
- package/npm/core/question-owners.d.ts +53 -0
- package/npm/core/question-proposals.d.ts +77 -0
- package/npm/core/questions.d.ts +297 -0
- package/npm/core/record-cache.d.ts +52 -0
- package/npm/core/refs.d.ts +9 -0
- package/npm/core/repo-description.d.ts +44 -0
- package/npm/core/repo-reads.d.ts +44 -0
- package/npm/core/roles-migrate.d.ts +9 -0
- package/npm/core/runtime-migrate.d.ts +11 -0
- package/npm/core/schema/ai.d.ts +397 -0
- package/npm/core/schema/change.d.ts +244 -0
- package/npm/core/schema/common.d.ts +135 -0
- package/npm/core/schema/conventions.d.ts +75 -0
- package/npm/core/schema/dialect.d.ts +801 -0
- package/npm/core/schema/executors.d.ts +396 -0
- package/npm/core/schema/fact-corrections.d.ts +55 -0
- package/npm/core/schema/facts.d.ts +1491 -0
- package/npm/core/schema/frameworks.d.ts +371 -0
- package/npm/core/schema/judgment.d.ts +77 -0
- package/npm/core/schema/kinds.d.ts +5166 -0
- package/npm/core/schema/layout.d.ts +25 -0
- package/npm/core/schema/orgpack.d.ts +1185 -0
- package/npm/core/schema/plugin.d.ts +73 -0
- package/npm/core/schema/question.d.ts +195 -0
- package/npm/core/schema/repo-type.d.ts +109 -0
- package/npm/core/schema/review.d.ts +558 -0
- package/npm/core/schema/scan-settings.d.ts +34 -0
- package/npm/core/schema/scan-verify.d.ts +535 -0
- package/npm/core/schema/spec.d.ts +269 -0
- package/npm/core/schema/version.d.ts +9 -0
- package/npm/core/schema/workspace.d.ts +330 -0
- package/npm/core/serialize.d.ts +17 -0
- package/npm/core/shared-maps.d.ts +146 -0
- package/npm/core/sources-migrate.d.ts +15 -0
- package/npm/core/specs.d.ts +66 -0
- package/npm/core/stack-helpers.d.ts +32 -0
- package/npm/core/tar-read.d.ts +13 -0
- package/npm/core/template.d.ts +101 -0
- package/npm/core/words.d.ts +13 -0
- package/npm/core/zip-read.d.ts +37 -0
- package/npm/core/zip.d.ts +13 -0
- package/npm/fs-repo.d.ts +34 -0
- package/npm/index.d.ts +6 -0
- package/npm/index.js +9780 -0
- package/npm/parse-cache.d.ts +97 -0
- package/npm/plugin.d.ts +89 -0
- package/npm/runner.d.ts +72 -0
- package/npm/sandbox.d.ts +80 -0
- package/package.json +28 -3
- package/README.md +0 -3
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* change-types.yaml version 1 → 2 (ADR 0113). Version 2 adds a type's size, whether a brief may
|
|
3
|
+
* say it is small, and the fast path's gate; a type that sets none of them is standard, as every
|
|
4
|
+
* type was in version 1. So the migration only writes the new version and keeps the file's
|
|
5
|
+
* comments and order: no type changes path until a person marks it small.
|
|
6
|
+
*/
|
|
7
|
+
export declare function migrateChangeTypesText(text: string): {
|
|
8
|
+
text: string;
|
|
9
|
+
changed: boolean;
|
|
10
|
+
};
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Citations: does a line say what a fact or a flow step claims (ADR 0089), does a quote match a
|
|
3
|
+
* line once the model's small rewrites are forgiven (ADR 0103), and what must never be quoted
|
|
4
|
+
* (ADR 0124). Pure functions; the verifier and the spec check both use them.
|
|
5
|
+
*/
|
|
6
|
+
/** A field as compared: the last dotted part, lower case, without _ - or spaces. */
|
|
7
|
+
export declare const fieldKey: (f: string) => string;
|
|
8
|
+
/**
|
|
9
|
+
* Whether a line names a route: the path, or its tail once leading segments are dropped (a
|
|
10
|
+
* class-level prefix sits elsewhere), with at least one plain segment left. Parameters match
|
|
11
|
+
* in any style ({id}, :id, <id>, ${id}), and a parameter at the end may be left off the line
|
|
12
|
+
* (a path built as `base + "/v1/rates/" + pair`).
|
|
13
|
+
*/
|
|
14
|
+
export declare function lineNamesRoute(line: string, path: string): boolean;
|
|
15
|
+
/** Whether a line names a word (a table, a topic): case aside, not inside a longer word. */
|
|
16
|
+
export declare const lineNamesWord: (line: string, word: string) => boolean;
|
|
17
|
+
/** Whether a line names a field, letter case and _ or - aside (first_name matches firstName). */
|
|
18
|
+
export declare const lineNamesField: (line: string, field: string) => boolean;
|
|
19
|
+
export interface Claim {
|
|
20
|
+
kind: "route" | "word" | "field";
|
|
21
|
+
value: string;
|
|
22
|
+
}
|
|
23
|
+
export declare const lineNamesClaim: (line: string, c: Claim) => boolean;
|
|
24
|
+
/**
|
|
25
|
+
* Whether the claim is on the cited line (1-based) or within `window` lines either side: an
|
|
26
|
+
* annotation often sits on the line above its handler, and a path may wrap.
|
|
27
|
+
*/
|
|
28
|
+
export declare function claimOnLines(lines: readonly string[], line: number, claim: Claim, window?: number): boolean;
|
|
29
|
+
/**
|
|
30
|
+
* A quote as compared (ADR 0103): whitespace folded, CRLF to LF, curly quotes straightened,
|
|
31
|
+
* single quotes for double, end punctuation and a trailing semicolon or comma forgiven.
|
|
32
|
+
*/
|
|
33
|
+
export declare function normalizeQuote(q: string): string;
|
|
34
|
+
/** Whether a quote is the line, starts it, or sits inside it, after normalisation. */
|
|
35
|
+
export declare function quoteMatches(line: string, quote: string | undefined): boolean;
|
|
36
|
+
/** A quote is not required from a binary, a notebook, a minified file, or a very long line. */
|
|
37
|
+
export declare function quoteNotRequired(path: string, line: string): boolean;
|
|
38
|
+
/** Paths whose lines are never quoted into a map. */
|
|
39
|
+
export declare function isSecretPath(path: string): boolean;
|
|
40
|
+
/**
|
|
41
|
+
* Redact a line that carries a secret-looking key with a literal value; a placeholder or a
|
|
42
|
+
* reference (`${X}`, `env:X`, `vault:...`) stays, as does a line that names no such key.
|
|
43
|
+
* A private-key block is redacted whole.
|
|
44
|
+
*/
|
|
45
|
+
export declare function redactSecrets(line: string): string;
|
|
46
|
+
/**
|
|
47
|
+
* Whether a word claim is put together from `cite.with` parts (ADR 0124 addendum A-derived): a
|
|
48
|
+
* rake task's `namespace:task`, a key a helper prefixes (`${prefix}_conferenceCache`). Each part's
|
|
49
|
+
* value must be in the claim as a whole piece (bounded by the claim's start or end, a separator
|
|
50
|
+
* `: . _ - / #`, or another part), and whatever is left between the parts, separators aside, must
|
|
51
|
+
* be written on the cited lines. The parts' own lines are checked by the caller.
|
|
52
|
+
*/
|
|
53
|
+
export declare function partsBuildWord(claim: string, parts: readonly string[], lines: readonly string[]): boolean;
|
|
54
|
+
export declare function partsNamePath(lines: readonly string[], path: string): boolean;
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { type CatalogRecord, type RecordOf } from "./catalog.js";
|
|
2
|
+
/**
|
|
3
|
+
* Curated decisions applied over generated records: the last step of building the catalog.
|
|
4
|
+
*
|
|
5
|
+
* Generated records are rebuilt from code on every scan; a person's decision lives in
|
|
6
|
+
* `catalog/curated/` and is replayed over them each time, so it survives rescans.
|
|
7
|
+
*
|
|
8
|
+
* - alias: changes no record (name resolution reads it).
|
|
9
|
+
* - assert: sets fields from `value` on the target; the record becomes `asserted`, with
|
|
10
|
+
* manual evidence naming who.
|
|
11
|
+
* - suppress: drops the target. A suppress whose value names a scope (`{ diagram }` or
|
|
12
|
+
* `{ triage }`) only hides the record from that comparison and changes nothing here.
|
|
13
|
+
* - resolve-conflict: sets the chosen value of each field and clears that `conflicts` entry.
|
|
14
|
+
* The record keeps its confidence when the choice is what it already said (usually what the
|
|
15
|
+
* code says); otherwise it becomes `asserted`.
|
|
16
|
+
* - classify: sets `classification` on a Column (value: a name) or on Schema fields
|
|
17
|
+
* (value: `{ field: name }`).
|
|
18
|
+
*
|
|
19
|
+
* Decisions apply in time order (then id), so a later decision wins. One that can't apply
|
|
20
|
+
* (missing target, wrong value shape, a result that fails C1) is reported and skipped; the
|
|
21
|
+
* catalog never takes a half-applied decision. Pure and deterministic.
|
|
22
|
+
*/
|
|
23
|
+
export type CuratedDecisionRecord = RecordOf<"CuratedDecision">;
|
|
24
|
+
export interface CuratedProblem {
|
|
25
|
+
decision: string;
|
|
26
|
+
target: string;
|
|
27
|
+
message: string;
|
|
28
|
+
}
|
|
29
|
+
export interface CuratedResult {
|
|
30
|
+
records: CatalogRecord[];
|
|
31
|
+
/** Ids of the decisions that applied (aliases and scoped suppressions included). */
|
|
32
|
+
applied: string[];
|
|
33
|
+
/** Ids of the records a suppress decision dropped. */
|
|
34
|
+
suppressed: string[];
|
|
35
|
+
problems: CuratedProblem[];
|
|
36
|
+
}
|
|
37
|
+
export declare function applyCurated(records: CatalogRecord[], decisions: readonly CatalogRecord[]): CuratedResult;
|
|
@@ -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;
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
import type { CatalogRecord } from "./catalog.js";
|
|
2
|
+
import { type FacingWords, type FactEnd, type FactsJoinResult, type GatewayFacing, type JoinRepo } from "./facts-join.js";
|
|
3
|
+
import type { CallerKind } from "./schema/facts.js";
|
|
4
|
+
import type { Profile } from "./schema/orgpack.js";
|
|
5
|
+
/**
|
|
6
|
+
* Who a gateway route lets in (ADR 0124 addendum A-callers). A route's own files usually name
|
|
7
|
+
* its consumers (the API product it belongs to, the developer apps subscribed to it, a client id
|
|
8
|
+
* or certificate subject a check admits), and the reader records them on the route's entry fact
|
|
9
|
+
* as `callers`, each cited. A caller whose repo is never scanned (another team's product) can't
|
|
10
|
+
* be read at all, so a person declares it in the org pack's profile, as a System with the
|
|
11
|
+
* gateway identity it calls as (or the route itself): that declaration links to the cited
|
|
12
|
+
* consumer when the route's files name it, stays marked as a person's word, and never replaces
|
|
13
|
+
* or removes anything the code says.
|
|
14
|
+
*
|
|
15
|
+
* For every route of the estate this gives the consumers its files name, the declared systems
|
|
16
|
+
* that call it, the scanned calls that reach it, and whether nothing at all is known ("callers
|
|
17
|
+
* unknown", which the critic asks about rather than passing). For each declared caller it gives
|
|
18
|
+
* the chain the join reads from there: the person's word first, then each gateway hop, the
|
|
19
|
+
* service, and on through the calls the service makes from that entry.
|
|
20
|
+
*
|
|
21
|
+
* Pure: the same facts, join and declarations give the same result.
|
|
22
|
+
*/
|
|
23
|
+
/** A route's consumer as its own files name it: what it is, its name, and the line naming it. */
|
|
24
|
+
export interface NamedCaller {
|
|
25
|
+
as: CallerKind;
|
|
26
|
+
name: string;
|
|
27
|
+
/** path:line of the citation. */
|
|
28
|
+
at: string;
|
|
29
|
+
}
|
|
30
|
+
/** A gateway route a person says an unscanned system calls (the org pack's profile). */
|
|
31
|
+
export interface DeclaredCallInput {
|
|
32
|
+
system: string;
|
|
33
|
+
name: string;
|
|
34
|
+
boundary: "product" | "internal" | "vendor";
|
|
35
|
+
owner?: string;
|
|
36
|
+
/** The identity the gateway knows the caller by, as the route's files would name it. */
|
|
37
|
+
as?: CallerKind;
|
|
38
|
+
identity?: string;
|
|
39
|
+
/** The route: its handler (`proxy/flow`) or `METHOD /path` as the gateway serves it. */
|
|
40
|
+
route?: string;
|
|
41
|
+
/** Where the person said it, relative to the org pack (`profiles/<platform>/profile.yaml`). */
|
|
42
|
+
source: string;
|
|
43
|
+
}
|
|
44
|
+
/** A declared caller of one route: the person's word, and the cited consumer it links to. */
|
|
45
|
+
export interface DeclaredCaller {
|
|
46
|
+
system: string;
|
|
47
|
+
name: string;
|
|
48
|
+
boundary: "product" | "internal" | "vendor";
|
|
49
|
+
owner?: string;
|
|
50
|
+
as?: CallerKind;
|
|
51
|
+
identity?: string;
|
|
52
|
+
route?: string;
|
|
53
|
+
/** The consumer the route's files name that the declaration says it is; left out when none. */
|
|
54
|
+
linked?: NamedCaller;
|
|
55
|
+
by: "person";
|
|
56
|
+
source: string;
|
|
57
|
+
}
|
|
58
|
+
export interface RouteCallers {
|
|
59
|
+
/** The gateway route (its entry fact). */
|
|
60
|
+
route: FactEnd;
|
|
61
|
+
/** Its catalog GatewayRoute. */
|
|
62
|
+
gatewayRoute: string;
|
|
63
|
+
method?: string;
|
|
64
|
+
path: string;
|
|
65
|
+
/** The consumers the route's own files name, in the facts' order. */
|
|
66
|
+
named: NamedCaller[];
|
|
67
|
+
/** The systems a person declared as calling it. */
|
|
68
|
+
declared: DeclaredCaller[];
|
|
69
|
+
/** The calls of scanned repos that land on it (a gateway's forwarding call into it, too). */
|
|
70
|
+
scanned: FactEnd[];
|
|
71
|
+
/** Nothing names, declares or makes a call into the route: who calls it is a question. */
|
|
72
|
+
unknown?: true;
|
|
73
|
+
}
|
|
74
|
+
/** One step of a declared caller's chain. */
|
|
75
|
+
export type ChainStep = {
|
|
76
|
+
kind: "declared";
|
|
77
|
+
system: string;
|
|
78
|
+
name: string;
|
|
79
|
+
as?: CallerKind;
|
|
80
|
+
identity?: string;
|
|
81
|
+
/** Whether a cited consumer of the route is the identity the person named. */
|
|
82
|
+
linked: boolean;
|
|
83
|
+
} | {
|
|
84
|
+
kind: "gateway";
|
|
85
|
+
component: string;
|
|
86
|
+
proxy: string;
|
|
87
|
+
route: string;
|
|
88
|
+
auth?: string;
|
|
89
|
+
scopes: string[];
|
|
90
|
+
facing?: GatewayFacing;
|
|
91
|
+
} | {
|
|
92
|
+
kind: "service";
|
|
93
|
+
component: string;
|
|
94
|
+
method?: string;
|
|
95
|
+
path: string;
|
|
96
|
+
entry: FactEnd;
|
|
97
|
+
};
|
|
98
|
+
export interface CallerChain {
|
|
99
|
+
system: string;
|
|
100
|
+
/** The GatewayRoute of the first hop: the route the person says the system calls. */
|
|
101
|
+
route: string;
|
|
102
|
+
steps: ChainStep[];
|
|
103
|
+
}
|
|
104
|
+
/** A declaration the facts can't place: no route matches what it names. */
|
|
105
|
+
export interface DeclaredProblem {
|
|
106
|
+
system: string;
|
|
107
|
+
source: string;
|
|
108
|
+
message: string;
|
|
109
|
+
}
|
|
110
|
+
export interface CallersResult {
|
|
111
|
+
routes: RouteCallers[];
|
|
112
|
+
chains: CallerChain[];
|
|
113
|
+
problems: DeclaredProblem[];
|
|
114
|
+
}
|
|
115
|
+
export interface JoinCallersInput {
|
|
116
|
+
repos: readonly JoinRepo[];
|
|
117
|
+
/** The estate's join (`joinFacts`), whole: scanned callers come from it. */
|
|
118
|
+
join: FactsJoinResult;
|
|
119
|
+
declared?: readonly DeclaredCallInput[];
|
|
120
|
+
/** The estate's facing words, as given to `joinFacts`. */
|
|
121
|
+
facing?: FacingWords;
|
|
122
|
+
/** The gateway bundle folders, as given to `joinFacts` (ADR 0147). */
|
|
123
|
+
bundleFolders?: readonly string[];
|
|
124
|
+
}
|
|
125
|
+
/** Every call a person declared in the org pack's profiles, one per route or identity named. */
|
|
126
|
+
export declare function declaredCallsOf(profiles: readonly {
|
|
127
|
+
platform: string;
|
|
128
|
+
profile?: Profile;
|
|
129
|
+
}[]): DeclaredCallInput[];
|
|
130
|
+
/** Who each gateway route of the estate lets in, and the chain from each declared caller. */
|
|
131
|
+
export declare function joinCallers(input: JoinCallersInput): CallersResult;
|
|
132
|
+
/** A chain in one line: `Harbor Desk (declared; app harbor-desk-portal) → edge-gateway … → …`. */
|
|
133
|
+
export declare function chainText(c: CallerChain): string;
|
|
134
|
+
/**
|
|
135
|
+
* The flag on a declared caller's Interface (A-callers): the person's word, made again from the
|
|
136
|
+
* profile whenever the gateway is written, never kept on its own.
|
|
137
|
+
*/
|
|
138
|
+
export declare const DECLARED_CALLER = "declared-caller";
|
|
139
|
+
/**
|
|
140
|
+
* The callers as C1 records, for the routes of `repos` (the gateway repos being written): one
|
|
141
|
+
* AccessGrant per consumer a route names (its subject the identity, its resource the route's
|
|
142
|
+
* GatewayRoute, the route's scopes, cited on the line that names it; `flags` say which kind of
|
|
143
|
+
* identity it is), a GatewayRoute for a route no scanned call reaches (as `joinRecords` writes
|
|
144
|
+
* one for a route a call goes through, with the API product a route belongs to as `product`),
|
|
145
|
+
* and one Interface per declared caller: from the declared System to where the route forwards,
|
|
146
|
+
* `via: gateway` through the route, `asserted`, its evidence the person's word (`manual`) beside
|
|
147
|
+
* the route's line and the consumer line it links to. C1 as it is: no schema change.
|
|
148
|
+
*/
|
|
149
|
+
export declare function callerRecords(result: CallersResult, repos: readonly JoinRepo[], join: FactsJoinResult, o?: {
|
|
150
|
+
only?: readonly string[];
|
|
151
|
+
existing?: readonly CatalogRecord[];
|
|
152
|
+
}): CatalogRecord[];
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import type { Fact } from "./schema/facts.js";
|
|
2
|
+
/**
|
|
3
|
+
* A changed file invalidates only what cites it (CLAUDE.md rule 4; ADR 0124 §3 and addendum
|
|
4
|
+
* A-incremental). When a repo's checkout moves to a new commit, a fact whose every cited file is
|
|
5
|
+
* unchanged still rests on the same lines and is carried to the new commit; a fact citing a file
|
|
6
|
+
* that was edited, renamed or deleted is read again. Pure: the diff comes from the git adapter
|
|
7
|
+
* (`changedFiles` in @maycombhq/workspace), so the same facts and the same diff split the same way.
|
|
8
|
+
*/
|
|
9
|
+
/** One file changed between two commits, as `git diff --name-status -M` says it. */
|
|
10
|
+
export interface FileChange {
|
|
11
|
+
status: "added" | "modified" | "deleted" | "renamed" | "copied" | "type-changed";
|
|
12
|
+
/** The path at the newer commit (a deleted file's path at the older one). */
|
|
13
|
+
path: string;
|
|
14
|
+
/** A rename's or copy's path at the older commit. */
|
|
15
|
+
from?: string;
|
|
16
|
+
}
|
|
17
|
+
/** Why a fact must be read again: the first file it cites that changed, and how. */
|
|
18
|
+
export interface StaleCite {
|
|
19
|
+
/** The cited path, as the fact names it (at the fact's commit). */
|
|
20
|
+
file: string;
|
|
21
|
+
how: "edited" | "renamed" | "deleted";
|
|
22
|
+
/** A renamed file's path at the newer commit. */
|
|
23
|
+
to?: string;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* 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
|
|
28
|
+
* sorted, except that a fact's own cited file comes first for a non-flow fact.
|
|
29
|
+
*/
|
|
30
|
+
export declare function citedFiles(f: Fact): string[];
|
|
31
|
+
/**
|
|
32
|
+
* Whether a diff touches a file the fact cites: the first such file (in `citedFiles` order) and
|
|
33
|
+
* how it changed, or undefined when every cited file is as it was. A file added or copied beside
|
|
34
|
+
* a cited one leaves it as it was; a cited file renamed is followed to its new path.
|
|
35
|
+
*/
|
|
36
|
+
export declare function staleCite(f: Fact, changes: readonly FileChange[]): StaleCite | undefined;
|
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
import { type FactEnd, type JoinHow, type FacingWords, type JoinRepo } from "./facts-join.js";
|
|
2
|
+
import { type JoinVendor, type JoinVendorOperation } from "./facts-join-vendor.js";
|
|
3
|
+
import type { Fact, FactOf } from "./schema/facts.js";
|
|
4
|
+
/**
|
|
5
|
+
* A prototype compared with the estate (ADR 0133). A team's working prototype (a UI, its BFF
|
|
6
|
+
* behind SSO, and the backend mocked) states exactly what a change must deliver: its screens'
|
|
7
|
+
* calls to its BFF, and its BFF's calls to the mocks. This places each of those calls in one of
|
|
8
|
+
* four groups, citing the prototype's line and, where there is one, the estate's or the vendor's:
|
|
9
|
+
*
|
|
10
|
+
* - **exists**: the estate serves it as the prototype needs (through the gateway chain, where the
|
|
11
|
+
* estate join follows one);
|
|
12
|
+
* - **changes**: the estate serves the operation, but a field the prototype sends or reads is
|
|
13
|
+
* missing or differs (type, required-ness), or the prototype's sign-on asks for a scope the
|
|
14
|
+
* estate doesn't demand, or a different auth;
|
|
15
|
+
* - **new**: nothing in the estate serves it and no vendor publishes it;
|
|
16
|
+
* - **vendor**: only a vendor's published operation provides it, so it needs a route through the
|
|
17
|
+
* external gateway (the repos that forward to that vendor already are named).
|
|
18
|
+
*
|
|
19
|
+
* Nothing new matches a call: the estate side is the estate join (`joinFacts`, ADR 0124 C-join,
|
|
20
|
+
* with its fallback by method and path and its walk through gateways), and the vendor side is
|
|
21
|
+
* ADR 0130's `joinVendorOperations`. Inside the prototype, a call is paired with the entry it
|
|
22
|
+
* lands on by `routeScore`, the join's own path rule. A prototype's facts are never projected
|
|
23
|
+
* into the catalog; they are read here, and only here.
|
|
24
|
+
*
|
|
25
|
+
* Pure and deterministic: the same facts and vendors give the same comparison, in any order.
|
|
26
|
+
*/
|
|
27
|
+
/** A repo type that marks a prototype (`prototype`, `prototype-<anything>`), from the manifest. */
|
|
28
|
+
export declare const PROTOTYPE_TYPE: RegExp;
|
|
29
|
+
/** Whether a manifest repo type is a prototype's. */
|
|
30
|
+
export declare const isPrototypeType: (type: string | undefined) => boolean;
|
|
31
|
+
/**
|
|
32
|
+
* The mock tools whose declarations mark a module as the mocked backend (a framework fact naming
|
|
33
|
+
* one, with the module as its component): MSW, WireMock, json-server, MockServer, Prism, Mirage.
|
|
34
|
+
*/
|
|
35
|
+
export declare const MOCK_FRAMEWORKS: RegExp;
|
|
36
|
+
/**
|
|
37
|
+
* A mock's file, by its path: a mocks or stubs folder, a WireMock mapping, a json-server
|
|
38
|
+
* `db.json` or `routes.json`, a Postman collection.
|
|
39
|
+
*/
|
|
40
|
+
export declare const MOCK_FILE: RegExp;
|
|
41
|
+
type Entry = FactOf<"entry">;
|
|
42
|
+
/**
|
|
43
|
+
* Whether an entry is one of the prototype's mocks: its file is a mock's, its module declares a
|
|
44
|
+
* mock tool (a framework fact with that component), or its citation's other lines hold a mock
|
|
45
|
+
* profile (`@Profile("mock")`).
|
|
46
|
+
*/
|
|
47
|
+
export declare function isMockEntry(e: Entry, facts: readonly Fact[]): boolean;
|
|
48
|
+
export declare const PROTOTYPE_GROUPS: readonly ["exists", "changes", "new", "vendor"];
|
|
49
|
+
export type PrototypeGroup = (typeof PROTOTYPE_GROUPS)[number];
|
|
50
|
+
/** `ui-bff`: a screen's call to the prototype's BFF; `bff-mock`: the BFF's call to a mock. */
|
|
51
|
+
export type PrototypeLeg = "ui-bff" | "bff-mock";
|
|
52
|
+
/** A field of a vendor operation, as intake reads it from the spec. */
|
|
53
|
+
export interface PrototypeVendorField {
|
|
54
|
+
side: "request" | "response";
|
|
55
|
+
name: string;
|
|
56
|
+
type?: string;
|
|
57
|
+
required?: boolean;
|
|
58
|
+
/** The values the spec's `enum` lists (ADR 0142). */
|
|
59
|
+
enum?: readonly string[];
|
|
60
|
+
/** Where a request field travels (`header` makes it a header, ADR 0142). */
|
|
61
|
+
in?: string;
|
|
62
|
+
/** spec path:line of the property. */
|
|
63
|
+
at?: string;
|
|
64
|
+
}
|
|
65
|
+
export interface PrototypeVendorOperation extends JoinVendorOperation {
|
|
66
|
+
auth?: string;
|
|
67
|
+
scopes?: readonly string[];
|
|
68
|
+
fields?: readonly PrototypeVendorField[];
|
|
69
|
+
/** The error statuses the spec lists (4xx, 5xx), each with its line (ADR 0142). */
|
|
70
|
+
errors?: readonly {
|
|
71
|
+
status: string;
|
|
72
|
+
at?: string;
|
|
73
|
+
}[];
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* A vendor, or another team's system (O2, `boundary: internal`), with its published operations
|
|
77
|
+
* and their fields (ADR 0130's reading of its spec).
|
|
78
|
+
*/
|
|
79
|
+
export interface PrototypeVendor extends JoinVendor {
|
|
80
|
+
operations: readonly PrototypeVendorOperation[];
|
|
81
|
+
}
|
|
82
|
+
export type PrototypeDifferenceKind = "field-missing" | "field-type" | "field-required" | "field-enum" | "header-missing" | "header-required" | "error-missing" | "error-unhandled" | "scope-missing" | "auth";
|
|
83
|
+
/** One way the estate (or the vendor) serves an operation other than as the prototype needs. */
|
|
84
|
+
export interface PrototypeDifference {
|
|
85
|
+
kind: PrototypeDifferenceKind;
|
|
86
|
+
side?: "request" | "response";
|
|
87
|
+
field?: string;
|
|
88
|
+
scope?: string;
|
|
89
|
+
/** field-enum: the value one side lists and the other doesn't. */
|
|
90
|
+
value?: string;
|
|
91
|
+
/** error-missing, error-unhandled: the status. */
|
|
92
|
+
status?: string;
|
|
93
|
+
/** What the prototype says, and the line it says it on. */
|
|
94
|
+
prototype: {
|
|
95
|
+
value: string;
|
|
96
|
+
at: string;
|
|
97
|
+
};
|
|
98
|
+
/** What the estate says, when it says something. */
|
|
99
|
+
estate?: {
|
|
100
|
+
value: string;
|
|
101
|
+
at: string;
|
|
102
|
+
};
|
|
103
|
+
message: string;
|
|
104
|
+
}
|
|
105
|
+
/** One call of the prototype, placed. */
|
|
106
|
+
export interface PrototypeCall {
|
|
107
|
+
/** `<leg>.<method>-<path>`, stable. */
|
|
108
|
+
id: string;
|
|
109
|
+
leg: PrototypeLeg;
|
|
110
|
+
group: PrototypeGroup;
|
|
111
|
+
method?: string;
|
|
112
|
+
path: string;
|
|
113
|
+
/** The prototype's call. */
|
|
114
|
+
call: FactEnd;
|
|
115
|
+
/** The prototype's entry it lands on: the BFF's route, or the mock. */
|
|
116
|
+
lands: FactEnd;
|
|
117
|
+
/** The auth and scopes the prototype's sign-on gives the route (a BFF route only). */
|
|
118
|
+
auth?: string;
|
|
119
|
+
scopes?: string[];
|
|
120
|
+
/** What in the estate serves it (exists, changes). */
|
|
121
|
+
estate?: {
|
|
122
|
+
entry: FactEnd;
|
|
123
|
+
/** The Endpoint the estate's entry projects to. */
|
|
124
|
+
endpoint: string;
|
|
125
|
+
how: JoinHow;
|
|
126
|
+
/** The gateway routes the estate join went through to reach the entry, in order. */
|
|
127
|
+
gateway?: string[];
|
|
128
|
+
auth?: string;
|
|
129
|
+
scopes?: string[];
|
|
130
|
+
};
|
|
131
|
+
/** The vendor operation that alone provides it (vendor). */
|
|
132
|
+
vendor?: {
|
|
133
|
+
system: string;
|
|
134
|
+
name: string;
|
|
135
|
+
operation: string;
|
|
136
|
+
method: string;
|
|
137
|
+
path: string;
|
|
138
|
+
at?: string;
|
|
139
|
+
/**
|
|
140
|
+
* The estate's repos that forward to this vendor already: where the new route goes. For
|
|
141
|
+
* another team's system, the repos that call it already.
|
|
142
|
+
*/
|
|
143
|
+
through: string[];
|
|
144
|
+
/** `internal`: another team's system, which the change calls as it publishes it (O2). */
|
|
145
|
+
boundary?: "vendor" | "internal";
|
|
146
|
+
};
|
|
147
|
+
/** Two or more estate entries serve it equally well: a person says which. */
|
|
148
|
+
candidates?: FactEnd[];
|
|
149
|
+
differences: PrototypeDifference[];
|
|
150
|
+
sentence: string;
|
|
151
|
+
}
|
|
152
|
+
export interface PrototypeComparison {
|
|
153
|
+
prototype: string;
|
|
154
|
+
counts: Record<PrototypeGroup, number>;
|
|
155
|
+
calls: PrototypeCall[];
|
|
156
|
+
/** The estate repos the change modifies: those serving a call that changes, and the proxies a vendor call needs. */
|
|
157
|
+
repos: string[];
|
|
158
|
+
/** The estate repos that serve calls as they are. */
|
|
159
|
+
uses: string[];
|
|
160
|
+
/** The estate Endpoints that change. */
|
|
161
|
+
endpoints: string[];
|
|
162
|
+
/** The vendor operations the prototype needs routed. */
|
|
163
|
+
vendorOperations: string[];
|
|
164
|
+
vendors: string[];
|
|
165
|
+
/** Calls that land on nothing in the prototype (a sign-on server's keys, say): not compared. */
|
|
166
|
+
left: {
|
|
167
|
+
call: FactEnd;
|
|
168
|
+
why: string;
|
|
169
|
+
}[];
|
|
170
|
+
}
|
|
171
|
+
export interface ComparePrototypeInput {
|
|
172
|
+
/** The prototype's verified facts. */
|
|
173
|
+
prototype: JoinRepo;
|
|
174
|
+
/** The estate's repos as the join reads them; no prototype among them. */
|
|
175
|
+
estate: readonly JoinRepo[];
|
|
176
|
+
/** The vendors whose specs are in inputs/. */
|
|
177
|
+
vendors?: readonly PrototypeVendor[];
|
|
178
|
+
/** The org pack's outside systems (vendors' ids and names), as the estate join takes them. */
|
|
179
|
+
outside?: readonly string[];
|
|
180
|
+
/** The org pack's facing words (ADR 0147), as the estate join takes them. */
|
|
181
|
+
facing?: FacingWords;
|
|
182
|
+
/** The org pack's gateway bundle folders (ADR 0147), as the estate join takes them. */
|
|
183
|
+
bundleFolders?: readonly string[];
|
|
184
|
+
}
|
|
185
|
+
/** The words of the comparison, in one place: the CLI, the attached document and the app say these. */
|
|
186
|
+
export declare const PROTOTYPE_WORDS: {
|
|
187
|
+
leg: Record<PrototypeLeg, string>;
|
|
188
|
+
exists: (what: string, who: string, repo: string, served: string, at: string) => string;
|
|
189
|
+
changes: (what: string, who: string, repo: string, served: string, at: string, n: number) => string;
|
|
190
|
+
ambiguous: (what: string, who: string, n: number) => string;
|
|
191
|
+
new: (what: string, who: string) => string;
|
|
192
|
+
vendor: (what: string, who: string, name: string, op: string, at: string, through: string[]) => string;
|
|
193
|
+
team: (what: string, who: string, name: string, op: string, at: string, through: string[]) => string;
|
|
194
|
+
enumNotTaken: (name: string, v: string, at: string, repo: string, theirs: string[], theirAt: string) => string;
|
|
195
|
+
enumNotReturned: (name: string, v: string, at: string, repo: string, theirs: string[], theirAt: string) => string;
|
|
196
|
+
enumUnhandled: (name: string, v: string, theirAt: string, repo: string, mine: string[], at: string) => string;
|
|
197
|
+
headerMissing: (side: string, name: string, at: string, repo: string, theirs: string[]) => string;
|
|
198
|
+
headerRequired: (name: string, theirAt: string, repo: string) => string;
|
|
199
|
+
errorMissing: (status: string, at: string, repo: string, theirs: string[]) => string;
|
|
200
|
+
errorUnhandled: (status: string, theirAt: string, repo: string, mine: string[]) => string;
|
|
201
|
+
architectureHeading: string;
|
|
202
|
+
architectureIntro: (repo: string) => string;
|
|
203
|
+
fieldMissing: (side: string, name: string, at: string, repo: string) => string;
|
|
204
|
+
fieldType: (side: string, name: string, mine: string, at: string, repo: string, theirs: string, raw: string, theirAt: string) => string;
|
|
205
|
+
fieldRequired: (side: string, name: string, mine: boolean, at: string, repo: string, theirAt: string) => string;
|
|
206
|
+
scopeMissing: (scope: string, at: string, repo: string, theirs: string[]) => string;
|
|
207
|
+
auth: (mine: string, at: string, repo: string, theirs: string, theirAt: string) => string;
|
|
208
|
+
left: (what: string, who: string) => string;
|
|
209
|
+
};
|
|
210
|
+
/**
|
|
211
|
+
* The values an enum field's `type` lists (ADR 0142), as the facts write it: a union of quoted
|
|
212
|
+
* literals (`"captured" | "failed"`), a named list (`ChargeStatus(CAPTURED|FAILED)`,
|
|
213
|
+
* `enum(EUR, USD)`), or the values alone (`EUR|USD`). Undefined when the type lists none: a
|
|
214
|
+
* plain `String`, or an enum named but not listed, whose values are unknown.
|
|
215
|
+
*/
|
|
216
|
+
export declare function enumValues(type: string | undefined): string[] | undefined;
|
|
217
|
+
export declare const isHeaderName: (name: string) => boolean;
|
|
218
|
+
/** Compare a prototype's calls with what the estate and the vendors serve. */
|
|
219
|
+
export declare function comparePrototype(input: ComparePrototypeInput): PrototypeComparison;
|
|
220
|
+
/**
|
|
221
|
+
* The calls nothing in the estate serves, for the architecture stage (ADR 0142): a section of the
|
|
222
|
+
* attached comparison, each call with what it sends and reads, cited. Where each goes is that
|
|
223
|
+
* stage's to decide, so the footprint gains nothing from them; the stage reads this section back
|
|
224
|
+
* (`readPrototypeArchitecture`) and is told to place each one. Empty when nothing is new.
|
|
225
|
+
*/
|
|
226
|
+
export declare function prototypeArchitectureSection(c: PrototypeComparison,
|
|
227
|
+
/** The prototype's facts, for the fields each call carries. */
|
|
228
|
+
facts: readonly Fact[]): string[];
|
|
229
|
+
/**
|
|
230
|
+
* The calls an attached comparison lists for the architecture stage, as written (with the
|
|
231
|
+
* `[file:line]` an attached file's read text puts before each line, when it has one).
|
|
232
|
+
*/
|
|
233
|
+
export declare function readPrototypeArchitecture(text: string): string[];
|
|
234
|
+
export {};
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
import { type FactEnd, type JoinRepo } from "./facts-join.js";
|
|
2
|
+
/**
|
|
3
|
+
* A gateway's forwarding calls matched to the vendor operations they reach (ADR 0130). The facts
|
|
4
|
+
* join (ADR 0124, A-gateway) follows a call through a gateway to whatever in the estate answers;
|
|
5
|
+
* a forwarding call to a vendor's host has nothing in the estate behind it, so the join stops
|
|
6
|
+
* there. This reads the other side: the vendor's published operations (intake reads them from
|
|
7
|
+
* its spec in inputs/), and for each forwarding call of a gateway route, the one operation it
|
|
8
|
+
* reaches by method and path, path parameters normalised.
|
|
9
|
+
*
|
|
10
|
+
* Which vendor a call goes to is read, in order, from: a person's answer naming the vendor; the
|
|
11
|
+
* call's `to`; its host, or the hosts the config facts its base names give (an Apigee
|
|
12
|
+
* TargetServer per environment), matched to a host the vendor's spec lists, else to the vendor's
|
|
13
|
+
* name written in a host label (api.northwindpay.example → Northwind Pay), as the merge does.
|
|
14
|
+
* A call whose host no vendor claims is left alone: it is the join's, never guessed.
|
|
15
|
+
*
|
|
16
|
+
* Then the operation: the vendor's operations of the same method whose path, with the spec's
|
|
17
|
+
* server path in front or without it, has the call's shape. One is a match; none is a gap (the
|
|
18
|
+
* vendor's spec doesn't publish what the gateway forwards); two or more equally good is a
|
|
19
|
+
* question. Pure and deterministic: the same facts, answers and operations give the same result,
|
|
20
|
+
* whatever order they come in.
|
|
21
|
+
*/
|
|
22
|
+
/** One operation a vendor publishes, as intake reads it from the vendor's spec. */
|
|
23
|
+
export interface JoinVendorOperation {
|
|
24
|
+
/** The catalog Endpoint id of the operation. */
|
|
25
|
+
id: string;
|
|
26
|
+
method: string;
|
|
27
|
+
/** The path as the spec writes it (Swagger 2's basePath in front). */
|
|
28
|
+
path: string;
|
|
29
|
+
/** The path with the spec's server path in front (OpenAPI 3 `servers`), when it has one. */
|
|
30
|
+
fullPath?: string;
|
|
31
|
+
/** spec path:line of the operation. */
|
|
32
|
+
cite?: string;
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* A vendor, or any other system outside the estate that publishes a spec (O2: another team's,
|
|
36
|
+
* boundary `internal`), and what the join needs to find its calls: its names, its hosts and its
|
|
37
|
+
* operations.
|
|
38
|
+
*/
|
|
39
|
+
export interface JoinVendor {
|
|
40
|
+
/** The org pack's system id: a vendor's, or another outside system's. */
|
|
41
|
+
system: string;
|
|
42
|
+
/**
|
|
43
|
+
* The system's boundary in the profile. `internal` (another team's system, ADR 0142): the
|
|
44
|
+
* estate's services call it themselves, not through the external gateway, so a service's own
|
|
45
|
+
* call to it is matched too (`direct` on the match). Left out, or `vendor`: only a gateway's
|
|
46
|
+
* forwarding calls are matched, as ADR 0130 says.
|
|
47
|
+
*/
|
|
48
|
+
boundary?: "vendor" | "internal";
|
|
49
|
+
/** Its name and aliases, as the org pack writes them. */
|
|
50
|
+
names: readonly string[];
|
|
51
|
+
/** The hosts its spec's servers name, and any host the org pack gives it (patterns allowed). */
|
|
52
|
+
hosts: readonly string[];
|
|
53
|
+
operations: readonly JoinVendorOperation[];
|
|
54
|
+
}
|
|
55
|
+
/** How the vendor was found: a person's `answer`, the call's `to` (`named`), or its `host`. */
|
|
56
|
+
export type VendorJoinHow = "answer" | "named" | "host";
|
|
57
|
+
export interface VendorCallMatch {
|
|
58
|
+
/** The gateway's forwarding call. */
|
|
59
|
+
call: FactEnd;
|
|
60
|
+
/** The route (entry) the forwarding call is under. */
|
|
61
|
+
route?: FactEnd;
|
|
62
|
+
/** The config fact (a TargetServer) that ties the call to the vendor's host. */
|
|
63
|
+
tie?: FactEnd;
|
|
64
|
+
vendor: string;
|
|
65
|
+
how: VendorJoinHow;
|
|
66
|
+
/** The vendor operation's Endpoint id. */
|
|
67
|
+
operation: string;
|
|
68
|
+
method?: string;
|
|
69
|
+
/** The path the gateway forwards to. */
|
|
70
|
+
path: string;
|
|
71
|
+
/**
|
|
72
|
+
* ADR 0142: a service's own call to another team's system, not a gateway's forwarding call;
|
|
73
|
+
* `route` is then the entry the call is made under, when it names one.
|
|
74
|
+
*/
|
|
75
|
+
direct?: true;
|
|
76
|
+
}
|
|
77
|
+
/** A forwarding call to an operation the vendor's spec doesn't publish. */
|
|
78
|
+
export interface VendorCallGap {
|
|
79
|
+
call: FactEnd;
|
|
80
|
+
route?: FactEnd;
|
|
81
|
+
tie?: FactEnd;
|
|
82
|
+
vendor: string;
|
|
83
|
+
method?: string;
|
|
84
|
+
path: string;
|
|
85
|
+
message: string;
|
|
86
|
+
}
|
|
87
|
+
/** A forwarding call two or more of the vendor's operations answer equally well. */
|
|
88
|
+
export interface VendorCallAsk {
|
|
89
|
+
call: FactEnd;
|
|
90
|
+
route?: FactEnd;
|
|
91
|
+
vendor: string;
|
|
92
|
+
question: string;
|
|
93
|
+
/** The operations' Endpoint ids, sorted. */
|
|
94
|
+
candidates: string[];
|
|
95
|
+
}
|
|
96
|
+
export interface VendorJoinResult {
|
|
97
|
+
matches: VendorCallMatch[];
|
|
98
|
+
gaps: VendorCallGap[];
|
|
99
|
+
asks: VendorCallAsk[];
|
|
100
|
+
}
|
|
101
|
+
export interface JoinVendorOperationsInput {
|
|
102
|
+
repos: readonly JoinRepo[];
|
|
103
|
+
vendors: readonly JoinVendor[];
|
|
104
|
+
/** A person's answer naming the repo or system a call goes to: repo → call fact id → name. */
|
|
105
|
+
targets?: Readonly<Record<string, Readonly<Record<string, string>>>>;
|
|
106
|
+
/** The gateway bundle folders, as given to `joinFacts` (ADR 0147). */
|
|
107
|
+
bundleFolders?: readonly string[];
|
|
108
|
+
}
|
|
109
|
+
/** Match every gateway forwarding call that goes to a vendor to the vendor operation it reaches. */
|
|
110
|
+
export declare function joinVendorOperations(input: JoinVendorOperationsInput): VendorJoinResult;
|