@maycombhq/sdk 2.0.0-beta.3 → 2.0.0-beta.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/npm/core/ai-decisions.d.ts +373 -0
  2. package/npm/core/api.d.ts +15888 -3797
  3. package/npm/core/app-memory.d.ts +69 -0
  4. package/npm/core/assistant-actor.d.ts +28 -7
  5. package/npm/core/audit.d.ts +174 -0
  6. package/npm/core/canary.d.ts +369 -0
  7. package/npm/core/cancel.d.ts +20 -0
  8. package/npm/core/catalog.d.ts +220 -66
  9. package/npm/core/change-types-migrate.d.ts +14 -0
  10. package/npm/core/cite.d.ts +88 -6
  11. package/npm/core/contract-check.d.ts +276 -0
  12. package/npm/core/curated.d.ts +10 -0
  13. package/npm/core/decision-batches.d.ts +29 -0
  14. package/npm/core/declarable-routes.d.ts +52 -0
  15. package/npm/core/declared-links.d.ts +210 -0
  16. package/npm/core/eol.d.ts +5 -0
  17. package/npm/core/fact-paths.d.ts +14 -0
  18. package/npm/core/facts-callers.d.ts +23 -1
  19. package/npm/core/facts-carry.d.ts +8 -2
  20. package/npm/core/facts-deps.d.ts +85 -0
  21. package/npm/core/facts-join-prototype.d.ts +66 -4
  22. package/npm/core/facts-join-vendor.d.ts +67 -7
  23. package/npm/core/facts-join.d.ts +476 -2
  24. package/npm/core/facts-terms.d.ts +108 -0
  25. package/npm/core/facts.d.ts +155 -1
  26. package/npm/core/field-places.d.ts +109 -0
  27. package/npm/core/file-pool.d.ts +84 -0
  28. package/npm/core/fs.d.ts +205 -7
  29. package/npm/core/glob-plain.d.ts +34 -0
  30. package/npm/core/glob.d.ts +14 -0
  31. package/npm/core/hash-cache.d.ts +53 -0
  32. package/npm/core/host-questions.d.ts +273 -1
  33. package/npm/core/identity.d.ts +20 -8
  34. package/npm/core/index.d.ts +38 -0
  35. package/npm/core/initialisms.d.ts +62 -0
  36. package/npm/core/kept-files.d.ts +17 -0
  37. package/npm/core/light.d.ts +5 -0
  38. package/npm/core/link-candidates.d.ts +224 -0
  39. package/npm/core/link-evidence.d.ts +212 -0
  40. package/npm/core/log.d.ts +2 -0
  41. package/npm/core/manifest-edit.d.ts +83 -6
  42. package/npm/core/merge.d.ts +28 -0
  43. package/npm/core/metarepo.d.ts +26 -1
  44. package/npm/core/migrate.d.ts +3 -2
  45. package/npm/core/org-notes.d.ts +180 -0
  46. package/npm/core/orgpack-defaults.d.ts +30 -6
  47. package/npm/core/orgpack-load.d.ts +24 -0
  48. package/npm/core/paths.d.ts +23 -0
  49. package/npm/core/printer.d.ts +18 -0
  50. package/npm/core/process-trees.d.ts +109 -0
  51. package/npm/core/profile-migrate.d.ts +13 -0
  52. package/npm/core/question-order.d.ts +23 -0
  53. package/npm/core/question-owners.d.ts +57 -0
  54. package/npm/core/question-proposals.d.ts +77 -0
  55. package/npm/core/question-roles.d.ts +84 -0
  56. package/npm/core/questions.d.ts +123 -6
  57. package/npm/core/record-cache.d.ts +122 -2
  58. package/npm/core/repo-files.d.ts +66 -0
  59. package/npm/core/repo-reads.d.ts +44 -0
  60. package/npm/core/roles-migrate.d.ts +10 -0
  61. package/npm/core/run-log.d.ts +341 -0
  62. package/npm/core/runtime-migrate.d.ts +18 -0
  63. package/npm/core/schema/ai.d.ts +61 -13
  64. package/npm/core/schema/common.d.ts +32 -8
  65. package/npm/core/schema/component-type.d.ts +193 -0
  66. package/npm/core/schema/conventions.d.ts +80 -0
  67. package/npm/core/schema/dialect.d.ts +12 -12
  68. package/npm/core/schema/fact-corrections.d.ts +112 -2
  69. package/npm/core/schema/facts.d.ts +743 -23
  70. package/npm/core/schema/frameworks.d.ts +12 -12
  71. package/npm/core/schema/kinds.d.ts +230 -66
  72. package/npm/core/schema/orgpack.d.ts +248 -24
  73. package/npm/core/schema/question.d.ts +281 -5
  74. package/npm/core/schema/reading-rules.d.ts +51 -0
  75. package/npm/core/schema/repo-type.d.ts +20 -2
  76. package/npm/core/schema/review.d.ts +30 -9
  77. package/npm/core/schema/scan-verify.d.ts +77 -0
  78. package/npm/core/schema/version.d.ts +4 -1
  79. package/npm/core/schema/workspace.d.ts +29 -11
  80. package/npm/core/setup-edit.d.ts +107 -0
  81. package/npm/core/shared-maps.d.ts +146 -0
  82. package/npm/core/stack-helpers.d.ts +32 -0
  83. package/npm/core/version-order.d.ts +14 -0
  84. package/npm/fs-repo.d.ts +2 -1
  85. package/npm/index.js +14248 -6710
  86. package/npm/listing.d.ts +14 -0
  87. package/npm/sandbox.d.ts +2 -1
  88. package/package.json +1 -1
