@maycombhq/sdk 2.0.0-beta.1 → 2.0.0-beta.2

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.
Files changed (87) hide show
  1. package/{dist → npm}/cache.d.ts +1 -1
  2. package/npm/core/api.d.ts +6098 -0
  3. package/npm/core/assistant-actor.d.ts +15 -0
  4. package/npm/core/branches.d.ts +21 -0
  5. package/npm/core/cancel.d.ts +9 -0
  6. package/npm/core/catalog.d.ts +4733 -0
  7. package/npm/core/change-types-migrate.d.ts +10 -0
  8. package/npm/core/cite.d.ts +54 -0
  9. package/npm/core/curated.d.ts +37 -0
  10. package/npm/core/facts-callers.d.ts +150 -0
  11. package/npm/core/facts-carry.d.ts +36 -0
  12. package/npm/core/facts-join-prototype.d.ts +177 -0
  13. package/npm/core/facts-join-vendor.d.ts +92 -0
  14. package/npm/core/facts-join.d.ts +256 -0
  15. package/npm/core/facts.d.ts +94 -0
  16. package/npm/core/fs.d.ts +47 -0
  17. package/npm/core/gates-migrate.d.ts +10 -0
  18. package/npm/core/host-questions.d.ts +24 -0
  19. package/npm/core/identity.d.ts +17 -0
  20. package/npm/core/index.d.ts +62 -0
  21. package/npm/core/json-schema.d.ts +20 -0
  22. package/npm/core/judgments.d.ts +63 -0
  23. package/npm/core/light.d.ts +8 -0
  24. package/npm/core/log.d.ts +49 -0
  25. package/npm/core/manifest-edit.d.ts +48 -0
  26. package/npm/core/merge.d.ts +78 -0
  27. package/npm/core/metarepo.d.ts +83 -0
  28. package/npm/core/migrate.d.ts +31 -0
  29. package/npm/core/migration-files.d.ts +13 -0
  30. package/npm/core/orgpack-defaults.d.ts +194 -0
  31. package/npm/core/orgpack-load.d.ts +86 -0
  32. package/npm/core/questions.d.ts +267 -0
  33. package/npm/core/record-cache.d.ts +52 -0
  34. package/npm/core/refs.d.ts +9 -0
  35. package/npm/core/repo-description.d.ts +44 -0
  36. package/npm/core/runtime-migrate.d.ts +11 -0
  37. package/npm/core/schema/ai.d.ts +397 -0
  38. package/npm/core/schema/change.d.ts +244 -0
  39. package/npm/core/schema/common.d.ts +135 -0
  40. package/npm/core/schema/dialect.d.ts +801 -0
  41. package/npm/core/schema/executors.d.ts +396 -0
  42. package/npm/core/schema/fact-corrections.d.ts +55 -0
  43. package/npm/core/schema/facts.d.ts +1476 -0
  44. package/npm/core/schema/frameworks.d.ts +371 -0
  45. package/npm/core/schema/judgment.d.ts +77 -0
  46. package/npm/core/schema/kinds.d.ts +5166 -0
  47. package/npm/core/schema/layout.d.ts +25 -0
  48. package/npm/core/schema/orgpack.d.ts +1167 -0
  49. package/npm/core/schema/plugin.d.ts +73 -0
  50. package/npm/core/schema/question.d.ts +152 -0
  51. package/npm/core/schema/repo-type.d.ts +109 -0
  52. package/npm/core/schema/review.d.ts +558 -0
  53. package/npm/core/schema/scan-settings.d.ts +34 -0
  54. package/npm/core/schema/scan-verify.d.ts +535 -0
  55. package/npm/core/schema/spec.d.ts +269 -0
  56. package/npm/core/schema/version.d.ts +9 -0
  57. package/npm/core/schema/workspace.d.ts +312 -0
  58. package/npm/core/serialize.d.ts +17 -0
  59. package/npm/core/sources-migrate.d.ts +15 -0
  60. package/npm/core/specs.d.ts +66 -0
  61. package/npm/core/tar-read.d.ts +13 -0
  62. package/npm/core/template.d.ts +101 -0
  63. package/npm/core/words.d.ts +13 -0
  64. package/npm/core/zip-read.d.ts +37 -0
  65. package/npm/core/zip.d.ts +13 -0
  66. package/npm/index.js +8892 -0
  67. package/{dist → npm}/plugin.d.ts +1 -1
  68. package/{dist → npm}/runner.d.ts +1 -1
  69. package/package.json +10 -11
  70. package/dist/cache.js +0 -115
  71. package/dist/cache.js.map +0 -1
  72. package/dist/fs-repo.js +0 -120
  73. package/dist/fs-repo.js.map +0 -1
  74. package/dist/index.js +0 -7
  75. package/dist/index.js.map +0 -1
  76. package/dist/parse-cache.js +0 -275
  77. package/dist/parse-cache.js.map +0 -1
  78. package/dist/plugin.js +0 -85
  79. package/dist/plugin.js.map +0 -1
  80. package/dist/runner.js +0 -209
  81. package/dist/runner.js.map +0 -1
  82. package/dist/sandbox.js +0 -443
  83. package/dist/sandbox.js.map +0 -1
  84. /package/{dist → npm}/fs-repo.d.ts +0 -0
  85. /package/{dist → npm}/index.d.ts +0 -0
  86. /package/{dist → npm}/parse-cache.d.ts +0 -0
  87. /package/{dist → npm}/sandbox.d.ts +0 -0
