@maycombhq/sdk 2.0.0-beta.3 → 2.0.0-beta.30
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/npm/core/ai-decisions.d.ts +373 -0
- package/npm/core/api.d.ts +15888 -3797
- package/npm/core/app-memory.d.ts +69 -0
- package/npm/core/assistant-actor.d.ts +28 -7
- package/npm/core/audit.d.ts +174 -0
- package/npm/core/canary.d.ts +369 -0
- package/npm/core/cancel.d.ts +20 -0
- package/npm/core/catalog.d.ts +220 -66
- package/npm/core/change-types-migrate.d.ts +14 -0
- package/npm/core/cite.d.ts +88 -6
- package/npm/core/contract-check.d.ts +276 -0
- package/npm/core/curated.d.ts +10 -0
- package/npm/core/decision-batches.d.ts +29 -0
- package/npm/core/declarable-routes.d.ts +52 -0
- package/npm/core/declared-links.d.ts +210 -0
- package/npm/core/eol.d.ts +5 -0
- package/npm/core/fact-paths.d.ts +14 -0
- package/npm/core/facts-callers.d.ts +23 -1
- package/npm/core/facts-carry.d.ts +8 -2
- package/npm/core/facts-deps.d.ts +85 -0
- package/npm/core/facts-join-prototype.d.ts +66 -4
- package/npm/core/facts-join-vendor.d.ts +67 -7
- package/npm/core/facts-join.d.ts +476 -2
- package/npm/core/facts-terms.d.ts +108 -0
- package/npm/core/facts.d.ts +155 -1
- package/npm/core/field-places.d.ts +109 -0
- package/npm/core/file-pool.d.ts +84 -0
- package/npm/core/fs.d.ts +205 -7
- package/npm/core/glob-plain.d.ts +34 -0
- package/npm/core/glob.d.ts +14 -0
- package/npm/core/hash-cache.d.ts +53 -0
- package/npm/core/host-questions.d.ts +273 -1
- package/npm/core/identity.d.ts +20 -8
- package/npm/core/index.d.ts +38 -0
- package/npm/core/initialisms.d.ts +62 -0
- package/npm/core/kept-files.d.ts +17 -0
- package/npm/core/light.d.ts +5 -0
- package/npm/core/link-candidates.d.ts +224 -0
- package/npm/core/link-evidence.d.ts +212 -0
- package/npm/core/log.d.ts +2 -0
- package/npm/core/manifest-edit.d.ts +83 -6
- package/npm/core/merge.d.ts +28 -0
- package/npm/core/metarepo.d.ts +26 -1
- package/npm/core/migrate.d.ts +3 -2
- package/npm/core/org-notes.d.ts +180 -0
- package/npm/core/orgpack-defaults.d.ts +30 -6
- package/npm/core/orgpack-load.d.ts +24 -0
- package/npm/core/paths.d.ts +23 -0
- package/npm/core/printer.d.ts +18 -0
- package/npm/core/process-trees.d.ts +109 -0
- package/npm/core/profile-migrate.d.ts +13 -0
- package/npm/core/question-order.d.ts +23 -0
- package/npm/core/question-owners.d.ts +57 -0
- package/npm/core/question-proposals.d.ts +77 -0
- package/npm/core/question-roles.d.ts +84 -0
- package/npm/core/questions.d.ts +123 -6
- package/npm/core/record-cache.d.ts +122 -2
- package/npm/core/repo-files.d.ts +66 -0
- package/npm/core/repo-reads.d.ts +44 -0
- package/npm/core/roles-migrate.d.ts +10 -0
- package/npm/core/run-log.d.ts +341 -0
- package/npm/core/runtime-migrate.d.ts +18 -0
- package/npm/core/schema/ai.d.ts +61 -13
- package/npm/core/schema/common.d.ts +32 -8
- package/npm/core/schema/component-type.d.ts +193 -0
- package/npm/core/schema/conventions.d.ts +80 -0
- package/npm/core/schema/dialect.d.ts +12 -12
- package/npm/core/schema/fact-corrections.d.ts +112 -2
- package/npm/core/schema/facts.d.ts +743 -23
- package/npm/core/schema/frameworks.d.ts +12 -12
- package/npm/core/schema/kinds.d.ts +230 -66
- package/npm/core/schema/orgpack.d.ts +248 -24
- package/npm/core/schema/question.d.ts +281 -5
- package/npm/core/schema/reading-rules.d.ts +51 -0
- package/npm/core/schema/repo-type.d.ts +20 -2
- package/npm/core/schema/review.d.ts +30 -9
- package/npm/core/schema/scan-verify.d.ts +77 -0
- package/npm/core/schema/version.d.ts +4 -1
- package/npm/core/schema/workspace.d.ts +29 -11
- package/npm/core/setup-edit.d.ts +107 -0
- package/npm/core/shared-maps.d.ts +146 -0
- package/npm/core/stack-helpers.d.ts +32 -0
- package/npm/core/version-order.d.ts +14 -0
- package/npm/fs-repo.d.ts +2 -1
- package/npm/index.js +14248 -6710
- package/npm/listing.d.ts +14 -0
- package/npm/sandbox.d.ts +2 -1
- package/package.json +1 -1
package/npm/core/identity.d.ts
CHANGED
|
@@ -1,13 +1,12 @@
|
|
|
1
|
+
export { normalizePath, stripParamConstraints } from "./paths.js";
|
|
2
|
+
/** Code-unit string order, the same in every locale (`localeCompare` is not: ICU orders `_`/`-`
|
|
3
|
+
* and, in `da`, `aa` differently), for every sort that feeds records, ids, hashes or a merge. */
|
|
4
|
+
export declare function cmpText(a: string, b: string): number;
|
|
1
5
|
/**
|
|
2
|
-
*
|
|
3
|
-
* (
|
|
4
|
-
*
|
|
5
|
-
* - path parameters in any style ({id}, :id, <id>, ${id}) become "{}"
|
|
6
|
-
* - query strings and fragments are dropped
|
|
7
|
-
* - repeated and trailing slashes are removed; a leading slash is ensured for paths
|
|
8
|
-
* - topics (no leading slash in the input and no "/" at all) are returned trimmed
|
|
6
|
+
* `cmpText`, but a run of digits is compared as a number (`a.ts:9` before `a.ts:10`): what
|
|
7
|
+
* `localeCompare(b, "en", { numeric: true })` was used for, without ICU.
|
|
9
8
|
*/
|
|
10
|
-
export declare function
|
|
9
|
+
export declare function cmpNatural(a: string, b: string): number;
|
|
11
10
|
/**
|
|
12
11
|
* Stable interface id: a hash of caller, callee, method and normalised path, so the same
|
|
13
12
|
* edge seen by several extractors merges into one Interface record.
|
|
@@ -15,3 +14,16 @@ export declare function normalizePath(input: string): string;
|
|
|
15
14
|
export declare function interfaceId(from: string, to: string, method: string | undefined, path: string): string;
|
|
16
15
|
/** Lowercase slug suitable as a record id, built from free text such as a system name. */
|
|
17
16
|
export declare function slugify(text: string): string;
|
|
17
|
+
/**
|
|
18
|
+
* Round 47: a name with no Latin letter or digit in it (`注文`, `Заказы`, `...`) slugs to
|
|
19
|
+
* nothing, so every such name used to become the same `unnamed` and their records merged.
|
|
20
|
+
* It gets `unnamed-<short hash of the name>` instead: stable, and different per name. Blank
|
|
21
|
+
* text stays `unnamed`.
|
|
22
|
+
*/
|
|
23
|
+
export declare function unnamedId(text: string): string;
|
|
24
|
+
/**
|
|
25
|
+
* A slug that is never a Windows device name (review round 46): a record is the file
|
|
26
|
+
* `<kind>/<id>.yaml` and Windows can't create `aux.yaml`, so the slug's first dot-separated part,
|
|
27
|
+
* when it is one, gets `-1` (`aux` is `aux-1`, `con.v2` is `con-1.v2`). C1's RecordId is unchanged.
|
|
28
|
+
*/
|
|
29
|
+
export declare function notDeviceName(slug: string): string;
|
package/npm/core/index.d.ts
CHANGED
|
@@ -3,12 +3,24 @@ export * from "./schema/kinds.js";
|
|
|
3
3
|
export * from "./schema/facts.js";
|
|
4
4
|
export * from "./schema/fact-corrections.js";
|
|
5
5
|
export * from "./facts.js";
|
|
6
|
+
export * from "./app-memory.js";
|
|
7
|
+
export * from "./fact-paths.js";
|
|
6
8
|
export * from "./migration-files.js";
|
|
7
9
|
export * from "./facts-join.js";
|
|
8
10
|
export * from "./facts-join-vendor.js";
|
|
9
11
|
export * from "./facts-join-prototype.js";
|
|
10
12
|
export * from "./facts-carry.js";
|
|
11
13
|
export * from "./facts-callers.js";
|
|
14
|
+
export * from "./facts-terms.js";
|
|
15
|
+
export * from "./facts-deps.js";
|
|
16
|
+
export * from "./org-notes.js";
|
|
17
|
+
export * from "./link-evidence.js";
|
|
18
|
+
export * from "./shared-maps.js";
|
|
19
|
+
export * from "./contract-check.js";
|
|
20
|
+
export * from "./field-places.js";
|
|
21
|
+
export * from "./audit.js";
|
|
22
|
+
export * from "./canary.js";
|
|
23
|
+
export * from "./stack-helpers.js";
|
|
12
24
|
export * from "./cite.js";
|
|
13
25
|
export * from "./catalog.js";
|
|
14
26
|
export * from "./identity.js";
|
|
@@ -23,10 +35,12 @@ export * from "./schema/frameworks.js";
|
|
|
23
35
|
export * from "./schema/scan-settings.js";
|
|
24
36
|
export * from "./schema/scan-verify.js";
|
|
25
37
|
export * from "./schema/repo-type.js";
|
|
38
|
+
export * from "./schema/component-type.js";
|
|
26
39
|
export * from "./schema/layout.js";
|
|
27
40
|
export * from "./schema/plugin.js";
|
|
28
41
|
export * from "./schema/review.js";
|
|
29
42
|
export * from "./schema/orgpack.js";
|
|
43
|
+
export * from "./schema/conventions.js";
|
|
30
44
|
export * from "./schema/executors.js";
|
|
31
45
|
export * from "./orgpack-defaults.js";
|
|
32
46
|
export * from "./orgpack-load.js";
|
|
@@ -41,12 +55,23 @@ export * from "./gates-migrate.js";
|
|
|
41
55
|
export * from "./change-types-migrate.js";
|
|
42
56
|
export * from "./sources-migrate.js";
|
|
43
57
|
export * from "./runtime-migrate.js";
|
|
58
|
+
export * from "./roles-migrate.js";
|
|
59
|
+
export * from "./profile-migrate.js";
|
|
44
60
|
export * from "./metarepo.js";
|
|
45
61
|
export * from "./fs.js";
|
|
62
|
+
export * from "./glob.js";
|
|
63
|
+
export * from "./repo-files.js";
|
|
46
64
|
export * from "./record-cache.js";
|
|
65
|
+
export * from "./file-pool.js";
|
|
66
|
+
export * from "./hash-cache.js";
|
|
67
|
+
export * from "./kept-files.js";
|
|
47
68
|
export * from "./log.js";
|
|
69
|
+
export * from "./run-log.js";
|
|
70
|
+
export * from "./version-order.js";
|
|
71
|
+
export * from "./printer.js";
|
|
48
72
|
export * from "./zip.js";
|
|
49
73
|
export * from "./words.js";
|
|
74
|
+
export * from "./initialisms.js";
|
|
50
75
|
export * from "./zip-read.js";
|
|
51
76
|
export * from "./tar-read.js";
|
|
52
77
|
export * from "./schema/question.js";
|
|
@@ -54,9 +79,22 @@ export * from "./questions.js";
|
|
|
54
79
|
export * from "./schema/judgment.js";
|
|
55
80
|
export * from "./judgments.js";
|
|
56
81
|
export * from "./host-questions.js";
|
|
82
|
+
export * from "./repo-reads.js";
|
|
83
|
+
export * from "./question-order.js";
|
|
84
|
+
export * from "./question-owners.js";
|
|
85
|
+
export * from "./question-roles.js";
|
|
86
|
+
export * from "./question-proposals.js";
|
|
57
87
|
export * from "./repo-description.js";
|
|
58
88
|
export * from "./manifest-edit.js";
|
|
89
|
+
export * from "./setup-edit.js";
|
|
59
90
|
export * from "./schema/spec.js";
|
|
60
91
|
export * from "./specs.js";
|
|
61
92
|
export * from "./cancel.js";
|
|
93
|
+
export * from "./process-trees.js";
|
|
62
94
|
export * from "./assistant-actor.js";
|
|
95
|
+
export * from "./link-candidates.js";
|
|
96
|
+
export * from "./ai-decisions.js";
|
|
97
|
+
export * from "./decision-batches.js";
|
|
98
|
+
export * from "./declared-links.js";
|
|
99
|
+
export * from "./declarable-routes.js";
|
|
100
|
+
export * from "./schema/reading-rules.js";
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* An acronym and the words it stands for (beta.28.3): "SSO" and "single sign-on", "EDW" and
|
|
3
|
+
* "enterprise data warehouse". One side of a search often writes the letters and the other the
|
|
4
|
+
* words, with no word in common, and a small embedding model rates the two far apart.
|
|
5
|
+
*
|
|
6
|
+
* The link is taken only from where the organisation's own pages define it: "Enterprise Data
|
|
7
|
+
* Warehouse (EDW)", "EDW (Enterprise Data Warehouse)", or a line of an abbreviations list
|
|
8
|
+
* ("EDW: Enterprise Data Warehouse", "| SSO | single sign-on |"), and only when the words' first
|
|
9
|
+
* letters spell the acronym. Letters alone are not enough: ordinary prose spells most
|
|
10
|
+
* three-letter acronyms by chance ("step still open" is no SSO), so a run of words is never
|
|
11
|
+
* taken for an acronym's meaning unless a page sets the two side by side. Deterministic, no
|
|
12
|
+
* model. A link only ranks and keeps what a search shows; it never makes a record or a fact.
|
|
13
|
+
*/
|
|
14
|
+
export interface Initialism {
|
|
15
|
+
/** As written: capital letters and digits, three to six, starting with a letter. */
|
|
16
|
+
acronym: string;
|
|
17
|
+
/** The words it stands for: lower case, single spaces, hyphens as spaces. */
|
|
18
|
+
phrase: string;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* How a phrase is looked for in a text: lower case, anything but letters and digits as one space,
|
|
22
|
+
* a space at each end. Where a sentence, a bracket or a paragraph ends there is a bar, so a phrase is
|
|
23
|
+
* never found across one ("the change. Request access" writes no "change request").
|
|
24
|
+
*/
|
|
25
|
+
export declare const foldWords: (s: string) => string;
|
|
26
|
+
/**
|
|
27
|
+
* The acronyms a text defines, each with the words it sets beside it, in the order met:
|
|
28
|
+
*
|
|
29
|
+
* - `words (ACR)`: the words just before the bracket, as many as spell it;
|
|
30
|
+
* - `ACR (words)`: everything in the bracket;
|
|
31
|
+
* - `ACR: words`, `ACR - words`, `ACR = words`, `| ACR | words |` at a line's start (after a
|
|
32
|
+
* list mark or emphasis): the words up to the next punctuation, as many as spell it.
|
|
33
|
+
*
|
|
34
|
+
* The words' first letters must spell the acronym; a pair that doesn't is no definition.
|
|
35
|
+
*/
|
|
36
|
+
export declare function definedInitialisms(text: string): Initialism[];
|
|
37
|
+
export interface InitialismUse extends Initialism {
|
|
38
|
+
/** Which form the text writes. */
|
|
39
|
+
wrote: "acronym" | "phrase";
|
|
40
|
+
}
|
|
41
|
+
export interface InitialismLink extends Initialism {
|
|
42
|
+
/** Which text writes the acronym; the other writes the words. */
|
|
43
|
+
acronymIn: "a" | "b";
|
|
44
|
+
}
|
|
45
|
+
/** The acronyms an estate's pages define, to link a text that writes one form to one that writes the other. */
|
|
46
|
+
export interface InitialismBook {
|
|
47
|
+
readonly size: number;
|
|
48
|
+
entries(): Initialism[];
|
|
49
|
+
/** The defined acronyms a text writes, and the defined phrases it writes, in the book's order. */
|
|
50
|
+
uses(text: string): InitialismUse[];
|
|
51
|
+
/**
|
|
52
|
+
* The names one text writes as an acronym and the other only as its words. A name both write
|
|
53
|
+
* as the acronym is a word in common, not a link, and is left out.
|
|
54
|
+
*/
|
|
55
|
+
links(a: string, b: string): InitialismLink[];
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* A book of definitions, each acronym and phrase once, sorted: the same definitions give the same
|
|
59
|
+
* book. An acronym that is an ordinary word in capitals (POST, NOTE, AND) is left out, as is a
|
|
60
|
+
* phrase of one word.
|
|
61
|
+
*/
|
|
62
|
+
export declare function initialismBook(defs: Iterable<Initialism>): InitialismBook;
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/** While `isQuiet()` says so, files checked since the last change aren't checked again; none to stop. */
|
|
2
|
+
export declare function trustKeptFiles(isQuiet?: () => boolean): void;
|
|
3
|
+
/**
|
|
4
|
+
* A file may have changed: each kept file is checked again when next asked; with `path` (a
|
|
5
|
+
* file or a folder), only those at or under it.
|
|
6
|
+
*/
|
|
7
|
+
export declare function keptFilesMayHaveChanged(path?: string): void;
|
|
8
|
+
/**
|
|
9
|
+
* What `parse` makes of the file's text, from the last read while the file is unchanged.
|
|
10
|
+
* Undefined when there is no such file. A parse that throws is not kept: the error goes to the
|
|
11
|
+
* caller, as a fresh read's would.
|
|
12
|
+
*/
|
|
13
|
+
export declare function keptParse<T>(path: string, kind: string, parse: (text: string) => T, o?: {
|
|
14
|
+
copy?: boolean;
|
|
15
|
+
}): Promise<T | undefined>;
|
|
16
|
+
/** For tests: forget every file kept. */
|
|
17
|
+
export declare function forgetKeptFiles(): void;
|
package/npm/core/light.d.ts
CHANGED
|
@@ -6,3 +6,8 @@
|
|
|
6
6
|
*/
|
|
7
7
|
export { SCHEMA_VERSION } from "./schema/version.js";
|
|
8
8
|
export { createLog, logFileOf, NO_LOG, type Log, type LogEntry, type LogLevel } from "./log.js";
|
|
9
|
+
export { recordedCommand, retitleTerminalRuns, runLogKept, runTitle, startTerminalRun, TITLE_VALUE_FLAGS, type TerminalRunRecorder, } from "./run-log.js";
|
|
10
|
+
export { printToCurrent, withPrinter } from "./printer.js";
|
|
11
|
+
export { atticusHandles, onAtticusSignal } from "./process-trees.js";
|
|
12
|
+
export { keyIsSecret } from "./cite.js";
|
|
13
|
+
export { atticusVersionOf, newerThan } from "./version-order.js";
|
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
import type { FactsJoinResult, PersonPair } from "./facts-join.js";
|
|
2
|
+
import type { Fact } from "./schema/facts.js";
|
|
3
|
+
/**
|
|
4
|
+
* G1 (ADR 0174): connect two boxes call by call. Box A's calls that join nothing (asked,
|
|
5
|
+
* unresolved, missed, left), box B's APIs (a service's entries, a proxy's routes, an outside
|
|
6
|
+
* system's operations from its intaken spec), and for each call the API it most likely is.
|
|
7
|
+
* Pure: the caller reads the facts, the join and the spec.
|
|
8
|
+
*/
|
|
9
|
+
export type LooseStatus = "asked" | "missed" | "left" | "outside" | "unresolved"
|
|
10
|
+
/** Already paired by a person with an API of this box. */
|
|
11
|
+
| "paired"
|
|
12
|
+
/**
|
|
13
|
+
* Beta.28.1: the join ties it to another box (or this one) and an arrow is drawn for it:
|
|
14
|
+
* listed so it can be moved here from the same panel, never ticked unseen.
|
|
15
|
+
*/
|
|
16
|
+
| "joined"
|
|
17
|
+
/**
|
|
18
|
+
* Beta.28.1: the join ties it to something, and no arrow is drawn for it (its own component,
|
|
19
|
+
* or no Interface of it on the canvas): as loose as a call that joins nothing.
|
|
20
|
+
*/
|
|
21
|
+
| "undrawn"
|
|
22
|
+
/**
|
|
23
|
+
* The review of beta.28.1 (S2): the join ties it to this very box and an arrow is drawn for it
|
|
24
|
+
* (`now` the API it goes to): it goes here already, so nothing is suggested for it, and a
|
|
25
|
+
* pairing with the API it goes to would be a redundant line (refused).
|
|
26
|
+
*/
|
|
27
|
+
| "here";
|
|
28
|
+
export interface CandidateApi {
|
|
29
|
+
/** The entry's fact id, or the operation's id in the spec. */
|
|
30
|
+
id: string;
|
|
31
|
+
kind: "entry" | "route" | "operation";
|
|
32
|
+
method?: string;
|
|
33
|
+
path: string;
|
|
34
|
+
/** file:line, for an entry. */
|
|
35
|
+
at?: string;
|
|
36
|
+
/** Words that name it besides its path: a spec operation's operationId, a route's name. */
|
|
37
|
+
words?: string;
|
|
38
|
+
/** A gateway route: the path it forwards to (what the service behind it serves). */
|
|
39
|
+
forwards?: string;
|
|
40
|
+
}
|
|
41
|
+
export interface CandidateCall {
|
|
42
|
+
fact: string;
|
|
43
|
+
callType: string;
|
|
44
|
+
method?: string;
|
|
45
|
+
path: string;
|
|
46
|
+
at: string;
|
|
47
|
+
status: LooseStatus;
|
|
48
|
+
/** What the join said: the reason it left it, the target it missed, the host it asked about. */
|
|
49
|
+
why?: string;
|
|
50
|
+
/** For paired: the API it is paired with. */
|
|
51
|
+
paired?: string;
|
|
52
|
+
/**
|
|
53
|
+
* For paired (the field report of beta.28.3, "it says it's paired, but I don't see the line"):
|
|
54
|
+
* whether the map draws its arrow to this box. A pairing is a line in the corrections file;
|
|
55
|
+
* the arrow is the catalog's, drawn by the repo's next Apply. Left out when the caller read no
|
|
56
|
+
* catalog (`drawn` and `drawnTo` not given).
|
|
57
|
+
*/
|
|
58
|
+
drawn?: boolean;
|
|
59
|
+
/**
|
|
60
|
+
* For paired (ADR 0199, the review): the component both ends of the pairing are in. No arrow
|
|
61
|
+
* is drawn between boxes for it, whatever is applied.
|
|
62
|
+
*/
|
|
63
|
+
inside?: string;
|
|
64
|
+
/**
|
|
65
|
+
* ADR 0199, the review: the pairing is the AI's (ADR 0181), not confirmed by a person;
|
|
66
|
+
* `pairedBy` is then the run's own name. Never said of a person's pairing.
|
|
67
|
+
*/
|
|
68
|
+
pairedAi?: boolean;
|
|
69
|
+
/**
|
|
70
|
+
* ADR 0199, the second review (M1): the box the pairing `pairedBy` made names, when it is
|
|
71
|
+
* not the box the call goes to (`joins`): a gateway's, whose route forwards the call on.
|
|
72
|
+
*/
|
|
73
|
+
pairedWith?: string;
|
|
74
|
+
/**
|
|
75
|
+
* ADR 0199 (M1): why a call with a pairing goes to another box than the pairing's. The
|
|
76
|
+
* estate's join says, never a guess: `forwarded`, the pairing is with a gateway's route and
|
|
77
|
+
* the route's forwarding call reaches `joins` (one link, drawn from the caller to `joins`);
|
|
78
|
+
* `outranked`, the pairing is the AI's and a person's answer names `joins` instead (the join's
|
|
79
|
+
* own rule: a person's word stands over the AI's), so the pairing is not in effect.
|
|
80
|
+
*/
|
|
81
|
+
onward?: "forwarded" | "outranked";
|
|
82
|
+
/**
|
|
83
|
+
* Beta.28.1: the box the join ties it to now (a repo, or an outside target), for a call that
|
|
84
|
+
* is joined, undrawn or outside: where it goes, or would go, before it is moved.
|
|
85
|
+
*/
|
|
86
|
+
joins?: string;
|
|
87
|
+
/** For here: the API of this box it goes to now (an entry's fact id), when the join names one. */
|
|
88
|
+
now?: string;
|
|
89
|
+
/**
|
|
90
|
+
* The review of beta.28.1 (N3): who paired it with the box it goes to now (another box): a
|
|
91
|
+
* pairing here replaces that person's word, which the panel says before it is written.
|
|
92
|
+
* ADR 0199: also who paired a `paired` call with this box.
|
|
93
|
+
*/
|
|
94
|
+
pairedBy?: string;
|
|
95
|
+
/**
|
|
96
|
+
* Beta.30 (the owner's field report, "it's connected to the wrong box"): for a call that goes
|
|
97
|
+
* somewhere already, how that was decided, as the estate's join says: `code`, the call's own
|
|
98
|
+
* fact names the box; `address`, its host or base path is the box's; `path`, only its path
|
|
99
|
+
* matched (a guess); `gateway`, a gateway's route forwards it there (`through` the gateway's
|
|
100
|
+
* repo); `answer`, a person's answer to a question; `paired`, a person's pairing; `ai`, the
|
|
101
|
+
* AI's pairing or answer; `kept`, the map draws an arrow from the call's line that this read's
|
|
102
|
+
* join doesn't place (kept from an earlier read, as an upgrade adopts them). `who` is who
|
|
103
|
+
* answered or paired. The caller that reads the files adds when, the question and a
|
|
104
|
+
* pairing's reason.
|
|
105
|
+
*/
|
|
106
|
+
how?: CandidateHow;
|
|
107
|
+
suggestion?: {
|
|
108
|
+
api: string;
|
|
109
|
+
score: number;
|
|
110
|
+
why: SuggestWhy;
|
|
111
|
+
};
|
|
112
|
+
/** The APIs it most likely is, best first (at most three); the first is `suggestion`. */
|
|
113
|
+
suggestions?: {
|
|
114
|
+
api: string;
|
|
115
|
+
score: number;
|
|
116
|
+
why: SuggestWhy;
|
|
117
|
+
}[];
|
|
118
|
+
/** The best is well ahead of the rest and scores high: safe to pair without a look. */
|
|
119
|
+
confident?: boolean;
|
|
120
|
+
}
|
|
121
|
+
export interface CandidateHow {
|
|
122
|
+
by: "code" | "address" | "path" | "gateway" | "answer" | "paired" | "ai" | "kept";
|
|
123
|
+
who?: string;
|
|
124
|
+
/** For gateway: the repo of the gateway whose route forwards the call. */
|
|
125
|
+
through?: string;
|
|
126
|
+
/** When it was answered or paired, the question answered, a pairing's reason (the caller's). */
|
|
127
|
+
at?: string;
|
|
128
|
+
question?: string;
|
|
129
|
+
reason?: string;
|
|
130
|
+
}
|
|
131
|
+
/** How a join was decided, in the kinds Connect says (the join's own words, never a guess). */
|
|
132
|
+
export declare function howOfJoin(j: FactsJoinResult["joins"][number]): CandidateHow;
|
|
133
|
+
export type SuggestWhy = "same-path" | "prefix" | "parameter" | "names-alike"
|
|
134
|
+
/** The call's path, with its settings resolved, is the API's. */
|
|
135
|
+
| "setting"
|
|
136
|
+
/** The call's words match the operation's name (operationId) or the route's. */
|
|
137
|
+
| "operation-words"
|
|
138
|
+
/** The call's path is what the gateway's route forwards to. */
|
|
139
|
+
| "forwarded-path";
|
|
140
|
+
export interface LinkCandidates {
|
|
141
|
+
calls: CandidateCall[];
|
|
142
|
+
apis: CandidateApi[];
|
|
143
|
+
}
|
|
144
|
+
/** A call's path with the settings it names filled in (`${api.base}/x` → `/v2/x`). */
|
|
145
|
+
export declare function resolvePath(p: string, settings: Readonly<Record<string, string>> | undefined): {
|
|
146
|
+
path: string;
|
|
147
|
+
resolved: boolean;
|
|
148
|
+
};
|
|
149
|
+
/** The words of a path or of a name that holds one (`requestRefundPath`), lower case. */
|
|
150
|
+
export declare function wordsOf(p: string): Set<string>;
|
|
151
|
+
/**
|
|
152
|
+
* How likely a call is the API: 0 to 1, and why. The best of: the paths as written, the call's
|
|
153
|
+
* path with its settings resolved, the path the API's route forwards to, and the words.
|
|
154
|
+
*/
|
|
155
|
+
export declare function pairScore(call: {
|
|
156
|
+
method?: string;
|
|
157
|
+
path: string;
|
|
158
|
+
}, api: {
|
|
159
|
+
method?: string;
|
|
160
|
+
path: string;
|
|
161
|
+
words?: string;
|
|
162
|
+
forwards?: string;
|
|
163
|
+
}, settings?: Readonly<Record<string, string>>): {
|
|
164
|
+
score: number;
|
|
165
|
+
why: SuggestWhy;
|
|
166
|
+
} | undefined;
|
|
167
|
+
/** The suggestion threshold: below it, a call gets none. */
|
|
168
|
+
export declare const SUGGEST_AT = 0.35;
|
|
169
|
+
/** A suggestion this sure, and this far ahead of the next, is confident: safe to pair unseen. */
|
|
170
|
+
export declare const CONFIDENT_AT = 0.85;
|
|
171
|
+
export declare const CONFIDENT_LEAD = 0.2;
|
|
172
|
+
export declare function linkCandidates(o: {
|
|
173
|
+
from: string;
|
|
174
|
+
facts: readonly Fact[];
|
|
175
|
+
join: Pick<FactsJoinResult, "joins" | "asks" | "misses" | "outside" | "left">;
|
|
176
|
+
apis: readonly CandidateApi[];
|
|
177
|
+
/** The pairings of `from` already on file, and the box they are with. */
|
|
178
|
+
pairs?: Readonly<Record<string, PersonPair>>;
|
|
179
|
+
/** The box B: a repo or an outside system id. */
|
|
180
|
+
to: {
|
|
181
|
+
repo?: string;
|
|
182
|
+
system?: string;
|
|
183
|
+
};
|
|
184
|
+
/** A's settings by key (its config facts with a value), to fill a call's `${key}` in. */
|
|
185
|
+
settings?: Readonly<Record<string, string>>;
|
|
186
|
+
/**
|
|
187
|
+
* Beta.28.1: whether the canvas draws a join's arrow (its Interface is in the catalog). A join
|
|
188
|
+
* of a call to its own component is never drawn, whatever this says. Default: every other is.
|
|
189
|
+
*/
|
|
190
|
+
drawn?: (j: FactsJoinResult["joins"][number]) => boolean;
|
|
191
|
+
/**
|
|
192
|
+
* Beta.28.1: whether the canvas draws a call placed outside the estate to this target (an
|
|
193
|
+
* outside system of the profile takes it). Default: none is, so the call is listed loose.
|
|
194
|
+
*/
|
|
195
|
+
drawnOutside?: (target: string, call: string) => boolean;
|
|
196
|
+
/**
|
|
197
|
+
* Whether a repo, a component or a system is drawn in the box connected to (a repo's own id,
|
|
198
|
+
* its components; a system's repos and their components). Default: the box's own id only.
|
|
199
|
+
*/
|
|
200
|
+
inBox?: (name: string) => boolean;
|
|
201
|
+
/**
|
|
202
|
+
* The review of beta.28.1 (S4): the box the built catalog draws a call's arrow to (an
|
|
203
|
+
* Interface current in it citing the call's line), for a call the join doesn't place: the
|
|
204
|
+
* canvas is what the person sees, so a drawn call is never listed as loose.
|
|
205
|
+
*/
|
|
206
|
+
drawnTo?: (call: string) => string | undefined;
|
|
207
|
+
/**
|
|
208
|
+
* ADR 0199, the review (S5): whether the catalog has the join's own Interface (by its id), not
|
|
209
|
+
* only one citing the call's line: the arrow of exactly this call to exactly this entry.
|
|
210
|
+
*/
|
|
211
|
+
drawnExact?: (j: FactsJoinResult["joins"][number]) => boolean;
|
|
212
|
+
/**
|
|
213
|
+
* ADR 0199, the review (S5): every box the catalog draws an arrow to from the call's line (two
|
|
214
|
+
* calls on one line each have one). Default: `drawnTo`'s one box.
|
|
215
|
+
*/
|
|
216
|
+
drawnBoxes?: (call: string) => readonly string[];
|
|
217
|
+
/**
|
|
218
|
+
* ADR 0199 (M1): the targets a call's answered question names, by call fact id, and of them
|
|
219
|
+
* those the AI answered: with them an AI pairing a person's answer outranks is told by the
|
|
220
|
+
* join's own rule. Left out, no pairing is said to be outranked.
|
|
221
|
+
*/
|
|
222
|
+
targets?: Readonly<Record<string, string>>;
|
|
223
|
+
aiTargets?: Readonly<Record<string, unknown>>;
|
|
224
|
+
}): LinkCandidates;
|
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import type { CatalogRecord } from "./catalog.js";
|
|
3
|
+
import { type FactsJoinResult, type JoinRepo } from "./facts-join.js";
|
|
4
|
+
import type { EvidenceT } from "./schema/common.js";
|
|
5
|
+
/**
|
|
6
|
+
* Links confirmed from outside the code (ADR 0151): contract files a consumer keeps (J3) and
|
|
7
|
+
* traffic exports a person imported as aggregate counts (J4). Neither makes a link: the join
|
|
8
|
+
* makes links from cited code. They add evidence and a flag to an Interface the join already
|
|
9
|
+
* made, and say where the two disagree: a contract or traffic the join has no link for, a
|
|
10
|
+
* contract naming another provider, a link no traffic used over the range.
|
|
11
|
+
*
|
|
12
|
+
* A contract or traffic never raises a guess (`inferred`) to verified: a guess stays a guess
|
|
13
|
+
* until the code names the callee (ADR 0151 §3). Pure: the same join and evidence files give
|
|
14
|
+
* the same marks and findings, whatever order they come in.
|
|
15
|
+
*/
|
|
16
|
+
/** An Interface a consumer's contract file (a Pact interaction, a consumer-side OpenAPI operation) confirms. */
|
|
17
|
+
export declare const CONFIRMED_BY_CONTRACT = "confirmed-by-contract";
|
|
18
|
+
/** An Interface a contract file names another provider for: a gap a person settles. */
|
|
19
|
+
export declare const CONTRACT_DISAGREES = "contract-disagrees";
|
|
20
|
+
/** An Interface an imported traffic export shows used over its range. */
|
|
21
|
+
export declare const SEEN_IN_TRAFFIC = "seen-in-traffic";
|
|
22
|
+
/** The flags this module writes, and takes off again before every write. */
|
|
23
|
+
export declare const LINK_EVIDENCE_FLAGS: ReadonlySet<string>;
|
|
24
|
+
/** The flags that are evidence a link holds, never a gap (as `JOIN_HOW_FLAGS`). */
|
|
25
|
+
export declare const LINK_EVIDENCE_NOT_GAPS: ReadonlySet<string>;
|
|
26
|
+
/** The `extractor` of the evidence this module adds, so a write takes the last write's off. */
|
|
27
|
+
export declare const CONTRACT_EVIDENCE = "atticus-contract@1";
|
|
28
|
+
export declare const TRAFFIC_EVIDENCE = "atticus-traffic@1";
|
|
29
|
+
/** One request a consumer's contract file says it makes. */
|
|
30
|
+
export declare const ContractEntry: z.ZodObject<{
|
|
31
|
+
format: z.ZodEnum<{
|
|
32
|
+
openapi: "openapi";
|
|
33
|
+
pact: "pact";
|
|
34
|
+
}>;
|
|
35
|
+
file: z.ZodString;
|
|
36
|
+
line: z.ZodNumber;
|
|
37
|
+
consumer: z.ZodOptional<z.ZodString>;
|
|
38
|
+
provider: z.ZodOptional<z.ZodString>;
|
|
39
|
+
hosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
40
|
+
method: z.ZodOptional<z.ZodString>;
|
|
41
|
+
path: z.ZodString;
|
|
42
|
+
}, z.core.$strict>;
|
|
43
|
+
export type ContractEntryT = z.infer<typeof ContractEntry>;
|
|
44
|
+
/**
|
|
45
|
+
* The facts companion `<repo>.contracts.yaml` (ADR 0151): the contract files read in a repo's
|
|
46
|
+
* checkout at the facts' commit by `atticus verify <repo> --write`, so every later write of any
|
|
47
|
+
* repo reads the same entries without the checkout.
|
|
48
|
+
*/
|
|
49
|
+
export declare const ContractsFile: z.ZodObject<{
|
|
50
|
+
schemaVersion: z.ZodLiteral<1>;
|
|
51
|
+
repo: z.ZodString;
|
|
52
|
+
commit: z.ZodOptional<z.ZodString>;
|
|
53
|
+
entries: z.ZodArray<z.ZodObject<{
|
|
54
|
+
format: z.ZodEnum<{
|
|
55
|
+
openapi: "openapi";
|
|
56
|
+
pact: "pact";
|
|
57
|
+
}>;
|
|
58
|
+
file: z.ZodString;
|
|
59
|
+
line: z.ZodNumber;
|
|
60
|
+
consumer: z.ZodOptional<z.ZodString>;
|
|
61
|
+
provider: z.ZodOptional<z.ZodString>;
|
|
62
|
+
hosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
63
|
+
method: z.ZodOptional<z.ZodString>;
|
|
64
|
+
path: z.ZodString;
|
|
65
|
+
}, z.core.$strict>>;
|
|
66
|
+
}, z.core.$strict>;
|
|
67
|
+
export type ContractsFileT = z.infer<typeof ContractsFile>;
|
|
68
|
+
/** One aggregate of an imported traffic export: never a raw row. */
|
|
69
|
+
export declare const TrafficRow: z.ZodObject<{
|
|
70
|
+
app: z.ZodString;
|
|
71
|
+
component: z.ZodOptional<z.ZodString>;
|
|
72
|
+
method: z.ZodString;
|
|
73
|
+
path: z.ZodString;
|
|
74
|
+
proxy: z.ZodOptional<z.ZodString>;
|
|
75
|
+
basepath: z.ZodOptional<z.ZodString>;
|
|
76
|
+
count: z.ZodNumber;
|
|
77
|
+
}, z.core.$strict>;
|
|
78
|
+
export type TrafficRowT = z.infer<typeof TrafficRow>;
|
|
79
|
+
/** `evidence/traffic/<source>-<from>-<to>.yaml`: what an import kept, reviewed in a pull request. */
|
|
80
|
+
export declare const TrafficFile: z.ZodObject<{
|
|
81
|
+
schemaVersion: z.ZodLiteral<1>;
|
|
82
|
+
source: z.ZodString;
|
|
83
|
+
from: z.ZodString;
|
|
84
|
+
to: z.ZodString;
|
|
85
|
+
inputSha256: z.ZodString;
|
|
86
|
+
rows: z.ZodArray<z.ZodObject<{
|
|
87
|
+
app: z.ZodString;
|
|
88
|
+
component: z.ZodOptional<z.ZodString>;
|
|
89
|
+
method: z.ZodString;
|
|
90
|
+
path: z.ZodString;
|
|
91
|
+
proxy: z.ZodOptional<z.ZodString>;
|
|
92
|
+
basepath: z.ZodOptional<z.ZodString>;
|
|
93
|
+
count: z.ZodNumber;
|
|
94
|
+
}, z.core.$strict>>;
|
|
95
|
+
}, z.core.$strict>;
|
|
96
|
+
export type TrafficFileT = z.infer<typeof TrafficFile>;
|
|
97
|
+
/** The file name a traffic aggregate is written under. */
|
|
98
|
+
export declare const trafficFileName: (f: Pick<TrafficFileT, "source" | "from" | "to">) => string;
|
|
99
|
+
/** The canonical text of a traffic aggregate: keys in schema order, one row a block. */
|
|
100
|
+
export declare function trafficFileText(f: TrafficFileT): string;
|
|
101
|
+
/** A traffic file read back, each row with the line it starts on (what its evidence cites). */
|
|
102
|
+
export interface TrafficOnFile {
|
|
103
|
+
/** Its path in the metarepo, forward slashes (`evidence/traffic/...`). */
|
|
104
|
+
rel: string;
|
|
105
|
+
file: TrafficFileT;
|
|
106
|
+
lines: number[];
|
|
107
|
+
}
|
|
108
|
+
/** Read a traffic aggregate with its rows' lines; a problem when it isn't one. */
|
|
109
|
+
export declare function readTrafficFile(rel: string, text: string): {
|
|
110
|
+
ok: true;
|
|
111
|
+
traffic: TrafficOnFile;
|
|
112
|
+
} | {
|
|
113
|
+
ok: false;
|
|
114
|
+
message: string;
|
|
115
|
+
};
|
|
116
|
+
/** A link end as a finding names it. */
|
|
117
|
+
export interface LinkRef {
|
|
118
|
+
interface: string;
|
|
119
|
+
from: string;
|
|
120
|
+
to: string;
|
|
121
|
+
method?: string;
|
|
122
|
+
path: string;
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* What a contract file says that the join doesn't: `provider-differs` (the consumer's request is
|
|
126
|
+
* a link the join made to another component), `no-link` (the join has no link for it),
|
|
127
|
+
* `unknown-provider` (the provider it names is no component or repo of the estate).
|
|
128
|
+
*/
|
|
129
|
+
export interface ContractFinding {
|
|
130
|
+
reason: "provider-differs" | "no-link" | "unknown-provider";
|
|
131
|
+
repo: string;
|
|
132
|
+
/** file:line in the consumer's repo. */
|
|
133
|
+
at: string;
|
|
134
|
+
format: "pact" | "openapi";
|
|
135
|
+
consumer: string;
|
|
136
|
+
provider?: string;
|
|
137
|
+
method?: string;
|
|
138
|
+
path: string;
|
|
139
|
+
/** The links the request matched (for `provider-differs`, `unknown-provider`). */
|
|
140
|
+
links: LinkRef[];
|
|
141
|
+
message: string;
|
|
142
|
+
}
|
|
143
|
+
/**
|
|
144
|
+
* What a traffic export says that the join doesn't: `missed-link` (traffic no link carries),
|
|
145
|
+
* `unknown-app` (an app named like no component: a person names it in the row's `component`),
|
|
146
|
+
* `unseen-link` (a link the export covers that no traffic used over the range).
|
|
147
|
+
*/
|
|
148
|
+
export interface TrafficFinding {
|
|
149
|
+
reason: "missed-link" | "unknown-app" | "unseen-link";
|
|
150
|
+
/** The traffic file, and the row's line (not for `unseen-link`). */
|
|
151
|
+
file: string;
|
|
152
|
+
at?: string;
|
|
153
|
+
range: {
|
|
154
|
+
from: string;
|
|
155
|
+
to: string;
|
|
156
|
+
};
|
|
157
|
+
app?: string;
|
|
158
|
+
component?: string;
|
|
159
|
+
method?: string;
|
|
160
|
+
path?: string;
|
|
161
|
+
count?: number;
|
|
162
|
+
link?: LinkRef;
|
|
163
|
+
message: string;
|
|
164
|
+
}
|
|
165
|
+
/** A link the traffic showed, with how much and over what range. */
|
|
166
|
+
export interface TrafficSeen extends LinkRef {
|
|
167
|
+
count: number;
|
|
168
|
+
file: string;
|
|
169
|
+
range: {
|
|
170
|
+
from: string;
|
|
171
|
+
to: string;
|
|
172
|
+
};
|
|
173
|
+
}
|
|
174
|
+
export interface LinkEvidenceResult {
|
|
175
|
+
/** By Interface id: the flags and evidence to add. */
|
|
176
|
+
marks: Record<string, {
|
|
177
|
+
flags: string[];
|
|
178
|
+
evidence: EvidenceT[];
|
|
179
|
+
}>;
|
|
180
|
+
contracts: {
|
|
181
|
+
entries: number;
|
|
182
|
+
confirmed: LinkRef[];
|
|
183
|
+
findings: ContractFinding[];
|
|
184
|
+
};
|
|
185
|
+
traffic: {
|
|
186
|
+
rows: number;
|
|
187
|
+
seen: TrafficSeen[];
|
|
188
|
+
findings: TrafficFinding[];
|
|
189
|
+
};
|
|
190
|
+
}
|
|
191
|
+
export interface LinkEvidenceInput {
|
|
192
|
+
/** The whole estate's join (every repo with verified facts). */
|
|
193
|
+
join: FactsJoinResult;
|
|
194
|
+
repos: readonly JoinRepo[];
|
|
195
|
+
contracts?: readonly ContractsFileT[];
|
|
196
|
+
traffic?: readonly TrafficOnFile[];
|
|
197
|
+
}
|
|
198
|
+
/**
|
|
199
|
+
* Mark the joins the contract files and traffic aggregates bear out, and list where they and the
|
|
200
|
+
* join disagree (ADR 0151).
|
|
201
|
+
*/
|
|
202
|
+
export declare function linkEvidenceOf(input: LinkEvidenceInput): LinkEvidenceResult;
|
|
203
|
+
/**
|
|
204
|
+
* The records without what an earlier write's contract and traffic evidence added: its flags and
|
|
205
|
+
* evidence entries. A record left with no evidence at all (none could be) is dropped.
|
|
206
|
+
*/
|
|
207
|
+
export declare function stripLinkEvidence(records: readonly CatalogRecord[]): CatalogRecord[];
|
|
208
|
+
/**
|
|
209
|
+
* The records with the marks added: each marked Interface gets its flags (after its own) and
|
|
210
|
+
* evidence (after its own, each line once). Its confidence is never changed (ADR 0151 §3).
|
|
211
|
+
*/
|
|
212
|
+
export declare function applyLinkEvidence(records: readonly CatalogRecord[], marks: LinkEvidenceResult["marks"]): CatalogRecord[];
|
package/npm/core/log.d.ts
CHANGED
|
@@ -45,5 +45,7 @@ export declare function createLog(root: string, o?: {
|
|
|
45
45
|
maxBytes?: number;
|
|
46
46
|
keep?: number;
|
|
47
47
|
}): Log;
|
|
48
|
+
/** ensureLocalIgnore, for the log's synchronous writes (and a terminal run's, ADR 0187). */
|
|
49
|
+
export declare function ignoreLocalSync(root: string): void;
|
|
48
50
|
/** A log that writes nothing (tests, and commands run with no metarepo). */
|
|
49
51
|
export declare const NO_LOG: Log;
|