@@ -0,0 +1,108 @@
1
+ import type { CatalogRecord } from "./catalog.js";
2
+ import { type FactEnd, type FactsJoinResult, type JoinRepo } from "./facts-join.js";
3
+ import type { TermRole } from "./schema/facts.js";
4
+ /**
5
+ * The organisation's terms across the estate (ADR 0163). A `term` fact records an identifier of
6
+ * the organisation's own (a CMDB id, an application id) as a repo writes it, with the role a note
7
+ * or the file's own words give it: `owner` (the value names the repo's own system), `consumer`
8
+ * (it names a system the repo lets in), `none` or `unknown`. Atticus knows no term; it only
9
+ * compares the values the facts cite, word for word:
10
+ *
11
+ * - an owner value ties its repo to its system;
12
+ * - a consumer value points to the repo whose owner value is the same;
13
+ * - the same value in two repos that no owner and consumer explain is a possible link: inferred,
14
+ * flagged, shown for a person to confirm;
15
+ * - a repo's consumers are who its routes let in: on a gateway they become AccessGrants on its
16
+ * routes, so the critic names them when a route changes;
17
+ * - and they are checked against the calls the join found: a repo calling the routes whose owner
18
+ * value isn't listed is a finding, a listed consumer that makes no call is a note.
19
+ *
20
+ * Pure: the same facts and join give the same result.
21
+ */
22
+ /** A term as one repo writes it. */
23
+ export interface TermSeen extends FactEnd {
24
+ term: string;
25
+ value: string;
26
+ role: TermRole;
27
+ /** path:line of the line that gives it its role. */
28
+ meaningAt?: string;
29
+ /** The note's key, or its words quoted. */
30
+ note?: string;
31
+ }
32
+ /** A consumer a repo lists, and the repo whose own value it is, when one says so. */
33
+ export interface TermConsumer {
34
+ listedBy: TermSeen;
35
+ owner?: TermSeen;
36
+ }
37
+ /** The flag a possible link by a shared value carries: a guess for a person to confirm. */
38
+ export declare const LINKED_BY_TERM_VALUE = "linked-by-term-value";
39
+ /** The same value in two or more repos, which no owner and its consumers explain. */
40
+ export interface PossibleTermLink {
41
+ value: string;
42
+ seen: TermSeen[];
43
+ inferred: true;
44
+ flag: typeof LINKED_BY_TERM_VALUE;
45
+ }
46
+ /** A consumer let in to a route: an access grant, read from the route repo's term facts. */
47
+ export interface TermGrant {
48
+ route: FactEnd;
49
+ gatewayRoute: string;
50
+ consumer: TermSeen;
51
+ owner?: TermSeen;
52
+ }
53
+ /**
54
+ * What the consumers a repo lists say against the calls the join found. `caller-not-listed`: a
55
+ * repo calls its routes and none of its own values is listed (a finding); `caller-no-id`: a repo
56
+ * calls them and no fact of it names its own value, so whether it is listed is unknown (a note,
57
+ * review 12); `listed-no-call`: a listed consumer's repo is known and makes no call into them (a
58
+ * note).
59
+ */
60
+ export type TermAccessFinding = {
61
+ reason: "caller-not-listed" | "caller-no-id";
62
+ repo: string;
63
+ route: FactEnd;
64
+ call: FactEnd;
65
+ /** The caller's own values (owner terms), none of which is listed. */
66
+ callerValues: string[];
67
+ message: string;
68
+ } | {
69
+ reason: "listed-no-call";
70
+ repo: string;
71
+ consumer: TermSeen;
72
+ owner: TermSeen;
73
+ message: string;
74
+ };
75
+ export interface TermsResult {
76
+ /** Every term of the estate, by repo and fact id. */
77
+ terms: TermSeen[];
78
+ consumers: TermConsumer[];
79
+ possible: PossibleTermLink[];
80
+ grants: TermGrant[];
81
+ access: TermAccessFinding[];
82
+ }
83
+ export interface JoinTermsInput {
84
+ repos: readonly JoinRepo[];
85
+ /** The estate's join (`joinFacts`), whole: the calls into each repo's routes come from it. */
86
+ join?: FactsJoinResult;
87
+ /** The gateway bundle folders (ADR 0147), as given to `joinFacts`. */
88
+ bundleFolders?: readonly string[];
89
+ }
90
+ /** Who owns, lists and shares each value, and what the lists say against the calls. */
91
+ export declare function joinTerms(input: JoinTermsInput): TermsResult;
92
+ /** The flag a term's AccessGrant carries beside its `caller:<term>`, so it is told apart. */
93
+ export declare const termFlag: (term: string) => string;
94
+ /**
95
+ * The consumers a gateway repo's term facts list, as C1 AccessGrants on its routes (ADR 0163):
96
+ * one per consumer and route, the subject the value as written, the resource the route's
97
+ * GatewayRoute, cited on the value's line and the line giving it its role. `caller:<term>` lets
98
+ * the critic name them as a route's consumers when the route changes, as it names a route's own
99
+ * callers (A-callers). C1 as it is: no schema change.
100
+ */
101
+ export declare function termGrantRecords(result: TermsResult, repos: readonly JoinRepo[], o?: {
102
+ only?: readonly string[];
103
+ }): CatalogRecord[];
104
+ /**
105
+ * The flag an owner term gives its repo's Component (ADR 0163): `term:<term>=<value>`, the
106
+ * identifier the organisation knows the system by. `flags` is C1's existing optional field.
107
+ */
108
+ export declare const ownerTermFlag: (term: string, value: string) => string;
@@ -1,3 +1,4 @@
1
+ import { z } from "zod";
1
2
  import type { CatalogRecord } from "./catalog.js";
