@maycombhq/sdk 2.0.0-beta.21 → 2.0.0-beta.23
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 +14 -1
- package/npm/core/api.d.ts +2993 -550
- package/npm/core/cite.d.ts +20 -4
- package/npm/core/facts-carry.d.ts +8 -2
- package/npm/core/facts-join.d.ts +78 -1
- package/npm/core/fs.d.ts +25 -0
- package/npm/core/glob.d.ts +14 -0
- package/npm/core/identity.d.ts +28 -0
- package/npm/core/index.d.ts +6 -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 +19 -3
- package/npm/core/repo-files.d.ts +60 -0
- package/npm/core/roles-migrate.d.ts +4 -3
- package/npm/core/run-log.d.ts +165 -0
- package/npm/core/schema/fact-corrections.d.ts +17 -3
- package/npm/core/schema/orgpack.d.ts +71 -18
- package/npm/core/schema/question.d.ts +55 -2
- package/npm/core/schema/scan-verify.d.ts +35 -0
- package/npm/core/setup-edit.d.ts +107 -0
- package/npm/fs-repo.d.ts +2 -1
- package/npm/index.js +1491 -110
- package/npm/listing.d.ts +14 -0
- package/package.json +1 -1
package/npm/core/cite.d.ts
CHANGED
|
@@ -33,16 +33,32 @@ 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
|
-
* Redact a line
|
|
42
|
-
*
|
|
43
|
-
*
|
|
46
|
+
* Redact the secrets on a line, keeping what names them: a value after a secret-looking key
|
|
47
|
+
* (at the line's start, whatever the value; anywhere on it, a quoted literal), a setter's
|
|
48
|
+
* literal, a URL's password, a bearer or basic token and well-known token shapes. A
|
|
49
|
+
* placeholder or a reference (`${X}`, `env:X`, `vault:...`) stays, as does code that only names
|
|
50
|
+
* a secret word (`if (password == null)`, `tokenizer.next()`). A private-key block is redacted
|
|
51
|
+
* whole. A key's value is redacted to the end of the line.
|
|
44
52
|
*/
|
|
45
53
|
export declare function redactSecrets(line: string): string;
|
|
54
|
+
/**
|
|
55
|
+
* Whether a quote redaction left as it is still holds what looks like a secret: an identifier
|
|
56
|
+
* with a secret word and an opaque quoted literal (8 or more characters with letters and digits,
|
|
57
|
+
* no spaces, not a path, URL or placeholder) on the same line, e.g.
|
|
58
|
+
* `creds.put(PASSWORD_KEY, "Xk9fQ2mZ7p")`. Code that only names a secret word
|
|
59
|
+
* (`passwordEncoder.encode(x)`, `getToken("Authorization")`) doesn't.
|
|
60
|
+
*/
|
|
61
|
+
export declare function quoteHoldsSecret(quote: string): boolean;
|
|
46
62
|
/**
|
|
47
63
|
* Whether a word claim is put together from `cite.with` parts (ADR 0124 addendum A-derived): a
|
|
48
64
|
* rake task's `namespace:task`, a key a helper prefixes (`${prefix}_conferenceCache`). Each part's
|
|
@@ -6,13 +6,19 @@ import type { Fact } from "./schema/facts.js";
|
|
|
6
6
|
* that was edited, renamed or deleted is read again. Pure: the diff comes from the git adapter
|
|
7
7
|
* (`changedFiles` in @maycombhq/workspace), so the same facts and the same diff split the same way.
|
|
8
8
|
*/
|
|
9
|
-
/** One file changed between two commits, as `git diff --
|
|
9
|
+
/** One file changed between two commits, as `git diff --raw -M` says it. */
|
|
10
10
|
export interface FileChange {
|
|
11
11
|
status: "added" | "modified" | "deleted" | "renamed" | "copied" | "type-changed";
|
|
12
12
|
/** The path at the newer commit (a deleted file's path at the older one). */
|
|
13
13
|
path: string;
|
|
14
14
|
/** A rename's or copy's path at the older commit. */
|
|
15
15
|
from?: string;
|
|
16
|
+
/**
|
|
17
|
+
* Review round 49: the path is a submodule's gitlink (mode 160000 at either commit), so the
|
|
18
|
+
* diff names the folder, not the files in it that changed. Every cited file under it is read
|
|
19
|
+
* again.
|
|
20
|
+
*/
|
|
21
|
+
gitlink?: boolean;
|
|
16
22
|
}
|
|
17
23
|
/** Why a fact must be read again: the first file it cites that changed, and how. */
|
|
18
24
|
export interface StaleCite {
|
|
@@ -24,7 +30,7 @@ export interface StaleCite {
|
|
|
24
30
|
}
|
|
25
31
|
/**
|
|
26
32
|
* The files a fact rests on: its cite and the cite's `with` parts, an entry's `authCite` (ADR
|
|
27
|
-
* 0124 addendum A-read), and for a flow every step's and error path's cite and parts. Unique and
|
|
33
|
+
* 0124 addendum A-read) and a call's `authCite` and `tlsCite` (ADR 0163), with their parts, and for a flow every step's and error path's cite and parts. Unique and
|
|
28
34
|
* sorted, except that a fact's own cited file comes first for a non-flow fact.
|
|
29
35
|
*/
|
|
30
36
|
export declare function citedFiles(f: Fact): 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 {
|
|
@@ -197,6 +226,16 @@ export declare const JOINED_DESPITE_CONFLICT = "joined-despite-conflict";
|
|
|
197
226
|
export declare const JOINED_BY_SERVICE_NAME = "joined-by-service-name";
|
|
198
227
|
/** G1 (ADR 0174): a person paired the call with this entry on the canvas. */
|
|
199
228
|
export declare const JOINED_BY_PERSON = "joined-by-person";
|
|
229
|
+
/**
|
|
230
|
+
* An Apigee proxy's forwarding call matched the service's entry only by taking off the front of
|
|
231
|
+
* the target's path that nothing names as the service's base path (no manifest `basePath`, no
|
|
232
|
+
* Route or Ingress path, no context path setting): `/forge-limits/v3/limits` and the suffix
|
|
233
|
+
* `/check` against `/limits/check`. A guess, so the link is inferred; the Interface's flag only,
|
|
234
|
+
* not one of `JOIN_GUESS_FLAGS` (the local API's guesses), and its how is the host's.
|
|
235
|
+
*/
|
|
236
|
+
export declare const JOINED_BY_PATH_OVERLAP = "joined-by-path-overlap";
|
|
237
|
+
/** How many entries a `<BasePath>/**` pass-through links to at most, in path order. */
|
|
238
|
+
export declare const MAX_PASS_THROUGH_LINKS = 50;
|
|
200
239
|
/**
|
|
201
240
|
* ADR 0181: the AI decided the link (a pairing, or a target answer), applied by Atticus from its
|
|
202
241
|
* run without a person. A how, never a person's word: the Interface is inferred, its evidence is
|
|
@@ -304,6 +343,20 @@ export interface FactJoin {
|
|
|
304
343
|
aiHop?: JoinAi & {
|
|
305
344
|
call: FactEnd;
|
|
306
345
|
};
|
|
346
|
+
/**
|
|
347
|
+
* An Apigee proxy's forwarding call (the path suffix): the proxy's route whose requests it
|
|
348
|
+
* carries, when the path the target receives is the target's path and this route's suffix (or,
|
|
349
|
+
* for a `<BasePath>/**` pass-through, everything under the target's path). A call that serves
|
|
350
|
+
* several routes has a join per route.
|
|
351
|
+
*/
|
|
352
|
+
forRoute?: FactEnd;
|
|
353
|
+
/** The service's base path the join took off before matching its entry (the path suffix). */
|
|
354
|
+
base?: JoinBase;
|
|
355
|
+
/**
|
|
356
|
+
* The setting that keeps the proxy's path suffix off (`target.copy.pathsuffix` false, in a
|
|
357
|
+
* JavaScript or AssignMessage policy), so the target receives its own path as it is.
|
|
358
|
+
*/
|
|
359
|
+
suffixOff?: FactEnd;
|
|
307
360
|
}
|
|
308
361
|
/** ADR 0181: the AI run a decision came from. */
|
|
309
362
|
export interface JoinAi {
|
|
@@ -435,6 +488,11 @@ export interface PersonPair {
|
|
|
435
488
|
by: string;
|
|
436
489
|
/** ADR 0181: the pairing is the AI's, with its run; joined `joined-by-ai`. */
|
|
437
490
|
ai?: JoinAi;
|
|
491
|
+
/**
|
|
492
|
+
* Review round 48: a person said the call reaches none (their `unlink` is the newest): no
|
|
493
|
+
* pairing, and an AI answer naming a target doesn't join it (a person's answer still does).
|
|
494
|
+
*/
|
|
495
|
+
none?: boolean;
|
|
438
496
|
}
|
|
439
497
|
export interface JoinFactsInput {
|
|
440
498
|
repos: readonly JoinRepo[];
|
|
@@ -542,8 +600,23 @@ export declare function basePathOf(e: Entry): string;
|
|
|
542
600
|
* by a Service's short name (J1). Empty for a join nobody had to guess.
|
|
543
601
|
*/
|
|
544
602
|
export declare function joinGuessesOf(j: Pick<FactJoin, "inferred" | "byLabel" | "guesses">): JoinGuessFlag[];
|
|
603
|
+
/**
|
|
604
|
+
* Whether an Apigee forwarding call on the way matched its entry only by a guessed base path
|
|
605
|
+
* (`joined-by-path-overlap`): the join's own, or a gateway hop's.
|
|
606
|
+
*/
|
|
607
|
+
export declare const isOverlapJoin: (j: {
|
|
608
|
+
base?: JoinBase | undefined;
|
|
609
|
+
gateway?: readonly {
|
|
610
|
+
base?: JoinBase | undefined;
|
|
611
|
+
}[] | undefined;
|
|
612
|
+
}) => boolean;
|
|
545
613
|
/** Whether a join guessed its callee anywhere on the way (`joinGuessesOf` gives how). */
|
|
546
|
-
export declare const isGuessedJoin: (j: Pick<FactJoin, "inferred" | "byLabel" | "guesses">
|
|
614
|
+
export declare const isGuessedJoin: (j: Pick<FactJoin, "inferred" | "byLabel" | "guesses"> & {
|
|
615
|
+
base?: JoinBase | undefined;
|
|
616
|
+
gateway?: readonly {
|
|
617
|
+
base?: JoinBase | undefined;
|
|
618
|
+
}[] | undefined;
|
|
619
|
+
}) => boolean;
|
|
547
620
|
/**
|
|
548
621
|
* How a join found its callee, as its Interface's flags (C1, ADR 0135): a guess by its own F2
|
|
549
622
|
* flags alone (`JOIN_GUESS_FLAGS`: by path or label, F2; by a platform setting or a folder name,
|
|
@@ -557,6 +630,10 @@ export declare const aiOfJoin: (j: Pick<FactJoin, "how" | "paired"> & {
|
|
|
557
630
|
export declare function joinFlagsOf(j: Pick<FactJoin, "how" | "inferred" | "byLabel" | "guesses" | "paired"> & {
|
|
558
631
|
aiAnswer?: JoinAi | undefined;
|
|
559
632
|
aiHop?: JoinAi | undefined;
|
|
633
|
+
base?: JoinBase | undefined;
|
|
634
|
+
gateway?: readonly {
|
|
635
|
+
base?: JoinBase | undefined;
|
|
636
|
+
}[] | undefined;
|
|
560
637
|
}): string[];
|
|
561
638
|
/**
|
|
562
639
|
* 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
|
@@ -51,6 +51,31 @@ o?: {
|
|
|
51
51
|
release: () => Promise<void>;
|
|
52
52
|
interrupted?: LockInfo;
|
|
53
53
|
}>;
|
|
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
|
+
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
|
+
};
|
|
63
|
+
/**
|
|
64
|
+
* Review round 46: run `work` holding a file that another process may append to or rewrite at
|
|
65
|
+
* the same time (a repo's corrections: the app server appends, a CLI command rewrites it), so a
|
|
66
|
+
* read, change and write never loses what the other wrote meanwhile. In this process the writers
|
|
67
|
+
* of one file queue; between processes `<file>.lock` is created with `wx` (which fails when it is
|
|
68
|
+
* there), retried with a short backoff. A lock whose process is gone, or older than `staleMs`, is
|
|
69
|
+
* taken over; after `waitMs` it gives up with LockHeldError naming the holder. No `flock`, so it
|
|
70
|
+
* works the same on Windows, where a lock file being deleted can refuse for a moment (EPERM,
|
|
71
|
+
* EBUSY): those are retried.
|
|
72
|
+
*/
|
|
73
|
+
export declare function withSharedFileLock<T>(path: string, work: () => Promise<T>, o?: {
|
|
74
|
+
staleMs?: number;
|
|
75
|
+
waitMs?: number;
|
|
76
|
+
what?: string;
|
|
77
|
+
maxAgeMs?: number;
|
|
78
|
+
}): Promise<T>;
|
|
54
79
|
/**
|
|
55
80
|
* What stays on this machine inside .atticus/: the person's settings, the log, locks, upgrade
|
|
56
81
|
* backups, the prompt and response history (ADR 0110), what `atticus probe` measured of the
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Path globs for the code tools (grep `paths`, files, and every .gitignore line of a scanned
|
|
3
|
+
* repo), matched in linear time. A glob is compiled to a small automaton and run over the path
|
|
4
|
+
* one character at a time with a set of live states, so no glob, however its `*`s are laid out,
|
|
5
|
+
* can backtrack: these run on the main thread with no time limit (final review, 2.0.0-beta.21).
|
|
6
|
+
*/
|
|
7
|
+
export interface GlobMatcher {
|
|
8
|
+
test(path: string): boolean;
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* A glob as a matcher over a repo-relative path. A glob with no / matches a name at any depth;
|
|
12
|
+
* a leading / anchors it at the top.
|
|
13
|
+
*/
|
|
14
|
+
export declare function globMatcher(glob: string, anyDepth?: boolean): GlobMatcher;
|
package/npm/core/identity.d.ts
CHANGED
|
@@ -8,6 +8,21 @@
|
|
|
8
8
|
* - topics (no leading slash in the input and no "/" at all) are returned trimmed
|
|
9
9
|
*/
|
|
10
10
|
export declare function normalizePath(input: string): string;
|
|
11
|
+
/**
|
|
12
|
+
* A path with each `{...}` parameter cut to its name: what follows the first `:`, `?` or `=` in
|
|
13
|
+
* braces nested inside a constraint (`{code:regex(^\\d{3}$)}`) are matched, not cut at the first `}`.
|
|
14
|
+
* braces nested inside a constraint (`{code:regex(^\\d{{3}}$)}`) are matched, not cut at the first `}`.
|
|
15
|
+
* An unclosed `{` leaves the rest as written.
|
|
16
|
+
*/
|
|
17
|
+
export declare function stripParamConstraints(path: string): string;
|
|
18
|
+
/** Code-unit string order, the same in every locale (`localeCompare` is not: ICU orders `_`/`-`
|
|
19
|
+
* and, in `da`, `aa` differently), for every sort that feeds records, ids, hashes or a merge. */
|
|
20
|
+
export declare function cmpText(a: string, b: string): number;
|
|
21
|
+
/**
|
|
22
|
+
* `cmpText`, but a run of digits is compared as a number (`a.ts:9` before `a.ts:10`): what
|
|
23
|
+
* `localeCompare(b, "en", { numeric: true })` was used for, without ICU.
|
|
24
|
+
*/
|
|
25
|
+
export declare function cmpNatural(a: string, b: string): number;
|
|
11
26
|
/**
|
|
12
27
|
* Stable interface id: a hash of caller, callee, method and normalised path, so the same
|
|
13
28
|
* edge seen by several extractors merges into one Interface record.
|
|
@@ -15,3 +30,16 @@ export declare function normalizePath(input: string): string;
|
|
|
15
30
|
export declare function interfaceId(from: string, to: string, method: string | undefined, path: string): string;
|
|
16
31
|
/** Lowercase slug suitable as a record id, built from free text such as a system name. */
|
|
17
32
|
export declare function slugify(text: string): string;
|
|
33
|
+
/**
|
|
34
|
+
* Round 47: a name with no Latin letter or digit in it (`注文`, `Заказы`, `...`) slugs to
|
|
35
|
+
* nothing, so every such name used to become the same `unnamed` and their records merged.
|
|
36
|
+
* It gets `unnamed-<short hash of the name>` instead: stable, and different per name. Blank
|
|
37
|
+
* text stays `unnamed`.
|
|
38
|
+
*/
|
|
39
|
+
export declare function unnamedId(text: string): string;
|
|
40
|
+
/**
|
|
41
|
+
* A slug that is never a Windows device name (review round 46): a record is the file
|
|
42
|
+
* `<kind>/<id>.yaml` and Windows can't create `aux.yaml`, so the slug's first dot-separated part,
|
|
43
|
+
* when it is one, gets `-1` (`aux` is `aux-1`, `con.v2` is `con-1.v2`). C1's RecordId is unchanged.
|
|
44
|
+
*/
|
|
45
|
+
export declare function notDeviceName(slug: string): string;
|
package/npm/core/index.d.ts
CHANGED
|
@@ -55,8 +55,13 @@ export * from "./roles-migrate.js";
|
|
|
55
55
|
export * from "./profile-migrate.js";
|
|
56
56
|
export * from "./metarepo.js";
|
|
57
57
|
export * from "./fs.js";
|
|
58
|
+
export * from "./glob.js";
|
|
59
|
+
export * from "./repo-files.js";
|
|
58
60
|
export * from "./record-cache.js";
|
|
61
|
+
export * from "./kept-files.js";
|
|
59
62
|
export * from "./log.js";
|
|
63
|
+
export * from "./run-log.js";
|
|
64
|
+
export * from "./printer.js";
|
|
60
65
|
export * from "./zip.js";
|
|
61
66
|
export * from "./words.js";
|
|
62
67
|
export * from "./zip-read.js";
|
|
@@ -73,6 +78,7 @@ export * from "./question-roles.js";
|
|
|
73
78
|
export * from "./question-proposals.js";
|
|
74
79
|
export * from "./repo-description.js";
|
|
75
80
|
export * from "./manifest-edit.js";
|
|
81
|
+
export * from "./setup-edit.js";
|
|
76
82
|
export * from "./schema/spec.js";
|
|
77
83
|
export * from "./specs.js";
|
|
78
84
|
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 {};
|
package/npm/core/questions.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { type JudgmentStore } from "./judgments.js";
|
|
2
|
-
import { Question, type AiBy, type AppliedRule, type QuestionDraft, type QuestionScopeLevel, type QuestionState } from "./schema/question.js";
|
|
2
|
+
import { Question, type AiBy, type AppliedRule, type QuestionDraft, type QuestionRole, type QuestionScopeLevel, type QuestionState } from "./schema/question.js";
|
|
3
3
|
/**
|
|
4
4
|
* Questions as files (ADR 0078): raise, list, read and answer questions/<id>.yaml. The CLI
|
|
5
5
|
* (atticus questions) and the local API (/api/questions) both call these, so the app and the
|
|
@@ -47,6 +47,17 @@ export interface AskedBy {
|
|
|
47
47
|
}
|
|
48
48
|
/** An open question from what an AI step raised. */
|
|
49
49
|
export declare function questionFromDraft(d: QuestionDraft, by: AskedBy): Question;
|
|
50
|
+
/**
|
|
51
|
+
* ADR 0191: a person re-routes a question to another role (a business question the architect was
|
|
52
|
+
* given goes to the product owner). `role` becomes the new one and `routed` says from which, by
|
|
53
|
+
* whom and when; what it asks follows the role unless the AI tagged it. Open or answered alike:
|
|
54
|
+
* the answer, if any, stays. Written only if the file is as it was read.
|
|
55
|
+
*/
|
|
56
|
+
export declare function routeQuestion(root: string, id: string, o: {
|
|
57
|
+
role: QuestionRole;
|
|
58
|
+
by: string;
|
|
59
|
+
at: string;
|
|
60
|
+
}): Promise<Question>;
|
|
50
61
|
/**
|
|
51
62
|
* Write a question as it is (a person's comment on a critic finding, ADR 0124 addendum D-app,
|
|
52
63
|
* is a question they answered as they asked it). Every other writer goes through
|
|
@@ -227,12 +238,17 @@ export declare function raiseQuestions(root: string, drafts: QuestionDraft[], by
|
|
|
227
238
|
}>;
|
|
228
239
|
/**
|
|
229
240
|
* Rewrite questions/<id>.yaml files written at an older question schema version (1, ADR 0078;
|
|
230
|
-
* 2, ADR 0117) at the current one (
|
|
231
|
-
* version adds is optional. Returns the files, relative to the root; with dryRun, the files it
|
|
241
|
+
* 2, ADR 0117; 3, ADR 0153; 4, ADR 0162; 5, ADR 0181) at the current one (6, ADR 0191): only the
|
|
242
|
+
* version changes, since what each version adds is optional. Returns the files, relative to the root; with dryRun, the files it
|
|
232
243
|
* would rewrite.
|
|
233
244
|
*/
|
|
234
245
|
export declare function migrateQuestions(root: string, o?: {
|
|
235
246
|
dryRun?: boolean;
|
|
247
|
+
/** Round 49: the files left as they are, with why (a file not named by its question's id). */
|
|
248
|
+
problems?: {
|
|
249
|
+
file: string;
|
|
250
|
+
message: string;
|
|
251
|
+
}[];
|
|
236
252
|
}): Promise<string[]>;
|
|
237
253
|
/** What a step says of a question it reused: who asked it first, and that it waits on it. */
|
|
238
254
|
export declare const reusedLine: (q: Question) => string;
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import { type GlobMatcher } from "./glob.js";
|
|
2
|
+
/**
|
|
3
|
+
* A file's bytes as text, the same way for every reader: UTF-16 (LE or BE) when it starts with
|
|
4
|
+
* that byte-order mark (SQL Server Management Studio saves .sql files so), else UTF-8 with any
|
|
5
|
+
* byte-order mark dropped, else, when the bytes aren't valid UTF-8, windows-1252 (a Latin-1 file
|
|
6
|
+
* from an older editor). Line numbers and quotes then agree between the read, the scan and the
|
|
7
|
+
* check.
|
|
8
|
+
*/
|
|
9
|
+
export declare function decodeText(bytes: Uint8Array): string;
|
|
10
|
+
/** Whether a file's bytes are binary: a NUL in the first 8,000, unless it is marked UTF-16. */
|
|
11
|
+
export declare function isBinaryBytes(bytes: Uint8Array): boolean;
|
|
12
|
+
/** The same, for text `decodeText` made: a NUL is left only where the bytes were binary. */
|
|
13
|
+
export declare function isBinaryText(text: string): boolean;
|
|
14
|
+
/** A Git LFS pointer a checkout wasn't smudged with: three lines that stand for the real file. */
|
|
15
|
+
export declare function isLfsPointer(text: string): boolean;
|
|
16
|
+
/**
|
|
17
|
+
* Tokens a text costs, as every budget counts them (ADR 0112): four ASCII characters a token,
|
|
18
|
+
* and each character outside ASCII a token of its own. Characters / 4 alone counted Japanese,
|
|
19
|
+
* Chinese or Cyrillic at a quarter of what a tokenizer gives, so prompts over the model's limit
|
|
20
|
+
* were planned as fitting. `tokenUnits` is the same count in quarters, to sum over parts.
|
|
21
|
+
*/
|
|
22
|
+
export declare function estimateTokens(text: string): number;
|
|
23
|
+
/** Quarter tokens: 1 for each ASCII character, 4 for each other (an astral one counted once). */
|
|
24
|
+
export declare function tokenUnits(text: string): number;
|
|
25
|
+
export interface IgnoreRule {
|
|
26
|
+
/** The folder of the .gitignore, repo-relative ("" for the root). */
|
|
27
|
+
base: string;
|
|
28
|
+
/** Matched in linear time (glob.ts): a scanned repo's .gitignore can't stall the scan. */
|
|
29
|
+
re: GlobMatcher;
|
|
30
|
+
negate: boolean;
|
|
31
|
+
dirOnly: boolean;
|
|
32
|
+
}
|
|
33
|
+
/** The rules of one .gitignore file (git's syntax: #, !, a trailing /, a leading or inner /). */
|
|
34
|
+
export declare function ignoreRules(text: string, base: string): IgnoreRule[];
|
|
35
|
+
/** Whether git would ignore a path by these rules: the last rule that matches decides. */
|
|
36
|
+
export declare function ignoredBy(rules: readonly IgnoreRule[], path: string, isDir: boolean): boolean;
|
|
37
|
+
export interface WalkOptions {
|
|
38
|
+
/**
|
|
39
|
+
* Whether a folder is left out: `above` are the folders it is in (repo-relative parts), `name`
|
|
40
|
+
* its own, `siblings` every name beside it. Asked after .git, links and .gitignore.
|
|
41
|
+
*/
|
|
42
|
+
skipFolder?: (above: readonly string[], name: string, siblings: readonly string[]) => boolean;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* A checkout's files, repo-relative with `/`, in the order a walk by name meets them: never a
|
|
46
|
+
* symbolic link (so no loop, no file outside the repo and no secret under another name), never
|
|
47
|
+
* `.git`, and nothing a .gitignore in the repo ignores (an ignored folder isn't walked). Only the
|
|
48
|
+
* repo's own .gitignore files are read. Deterministic: the same tree gives the same list.
|
|
49
|
+
*/
|
|
50
|
+
export declare function listRepoFilesSync(root: string, o?: WalkOptions): string[];
|
|
51
|
+
/**
|
|
52
|
+
* The same walk, a file at a time: `visit` returns false to stop. Stops after `max` files and
|
|
53
|
+
* says it was cut.
|
|
54
|
+
*/
|
|
55
|
+
export declare function walkRepo(root: string, visit: (path: string) => Promise<boolean | void>, o?: WalkOptions & {
|
|
56
|
+
max?: number;
|
|
57
|
+
}): Promise<{
|
|
58
|
+
files: number;
|
|
59
|
+
cut: boolean;
|
|
60
|
+
}>;
|