@maycombhq/sdk 2.0.0-beta.23 → 2.0.0-beta.25
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/api.d.ts +530 -30
- package/npm/core/cite.d.ts +13 -2
- package/npm/core/facts-deps.d.ts +85 -0
- package/npm/core/facts-join.d.ts +33 -7
- package/npm/core/facts.d.ts +59 -0
- package/npm/core/host-questions.d.ts +180 -0
- package/npm/core/identity.d.ts +1 -17
- package/npm/core/index.d.ts +1 -0
- package/npm/core/paths.d.ts +23 -0
- package/npm/core/questions.d.ts +14 -0
- package/npm/core/schema/ai.d.ts +2 -2
- package/npm/core/schema/dialect.d.ts +12 -12
- package/npm/core/schema/fact-corrections.d.ts +2 -0
- package/npm/core/schema/facts.d.ts +315 -4
- package/npm/core/schema/frameworks.d.ts +10 -10
- package/npm/core/schema/review.d.ts +2 -2
- package/npm/core/schema/scan-verify.d.ts +45 -45
- package/npm/index.js +5530 -4902
- package/package.json +1 -1
package/npm/core/cite.d.ts
CHANGED
|
@@ -42,6 +42,16 @@ export declare function quoteNotRequired(path: string, line: string): boolean;
|
|
|
42
42
|
* 46): a stream's name after `:` (`.env::$DATA` is `.env`) and trailing dots and spaces dropped.
|
|
43
43
|
*/
|
|
44
44
|
export declare function isSecretPath(path: string): boolean;
|
|
45
|
+
/**
|
|
46
|
+
* Whether a text holds a secret by its shape alone, whatever names it (beta.24 review): a URL's
|
|
47
|
+
* password (`jdbc:postgresql://user:pass@host`), a bearer or Basic token or one of the well-known token
|
|
48
|
+
* shapes `redactSecrets` takes out. A reference (`${X}`, `env:X`) in the password's place is none.
|
|
49
|
+
* `basic: false` leaves the Basic token out, as beta.24 released the check: the facts schema
|
|
50
|
+
* keeps it so (the verifier and Trust's secrets check take the Basic token).
|
|
51
|
+
*/
|
|
52
|
+
export declare function hasSecretShape(text: string, o?: {
|
|
53
|
+
basic?: boolean;
|
|
54
|
+
}): boolean;
|
|
45
55
|
/**
|
|
46
56
|
* Redact the secrets on a line, keeping what names them: a value after a secret-looking key
|
|
47
57
|
* (at the line's start, whatever the value; anywhere on it, a quoted literal), a setter's
|
|
@@ -63,8 +73,9 @@ export declare function quoteHoldsSecret(quote: string): boolean;
|
|
|
63
73
|
* Whether a word claim is put together from `cite.with` parts (ADR 0124 addendum A-derived): a
|
|
64
74
|
* rake task's `namespace:task`, a key a helper prefixes (`${prefix}_conferenceCache`). Each part's
|
|
65
75
|
* value must be in the claim as a whole piece (bounded by the claim's start or end, a separator
|
|
66
|
-
* `: . _
|
|
67
|
-
* be written on the cited lines
|
|
76
|
+
* `: . _ / #`, or another part; `-` joins a word), and whatever is left between the parts,
|
|
77
|
+
* separators aside, must be written on the cited lines: at least one piece, so the cited lines
|
|
78
|
+
* name some of the word. The parts' own lines are checked by the caller.
|
|
68
79
|
*/
|
|
69
80
|
export declare function partsBuildWord(claim: string, parts: readonly string[], lines: readonly string[]): boolean;
|
|
70
81
|
export declare function partsNamePath(lines: readonly string[], path: string): boolean;
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import type { FactEnd, JoinRepo } from "./facts-join.js";
|
|
2
|
+
import type { DependencyScope } from "./schema/facts.js";
|
|
3
|
+
/**
|
|
4
|
+
* The estate's build dependencies (ADR 0192): a component's `dependency` fact that names the
|
|
5
|
+
* coordinates (group and name) another component's `artifact` fact publishes is a "depends on"
|
|
6
|
+
* link from the one to the other, with a cited line at both ends: the dependency's in the
|
|
7
|
+
* depending build file, the published coordinates' in the library's. Matching is by those
|
|
8
|
+
* coordinates alone, letter case aside: no group prefix, naming convention or repo type says
|
|
9
|
+
* what is the organisation's own; what some repo of the estate publishes is.
|
|
10
|
+
*
|
|
11
|
+
* - A dependency on coordinates nobody in the estate publishes (a vendor SDK, an open-source
|
|
12
|
+
* library) draws nothing and asks nothing: it is counted in `outside`.
|
|
13
|
+
* - A test-scoped dependency draws nothing (`test`): it builds the tests, not the component.
|
|
14
|
+
* - Coordinates two components publish draw nothing either: they are `ambiguous`, for a person.
|
|
15
|
+
* - A component's dependency on its own coordinates draws nothing.
|
|
16
|
+
*
|
|
17
|
+
* The library's own calls are the library's: nothing here touches a call, and nothing of the
|
|
18
|
+
* library is given to the components that depend on it. Pure: the same facts give the same
|
|
19
|
+
* links, whatever order the repos come in.
|
|
20
|
+
*/
|
|
21
|
+
/** One end of a "depends on" link: its fact, and every line the claim rests on (`file:line`). */
|
|
22
|
+
export interface DependencyEnd extends FactEnd {
|
|
23
|
+
lines: string[];
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Review of beta.25: one dependency fact a link rests on, with the coordinates it names (a link
|
|
27
|
+
* between two components holds every coordinate one builds on of the other's: `kit-api` and
|
|
28
|
+
* `kit-core` of component `kit` are one arrow).
|
|
29
|
+
*/
|
|
30
|
+
export interface DependencyFactEnd extends DependencyEnd {
|
|
31
|
+
group: string;
|
|
32
|
+
name: string;
|
|
33
|
+
version?: string;
|
|
34
|
+
/** Its scope, when not compile. */
|
|
35
|
+
scope?: DependencyScope;
|
|
36
|
+
}
|
|
37
|
+
export interface DependencyLink {
|
|
38
|
+
/** The dependency fact, in the component that builds on the library (the first by id). */
|
|
39
|
+
from: DependencyEnd;
|
|
40
|
+
/**
|
|
41
|
+
* Beta.25: every dependency fact the link rests on, `from` first, each with its lines: two
|
|
42
|
+
* module poms of one component, a `<profile>`'s copy, `implementation` and `runtimeOnly` of the
|
|
43
|
+
* same coordinates, and (review of beta.25) every other coordinate of the same library
|
|
44
|
+
* component, each with its coordinates. The link goes only once each of them is wrong.
|
|
45
|
+
*/
|
|
46
|
+
facts?: (DependencyEnd & Partial<Pick<DependencyFactEnd, "group" | "name" | "version" | "scope">>)[];
|
|
47
|
+
/** The artifact fact, in the library's component, that publishes the coordinates. */
|
|
48
|
+
to: DependencyEnd;
|
|
49
|
+
/**
|
|
50
|
+
* Review of beta.25: every artifact fact of the library's component a dependency on the link
|
|
51
|
+
* names, `to` first (one per coordinate).
|
|
52
|
+
*/
|
|
53
|
+
published?: DependencyEnd[];
|
|
54
|
+
group: string;
|
|
55
|
+
name: string;
|
|
56
|
+
/**
|
|
57
|
+
* The dependency's declared scope, when it says one other than compile; on a link merged from
|
|
58
|
+
* several facts (review of beta.25), only when every one of them has it, else left out.
|
|
59
|
+
*/
|
|
60
|
+
scope?: DependencyScope;
|
|
61
|
+
/** The version the dependency declares, when it says one. */
|
|
62
|
+
version?: string;
|
|
63
|
+
}
|
|
64
|
+
/** Coordinates two or more components of the estate publish: nothing is drawn to either. */
|
|
65
|
+
export interface AmbiguousCoordinates {
|
|
66
|
+
group: string;
|
|
67
|
+
name: string;
|
|
68
|
+
by: FactEnd[];
|
|
69
|
+
}
|
|
70
|
+
export interface DependencyJoinResult {
|
|
71
|
+
links: DependencyLink[];
|
|
72
|
+
ambiguous: AmbiguousCoordinates[];
|
|
73
|
+
/** Dependencies on coordinates nobody in the estate publishes: drawn as nothing. */
|
|
74
|
+
outside: number;
|
|
75
|
+
/** Test-scoped dependencies on the estate's own coordinates: drawn as nothing. */
|
|
76
|
+
test: number;
|
|
77
|
+
}
|
|
78
|
+
export declare function joinDependencies(input: {
|
|
79
|
+
repos: readonly JoinRepo[];
|
|
80
|
+
}): DependencyJoinResult;
|
|
81
|
+
/**
|
|
82
|
+
* The id a "depends on" link is known by, for a view's join: stable across reads of one pom, and
|
|
83
|
+
* (review of beta.25) one per pair of components, as the join makes one link per pair.
|
|
84
|
+
*/
|
|
85
|
+
export declare const dependencyLinkId: (l: Pick<DependencyLink, "from" | "to">) => string;
|
package/npm/core/facts-join.d.ts
CHANGED
|
@@ -73,6 +73,14 @@ export interface JoinRepo {
|
|
|
73
73
|
hosts: readonly string[];
|
|
74
74
|
basePath?: string;
|
|
75
75
|
}[];
|
|
76
|
+
/**
|
|
77
|
+
* Beta.25 (ADR 0192 addendum): every module the manifest lists, by its folder, hosts or not: a
|
|
78
|
+
* build fact (`artifact`, `dependency`) that names no component is its build file's module's.
|
|
79
|
+
*/
|
|
80
|
+
moduleDirs?: readonly {
|
|
81
|
+
path: string;
|
|
82
|
+
component: string;
|
|
83
|
+
}[];
|
|
76
84
|
/** An API gateway (the manifest's `type: gateway`): its entries are routes it forwards. */
|
|
77
85
|
gateway?: boolean;
|
|
78
86
|
/**
|
|
@@ -207,6 +215,13 @@ export declare const JOINED_BY_ANSWER = "joined-by-answer";
|
|
|
207
215
|
export declare const JOINED_BY_NAME = "joined-by-name";
|
|
208
216
|
export declare const JOINED_BY_REPO = "joined-by-repo";
|
|
209
217
|
export declare const JOINED_BY_HOST = "joined-by-host";
|
|
218
|
+
/**
|
|
219
|
+
* A call whose host nothing resolves, joined to a gateway proxy's flow by its whole path: the one
|
|
220
|
+
* proxy whose cited `<BasePath>` starts it, the one flow of its method under it. Code at both
|
|
221
|
+
* ends: a how, never a guess. Beta.25: verified only for a gateway's forwarding call that names
|
|
222
|
+
* no host (a chained proxy); a call whose host nothing resolves is inferred, `joined-by-path` first.
|
|
223
|
+
*/
|
|
224
|
+
export declare const JOINED_BY_BASE_PATH = "joined-by-base-path";
|
|
210
225
|
/**
|
|
211
226
|
* J0, J1: the guesses a join by host can rest on, though the host itself was cited. The setting
|
|
212
227
|
* that gave the host is a platform-wide one nobody aimed at the caller (`setsForAll`), or one that
|
|
@@ -263,7 +278,7 @@ export declare const JOINED_TO_SHARED_MAP = "joined-to-shared-map";
|
|
|
263
278
|
* or the component's own name as the host), `path` (no target named: the only entry of the
|
|
264
279
|
* estate that serves it), `topic` (a listener of the published topic).
|
|
265
280
|
*/
|
|
266
|
-
export type JoinHow = "answer" | "named" | "repo" | "host" | "path" | "topic";
|
|
281
|
+
export type JoinHow = "answer" | "named" | "repo" | "host" | "base-path" | "path" | "topic";
|
|
267
282
|
export interface FactJoin {
|
|
268
283
|
call: FactEnd;
|
|
269
284
|
entry: FactEnd;
|
|
@@ -289,6 +304,8 @@ export interface FactJoin {
|
|
|
289
304
|
* A join by path (the join fallback): nobody named the callee, so it is inferred. `within`
|
|
290
305
|
* says where the one entry that serves the call was found: the caller's own repo first, else
|
|
291
306
|
* the estate; `named` is the target the call gave, when it named one the estate doesn't have.
|
|
307
|
+
* Beta.25: also a join by a proxy's BasePath (`how: "base-path"`) whose caller's host nothing
|
|
308
|
+
* resolves (`within: "estate"`): the path is code at both ends, the host a guess.
|
|
292
309
|
*/
|
|
293
310
|
inferred?: {
|
|
294
311
|
within: "repo" | "estate";
|
|
@@ -545,8 +562,23 @@ export declare function routeScore(called: string, served: string): number;
|
|
|
545
562
|
export declare function nameScore(called: string, served: string): number;
|
|
546
563
|
/** The question for a call no single repo answers: the same words as the facts-targets question. */
|
|
547
564
|
export declare function callTargetQuestion(f: Call, component: string): string;
|
|
565
|
+
/**
|
|
566
|
+
* The question for a gateway's forwarding call whose host nothing resolves. A host still written
|
|
567
|
+
* as a token (`@targetUrl@`, `{{host}}`, `${HOST}`) is most often one a deploy tool's file sets
|
|
568
|
+
* per environment (the Apigee config plugin's `config.json`), which a read before beta.24 didn't
|
|
569
|
+
* record: the next step it says is to read the gateway repo again, never a guess at a repo.
|
|
570
|
+
*/
|
|
571
|
+
export declare function forwardHostQuestion(host: string, repo: string): string;
|
|
548
572
|
/** The question for a call whose gateway routes lead back where they came from (A-gateway2). */
|
|
549
573
|
export declare function gatewayCycleQuestion(f: Call, component: string, gateway: string): string;
|
|
574
|
+
/**
|
|
575
|
+
* A host's registrable domain (`northwind.example` for `api.northwind.example`,
|
|
576
|
+
* `northwind.co.uk` for `api.northwind.co.uk`), or undefined for a name the outside rule can't
|
|
577
|
+
* place: one label, `localhost`, an address, a private or in-cluster name (`.corp`, `.svc`), a
|
|
578
|
+
* Service and its namespace (`wallets.payments`, `wallets.qa`, `forge-wallets.dev`: two labels
|
|
579
|
+
* whose last is no `PUBLIC_TLDS` name). A wildcard and a port are left off.
|
|
580
|
+
*/
|
|
581
|
+
export declare function registrableDomain(host: string): string | undefined;
|
|
550
582
|
/**
|
|
551
583
|
* The host a call goes to as the join reads it (P1): the call's own host, else the host of the
|
|
552
584
|
* config fact its `base` names (the first by id), else the base itself; `host:port` when the text
|
|
@@ -554,12 +586,6 @@ export declare function gatewayCycleQuestion(f: Call, component: string, gateway
|
|
|
554
586
|
* no key that reads as a host). The measure uses it to tell which outside system took a call.
|
|
555
587
|
*/
|
|
556
588
|
export declare function callHostOf(f: Call, repoFacts: readonly Fact[]): string | undefined;
|
|
557
|
-
/**
|
|
558
|
-
* J0: a config placeholder: `${X}` or Spring's `${X:default}` anywhere in a value (a URL may be
|
|
559
|
-
* written around it, `https://${HOST}/v2`), `env:X` as the whole value, or a build or deploy
|
|
560
|
-
* token `@X@` (Maven filtering, a gateway bundle's token replace from CI properties). With two in one value
|
|
561
|
-
* (`${SCHEME}://${HOST}/v1`) this is the first, the rest left in `after`.
|
|
562
|
-
*/
|
|
563
589
|
export declare function placeholderIn(s: string | undefined): {
|
|
564
590
|
name: string;
|
|
565
591
|
fallback?: string;
|
package/npm/core/facts.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
1
2
|
import type { CatalogRecord } from "./catalog.js";
|
|
2
3
|
import { Fact, type FactOf } from "./schema/facts.js";
|
|
3
4
|
/**
|
|
@@ -14,14 +15,48 @@ export interface FactIssue {
|
|
|
14
15
|
code: string;
|
|
15
16
|
message: string;
|
|
16
17
|
}
|
|
18
|
+
/**
|
|
19
|
+
* A fact of a kind this Atticus doesn't know (beta.25, ADR 0192 addendum): a newer Atticus wrote
|
|
20
|
+
* it. It is left out of what is read, and said, rather than refusing the whole file; whoever
|
|
21
|
+
* writes the file back must keep it (or not write), since it is a teammate's fact.
|
|
22
|
+
*/
|
|
23
|
+
export interface NewerFact {
|
|
24
|
+
line?: number;
|
|
25
|
+
factId: string;
|
|
26
|
+
kind: string;
|
|
27
|
+
message: string;
|
|
28
|
+
/** The line as written (a line-by-line read), for a writer to keep it as it is. */
|
|
29
|
+
raw?: string;
|
|
30
|
+
}
|
|
17
31
|
export type ParseFactsResult = {
|
|
18
32
|
ok: true;
|
|
19
33
|
facts: Fact[];
|
|
34
|
+
/** Beta.25: the facts of kinds a newer Atticus wrote, left out of `facts`. */
|
|
35
|
+
newer?: NewerFact[];
|
|
20
36
|
} | {
|
|
21
37
|
ok: false;
|
|
22
38
|
issues: FactIssue[];
|
|
23
39
|
};
|
|
40
|
+
/** A JSON value that is a fact of a kind this Atticus doesn't know, said as one; else undefined. */
|
|
41
|
+
export declare function newerFactOf(json: unknown, line?: number): NewerFact | undefined;
|
|
42
|
+
/**
|
|
43
|
+
* Review of beta.25: a fact of a kind this Atticus knows that a newer Atticus wrote: every reason
|
|
44
|
+
* it doesn't read is a field this Atticus doesn't know (a name as Atticus writes them, never a
|
|
45
|
+
* slip of one the kind has: `nearFieldOf`) or a value of one of its lists it doesn't know (a
|
|
46
|
+
* lowercase word more than two edits from each of the list's values, as `scope: "shaded"`; never
|
|
47
|
+
* `scope: "system"`, which is recorded as provided). Said as such, so the fact is left out on its
|
|
48
|
+
* own and kept as written; anything else wrong is a wrong fact, refused for the assistant to fix.
|
|
49
|
+
*/
|
|
50
|
+
export declare function newerShapeOf(json: unknown, issues: readonly z.core.$ZodIssue[], line?: number): NewerFact | undefined;
|
|
24
51
|
export declare function parseFacts(text: string): ParseFactsResult;
|
|
52
|
+
/**
|
|
53
|
+
* A facts file's line as it may be kept where people read it (`<repo>.rejected.jsonl`), beta.25
|
|
54
|
+
* review: a config fact any of whose fields carries a secret (`configSecretField`, beta.24's value
|
|
55
|
+
* check included, or a quote `redactSecrets` changes) has its value, source, parts and quote
|
|
56
|
+
* redacted, the rest kept as written. A line that isn't JSON is redacted as a line of code is,
|
|
57
|
+
* and any quoted literal that reads as a credential goes too. Anything else is kept as it is.
|
|
58
|
+
*/
|
|
59
|
+
export declare function redactFactLine(raw: string): string;
|
|
25
60
|
/** A line of a facts file that isn't a fact, with its number, its text and what is wrong. */
|
|
26
61
|
export type BadFactLine = {
|
|
27
62
|
line: number;
|
|
@@ -37,6 +72,7 @@ export type BadFactLine = {
|
|
|
37
72
|
export declare function parseFactLine(raw: string, line: number, seen: Set<string>): {
|
|
38
73
|
fact?: Fact;
|
|
39
74
|
bad?: BadFactLine;
|
|
75
|
+
newer?: NewerFact;
|
|
40
76
|
};
|
|
41
77
|
/**
|
|
42
78
|
* Read a JSONL facts file line by line, keeping every line that reads and returning the others
|
|
@@ -49,6 +85,8 @@ export declare function parseFactLine(raw: string, line: number, seen: Set<strin
|
|
|
49
85
|
export declare function parseFactsLines(text: string): {
|
|
50
86
|
facts: Fact[];
|
|
51
87
|
bad: BadFactLine[];
|
|
88
|
+
/** Beta.25: facts of kinds a newer Atticus wrote, left out of `facts` (`newerFactOf`). */
|
|
89
|
+
newer: NewerFact[];
|
|
52
90
|
};
|
|
53
91
|
/** One canonical JSON line per fact, sorted by id; the same facts give the same bytes. */
|
|
54
92
|
export declare function serializeFacts(facts: readonly Fact[]): string;
|
|
@@ -71,6 +109,27 @@ export interface ProjectResult {
|
|
|
71
109
|
export declare const factIdPart: (text: string) => string;
|
|
72
110
|
/** The Endpoint id an entry fact projects to in its component (`projectFacts`). */
|
|
73
111
|
export declare function entryEndpointId(f: FactOf<"entry">, component: string): string;
|
|
112
|
+
/**
|
|
113
|
+
* The component a fact is placed in that names one its repo's manifest doesn't have (review of
|
|
114
|
+
* beta.25, ADR 0192 addendum §2): a repo whose manifest entry lists no modules ships as its one
|
|
115
|
+
* component, so a fact (an entry, a call, a store, any but a build's coordinates, which the
|
|
116
|
+
* verifier refuses instead) naming a component that is neither the repo's own nor one the
|
|
117
|
+
* manifest names anywhere (`ledger-api`, a folder's name) is the repo's component's, and its
|
|
118
|
+
* endpoints are in the box its depends-on arrow starts from. Undefined when the fact stays as it
|
|
119
|
+
* is: it names none, or one the manifest names, or the repo lists modules, or it is a prototype
|
|
120
|
+
* (ADR 0133: its UI, BFF and mocks are components of their own, read and compared, never
|
|
121
|
+
* written into the catalog).
|
|
122
|
+
*/
|
|
123
|
+
export declare function placedComponentOf(f: Fact, manifest: {
|
|
124
|
+
/** The repo's own component (the manifest's `component`, else its id). */
|
|
125
|
+
component: string;
|
|
126
|
+
/** The repo's modules as the manifest lists them. */
|
|
127
|
+
modules?: readonly unknown[] | undefined;
|
|
128
|
+
/** Every component (and repo id) the estate's manifests name. */
|
|
129
|
+
components: readonly string[];
|
|
130
|
+
/** The repo is a prototype (its manifest `type`). */
|
|
131
|
+
prototype?: boolean | undefined;
|
|
132
|
+
}): string | undefined;
|
|
74
133
|
/**
|
|
75
134
|
* A call's normalised path: a gRPC method stays `package.Service/Method` and a SOAP operation
|
|
76
135
|
* `Contract/Operation` (a client may write either with a leading slash); an HTTP path loses a parameter's optional marker and constraint first
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { type Document } from "yaml";
|
|
1
2
|
import { type LineChange } from "./manifest-edit.js";
|
|
2
3
|
/**
|
|
3
4
|
* Which repo answers on a host (ADR 0088): a scan or atticus estate join asks, as a question
|
|
@@ -36,6 +37,118 @@ export declare function topicOfQuestion(q: {
|
|
|
36
37
|
export declare const PICKER_LABELS: ReadonlySet<string>;
|
|
37
38
|
/** The last option of a hosts question: no repo of the estate answers on it. */
|
|
38
39
|
export declare const HOSTS_NONE = "None of these";
|
|
40
|
+
/**
|
|
41
|
+
* The step `atticus estate join` asks which component a spec step's call-out reaches by (named
|
|
42
|
+
* here so the answer's rules below are checked where it is written; the CLI raises it).
|
|
43
|
+
*/
|
|
44
|
+
export declare const ESTATE_TARGETS_STEP_ID = "estate-targets";
|
|
45
|
+
/**
|
|
46
|
+
* Beta.24 review (answers made into boxes): the questions about where calls go, whose answer the
|
|
47
|
+
* join reads: hosts, targets (an ambiguous call or an unknown host's), topics and the estate's
|
|
48
|
+
* call-outs. Each takes Ignore, and none takes words that name nothing as a system.
|
|
49
|
+
*/
|
|
50
|
+
export declare const JOIN_STEPS: ReadonlySet<string>;
|
|
51
|
+
/**
|
|
52
|
+
* The option every join question has (beta.24 review): the calls it asks about aren't real calls
|
|
53
|
+
* (CI/CD, a test, a template), so the join leaves them, the same as "None of these", and never
|
|
54
|
+
* draws a box for them. Its words with a reason are `Ignore: <reason>`.
|
|
55
|
+
*/
|
|
56
|
+
export declare const JOIN_IGNORE_LABEL = "Ignore: not a real call (e.g. CI/CD, a test, a template)";
|
|
57
|
+
/** How an Ignore answer with a reason starts (the person's words follow it). */
|
|
58
|
+
export declare const IGNORE_PREFIX = "Ignore:";
|
|
59
|
+
/** The Ignore option, as a question file holds it. */
|
|
60
|
+
export declare const ignoreOption: () => {
|
|
61
|
+
label: string;
|
|
62
|
+
means: string;
|
|
63
|
+
changes: string;
|
|
64
|
+
};
|
|
65
|
+
/** Beta.25: the longest reason an Ignore keeps, as the local API takes it. */
|
|
66
|
+
export declare const IGNORE_REASON_MAX = 300;
|
|
67
|
+
/** An Ignore answer's words: `Ignore: <reason>`. */
|
|
68
|
+
export declare const ignoreText: (reason: string) => string;
|
|
69
|
+
/**
|
|
70
|
+
* Whether a question's answer is Ignore (beta.24 review), and its reason when one was given: the
|
|
71
|
+
* Ignore option, or words that start `Ignore:`. Undefined for any other answer, or none.
|
|
72
|
+
*/
|
|
73
|
+
export declare function ignoredAnswer(q: {
|
|
74
|
+
options: readonly {
|
|
75
|
+
label: string;
|
|
76
|
+
}[];
|
|
77
|
+
answer?: {
|
|
78
|
+
option?: number;
|
|
79
|
+
text?: string;
|
|
80
|
+
by: unknown;
|
|
81
|
+
} | undefined;
|
|
82
|
+
}): {
|
|
83
|
+
reason?: string;
|
|
84
|
+
} | undefined;
|
|
85
|
+
/** The longest name an outside system an answer adds may have. */
|
|
86
|
+
export declare const SYSTEM_NAME_MAX = 40;
|
|
87
|
+
/**
|
|
88
|
+
* Beta.25 (review of beta.24): whether a system's name reads as a sentence: by its words only,
|
|
89
|
+
* two or more of a sentence's small words ("ignore this, its cicd related"). Never by its marks:
|
|
90
|
+
* a real system's name may have a comma, a full stop or a `!` in it ("Northwind, Inc.", "Harbor
|
|
91
|
+
* Co."), and a profile holds what its people wrote.
|
|
92
|
+
*/
|
|
93
|
+
export declare function nameReadsAsSentence(name: string): boolean;
|
|
94
|
+
/**
|
|
95
|
+
* Beta.25 (review of beta.24): whether words read as a sentence rather than a name: a sentence's
|
|
96
|
+
* marks (a comma, a semicolon, `!`, `?`, a quote, or a full stop that ends a word: never the dots
|
|
97
|
+
* of a host), or two or more of a sentence's small words ("ignore this, its cicd related"). A name
|
|
98
|
+
* of any length in words ("Payments API Gateway North East") is a name, and so is one with a
|
|
99
|
+
* single small word in it ("IT Service Desk", "Plan A").
|
|
100
|
+
*/
|
|
101
|
+
export declare function readsAsSentence(words: string): boolean;
|
|
102
|
+
/**
|
|
103
|
+
* Why words can't be a new outside system's name (beta.24 review), or undefined when they can: a
|
|
104
|
+
* short name of letters, digits, spaces and dashes, at most 40 characters, that doesn't read as a
|
|
105
|
+
* sentence (`readsAsSentence`). Lenient for names: "IT Service Desk", "Plan A" and a five-word
|
|
106
|
+
* name are names.
|
|
107
|
+
*/
|
|
108
|
+
export declare function systemNameProblem(name: string): string | undefined;
|
|
109
|
+
/** The names Atticus knows a target by (`knownTargetNames`). */
|
|
110
|
+
export interface KnownTargets {
|
|
111
|
+
ids: Set<string>;
|
|
112
|
+
names: Set<string>;
|
|
113
|
+
/**
|
|
114
|
+
* Beta.25: the profiles' systems' names exactly, lower case, marks and all ("northwind, inc."),
|
|
115
|
+
* of those whose name isn't a sentence by its words (`nameReadsAsSentence`).
|
|
116
|
+
*/
|
|
117
|
+
systemNames?: Set<string>;
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* Beta.25: the names Atticus knows a target by, as `namesKnownTarget` reads them: `ids` the ids
|
|
121
|
+
* (repos, components, a system's id, alias or topic, teams) exactly, lower case; `names` those and
|
|
122
|
+
* the systems' names, each also as the id it slugs to; `systemNames` the systems' names exactly.
|
|
123
|
+
* Systems whose id is in `except` are left out (the boxes an answer's words made, which name
|
|
124
|
+
* nothing real).
|
|
125
|
+
*/
|
|
126
|
+
export declare function knownTargetNames(root: string, o?: {
|
|
127
|
+
except?: ReadonlySet<string>;
|
|
128
|
+
}): Promise<Required<KnownTargets>>;
|
|
129
|
+
/**
|
|
130
|
+
* Whether words name a target of `knownTargetNames`: a profile system's name exactly, case aside
|
|
131
|
+
* (beta.25: "Northwind, Inc." names the system so named, its marks and all); else case and spacing
|
|
132
|
+
* aside, or by the id they slug to; words that read as a sentence only when they are an id exactly
|
|
133
|
+
* (a sentence is never a system's name, even one an answer's words once wrote into a profile).
|
|
134
|
+
*/
|
|
135
|
+
export declare function namesKnown(known: KnownTargets, words: string): boolean;
|
|
136
|
+
/**
|
|
137
|
+
* Beta.24 review: whether words name a repo, component, system or team Atticus knows, as an
|
|
138
|
+
* answer about where calls go may: a repo of the manifests (its id, component or a module's
|
|
139
|
+
* component), a system of the profiles (its id, name, an alias or a topic), a team of roles.yaml,
|
|
140
|
+
* or a component a repo's facts name. Case and spacing aside, or by the id the words slug to.
|
|
141
|
+
* Beta.25: words that read as a sentence name only an id they are exactly, and the systems in
|
|
142
|
+
* `except` (the boxes an answer's words made) are none.
|
|
143
|
+
*/
|
|
144
|
+
export declare function namesKnownTarget(root: string, words: string, o?: {
|
|
145
|
+
except?: ReadonlySet<string>;
|
|
146
|
+
}): Promise<boolean>;
|
|
147
|
+
/**
|
|
148
|
+
* Beta.24 review: the refusal of words that name no repo, component or system as the answer of a
|
|
149
|
+
* question about where calls go, in a person's words: what to do instead.
|
|
150
|
+
*/
|
|
151
|
+
export declare const wordsNameNothing: (words: string) => string;
|
|
39
152
|
/**
|
|
40
153
|
* The options of a hosts question that say an outside system answers on the host (O1): another
|
|
41
154
|
* team's system (boundary internal, the first, the default) or a vendor's. The answer writes the
|
|
@@ -57,6 +170,41 @@ export declare const hostQuestionText: (host: string) => string;
|
|
|
57
170
|
export declare function hostOfQuestion(q: {
|
|
58
171
|
question: string;
|
|
59
172
|
}): string | undefined;
|
|
173
|
+
/**
|
|
174
|
+
* Beta.24 review: the host a targets question the join raised for a host nothing resolves asks
|
|
175
|
+
* about (a gateway's forwarding call whose target URL is a token, `@targetUrl@`): its words start
|
|
176
|
+
* as a hosts question's do, and may go on to say what to do next (`forwardHostQuestion`). A
|
|
177
|
+
* targets question asked of a call (`Which repo or system answers ...`) has none. Beta.25: the
|
|
178
|
+
* host up to the first `?` that ends the question, so a token with spaces in it (`{{ vendor_url
|
|
179
|
+
* }}`, as `forwardHostQuestion` writes it) is read back whole.
|
|
180
|
+
*/
|
|
181
|
+
export declare function joinHostOfQuestion(q: {
|
|
182
|
+
question: string;
|
|
183
|
+
}): string | undefined;
|
|
184
|
+
/**
|
|
185
|
+
* The outside system an answer to a join host question adds (beta.24 review): named by the host,
|
|
186
|
+
* or for a host still written as a token, by the token's name (`@targetVendorUrl@` →
|
|
187
|
+
* `targetVendorUrl`), never with the token's marks in its id.
|
|
188
|
+
*/
|
|
189
|
+
export declare function outsideSystemOfJoinHost(host: string): {
|
|
190
|
+
id: string;
|
|
191
|
+
name: string;
|
|
192
|
+
};
|
|
193
|
+
/**
|
|
194
|
+
* Beta.25 (review of beta.24): the one way every profile edit is written (an outside system, a
|
|
195
|
+
* system a person named, a box put right), so a preview shows only the lines that really change:
|
|
196
|
+
* no line folded (`lineWidth: 0`), flow collections padded as the file pads them (`[ a ]` or
|
|
197
|
+
* `[a]`), and each line the edit didn't change kept exactly as the file had it (the library pads
|
|
198
|
+
* a file's maps and lists alike, so a file that mixes `{ a: 1 }` with `[b]` keeps both). LF only;
|
|
199
|
+
* the caller writes it in the file's own line endings.
|
|
200
|
+
*/
|
|
201
|
+
export declare function profileText(doc: Document, before: string | undefined): string;
|
|
202
|
+
/**
|
|
203
|
+
* Beta.25 (review of beta.24): a profile edit Atticus doesn't make, said in a person's words (the
|
|
204
|
+
* local API answers 422): the file stays as it is, for a person to change by hand.
|
|
205
|
+
*/
|
|
206
|
+
export declare class ProfileEditError extends Error {
|
|
207
|
+
}
|
|
60
208
|
/**
|
|
61
209
|
* Put an outside system for a host into the profile whose repos.manifest.yaml lists the repo
|
|
62
210
|
* that asked (O1): its id and name from the host, the host as its alias, the boundary given
|
|
@@ -97,7 +245,39 @@ export declare function addProfileSystem(root: string, repo: string, s: {
|
|
|
97
245
|
topics?: string[];
|
|
98
246
|
/** The lines a new system changes in the profile (as the write makes them). */
|
|
99
247
|
changes?: LineChange[];
|
|
248
|
+
/**
|
|
249
|
+
* Beta.25: for a new system, the file, the text it was read as (undefined: none yet) and the
|
|
250
|
+
* text written (or, previewed, to write), so a caller can write it with others, all or none.
|
|
251
|
+
*/
|
|
252
|
+
write?: {
|
|
253
|
+
file: string;
|
|
254
|
+
before: string | undefined;
|
|
255
|
+
after: string;
|
|
256
|
+
};
|
|
100
257
|
}>;
|
|
258
|
+
/**
|
|
259
|
+
* Beta.24 review: take a system out of the profile that has it, or (with `rename`) give it another
|
|
260
|
+
* id and name, keeping its other fields, the file's comments and its order (a comment above a
|
|
261
|
+
* system taken out stays, above the next). For a system an answer's words made (a box on Map ›
|
|
262
|
+
* Trust): written as a file change in the
|
|
263
|
+
* metarepo, for review in the pull request. `preview` writes nothing. Undefined when no profile
|
|
264
|
+
* has the system. Throws when the profile would not be valid (the new id another system has).
|
|
265
|
+
*/
|
|
266
|
+
export declare function editProfileSystem(root: string, id: string, o?: {
|
|
267
|
+
rename?: {
|
|
268
|
+
id: string;
|
|
269
|
+
name: string;
|
|
270
|
+
};
|
|
271
|
+
preview?: boolean;
|
|
272
|
+
}): Promise<{
|
|
273
|
+
profile: string;
|
|
274
|
+
changes: LineChange[];
|
|
275
|
+
written: boolean;
|
|
276
|
+
/** Beta.25: the file, the text it was read as and the text written (or to write). */
|
|
277
|
+
file: string;
|
|
278
|
+
before: string;
|
|
279
|
+
after: string;
|
|
280
|
+
} | undefined>;
|
|
101
281
|
/**
|
|
102
282
|
* Put a host under a repo's `hosts` in the repos.manifest.yaml that lists it, keeping the
|
|
103
283
|
* file's comments and order. `added` is false when the repo already lists it. Throws when no
|
package/npm/core/identity.d.ts
CHANGED
|
@@ -1,20 +1,4 @@
|
|
|
1
|
-
|
|
2
|
-
* Normalise an HTTP path or topic so the same interface found in different places
|
|
3
|
-
* (caller code, gateway route, callee controller) gets the same identity.
|
|
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
|
|
9
|
-
*/
|
|
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;
|
|
1
|
+
export { normalizePath, stripParamConstraints } from "./paths.js";
|
|
18
2
|
/** Code-unit string order, the same in every locale (`localeCompare` is not: ICU orders `_`/`-`
|
|
19
3
|
* and, in `da`, `aa` differently), for every sort that feeds records, ids, hashes or a merge. */
|
|
20
4
|
export declare function cmpText(a: string, b: string): number;
|
package/npm/core/index.d.ts
CHANGED
|
@@ -11,6 +11,7 @@ export * from "./facts-join-prototype.js";
|
|
|
11
11
|
export * from "./facts-carry.js";
|
|
12
12
|
export * from "./facts-callers.js";
|
|
13
13
|
export * from "./facts-terms.js";
|
|
14
|
+
export * from "./facts-deps.js";
|
|
14
15
|
export * from "./org-notes.js";
|
|
15
16
|
export * from "./link-evidence.js";
|
|
16
17
|
export * from "./shared-maps.js";
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@maycombhq/core/paths`: how the join normalises an HTTP path or a topic, with no imports, so
|
|
3
|
+
* the app (a browser bundle that takes nothing else of core at run time) matches a call's path to
|
|
4
|
+
* a link's exactly as the join made the link (review of beta.24). The same export as the
|
|
5
|
+
* package's own (`@maycombhq/core`).
|
|
6
|
+
*/
|
|
7
|
+
/**
|
|
8
|
+
* Normalise an HTTP path or topic so the same interface found in different places
|
|
9
|
+
* (caller code, gateway route, callee controller) gets the same identity.
|
|
10
|
+
*
|
|
11
|
+
* - path parameters in any style ({id}, :id, <id>, ${id}) become "{}"
|
|
12
|
+
* - query strings and fragments are dropped
|
|
13
|
+
* - repeated and trailing slashes are removed; a leading slash is ensured for paths
|
|
14
|
+
* - topics (no leading slash in the input and no "/" at all) are returned trimmed
|
|
15
|
+
*/
|
|
16
|
+
export declare function normalizePath(input: string): string;
|
|
17
|
+
/**
|
|
18
|
+
* A path with each `{...}` parameter cut to its name: what follows the first `:`, `?` or `=` in
|
|
19
|
+
* braces nested inside a constraint (`{code:regex(^\\d{3}$)}`) are matched, not cut at the first `}`.
|
|
20
|
+
* braces nested inside a constraint (`{code:regex(^\\d{{3}}$)}`) are matched, not cut at the first `}`.
|
|
21
|
+
* An unclosed `{` leaves the rest as written.
|
|
22
|
+
*/
|
|
23
|
+
export declare function stripParamConstraints(path: string): string;
|
package/npm/core/questions.d.ts
CHANGED
|
@@ -318,6 +318,20 @@ export interface AnswerInput {
|
|
|
318
318
|
batch?: string;
|
|
319
319
|
/** ADR 0181: a person's rule applies it, from their correction. */
|
|
320
320
|
rule?: AppliedRule;
|
|
321
|
+
/**
|
|
322
|
+
* Beta.24 review: Ignore, for a question about where calls go: they aren't real calls (CI/CD, a
|
|
323
|
+
* test, a template), so the join leaves them. In place of option and text; the reason, when
|
|
324
|
+
* given, is the answer's words (`Ignore: <reason>`), else the Ignore option is picked (added to
|
|
325
|
+
* the question's options when it was asked before Ignore was offered).
|
|
326
|
+
*/
|
|
327
|
+
ignore?: {
|
|
328
|
+
reason?: string;
|
|
329
|
+
};
|
|
330
|
+
/**
|
|
331
|
+
* Beta.24 review: the id of the system `beforeWrite` adds to the profile, which the answer's
|
|
332
|
+
* words name, so they aren't refused as naming nothing.
|
|
333
|
+
*/
|
|
334
|
+
adds?: string;
|
|
321
335
|
}
|
|
322
336
|
/**
|
|
323
337
|
* Whether a host a hosts question asks about (`localhost:9966`, `limits.payments.forge.internal`)
|
package/npm/core/schema/ai.d.ts
CHANGED
|
@@ -108,8 +108,8 @@ export declare const ContextSource: z.ZodObject<{
|
|
|
108
108
|
pattern: "pattern";
|
|
109
109
|
code: "code";
|
|
110
110
|
document: "document";
|
|
111
|
-
catalog: "catalog";
|
|
112
111
|
artifact: "artifact";
|
|
112
|
+
catalog: "catalog";
|
|
113
113
|
checklist: "checklist";
|
|
114
114
|
skill: "skill";
|
|
115
115
|
instruction: "instruction";
|
|
@@ -134,8 +134,8 @@ export declare const ContextPackManifest: z.ZodObject<{
|
|
|
134
134
|
pattern: "pattern";
|
|
135
135
|
code: "code";
|
|
136
136
|
document: "document";
|
|
137
|
-
catalog: "catalog";
|
|
138
137
|
artifact: "artifact";
|
|
138
|
+
catalog: "catalog";
|
|
139
139
|
checklist: "checklist";
|
|
140
140
|
skill: "skill";
|
|
141
141
|
instruction: "instruction";
|