2
3
  import { Fact, type FactOf } from "./schema/facts.js";
3
4
  /**
@@ -14,14 +15,74 @@ export interface FactIssue {
14
15
  code: string;
15
16
  message: string;
16
17
  }
18
+ /**
19
+ * A fact of a kind this Atticus doesn't know (beta.25, ADR 0192 addendum): a newer Atticus wrote
20
+ * it. It is left out of what is read, and said, rather than refusing the whole file; whoever
21
+ * writes the file back must keep it (or not write), since it is a teammate's fact.
22
+ */
23
+ export interface NewerFact {
24
+ line?: number;
25
+ factId: string;
26
+ kind: string;
27
+ message: string;
28
+ /** The line as written (a line-by-line read), for a writer to keep it as it is. */
29
+ raw?: string;
30
+ }
17
31
  export type ParseFactsResult = {
18
32
  ok: true;
19
33
  facts: Fact[];
34
+ /** Beta.25: the facts of kinds a newer Atticus wrote, left out of `facts`. */
35
+ newer?: NewerFact[];
20
36
  } | {
21
37
  ok: false;
22
38
  issues: FactIssue[];
23
39
  };
40
+ /** A JSON value that is a fact of a kind this Atticus doesn't know, said as one; else undefined. */
41
+ export declare function newerFactOf(json: unknown, line?: number): NewerFact | undefined;
42
+ /**
43
+ * Review of beta.25: a fact of a kind this Atticus knows that a newer Atticus wrote: every reason
44
+ * it doesn't read is a field this Atticus doesn't know (a name as Atticus writes them, never a
45
+ * slip of one the kind has: `nearFieldOf`) or a value of one of its lists it doesn't know (a
46
+ * lowercase word more than two edits from each of the list's values, as `scope: "shaded"`; never
47
+ * `scope: "system"`, which is recorded as provided). Said as such, so the fact is left out on its
48
+ * own and kept as written; anything else wrong is a wrong fact, refused for the assistant to fix.
49
+ */
50
+ export declare function newerShapeOf(json: unknown, issues: readonly z.core.$ZodIssue[], line?: number): NewerFact | undefined;
51
+ /**
52
+ * ADR 0205 step 3: a facts file is parsed once for its bytes. Each parse is kept, serialized
53
+ * (`v8.serialize`, which keeps -0 and fields set to undefined), by the SHA-256 of the text, in
54
+ * this process (a bounded memo) and, where a build installed one, in the build cache's store on
55
+ * disk; a text with the same bytes is the same parse, handed back as a fresh copy.
56
+ */
57
+ export declare const factsParseHooks: {
58
+ /** The way before step 3: every text parsed. */
59
+ off?: boolean;
60
+ /** The equivalence tests: each kept parse checked against a parse of the text, or a throw. */
61
+ check?: boolean;
62
+ /** The build cache's store on disk, by the text's hash (installed by the scanner). */
63
+ store?: {
64
+ get(textSha: string): Uint8Array | undefined;
65
+ put(textSha: string, kept: Uint8Array): void;
66
+ /** A parse of this text was used from the memo: the store keeps its copy. */
67
+ used(textSha: string): void;
68
+ };
69
+ };
70
+ /** How often a kept parse was used, and a text parsed (the tests). */
71
+ export declare const factsParseStats: {
72
+ kept: number;
73
+ parsed: number;
74
+ };
75
+ /** Forget this process's kept parses (a test of the store on disk; a server letting memory go). */
76
+ export declare function forgetFactsParses(): void;
24
77
  export declare function parseFacts(text: string): ParseFactsResult;
