@maycombhq/sdk 2.0.0-beta.22 → 2.0.0-beta.24
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 +3075 -317
- package/npm/core/cite.d.ts +9 -2
- package/npm/core/facts-deps.d.ts +55 -0
- package/npm/core/facts-join.d.ts +94 -8
- package/npm/core/fs.d.ts +8 -0
- package/npm/core/host-questions.d.ts +105 -0
- package/npm/core/index.d.ts +5 -0
- package/npm/core/kept-files.d.ts +17 -0
- package/npm/core/light.d.ts +2 -0
- package/npm/core/log.d.ts +2 -0
- package/npm/core/manifest-edit.d.ts +21 -3
- package/npm/core/metarepo.d.ts +8 -0
- package/npm/core/orgpack-defaults.d.ts +3 -1
- package/npm/core/printer.d.ts +4 -0
- package/npm/core/question-owners.d.ts +4 -0
- package/npm/core/question-roles.d.ts +64 -4
- package/npm/core/questions.d.ts +28 -3
- package/npm/core/roles-migrate.d.ts +4 -3
- package/npm/core/run-log.d.ts +165 -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 +7 -0
- package/npm/core/schema/facts.d.ts +268 -4
- package/npm/core/schema/frameworks.d.ts +10 -10
- package/npm/core/schema/orgpack.d.ts +22 -6
- package/npm/core/schema/question.d.ts +55 -2
- package/npm/core/schema/review.d.ts +2 -2
- package/npm/core/schema/scan-verify.d.ts +80 -45
- package/npm/core/setup-edit.d.ts +107 -0
- package/npm/index.js +6428 -4882
- package/package.json +1 -1
package/npm/core/cite.d.ts
CHANGED
|
@@ -42,6 +42,12 @@ 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 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
|
+
*/
|
|
50
|
+
export declare function hasSecretShape(text: string): boolean;
|
|
45
51
|
/**
|
|
46
52
|
* Redact the secrets on a line, keeping what names them: a value after a secret-looking key
|
|
47
53
|
* (at the line's start, whatever the value; anywhere on it, a quoted literal), a setter's
|
|
@@ -63,8 +69,9 @@ export declare function quoteHoldsSecret(quote: string): boolean;
|
|
|
63
69
|
* Whether a word claim is put together from `cite.with` parts (ADR 0124 addendum A-derived): a
|
|
64
70
|
* rake task's `namespace:task`, a key a helper prefixes (`${prefix}_conferenceCache`). Each part's
|
|
65
71
|
* 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
|
|
72
|
+
* `: . _ / #`, or another part; `-` joins a word), and whatever is left between the parts,
|
|
73
|
+
* separators aside, must be written on the cited lines: at least one piece, so the cited lines
|
|
74
|
+
* name some of the word. The parts' own lines are checked by the caller.
|
|
68
75
|
*/
|
|
69
76
|
export declare function partsBuildWord(claim: string, parts: readonly string[], lines: readonly string[]): boolean;
|
|
70
77
|
export declare function partsNamePath(lines: readonly string[], path: string): boolean;
|
|
@@ -0,0 +1,55 @@
|
|
|
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
|
+
export interface DependencyLink {
|
|
26
|
+
/** The dependency fact, in the component that builds on the library. */
|
|
27
|
+
from: DependencyEnd;
|
|
28
|
+
/** The artifact fact, in the library's component, that publishes the coordinates. */
|
|
29
|
+
to: DependencyEnd;
|
|
30
|
+
group: string;
|
|
31
|
+
name: string;
|
|
32
|
+
/** The dependency's declared scope, when it says one other than compile. */
|
|
33
|
+
scope?: DependencyScope;
|
|
34
|
+
/** The version the dependency declares, when it says one. */
|
|
35
|
+
version?: string;
|
|
36
|
+
}
|
|
37
|
+
/** Coordinates two or more components of the estate publish: nothing is drawn to either. */
|
|
38
|
+
export interface AmbiguousCoordinates {
|
|
39
|
+
group: string;
|
|
40
|
+
name: string;
|
|
41
|
+
by: FactEnd[];
|
|
42
|
+
}
|
|
43
|
+
export interface DependencyJoinResult {
|
|
44
|
+
links: DependencyLink[];
|
|
45
|
+
ambiguous: AmbiguousCoordinates[];
|
|
46
|
+
/** Dependencies on coordinates nobody in the estate publishes: drawn as nothing. */
|
|
47
|
+
outside: number;
|
|
48
|
+
/** Test-scoped dependencies on the estate's own coordinates: drawn as nothing. */
|
|
49
|
+
test: number;
|
|
50
|
+
}
|
|
51
|
+
export declare function joinDependencies(input: {
|
|
52
|
+
repos: readonly JoinRepo[];
|
|
53
|
+
}): DependencyJoinResult;
|
|
54
|
+
/** The id a "depends on" link is known by, for a view's join: stable across reads of one pom. */
|
|
55
|
+
export declare const dependencyLinkId: (l: Pick<DependencyLink, "from" | "to">) => string;
|
package/npm/core/facts-join.d.ts
CHANGED
|
@@ -41,6 +41,14 @@ import type { Fact, FactOf } from "./schema/facts.js";
|
|
|
41
41
|
* gateway-walk): without it a call is joined to the route it lands on, and each route's
|
|
42
42
|
* forwarding call to its service on its own, so the chain is there in two links, not one.
|
|
43
43
|
*
|
|
44
|
+
* The path suffix (an Apigee proxy to its service): a forwarding call cited in a bundle whose
|
|
45
|
+
* path no entry serves in the same shape is joined per route of its proxy (the route it is from,
|
|
46
|
+
* else the proxy's flows, else its `<BasePath>/**`) at the target's path with the route's suffix
|
|
47
|
+
* after it (none when `target.copy.pathsuffix` is false; everything under it for a pass-through),
|
|
48
|
+
* matched against the service's entries with its base path taken off: the manifest's, an
|
|
49
|
+
* exposure's, its context and servlet path settings, else the longest overlap, a guess
|
|
50
|
+
* (`joined-by-path-overlap`). Each such join cites the route (`forRoute`) and the base (`base`).
|
|
51
|
+
*
|
|
44
52
|
* Placeholders (J0): a base URL, host or topic written as `${X}`, `${X:default}` or `env:X` is
|
|
45
53
|
* each value the config facts setting `X` give it, read in the caller's repo and in any repo of
|
|
46
54
|
* the estate whose setting is for the caller's component (its folder, its deployment, its
|
|
@@ -115,6 +123,27 @@ export interface GatewayHop {
|
|
|
115
123
|
scopes?: string[];
|
|
116
124
|
/** Which side this gateway faces, when the manifest or the proxy's virtual host says. */
|
|
117
125
|
facing?: GatewayFacing;
|
|
126
|
+
/** The base path the service behind this hop serves under, as `FactJoin.base`. */
|
|
127
|
+
base?: JoinBase;
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* The base path a service's entries sit under that the join took off the path an Apigee proxy
|
|
131
|
+
* forwards before matching them (the path suffix): the manifest's `basePath`, an exposure's
|
|
132
|
+
* (`deploy`: an OpenShift Route's or an Ingress's path), the service's own context path and
|
|
133
|
+
* servlet path settings (`config`), or, with none of those, the longest run of the target's path
|
|
134
|
+
* that starts the entry's (`overlap`, a guess: `joined-by-path-overlap`). `by` is the facts it
|
|
135
|
+
* came from (none for the manifest or an overlap).
|
|
136
|
+
*/
|
|
137
|
+
export interface JoinBase {
|
|
138
|
+
path: string;
|
|
139
|
+
/**
|
|
140
|
+
* `url`: nothing names the base, and one route's whole URL (the target's path and the flow's
|
|
141
|
+
* suffix) ends in exactly one entry's whole path, at least one of the target's own segments
|
|
142
|
+
* included: code at both ends, not a guess. `overlap` is that for a pass-through (every entry
|
|
143
|
+
* under a guessed base), a guess.
|
|
144
|
+
*/
|
|
145
|
+
from: "manifest" | "deploy" | "config" | "url" | "overlap";
|
|
146
|
+
by?: FactEnd[];
|
|
118
147
|
}
|
|
119
148
|
/** One end of a join: a fact, its repo and component, and the line it cites. */
|
|
120
149
|
export interface FactEnd {
|
|
@@ -178,6 +207,12 @@ export declare const JOINED_BY_ANSWER = "joined-by-answer";
|
|
|
178
207
|
export declare const JOINED_BY_NAME = "joined-by-name";
|
|
179
208
|
export declare const JOINED_BY_REPO = "joined-by-repo";
|
|
180
209
|
export declare const JOINED_BY_HOST = "joined-by-host";
|
|
210
|
+
/**
|
|
211
|
+
* A call whose host nothing resolves, joined to a gateway proxy's flow by its whole path: the one
|
|
212
|
+
* proxy whose cited `<BasePath>` starts it, the one flow of its method under it. Code at both
|
|
213
|
+
* ends: a how, never a guess.
|
|
214
|
+
*/
|
|
215
|
+
export declare const JOINED_BY_BASE_PATH = "joined-by-base-path";
|
|
181
216
|
/**
|
|
182
217
|
* J0, J1: the guesses a join by host can rest on, though the host itself was cited. The setting
|
|
183
218
|
* that gave the host is a platform-wide one nobody aimed at the caller (`setsForAll`), or one that
|
|
@@ -197,6 +232,16 @@ export declare const JOINED_DESPITE_CONFLICT = "joined-despite-conflict";
|
|
|
197
232
|
export declare const JOINED_BY_SERVICE_NAME = "joined-by-service-name";
|
|
198
233
|
/** G1 (ADR 0174): a person paired the call with this entry on the canvas. */
|
|
199
234
|
export declare const JOINED_BY_PERSON = "joined-by-person";
|
|
235
|
+
/**
|
|
236
|
+
* An Apigee proxy's forwarding call matched the service's entry only by taking off the front of
|
|
237
|
+
* the target's path that nothing names as the service's base path (no manifest `basePath`, no
|
|
238
|
+
* Route or Ingress path, no context path setting): `/forge-limits/v3/limits` and the suffix
|
|
239
|
+
* `/check` against `/limits/check`. A guess, so the link is inferred; the Interface's flag only,
|
|
240
|
+
* not one of `JOIN_GUESS_FLAGS` (the local API's guesses), and its how is the host's.
|
|
241
|
+
*/
|
|
242
|
+
export declare const JOINED_BY_PATH_OVERLAP = "joined-by-path-overlap";
|
|
243
|
+
/** How many entries a `<BasePath>/**` pass-through links to at most, in path order. */
|
|
244
|
+
export declare const MAX_PASS_THROUGH_LINKS = 50;
|
|
200
245
|
/**
|
|
201
246
|
* ADR 0181: the AI decided the link (a pairing, or a target answer), applied by Atticus from its
|
|
202
247
|
* run without a person. A how, never a person's word: the Interface is inferred, its evidence is
|
|
@@ -224,7 +269,7 @@ export declare const JOINED_TO_SHARED_MAP = "joined-to-shared-map";
|
|
|
224
269
|
* or the component's own name as the host), `path` (no target named: the only entry of the
|
|
225
270
|
* estate that serves it), `topic` (a listener of the published topic).
|
|
226
271
|
*/
|
|
227
|
-
export type JoinHow = "answer" | "named" | "repo" | "host" | "path" | "topic";
|
|
272
|
+
export type JoinHow = "answer" | "named" | "repo" | "host" | "base-path" | "path" | "topic";
|
|
228
273
|
export interface FactJoin {
|
|
229
274
|
call: FactEnd;
|
|
230
275
|
entry: FactEnd;
|
|
@@ -304,6 +349,20 @@ export interface FactJoin {
|
|
|
304
349
|
aiHop?: JoinAi & {
|
|
305
350
|
call: FactEnd;
|
|
306
351
|
};
|
|
352
|
+
/**
|
|
353
|
+
* An Apigee proxy's forwarding call (the path suffix): the proxy's route whose requests it
|
|
354
|
+
* carries, when the path the target receives is the target's path and this route's suffix (or,
|
|
355
|
+
* for a `<BasePath>/**` pass-through, everything under the target's path). A call that serves
|
|
356
|
+
* several routes has a join per route.
|
|
357
|
+
*/
|
|
358
|
+
forRoute?: FactEnd;
|
|
359
|
+
/** The service's base path the join took off before matching its entry (the path suffix). */
|
|
360
|
+
base?: JoinBase;
|
|
361
|
+
/**
|
|
362
|
+
* The setting that keeps the proxy's path suffix off (`target.copy.pathsuffix` false, in a
|
|
363
|
+
* JavaScript or AssignMessage policy), so the target receives its own path as it is.
|
|
364
|
+
*/
|
|
365
|
+
suffixOff?: FactEnd;
|
|
307
366
|
}
|
|
308
367
|
/** ADR 0181: the AI run a decision came from. */
|
|
309
368
|
export interface JoinAi {
|
|
@@ -492,8 +551,22 @@ export declare function routeScore(called: string, served: string): number;
|
|
|
492
551
|
export declare function nameScore(called: string, served: string): number;
|
|
493
552
|
/** The question for a call no single repo answers: the same words as the facts-targets question. */
|
|
494
553
|
export declare function callTargetQuestion(f: Call, component: string): string;
|
|
554
|
+
/**
|
|
555
|
+
* The question for a gateway's forwarding call whose host nothing resolves. A host still written
|
|
556
|
+
* as a token (`@targetUrl@`, `{{host}}`, `${HOST}`) is most often one a deploy tool's file sets
|
|
557
|
+
* per environment (the Apigee config plugin's `config.json`), which a read before beta.24 didn't
|
|
558
|
+
* record: the next step it says is to read the gateway repo again, never a guess at a repo.
|
|
559
|
+
*/
|
|
560
|
+
export declare function forwardHostQuestion(host: string, repo: string): string;
|
|
495
561
|
/** The question for a call whose gateway routes lead back where they came from (A-gateway2). */
|
|
496
562
|
export declare function gatewayCycleQuestion(f: Call, component: string, gateway: string): string;
|
|
563
|
+
/**
|
|
564
|
+
* A host's registrable domain (`northwind.example` for `api.northwind.example`,
|
|
565
|
+
* `northwind.co.uk` for `api.northwind.co.uk`), or undefined for a name the outside rule can't
|
|
566
|
+
* place: one label, `localhost`, an address, a private or in-cluster name (`.corp`, `.svc`), a
|
|
567
|
+
* Service and its namespace (`wallets.payments`). A wildcard and a port are left off.
|
|
568
|
+
*/
|
|
569
|
+
export declare function registrableDomain(host: string): string | undefined;
|
|
497
570
|
/**
|
|
498
571
|
* The host a call goes to as the join reads it (P1): the call's own host, else the host of the
|
|
499
572
|
* config fact its `base` names (the first by id), else the base itself; `host:port` when the text
|
|
@@ -501,12 +574,6 @@ export declare function gatewayCycleQuestion(f: Call, component: string, gateway
|
|
|
501
574
|
* no key that reads as a host). The measure uses it to tell which outside system took a call.
|
|
502
575
|
*/
|
|
503
576
|
export declare function callHostOf(f: Call, repoFacts: readonly Fact[]): string | undefined;
|
|
504
|
-
/**
|
|
505
|
-
* J0: a config placeholder: `${X}` or Spring's `${X:default}` anywhere in a value (a URL may be
|
|
506
|
-
* written around it, `https://${HOST}/v2`), `env:X` as the whole value, or a build or deploy
|
|
507
|
-
* token `@X@` (Maven filtering, a gateway bundle's token replace from CI properties). With two in one value
|
|
508
|
-
* (`${SCHEME}://${HOST}/v1`) this is the first, the rest left in `after`.
|
|
509
|
-
*/
|
|
510
577
|
export declare function placeholderIn(s: string | undefined): {
|
|
511
578
|
name: string;
|
|
512
579
|
fallback?: string;
|
|
@@ -547,8 +614,23 @@ export declare function basePathOf(e: Entry): string;
|
|
|
547
614
|
* by a Service's short name (J1). Empty for a join nobody had to guess.
|
|
548
615
|
*/
|
|
549
616
|
export declare function joinGuessesOf(j: Pick<FactJoin, "inferred" | "byLabel" | "guesses">): JoinGuessFlag[];
|
|
617
|
+
/**
|
|
618
|
+
* Whether an Apigee forwarding call on the way matched its entry only by a guessed base path
|
|
619
|
+
* (`joined-by-path-overlap`): the join's own, or a gateway hop's.
|
|
620
|
+
*/
|
|
621
|
+
export declare const isOverlapJoin: (j: {
|
|
622
|
+
base?: JoinBase | undefined;
|
|
623
|
+
gateway?: readonly {
|
|
624
|
+
base?: JoinBase | undefined;
|
|
625
|
+
}[] | undefined;
|
|
626
|
+
}) => boolean;
|
|
550
627
|
/** Whether a join guessed its callee anywhere on the way (`joinGuessesOf` gives how). */
|
|
551
|
-
export declare const isGuessedJoin: (j: Pick<FactJoin, "inferred" | "byLabel" | "guesses">
|
|
628
|
+
export declare const isGuessedJoin: (j: Pick<FactJoin, "inferred" | "byLabel" | "guesses"> & {
|
|
629
|
+
base?: JoinBase | undefined;
|
|
630
|
+
gateway?: readonly {
|
|
631
|
+
base?: JoinBase | undefined;
|
|
632
|
+
}[] | undefined;
|
|
633
|
+
}) => boolean;
|
|
552
634
|
/**
|
|
553
635
|
* How a join found its callee, as its Interface's flags (C1, ADR 0135): a guess by its own F2
|
|
554
636
|
* flags alone (`JOIN_GUESS_FLAGS`: by path or label, F2; by a platform setting or a folder name,
|
|
@@ -562,6 +644,10 @@ export declare const aiOfJoin: (j: Pick<FactJoin, "how" | "paired"> & {
|
|
|
562
644
|
export declare function joinFlagsOf(j: Pick<FactJoin, "how" | "inferred" | "byLabel" | "guesses" | "paired"> & {
|
|
563
645
|
aiAnswer?: JoinAi | undefined;
|
|
564
646
|
aiHop?: JoinAi | undefined;
|
|
647
|
+
base?: JoinBase | undefined;
|
|
648
|
+
gateway?: readonly {
|
|
649
|
+
base?: JoinBase | undefined;
|
|
650
|
+
}[] | undefined;
|
|
565
651
|
}): string[];
|
|
566
652
|
/**
|
|
567
653
|
* A shared link's flags (ADR 0135, section 5): each once, the union of its joins'. A verified link
|
package/npm/core/fs.d.ts
CHANGED
|
@@ -53,6 +53,13 @@ o?: {
|
|
|
53
53
|
}>;
|
|
54
54
|
/** The lock file beside a file two processes write (`<file>.lock`): no facts-folder reader takes it for a file of its own. */
|
|
55
55
|
export declare const sharedLockFileOf: (path: string) => string;
|
|
56
|
+
/**
|
|
57
|
+
* Review of beta.23: the options of a lock that guards only a quick write (a stage's loop file,
|
|
58
|
+
* its thread, the stories' numbers): older than two minutes, it is stale whoever holds it.
|
|
59
|
+
*/
|
|
60
|
+
export declare const QUICK_WRITE_LOCK: {
|
|
61
|
+
readonly maxAgeMs: 120000;
|
|
62
|
+
};
|
|
56
63
|
/**
|
|
57
64
|
* Review round 46: run `work` holding a file that another process may append to or rewrite at
|
|
58
65
|
* the same time (a repo's corrections: the app server appends, a CLI command rewrites it), so a
|
|
@@ -67,6 +74,7 @@ export declare function withSharedFileLock<T>(path: string, work: () => Promise<
|
|
|
67
74
|
staleMs?: number;
|
|
68
75
|
waitMs?: number;
|
|
69
76
|
what?: string;
|
|
77
|
+
maxAgeMs?: number;
|
|
70
78
|
}): Promise<T>;
|
|
71
79
|
/**
|
|
72
80
|
* What stays on this machine inside .atticus/: the person's settings, the log, locks, upgrade
|
|
@@ -36,6 +36,75 @@ export declare function topicOfQuestion(q: {
|
|
|
36
36
|
export declare const PICKER_LABELS: ReadonlySet<string>;
|
|
37
37
|
/** The last option of a hosts question: no repo of the estate answers on it. */
|
|
38
38
|
export declare const HOSTS_NONE = "None of these";
|
|
39
|
+
/**
|
|
40
|
+
* The step `atticus estate join` asks which component a spec step's call-out reaches by (named
|
|
41
|
+
* here so the answer's rules below are checked where it is written; the CLI raises it).
|
|
42
|
+
*/
|
|
43
|
+
export declare const ESTATE_TARGETS_STEP_ID = "estate-targets";
|
|
44
|
+
/**
|
|
45
|
+
* Beta.24 review (answers made into boxes): the questions about where calls go, whose answer the
|
|
46
|
+
* join reads: hosts, targets (an ambiguous call or an unknown host's), topics and the estate's
|
|
47
|
+
* call-outs. Each takes Ignore, and none takes words that name nothing as a system.
|
|
48
|
+
*/
|
|
49
|
+
export declare const JOIN_STEPS: ReadonlySet<string>;
|
|
50
|
+
/**
|
|
51
|
+
* The option every join question has (beta.24 review): the calls it asks about aren't real calls
|
|
52
|
+
* (CI/CD, a test, a template), so the join leaves them, the same as "None of these", and never
|
|
53
|
+
* draws a box for them. Its words with a reason are `Ignore: <reason>`.
|
|
54
|
+
*/
|
|
55
|
+
export declare const JOIN_IGNORE_LABEL = "Ignore: not a real call (e.g. CI/CD, a test, a template)";
|
|
56
|
+
/** How an Ignore answer with a reason starts (the person's words follow it). */
|
|
57
|
+
export declare const IGNORE_PREFIX = "Ignore:";
|
|
58
|
+
/** The Ignore option, as a question file holds it. */
|
|
59
|
+
export declare const ignoreOption: () => {
|
|
60
|
+
label: string;
|
|
61
|
+
means: string;
|
|
62
|
+
changes: string;
|
|
63
|
+
};
|
|
64
|
+
/** An Ignore answer's words: `Ignore: <reason>`. */
|
|
65
|
+
export declare const ignoreText: (reason: string) => string;
|
|
66
|
+
/**
|
|
67
|
+
* Whether a question's answer is Ignore (beta.24 review), and its reason when one was given: the
|
|
68
|
+
* Ignore option, or words that start `Ignore:`. Undefined for any other answer, or none.
|
|
69
|
+
*/
|
|
70
|
+
export declare function ignoredAnswer(q: {
|
|
71
|
+
options: readonly {
|
|
72
|
+
label: string;
|
|
73
|
+
}[];
|
|
74
|
+
answer?: {
|
|
75
|
+
option?: number;
|
|
76
|
+
text?: string;
|
|
77
|
+
by: unknown;
|
|
78
|
+
} | undefined;
|
|
79
|
+
}): {
|
|
80
|
+
reason?: string;
|
|
81
|
+
} | undefined;
|
|
82
|
+
/** The longest name an outside system an answer adds may have. */
|
|
83
|
+
export declare const SYSTEM_NAME_MAX = 40;
|
|
84
|
+
/**
|
|
85
|
+
* Why words can't be a new outside system's name (beta.24 review), or undefined when they can: a
|
|
86
|
+
* short name of letters, digits, spaces and dashes, at most 40 characters, not a sentence (four
|
|
87
|
+
* words at most, none of "ignore", "this", "is", "a", "to", "the", "related", "not", "it").
|
|
88
|
+
*/
|
|
89
|
+
export declare function systemNameProblem(name: string): string | undefined;
|
|
90
|
+
/**
|
|
91
|
+
* Beta.24 review: whether a system (its id, and its name when it has one) looks made from an
|
|
92
|
+
* answer's words rather than named: an id of five or more dash-separated words, or with a word
|
|
93
|
+
* of a sentence in it, or a name with spaces longer than 40 characters.
|
|
94
|
+
*/
|
|
95
|
+
export declare function madeFromWords(id: string, name?: string): boolean;
|
|
96
|
+
/**
|
|
97
|
+
* Beta.24 review: whether words name a repo, component, system or team Atticus knows, as an
|
|
98
|
+
* answer about where calls go may: a repo of the manifests (its id, component or a module's
|
|
99
|
+
* component), a system of the profiles (its id, name, an alias or a topic), a team of roles.yaml,
|
|
100
|
+
* or a component a repo's facts name. Case and spacing aside, or by the id the words slug to.
|
|
101
|
+
*/
|
|
102
|
+
export declare function namesKnownTarget(root: string, words: string): Promise<boolean>;
|
|
103
|
+
/**
|
|
104
|
+
* Beta.24 review: the refusal of words that name no repo, component or system as the answer of a
|
|
105
|
+
* question about where calls go, in a person's words: what to do instead.
|
|
106
|
+
*/
|
|
107
|
+
export declare const wordsNameNothing: (words: string) => string;
|
|
39
108
|
/**
|
|
40
109
|
* The options of a hosts question that say an outside system answers on the host (O1): another
|
|
41
110
|
* team's system (boundary internal, the first, the default) or a vendor's. The answer writes the
|
|
@@ -57,6 +126,24 @@ export declare const hostQuestionText: (host: string) => string;
|
|
|
57
126
|
export declare function hostOfQuestion(q: {
|
|
58
127
|
question: string;
|
|
59
128
|
}): string | undefined;
|
|
129
|
+
/**
|
|
130
|
+
* Beta.24 review: the host a targets question the join raised for a host nothing resolves asks
|
|
131
|
+
* about (a gateway's forwarding call whose target URL is a token, `@targetUrl@`): its words start
|
|
132
|
+
* as a hosts question's do, and may go on to say what to do next (`forwardHostQuestion`). A
|
|
133
|
+
* targets question asked of a call (`Which repo or system answers ...`) has none.
|
|
134
|
+
*/
|
|
135
|
+
export declare function joinHostOfQuestion(q: {
|
|
136
|
+
question: string;
|
|
137
|
+
}): string | undefined;
|
|
138
|
+
/**
|
|
139
|
+
* The outside system an answer to a join host question adds (beta.24 review): named by the host,
|
|
140
|
+
* or for a host still written as a token, by the token's name (`@targetVendorUrl@` →
|
|
141
|
+
* `targetVendorUrl`), never with the token's marks in its id.
|
|
142
|
+
*/
|
|
143
|
+
export declare function outsideSystemOfJoinHost(host: string): {
|
|
144
|
+
id: string;
|
|
145
|
+
name: string;
|
|
146
|
+
};
|
|
60
147
|
/**
|
|
61
148
|
* Put an outside system for a host into the profile whose repos.manifest.yaml lists the repo
|
|
62
149
|
* that asked (O1): its id and name from the host, the host as its alias, the boundary given
|
|
@@ -98,6 +185,24 @@ export declare function addProfileSystem(root: string, repo: string, s: {
|
|
|
98
185
|
/** The lines a new system changes in the profile (as the write makes them). */
|
|
99
186
|
changes?: LineChange[];
|
|
100
187
|
}>;
|
|
188
|
+
/**
|
|
189
|
+
* Beta.24 review: take a system out of the profile that has it, or (with `rename`) give it another
|
|
190
|
+
* id and name, keeping its other fields, the file's comments and its order. For a system an
|
|
191
|
+
* answer's words made (`madeFromWords`), from Map › Trust: written as a file change in the
|
|
192
|
+
* metarepo, for review in the pull request. `preview` writes nothing. Undefined when no profile
|
|
193
|
+
* has the system. Throws when the profile would not be valid (the new id another system has).
|
|
194
|
+
*/
|
|
195
|
+
export declare function editProfileSystem(root: string, id: string, o?: {
|
|
196
|
+
rename?: {
|
|
197
|
+
id: string;
|
|
198
|
+
name: string;
|
|
199
|
+
};
|
|
200
|
+
preview?: boolean;
|
|
201
|
+
}): Promise<{
|
|
202
|
+
profile: string;
|
|
203
|
+
changes: LineChange[];
|
|
204
|
+
written: boolean;
|
|
205
|
+
} | undefined>;
|
|
101
206
|
/**
|
|
102
207
|
* Put a host under a repo's `hosts` in the repos.manifest.yaml that lists it, keeping the
|
|
103
208
|
* file's comments and order. `added` is false when the repo already lists it. Throws when no
|
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";
|
|
@@ -58,7 +59,10 @@ export * from "./fs.js";
|
|
|
58
59
|
export * from "./glob.js";
|
|
59
60
|
export * from "./repo-files.js";
|
|
60
61
|
export * from "./record-cache.js";
|
|
62
|
+
export * from "./kept-files.js";
|
|
61
63
|
export * from "./log.js";
|
|
64
|
+
export * from "./run-log.js";
|
|
65
|
+
export * from "./printer.js";
|
|
62
66
|
export * from "./zip.js";
|
|
63
67
|
export * from "./words.js";
|
|
64
68
|
export * from "./zip-read.js";
|
|
@@ -75,6 +79,7 @@ export * from "./question-roles.js";
|
|
|
75
79
|
export * from "./question-proposals.js";
|
|
76
80
|
export * from "./repo-description.js";
|
|
77
81
|
export * from "./manifest-edit.js";
|
|
82
|
+
export * from "./setup-edit.js";
|
|
78
83
|
export * from "./schema/spec.js";
|
|
79
84
|
export * from "./specs.js";
|
|
80
85
|
export * from "./cancel.js";
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/** While `isQuiet()` says so, files checked since the last change aren't checked again; none to stop. */
|
|
2
|
+
export declare function trustKeptFiles(isQuiet?: () => boolean): void;
|
|
3
|
+
/**
|
|
4
|
+
* A file may have changed: each kept file is checked again when next asked; with `path` (a
|
|
5
|
+
* file or a folder), only those at or under it.
|
|
6
|
+
*/
|
|
7
|
+
export declare function keptFilesMayHaveChanged(path?: string): void;
|
|
8
|
+
/**
|
|
9
|
+
* What `parse` makes of the file's text, from the last read while the file is unchanged.
|
|
10
|
+
* Undefined when there is no such file. A parse that throws is not kept: the error goes to the
|
|
11
|
+
* caller, as a fresh read's would.
|
|
12
|
+
*/
|
|
13
|
+
export declare function keptParse<T>(path: string, kind: string, parse: (text: string) => T, o?: {
|
|
14
|
+
copy?: boolean;
|
|
15
|
+
}): Promise<T | undefined>;
|
|
16
|
+
/** For tests: forget every file kept. */
|
|
17
|
+
export declare function forgetKeptFiles(): void;
|
package/npm/core/light.d.ts
CHANGED
|
@@ -6,3 +6,5 @@
|
|
|
6
6
|
*/
|
|
7
7
|
export { SCHEMA_VERSION } from "./schema/version.js";
|
|
8
8
|
export { createLog, logFileOf, NO_LOG, type Log, type LogEntry, type LogLevel } from "./log.js";
|
|
9
|
+
export { recordedCommand, startTerminalRun, type TerminalRunRecorder } from "./run-log.js";
|
|
10
|
+
export { printToCurrent, withPrinter } from "./printer.js";
|
package/npm/core/log.d.ts
CHANGED
|
@@ -45,5 +45,7 @@ export declare function createLog(root: string, o?: {
|
|
|
45
45
|
maxBytes?: number;
|
|
46
46
|
keep?: number;
|
|
47
47
|
}): Log;
|
|
48
|
+
/** ensureLocalIgnore, for the log's synchronous writes (and a terminal run's, ADR 0187). */
|
|
49
|
+
export declare function ignoreLocalSync(root: string): void;
|
|
48
50
|
/** A log that writes nothing (tests, and commands run with no metarepo). */
|
|
49
51
|
export declare const NO_LOG: Log;
|
|
@@ -28,7 +28,9 @@ export declare function setManifestDescription(root: string, repo: string, descr
|
|
|
28
28
|
* are in. The entry is written with the fields that are set and no more, and the whole manifest
|
|
29
29
|
* is checked before it is written, so a duplicate id or a password in the URL is refused here.
|
|
30
30
|
*/
|
|
31
|
-
export declare function addManifestRepo(root: string, platform: string, entry:
|
|
31
|
+
export declare function addManifestRepo(root: string, platform: string, entry: NewManifestRepo): Promise<ManifestFile>;
|
|
32
|
+
/** One repo to add to a manifest: the fields that are set, and no more. */
|
|
33
|
+
export interface NewManifestRepo {
|
|
32
34
|
id: string;
|
|
33
35
|
url: string;
|
|
34
36
|
type: string;
|
|
@@ -38,7 +40,21 @@ export declare function addManifestRepo(root: string, platform: string, entry: {
|
|
|
38
40
|
system?: string;
|
|
39
41
|
component?: string;
|
|
40
42
|
description?: RepoDescription;
|
|
41
|
-
}
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* ADR 0190: many repos into a platform's manifest at once (the app's paste of ~40 clone URLs),
|
|
46
|
+
* as addManifestRepo adds one: appended in order, comments and order kept, the file's own line
|
|
47
|
+
* endings, the whole manifest checked before anything is written. An id another manifest (or
|
|
48
|
+
* an earlier entry of the batch) lists is refused, naming it. With `preview`, nothing is
|
|
49
|
+
* written: the lines it would change come back, for the app's diff before the write.
|
|
50
|
+
*/
|
|
51
|
+
export declare function addManifestRepos(root: string, platform: string, entries: readonly NewManifestRepo[], o?: {
|
|
52
|
+
preview?: boolean;
|
|
53
|
+
}): Promise<{
|
|
54
|
+
file: ManifestFile;
|
|
55
|
+
changes: LineChange[];
|
|
56
|
+
written: boolean;
|
|
57
|
+
}>;
|
|
42
58
|
/**
|
|
43
59
|
* F5: move a repo's id in the manifest that lists it, in place (comments and order kept). Refused
|
|
44
60
|
* when no manifest lists the repo, or any lists the new id already (ids are unique across every
|
|
@@ -74,7 +90,9 @@ export declare function changedLines(before: string, after: string): LineChange[
|
|
|
74
90
|
* file's comments and order; checked before it is written. With `preview`, nothing is written:
|
|
75
91
|
* the lines it would change come back.
|
|
76
92
|
*/
|
|
77
|
-
export declare function setManifestField(root: string, repo: string,
|
|
93
|
+
export declare function setManifestField(root: string, repo: string,
|
|
94
|
+
/** ADR 0190: `type` too, from the app's Detect the type (atticus repo-type detect). */
|
|
95
|
+
field: "owner" | "system" | "type", value: string, o?: {
|
|
78
96
|
preview?: boolean;
|
|
79
97
|
}): Promise<{
|
|
80
98
|
file: ManifestFile;
|
package/npm/core/metarepo.d.ts
CHANGED
|
@@ -88,6 +88,14 @@ export declare function layoutOf(root: string): {
|
|
|
88
88
|
};
|
|
89
89
|
/** The catalog folder (holding generated/ and curated/). */
|
|
90
90
|
export declare function catalogDirOf(root: string): string;
|
|
91
|
+
/**
|
|
92
|
+
* Whether a changed file (root-relative, "/"-separated, as the server's live events name it) can
|
|
93
|
+
* change the catalog: a file in the catalog folder the layout names, that folder or one above it
|
|
94
|
+
* (the watcher names top folders when many files change), or the org pack, whose sources.yaml
|
|
95
|
+
* says where the catalog is. The server reads the catalog again only then, and tags each
|
|
96
|
+
* `file.changed` event with it (`catalog`), so a page follows the layout too.
|
|
97
|
+
*/
|
|
98
|
+
export declare function catalogMayHaveChangedAt(root: string, path: string): boolean;
|
|
91
99
|
/**
|
|
92
100
|
* Where OpenSpec keeps changes, relative to the root with forward slashes: `changes/` under
|
|
93
101
|
* `layout.openspec` (`openspec/changes` by default, `.atticus/openspec/changes` in a repo
|
|
@@ -30,11 +30,12 @@ export declare const DEFAULT_GATES: {
|
|
|
30
30
|
}[];
|
|
31
31
|
};
|
|
32
32
|
export declare const DEFAULT_ROLES: {
|
|
33
|
-
schemaVersion: 1 | 2;
|
|
33
|
+
schemaVersion: 1 | 2 | 3;
|
|
34
34
|
teams: {
|
|
35
35
|
id: string;
|
|
36
36
|
people: string[];
|
|
37
37
|
name?: string | undefined;
|
|
38
|
+
roles?: Record<string, string[]> | undefined;
|
|
38
39
|
}[];
|
|
39
40
|
custom: {
|
|
40
41
|
id: string;
|
|
@@ -55,6 +56,7 @@ export declare const DEFAULT_ROLES: {
|
|
|
55
56
|
actions: [string, string];
|
|
56
57
|
reason: string;
|
|
57
58
|
}[];
|
|
59
|
+
defaults?: Record<string, string[]> | undefined;
|
|
58
60
|
};
|
|
59
61
|
export declare const DEFAULT_RUNTIME: {
|
|
60
62
|
schemaVersion: 1 | 2 | 3 | 4;
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
/** Run `work` with every line printed inside it (at any depth, across awaits) going to `print`. */
|
|
2
|
+
export declare function withPrinter<T>(print: (line: string) => void, work: () => T): T;
|
|
3
|
+
/** Print a line to the job this code runs in, if any. */
|
|
4
|
+
export declare function printToCurrent(line: string): void;
|
|
@@ -17,8 +17,12 @@ export type QuestionOwner = {
|
|
|
17
17
|
/** The teams roles.yaml names, and why they couldn't be read when they couldn't. */
|
|
18
18
|
export declare function readTeams(root: string): Promise<{
|
|
19
19
|
teams: Team[];
|
|
20
|
+
/** Version 3 (ADR 0191): the organisation's person for each role, when no team names one. */
|
|
21
|
+
defaults?: Record<string, string[]>;
|
|
20
22
|
problem?: string;
|
|
21
23
|
}>;
|
|
24
|
+
/** A handle as compared: no leading @, lower case (Git hosts' handles are case-insensitive). */
|
|
25
|
+
export declare const handleKey: (h: string) => string;
|
|
22
26
|
/** The teams a person is on, by their Git handle. */
|
|
23
27
|
export declare function teamsOfPerson(handle: string, teams: readonly Team[]): Team[];
|
|
24
28
|
/**
|
|
@@ -1,15 +1,74 @@
|
|
|
1
1
|
import { BUILT_IN_ROLES } from "./schema/orgpack.js";
|
|
2
|
-
import { type Question, type QuestionRole } from "./schema/question.js";
|
|
2
|
+
import { type Question, type QuestionAsks, type QuestionRole } from "./schema/question.js";
|
|
3
3
|
/**
|
|
4
4
|
* The role that owns what a step asks: the stage's own for a change's stage (`change-feature`,
|
|
5
5
|
* `change-stories`, a task's run), else, for a step that serves every stage (a context gap, a
|
|
6
6
|
* knowledge conflict), the stage its rerun command names. Undefined outside a change's phases.
|
|
7
7
|
*/
|
|
8
8
|
export declare function roleOfStep(step: string, rerun?: string): QuestionRole | undefined;
|
|
9
|
-
/**
|
|
10
|
-
|
|
9
|
+
/**
|
|
10
|
+
* ADR 0191: the role that owns what a question asks. Design is the architect's and delivery the
|
|
11
|
+
* tech lead's, whichever stage asked. Business is the product owner's, or the business analyst's
|
|
12
|
+
* once the stories are being written (a question the stories or tasks stage raises about what the
|
|
13
|
+
* change must do is the analyst's to answer at that level).
|
|
14
|
+
*/
|
|
15
|
+
export declare function roleOfAsks(asks: QuestionAsks, stageRole?: QuestionRole): QuestionRole;
|
|
16
|
+
/** ADR 0191: what a role's questions ask, for a question that has no `asks` of its own. */
|
|
17
|
+
export declare function asksOfRole(role: QuestionRole): QuestionAsks;
|
|
18
|
+
type RoutedQuestion = Pick<Question, "askedBy" | "rerun"> & {
|
|
11
19
|
role?: QuestionRole | undefined;
|
|
12
|
-
|
|
20
|
+
asks?: QuestionAsks | undefined;
|
|
21
|
+
};
|
|
22
|
+
/**
|
|
23
|
+
* A question's role: a person's re-routing or the one it was raised with (versions 5 and 6), else
|
|
24
|
+
* what it asks (version 6), else derived from the step that asked and its rerun.
|
|
25
|
+
*/
|
|
26
|
+
export declare function roleOfQuestion(q: RoutedQuestion): QuestionRole | undefined;
|
|
27
|
+
/** What a question asks: its own tag (version 6), else its role's level; undefined with neither. */
|
|
28
|
+
export declare function asksOfQuestion(q: RoutedQuestion): QuestionAsks | undefined;
|
|
29
|
+
/**
|
|
30
|
+
* ADR 0191: what a critic finding asks of people, by the same three levels, so a product owner's
|
|
31
|
+
* Home shows only the business ones (the audit: running the critic from the brief made findings
|
|
32
|
+
* about circuit breakers and alerts, and Home showed the product owner a change blocked by them).
|
|
33
|
+
* A finding on the design's files is design; on tasks.md, the build or the release, delivery; one
|
|
34
|
+
* on the brief, the proposal, the UX or the stories is business unless its rule, lens or words are
|
|
35
|
+
* about how the estate does it (resilience, timeouts, alerts, interfaces). On the brief, only the
|
|
36
|
+
* architecture lens or words no business sentence uses (a timeout, a retry, a circuit breaker)
|
|
37
|
+
* make it design: an alert, a queue or an interface there may be the business's own.
|
|
38
|
+
*/
|
|
39
|
+
export declare function asksOfFinding(f: {
|
|
40
|
+
artifact: string;
|
|
41
|
+
rule?: string | undefined;
|
|
42
|
+
lens?: string | undefined;
|
|
43
|
+
summary?: string | undefined;
|
|
44
|
+
}): QuestionAsks;
|
|
45
|
+
/**
|
|
46
|
+
* ADR 0191: the levels a change's phase is decided at. In Define only the business level holds
|
|
47
|
+
* the change (a design finding waits for the architect); in Design, business and design; from
|
|
48
|
+
* Plan on, all three.
|
|
49
|
+
*/
|
|
50
|
+
export declare function asksOfPhase(state: string): QuestionAsks[];
|
|
51
|
+
/** The change.yaml owner key of each phase's role, in the order a change goes. */
|
|
52
|
+
export declare const OWNER_OF_ROLE: Readonly<Record<QuestionRole, string>>;
|
|
53
|
+
/**
|
|
54
|
+
* ADR 0191: whose turn a phase's hand-off is: the next role's owner key (define → the architect,
|
|
55
|
+
* design → the business analyst, plan → the tech lead), so the hand-off names its
|
|
56
|
+
* reviewers and At a glance says who it waits on.
|
|
57
|
+
*/
|
|
58
|
+
export declare function nextOwnerOf(phase: string): string | undefined;
|
|
59
|
+
/** The people a phase's hand-off waits on: the next role's owners on the change (handles, no @). */
|
|
60
|
+
export declare function nextOwnersOf(phase: string, owners: Readonly<Record<string, readonly string[]>>, custom?: readonly CustomRole[]): {
|
|
61
|
+
role: string;
|
|
62
|
+
people: string[];
|
|
63
|
+
} | undefined;
|
|
64
|
+
/**
|
|
65
|
+
* ADR 0191 review: the people a built-in owner key names on a change, its keys read as
|
|
66
|
+
* rolesOfPerson reads them: any case, the words people write for it (`tech-lead`, `developer`
|
|
67
|
+
* and `delivery-lead` for the team lead), or a custom role of roles.yaml based on it, the key
|
|
68
|
+
* itself first. Another built-in role (a security reviewer beside the architect) is its own.
|
|
69
|
+
* Handles, no @, once each as handles compare; a team (`forge/platform`) is not a person.
|
|
70
|
+
*/
|
|
71
|
+
export declare function ownersOfRole(key: string, owners: Readonly<Record<string, readonly string[]>>, custom?: readonly CustomRole[]): string[];
|
|
13
72
|
/** A custom role of roles.yaml (`custom`): its id and the built-in role it is based on. */
|
|
14
73
|
export interface CustomRole {
|
|
15
74
|
id: string;
|
|
@@ -22,3 +81,4 @@ export declare function roleOfOwner(key: string, custom?: readonly CustomRole[])
|
|
|
22
81
|
* question role, once each, in the order of the phases.
|
|
23
82
|
*/
|
|
24
83
|
export declare function rolesOfPerson(handle: string, owners: Readonly<Record<string, readonly string[]>>, custom?: readonly CustomRole[]): QuestionRole[];
|
|
84
|
+
export {};
|