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

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 (102) hide show
  1. package/{dist → npm}/cache.d.ts +1 -1
  2. package/npm/core/api.d.ts +7964 -0
  3. package/npm/core/assistant-actor.d.ts +15 -0
  4. package/npm/core/audit.d.ts +153 -0
  5. package/npm/core/branches.d.ts +21 -0
  6. package/npm/core/cancel.d.ts +9 -0
  7. package/npm/core/catalog.d.ts +4735 -0
  8. package/npm/core/change-types-migrate.d.ts +10 -0
  9. package/npm/core/cite.d.ts +54 -0
  10. package/npm/core/contract-check.d.ts +251 -0
  11. package/npm/core/curated.d.ts +37 -0
  12. package/npm/core/fact-paths.d.ts +14 -0
  13. package/npm/core/facts-callers.d.ts +152 -0
  14. package/npm/core/facts-carry.d.ts +36 -0
  15. package/npm/core/facts-join-prototype.d.ts +239 -0
  16. package/npm/core/facts-join-vendor.d.ts +110 -0
  17. package/npm/core/facts-join.d.ts +482 -0
  18. package/npm/core/facts-terms.d.ts +108 -0
  19. package/npm/core/facts.d.ts +94 -0
  20. package/npm/core/fs.d.ts +47 -0
  21. package/npm/core/gates-migrate.d.ts +10 -0
  22. package/npm/core/host-questions.d.ts +111 -0
  23. package/npm/core/identity.d.ts +17 -0
  24. package/npm/core/index.d.ts +77 -0
  25. package/npm/core/json-schema.d.ts +20 -0
  26. package/npm/core/judgments.d.ts +63 -0
  27. package/npm/core/light.d.ts +8 -0
  28. package/npm/core/link-evidence.d.ts +212 -0
  29. package/npm/core/log.d.ts +49 -0
  30. package/npm/core/manifest-edit.d.ts +57 -0
  31. package/npm/core/merge.d.ts +85 -0
  32. package/npm/core/metarepo.d.ts +91 -0
  33. package/npm/core/migrate.d.ts +32 -0
  34. package/npm/core/migration-files.d.ts +13 -0
  35. package/npm/core/org-notes.d.ts +180 -0
  36. package/npm/core/orgpack-defaults.d.ts +199 -0
  37. package/npm/core/orgpack-load.d.ts +102 -0
  38. package/npm/core/profile-migrate.d.ts +11 -0
  39. package/npm/core/question-order.d.ts +23 -0
  40. package/npm/core/question-owners.d.ts +53 -0
  41. package/npm/core/question-proposals.d.ts +77 -0
  42. package/npm/core/questions.d.ts +312 -0
  43. package/npm/core/record-cache.d.ts +52 -0
  44. package/npm/core/refs.d.ts +9 -0
  45. package/npm/core/repo-description.d.ts +44 -0
  46. package/npm/core/repo-reads.d.ts +44 -0
  47. package/npm/core/roles-migrate.d.ts +9 -0
  48. package/npm/core/runtime-migrate.d.ts +11 -0
  49. package/npm/core/schema/ai.d.ts +397 -0
  50. package/npm/core/schema/change.d.ts +244 -0
  51. package/npm/core/schema/common.d.ts +135 -0
  52. package/npm/core/schema/conventions.d.ts +80 -0
  53. package/npm/core/schema/dialect.d.ts +801 -0
  54. package/npm/core/schema/executors.d.ts +396 -0
  55. package/npm/core/schema/fact-corrections.d.ts +56 -0
  56. package/npm/core/schema/facts.d.ts +1773 -0
  57. package/npm/core/schema/frameworks.d.ts +371 -0
  58. package/npm/core/schema/judgment.d.ts +77 -0
  59. package/npm/core/schema/kinds.d.ts +5168 -0
  60. package/npm/core/schema/layout.d.ts +25 -0
  61. package/npm/core/schema/orgpack.d.ts +1193 -0
  62. package/npm/core/schema/plugin.d.ts +73 -0
  63. package/npm/core/schema/question.d.ts +230 -0
  64. package/npm/core/schema/repo-type.d.ts +127 -0
  65. package/npm/core/schema/review.d.ts +558 -0
  66. package/npm/core/schema/scan-settings.d.ts +34 -0
  67. package/npm/core/schema/scan-verify.d.ts +535 -0
  68. package/npm/core/schema/spec.d.ts +269 -0
  69. package/npm/core/schema/version.d.ts +10 -0
  70. package/npm/core/schema/workspace.d.ts +330 -0
  71. package/npm/core/serialize.d.ts +17 -0
  72. package/npm/core/shared-maps.d.ts +146 -0
  73. package/npm/core/sources-migrate.d.ts +15 -0
  74. package/npm/core/specs.d.ts +66 -0
  75. package/npm/core/stack-helpers.d.ts +32 -0
  76. package/npm/core/tar-read.d.ts +13 -0
  77. package/npm/core/template.d.ts +101 -0
  78. package/npm/core/words.d.ts +13 -0
  79. package/npm/core/zip-read.d.ts +37 -0
  80. package/npm/core/zip.d.ts +13 -0
  81. package/npm/index.js +10097 -0
  82. package/{dist → npm}/plugin.d.ts +1 -1
  83. package/{dist → npm}/runner.d.ts +1 -1
  84. package/package.json +10 -11
  85. package/dist/cache.js +0 -115
  86. package/dist/cache.js.map +0 -1
  87. package/dist/fs-repo.js +0 -120
  88. package/dist/fs-repo.js.map +0 -1
  89. package/dist/index.js +0 -7
  90. package/dist/index.js.map +0 -1
  91. package/dist/parse-cache.js +0 -275
  92. package/dist/parse-cache.js.map +0 -1
  93. package/dist/plugin.js +0 -85
  94. package/dist/plugin.js.map +0 -1
  95. package/dist/runner.js +0 -209
  96. package/dist/runner.js.map +0 -1
  97. package/dist/sandbox.js +0 -443
  98. package/dist/sandbox.js.map +0 -1
  99. /package/{dist → npm}/fs-repo.d.ts +0 -0
  100. /package/{dist → npm}/index.d.ts +0 -0
  101. /package/{dist → npm}/parse-cache.d.ts +0 -0
  102. /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,251 @@