78
+ /**
79
+ * A facts file's line as it may be kept where people read it (`<repo>.rejected.jsonl`), beta.25
80
+ * review: a config fact any of whose fields carries a secret (`configSecretField`, beta.24's value
81
+ * check included, or a quote `redactSecrets` changes) has its value, source, parts and quote
82
+ * redacted, the rest kept as written. A line that isn't JSON is redacted as a line of code is,
83
+ * and any quoted literal that reads as a credential goes too. Anything else is kept as it is.
84
+ */
85
+ export declare function redactFactLine(raw: string): string;
25
86
  /** A line of a facts file that isn't a fact, with its number, its text and what is wrong. */
26
87
  export type BadFactLine = {
27
88
  line: number;
@@ -37,6 +98,7 @@ export type BadFactLine = {
37
98
  export declare function parseFactLine(raw: string, line: number, seen: Set<string>): {
38
99
  fact?: Fact;
39
100
  bad?: BadFactLine;
101
+ newer?: NewerFact;
40
102
  };
41
103
  /**
42
104
  * Read a JSONL facts file line by line, keeping every line that reads and returning the others
@@ -49,6 +111,8 @@ export declare function parseFactLine(raw: string, line: number, seen: Set<strin
49
111
  export declare function parseFactsLines(text: string): {
50
112
  facts: Fact[];
51
113
  bad: BadFactLine[];
114
+ /** Beta.25: facts of kinds a newer Atticus wrote, left out of `facts` (`newerFactOf`). */
115
+ newer: NewerFact[];
52
116
  };
53
117
  /** One canonical JSON line per fact, sorted by id; the same facts give the same bytes. */
54
118
  export declare function serializeFacts(facts: readonly Fact[]): string;
@@ -69,8 +133,97 @@ export interface ProjectResult {
69
133
  }
70
134
  /** A name as a part of a projected catalog id: its slug, with dots made dashes (a component, a store). */
71
135
  export declare const factIdPart: (text: string) => string;
136
+ /**
137
+ * ADR 0124 addendum E-ids (the owner, 2026-11-19): the id of the loose end a fact leaves,
138
+ * `unresolved.<repo>.<rest>`, the repo as the other ids name it (`factIdPart`, as a component
139
+ * named for its repo is), so the same fact id in two repos is two records. `rest` is the call's
140
+ * fact id (`factIdPart`), or a listener's Endpoint id (`<component>.<name>`).
141
+ */
142
+ export declare const unresolvedIdOf: (repo: string, rest: string) => string;
143
+ /**
144
+ * The second whole-release review of beta.30: another repo id among `ids` that names the same
145
+ * loose-end id as `id` (`forge.api` and `forge-api`), so the map couldn't tell their loose ends
146
+ * apart. The id scheme is C1's and stays: two such repo ids are refused where a repo id is written.
147
+ */
148
+ export declare function repoIdTwinOf(id: string, ids: Iterable<string>): string | undefined;
149
+ /**
150
+ * A twin pair in the one order every place says it (the review of b30/review2-fixes): sorted by
151
+ * cmpText, so doctor, the stages, a build, a scan, selfcheck and GET /api/build name the pair
152
+ * alike and suggest renaming the same repo, the second.
153
+ */
154
+ export declare const repoIdTwinPair: (x: string, y: string) => [string, string];
155
+ /** Why two repo ids can't both be: the words every refusal of repoIdTwinOf's pair starts with. */
156
+ export declare const repoIdTwinWords: (x: string, y: string) => string;
157
+ /** A pair of repo ids that name one loose-end id, and the way on: rename the second (repoIdTwinPair). */
158
+ export declare const repoIdTwinWarning: (x: string, y: string) => string;
159
+ /**
160
+ * Every pair of repo ids that name one loose-end id, whatever order they are listed in: for each
161
+ * loose-end id, its repo ids sorted (cmpText), the first with each of the others, the pairs
162
+ * sorted. What a merge of two pull requests, or a hand edit, can leave on disk past the refusals
163
+ * where an id is written (doctor, selfcheck, a build, the stages).
164
+ */
165
+ export declare function repoIdTwins(ids: Iterable<string>): [string, string][];
166
+ /**
167
+ * ADR 0124 addendum E-ids: an Unresolved record the facts projection made, by the id each repo's
168
+ * own record has now, once per repo its evidence names, sorted. Before beta.30 the id carried no
169
+ * repo (`unresolved.<fact id>`, `unresolved.<component>.<name>` for a listener), so two repos'
170
+ * loose ends with one fact id were one record citing one of them; such an id is named again with
171
+ * each repo its evidence names. A record of the new form gives its own id. Told apart by shape,
172
+ * which is unambiguous: a call's fact id part and an Endpoint's name have no dot (`factIdPart`).
173
+ * Anything else (a built-in reader's loose end, `<owner>.<kind>.<hash>`; no repo): none.
174
+ */
175
+ export declare function unresolvedIdsNow(r: {
176
+ kind: string;
177
+ id: string;
178
+ unresolvedKind?: unknown;
179
+ owner?: unknown;
180
+ evidence?: readonly {
181
+ repo?: string | undefined;
182
+ }[];
183
+ }): string[];
184
+ /**
185
+ * ADR 0124 addendum E-ids: whether an id, with no record to tell by, is a loose end's id of the
186
+ * form before beta.30: a call's `unresolved.<fact id>` (no dot after it), or a listener's
187
+ * `unresolved.<component>.on-<topic>` (one dot, then an event Endpoint's name). For words only;
188
+ * `unresolvedIdsNow` tells a record's for sure.
189
+ */
190
+ export declare function oldLooseEndId(id: string): boolean;
191
+ /**
192
+ * ADR 0124 addendum E-ids (the review of 5cc4ce87, I1): whether an id, with no record to tell
193
+ * by, may be a loose end's id of the form before beta.30, given the repos' id parts
194
+ * (`factIdPart` of each repo): what `oldLooseEndId` reads, or a listener of a component whose id
195
+ * has a dot (`unresolved.forge.ledger.on-x`), whose first part is no repo's (under a repo's id,
196
+ * the same shape is the new form).
197
+ */
198
+ export declare function mayBeOldLooseEndId(id: string, repoParts: ReadonlySet<string>): boolean;
199
+ /**
200
+ * ADR 0124 addendum E-ids: the id a loose end of the new form (`unresolved.<repo>.<rest>`) had
201
+ * before beta.30 (`unresolved.<rest>`); undefined for a record of any other form.
202
+ */
203
+ export declare function oldIdOfLooseEnd(r: Parameters<typeof unresolvedIdsNow>[0]): string | undefined;
72
204
  /** The Endpoint id an entry fact projects to in its component (`projectFacts`). */
73
205
  export declare function entryEndpointId(f: FactOf<"entry">, component: string): string;
206
+ /**
207
+ * The component a fact is placed in that names one its repo's manifest doesn't have (review of
208
+ * beta.25, ADR 0192 addendum §2): a repo whose manifest entry lists no modules ships as its one
209
+ * component, so a fact (an entry, a call, a store, any but a build's coordinates, which the
210
+ * verifier refuses instead) naming a component that is neither the repo's own nor one the
211
+ * manifest names anywhere (`ledger-api`, a folder's name) is the repo's component's, and its
212
+ * endpoints are in the box its depends-on arrow starts from. Undefined when the fact stays as it
213
+ * is: it names none, or one the manifest names, or the repo lists modules, or it is a prototype
214
+ * (ADR 0133: its UI, BFF and mocks are components of their own, read and compared, never
215
+ * written into the catalog).
216
+ */
217
+ export declare function placedComponentOf(f: Fact, manifest: {
218
+ /** The repo's own component (the manifest's `component`, else its id). */
219
+ component: string;
220
+ /** The repo's modules as the manifest lists them. */
221
+ modules?: readonly unknown[] | undefined;
222
+ /** Every component (and repo id) the estate's manifests name. */
223
+ components: readonly string[];
224
+ /** The repo is a prototype (its manifest `type`). */
225
+ prototype?: boolean | undefined;
226
+ }): string | undefined;
74
227
  /**
75
228
  * A call's normalised path: a gRPC method stays `package.Service/Method` and a SOAP operation
76
229
  * `Contract/Operation` (a client may write either with a leading slash); an HTTP path loses a parameter's optional marker and constraint first
@@ -89,6 +242,7 @@ export declare function catalogAuth(f: FactOf<"entry">): FactOf<"entry">["auth"]
89
242
  * Facts to C1. Ids are made from the claims, so the same facts give the same ids:
90
243
  * Endpoint `<component>.<method-path>`, Interface `if-<hash>`, DataStore `<store>`,
91
244
  * Table `<store>.<table>`, Column `<store>.<table>.<column>`, Schema `<endpoint>.<side>`,
92
- * Deployment `<component>.<env>`, Setting `<component>.<key>`, Flow `<component>.<name>`.
245
+ * Deployment `<component>.<env>`, Setting `<component>.<key>`, Flow `<component>.<name>`,
246
+ * Unresolved `unresolved.<repo>.<call>` (ADR 0124 addendum E-ids).
93
247
  */
94
248
  export declare function projectFacts(input: readonly Fact[], opts?: ProjectOptions): ProjectResult;
@@ -0,0 +1,109 @@
1
+ import type { Fact, FactOf } from "./schema/facts.js";
2
+ /**
3
+ * A field's place in its payload, built from the facts alone (ADR 0164, addendum of 2026-11-17).
4
+ *
5
+ * A reader writes one field fact per field of each class a payload is made of, each cited on its
6
+ * declaration in the class's own file, by the name the field has there: `depot`, not
7
+ * `receipt.stamps[].depot`. What says where a class sits is the field that holds it: a
8
+ * field whose declared type names the class (`List<Stamp> stamps`). So, per
9
+ * owner and side:
10
+ *
11
+ * - **A class** is the fields cited in one file (the verifier checked each on its line, so the
12
+ * file is the one thing about membership that is not the reader's choice of words). Where one
13
+ * file holds several classes, the fields whose id carries a type's name
14
+ * (`field.stamp.reason`) are that type's.
15
+ * - **A parent** of a class is a field of the same owner and side whose type names it: the
16
+ * fact's `type`, and where that is left out the type the cited line declares for it. A list
17
+ * gives `[]`; a wrapper that only passes its value on (`Optional<X>`, `ResponseEntity<X>`) is
18
+ * no level. A map gives a place nobody can name (its keys are data). A class named inside any
19
+ * other generic type (`Page<Item>`) is placed through that type's own fields when they are on
20
+ * record (`Envelope<Order>` with `T content`), and has no place anyone can name when not.
21
+ * - **A path** is the parent's path, then the field's name; through as many levels as the facts
22
+ * hold, at every place a class is reached from, never round a class that holds itself twice.
23
+ * - **An envelope mapping** (`mappedTo` a field, `transform: envelope …`, ADR 0164 §2) places
24
+ * one field under another, as before; where the field's class is itself held, by type, by a
25
+ * field under that envelope, the type's path is the place (`data.customer.name`).
26
+ * - **A dotted name** (`receipt.depot_token`) is the reader's own path: where it starts with the
27
+ * end of its class's place it is not prefixed again. It places itself only, never its siblings.
28
+ * - **Roots**: every class no field points at that holds another class is a root (a body and
29
+ * an error body, a base class and the class that extends it): its fields are top-level.
30
+ *
31
+ * A field whose place isn't sure carries `unplaced`, the reason in words. Two kinds. A doubt that
32
+ * only says *where* (a class nothing points at beside classes that hold others; classes that
33
+ * only hold each other) matters only to a difference that depends on where: the check ignores
34
+ * it when the other side has that name nowhere, or once. A doubt that `decides` (a map; a
35
+ * generic type whose shape isn't on record; an envelope mapping and a type that name different
36
+ * parents; a dotted name that doesn't fit its class's place; more places than are compared)
37
+ * leaves any difference on the field unconfirmed.
38
+ *
39
+ * Pure: the same fields give the same places whatever order they come in. No file is read.
40
+ */
41
+ type Field = FactOf<"field">;
42
+ /** One place a field has on the wire. */
43
+ export interface FieldPlace {
44
+ /** The path from the payload's root: `receipt.stamps[].depot`. */
45
+ name: string;
46
+ /** The ids of the fields that hold it, from the root down. */
47
+ via: string[];
48
+ /** Why the place isn't sure, in words. */
49
+ unplaced?: string;
50
+ /** The doubt holds whatever the other side has: any difference on the field is unconfirmed. */
51
+ decides?: true;
52
+ /** The place is a second turn round a class that holds itself. */
53
+ again?: true;
54
+ /**
55
+ * The path starts at a class nothing holds that holds others, and nothing on the way is in
56
+ * doubt: built, not just written. `root` is that class (its file).
57
+ */
58
+ sure?: true;
59
+ root?: string;
60
+ }
61
+ /** A class whose place in a payload isn't on record. */
62
+ export interface LooseClass {
63
+ owner: string;
64
+ side: string;
65
+ /** The class as its file names it. */
66
+ class: string;
67
+ file: string;
68
+ /** Its fields' ids. */
69
+ fields: string[];
70
+ why: string;
71
+ }
72
+ /** A class a type names, and how the type holds it. */
73
+ interface TypeRef {
74
+ ident: string;
75
+ /** `inside`: within a generic type that is no list, wrapper or map (`outer`). */
76
+ kind: "one" | "list" | "map" | "inside";
77
+ outer?: string;
78
+ }
79
+ /**
80
+ * The identifiers a type names, each with how it is held: alone, in a list (`List<X>`, `X[]`,
81
+ * `[]X`, `list[X]`, `repeated X`), in a map, or inside another generic type. A qualified name
82
+ * counts by its last part; quoted values (an enum's) are left out.
83
+ */
84
+ export declare function typeRefs(type: string): TypeRef[];
85
+ /**
86
+ * The type the cited line declares for the field, when the fact has none: the line's text is the
87
+ * quote, the field the token that reads as its cited value or its name (`depotToken` for
88
+ * `depot_token`). Java, C#, Kotlin, TypeScript, Python and Go forms; anything else gives nothing.
89
+ */
90
+ export declare function declaredTypeOf(f: Pick<Field, "name" | "type" | "cite">): string | undefined;
91
+ export interface FieldPlaces {
92
+ /** Each field's places, by id; a header's and a field with no class is its own name. */
93
+ of: (f: Field) => FieldPlace[];
94
+ /** The classes whose place isn't on record. */
95
+ loose: () => Omit<LooseClass, "owner" | "side">[];
96
+ }
97
+ /**
98
+ * The places of the fields of one owner and side (mapping facts between two payloads and a
99
+ * mapper's dropped end left out by the caller).
100
+ */
101
+ export declare function placeFields(input: readonly Field[], side: string): FieldPlaces;
102
+ /**
103
+ * The classes of a repo's payloads whose place isn't on record (for `atticus verify`): per entry
104
+ * or call and side, each class no field of that payload reaches, with why. The fields are those
105
+ * the contract check compares: a mapping between two payloads (a gateway policy's) and the end
106
+ * of a mapper that doesn't travel are left out, as `checkContracts` leaves them.
107
+ */
108
+ export declare function looseFieldClasses(facts: readonly Fact[]): LooseClass[];
109
+ export {};
@@ -0,0 +1,84 @@
1
+ /**
2
+ * Reading and hashing many small files (beta.28.2): a catalog's 100,000 record files took 10 to
3
+ * 13 s to hash through the promise API, four calls each (open, stat, read, close) handed to
4
+ * libuv's thread pool and back, and each text decoded, its line endings replaced and encoded again
5
+ * to be hashed. Here a few worker threads read them with the synchronous calls, one file at a
6
+ * time each (so no more than one open file a worker: no EMFILE, on Windows either), and hash the
7
+ * bytes; the main thread stays free (a progress line, Stop between steps) and gets the results in
8
+ * the order of the paths, whatever the order the workers finish in. Every byte of every file is
9
+ * read: nothing is taken from a file's size and time. A small folder, or a process where a worker
10
+ * can't start, is read in this thread instead, to the same results.
11
+ *
12
+ * Beta.28.3: a read given a `signal` (a job's Stop) ends when it is stopped, with CancelledError:
13
+ * the workers are ended where they are (no more than the file each has open is read on), this
14
+ * thread's read stops between two files, and the wait for workers that never start ends at once.
15
+ * It only reads, so a stopped read leaves nothing behind.
16
+ */
17
+ /** A file's size and time (ms, floored), as `stat` gives them. */
18
+ export interface FileStat {
19
+ size: number;
20
+ mtimeMs: number;
21
+ }
22
+ /** A file's size and time, and the hash of its text with its line endings LF (`textShaOf`). */
23
+ export interface FileHash extends FileStat {
24
+ sha: string;
25
+ }
26
+ /**
27
+ * How the files are read: tests force a number of workers (0: this thread) and the smallest
28
+ * folder read by workers. By default 2 to 4 workers (one fewer than the CPUs, at least 2), for
29
+ * folders of `MIN_FILES` files or more.
30
+ */
31
+ export declare const filePoolHooks: {
32
+ workers?: number;
33
+ minFiles?: number;
34
+ /** A test's workers that fail as they start (as one that can't: ERR_WORKER_INIT_FAILED, OOM). */
35
+ failStart?: boolean;
36
+ /** A test's workers that start and never say they are ready (nor fail, nor exit). */
37
+ neverReady?: boolean;
38
+ /** How long the workers have to say they are ready (default `START_TIMEOUT_MS`). */
39
+ startTimeoutMs?: number;
40
+ /** A test hears how many files are read so far (in workers a batch at a time). */
41
+ onRead?: (files: number) => void;
42
+ };
43
+ /**
44
+ * How long the workers have to say they are ready before this thread reads instead (the final
45
+ * review of beta.28.2: a worker that neither answered nor failed hung the build). A worker starts
46
+ * in tens of milliseconds; 10 s is a host so loaded that this thread would be no slower.
47
+ */
48
+ export declare const START_TIMEOUT_MS = 10000;
49
+ /**
50
+ * The hash of a file's text, read as UTF-8, with its line endings LF: `sha256Of` of that text.
51
+ * Bytes that are UTF-8 with no CR are that text's own bytes, so they are hashed as they are;
52
+ * any other (a CR, a byte that isn't UTF-8, read as U+FFFD) are decoded first, as a read gives.
53
+ */
54
+ export declare function textShaOf(bytes: Buffer): string;
55
+ /**
56
+ * Every named file under `dir` (paths with forward slashes), read whole and hashed: its text hash
57
+ * (`textShaOf`), size and time, in the order of `rels`. A file that can't be opened or read fails
58
+ * the call with that error (its `code`: ENOENT for one gone since it was listed). With `raw`, the
59
+ * hash is of the file's bytes as they are (sha256, no line endings made LF): a parse kept by it
60
+ * is of exactly those bytes (record-cache.ts). With `signal`, a stop ends the read part way and
61
+ * fails the call with CancelledError (beta.28.3).
62
+ */
63
+ export declare function hashFilesIn(dir: string, rels: readonly string[], o?: {
64
+ raw?: boolean;
65
+ signal?: AbortSignal;
66
+ ctime?: boolean;
67
+ }): Promise<(FileHash & {
68
+ ctimeMs?: number;
69
+ ino?: number;
70
+ })[]>;
71
+ /**
72
+ * Every named file's size and time (ms, floored), in the order of `rels`; none for one not there.
73
+ * With `signal`, a stop ends the read part way and fails the call with CancelledError. With
74
+ * `ctime`, each file's change time too (`ctimeMs`: the last change of its bytes or its times,
75
+ * which no program sets) and its identity (`ino`: the inode, NTFS's file id; 0 where the
76
+ * platform reports none): hash-cache.ts keeps a hash by them.
77
+ */
78
+ export declare function statFilesIn(dir: string, rels: readonly string[], o?: {
79
+ signal?: AbortSignal;
80
+ ctime?: boolean;
81
+ }): Promise<((FileStat & {
82
+ ctimeMs?: number;
83
+ ino?: number;
84
+ }) | undefined)[]>;