@maycombhq/sdk 2.0.0-beta.28.1 → 2.0.0-beta.28.2
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/file-pool.d.ts +59 -0
- package/npm/core/fs.d.ts +17 -1
- package/npm/core/index.d.ts +1 -0
- package/npm/core/record-cache.d.ts +84 -0
- package/npm/index.js +32 -3
- 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
|
|
@@ -0,0 +1,59 @@
|
|
|
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
|
+
/** A file's size and time (ms, floored), as `stat` gives them. */
|
|
13
|
+
export interface FileStat {
|
|
14
|
+
size: number;
|
|
15
|
+
mtimeMs: number;
|
|
16
|
+
}
|
|
17
|
+
/** A file's size and time, and the hash of its text with its line endings LF (`textShaOf`). */
|
|
18
|
+
export interface FileHash extends FileStat {
|
|
19
|
+
sha: string;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* How the files are read: tests force a number of workers (0: this thread) and the smallest
|
|
23
|
+
* folder read by workers. By default 2 to 4 workers (one fewer than the CPUs, at least 2), for
|
|
24
|
+
* folders of `MIN_FILES` files or more.
|
|
25
|
+
*/
|
|
26
|
+
export declare const filePoolHooks: {
|
|
27
|
+
workers?: number;
|
|
28
|
+
minFiles?: number;
|
|
29
|
+
/** A test's workers that fail as they start (as one that can't: ERR_WORKER_INIT_FAILED, OOM). */
|
|
30
|
+
failStart?: boolean;
|
|
31
|
+
/** A test's workers that start and never say they are ready (nor fail, nor exit). */
|
|
32
|
+
neverReady?: boolean;
|
|
33
|
+
/** How long the workers have to say they are ready (default `START_TIMEOUT_MS`). */
|
|
34
|
+
startTimeoutMs?: number;
|
|
35
|
+
};
|
|
36
|
+
/**
|
|
37
|
+
* How long the workers have to say they are ready before this thread reads instead (the final
|
|
38
|
+
* review of beta.28.2: a worker that neither answered nor failed hung the build). A worker starts
|
|
39
|
+
* in tens of milliseconds; 10 s is a host so loaded that this thread would be no slower.
|
|
40
|
+
*/
|
|
41
|
+
export declare const START_TIMEOUT_MS = 10000;
|
|
42
|
+
/**
|
|
43
|
+
* The hash of a file's text, read as UTF-8, with its line endings LF: `sha256Of` of that text.
|
|
44
|
+
* Bytes that are UTF-8 with no CR are that text's own bytes, so they are hashed as they are;
|
|
45
|
+
* any other (a CR, a byte that isn't UTF-8, read as U+FFFD) are decoded first, as a read gives.
|
|
46
|
+
*/
|
|
47
|
+
export declare function textShaOf(bytes: Buffer): string;
|
|
48
|
+
/**
|
|
49
|
+
* Every named file under `dir` (paths with forward slashes), read whole and hashed: its text hash
|
|
50
|
+
* (`textShaOf`), size and time, in the order of `rels`. A file that can't be opened or read fails
|
|
51
|
+
* the call with that error (its `code`: ENOENT for one gone since it was listed). With `raw`, the
|
|
52
|
+
* hash is of the file's bytes as they are (sha256, no line endings made LF): a parse kept by it
|
|
53
|
+
* is of exactly those bytes (record-cache.ts).
|
|
54
|
+
*/
|
|
55
|
+
export declare function hashFilesIn(dir: string, rels: readonly string[], o?: {
|
|
56
|
+
raw?: boolean;
|
|
57
|
+
}): Promise<FileHash[]>;
|
|
58
|
+
/** Every named file's size and time (ms, floored), in the order of `rels`; none for one not there. */
|
|
59
|
+
export declare function statFilesIn(dir: string, rels: readonly string[]): 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
|
@@ -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,6 +60,16 @@ export type ParseOutcome<T> = {
|
|
|
35
60
|
ok: false;
|
|
36
61
|
message: string;
|
|
37
62
|
};
|
|
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
|
+
}
|
|
38
73
|
/** Run `f` over the items, up to `AT_ONCE` at a time, keeping the order. */
|
|
39
74
|
export declare function mapAtOnce<I, O>(items: I[], f: (item: I) => Promise<O>): Promise<O[]>;
|
|
40
75
|
/**
|
|
@@ -59,4 +94,53 @@ export declare function readParsedFiles<T>(o: {
|
|
|
59
94
|
keep?: boolean;
|
|
60
95
|
/** Each file's size and time with its parse (beta.28.1: a write matches them to its own read). */
|
|
61
96
|
withStats?: boolean;
|
|
97
|
+
/**
|
|
98
|
+
* Told what this read keeps under `cacheRoot` (not called when it keeps nothing): a writer that
|
|
99
|
+
* then writes some of the files adds their parses with `keepParses` (beta.28.2).
|
|
100
|
+
*/
|
|
101
|
+
kept?: (k: KeptParses<T>) => void;
|
|
62
102
|
}): Promise<Parsed<T>[]>;
|
|
103
|
+
/** What a read kept of a folder's parses (`readParsedFiles`'s `kept`), for `keepParses`. */
|
|
104
|
+
export interface KeptParses<T> {
|
|
105
|
+
readonly memo: {
|
|
106
|
+
root: string;
|
|
107
|
+
file: string;
|
|
108
|
+
};
|
|
109
|
+
readonly version: string;
|
|
110
|
+
readonly dir: string;
|
|
111
|
+
/** The kept parses by path, as that read left them. */
|
|
112
|
+
readonly entries: ReadonlyMap<string, Entry>;
|
|
113
|
+
/** Only to tie the type to the parse's value. */
|
|
114
|
+
readonly _value?: T;
|
|
115
|
+
}
|
|
116
|
+
/**
|
|
117
|
+
* Add the parses of files a writer wrote since its read (`k`) to what that read kept, and forget
|
|
118
|
+
* the files it removed (beta.28.2: a catalog write rewrites its features and glossary terms,
|
|
119
|
+
* megabytes of YAML, and the next read parsed them again). Each file is kept by the size and time
|
|
120
|
+
* it had as it was written, with the parse of the text the writer wrote there, which is what a
|
|
121
|
+
* read of it would parse; a file whose size or time is another now (changed since), or gone, isn't
|
|
122
|
+
* kept. A file written moments ago is racy (its time is within `RACY_MS` of the write): it is kept
|
|
123
|
+
* with the hash of the bytes written (`writeFileAtomic`'s `stat` gives it, and the clock as the
|
|
124
|
+
* write began), so the next read reuses it only when the file still hashes to them; one with no
|
|
125
|
+
* hash is parsed again by the next read. A cache that can't be written costs the next read its
|
|
126
|
+
* parses.
|
|
127
|
+
*/
|
|
128
|
+
export declare function keepParses<T>(k: KeptParses<T>, o: {
|
|
129
|
+
/**
|
|
130
|
+
* Each file written, with the size and time it had as it was written (`writeFileAtomic`'s
|
|
131
|
+
* `stat`): it is kept only while it still has exactly those, so an edit made since (of the
|
|
132
|
+
* same size too: its time differs, or within the grain its hash does) is parsed by the next
|
|
133
|
+
* read, never served the writer's text. `sha` and `writtenAt` as `writeFileAtomic` gives them.
|
|
134
|
+
*/
|
|
135
|
+
files: readonly {
|
|
136
|
+
rel: string;
|
|
137
|
+
value?: T;
|
|
138
|
+
problem?: string;
|
|
139
|
+
at: FileStat & {
|
|
140
|
+
sha?: string;
|
|
141
|
+
writtenAt?: number;
|
|
142
|
+
};
|
|
143
|
+
}[];
|
|
144
|
+
removed: readonly string[];
|
|
145
|
+
}): Promise<void>;
|
|
146
|
+
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(),
|
package/package.json
CHANGED