@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
|
@@ -8,3 +8,17 @@ export declare function migrateChangeTypesText(text: string): {
|
|
|
8
8
|
text: string;
|
|
9
9
|
changed: boolean;
|
|
10
10
|
};
|
|
11
|
+
/** The quick type's entry on one line, for a person to add to a list written that way. */
|
|
12
|
+
export declare const QUICK_ENTRY_ONE_LINE: string;
|
|
13
|
+
/**
|
|
14
|
+
* Add the quick change type (ADR 0201) at the end of a change-types.yaml's `types`. The entry is
|
|
15
|
+
* put into the text after the list's last line, at the list's own indent and line endings, so
|
|
16
|
+
* comments and every other entry stay byte for byte. Unchanged when the file doesn't read as
|
|
17
|
+
* change types or already has a type `quick`; when it keeps its types on one line, `why` says so.
|
|
18
|
+
*/
|
|
19
|
+
export declare function addQuickTypeText(text: string): {
|
|
20
|
+
text: string;
|
|
21
|
+
changed: boolean;
|
|
22
|
+
/** Unchanged because the list is a flow sequence (`types: [ … ]`): a person adds the entry. */
|
|
23
|
+
why?: "one-line";
|
|
24
|
+
};
|
package/npm/core/cite.d.ts
CHANGED
|
@@ -33,22 +33,104 @@ export declare function claimOnLines(lines: readonly string[], line: number, cla
|
|
|
33
33
|
export declare function normalizeQuote(q: string): string;
|
|
34
34
|
/** Whether a quote is the line, starts it, or sits inside it, after normalisation. */
|
|
35
35
|
export declare function quoteMatches(line: string, quote: string | undefined): boolean;
|
|
36
|
+
/** Whether a path names a binary file by its extension (an image, an archive, a font, a build). */
|
|
37
|
+
export declare function isBinaryPath(path: string): boolean;
|
|
36
38
|
/** A quote is not required from a binary, a notebook, a minified file, or a very long line. */
|
|
37
39
|
export declare function quoteNotRequired(path: string, line: string): boolean;
|
|
38
|
-
/**
|
|
40
|
+
/**
|
|
41
|
+
* Paths whose lines are never quoted into a map. Each part is read as NTFS opens it (review round
|
|
42
|
+
* 46): a stream's name after `:` (`.env::$DATA` is `.env`) and trailing dots and spaces dropped.
|
|
43
|
+
*/
|
|
39
44
|
export declare function isSecretPath(path: string): boolean;
|
|
40
45
|
/**
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
*
|
|
46
|
+
* Beta.27 review: the well-known token prefixes, whatever follows them (TOKEN_SHAPES want the
|
|
47
|
+
* whole token, so a token cut short or typed in part passes them): a Git host's personal, project
|
|
48
|
+
* and deploy tokens, a package registry's, a model hub's, a payment provider's secret, restricted,
|
|
49
|
+
* publishable and webhook keys, a chat workspace's bot, user and app tokens, a cloud's access key
|
|
50
|
+
* ids, API keys and OAuth access tokens, a JWT's header, a mail service's key, a point-of-sale
|
|
51
|
+
* provider's access and secret keys, a telephony provider's API key and account ids, a data
|
|
52
|
+
* platform's token, a storage account's key in a connection string, a shared access signature,
|
|
53
|
+
* and a bearer or Basic authorization. One list: a run's title (run-log.ts) drops a word with one.
|
|
54
|
+
*/
|
|
55
|
+
export declare const TOKEN_PREFIXES: readonly RegExp[];
|
|
56
|
+
/** Whether a text holds one of TOKEN_PREFIXES anywhere (beta.27 review). */
|
|
57
|
+
export declare const hasTokenPrefix: (text: string) => boolean;
|
|
58
|
+
/**
|
|
59
|
+
* Whether a text holds a secret by its shape alone, whatever names it (beta.24 review): a URL's
|
|
60
|
+
* password (`jdbc:postgresql://user:pass@host`), a bearer or Basic token or one of the well-known token
|
|
61
|
+
* shapes `redactSecrets` takes out. A reference (`${X}`, `env:X`) in the password's place is none.
|
|
62
|
+
* `basic: false` leaves the Basic token out, as beta.24 released the check: the facts schema
|
|
63
|
+
* keeps it so (the verifier and Trust's secrets check take the Basic token).
|
|
64
|
+
*/
|
|
65
|
+
export declare function hasSecretShape(text: string, o?: {
|
|
66
|
+
basic?: boolean;
|
|
67
|
+
}): boolean;
|
|
68
|
+
/**
|
|
69
|
+
* Beta.27 re-review: a text with what hasSecretShape finds in it masked (`***`, keeping what names
|
|
70
|
+
* it): a URL's password, a bearer or Basic token, the well-known token shapes. A run's log line
|
|
71
|
+
* goes through it, so an echoed error ("Can't read <root>/AKIA…") never keeps a key.
|
|
72
|
+
*/
|
|
73
|
+
export declare function maskSecretShapes(text: string, mask?: string): string;
|
|
74
|
+
/**
|
|
75
|
+
* Review of beta.24: whether a key is itself a secret, so naming its line by it would show one: a
|
|
76
|
+
* well-known token shape (an access key id written as a credentials file's key), a run of 24 hex
|
|
77
|
+
* digits or more (a random id, a digest), a run of 16 letters and digits or more that switches
|
|
78
|
+
* between them as a random token does (`q7Xf3Kd9…`), or (round 4) 32 characters or more of one
|
|
79
|
+
* piece (no `_`, `-` or `.`) in base64's or hex's alphabet, digits and letters both, or 32
|
|
80
|
+
* characters or more of base64url's alphabet with digits and both cases.
|
|
81
|
+
* A key of words, however abbreviated (`MSSQL_SA_PWD_2019`, `x509Certificate2Path`), is shown.
|
|
82
|
+
* Beta.27: here in core (it was the verifier's), so a run's title drops a value shaped so too.
|
|
83
|
+
*/
|
|
84
|
+
export declare function keyIsSecret(key: string): boolean;
|
|
85
|
+
/**
|
|
86
|
+
* Redact the secrets on a line, keeping what names them: a value after a secret-looking key
|
|
87
|
+
* (at the line's start, whatever the value; anywhere on it, a quoted literal), a setter's
|
|
88
|
+
* literal, a URL's password, a bearer or basic token and well-known token shapes. A
|
|
89
|
+
* placeholder or a reference (`${X}`, `env:X`, `vault:...`) stays, as does code that only names
|
|
90
|
+
* a secret word (`if (password == null)`, `tokenizer.next()`). A private-key block is redacted
|
|
91
|
+
* whole. A key's value is redacted to the end of the line.
|
|
44
92
|
*/
|
|
45
93
|
export declare function redactSecrets(line: string): string;
|
|
94
|
+
/**
|
|
95
|
+
* Whether a quote redaction left as it is still holds what looks like a secret: an identifier
|
|
96
|
+
* with a secret word and an opaque quoted literal (8 or more characters with letters and digits,
|
|
97
|
+
* no spaces, not a path, URL or placeholder) on the same line, e.g.
|
|
98
|
+
* `creds.put(PASSWORD_KEY, "Xk9fQ2mZ7p")`. Code that only names a secret word
|
|
99
|
+
* (`passwordEncoder.encode(x)`, `getToken("Authorization")`) doesn't.
|
|
100
|
+
*/
|
|
101
|
+
export declare function quoteHoldsSecret(quote: string): boolean;
|
|
46
102
|
/**
|
|
47
103
|
* Whether a word claim is put together from `cite.with` parts (ADR 0124 addendum A-derived): a
|
|
48
104
|
* rake task's `namespace:task`, a key a helper prefixes (`${prefix}_conferenceCache`). Each part's
|
|
49
105
|
* value must be in the claim as a whole piece (bounded by the claim's start or end, a separator
|
|
50
|
-
* `: . _
|
|
51
|
-
* be written on the cited lines
|
|
106
|
+
* `: . _ / #`, or another part; `-` joins a word), and whatever is left between the parts,
|
|
107
|
+
* separators aside, must be written on the cited lines: at least one piece, so the cited lines
|
|
108
|
+
* name some of the word. The parts' own lines are checked by the caller.
|
|
52
109
|
*/
|
|
53
110
|
export declare function partsBuildWord(claim: string, parts: readonly string[], lines: readonly string[]): boolean;
|
|
54
111
|
export declare function partsNamePath(lines: readonly string[], path: string): boolean;
|
|
112
|
+
/**
|
|
113
|
+
* Whether a part's value or line, or a code line in the cite window, declares a conventional
|
|
114
|
+
* route, one whose action is its method's name (third and fourth reviews of ADR 0196): a template
|
|
115
|
+
* with an action token (`{controller}/{action}/{id}`, `{controller=Home}/{action=Index}/{id?}`,
|
|
116
|
+
* attribute routing's `[action]`, on the class or the method's own `[Route("[action]")]`), a call
|
|
117
|
+
* that sets the default template (`MapDefaultControllerRoute()`), or a DRF `@action(` that sets no
|
|
118
|
+
* `url_path=` (its path is the method's name). `[controller]` alone is not one: an attribute route
|
|
119
|
+
* names its action in its own attribute, not by the method.
|
|
120
|
+
*
|
|
121
|
+
* A text may hold several lines, a window joined with `\n` (fifth review): a DRF `@action(` is
|
|
122
|
+
* read to its closing parenthesis, so a `url_path=` on a line below it, inside the call, makes it
|
|
123
|
+
* none; one the window doesn't close is read as far as the window goes.
|
|
124
|
+
*/
|
|
125
|
+
export declare function declaresConventionalRoute(texts: readonly string[]): boolean;
|
|
126
|
+
/**
|
|
127
|
+
* The piece of an HTTP route put together from parts that only a commented-out mapping writes
|
|
128
|
+
* (third review of ADR 0196), or undefined. A piece the parts' lines don't name, which a comment
|
|
129
|
+
* line in the cite window writes as a path (`// @GetMapping("/balances")`) while no code line there
|
|
130
|
+
* does, is named by that comment, not by the code: a method `balances()` under it, with the class's
|
|
131
|
+
* `/api` a part, names no `/api/balances`. Anywhere else an identifier names a piece as the path
|
|
132
|
+
* check always let it (a gRPC stub, a WCF call, a conventional route's action, a constant).
|
|
133
|
+
*/
|
|
134
|
+
export declare function pathPieceOnlyInComment(rawNear: readonly string[],
|
|
135
|
+
/** Whether a line of the window (and its index in it) is all comment. */
|
|
136
|
+
isComment: (l: string, i: number) => boolean, partLines: readonly string[], path: string): string | undefined;
|
|
@@ -0,0 +1,276 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import type { FactEnd, FactsJoinResult } from "./facts-join.js";
|
|
3
|
+
import type { VendorCallMatch } from "./facts-join-vendor.js";
|
|
4
|
+
import type { Fact } from "./schema/facts.js";
|
|
5
|
+
/** A field a spec lists: a request or response property or parameter, or a message's field. */
|
|
6
|
+
export declare const SpecField: z.ZodObject<{
|
|
7
|
+
side: z.ZodEnum<{
|
|
8
|
+
message: "message";
|
|
9
|
+
request: "request";
|
|
10
|
+
response: "response";
|
|
11
|
+
}>;
|
|
12
|
+
name: z.ZodString;
|
|
13
|
+
type: z.ZodOptional<z.ZodString>;
|
|
14
|
+
required: z.ZodOptional<z.ZodBoolean>;
|
|
15
|
+
in: z.ZodOptional<z.ZodString>;
|
|
16
|
+
number: z.ZodOptional<z.ZodNumber>;
|
|
17
|
+
at: z.ZodString;
|
|
18
|
+
}, z.core.$strict>;
|
|
19
|
+
export type SpecFieldT = z.infer<typeof SpecField>;
|
|
20
|
+
export declare const SPEC_FORMATS: readonly ["openapi", "protobuf", "avro", "json-schema", "asyncapi"];
|
|
21
|
+
/**
|
|
22
|
+
* One operation or one message a spec file describes, as the contract check reads it. An
|
|
23
|
+
* operation has a method and a path (with the server's path in front); a message has the name
|
|
24
|
+
* of its type (a proto message's full name, an Avro record's, a JSON Schema's title) and, when
|
|
25
|
+
* the spec says (AsyncAPI), the topic it travels on.
|
|
26
|
+
*/
|
|
27
|
+
export declare const ContractSpec: z.ZodObject<{
|
|
28
|
+
kind: z.ZodEnum<{
|
|
29
|
+
message: "message";
|
|
30
|
+
operation: "operation";
|
|
31
|
+
}>;
|
|
32
|
+
format: z.ZodEnum<{
|
|
33
|
+
openapi: "openapi";
|
|
34
|
+
"json-schema": "json-schema";
|
|
35
|
+
avro: "avro";
|
|
36
|
+
protobuf: "protobuf";
|
|
37
|
+
asyncapi: "asyncapi";
|
|
38
|
+
}>;
|
|
39
|
+
role: z.ZodEnum<{
|
|
40
|
+
schema: "schema";
|
|
41
|
+
consumer: "consumer";
|
|
42
|
+
own: "own";
|
|
43
|
+
}>;
|
|
44
|
+
file: z.ZodString;
|
|
45
|
+
line: z.ZodNumber;
|
|
46
|
+
method: z.ZodOptional<z.ZodString>;
|
|
47
|
+
path: z.ZodOptional<z.ZodString>;
|
|
48
|
+
entry: z.ZodOptional<z.ZodString>;
|
|
49
|
+
name: z.ZodOptional<z.ZodString>;
|
|
50
|
+
topic: z.ZodOptional<z.ZodString>;
|
|
51
|
+
id: z.ZodOptional<z.ZodString>;
|
|
52
|
+
fields: z.ZodArray<z.ZodObject<{
|
|
53
|
+
side: z.ZodEnum<{
|
|
54
|
+
message: "message";
|
|
55
|
+
request: "request";
|
|
56
|
+
response: "response";
|
|
57
|
+
}>;
|
|
58
|
+
name: z.ZodString;
|
|
59
|
+
type: z.ZodOptional<z.ZodString>;
|
|
60
|
+
required: z.ZodOptional<z.ZodBoolean>;
|
|
61
|
+
in: z.ZodOptional<z.ZodString>;
|
|
62
|
+
number: z.ZodOptional<z.ZodNumber>;
|
|
63
|
+
at: z.ZodString;
|
|
64
|
+
}, z.core.$strict>>;
|
|
65
|
+
errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
66
|
+
status: z.ZodString;
|
|
67
|
+
at: z.ZodString;
|
|
68
|
+
}, z.core.$strict>>>;
|
|
69
|
+
}, z.core.$strict>;
|
|
70
|
+
export type ContractSpecT = z.infer<typeof ContractSpec>;
|
|
71
|
+
/**
|
|
72
|
+
* The facts companion `<repo>.specs.yaml` (ADR 0164): the specs a repo's checkout holds, read at
|
|
73
|
+
* the facts' commit by `atticus verify <repo> --write`, so the contract check reads the same
|
|
74
|
+
* specs on every run without the checkout.
|
|
75
|
+
*/
|
|
76
|
+
export declare const SpecsFile: z.ZodObject<{
|
|
77
|
+
schemaVersion: z.ZodLiteral<1>;
|
|
78
|
+
repo: z.ZodString;
|
|
79
|
+
commit: z.ZodOptional<z.ZodString>;
|
|
80
|
+
specs: z.ZodArray<z.ZodObject<{
|
|
81
|
+
kind: z.ZodEnum<{
|
|
82
|
+
message: "message";
|
|
83
|
+
operation: "operation";
|
|
84
|
+
}>;
|
|
85
|
+
format: z.ZodEnum<{
|
|
86
|
+
openapi: "openapi";
|
|
87
|
+
"json-schema": "json-schema";
|
|
88
|
+
avro: "avro";
|
|
89
|
+
protobuf: "protobuf";
|
|
90
|
+
asyncapi: "asyncapi";
|
|
91
|
+
}>;
|
|
92
|
+
role: z.ZodEnum<{
|
|
93
|
+
schema: "schema";
|
|
94
|
+
consumer: "consumer";
|
|
95
|
+
own: "own";
|
|
96
|
+
}>;
|
|
97
|
+
file: z.ZodString;
|
|
98
|
+
line: z.ZodNumber;
|
|
99
|
+
method: z.ZodOptional<z.ZodString>;
|
|
100
|
+
path: z.ZodOptional<z.ZodString>;
|
|
101
|
+
entry: z.ZodOptional<z.ZodString>;
|
|
102
|
+
name: z.ZodOptional<z.ZodString>;
|
|
103
|
+
topic: z.ZodOptional<z.ZodString>;
|
|
104
|
+
id: z.ZodOptional<z.ZodString>;
|
|
105
|
+
fields: z.ZodArray<z.ZodObject<{
|
|
106
|
+
side: z.ZodEnum<{
|
|
107
|
+
message: "message";
|
|
108
|
+
request: "request";
|
|
109
|
+
response: "response";
|
|
110
|
+
}>;
|
|
111
|
+
name: z.ZodString;
|
|
112
|
+
type: z.ZodOptional<z.ZodString>;
|
|
113
|
+
required: z.ZodOptional<z.ZodBoolean>;
|
|
114
|
+
in: z.ZodOptional<z.ZodString>;
|
|
115
|
+
number: z.ZodOptional<z.ZodNumber>;
|
|
116
|
+
at: z.ZodString;
|
|
117
|
+
}, z.core.$strict>>;
|
|
118
|
+
errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
119
|
+
status: z.ZodString;
|
|
120
|
+
at: z.ZodString;
|
|
121
|
+
}, z.core.$strict>>>;
|
|
122
|
+
}, z.core.$strict>>;
|
|
123
|
+
}, z.core.$strict>;
|
|
124
|
+
export type SpecsFileT = z.infer<typeof SpecsFile>;
|
|
125
|
+
/** The specs of a system outside the estate, taken in through intake (O2). */
|
|
126
|
+
export interface OutsideSpecs {
|
|
127
|
+
system: string;
|
|
128
|
+
name: string;
|
|
129
|
+
specs: readonly ContractSpecT[];
|
|
130
|
+
}
|
|
131
|
+
export declare const CONTRACT_KINDS: readonly ["field-missing", "field-extra", "field-not-sent", "field-required", "field-type", "field-number", "error-unlisted", "error-unanswered"];
|
|
132
|
+
export type ContractKind = (typeof CONTRACT_KINDS)[number];
|
|
133
|
+
/** One end of a comparison: who says it (a repo's code, a spec), the value, and its line. */
|
|
134
|
+
export interface ContractEnd {
|
|
135
|
+
/** The repo whose code or spec it is, or the outside system. */
|
|
136
|
+
repo?: string;
|
|
137
|
+
system?: string;
|
|
138
|
+
/** What this end is, in words: `forge-portal-bff's call`, `the spec forge-accounts-v1.yaml`. */
|
|
139
|
+
what: string;
|
|
140
|
+
value?: string;
|
|
141
|
+
/** path:line. */
|
|
142
|
+
at?: string;
|
|
143
|
+
}
|
|
144
|
+
export interface ContractMismatch {
|
|
145
|
+
/** Stable: the link, the boundary, the kind, the side and the field or status. */
|
|
146
|
+
id: string;
|
|
147
|
+
/** The catalog Interface of the link, when the join gives one. */
|
|
148
|
+
interface?: string;
|
|
149
|
+
/** Every Interface it concerns: the link's, and each gateway hop's forwarding call's. */
|
|
150
|
+
interfaces?: string[];
|
|
151
|
+
/** The call the link starts at (the publish, for a topic). */
|
|
152
|
+
call: FactEnd;
|
|
153
|
+
/** What it reaches: an entry of the estate, or an outside system. */
|
|
154
|
+
entry?: FactEnd;
|
|
155
|
+
system?: string;
|
|
156
|
+
/**
|
|
157
|
+
* `mismatch`: the two sides disagree; `unconfirmed`: a mapping on the way isn't traced, or the
|
|
158
|
+
* difference rests on a field whose place in its payload the facts don't give (the message
|
|
159
|
+
* says which).
|
|
160
|
+
*/
|
|
161
|
+
status: "mismatch" | "unconfirmed";
|
|
162
|
+
kind: ContractKind;
|
|
163
|
+
side?: "request" | "response" | "message";
|
|
164
|
+
field?: string;
|
|
165
|
+
error?: string;
|
|
166
|
+
/** The side that sends (or, for a response, reads) and the side that takes (or returns). */
|
|
167
|
+
sender: ContractEnd;
|
|
168
|
+
receiver: ContractEnd;
|
|
169
|
+
/** The mapping lines the comparison went through (`repo path:line`), in order. */
|
|
170
|
+
via?: string[];
|
|
171
|
+
/** The mapping that isn't traced, when `unconfirmed` for that reason. */
|
|
172
|
+
untraced?: string;
|
|
173
|
+
message: string;
|
|
174
|
+
}
|
|
175
|
+
/** A link compared: how many boundaries had something on both sides, and what was found. */
|
|
176
|
+
export interface ContractLink {
|
|
177
|
+
key: string;
|
|
178
|
+
interface?: string;
|
|
179
|
+
/** Every Interface the link's check concerns: its own, and each gateway hop's forwarding call's. */
|
|
180
|
+
interfaces?: string[];
|
|
181
|
+
call: FactEnd;
|
|
182
|
+
entry?: FactEnd;
|
|
183
|
+
system?: string;
|
|
184
|
+
kind: "rest" | "topic" | "outside";
|
|
185
|
+
method?: string;
|
|
186
|
+
path: string;
|
|
187
|
+
/** The gateway routes on the way, in order (`repo` of each). */
|
|
188
|
+
through: string[];
|
|
189
|
+
/** The specs read for it (`file:line`, the repo's or intake's). */
|
|
190
|
+
specs: string[];
|
|
191
|
+
/** Boundaries where both sides said something about the payload. */
|
|
192
|
+
compared: number;
|
|
193
|
+
mismatches: number;
|
|
194
|
+
unconfirmed: number;
|
|
195
|
+
}
|
|
196
|
+
export interface ContractCheckResult {
|
|
197
|
+
links: ContractLink[];
|
|
198
|
+
findings: ContractMismatch[];
|
|
199
|
+
counts: {
|
|
200
|
+
links: number;
|
|
201
|
+
compared: number;
|
|
202
|
+
mismatches: number;
|
|
203
|
+
unconfirmed: number;
|
|
204
|
+
/**
|
|
205
|
+
* ADR 0172: the calls no link starts at (not joined, not to an outside system), so nothing on
|
|
206
|
+
* their other side can be compared until they join.
|
|
207
|
+
*/
|
|
208
|
+
unlinked: number;
|
|
209
|
+
};
|
|
210
|
+
}
|
|
211
|
+
export interface ContractCheckInput {
|
|
212
|
+
repos: readonly {
|
|
213
|
+
repo: string;
|
|
214
|
+
facts: readonly Fact[];
|
|
215
|
+
}[];
|
|
216
|
+
join: FactsJoinResult;
|
|
217
|
+
/** Every repo's `<repo>.specs.yaml` on file. */
|
|
218
|
+
specs?: readonly SpecsFileT[];
|
|
219
|
+
/** The specs of systems outside the estate, from intake. */
|
|
220
|
+
outside?: readonly OutsideSpecs[];
|
|
221
|
+
/** The calls to outside systems matched to their spec's operations (`joinVendorOperations`). */
|
|
222
|
+
vendorMatches?: readonly VendorCallMatch[];
|
|
223
|
+
}
|
|
224
|
+
/** The words of the check, in one place: the CLI, the API and the app say these. */
|
|
225
|
+
export declare const CONTRACT_WORDS: {
|
|
226
|
+
extra: (side: string, name: string, s: string, sAt: string, r: string) => string;
|
|
227
|
+
notSent: (side: string, name: string, r: string, rAt: string, s: string) => string;
|
|
228
|
+
missing: (name: string, s: string, sAt: string, r: string) => string;
|
|
229
|
+
messageMissing: (name: string, r: string, rAt: string, s: string) => string;
|
|
230
|
+
messageExtra: (name: string, s: string, sAt: string, r: string) => string;
|
|
231
|
+
undocumented: (name: string, r: string, rAt: string, s: string) => string;
|
|
232
|
+
required: (side: string, name: string, a: string, aAt: string, b: string, bAt: string) => string;
|
|
233
|
+
type: (side: string, name: string, a: string, at: string, aAt: string, b: string, bt: string, bAt: string) => string;
|
|
234
|
+
number: (n: number, a: string, an: string, aAt: string, b: string, bn: string, bAt: string) => string;
|
|
235
|
+
errorUnlisted: (status: string, r: string, rAt: string, s: string, spec: boolean) => string;
|
|
236
|
+
errorUnanswered: (status: string, s: string, sAt: string, r: string) => string;
|
|
237
|
+
unconfirmed: (message: string, untraced: string) => string;
|
|
238
|
+
/** Addendum of 2026-11-17: a difference that rests on a place the facts don't give. */
|
|
239
|
+
unplaced: (message: string, why: string) => string;
|
|
240
|
+
place: (why: string) => string;
|
|
241
|
+
shared: (n: number, tail: string, r: string) => string;
|
|
242
|
+
noRoot: (s: string, side: string) => string;
|
|
243
|
+
nothingInside: (s: string, name: string) => string;
|
|
244
|
+
unlisted: (r: string, name: string) => string;
|
|
245
|
+
itemsUnread: (r: string, name: string) => string;
|
|
246
|
+
elsewhere: (names: readonly string[]) => string;
|
|
247
|
+
renamed: (name: string) => string;
|
|
248
|
+
sameAt: (names: readonly string[]) => string;
|
|
249
|
+
};
|
|
250
|
+
/**
|
|
251
|
+
* The `transform` a reader gives the field fact that names a publish's or listener's message type
|
|
252
|
+
* (ADR 0164): the field's `name` is the type as the line writes it (`PaymentSettled`, the
|
|
253
|
+
* generated proto class or the Avro record), its `type` the full name when the code gives one
|
|
254
|
+
* (`forge.payments.v1.PaymentSettled`), cited where the publish or the listener names it. It is
|
|
255
|
+
* no field of the payload: it ties the payload to its spec.
|
|
256
|
+
*/
|
|
257
|
+
export declare const MESSAGE_TYPE_TRANSFORM = "message type";
|
|
258
|
+
export declare const isMessageType: (f: {
|
|
259
|
+
side?: string;
|
|
260
|
+
transform?: string;
|
|
261
|
+
}) => boolean;
|
|
262
|
+
/** A `transform` that says the field travels inside the field it is mapped to (an envelope). */
|
|
263
|
+
export declare const ENVELOPE_TRANSFORM: RegExp;
|
|
264
|
+
/** Compare the payload on both sides of every link the join made, and of every call to an outside system with a spec. */
|
|
265
|
+
export declare function checkContracts(input: ContractCheckInput): ContractCheckResult;
|
|
266
|
+
/**
|
|
267
|
+
* ADR 0172: the calls of the estate no link starts at: a REST, SOAP or gRPC call, or a publish,
|
|
268
|
+
* the join neither joined nor left to an outside system. Their payload is checked once they join.
|
|
269
|
+
*/
|
|
270
|
+
export declare function unlinkedCalls(input: Pick<ContractCheckInput, "repos" | "join">): FactEnd[];
|
|
271
|
+
/**
|
|
272
|
+
* The findings a newer spec of an outside system brings (ADR 0164): those against `next` that
|
|
273
|
+
* the same calls didn't have against `prev`, by kind, side and field. What the Outside systems
|
|
274
|
+
* page shows when a vendor's or a team's new spec is taken in.
|
|
275
|
+
*/
|
|
276
|
+
export declare function newFindings(next: readonly ContractMismatch[], prev: readonly ContractMismatch[]): ContractMismatch[];
|
package/npm/core/curated.d.ts
CHANGED
|
@@ -34,4 +34,14 @@ export interface CuratedResult {
|
|
|
34
34
|
suppressed: string[];
|
|
35
35
|
problems: CuratedProblem[];
|
|
36
36
|
}
|
|
37
|
+
/** Decisions apply oldest first by the instant their `at` names (an offset is allowed, so
|
|
38
|
+
* text order isn't time order), then by id; an `at` that doesn't parse sorts by its text after
|
|
39
|
+
* every one that does. */
|
|
40
|
+
export declare function byDecisionTime(a: {
|
|
41
|
+
at: string;
|
|
42
|
+
id: string;
|
|
43
|
+
}, b: {
|
|
44
|
+
at: string;
|
|
45
|
+
id: string;
|
|
46
|
+
}): number;
|
|
37
47
|
export declare function applyCurated(records: CatalogRecord[], decisions: readonly CatalogRecord[]): CuratedResult;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { type DecisionBatchT } from "./ai-decisions.js";
|
|
2
|
+
/**
|
|
3
|
+
* ADR 0181: the batch records under `decisions/` (`.atticus/decisions/` when adopted), one file
|
|
4
|
+
* per batch, and the `corrections-v2` upgrade step. The lines a batch names stay in the repos'
|
|
5
|
+
* corrections files and the answers in the question files; the record is what Undo reads.
|
|
6
|
+
*/
|
|
7
|
+
/** Where a batch's record is, relative to the root. */
|
|
8
|
+
export declare const batchRelOf: (root: string, id: string) => string;
|
|
9
|
+
/** Write a batch's record (a new one, or the same one undone). */
|
|
10
|
+
export declare function writeBatch(root: string, b: DecisionBatchT): Promise<string>;
|
|
11
|
+
/** One batch's record; undefined when there is none (or the id isn't a batch's). */
|
|
12
|
+
export declare function readBatch(root: string, id: string): Promise<DecisionBatchT | undefined>;
|
|
13
|
+
/** Every batch on record, newest first, with the files that don't read as one. */
|
|
14
|
+
export declare function listBatches(root: string): Promise<{
|
|
15
|
+
batches: DecisionBatchT[];
|
|
16
|
+
problems: {
|
|
17
|
+
file: string;
|
|
18
|
+
message: string;
|
|
19
|
+
}[];
|
|
20
|
+
}>;
|
|
21
|
+
/**
|
|
22
|
+
* The `corrections-v2` step (ADR 0181): a corrections line that uses version 2's fields (an AI
|
|
23
|
+
* pairing, a batch, a rule, a match, an unlink) but says version 1, as a hand edit might, says 2;
|
|
24
|
+
* every other line means the same at version 1 and is left exactly as it is. Returns the files,
|
|
25
|
+
* relative to the root; with dryRun, the files it would rewrite.
|
|
26
|
+
*/
|
|
27
|
+
export declare function migrateCorrections(root: string, o?: {
|
|
28
|
+
dryRun?: boolean;
|
|
29
|
+
}): Promise<string[]>;
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import type { JoinRepo } from "./facts-join.js";
|
|
2
|
+
/**
|
|
3
|
+
* ADR 0200: the gateway routes a person can declare a caller of, listed to pick from. A declared
|
|
4
|
+
* call (the profile's `calls`, A-callers) lands only on a gateway route: an entry of a gateway
|
|
5
|
+
* repo, or any repo's entry under a proxy bundle folder. An ordinary service's entry is not one,
|
|
6
|
+
* and the join places no declaration on it. The routes come from the same rule the join uses
|
|
7
|
+
* (`gatewayRouteFacts`), and the words offered for each are words the join places on it
|
|
8
|
+
* (`declaredRouteMatches`). Pure.
|
|
9
|
+
*/
|
|
10
|
+
export interface DeclarableRoute {
|
|
11
|
+
/** The route's entry fact. */
|
|
12
|
+
id: string;
|
|
13
|
+
method?: string;
|
|
14
|
+
path: string;
|
|
15
|
+
/** The handler or proxy flow that serves it, where the facts name one. */
|
|
16
|
+
handler?: string;
|
|
17
|
+
/** path:line of the line it was read from. */
|
|
18
|
+
at: string;
|
|
19
|
+
/**
|
|
20
|
+
* What the declaration says to mean this route: `METHOD /path` where no other route of the
|
|
21
|
+
* estate is served on those words, else its handler where that names only this one.
|
|
22
|
+
*/
|
|
23
|
+
say: string;
|
|
24
|
+
/** The system declared it already (by either way of naming it). */
|
|
25
|
+
declared?: true;
|
|
26
|
+
/** The other repos whose route the same words name: the declaration lands there too. */
|
|
27
|
+
also?: string[];
|
|
28
|
+
}
|
|
29
|
+
export interface DeclarableRoutes {
|
|
30
|
+
/** The repo has gateway routes. */
|
|
31
|
+
gateway: boolean;
|
|
32
|
+
routes: DeclarableRoute[];
|
|
33
|
+
/** How many entries the repo has on record, routes or not. */
|
|
34
|
+
entries: number;
|
|
35
|
+
}
|
|
36
|
+
interface Input {
|
|
37
|
+
repos: readonly JoinRepo[];
|
|
38
|
+
/** The gateway bundle folders, as given to the join (the estate's conventions). */
|
|
39
|
+
bundleFolders?: readonly string[] | undefined;
|
|
40
|
+
}
|
|
41
|
+
/** The gateway routes of `repo`, by path then method, each with the words that declare it. */
|
|
42
|
+
export declare function declarableRoutes(input: Input & {
|
|
43
|
+
repo: string;
|
|
44
|
+
/** The routes the system declared already, as its profile says them. */
|
|
45
|
+
declared: readonly string[];
|
|
46
|
+
}): DeclarableRoutes;
|
|
47
|
+
/** The repos that have gateway routes, by id, with how many. */
|
|
48
|
+
export declare function declarableGateways(input: Input): {
|
|
49
|
+
repo: string;
|
|
50
|
+
routes: number;
|
|
51
|
+
}[];
|
|
52
|
+
export {};
|