@maycombhq/sdk 2.0.0-beta.28.1 → 2.0.0-beta.28.3
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 +78 -1
- package/npm/core/cancel.d.ts +6 -0
- package/npm/core/file-pool.d.ts +73 -0
- package/npm/core/fs.d.ts +17 -1
- package/npm/core/index.d.ts +2 -0
- package/npm/core/initialisms.d.ts +62 -0
- package/npm/core/process-trees.d.ts +24 -1
- package/npm/core/record-cache.d.ts +95 -2
- package/npm/index.js +42 -10
- package/package.json +1 -1
package/npm/core/api.d.ts
CHANGED
|
@@ -600,8 +600,29 @@ import { z } from "zod";
|
|
|
600
600
|
* lines naming each with the file to fix it in. Additive only. Apply to every repo (POST
|
|
601
601
|
* /api/facts/apply-all) the same: a repo that wrote with facts left out is applied, and its
|
|
602
602
|
* result carries `leftOut` (all repos) and `leftOutRepos` (how many repos left some out).
|
|
603
|
+
* 3.15.0 (beta.28.2, ADR 0197 "beta.28.1 and older reading version 2"): a refused build's
|
|
604
|
+
* `reasons` (BuildRefusalView: GET /api/build's `pending.refused` and `last.refused`, a scan's
|
|
605
|
+
* and an Apply's job result) may be `newer-atticus`: catalog/sources/build.json or a slot was
|
|
606
|
+
* written by a newer Atticus, at a version of its format this one doesn't read. Its `message`
|
|
607
|
+
* says so, its `command` is `npm i -g @maycombhq/atticus@beta`, and nothing was written; it is
|
|
608
|
+
* never `not-upgraded`. The Apply preview's `confirm.refused` may list it the same way. The
|
|
609
|
+
* upgrade job (POST /api/upgrade) refuses on such a catalog with the same words; GET
|
|
610
|
+
* /api/upgrade then lists no `pending` step and says why in `newerCatalog`, and GET
|
|
611
|
+
* /api/build/undo offers no `plan` (its `problem` says why). Every route
|
|
612
|
+
* that writes one of the build's inputs (the build, scan, Apply, undo, prune, the upgrade, the
|
|
613
|
+
* map's edits and deletes, corrections, call corrections, pairings, declared links and boxes,
|
|
614
|
+
* answers, triage, the AI's decisions, the baseline, initiatives, an owner question's send,
|
|
615
|
+
* starting a run, the org pack's files, patterns, sources, adapters and AI settings, a file
|
|
616
|
+
* promoted into inputs/, repos and owners) answers 409 on such a catalog before it writes
|
|
617
|
+
* anything: a problem whose `refused` is `{ reasons: ["newer-atticus"], message, newer }`,
|
|
618
|
+
* `newer` (BuildRefusalView's, optional) naming each file a newer Atticus wrote with its
|
|
619
|
+
* version and the newest one this Atticus reads. Additive only.
|
|
620
|
+
* Also in 3.15.0 (ADR 0197 review): a `hand-edits` refusal may carry `unreadableManifest: true`,
|
|
621
|
+
* when catalog/sources/build.json is there but doesn't read (edited or merged by hand). Its
|
|
622
|
+
* `command` is the build again with `--discard-edits` of every record file, never the curate.
|
|
623
|
+
* Additive only.
|
|
603
624
|
*/
|
|
604
|
-
export declare const API_VERSION = "3.
|
|
625
|
+
export declare const API_VERSION = "3.15.0";
|
|
605
626
|
export declare const DEFAULT_PORT = 4321;
|
|
606
627
|
/** RFC 9457 problem details, used for every error. */
|
|
607
628
|
/**
|
|
@@ -3991,6 +4012,7 @@ export declare const BuildRefusalView: z.ZodObject<{
|
|
|
3991
4012
|
"large-removals": "large-removals";
|
|
3992
4013
|
"hand-edits": "hand-edits";
|
|
3993
4014
|
"not-upgraded": "not-upgraded";
|
|
4015
|
+
"newer-atticus": "newer-atticus";
|
|
3994
4016
|
}>>;
|
|
3995
4017
|
message: z.ZodString;
|
|
3996
4018
|
removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
@@ -4067,6 +4089,14 @@ export declare const BuildRefusalView: z.ZodObject<{
|
|
|
4067
4089
|
repo: z.ZodString;
|
|
4068
4090
|
why: z.ZodString;
|
|
4069
4091
|
}, z.core.$strip>>>;
|
|
4092
|
+
unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
|
|
4093
|
+
newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
4094
|
+
path: z.ZodString;
|
|
4095
|
+
name: z.ZodString;
|
|
4096
|
+
field: z.ZodString;
|
|
4097
|
+
version: z.ZodNumber;
|
|
4098
|
+
reads: z.ZodNumber;
|
|
4099
|
+
}, z.core.$strip>>>;
|
|
4070
4100
|
command: z.ZodString;
|
|
4071
4101
|
plan: z.ZodOptional<z.ZodString>;
|
|
4072
4102
|
}, z.core.$strip>;
|
|
@@ -4102,6 +4132,7 @@ export declare const BuildReportView: z.ZodObject<{
|
|
|
4102
4132
|
"large-removals": "large-removals";
|
|
4103
4133
|
"hand-edits": "hand-edits";
|
|
4104
4134
|
"not-upgraded": "not-upgraded";
|
|
4135
|
+
"newer-atticus": "newer-atticus";
|
|
4105
4136
|
}>>;
|
|
4106
4137
|
message: z.ZodString;
|
|
4107
4138
|
removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
@@ -4178,6 +4209,14 @@ export declare const BuildReportView: z.ZodObject<{
|
|
|
4178
4209
|
repo: z.ZodString;
|
|
4179
4210
|
why: z.ZodString;
|
|
4180
4211
|
}, z.core.$strip>>>;
|
|
4212
|
+
unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
|
|
4213
|
+
newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
4214
|
+
path: z.ZodString;
|
|
4215
|
+
name: z.ZodString;
|
|
4216
|
+
field: z.ZodString;
|
|
4217
|
+
version: z.ZodNumber;
|
|
4218
|
+
reads: z.ZodNumber;
|
|
4219
|
+
}, z.core.$strip>>>;
|
|
4181
4220
|
command: z.ZodString;
|
|
4182
4221
|
plan: z.ZodOptional<z.ZodString>;
|
|
4183
4222
|
}, z.core.$strip>>;
|
|
@@ -4316,6 +4355,7 @@ export declare const CatalogBuildView: z.ZodObject<{
|
|
|
4316
4355
|
"large-removals": "large-removals";
|
|
4317
4356
|
"hand-edits": "hand-edits";
|
|
4318
4357
|
"not-upgraded": "not-upgraded";
|
|
4358
|
+
"newer-atticus": "newer-atticus";
|
|
4319
4359
|
}>>;
|
|
4320
4360
|
message: z.ZodString;
|
|
4321
4361
|
removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
@@ -4392,6 +4432,14 @@ export declare const CatalogBuildView: z.ZodObject<{
|
|
|
4392
4432
|
repo: z.ZodString;
|
|
4393
4433
|
why: z.ZodString;
|
|
4394
4434
|
}, z.core.$strip>>>;
|
|
4435
|
+
unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
|
|
4436
|
+
newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
4437
|
+
path: z.ZodString;
|
|
4438
|
+
name: z.ZodString;
|
|
4439
|
+
field: z.ZodString;
|
|
4440
|
+
version: z.ZodNumber;
|
|
4441
|
+
reads: z.ZodNumber;
|
|
4442
|
+
}, z.core.$strip>>>;
|
|
4395
4443
|
command: z.ZodString;
|
|
4396
4444
|
plan: z.ZodOptional<z.ZodString>;
|
|
4397
4445
|
}, z.core.$strip>>;
|
|
@@ -4415,6 +4463,7 @@ export declare const CatalogBuildView: z.ZodObject<{
|
|
|
4415
4463
|
"large-removals": "large-removals";
|
|
4416
4464
|
"hand-edits": "hand-edits";
|
|
4417
4465
|
"not-upgraded": "not-upgraded";
|
|
4466
|
+
"newer-atticus": "newer-atticus";
|
|
4418
4467
|
}>>;
|
|
4419
4468
|
message: z.ZodString;
|
|
4420
4469
|
removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
@@ -4491,6 +4540,14 @@ export declare const CatalogBuildView: z.ZodObject<{
|
|
|
4491
4540
|
repo: z.ZodString;
|
|
4492
4541
|
why: z.ZodString;
|
|
4493
4542
|
}, z.core.$strip>>>;
|
|
4543
|
+
unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
|
|
4544
|
+
newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
4545
|
+
path: z.ZodString;
|
|
4546
|
+
name: z.ZodString;
|
|
4547
|
+
field: z.ZodString;
|
|
4548
|
+
version: z.ZodNumber;
|
|
4549
|
+
reads: z.ZodNumber;
|
|
4550
|
+
}, z.core.$strip>>>;
|
|
4494
4551
|
command: z.ZodString;
|
|
4495
4552
|
plan: z.ZodOptional<z.ZodString>;
|
|
4496
4553
|
}, z.core.$strip>>;
|
|
@@ -4923,6 +4980,7 @@ export declare const MapEditsResult: z.ZodObject<{
|
|
|
4923
4980
|
"large-removals": "large-removals";
|
|
4924
4981
|
"hand-edits": "hand-edits";
|
|
4925
4982
|
"not-upgraded": "not-upgraded";
|
|
4983
|
+
"newer-atticus": "newer-atticus";
|
|
4926
4984
|
}>>;
|
|
4927
4985
|
message: z.ZodString;
|
|
4928
4986
|
removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
@@ -4999,6 +5057,14 @@ export declare const MapEditsResult: z.ZodObject<{
|
|
|
4999
5057
|
repo: z.ZodString;
|
|
5000
5058
|
why: z.ZodString;
|
|
5001
5059
|
}, z.core.$strip>>>;
|
|
5060
|
+
unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
|
|
5061
|
+
newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
5062
|
+
path: z.ZodString;
|
|
5063
|
+
name: z.ZodString;
|
|
5064
|
+
field: z.ZodString;
|
|
5065
|
+
version: z.ZodNumber;
|
|
5066
|
+
reads: z.ZodNumber;
|
|
5067
|
+
}, z.core.$strip>>>;
|
|
5002
5068
|
command: z.ZodString;
|
|
5003
5069
|
plan: z.ZodOptional<z.ZodString>;
|
|
5004
5070
|
}, z.core.$strip>>;
|
|
@@ -5021,6 +5087,7 @@ export declare const FactsApplyResult: z.ZodObject<{
|
|
|
5021
5087
|
"large-removals": "large-removals";
|
|
5022
5088
|
"hand-edits": "hand-edits";
|
|
5023
5089
|
"not-upgraded": "not-upgraded";
|
|
5090
|
+
"newer-atticus": "newer-atticus";
|
|
5024
5091
|
}>>;
|
|
5025
5092
|
message: z.ZodString;
|
|
5026
5093
|
removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
@@ -5097,6 +5164,14 @@ export declare const FactsApplyResult: z.ZodObject<{
|
|
|
5097
5164
|
repo: z.ZodString;
|
|
5098
5165
|
why: z.ZodString;
|
|
5099
5166
|
}, z.core.$strip>>>;
|
|
5167
|
+
unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
|
|
5168
|
+
newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
5169
|
+
path: z.ZodString;
|
|
5170
|
+
name: z.ZodString;
|
|
5171
|
+
field: z.ZodString;
|
|
5172
|
+
version: z.ZodNumber;
|
|
5173
|
+
reads: z.ZodNumber;
|
|
5174
|
+
}, z.core.$strip>>>;
|
|
5100
5175
|
command: z.ZodString;
|
|
5101
5176
|
plan: z.ZodOptional<z.ZodString>;
|
|
5102
5177
|
}, z.core.$strip>>;
|
|
@@ -6375,6 +6450,7 @@ export declare const VerifyPreviewView: z.ZodObject<{
|
|
|
6375
6450
|
"nothing-read": "nothing-read";
|
|
6376
6451
|
empty: "empty";
|
|
6377
6452
|
"unexplained-removals": "unexplained-removals";
|
|
6453
|
+
"newer-atticus": "newer-atticus";
|
|
6378
6454
|
}>>>;
|
|
6379
6455
|
upgrade: z.ZodOptional<z.ZodLiteral<true>>;
|
|
6380
6456
|
command: z.ZodOptional<z.ZodString>;
|
|
@@ -14233,6 +14309,7 @@ export declare const UpgradeView: z.ZodObject<{
|
|
|
14233
14309
|
files: z.ZodArray<z.ZodString>;
|
|
14234
14310
|
}, z.core.$strip>>;
|
|
14235
14311
|
upgraded: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
14312
|
+
newerCatalog: z.ZodOptional<z.ZodString>;
|
|
14236
14313
|
}, z.core.$strip>;
|
|
14237
14314
|
/**
|
|
14238
14315
|
* 3.5.0: what a setup edit changed, or with `preview: true` would change: the file
|
package/npm/core/cancel.d.ts
CHANGED
|
@@ -12,5 +12,11 @@ export declare function withCommit<T>(commit: () => void, fn: () => Promise<T>):
|
|
|
12
12
|
export declare function commitCurrent(): boolean;
|
|
13
13
|
/** The signal of the job this code runs in, if it runs in one. */
|
|
14
14
|
export declare function currentSignal(): AbortSignal | undefined;
|
|
15
|
+
/**
|
|
16
|
+
* Beta.28.3: the signal a long read may stop on part way (the hash of every file of the
|
|
17
|
+
* catalog): the job's, until its work says it has started writing. From then there is none, so a
|
|
18
|
+
* read that is part of a write is never cut short and nothing is left half written.
|
|
19
|
+
*/
|
|
20
|
+
export declare function stoppableSignal(): AbortSignal | undefined;
|
|
15
21
|
/** Stop here when the job was cancelled. */
|
|
16
22
|
export declare function throwIfCancelled(): void;
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reading and hashing many small files (beta.28.2): a catalog's 100,000 record files took 10 to
|
|
3
|
+
* 13 s to hash through the promise API, four calls each (open, stat, read, close) handed to
|
|
4
|
+
* libuv's thread pool and back, and each text decoded, its line endings replaced and encoded again
|
|
5
|
+
* to be hashed. Here a few worker threads read them with the synchronous calls, one file at a
|
|
6
|
+
* time each (so no more than one open file a worker: no EMFILE, on Windows either), and hash the
|
|
7
|
+
* bytes; the main thread stays free (a progress line, Stop between steps) and gets the results in
|
|
8
|
+
* the order of the paths, whatever the order the workers finish in. Every byte of every file is
|
|
9
|
+
* read: nothing is taken from a file's size and time. A small folder, or a process where a worker
|
|
10
|
+
* can't start, is read in this thread instead, to the same results.
|
|
11
|
+
*
|
|
12
|
+
* Beta.28.3: a read given a `signal` (a job's Stop) ends when it is stopped, with CancelledError:
|
|
13
|
+
* the workers are ended where they are (no more than the file each has open is read on), this
|
|
14
|
+
* thread's read stops between two files, and the wait for workers that never start ends at once.
|
|
15
|
+
* It only reads, so a stopped read leaves nothing behind.
|
|
16
|
+
*/
|
|
17
|
+
/** A file's size and time (ms, floored), as `stat` gives them. */
|
|
18
|
+
export interface FileStat {
|
|
19
|
+
size: number;
|
|
20
|
+
mtimeMs: number;
|
|
21
|
+
}
|
|
22
|
+
/** A file's size and time, and the hash of its text with its line endings LF (`textShaOf`). */
|
|
23
|
+
export interface FileHash extends FileStat {
|
|
24
|
+
sha: string;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* How the files are read: tests force a number of workers (0: this thread) and the smallest
|
|
28
|
+
* folder read by workers. By default 2 to 4 workers (one fewer than the CPUs, at least 2), for
|
|
29
|
+
* folders of `MIN_FILES` files or more.
|
|
30
|
+
*/
|
|
31
|
+
export declare const filePoolHooks: {
|
|
32
|
+
workers?: number;
|
|
33
|
+
minFiles?: number;
|
|
34
|
+
/** A test's workers that fail as they start (as one that can't: ERR_WORKER_INIT_FAILED, OOM). */
|
|
35
|
+
failStart?: boolean;
|
|
36
|
+
/** A test's workers that start and never say they are ready (nor fail, nor exit). */
|
|
37
|
+
neverReady?: boolean;
|
|
38
|
+
/** How long the workers have to say they are ready (default `START_TIMEOUT_MS`). */
|
|
39
|
+
startTimeoutMs?: number;
|
|
40
|
+
/** A test hears how many files are read so far (in workers a batch at a time). */
|
|
41
|
+
onRead?: (files: number) => void;
|
|
42
|
+
};
|
|
43
|
+
/**
|
|
44
|
+
* How long the workers have to say they are ready before this thread reads instead (the final
|
|
45
|
+
* review of beta.28.2: a worker that neither answered nor failed hung the build). A worker starts
|
|
46
|
+
* in tens of milliseconds; 10 s is a host so loaded that this thread would be no slower.
|
|
47
|
+
*/
|
|
48
|
+
export declare const START_TIMEOUT_MS = 10000;
|
|
49
|
+
/**
|
|
50
|
+
* The hash of a file's text, read as UTF-8, with its line endings LF: `sha256Of` of that text.
|
|
51
|
+
* Bytes that are UTF-8 with no CR are that text's own bytes, so they are hashed as they are;
|
|
52
|
+
* any other (a CR, a byte that isn't UTF-8, read as U+FFFD) are decoded first, as a read gives.
|
|
53
|
+
*/
|
|
54
|
+
export declare function textShaOf(bytes: Buffer): string;
|
|
55
|
+
/**
|
|
56
|
+
* Every named file under `dir` (paths with forward slashes), read whole and hashed: its text hash
|
|
57
|
+
* (`textShaOf`), size and time, in the order of `rels`. A file that can't be opened or read fails
|
|
58
|
+
* the call with that error (its `code`: ENOENT for one gone since it was listed). With `raw`, the
|
|
59
|
+
* hash is of the file's bytes as they are (sha256, no line endings made LF): a parse kept by it
|
|
60
|
+
* is of exactly those bytes (record-cache.ts). With `signal`, a stop ends the read part way and
|
|
61
|
+
* fails the call with CancelledError (beta.28.3).
|
|
62
|
+
*/
|
|
63
|
+
export declare function hashFilesIn(dir: string, rels: readonly string[], o?: {
|
|
64
|
+
raw?: boolean;
|
|
65
|
+
signal?: AbortSignal;
|
|
66
|
+
}): Promise<FileHash[]>;
|
|
67
|
+
/**
|
|
68
|
+
* Every named file's size and time (ms, floored), in the order of `rels`; none for one not there.
|
|
69
|
+
* With `signal`, a stop ends the read part way and fails the call with CancelledError.
|
|
70
|
+
*/
|
|
71
|
+
export declare function statFilesIn(dir: string, rels: readonly string[], o?: {
|
|
72
|
+
signal?: AbortSignal;
|
|
73
|
+
}): Promise<(FileStat | undefined)[]>;
|
package/npm/core/fs.d.ts
CHANGED
|
@@ -5,7 +5,23 @@
|
|
|
5
5
|
* Windows a rename can fail for a moment while a virus scanner or indexer holds the file:
|
|
6
6
|
* it is retried a few times before giving up.
|
|
7
7
|
*/
|
|
8
|
-
export declare function writeFileAtomic(path: string, data: string | Uint8Array
|
|
8
|
+
export declare function writeFileAtomic(path: string, data: string | Uint8Array, o?: {
|
|
9
|
+
/**
|
|
10
|
+
* Told the size and time (ms, floored) of the file as written (beta.28.2: a writer keeps its
|
|
11
|
+
* parse by them): the temporary file's, taken on its handle before the rename (which keeps
|
|
12
|
+
* them), when the file has the same once renamed; not told when they differ (the file was
|
|
13
|
+
* changed meanwhile, or the system set another time on close). With them, the sha256 of the
|
|
14
|
+
* bytes written and `writtenAt`, the clock (ms) as the write began: a parse kept by them is
|
|
15
|
+
* checked by that hash while the file's time is within the timestamp's grain of `writtenAt`
|
|
16
|
+
* (record-cache.ts, `RACY_MS`).
|
|
17
|
+
*/
|
|
18
|
+
stat?: (s: {
|
|
19
|
+
size: number;
|
|
20
|
+
mtimeMs: number;
|
|
21
|
+
sha: string;
|
|
22
|
+
writtenAt: number;
|
|
23
|
+
}) => void;
|
|
24
|
+
}): Promise<void>;
|
|
9
25
|
/**
|
|
10
26
|
* Copy a file the way `writeFileAtomic` writes one: to a temporary file beside the target, then
|
|
11
27
|
* renamed over it. The copy is made by the system (a copy-on-write clone where the file system
|
package/npm/core/index.d.ts
CHANGED
|
@@ -60,12 +60,14 @@ export * from "./fs.js";
|
|
|
60
60
|
export * from "./glob.js";
|
|
61
61
|
export * from "./repo-files.js";
|
|
62
62
|
export * from "./record-cache.js";
|
|
63
|
+
export * from "./file-pool.js";
|
|
63
64
|
export * from "./kept-files.js";
|
|
64
65
|
export * from "./log.js";
|
|
65
66
|
export * from "./run-log.js";
|
|
66
67
|
export * from "./printer.js";
|
|
67
68
|
export * from "./zip.js";
|
|
68
69
|
export * from "./words.js";
|
|
70
|
+
export * from "./initialisms.js";
|
|
69
71
|
export * from "./zip-read.js";
|
|
70
72
|
export * from "./tar-read.js";
|
|
71
73
|
export * from "./schema/question.js";
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* An acronym and the words it stands for (beta.28.3): "SSO" and "single sign-on", "EDW" and
|
|
3
|
+
* "enterprise data warehouse". One side of a search often writes the letters and the other the
|
|
4
|
+
* words, with no word in common, and a small embedding model rates the two far apart.
|
|
5
|
+
*
|
|
6
|
+
* The link is taken only from where the organisation's own pages define it: "Enterprise Data
|
|
7
|
+
* Warehouse (EDW)", "EDW (Enterprise Data Warehouse)", or a line of an abbreviations list
|
|
8
|
+
* ("EDW: Enterprise Data Warehouse", "| SSO | single sign-on |"), and only when the words' first
|
|
9
|
+
* letters spell the acronym. Letters alone are not enough: ordinary prose spells most
|
|
10
|
+
* three-letter acronyms by chance ("step still open" is no SSO), so a run of words is never
|
|
11
|
+
* taken for an acronym's meaning unless a page sets the two side by side. Deterministic, no
|
|
12
|
+
* model. A link only ranks and keeps what a search shows; it never makes a record or a fact.
|
|
13
|
+
*/
|
|
14
|
+
export interface Initialism {
|
|
15
|
+
/** As written: capital letters and digits, three to six, starting with a letter. */
|
|
16
|
+
acronym: string;
|
|
17
|
+
/** The words it stands for: lower case, single spaces, hyphens as spaces. */
|
|
18
|
+
phrase: string;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* How a phrase is looked for in a text: lower case, anything but letters and digits as one space,
|
|
22
|
+
* a space at each end. Where a sentence, a bracket or a paragraph ends there is a bar, so a phrase is
|
|
23
|
+
* never found across one ("the change. Request access" writes no "change request").
|
|
24
|
+
*/
|
|
25
|
+
export declare const foldWords: (s: string) => string;
|
|
26
|
+
/**
|
|
27
|
+
* The acronyms a text defines, each with the words it sets beside it, in the order met:
|
|
28
|
+
*
|
|
29
|
+
* - `words (ACR)`: the words just before the bracket, as many as spell it;
|
|
30
|
+
* - `ACR (words)`: everything in the bracket;
|
|
31
|
+
* - `ACR: words`, `ACR - words`, `ACR = words`, `| ACR | words |` at a line's start (after a
|
|
32
|
+
* list mark or emphasis): the words up to the next punctuation, as many as spell it.
|
|
33
|
+
*
|
|
34
|
+
* The words' first letters must spell the acronym; a pair that doesn't is no definition.
|
|
35
|
+
*/
|
|
36
|
+
export declare function definedInitialisms(text: string): Initialism[];
|
|
37
|
+
export interface InitialismUse extends Initialism {
|
|
38
|
+
/** Which form the text writes. */
|
|
39
|
+
wrote: "acronym" | "phrase";
|
|
40
|
+
}
|
|
41
|
+
export interface InitialismLink extends Initialism {
|
|
42
|
+
/** Which text writes the acronym; the other writes the words. */
|
|
43
|
+
acronymIn: "a" | "b";
|
|
44
|
+
}
|
|
45
|
+
/** The acronyms an estate's pages define, to link a text that writes one form to one that writes the other. */
|
|
46
|
+
export interface InitialismBook {
|
|
47
|
+
readonly size: number;
|
|
48
|
+
entries(): Initialism[];
|
|
49
|
+
/** The defined acronyms a text writes, and the defined phrases it writes, in the book's order. */
|
|
50
|
+
uses(text: string): InitialismUse[];
|
|
51
|
+
/**
|
|
52
|
+
* The names one text writes as an acronym and the other only as its words. A name both write
|
|
53
|
+
* as the acronym is a word in common, not a link, and is left out.
|
|
54
|
+
*/
|
|
55
|
+
links(a: string, b: string): InitialismLink[];
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* A book of definitions, each acronym and phrase once, sorted: the same definitions give the same
|
|
59
|
+
* book. An acronym that is an ordinary word in capitals (POST, NOTE, AND) is left out, as is a
|
|
60
|
+
* phrase of one word.
|
|
61
|
+
*/
|
|
62
|
+
export declare function initialismBook(defs: Iterable<Initialism>): InitialismBook;
|
|
@@ -7,11 +7,22 @@ import { type ChildProcess } from "node:child_process";
|
|
|
7
7
|
* listener (onStopping: taskrun aborts its model call), and lets the signal end Atticus once nothing
|
|
8
8
|
* holds on (or after TREE_SIGNAL_GRACE_MS). When Atticus exits, every tree still running is killed
|
|
9
9
|
* outright. Shared by taskrun's builds and workspace's git (it was taskrun's own).
|
|
10
|
+
*
|
|
11
|
+
* Beta.28.3: three ways a tree outlived Atticus when the terminal closed at the wrong moment.
|
|
12
|
+
* The handlers were hooked only once the child was tracked, after it had started: a signal in
|
|
13
|
+
* between (seen in CI, a few milliseconds wide) ended Atticus as if nothing ran, and the child,
|
|
14
|
+
* in its own group, never heard it (startTree hooks first). A tree started after the signal was
|
|
15
|
+
* never stopped, and Atticus ending by the signal (no exit handlers run then) killed nothing of
|
|
16
|
+
* what still ran after the grace, nor what a stopped tree's leader left behind in its group.
|
|
10
17
|
*/
|
|
11
18
|
/** How a tracked tree is stopped: its own way (git's tree, a build's group), by the signal. */
|
|
12
19
|
export type StopTree = (signal: NodeJS.Signals) => void;
|
|
13
20
|
/** However long the runs take to record themselves, Atticus ends by the signal within this. */
|
|
14
21
|
export declare const TREE_SIGNAL_GRACE_MS = 10000;
|
|
22
|
+
/** A test's shorter grace (TREE_SIGNAL_GRACE_MS otherwise). */
|
|
23
|
+
export declare const processTreeHooks: {
|
|
24
|
+
signalGraceMs?: number;
|
|
25
|
+
};
|
|
15
26
|
/**
|
|
16
27
|
* Stop every tracked tree (SIGTERM, each its own way) and tell each listener: Atticus is
|
|
17
28
|
* stopping (atticus ui on its way out, or a signal).
|
|
@@ -51,9 +62,21 @@ export declare const stopPending: () => boolean;
|
|
|
51
62
|
/**
|
|
52
63
|
* Keep a child in its own process group until it ends: stopped with Atticus (a signal,
|
|
53
64
|
* stopTrackedTrees) by `stop`, killed by it with SIGKILL when Atticus exits. Gives back the way
|
|
54
|
-
* to let go of it (when it has ended).
|
|
65
|
+
* to let go of it (when it has ended). One tracked after a signal that ends Atticus is stopped
|
|
66
|
+
* at once. A child started in its own group is started through `startTree`, never tracked after
|
|
67
|
+
* the fact: a signal between its start and this call would end Atticus and leave it running.
|
|
55
68
|
*/
|
|
56
69
|
export declare function trackTree(child: ChildProcess, stop?: StopTree): () => void;
|
|
70
|
+
/**
|
|
71
|
+
* Start a child in its own process group and keep it (trackTree), with the signals' handlers in
|
|
72
|
+
* place before it starts: from its first moment a closed terminal, Ctrl+C or SIGTERM stops it
|
|
73
|
+
* with Atticus. `stop` is how it is stopped (its group by default). A start that throws keeps
|
|
74
|
+
* nothing.
|
|
75
|
+
*/
|
|
76
|
+
export declare function startTree<C extends ChildProcess>(start: () => C, stop?: (child: C) => StopTree): {
|
|
77
|
+
child: C;
|
|
78
|
+
untrack: () => void;
|
|
79
|
+
};
|
|
57
80
|
/**
|
|
58
81
|
* Hold a stop for a task run, from its start until its record is saved: a signal meanwhile
|
|
59
82
|
* stops its trees, and Atticus ends only once it is released.
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { type FileStat } from "./file-pool.js";
|
|
1
2
|
/**
|
|
2
3
|
* Record files read and parsed once, then kept between runs (ADR 0119, with its addendum of
|
|
3
4
|
* 2026-10-26). A metarepo's catalog is about 1,500 files and its specs 400 more; reading and
|
|
@@ -16,7 +17,31 @@
|
|
|
16
17
|
*
|
|
17
18
|
* Nothing here decides what a file means: the caller's `parse` does, and only its output (the
|
|
18
19
|
* record, or the problem with the file) is kept.
|
|
20
|
+
*
|
|
21
|
+
* Racily clean files (the final review of beta.28.2, Git's rule of the same name). A file system
|
|
22
|
+
* keeps a file's time to a grain (FAT 2 s, HFS+ 1 s, some SMB and NFS mounts 1 s or more), so a
|
|
23
|
+
* same-size edit made within that grain of a read or a write can keep the time the parse was kept
|
|
24
|
+
* by, and size and time alone would serve the old text. So each parse is kept with the clock as
|
|
25
|
+
* it was taken (`at`: before the bytes parsed were read, or before a writer wrote them), and one
|
|
26
|
+
* whose file's time is no more than `RACY_MS` before `at` is "racy": it keeps the sha256 of the
|
|
27
|
+
* bytes parsed, and is reused only when the file still hashes to them (read in the file pool's
|
|
28
|
+
* workers; cheaper than a parse), then kept again as of the hash's read when by then it is no
|
|
29
|
+
* longer racy (the next command, seconds on: from then on its stat alone decides). A parse whose
|
|
30
|
+
* file's time is more than `RACY_MS` before `at` is trusted by size and time, as before: any edit
|
|
31
|
+
* after `at` has a time after `at` less the grain, so it can't keep that time. A parse kept with no `at` (an older cache) is racy, and with no hash it is
|
|
32
|
+
* parsed again. The rule takes this machine's clock and the file system's to agree to within the
|
|
33
|
+
* grain (a mount whose server runs more than `RACY_MS` behind can still serve a stale parse, as
|
|
34
|
+
* Git can).
|
|
35
|
+
*/
|
|
36
|
+
/**
|
|
37
|
+
* The widest timestamp grain allowed for (FAT's 2 s): a parse kept of a file whose time was
|
|
38
|
+
* within this of the moment it was kept is checked by its hash before it is reused.
|
|
19
39
|
*/
|
|
40
|
+
export declare const RACY_MS = 2000;
|
|
41
|
+
/** Tests set the clock a parse is kept at (ms; default `Date.now`). */
|
|
42
|
+
export declare const recordCacheHooks: {
|
|
43
|
+
now?: () => number;
|
|
44
|
+
};
|
|
20
45
|
/** One file's parse: the value, or why the file isn't valid. Never both. */
|
|
21
46
|
export interface Parsed<T> {
|
|
22
47
|
/** The file, relative to the folder, with forward slashes. */
|
|
@@ -35,8 +60,21 @@ export type ParseOutcome<T> = {
|
|
|
35
60
|
ok: false;
|
|
36
61
|
message: string;
|
|
37
62
|
};
|
|
38
|
-
|
|
39
|
-
|
|
63
|
+
interface Entry {
|
|
64
|
+
size: number;
|
|
65
|
+
mtimeMs: number;
|
|
66
|
+
/** The clock (ms) as the parse was kept: before its bytes were read, or written. None: racy. */
|
|
67
|
+
at?: number;
|
|
68
|
+
/** A racy entry's sha256 of the bytes parsed (none once it isn't racy). */
|
|
69
|
+
sha?: string;
|
|
70
|
+
value?: unknown;
|
|
71
|
+
problem?: string;
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* Run `f` over the items, up to `AT_ONCE` at a time, keeping the order. With `signal`, a stop
|
|
75
|
+
* ends it between two lots with CancelledError (beta.28.3).
|
|
76
|
+
*/
|
|
77
|
+
export declare function mapAtOnce<I, O>(items: I[], f: (item: I) => Promise<O>, signal?: AbortSignal): Promise<O[]>;
|
|
40
78
|
/**
|
|
41
79
|
* Read and parse every named file of a folder, reusing the parses kept from an earlier run for
|
|
42
80
|
* the files that haven't changed. `name` names the kind of file (`catalog`, `spec`), `version`
|
|
@@ -59,4 +97,59 @@ export declare function readParsedFiles<T>(o: {
|
|
|
59
97
|
keep?: boolean;
|
|
60
98
|
/** Each file's size and time with its parse (beta.28.1: a write matches them to its own read). */
|
|
61
99
|
withStats?: boolean;
|
|
100
|
+
/**
|
|
101
|
+
* Told what this read keeps under `cacheRoot` (not called when it keeps nothing): a writer that
|
|
102
|
+
* then writes some of the files adds their parses with `keepParses` (beta.28.2).
|
|
103
|
+
*/
|
|
104
|
+
kept?: (k: KeptParses<T>) => void;
|
|
105
|
+
/**
|
|
106
|
+
* Beta.28.3: a job's Stop. A stop while the files' sizes and times are read, their bytes
|
|
107
|
+
* hashed, or the files read and parsed (a first read of a large catalog) ends the read with
|
|
108
|
+
* CancelledError; nothing is kept of a stopped read.
|
|
109
|
+
*/
|
|
110
|
+
signal?: AbortSignal;
|
|
62
111
|
}): Promise<Parsed<T>[]>;
|
|
112
|
+
/** What a read kept of a folder's parses (`readParsedFiles`'s `kept`), for `keepParses`. */
|
|
113
|
+
export interface KeptParses<T> {
|
|
114
|
+
readonly memo: {
|
|
115
|
+
root: string;
|
|
116
|
+
file: string;
|
|
117
|
+
};
|
|
118
|
+
readonly version: string;
|
|
119
|
+
readonly dir: string;
|
|
120
|
+
/** The kept parses by path, as that read left them. */
|
|
121
|
+
readonly entries: ReadonlyMap<string, Entry>;
|
|
122
|
+
/** Only to tie the type to the parse's value. */
|
|
123
|
+
readonly _value?: T;
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* Add the parses of files a writer wrote since its read (`k`) to what that read kept, and forget
|
|
127
|
+
* the files it removed (beta.28.2: a catalog write rewrites its features and glossary terms,
|
|
128
|
+
* megabytes of YAML, and the next read parsed them again). Each file is kept by the size and time
|
|
129
|
+
* it had as it was written, with the parse of the text the writer wrote there, which is what a
|
|
130
|
+
* read of it would parse; a file whose size or time is another now (changed since), or gone, isn't
|
|
131
|
+
* kept. A file written moments ago is racy (its time is within `RACY_MS` of the write): it is kept
|
|
132
|
+
* with the hash of the bytes written (`writeFileAtomic`'s `stat` gives it, and the clock as the
|
|
133
|
+
* write began), so the next read reuses it only when the file still hashes to them; one with no
|
|
134
|
+
* hash is parsed again by the next read. A cache that can't be written costs the next read its
|
|
135
|
+
* parses.
|
|
136
|
+
*/
|
|
137
|
+
export declare function keepParses<T>(k: KeptParses<T>, o: {
|
|
138
|
+
/**
|
|
139
|
+
* Each file written, with the size and time it had as it was written (`writeFileAtomic`'s
|
|
140
|
+
* `stat`): it is kept only while it still has exactly those, so an edit made since (of the
|
|
141
|
+
* same size too: its time differs, or within the grain its hash does) is parsed by the next
|
|
142
|
+
* read, never served the writer's text. `sha` and `writtenAt` as `writeFileAtomic` gives them.
|
|
143
|
+
*/
|
|
144
|
+
files: readonly {
|
|
145
|
+
rel: string;
|
|
146
|
+
value?: T;
|
|
147
|
+
problem?: string;
|
|
148
|
+
at: FileStat & {
|
|
149
|
+
sha?: string;
|
|
150
|
+
writtenAt?: number;
|
|
151
|
+
};
|
|
152
|
+
}[];
|
|
153
|
+
removed: readonly string[];
|
|
154
|
+
}): Promise<void>;
|
|
155
|
+
export {};
|
package/npm/index.js
CHANGED
|
@@ -6992,7 +6992,9 @@ var BuildRefusalView = z31.object({
|
|
|
6992
6992
|
"unexplained-removals",
|
|
6993
6993
|
"large-removals",
|
|
6994
6994
|
"hand-edits",
|
|
6995
|
-
"not-upgraded"
|
|
6995
|
+
"not-upgraded",
|
|
6996
|
+
// 3.15.0 (beta.28.2, ADR 0197): build.json or a slot a newer Atticus wrote.
|
|
6997
|
+
"newer-atticus"
|
|
6996
6998
|
])),
|
|
6997
6999
|
message: z31.string(),
|
|
6998
7000
|
removals: z31.array(BuildRemoval).optional(),
|
|
@@ -7002,6 +7004,28 @@ var BuildRefusalView = z31.object({
|
|
|
7002
7004
|
discardEdits: z31.number().int().optional(),
|
|
7003
7005
|
/** A scan that read nothing: each repo it couldn't read in full, and why. */
|
|
7004
7006
|
unread: z31.array(z31.object({ repo: z31.string(), why: z31.string() })).optional(),
|
|
7007
|
+
/**
|
|
7008
|
+
* 3.15.0 (beta.28.2, ADR 0197): a `hand-edits` refusal because build.json is there but doesn't
|
|
7009
|
+
* read (edited or merged by hand). The only way on is to build again with `discardEdits` (every
|
|
7010
|
+
* record file); its edits are not to be made curated.
|
|
7011
|
+
*/
|
|
7012
|
+
unreadableManifest: z31.literal(true).optional(),
|
|
7013
|
+
/**
|
|
7014
|
+
* 3.15.0 (beta.28.2, ADR 0197): a `newer-atticus` refusal's files a newer Atticus wrote
|
|
7015
|
+
* (build.json, a slot), each with its version field, the version it has and the newest one
|
|
7016
|
+
* this Atticus reads, as the 409 problem's `refused.newer` and the command line's --json say.
|
|
7017
|
+
*/
|
|
7018
|
+
newer: z31.array(z31.object({
|
|
7019
|
+
/** Metarepo-relative, '/'-separated. */
|
|
7020
|
+
path: z31.string(),
|
|
7021
|
+
/** What the words call it: `build.json`, or its path. */
|
|
7022
|
+
name: z31.string(),
|
|
7023
|
+
/** The version field (`version`, `slotVersion`, `factsSchemaVersion`). */
|
|
7024
|
+
field: z31.string(),
|
|
7025
|
+
version: z31.number().int(),
|
|
7026
|
+
/** The newest version of it this Atticus reads. */
|
|
7027
|
+
reads: z31.number().int()
|
|
7028
|
+
})).optional(),
|
|
7005
7029
|
/** What goes on in a terminal (the build, the hand edits' curate, or the upgrade). */
|
|
7006
7030
|
command: z31.string(),
|
|
7007
7031
|
/**
|
|
@@ -7637,7 +7661,7 @@ var VerifyPreviewView = z31.object({
|
|
|
7637
7661
|
confirm: z31.object({
|
|
7638
7662
|
removals: z31.number().int().optional(),
|
|
7639
7663
|
edits: z31.number().int().optional(),
|
|
7640
|
-
refused: z31.array(z31.enum(["nothing-read", "empty", "unexplained-removals"])).optional(),
|
|
7664
|
+
refused: z31.array(z31.enum(["nothing-read", "empty", "unexplained-removals", "newer-atticus"])).optional(),
|
|
7641
7665
|
upgrade: z31.literal(true).optional(),
|
|
7642
7666
|
command: z31.string().optional()
|
|
7643
7667
|
}).optional(),
|
|
@@ -9887,7 +9911,12 @@ var UpgradeView = z31.object({
|
|
|
9887
9911
|
* committed yet, besides the stamp. Final round: the panel reads them from the upgrade job's
|
|
9888
9912
|
* result, and offers Propose for the stamp alone too.
|
|
9889
9913
|
*/
|
|
9890
|
-
upgraded: z31.array(z31.string()).optional()
|
|
9914
|
+
upgraded: z31.array(z31.string()).optional(),
|
|
9915
|
+
/**
|
|
9916
|
+
* 3.15.0 (beta.28.2, ADR 0197): the catalog was built by a newer Atticus, in words that say to
|
|
9917
|
+
* upgrade Atticus (never `atticus upgrade`); `pending` is then empty, as the upgrade refuses.
|
|
9918
|
+
*/
|
|
9919
|
+
newerCatalog: z31.string().optional()
|
|
9891
9920
|
});
|
|
9892
9921
|
var FileEditView = z31.object({
|
|
9893
9922
|
path: z31.string(),
|
|
@@ -13618,6 +13647,11 @@ init_common();
|
|
|
13618
13647
|
init_kinds();
|
|
13619
13648
|
init_kept_files();
|
|
13620
13649
|
|
|
13650
|
+
// packages/core/dist/cancel.js
|
|
13651
|
+
import { AsyncLocalStorage } from "node:async_hooks";
|
|
13652
|
+
var store = new AsyncLocalStorage();
|
|
13653
|
+
var commits = new AsyncLocalStorage();
|
|
13654
|
+
|
|
13621
13655
|
// packages/core/dist/gates-migrate.js
|
|
13622
13656
|
init_orgpack();
|
|
13623
13657
|
import { isMap as isMap6, isSeq as isSeq4, parseDocument as parseDocument6 } from "yaml";
|
|
@@ -13968,8 +14002,11 @@ var RETITLE_WAIT_MS = 7 * 24 * 60 * 60 * 1e3;
|
|
|
13968
14002
|
var DAY = 24 * 60 * 60 * 1e3;
|
|
13969
14003
|
|
|
13970
14004
|
// packages/core/dist/printer.js
|
|
13971
|
-
import { AsyncLocalStorage } from "node:async_hooks";
|
|
13972
|
-
var printer = new
|
|
14005
|
+
import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
|
|
14006
|
+
var printer = new AsyncLocalStorage2();
|
|
14007
|
+
|
|
14008
|
+
// packages/core/dist/initialisms.js
|
|
14009
|
+
var ORDINARY = new Set("add all alter and any are ask asc bad begin but can case close closed column commit copy create data date day debug delete desc done drop each else end error fail false file fix fixme for from full get given good group had has having head help how inner insert int into its join key left like limit list max may min must new next none not note now null off old one only open option options order our out outer pass patch per post put read right row run see select set shall should show start status stop sum table tbd test that the then this tip todo top true two union update use user value values via warn warning was when where who why with yes you".split(" "));
|
|
13973
14010
|
|
|
13974
14011
|
// packages/core/dist/zip-read.js
|
|
13975
14012
|
var ZIP_LIMITS = {
|
|
@@ -14110,11 +14147,6 @@ init_kinds();
|
|
|
14110
14147
|
init_spec();
|
|
14111
14148
|
var SPEC_CACHE_VERSION = `spec@${FLOW_SCHEMA_VERSION}.${SPEC_HEADER_SCHEMA_VERSION}`;
|
|
14112
14149
|
|
|
14113
|
-
// packages/core/dist/cancel.js
|
|
14114
|
-
import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
|
|
14115
|
-
var store = new AsyncLocalStorage2();
|
|
14116
|
-
var commits = new AsyncLocalStorage2();
|
|
14117
|
-
|
|
14118
14150
|
// packages/core/dist/assistant-actor.js
|
|
14119
14151
|
init_ai();
|
|
14120
14152
|
init_orgpack();
|
package/package.json
CHANGED