@@ -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,150 @@
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
+ }
123
+ /** Every call a person declared in the org pack's profiles, one per route or identity named. */
124
+ export declare function declaredCallsOf(profiles: readonly {
125
+ platform: string;
126
+ profile?: Profile;
127
+ }[]): DeclaredCallInput[];
128
+ /** Who each gateway route of the estate lets in, and the chain from each declared caller. */
129
+ export declare function joinCallers(input: JoinCallersInput): CallersResult;
130
+ /** A chain in one line: `Harbor Desk (declared; app harbor-desk-portal) → edge-gateway … → …`. */
131
+ export declare function chainText(c: CallerChain): string;
132
+ /**
133
+ * The flag on a declared caller's Interface (A-callers): the person's word, made again from the
134
+ * profile whenever the gateway is written, never kept on its own.
135
+ */
136
+ export declare const DECLARED_CALLER = "declared-caller";
137
+ /**
138
+ * The callers as C1 records, for the routes of `repos` (the gateway repos being written): one
139
+ * AccessGrant per consumer a route names (its subject the identity, its resource the route's
140
+ * GatewayRoute, the route's scopes, cited on the line that names it; `flags` say which kind of
141
+ * identity it is), a GatewayRoute for a route no scanned call reaches (as `joinRecords` writes
142
+ * one for a route a call goes through, with the API product a route belongs to as `product`),
143
+ * and one Interface per declared caller: from the declared System to where the route forwards,
144
+ * `via: gateway` through the route, `asserted`, its evidence the person's word (`manual`) beside
145
+ * the route's line and the consumer line it links to. C1 as it is: no schema change.
146
+ */
147
+ export declare function callerRecords(result: CallersResult, repos: readonly JoinRepo[], join: FactsJoinResult, o?: {
148
+ only?: readonly string[];
149
+ existing?: readonly CatalogRecord[];
150
+ }): 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,177 @@
1
+ import { type FactEnd, type JoinHow, 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
+ /** spec path:line of the property. */
59
+ at?: string;
60
+ }
61
+ export interface PrototypeVendorOperation extends JoinVendorOperation {
62
+ auth?: string;
63
+ scopes?: readonly string[];
64
+ fields?: readonly PrototypeVendorField[];
65
+ }
66
+ /** A vendor with its published operations and their fields (ADR 0130's reading of its spec). */
67
+ export interface PrototypeVendor extends JoinVendor {
68
+ operations: readonly PrototypeVendorOperation[];
69
+ }
70
+ export type PrototypeDifferenceKind = "field-missing" | "field-type" | "field-required" | "scope-missing" | "auth";
71
+ /** One way the estate (or the vendor) serves an operation other than as the prototype needs. */
72
+ export interface PrototypeDifference {
73
+ kind: PrototypeDifferenceKind;
74
+ side?: "request" | "response";
75
+ field?: string;
76
+ scope?: string;
77
+ /** What the prototype says, and the line it says it on. */
78
+ prototype: {
79
+ value: string;
80
+ at: string;
81
+ };
82
+ /** What the estate says, when it says something. */
83
+ estate?: {
84
+ value: string;
85
+ at: string;
86
+ };
87
+ message: string;
88
+ }
89
+ /** One call of the prototype, placed. */
90
+ export interface PrototypeCall {
91
+ /** `<leg>.<method>-<path>`, stable. */
92
+ id: string;
93
+ leg: PrototypeLeg;
94
+ group: PrototypeGroup;
95
+ method?: string;
96
+ path: string;
97
+ /** The prototype's call. */
98
+ call: FactEnd;
99
+ /** The prototype's entry it lands on: the BFF's route, or the mock. */
100
+ lands: FactEnd;
101
+ /** The auth and scopes the prototype's sign-on gives the route (a BFF route only). */
102
+ auth?: string;
103
+ scopes?: string[];
104
+ /** What in the estate serves it (exists, changes). */
105
+ estate?: {
106
+ entry: FactEnd;
107
+ /** The Endpoint the estate's entry projects to. */
108
+ endpoint: string;
109
+ how: JoinHow;
110
+ /** The gateway routes the estate join went through to reach the entry, in order. */
111
+ gateway?: string[];
112
+ auth?: string;
113
+ scopes?: string[];
114
+ };
115
+ /** The vendor operation that alone provides it (vendor). */
116
+ vendor?: {
117
+ system: string;
118
+ name: string;
119
+ operation: string;
120
+ method: string;
121
+ path: string;
122
+ at?: string;
123
+ /** The estate's repos that forward to this vendor already: where the new route goes. */
124
+ through: string[];
125
+ };
126
+ /** Two or more estate entries serve it equally well: a person says which. */
127
+ candidates?: FactEnd[];
128
+ differences: PrototypeDifference[];
129
+ sentence: string;
130
+ }
131
+ export interface PrototypeComparison {
132
+ prototype: string;
133
+ counts: Record<PrototypeGroup, number>;
134
+ calls: PrototypeCall[];
135
+ /** The estate repos the change modifies: those serving a call that changes, and the proxies a vendor call needs. */
136
+ repos: string[];
137
+ /** The estate repos that serve calls as they are. */
138
+ uses: string[];
139
+ /** The estate Endpoints that change. */
140
+ endpoints: string[];
141
+ /** The vendor operations the prototype needs routed. */
142
+ vendorOperations: string[];
143
+ vendors: string[];
144
+ /** Calls that land on nothing in the prototype (a sign-on server's keys, say): not compared. */
145
+ left: {
146
+ call: FactEnd;
147
+ why: string;
148
+ }[];
149
+ }
150
+ export interface ComparePrototypeInput {
151
+ /** The prototype's verified facts. */
152
+ prototype: JoinRepo;
153
+ /** The estate's repos as the join reads them; no prototype among them. */
154
+ estate: readonly JoinRepo[];
155
+ /** The vendors whose specs are in inputs/. */
156
+ vendors?: readonly PrototypeVendor[];
157
+ /** The org pack's outside systems (vendors' ids and names), as the estate join takes them. */
158
+ outside?: readonly string[];
159
+ }
160
+ /** The words of the comparison, in one place: the CLI, the attached document and the app say these. */
161
+ export declare const PROTOTYPE_WORDS: {
162
+ leg: Record<PrototypeLeg, string>;
163
+ exists: (what: string, who: string, repo: string, served: string, at: string) => string;
164
+ changes: (what: string, who: string, repo: string, served: string, at: string, n: number) => string;
165
+ ambiguous: (what: string, who: string, n: number) => string;
166
+ new: (what: string, who: string) => string;
167
+ vendor: (what: string, who: string, name: string, op: string, at: string, through: string[]) => string;
168
+ fieldMissing: (side: string, name: string, at: string, repo: string) => string;
169
+ fieldType: (side: string, name: string, mine: string, at: string, repo: string, theirs: string, raw: string, theirAt: string) => string;
170
+ fieldRequired: (side: string, name: string, mine: boolean, at: string, repo: string, theirAt: string) => string;
171
+ scopeMissing: (scope: string, at: string, repo: string, theirs: string[]) => string;
172
+ auth: (mine: string, at: string, repo: string, theirs: string, theirAt: string) => string;
173
+ left: (what: string, who: string) => string;
174
+ };
175
+ /** Compare a prototype's calls with what the estate and the vendors serve. */
176
+ export declare function comparePrototype(input: ComparePrototypeInput): PrototypeComparison;
177
+ export {};
@@ -0,0 +1,92 @@
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
+ /** A vendor and what the join needs to find its calls: its names, its hosts and its operations. */
35
+ export interface JoinVendor {
36
+ /** The org pack's system id (boundary vendor). */
37
+ system: string;
38
+ /** Its name and aliases, as the org pack writes them. */
39
+ names: readonly string[];
40
+ /** The hosts its spec's servers name, and any host the org pack gives it (patterns allowed). */
41
+ hosts: readonly string[];
42
+ operations: readonly JoinVendorOperation[];
43
+ }
44
+ /** How the vendor was found: a person's `answer`, the call's `to` (`named`), or its `host`. */
45
+ export type VendorJoinHow = "answer" | "named" | "host";
46
+ export interface VendorCallMatch {
47
+ /** The gateway's forwarding call. */
48
+ call: FactEnd;
49
+ /** The route (entry) the forwarding call is under. */
50
+ route?: FactEnd;
51
+ /** The config fact (a TargetServer) that ties the call to the vendor's host. */
52
+ tie?: FactEnd;
53
+ vendor: string;
54
+ how: VendorJoinHow;
55
+ /** The vendor operation's Endpoint id. */
56
+ operation: string;
57
+ method?: string;
58
+ /** The path the gateway forwards to. */
59
+ path: string;
60
+ }
61
+ /** A forwarding call to an operation the vendor's spec doesn't publish. */
62
+ export interface VendorCallGap {
63
+ call: FactEnd;
64
+ route?: FactEnd;
65
+ tie?: FactEnd;
66
+ vendor: string;
67
+ method?: string;
68
+ path: string;
69
+ message: string;
70
+ }
71
+ /** A forwarding call two or more of the vendor's operations answer equally well. */
72
+ export interface VendorCallAsk {
73
+ call: FactEnd;
74
+ route?: FactEnd;
75
+ vendor: string;
76
+ question: string;
77
+ /** The operations' Endpoint ids, sorted. */
78
+ candidates: string[];
79
+ }
80
+ export interface VendorJoinResult {
81
+ matches: VendorCallMatch[];
82
+ gaps: VendorCallGap[];
83
+ asks: VendorCallAsk[];
84
+ }
85
+ export interface JoinVendorOperationsInput {
86
+ repos: readonly JoinRepo[];
87
+ vendors: readonly JoinVendor[];
88
+ /** A person's answer naming the repo or system a call goes to: repo → call fact id → name. */
89
+ targets?: Readonly<Record<string, Readonly<Record<string, string>>>>;
90
+ }
91
+ /** Match every gateway forwarding call that goes to a vendor to the vendor operation it reaches. */
92
+ export declare function joinVendorOperations(input: JoinVendorOperationsInput): VendorJoinResult;