1
+ import { z } from "zod";
2
+ import type { FactEnd, FactsJoinResult } from "./facts-join.js";
3
+ import type { VendorCallMatch } from "./facts-join-vendor.js";
4
+ import type { Fact } from "./schema/facts.js";
5
+ /** A field a spec lists: a request or response property or parameter, or a message's field. */
6
+ export declare const SpecField: z.ZodObject<{
7
+ side: z.ZodEnum<{
8
+ message: "message";
9
+ request: "request";
10
+ response: "response";
11
+ }>;
12
+ name: z.ZodString;
13
+ type: z.ZodOptional<z.ZodString>;
14
+ required: z.ZodOptional<z.ZodBoolean>;
15
+ in: z.ZodOptional<z.ZodString>;
16
+ number: z.ZodOptional<z.ZodNumber>;
17
+ at: z.ZodString;
18
+ }, z.core.$strict>;
19
+ export type SpecFieldT = z.infer<typeof SpecField>;
20
+ export declare const SPEC_FORMATS: readonly ["openapi", "protobuf", "avro", "json-schema", "asyncapi"];
21
+ /**
22
+ * One operation or one message a spec file describes, as the contract check reads it. An
23
+ * operation has a method and a path (with the server's path in front); a message has the name
24
+ * of its type (a proto message's full name, an Avro record's, a JSON Schema's title) and, when
25
+ * the spec says (AsyncAPI), the topic it travels on.
26
+ */
27
+ export declare const ContractSpec: z.ZodObject<{
28
+ kind: z.ZodEnum<{
29
+ message: "message";
30
+ operation: "operation";
31
+ }>;
32
+ format: z.ZodEnum<{
33
+ openapi: "openapi";
34
+ "json-schema": "json-schema";
35
+ avro: "avro";
36
+ protobuf: "protobuf";
37
+ asyncapi: "asyncapi";
38
+ }>;
39
+ role: z.ZodEnum<{
40
+ schema: "schema";
41
+ consumer: "consumer";
42
+ own: "own";
43
+ }>;
44
+ file: z.ZodString;
45
+ line: z.ZodNumber;
46
+ method: z.ZodOptional<z.ZodString>;
47
+ path: z.ZodOptional<z.ZodString>;
48
+ entry: z.ZodOptional<z.ZodString>;
49
+ name: z.ZodOptional<z.ZodString>;
50
+ topic: z.ZodOptional<z.ZodString>;
51
+ id: z.ZodOptional<z.ZodString>;
52
+ fields: z.ZodArray<z.ZodObject<{
53
+ side: z.ZodEnum<{
54
+ message: "message";
55
+ request: "request";
56
+ response: "response";
57
+ }>;
58
+ name: z.ZodString;
59
+ type: z.ZodOptional<z.ZodString>;
60
+ required: z.ZodOptional<z.ZodBoolean>;
61
+ in: z.ZodOptional<z.ZodString>;
62
+ number: z.ZodOptional<z.ZodNumber>;
63
+ at: z.ZodString;
64
+ }, z.core.$strict>>;
65
+ errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
66
+ status: z.ZodString;
67
+ at: z.ZodString;
68
+ }, z.core.$strict>>>;
69
+ }, z.core.$strict>;
70
+ export type ContractSpecT = z.infer<typeof ContractSpec>;
71
+ /**
72
+ * The facts companion `<repo>.specs.yaml` (ADR 0164): the specs a repo's checkout holds, read at
73
+ * the facts' commit by `atticus verify <repo> --write`, so the contract check reads the same
74
+ * specs on every run without the checkout.
75
+ */
76
+ export declare const SpecsFile: z.ZodObject<{
77
+ schemaVersion: z.ZodLiteral<1>;
78
+ repo: z.ZodString;
79
+ commit: z.ZodOptional<z.ZodString>;
80
+ specs: z.ZodArray<z.ZodObject<{
81
+ kind: z.ZodEnum<{
82
+ message: "message";
83
+ operation: "operation";
84
+ }>;
85
+ format: z.ZodEnum<{
86
+ openapi: "openapi";
87
+ "json-schema": "json-schema";
88
+ avro: "avro";
89
+ protobuf: "protobuf";
90
+ asyncapi: "asyncapi";
91
+ }>;
92
+ role: z.ZodEnum<{
93
+ schema: "schema";
94
+ consumer: "consumer";
95
+ own: "own";
96
+ }>;
97
+ file: z.ZodString;
98
+ line: z.ZodNumber;
99
+ method: z.ZodOptional<z.ZodString>;
100
+ path: z.ZodOptional<z.ZodString>;
101
+ entry: z.ZodOptional<z.ZodString>;
102
+ name: z.ZodOptional<z.ZodString>;
103
+ topic: z.ZodOptional<z.ZodString>;
104
+ id: z.ZodOptional<z.ZodString>;
105
+ fields: z.ZodArray<z.ZodObject<{
106
+ side: z.ZodEnum<{
107
+ message: "message";
108
+ request: "request";
109
+ response: "response";
110
+ }>;
111
+ name: z.ZodString;
112
+ type: z.ZodOptional<z.ZodString>;
113
+ required: z.ZodOptional<z.ZodBoolean>;
114
+ in: z.ZodOptional<z.ZodString>;
115
+ number: z.ZodOptional<z.ZodNumber>;
116
+ at: z.ZodString;
117
+ }, z.core.$strict>>;
118
+ errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
119
+ status: z.ZodString;
120
+ at: z.ZodString;
121
+ }, z.core.$strict>>>;
122
+ }, z.core.$strict>>;
123
+ }, z.core.$strict>;
124
+ export type SpecsFileT = z.infer<typeof SpecsFile>;
125
+ /** The specs of a system outside the estate, taken in through intake (O2). */
126
+ export interface OutsideSpecs {
127
+ system: string;
128
+ name: string;
129
+ specs: readonly ContractSpecT[];
130
+ }
131
+ export declare const CONTRACT_KINDS: readonly ["field-missing", "field-extra", "field-not-sent", "field-required", "field-type", "field-number", "error-unlisted", "error-unanswered"];
132
+ export type ContractKind = (typeof CONTRACT_KINDS)[number];
133
+ /** One end of a comparison: who says it (a repo's code, a spec), the value, and its line. */
134
+ export interface ContractEnd {
135
+ /** The repo whose code or spec it is, or the outside system. */
136
+ repo?: string;
137
+ system?: string;
138
+ /** What this end is, in words: `forge-portal-bff's call`, `the spec forge-accounts-v1.yaml`. */
139
+ what: string;
140
+ value?: string;
141
+ /** path:line. */
142
+ at?: string;
143
+ }
144
+ export interface ContractMismatch {
145
+ /** Stable: the link, the boundary, the kind, the side and the field or status. */
146
+ id: string;
147
+ /** The catalog Interface of the link, when the join gives one. */
148
+ interface?: string;
149
+ /** Every Interface it concerns: the link's, and each gateway hop's forwarding call's. */
150
+ interfaces?: string[];
151
+ /** The call the link starts at (the publish, for a topic). */
152
+ call: FactEnd;
153
+ /** What it reaches: an entry of the estate, or an outside system. */
154
+ entry?: FactEnd;
155
+ system?: string;
156
+ /** `mismatch`: the two sides disagree; `unconfirmed`: a mapping on the way isn't traced. */
157
+ status: "mismatch" | "unconfirmed";
158
+ kind: ContractKind;
159
+ side?: "request" | "response" | "message";
160
+ field?: string;
161
+ error?: string;
162
+ /** The side that sends (or, for a response, reads) and the side that takes (or returns). */
163
+ sender: ContractEnd;
164
+ receiver: ContractEnd;
165
+ /** The mapping lines the comparison went through (`repo path:line`), in order. */
166
+ via?: string[];
167
+ /** The mapping that isn't traced, when `unconfirmed`. */
168
+ untraced?: string;
169
+ message: string;
170
+ }
171
+ /** A link compared: how many boundaries had something on both sides, and what was found. */
172
+ export interface ContractLink {
173
+ key: string;
174
+ interface?: string;
175
+ /** Every Interface the link's check concerns: its own, and each gateway hop's forwarding call's. */
176
+ interfaces?: string[];
177
+ call: FactEnd;
178
+ entry?: FactEnd;
179
+ system?: string;
180
+ kind: "rest" | "topic" | "outside";
181
+ method?: string;
182
+ path: string;
183
+ /** The gateway routes on the way, in order (`repo` of each). */
184
+ through: string[];
185
+ /** The specs read for it (`file:line`, the repo's or intake's). */
186
+ specs: string[];
187
+ /** Boundaries where both sides said something about the payload. */
188
+ compared: number;
189
+ mismatches: number;
190
+ unconfirmed: number;
191
+ }
192
+ export interface ContractCheckResult {
193
+ links: ContractLink[];
194
+ findings: ContractMismatch[];
195
+ counts: {
196
+ links: number;
197
+ compared: number;
198
+ mismatches: number;
199
+ unconfirmed: number;
200
+ };
201
+ }
202
+ export interface ContractCheckInput {
203
+ repos: readonly {
204
+ repo: string;
205
+ facts: readonly Fact[];
206
+ }[];
207
+ join: FactsJoinResult;
208
+ /** Every repo's `<repo>.specs.yaml` on file. */
209
+ specs?: readonly SpecsFileT[];
210
+ /** The specs of systems outside the estate, from intake. */
211
+ outside?: readonly OutsideSpecs[];
212
+ /** The calls to outside systems matched to their spec's operations (`joinVendorOperations`). */
213
+ vendorMatches?: readonly VendorCallMatch[];
214
+ }
215
+ /** The words of the check, in one place: the CLI, the API and the app say these. */
216
+ export declare const CONTRACT_WORDS: {
217
+ extra: (side: string, name: string, s: string, sAt: string, r: string) => string;
218
+ notSent: (side: string, name: string, r: string, rAt: string, s: string) => string;
219
+ missing: (name: string, s: string, sAt: string, r: string) => string;
220
+ messageMissing: (name: string, r: string, rAt: string, s: string) => string;
221
+ messageExtra: (name: string, s: string, sAt: string, r: string) => string;
222
+ undocumented: (name: string, r: string, rAt: string, s: string) => string;
223
+ required: (side: string, name: string, a: string, aAt: string, b: string, bAt: string) => string;
224
+ type: (side: string, name: string, a: string, at: string, aAt: string, b: string, bt: string, bAt: string) => string;
225
+ number: (n: number, a: string, an: string, aAt: string, b: string, bn: string, bAt: string) => string;
226
+ errorUnlisted: (status: string, r: string, rAt: string, s: string, spec: boolean) => string;
227
+ errorUnanswered: (status: string, s: string, sAt: string, r: string) => string;
228
+ unconfirmed: (message: string, untraced: string) => string;
229
+ };
230
+ /**
231
+ * The `transform` a reader gives the field fact that names a publish's or listener's message type
232
+ * (ADR 0164): the field's `name` is the type as the line writes it (`PaymentSettled`, the
233
+ * generated proto class or the Avro record), its `type` the full name when the code gives one
234
+ * (`forge.payments.v1.PaymentSettled`), cited where the publish or the listener names it. It is
235
+ * no field of the payload: it ties the payload to its spec.
236
+ */
237
+ export declare const MESSAGE_TYPE_TRANSFORM = "message type";
238
+ export declare const isMessageType: (f: {
239
+ side?: string;
240
+ transform?: string;
241
+ }) => boolean;
242
+ /** A `transform` that says the field travels inside the field it is mapped to (an envelope). */
243
+ export declare const ENVELOPE_TRANSFORM: RegExp;
244
+ /** Compare the payload on both sides of every link the join made, and of every call to an outside system with a spec. */
245
+ export declare function checkContracts(input: ContractCheckInput): ContractCheckResult;
246
+ /**
247
+ * The findings a newer spec of an outside system brings (ADR 0164): those against `next` that
248
+ * the same calls didn't have against `prev`, by kind, side and field. What the Outside systems
249
+ * page shows when a vendor's or a team's new spec is taken in.
250
+ */
251
+ export declare function newFindings(next: readonly ContractMismatch[], prev: readonly ContractMismatch[]): ContractMismatch[];
@@ -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;