@maycombhq/sdk 2.0.0-beta.2 → 2.0.0-beta.22
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 +5890 -1210
- package/npm/core/audit.d.ts +165 -0
- package/npm/core/catalog.d.ts +220 -66
- package/npm/core/cite.d.ts +20 -4
- package/npm/core/contract-check.d.ts +261 -0
- package/npm/core/decision-batches.d.ts +29 -0
- package/npm/core/declared-links.d.ts +62 -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 +2 -0
- package/npm/core/facts-carry.d.ts +8 -2
- package/npm/core/facts-join-prototype.d.ts +66 -4
- package/npm/core/facts-join-vendor.d.ts +20 -2
- package/npm/core/facts-join.d.ts +325 -1
- package/npm/core/facts-terms.d.ts +108 -0
- package/npm/core/fs.d.ts +40 -4
- package/npm/core/glob.d.ts +14 -0
- package/npm/core/host-questions.d.ts +93 -1
- package/npm/core/identity.d.ts +28 -0
- package/npm/core/index.d.ts +24 -0
- package/npm/core/link-candidates.d.ts +103 -0
- package/npm/core/link-evidence.d.ts +212 -0
- package/npm/core/manifest-edit.d.ts +53 -4
- package/npm/core/merge.d.ts +28 -0
- package/npm/core/metarepo.d.ts +18 -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 +22 -6
- package/npm/core/orgpack-load.d.ts +19 -0
- package/npm/core/profile-migrate.d.ts +11 -0
- package/npm/core/question-order.d.ts +23 -0
- package/npm/core/question-owners.d.ts +53 -0
- package/npm/core/question-proposals.d.ts +77 -0
- package/npm/core/question-roles.d.ts +24 -0
- package/npm/core/questions.d.ts +90 -6
- package/npm/core/repo-files.d.ts +60 -0
- package/npm/core/repo-reads.d.ts +44 -0
- package/npm/core/roles-migrate.d.ts +9 -0
- package/npm/core/runtime-migrate.d.ts +18 -0
- package/npm/core/schema/ai.d.ts +57 -9
- 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/fact-corrections.d.ts +105 -2
- package/npm/core/schema/facts.d.ts +410 -1
- package/npm/core/schema/kinds.d.ts +230 -66
- package/npm/core/schema/orgpack.d.ts +159 -19
- package/npm/core/schema/question.d.ts +228 -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 +7 -7
- package/npm/core/schema/scan-verify.d.ts +87 -45
- package/npm/core/schema/version.d.ts +4 -1
- package/npm/core/schema/workspace.d.ts +29 -11
- package/npm/core/shared-maps.d.ts +146 -0
- package/npm/core/stack-helpers.d.ts +32 -0
- package/npm/fs-repo.d.ts +2 -1
- package/npm/index.js +6194 -2542
- package/npm/listing.d.ts +14 -0
- package/package.json +1 -1
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { type LineChange } from "./manifest-edit.js";
|
|
1
2
|
/**
|
|
2
3
|
* Which repo answers on a host (ADR 0088): a scan or atticus estate join asks, as a question
|
|
3
4
|
* file (ADR 0078), for each host the estate's calls name that no repo lists in its `hosts`;
|
|
@@ -5,20 +6,111 @@
|
|
|
5
6
|
*/
|
|
6
7
|
/** The step that asks which repo answers on a host. */
|
|
7
8
|
export declare const HOSTS_STEP = "scan-hosts";
|
|
9
|
+
/**
|
|
10
|
+
* The step that asks which repo or system answers a call with no target (the scanner's
|
|
11
|
+
* TARGETS_STEP), and its group question's option that says the calls go to more than one place:
|
|
12
|
+
* named here so an answer's rule (ADR 0153) is checked where it is written.
|
|
13
|
+
*/
|
|
14
|
+
export declare const TARGETS_STEP_ID = "facts-targets";
|
|
15
|
+
export declare const TARGETS_SPLIT_LABEL = "Not all to one place";
|
|
16
|
+
/**
|
|
17
|
+
* ADR 0162 (F8): the option of a targets question that opens the picker of the whole estate (the
|
|
18
|
+
* manifest's repos, the profiles' systems, the teams). It names nothing: it is never an answer.
|
|
19
|
+
*/
|
|
20
|
+
export declare const TARGETS_ANOTHER_LABEL = "Another repo\u2026";
|
|
21
|
+
/**
|
|
22
|
+
* ADR 0162 (F8): the step that asks who owns a topic or queue the repo publishes to or listens on
|
|
23
|
+
* that no estate repo serves the other side of, and its option that opens the picker (a system of
|
|
24
|
+
* the profile, or a team): the answer adds the topic to that system's aliases, so the merge lands
|
|
25
|
+
* the publish or the listener on it, as a file change for review.
|
|
26
|
+
*/
|
|
27
|
+
export declare const TOPICS_STEP_ID = "facts-topics";
|
|
28
|
+
export declare const TOPICS_OUTSIDE_LABEL = "A topic owned by another team or vendor";
|
|
29
|
+
/** A topics question's words: what the repo does with the topic, and the topic. */
|
|
30
|
+
export declare const topicQuestionText: (topic: string, component: string, side: "publish" | "listen") => string;
|
|
31
|
+
/** The topic a topics question asks about, read back from its words. */
|
|
32
|
+
export declare function topicOfQuestion(q: {
|
|
33
|
+
question: string;
|
|
34
|
+
}): string | undefined;
|
|
35
|
+
/** The options that open the picker: they name nothing, so they are never an answer. */
|
|
36
|
+
export declare const PICKER_LABELS: ReadonlySet<string>;
|
|
8
37
|
/** The last option of a hosts question: no repo of the estate answers on it. */
|
|
9
38
|
export declare const HOSTS_NONE = "None of these";
|
|
39
|
+
/**
|
|
40
|
+
* The options of a hosts question that say an outside system answers on the host (O1): another
|
|
41
|
+
* team's system (boundary internal, the first, the default) or a vendor's. The answer writes the
|
|
42
|
+
* system into the profile of the repo that asked, with the host as its alias, so the calls to
|
|
43
|
+
* the host go to it (F3: a declared system no estate repo belongs to is outside).
|
|
44
|
+
*/
|
|
45
|
+
export declare const HOSTS_OUTSIDE_INTERNAL = "An outside system (new): another team's";
|
|
46
|
+
export declare const HOSTS_OUTSIDE_VENDOR = "An outside system (new): a vendor";
|
|
47
|
+
/** The boundary an outside-system option of a hosts question gives its system, if it is one. */
|
|
48
|
+
export declare function outsideBoundaryOf(label: string | undefined): "internal" | "vendor" | undefined;
|
|
49
|
+
/** The system an outside-system answer adds for a host: its id and name, both from the host. */
|
|
50
|
+
export declare function outsideSystemOf(host: string): {
|
|
51
|
+
id: string;
|
|
52
|
+
name: string;
|
|
53
|
+
};
|
|
10
54
|
/** The question for a host, with its port when the calls name one: localhost:9966. */
|
|
11
55
|
export declare const hostQuestionText: (host: string) => string;
|
|
12
56
|
/** The host a hosts question asks about, read back from its words. */
|
|
13
57
|
export declare function hostOfQuestion(q: {
|
|
14
58
|
question: string;
|
|
15
59
|
}): string | undefined;
|
|
60
|
+
/**
|
|
61
|
+
* Put an outside system for a host into the profile whose repos.manifest.yaml lists the repo
|
|
62
|
+
* that asked (O1): its id and name from the host, the host as its alias, the boundary given
|
|
63
|
+
* (internal: another team's; vendor). The profile keeps its comments and order, and is made,
|
|
64
|
+
* with the platform's id as its name, when there is none. `added` is false when a system of the
|
|
65
|
+
* profiles already names the host. Throws when no manifest lists the repo, or the profile would
|
|
66
|
+
* not be valid (an id another system has).
|
|
67
|
+
*/
|
|
68
|
+
export declare function addOutsideSystem(root: string, repo: string, host: string, boundary: "internal" | "vendor"): Promise<{
|
|
69
|
+
id: string;
|
|
70
|
+
profile: string;
|
|
71
|
+
added: boolean;
|
|
72
|
+
}>;
|
|
73
|
+
/**
|
|
74
|
+
* ADR 0162 (F8): put a system a person named in a targets answer into the profile whose
|
|
75
|
+
* repos.manifest.yaml lists the repo that asked: a vendor (boundary vendor), or another team's
|
|
76
|
+
* system (boundary internal, owner the team's id from roles.yaml). Written as a file change in the
|
|
77
|
+
* metarepo, for review in the pull request, never to a shared system. `added` is false when a
|
|
78
|
+
* system of the profiles already has the id. Throws when no manifest lists the repo, or the
|
|
79
|
+
* profile would not be valid.
|
|
80
|
+
*/
|
|
81
|
+
export declare function addProfileSystem(root: string, repo: string, s: {
|
|
82
|
+
id: string;
|
|
83
|
+
name: string;
|
|
84
|
+
boundary: "internal" | "vendor";
|
|
85
|
+
owner?: string;
|
|
86
|
+
/**
|
|
87
|
+
* The topics and queues it owns (ADR 0162 amendment): written under `topics`, never
|
|
88
|
+
* `aliases`, with the profile at schema version 2.
|
|
89
|
+
*/
|
|
90
|
+
topics?: string[];
|
|
91
|
+
}, o?: {
|
|
92
|
+
preview?: boolean;
|
|
93
|
+
}): Promise<{
|
|
94
|
+
id: string;
|
|
95
|
+
profile: string;
|
|
96
|
+
added: boolean;
|
|
97
|
+
topics?: string[];
|
|
98
|
+
/** The lines a new system changes in the profile (as the write makes them). */
|
|
99
|
+
changes?: LineChange[];
|
|
100
|
+
}>;
|
|
16
101
|
/**
|
|
17
102
|
* Put a host under a repo's `hosts` in the repos.manifest.yaml that lists it, keeping the
|
|
18
103
|
* file's comments and order. `added` is false when the repo already lists it. Throws when no
|
|
19
104
|
* manifest lists the repo, or the host isn't one the manifest takes.
|
|
20
105
|
*/
|
|
21
|
-
export declare function addManifestHost(root: string, repo: string, host: string
|
|
106
|
+
export declare function addManifestHost(root: string, repo: string, host: string,
|
|
107
|
+
/**
|
|
108
|
+
* ADR 0153 (Q2): the path the repo answers under on the host, from an answer's path rule, set
|
|
109
|
+
* as its `basePath`. Refused when the repo gives another one.
|
|
110
|
+
*/
|
|
111
|
+
o?: {
|
|
112
|
+
basePath?: string;
|
|
113
|
+
}): Promise<{
|
|
22
114
|
manifest: string;
|
|
23
115
|
added: boolean;
|
|
24
116
|
}>;
|
package/npm/core/identity.d.ts
CHANGED
|
@@ -8,6 +8,21 @@
|
|
|
8
8
|
* - topics (no leading slash in the input and no "/" at all) are returned trimmed
|
|
9
9
|
*/
|
|
10
10
|
export declare function normalizePath(input: string): string;
|
|
11
|
+
/**
|
|
12
|
+
* A path with each `{...}` parameter cut to its name: what follows the first `:`, `?` or `=` in
|
|
13
|
+
* braces nested inside a constraint (`{code:regex(^\\d{3}$)}`) are matched, not cut at the first `}`.
|
|
14
|
+
* braces nested inside a constraint (`{code:regex(^\\d{{3}}$)}`) are matched, not cut at the first `}`.
|
|
15
|
+
* An unclosed `{` leaves the rest as written.
|
|
16
|
+
*/
|
|
17
|
+
export declare function stripParamConstraints(path: string): string;
|
|
18
|
+
/** Code-unit string order, the same in every locale (`localeCompare` is not: ICU orders `_`/`-`
|
|
19
|
+
* and, in `da`, `aa` differently), for every sort that feeds records, ids, hashes or a merge. */
|
|
20
|
+
export declare function cmpText(a: string, b: string): number;
|
|
21
|
+
/**
|
|
22
|
+
* `cmpText`, but a run of digits is compared as a number (`a.ts:9` before `a.ts:10`): what
|
|
23
|
+
* `localeCompare(b, "en", { numeric: true })` was used for, without ICU.
|
|
24
|
+
*/
|
|
25
|
+
export declare function cmpNatural(a: string, b: string): number;
|
|
11
26
|
/**
|
|
12
27
|
* Stable interface id: a hash of caller, callee, method and normalised path, so the same
|
|
13
28
|
* edge seen by several extractors merges into one Interface record.
|
|
@@ -15,3 +30,16 @@ export declare function normalizePath(input: string): string;
|
|
|
15
30
|
export declare function interfaceId(from: string, to: string, method: string | undefined, path: string): string;
|
|
16
31
|
/** Lowercase slug suitable as a record id, built from free text such as a system name. */
|
|
17
32
|
export declare function slugify(text: string): string;
|
|
33
|
+
/**
|
|
34
|
+
* Round 47: a name with no Latin letter or digit in it (`注文`, `Заказы`, `...`) slugs to
|
|
35
|
+
* nothing, so every such name used to become the same `unnamed` and their records merged.
|
|
36
|
+
* It gets `unnamed-<short hash of the name>` instead: stable, and different per name. Blank
|
|
37
|
+
* text stays `unnamed`.
|
|
38
|
+
*/
|
|
39
|
+
export declare function unnamedId(text: string): string;
|
|
40
|
+
/**
|
|
41
|
+
* A slug that is never a Windows device name (review round 46): a record is the file
|
|
42
|
+
* `<kind>/<id>.yaml` and Windows can't create `aux.yaml`, so the slug's first dot-separated part,
|
|
43
|
+
* when it is one, gets `-1` (`aux` is `aux-1`, `con.v2` is `con-1.v2`). C1's RecordId is unchanged.
|
|
44
|
+
*/
|
|
45
|
+
export declare function notDeviceName(slug: string): string;
|
package/npm/core/index.d.ts
CHANGED
|
@@ -3,12 +3,20 @@ 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 "./fact-paths.js";
|
|
6
7
|
export * from "./migration-files.js";
|
|
7
8
|
export * from "./facts-join.js";
|
|
8
9
|
export * from "./facts-join-vendor.js";
|
|
9
10
|
export * from "./facts-join-prototype.js";
|
|
10
11
|
export * from "./facts-carry.js";
|
|
11
12
|
export * from "./facts-callers.js";
|
|
13
|
+
export * from "./facts-terms.js";
|
|
14
|
+
export * from "./org-notes.js";
|
|
15
|
+
export * from "./link-evidence.js";
|
|
16
|
+
export * from "./shared-maps.js";
|
|
17
|
+
export * from "./contract-check.js";
|
|
18
|
+
export * from "./audit.js";
|
|
19
|
+
export * from "./stack-helpers.js";
|
|
12
20
|
export * from "./cite.js";
|
|
13
21
|
export * from "./catalog.js";
|
|
14
22
|
export * from "./identity.js";
|
|
@@ -23,10 +31,12 @@ export * from "./schema/frameworks.js";
|
|
|
23
31
|
export * from "./schema/scan-settings.js";
|
|
24
32
|
export * from "./schema/scan-verify.js";
|
|
25
33
|
export * from "./schema/repo-type.js";
|
|
34
|
+
export * from "./schema/component-type.js";
|
|
26
35
|
export * from "./schema/layout.js";
|
|
27
36
|
export * from "./schema/plugin.js";
|
|
28
37
|
export * from "./schema/review.js";
|
|
29
38
|
export * from "./schema/orgpack.js";
|
|
39
|
+
export * from "./schema/conventions.js";
|
|
30
40
|
export * from "./schema/executors.js";
|
|
31
41
|
export * from "./orgpack-defaults.js";
|
|
32
42
|
export * from "./orgpack-load.js";
|
|
@@ -41,8 +51,12 @@ export * from "./gates-migrate.js";
|
|
|
41
51
|
export * from "./change-types-migrate.js";
|
|
42
52
|
export * from "./sources-migrate.js";
|
|
43
53
|
export * from "./runtime-migrate.js";
|
|
54
|
+
export * from "./roles-migrate.js";
|
|
55
|
+
export * from "./profile-migrate.js";
|
|
44
56
|
export * from "./metarepo.js";
|
|
45
57
|
export * from "./fs.js";
|
|
58
|
+
export * from "./glob.js";
|
|
59
|
+
export * from "./repo-files.js";
|
|
46
60
|
export * from "./record-cache.js";
|
|
47
61
|
export * from "./log.js";
|
|
48
62
|
export * from "./zip.js";
|
|
@@ -54,9 +68,19 @@ export * from "./questions.js";
|
|
|
54
68
|
export * from "./schema/judgment.js";
|
|
55
69
|
export * from "./judgments.js";
|
|
56
70
|
export * from "./host-questions.js";
|
|
71
|
+
export * from "./repo-reads.js";
|
|
72
|
+
export * from "./question-order.js";
|
|
73
|
+
export * from "./question-owners.js";
|
|
74
|
+
export * from "./question-roles.js";
|
|
75
|
+
export * from "./question-proposals.js";
|
|
57
76
|
export * from "./repo-description.js";
|
|
58
77
|
export * from "./manifest-edit.js";
|
|
59
78
|
export * from "./schema/spec.js";
|
|
60
79
|
export * from "./specs.js";
|
|
61
80
|
export * from "./cancel.js";
|
|
62
81
|
export * from "./assistant-actor.js";
|
|
82
|
+
export * from "./link-candidates.js";
|
|
83
|
+
export * from "./ai-decisions.js";
|
|
84
|
+
export * from "./decision-batches.js";
|
|
85
|
+
export * from "./declared-links.js";
|
|
86
|
+
export * from "./schema/reading-rules.js";
|
|
@@ -0,0 +1,103 @@
|
|
|
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
|
+
export interface CandidateApi {
|
|
13
|
+
/** The entry's fact id, or the operation's id in the spec. */
|
|
14
|
+
id: string;
|
|
15
|
+
kind: "entry" | "route" | "operation";
|
|
16
|
+
method?: string;
|
|
17
|
+
path: string;
|
|
18
|
+
/** file:line, for an entry. */
|
|
19
|
+
at?: string;
|
|
20
|
+
/** Words that name it besides its path: a spec operation's operationId, a route's name. */
|
|
21
|
+
words?: string;
|
|
22
|
+
/** A gateway route: the path it forwards to (what the service behind it serves). */
|
|
23
|
+
forwards?: string;
|
|
24
|
+
}
|
|
25
|
+
export interface CandidateCall {
|
|
26
|
+
fact: string;
|
|
27
|
+
callType: string;
|
|
28
|
+
method?: string;
|
|
29
|
+
path: string;
|
|
30
|
+
at: string;
|
|
31
|
+
status: LooseStatus;
|
|
32
|
+
/** What the join said: the reason it left it, the target it missed, the host it asked about. */
|
|
33
|
+
why?: string;
|
|
34
|
+
/** For paired: the API it is paired with. */
|
|
35
|
+
paired?: string;
|
|
36
|
+
suggestion?: {
|
|
37
|
+
api: string;
|
|
38
|
+
score: number;
|
|
39
|
+
why: SuggestWhy;
|
|
40
|
+
};
|
|
41
|
+
/** The APIs it most likely is, best first (at most three); the first is `suggestion`. */
|
|
42
|
+
suggestions?: {
|
|
43
|
+
api: string;
|
|
44
|
+
score: number;
|
|
45
|
+
why: SuggestWhy;
|
|
46
|
+
}[];
|
|
47
|
+
/** The best is well ahead of the rest and scores high: safe to pair without a look. */
|
|
48
|
+
confident?: boolean;
|
|
49
|
+
}
|
|
50
|
+
export type SuggestWhy = "same-path" | "prefix" | "parameter" | "names-alike"
|
|
51
|
+
/** The call's path, with its settings resolved, is the API's. */
|
|
52
|
+
| "setting"
|
|
53
|
+
/** The call's words match the operation's name (operationId) or the route's. */
|
|
54
|
+
| "operation-words"
|
|
55
|
+
/** The call's path is what the gateway's route forwards to. */
|
|
56
|
+
| "forwarded-path";
|
|
57
|
+
export interface LinkCandidates {
|
|
58
|
+
calls: CandidateCall[];
|
|
59
|
+
apis: CandidateApi[];
|
|
60
|
+
}
|
|
61
|
+
/** A call's path with the settings it names filled in (`${api.base}/x` → `/v2/x`). */
|
|
62
|
+
export declare function resolvePath(p: string, settings: Readonly<Record<string, string>> | undefined): {
|
|
63
|
+
path: string;
|
|
64
|
+
resolved: boolean;
|
|
65
|
+
};
|
|
66
|
+
/** The words of a path or of a name that holds one (`requestRefundPath`), lower case. */
|
|
67
|
+
export declare function wordsOf(p: string): Set<string>;
|
|
68
|
+
/**
|
|
69
|
+
* How likely a call is the API: 0 to 1, and why. The best of: the paths as written, the call's
|
|
70
|
+
* path with its settings resolved, the path the API's route forwards to, and the words.
|
|
71
|
+
*/
|
|
72
|
+
export declare function pairScore(call: {
|
|
73
|
+
method?: string;
|
|
74
|
+
path: string;
|
|
75
|
+
}, api: {
|
|
76
|
+
method?: string;
|
|
77
|
+
path: string;
|
|
78
|
+
words?: string;
|
|
79
|
+
forwards?: string;
|
|
80
|
+
}, settings?: Readonly<Record<string, string>>): {
|
|
81
|
+
score: number;
|
|
82
|
+
why: SuggestWhy;
|
|
83
|
+
} | undefined;
|
|
84
|
+
/** The suggestion threshold: below it, a call gets none. */
|
|
85
|
+
export declare const SUGGEST_AT = 0.35;
|
|
86
|
+
/** A suggestion this sure, and this far ahead of the next, is confident: safe to pair unseen. */
|
|
87
|
+
export declare const CONFIDENT_AT = 0.85;
|
|
88
|
+
export declare const CONFIDENT_LEAD = 0.2;
|
|
89
|
+
export declare function linkCandidates(o: {
|
|
90
|
+
from: string;
|
|
91
|
+
facts: readonly Fact[];
|
|
92
|
+
join: Pick<FactsJoinResult, "joins" | "asks" | "misses" | "outside" | "left">;
|
|
93
|
+
apis: readonly CandidateApi[];
|
|
94
|
+
/** The pairings of `from` already on file, and the box they are with. */
|
|
95
|
+
pairs?: Readonly<Record<string, PersonPair>>;
|
|
96
|
+
/** The box B: a repo or an outside system id. */
|
|
97
|
+
to: {
|
|
98
|
+
repo?: string;
|
|
99
|
+
system?: string;
|
|
100
|
+
};
|
|
101
|
+
/** A's settings by key (its config facts with a value), to fill a call's `${key}` in. */
|
|
102
|
+
settings?: Readonly<Record<string, string>>;
|
|
103
|
+
}): 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[];
|
|
@@ -33,16 +33,65 @@ export declare function addManifestRepo(root: string, platform: string, entry: {
|
|
|
33
33
|
url: string;
|
|
34
34
|
type: string;
|
|
35
35
|
owner: string;
|
|
36
|
+
/** The branch to read, when known (a clone's current branch); the manifest's default is main. */
|
|
37
|
+
defaultBranch?: string;
|
|
36
38
|
system?: string;
|
|
37
39
|
component?: string;
|
|
38
40
|
description?: RepoDescription;
|
|
39
41
|
}): Promise<ManifestFile>;
|
|
40
42
|
/**
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
*
|
|
44
|
-
|
|
43
|
+
* F5: move a repo's id in the manifest that lists it, in place (comments and order kept). Refused
|
|
44
|
+
* when no manifest lists the repo, or any lists the new id already (ids are unique across every
|
|
45
|
+
* profile, ADR 0009). Only the id changes; the files filed under it are the caller's to move.
|
|
46
|
+
*/
|
|
47
|
+
export declare function renameManifestRepo(root: string, repo: string, to: string): Promise<ManifestFile>;
|
|
48
|
+
/**
|
|
49
|
+
* Rewrite every manifest at a version below `to` (the current one when left out) at that
|
|
50
|
+
* version, keeping its comments and order (ADR 0009, 0128, 0134). Nothing a person wrote
|
|
51
|
+
* changes: older manifests are read as they are and stay valid, and this only keeps diffs clean.
|
|
52
|
+
* `dryRun` lists what it would change.
|
|
45
53
|
*/
|
|
46
54
|
export declare function migrateManifests(root: string, o?: {
|
|
47
55
|
dryRun?: boolean;
|
|
56
|
+
to?: number;
|
|
48
57
|
}): Promise<string[]>;
|
|
58
|
+
/** A file's line ending, its text with LF only, and the text back in its own endings. */
|
|
59
|
+
export declare const eolOf: (raw: string) => "\r\n" | "\n";
|
|
60
|
+
export declare const lfOnly: (raw: string) => string;
|
|
61
|
+
export declare const inEol: (text: string, eol: "\r\n" | "\n") => string;
|
|
62
|
+
/** A line the edit changes: what it was (none when added) and what it is now. */
|
|
63
|
+
export interface LineChange {
|
|
64
|
+
was?: string;
|
|
65
|
+
now?: string;
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* The lines two texts differ in, in order: a line diff (longest common subsequence), each run of
|
|
69
|
+
* removed and added lines paired up as was and now. For a preview of a file's change.
|
|
70
|
+
*/
|
|
71
|
+
export declare function changedLines(before: string, after: string): LineChange[];
|
|
72
|
+
/**
|
|
73
|
+
* G2 (ADR 0174): set a repo's `owner` or `system` in the manifest that lists it, keeping the
|
|
74
|
+
* file's comments and order; checked before it is written. With `preview`, nothing is written:
|
|
75
|
+
* the lines it would change come back.
|
|
76
|
+
*/
|
|
77
|
+
export declare function setManifestField(root: string, repo: string, field: "owner" | "system", value: string, o?: {
|
|
78
|
+
preview?: boolean;
|
|
79
|
+
}): Promise<{
|
|
80
|
+
file: ManifestFile;
|
|
81
|
+
changes: LineChange[];
|
|
82
|
+
written: boolean;
|
|
83
|
+
}>;
|
|
84
|
+
/**
|
|
85
|
+
* G2 (ADR 0174): add a team to roles.yaml (moved to version 2 first when it is older), for
|
|
86
|
+
* review: its id and name, no people. With `preview`, nothing is written.
|
|
87
|
+
*/
|
|
88
|
+
export declare function addRolesTeam(root: string, team: {
|
|
89
|
+
id: string;
|
|
90
|
+
name: string;
|
|
91
|
+
}, o?: {
|
|
92
|
+
preview?: boolean;
|
|
93
|
+
}): Promise<{
|
|
94
|
+
rel: string;
|
|
95
|
+
changes: LineChange[];
|
|
96
|
+
written: boolean;
|
|
97
|
+
}>;
|
package/npm/core/merge.d.ts
CHANGED
|
@@ -21,6 +21,12 @@ export interface MergeRepo {
|
|
|
21
21
|
type: string;
|
|
22
22
|
/** Hosts the repo's component (or, for a gateway repo, the gateway) answers on (ADR 0053). */
|
|
23
23
|
hosts?: string[];
|
|
24
|
+
/**
|
|
25
|
+
* beta.18: the repo's facts are read, so its endpoints are known: a call to one of its hosts
|
|
26
|
+
* joins it only where one of them serves the call (the facts join's own rule). Unset, as
|
|
27
|
+
* before: a host the manifest lists joins every call to it.
|
|
28
|
+
*/
|
|
29
|
+
read?: boolean;
|
|
24
30
|
}
|
|
25
31
|
export interface MergeSystem {
|
|
26
32
|
id: string;
|
|
@@ -28,6 +34,8 @@ export interface MergeSystem {
|
|
|
28
34
|
boundary: "product" | "internal" | "vendor";
|
|
29
35
|
owner?: string;
|
|
30
36
|
aliases: string[];
|
|
37
|
+
/** ADR 0162 amendment: the topics and queues it owns, kept apart from its aliases. */
|
|
38
|
+
topics?: string[];
|
|
31
39
|
/** Copied to the System record (ADR 0040: saas marks a SaaS vendor). */
|
|
32
40
|
tags?: string[];
|
|
33
41
|
}
|
|
@@ -42,8 +50,19 @@ export interface MergePattern {
|
|
|
42
50
|
sameSystem?: boolean;
|
|
43
51
|
};
|
|
44
52
|
}
|
|
53
|
+
/**
|
|
54
|
+
* ADR 0162 (F8): the flag on an Interface a topic or queue makes to an outside system because the
|
|
55
|
+
* profile names the topic under the system's topics: a person's word, not the code's.
|
|
56
|
+
*/
|
|
57
|
+
export declare const DECLARED_TOPIC = "declared-topic";
|
|
45
58
|
export interface MergeInput {
|
|
46
59
|
records: CatalogRecord[];
|
|
60
|
+
/**
|
|
61
|
+
* The component type ids the organisation has (ADR 0180: the built-ins with the org pack's
|
|
62
|
+
* applied). A Component's type that is one of these is never replaced by a repo type from the
|
|
63
|
+
* manifest. Left out, Atticus's documented types (ADR 0040).
|
|
64
|
+
*/
|
|
65
|
+
componentTypes?: ReadonlySet<string>;
|
|
47
66
|
repos: MergeRepo[];
|
|
48
67
|
systems: MergeSystem[];
|
|
49
68
|
patterns?: MergePattern[];
|
|
@@ -71,6 +90,15 @@ export interface MergeResult {
|
|
|
71
90
|
/** Things worth knowing that aren't wrong, e.g. hosts that look like a gateway nobody declared. */
|
|
72
91
|
notes: string[];
|
|
73
92
|
}
|
|
93
|
+
/** A record id cut to fit: its start, then a hash of the whole id, the same for the same id. */
|
|
94
|
+
export declare const fitRecordId: (id: string) => string;
|
|
95
|
+
/**
|
|
96
|
+
* A plural noun's singular, by plain English rules (one for endpoint ids and the glossary):
|
|
97
|
+
* "transfers" → "transfer", "policies" → "policy", "addresses" → "address", "statuses" →
|
|
98
|
+
* "status", "aliases" → "alias"; "status", "analysis" and "access" stay as they are; "causes",
|
|
99
|
+
* "excuses", "cases" and "responses" lose only their s.
|
|
100
|
+
*/
|
|
101
|
+
export declare function singularNoun(word: string): string;
|
|
74
102
|
/** Canonical REST endpoint id: <component>.<method>-<last fixed path segment, singular>. */
|
|
75
103
|
export declare function endpointId(component: string, method: string | undefined, normalizedPath: string): string;
|
|
76
104
|
export declare function mergeCatalog(input: MergeInput): MergeResult;
|