@maycombhq/sdk 2.0.0-beta.28.2 → 2.0.0-beta.28.4

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 CHANGED
@@ -621,8 +621,35 @@ import { z } from "zod";
621
621
  * when catalog/sources/build.json is there but doesn't read (edited or merged by hand). Its
622
622
  * `command` is the build again with `--discard-edits` of every record file, never the curate.
623
623
  * Additive only.
624
+ * 3.16.0 (beta.28.4, ADR 0198): POST /api/facts/apply-all takes an optional body, `{ repos? }`
625
+ * (FactsApplyAllRequest): only those repos are applied (the map's bar sends the repos whose
626
+ * corrections wait, GET /api/propose's `applyFirst`), in id order whatever order they come in;
627
+ * 400, and no job, when a repo listed has no facts on file. Without `repos` it applies every
628
+ * repo read so far, as before. Its job's result (FactsApplyResult) gains `applied` and
629
+ * `notApplied`, the repos by name. While it runs over several repos its job's `progress` counts
630
+ * them (`done` of `total`: the repos finished). Stop is heard between its repos: a repo's
631
+ * write under way finishes whole, then the job ends `cancelled` with `stopped: true` in its
632
+ * result and the repos never reached under `notApplied`. Additive only.
633
+ * Also in 3.16.0 (beta.28.4, ADR 0199, two field reports on a 40-repo estate): POST
634
+ * /api/setup/repos/plan takes `job: true` for a folder of clones: 202 JobAccepted at once, the
635
+ * job says each folder as it comes to it ("Reading forge-ledger (4 of 40)…") and hears Stop
636
+ * between folders, and its result's `answer` is the ReposPlanView (or `problem`); the refusals
637
+ * the request knows at once (no such folder, several platforms and none chosen) still come as
638
+ * the answer. With or without `job`, a folder's repo a manifest lists already is told by its
639
+ * clone URL and not read (it is in `listed`, as before), and a folder that takes over a minute
640
+ * to read is in `skipped` with that reason. Additive only.
641
+ * Also in 3.16.0 (ADR 0199, "it says it's paired, but I don't see the line"): GET
642
+ * /api/links/candidates says of each `paired` call whether the map draws its arrow to this box
643
+ * (`drawn`), and of the view whether A's corrections are newer than A's last Apply
644
+ * (`applyPending`). A `paired` call also carries who paired it (`pairedBy`), any call with a
645
+ * pairing whether it is the AI's (`pairedAi`), and a pairing whose two ends are in one
646
+ * component that component (`inside`: no arrow is drawn for it). A pairing with a gateway's
647
+ * route the join carries on to the service behind it says so (`joins`, `onward: forwarded`,
648
+ * and on other boxes' rows `pairedWith`), an AI pairing a person's answer outranks says that
649
+ * (`onward: outranked`), and the view says when no catalog is built yet (`noCatalog`).
650
+ * Additive only.
624
651
  */
625
- export declare const API_VERSION = "3.15.0";
652
+ export declare const API_VERSION = "3.16.0";
626
653
  export declare const DEFAULT_PORT = 4321;
627
654
  /** RFC 9457 problem details, used for every error. */
628
655
  /**
@@ -5177,6 +5204,9 @@ export declare const FactsApplyResult: z.ZodObject<{
5177
5204
  }, z.core.$strip>>;
5178
5205
  leftOut: z.ZodOptional<z.ZodNumber>;
5179
5206
  leftOutRepos: z.ZodOptional<z.ZodNumber>;
5207
+ applied: z.ZodOptional<z.ZodArray<z.ZodString>>;
5208
+ notApplied: z.ZodOptional<z.ZodArray<z.ZodString>>;
5209
+ stopped: z.ZodOptional<z.ZodLiteral<true>>;
5180
5210
  next: z.ZodOptional<z.ZodUnknown>;
5181
5211
  }, z.core.$strip>;
5182
5212
  export type FactsApplyResultT = z.infer<typeof FactsApplyResult>;
@@ -10433,6 +10463,15 @@ export declare const FactsApplyRequest: z.ZodObject<{
10433
10463
  discardEdits: z.ZodOptional<z.ZodNumber>;
10434
10464
  plan: z.ZodOptional<z.ZodString>;
10435
10465
  }, z.core.$strict>;
10466
+ /**
10467
+ * 3.16.0 (ADR 0198): POST /api/facts/apply-all's body. `repos`: apply only these repos (the
10468
+ * repos whose corrections wait, as GET /api/propose's `applyFirst` lists them), in id order
10469
+ * whatever order they come in; 400, and no job, when one has no facts on file. Left out: every
10470
+ * repo read so far, as `atticus verify --all --write`.
10471
+ */
10472
+ export declare const FactsApplyAllRequest: z.ZodObject<{
10473
+ repos: z.ZodOptional<z.ZodArray<z.ZodString>>;
10474
+ }, z.core.$strict>;
10436
10475
  export declare const ScanRequest: z.ZodObject<{
10437
10476
  repos: z.ZodOptional<z.ZodArray<z.ZodString>>;
10438
10477
  full: z.ZodDefault<z.ZodBoolean>;
@@ -13703,6 +13742,14 @@ export declare const CandidateCallView: z.ZodObject<{
13703
13742
  }>;
13704
13743
  why: z.ZodOptional<z.ZodString>;
13705
13744
  paired: z.ZodOptional<z.ZodString>;
13745
+ drawn: z.ZodOptional<z.ZodBoolean>;
13746
+ inside: z.ZodOptional<z.ZodString>;
13747
+ pairedAi: z.ZodOptional<z.ZodBoolean>;
13748
+ pairedWith: z.ZodOptional<z.ZodString>;
13749
+ onward: z.ZodOptional<z.ZodEnum<{
13750
+ forwarded: "forwarded";
13751
+ outranked: "outranked";
13752
+ }>>;
13706
13753
  joins: z.ZodOptional<z.ZodString>;
13707
13754
  now: z.ZodOptional<z.ZodString>;
13708
13755
  pairedBy: z.ZodOptional<z.ZodString>;
@@ -13773,6 +13820,14 @@ export declare const LinkCandidatesView: z.ZodObject<{
13773
13820
  }>;
13774
13821
  why: z.ZodOptional<z.ZodString>;
13775
13822
  paired: z.ZodOptional<z.ZodString>;
13823
+ drawn: z.ZodOptional<z.ZodBoolean>;
13824
+ inside: z.ZodOptional<z.ZodString>;
13825
+ pairedAi: z.ZodOptional<z.ZodBoolean>;
13826
+ pairedWith: z.ZodOptional<z.ZodString>;
13827
+ onward: z.ZodOptional<z.ZodEnum<{
13828
+ forwarded: "forwarded";
13829
+ outranked: "outranked";
13830
+ }>>;
13776
13831
  joins: z.ZodOptional<z.ZodString>;
13777
13832
  now: z.ZodOptional<z.ZodString>;
13778
13833
  pairedBy: z.ZodOptional<z.ZodString>;
@@ -13835,6 +13890,8 @@ export declare const LinkCandidatesView: z.ZodObject<{
13835
13890
  question: z.ZodString;
13836
13891
  calls: z.ZodNumber;
13837
13892
  }, z.core.$strip>>;
13893
+ applyPending: z.ZodOptional<z.ZodBoolean>;
13894
+ noCatalog: z.ZodOptional<z.ZodBoolean>;
13838
13895
  }, z.core.$strip>;
13839
13896
  /** ADR 0178 part 2: Copilot matches A's loose calls with B's APIs; a person ticks the proposals. */
13840
13897
  export declare const MatchLinksRequest: z.ZodObject<{
@@ -14357,6 +14414,7 @@ export declare const ReposPlanRequest: z.ZodObject<{
14357
14414
  urls: z.ZodOptional<z.ZodString>;
14358
14415
  dir: z.ZodOptional<z.ZodString>;
14359
14416
  platform: z.ZodOptional<z.ZodString>;
14417
+ job: z.ZodOptional<z.ZodBoolean>;
14360
14418
  }, z.core.$strict>;
14361
14419
  export declare const PlannedRepoView: z.ZodObject<{
14362
14420
  id: z.ZodString;
@@ -10,7 +10,20 @@ export declare function withCommit<T>(commit: () => void, fn: () => Promise<T>):
10
10
  * heard it (it says a late Stop itself); false outside one.
11
11
  */
12
12
  export declare function commitCurrent(): boolean;
13
+ /** Run `fn` with `release` as what `releaseCurrent()` inside it calls. */
14
+ export declare function withRelease<T>(release: () => void, fn: () => Promise<T>): Promise<T>;
15
+ /**
16
+ * Say the write this job started (`commitCurrent`) has ended and nothing is being written: only
17
+ * between two whole writes, never inside one. True when a job heard it; false outside one.
18
+ */
19
+ export declare function releaseCurrent(): boolean;
13
20
  /** The signal of the job this code runs in, if it runs in one. */
14
21
  export declare function currentSignal(): AbortSignal | undefined;
22
+ /**
23
+ * Beta.28.3: the signal a long read may stop on part way (the hash of every file of the
24
+ * catalog): the job's, until its work says it has started writing. From then there is none, so a
25
+ * read that is part of a write is never cut short and nothing is left half written.
26
+ */
27
+ export declare function stoppableSignal(): AbortSignal | undefined;
15
28
  /** Stop here when the job was cancelled. */
16
29
  export declare function throwIfCancelled(): void;
@@ -8,6 +8,11 @@
8
8
  * the order of the paths, whatever the order the workers finish in. Every byte of every file is
9
9
  * read: nothing is taken from a file's size and time. A small folder, or a process where a worker
10
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.
11
16
  */
12
17
  /** A file's size and time (ms, floored), as `stat` gives them. */
13
18
  export interface FileStat {
@@ -32,6 +37,8 @@ export declare const filePoolHooks: {
32
37
  neverReady?: boolean;
33
38
  /** How long the workers have to say they are ready (default `START_TIMEOUT_MS`). */
34
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;
35
42
  };
36
43
  /**
37
44
  * How long the workers have to say they are ready before this thread reads instead (the final
@@ -50,10 +57,17 @@ export declare function textShaOf(bytes: Buffer): string;
50
57
  * (`textShaOf`), size and time, in the order of `rels`. A file that can't be opened or read fails
51
58
  * the call with that error (its `code`: ENOENT for one gone since it was listed). With `raw`, the
52
59
  * 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).
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).
54
62
  */
55
63
  export declare function hashFilesIn(dir: string, rels: readonly string[], o?: {
56
64
  raw?: boolean;
65
+ signal?: AbortSignal;
57
66
  }): 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)[]>;
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)[]>;
@@ -0,0 +1,34 @@
1
+ /**
2
+ * The .gitignore lines and path globs that need no automaton (the field report of
3
+ * 2.0.0-beta.28.3: a folder of clones took hours to read, each file of each clone matched
4
+ * against each of a few hundred .gitignore lines by an automaton that made a set a character).
5
+ * Most lines are a plain name, `*.ext` or `name*`: told by the path's own end or start. Used by
6
+ * `globMatcher` (glob.ts) and by the walker's rules (repo-files.ts); the automaton answers every
7
+ * other glob, and every path with a line end in it.
8
+ */
9
+ /** A glob's text as written: trimmed, \ as /, a leading ./ dropped. */
10
+ export declare function tidy(glob: string): string;
11
+ /**
12
+ * A glob that is told by the path's own text, with no automaton: the whole path (`is`), the
13
+ * path or its end after a `/` (`name`: `node_modules` at any depth), the path's end (`suffix`:
14
+ * `*.class`), or the start of its last name (`prefix`: `npm-debug.log*`). True of paths with no
15
+ * line end in them (`hasLineEnd`), which the automaton's `**` never spans.
16
+ */
17
+ export interface PlainGlob {
18
+ kind: "is" | "name" | "suffix" | "prefix";
19
+ text: string;
20
+ }
21
+ /** Whether a path has a line end in it: such a path is the automaton's, never a plain test's. */
22
+ export declare function hasLineEnd(path: string): boolean;
23
+ /** The plain test a glob comes to, as `globMatcher` reads it; undefined for any other glob. */
24
+ export declare function plainGlob(glob: string, anyDepth?: boolean): PlainGlob | undefined;
25
+ /** The same for a glob `globMatcher` has tidied already (its own text, its depth settled). */
26
+ export declare function plainOf(g: string, anyDepth: boolean): PlainGlob | undefined;
27
+ /** A plain glob's answer for a path with no line end in it. */
28
+ export declare function plainTest(g: PlainGlob, path: string): boolean;
29
+ /**
30
+ * The longest plain text every path a glob matches must hold (`_i.` of `*_i.[ch]`, `gen` of a
31
+ * line for any folder named gen): a path without it is no match, told before the automaton
32
+ * runs. The glob as `globMatcher` tidied it; "" when it has no plain text outside its `{a,b}`.
33
+ */
34
+ export declare function neededText(g: string): string;
@@ -67,6 +67,7 @@ export * from "./run-log.js";
67
67
  export * from "./printer.js";
68
68
  export * from "./zip.js";
69
69
  export * from "./words.js";
70
+ export * from "./initialisms.js";
70
71
  export * from "./zip-read.js";
71
72
  export * from "./tar-read.js";
72
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;
@@ -49,6 +49,36 @@ export interface CandidateCall {
49
49
  why?: string;
50
50
  /** For paired: the API it is paired with. */
51
51
  paired?: string;
52
+ /**
53
+ * For paired (the field report of beta.28.3, "it says it's paired, but I don't see the line"):
54
+ * whether the map draws its arrow to this box. A pairing is a line in the corrections file;
55
+ * the arrow is the catalog's, drawn by the repo's next Apply. Left out when the caller read no
56
+ * catalog (`drawn` and `drawnTo` not given).
57
+ */
58
+ drawn?: boolean;
59
+ /**
60
+ * For paired (ADR 0199, the review): the component both ends of the pairing are in. No arrow
61
+ * is drawn between boxes for it, whatever is applied.
62
+ */
63
+ inside?: string;
64
+ /**
65
+ * ADR 0199, the review: the pairing is the AI's (ADR 0181), not confirmed by a person;
66
+ * `pairedBy` is then the run's own name. Never said of a person's pairing.
67
+ */
68
+ pairedAi?: boolean;
69
+ /**
70
+ * ADR 0199, the second review (M1): the box the pairing `pairedBy` made names, when it is
71
+ * not the box the call goes to (`joins`): a gateway's, whose route forwards the call on.
72
+ */
73
+ pairedWith?: string;
74
+ /**
75
+ * ADR 0199 (M1): why a call with a pairing goes to another box than the pairing's. The
76
+ * estate's join says, never a guess: `forwarded`, the pairing is with a gateway's route and
77
+ * the route's forwarding call reaches `joins` (one link, drawn from the caller to `joins`);
78
+ * `outranked`, the pairing is the AI's and a person's answer names `joins` instead (the join's
79
+ * own rule: a person's word stands over the AI's), so the pairing is not in effect.
80
+ */
81
+ onward?: "forwarded" | "outranked";
52
82
  /**
53
83
  * Beta.28.1: the box the join ties it to now (a repo, or an outside target), for a call that
54
84
  * is joined, undrawn or outside: where it goes, or would go, before it is moved.
@@ -59,6 +89,7 @@ export interface CandidateCall {
59
89
  /**
60
90
  * The review of beta.28.1 (N3): who paired it with the box it goes to now (another box): a
61
91
  * pairing here replaces that person's word, which the panel says before it is written.
92
+ * ADR 0199: also who paired a `paired` call with this box.
62
93
  */
63
94
  pairedBy?: string;
64
95
  suggestion?: {
@@ -149,4 +180,21 @@ export declare function linkCandidates(o: {
149
180
  * canvas is what the person sees, so a drawn call is never listed as loose.
150
181
  */
151
182
  drawnTo?: (call: string) => string | undefined;
183
+ /**
184
+ * ADR 0199, the review (S5): whether the catalog has the join's own Interface (by its id), not
185
+ * only one citing the call's line: the arrow of exactly this call to exactly this entry.
186
+ */
187
+ drawnExact?: (j: FactsJoinResult["joins"][number]) => boolean;
188
+ /**
189
+ * ADR 0199, the review (S5): every box the catalog draws an arrow to from the call's line (two
190
+ * calls on one line each have one). Default: `drawnTo`'s one box.
191
+ */
192
+ drawnBoxes?: (call: string) => readonly string[];
193
+ /**
194
+ * ADR 0199 (M1): the targets a call's answered question names, by call fact id, and of them
195
+ * those the AI answered: with them an AI pairing a person's answer outranks is told by the
196
+ * join's own rule. Left out, no pairing is said to be outranked.
197
+ */
198
+ targets?: Readonly<Record<string, string>>;
199
+ aiTargets?: Readonly<Record<string, unknown>>;
152
200
  }): LinkCandidates;
@@ -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.
@@ -70,8 +70,11 @@ interface Entry {
70
70
  value?: unknown;
71
71
  problem?: string;
72
72
  }
73
- /** Run `f` over the items, up to `AT_ONCE` at a time, keeping the order. */
74
- export declare function mapAtOnce<I, O>(items: I[], f: (item: I) => Promise<O>): Promise<O[]>;
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[]>;
75
78
  /**
76
79
  * Read and parse every named file of a folder, reusing the parses kept from an earlier run for
77
80
  * the files that haven't changed. `name` names the kind of file (`catalog`, `spec`), `version`
@@ -99,6 +102,12 @@ export declare function readParsedFiles<T>(o: {
99
102
  * then writes some of the files adds their parses with `keepParses` (beta.28.2).
100
103
  */
101
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;
102
111
  }): Promise<Parsed<T>[]>;
103
112
  /** What a read kept of a folder's parses (`readParsedFiles`'s `kept`), for `keepParses`. */
104
113
  export interface KeptParses<T> {
@@ -1,4 +1,5 @@
1
1
  import { type GlobMatcher } from "./glob.js";
2
+ import { type PlainGlob } from "./glob-plain.js";
2
3
  /**
3
4
  * A file's bytes as text, the same way for every reader: UTF-16 (LE or BE) when it starts with
4
5
  * that byte-order mark (SQL Server Management Studio saves .sql files so), else UTF-8 with any
@@ -29,6 +30,11 @@ export interface IgnoreRule {
29
30
  re: GlobMatcher;
30
31
  negate: boolean;
31
32
  dirOnly: boolean;
33
+ /**
34
+ * The line as a test of the path's own text, when it is one (`node_modules`, `*.class`): what
35
+ * most lines are, so a large clone's files are told without the automaton. Same answer as `re`.
36
+ */
37
+ plain?: PlainGlob;
32
38
  }
33
39
  /** The rules of one .gitignore file (git's syntax: #, !, a trailing /, a leading or inner /). */
34
40
  export declare function ignoreRules(text: string, base: string): IgnoreRule[];
package/npm/index.js CHANGED
@@ -7232,6 +7232,19 @@ var FactsApplyResult = z31.object({
7232
7232
  leftOut: z31.number().int().positive().optional(),
7233
7233
  /** Apply to every repo's (POST /api/facts/apply-all): how many repos left facts out. */
7234
7234
  leftOutRepos: z31.number().int().positive().optional(),
7235
+ /**
7236
+ * 3.16.0 (ADR 0198), POST /api/facts/apply-all's: the repos it applied (those that wrote with
7237
+ * facts left out too) and the repos it didn't (rejected facts, a refused build, no clone), each
7238
+ * list in id order. Neither when no repo was reached.
7239
+ */
7240
+ applied: z31.array(z31.string()).optional(),
7241
+ notApplied: z31.array(z31.string()).optional(),
7242
+ /**
7243
+ * 3.16.0 (ADR 0198), POST /api/facts/apply-all's: Stop ended the run between two repos (its
7244
+ * job's state is `cancelled`). `applied` are applied whole; `notApplied` includes the repos it
7245
+ * never reached.
7246
+ */
7247
+ stopped: z31.literal(true).optional(),
7235
7248
  next: z31.unknown().optional()
7236
7249
  });
7237
7250
  var CatalogUpgradeView = z31.object({
@@ -8546,6 +8559,9 @@ var FactsApplyRequest = z31.strictObject({
8546
8559
  discardEdits: z31.number().int().min(0).max(1e6).optional(),
8547
8560
  plan: z31.string().regex(/^[0-9a-f]{64}$/).optional()
8548
8561
  });
8562
+ var FactsApplyAllRequest = z31.strictObject({
8563
+ repos: z31.array(z31.string().regex(/^[a-z0-9][a-z0-9._-]{0,99}$/i)).min(1).max(1e4).optional()
8564
+ });
8549
8565
  var ScanRequest = z31.strictObject({
8550
8566
  repos: z31.array(RecordId).optional(),
8551
8567
  /** Ignore the cache and rescan everything. */
@@ -9623,6 +9639,34 @@ var CandidateCallView = z31.object({
9623
9639
  ]),
9624
9640
  why: z31.string().optional(),
9625
9641
  paired: z31.string().optional(),
9642
+ /**
9643
+ * 3.16 (ADR 0199): for `paired`, whether the map draws its arrow to this box: true once the
9644
+ * catalog has it (the repo was applied since the pairing), false while it doesn't.
9645
+ */
9646
+ drawn: z31.boolean().optional(),
9647
+ /**
9648
+ * 3.16 (ADR 0199): for `paired`, the component both ends of the pairing are in: no arrow is
9649
+ * drawn between boxes for it, whatever is applied.
9650
+ */
9651
+ inside: z31.string().optional(),
9652
+ /**
9653
+ * 3.16 (ADR 0199): the pairing `pairedBy` names is the AI's (ADR 0181), not confirmed by a
9654
+ * person. `pairedBy` is given for a `paired` call too.
9655
+ */
9656
+ pairedAi: z31.boolean().optional(),
9657
+ /**
9658
+ * 3.16 (ADR 0199): the box the pairing `pairedBy` made names, when the call goes on from it
9659
+ * to `joins` (a gateway's route that forwards it).
9660
+ */
9661
+ pairedWith: z31.string().optional(),
9662
+ /**
9663
+ * 3.16 (ADR 0199): why a call with a pairing goes to another box (`joins`) than the
9664
+ * pairing's, as the estate's join says: `forwarded`, the pairing is with a gateway's route
9665
+ * whose forwarding call reaches `joins` (one link, drawn from the caller to `joins`; for a
9666
+ * `paired` call `drawn` is of that arrow); `outranked`, the pairing is the AI's and a person's
9667
+ * answer names `joins` instead, so the pairing is not in effect.
9668
+ */
9669
+ onward: z31.enum(["forwarded", "outranked"]).optional(),
9626
9670
  /** 3.14: the box the call goes to now (a repo, or an outside target), before it is moved. */
9627
9671
  joins: z31.string().optional(),
9628
9672
  /** 3.14: for `here`, the API of this box the call goes to now. */
@@ -9661,7 +9705,14 @@ var LinkCandidatesView = z31.object({
9661
9705
  /** No APIs of B on record: why, and how to get them (read the repo, verify it, or intake the spec). */
9662
9706
  noApis: z31.object({ why: z31.enum(["not-read", "unverified", "no-spec"]), command: z31.string() }).optional(),
9663
9707
  /** An open target question of A that one /** answer to B would close, with the calls it covers. */
9664
- rule: z31.object({ question: z31.string(), calls: z31.number().int().min(0) }).optional()
9708
+ rule: z31.object({ question: z31.string(), calls: z31.number().int().min(0) }).optional(),
9709
+ /**
9710
+ * 3.16 (ADR 0199): A's corrections file is newer than A's last Apply (as a proposal's
9711
+ * `applyFirst` tells it): what a person paired or corrected since isn't on the map yet.
9712
+ */
9713
+ applyPending: z31.boolean().optional(),
9714
+ /** 3.16 (ADR 0199): no catalog has been built yet, so the map draws nothing at all. */
9715
+ noCatalog: z31.boolean().optional()
9665
9716
  });
9666
9717
  var MatchLinksRequest = z31.object({ from: z31.string().min(1), to: LinkBox });
9667
9718
  var MatchProposal = z31.object({
@@ -9952,7 +10003,12 @@ var OpenFolderView = z31.object({
9952
10003
  var ReposPlanRequest = z31.strictObject({
9953
10004
  urls: z31.string().max(2e5).optional(),
9954
10005
  dir: z31.string().min(1).max(4096).optional(),
9955
- platform: RecordId.optional()
10006
+ platform: RecordId.optional(),
10007
+ /**
10008
+ * 3.16.0 (ADR 0199): read as a job. 202 JobAccepted at once; the job says each folder as it
10009
+ * comes to it, hears Stop between folders, and its result's `answer` is the ReposPlanView.
10010
+ */
10011
+ job: z31.boolean().optional()
9956
10012
  }).refine((b) => !!b.urls?.trim() !== !!b.dir, "send urls or dir, one of them");
9957
10013
  var PlannedRepoView = z31.object({
9958
10014
  id: z31.string(),
@@ -12384,14 +12440,15 @@ var OPS = {
12384
12440
  "/api/facts/apply-all": {
12385
12441
  post: {
12386
12442
  id: "applyAllFacts",
12387
- summary: "3.5.0 (ADR 0188): run atticus verify --all --write as a local job, as Apply after a declaration or an owner set on the canvas",
12443
+ summary: "3.5.0 (ADR 0188): run atticus verify --all --write as a local job, as Apply after a declaration or an owner set on the canvas; 3.16.0 (ADR 0198): with `repos`, only those repos (the ones whose corrections wait), in id order; 400 when one has no facts on file",
12388
12444
  tag: "workspace",
12445
+ body: FactsApplyAllRequest,
12389
12446
  ok: {
12390
12447
  status: 202,
12391
12448
  schema: "JobAccepted",
12392
- description: "Started: its job's result is FactsApplyResult: the code and the lines verify printed, and (3.14.0) leftOut and leftOutRepos when repos wrote with rejected facts left out (applied, code 0)"
12449
+ description: "Started: its job's result is FactsApplyResult: the code and the lines verify printed, (3.14.0) leftOut and leftOutRepos when repos wrote with rejected facts left out (applied, code 0), and (3.16.0) applied and notApplied, the repos by name"
12393
12450
  },
12394
- errors: [409]
12451
+ errors: [400, 409]
12395
12452
  }
12396
12453
  },
12397
12454
  "/api/estate/join": {
@@ -12487,10 +12544,11 @@ var OPS = {
12487
12544
  "/api/setup/repos/plan": {
12488
12545
  post: {
12489
12546
  id: "planRepos",
12490
- summary: "The repos pasted clone URLs (one a line, up to 500) or a folder of clones (repos discover's own code, a dry run) would add: each normalised URL and the id repo add gives it, a clone URL a manifest lists already left out, a taken id given -2, and a folder's type from its files. A folder with several platforms and none given reads nothing and answers the platforms to choose from (`platforms`, no `platform`). Writes nothing",
12547
+ summary: "The repos pasted clone URLs (one a line, up to 500) or a folder of clones (repos discover's own code, a dry run) would add: each normalised URL and the id repo add gives it, a clone URL a manifest lists already left out, a taken id given -2, and a folder's type from its files. A folder with several platforms and none given reads nothing and answers the platforms to choose from (`platforms`, no `platform`). Writes nothing. 3.16.0 (ADR 0199): a folder's repo a manifest lists already is told by its clone URL and not read (`listed`), a folder that takes over a minute to read is skipped saying so (`skipped`), and with `job: true` the read is a job: 202 JobAccepted at once, a line a folder, Stop heard between folders, the plan in the job's result `answer` (or `problem`)",
12491
12548
  tag: "run",
12492
12549
  body: ReposPlanRequest,
12493
12550
  ok: { status: 200, schema: "ReposPlanView", description: "OK" },
12551
+ alsoOk: { status: 202, schema: "JobAccepted", description: "Started as a job (`job: true`)" },
12494
12552
  errors: [400, 404, 409, 422]
12495
12553
  }
12496
12554
  },
@@ -13647,6 +13705,12 @@ init_common();
13647
13705
  init_kinds();
13648
13706
  init_kept_files();
13649
13707
 
13708
+ // packages/core/dist/cancel.js
13709
+ import { AsyncLocalStorage } from "node:async_hooks";
13710
+ var store = new AsyncLocalStorage();
13711
+ var commits = new AsyncLocalStorage();
13712
+ var releases = new AsyncLocalStorage();
13713
+
13650
13714
  // packages/core/dist/gates-migrate.js
13651
13715
  init_orgpack();
13652
13716
  import { isMap as isMap6, isSeq as isSeq4, parseDocument as parseDocument6 } from "yaml";
@@ -13662,9 +13726,81 @@ import { isMap as isMap8, parseDocument as parseDocument8 } from "yaml";
13662
13726
  // packages/core/dist/runtime-migrate.js
13663
13727
  import { isMap as isMap9, parseDocument as parseDocument9 } from "yaml";
13664
13728
 
13729
+ // packages/core/dist/glob-plain.js
13730
+ var LINE_END = /[\n\r\u2028\u2029]/;
13731
+ function tidy(glob) {
13732
+ return glob.trim().replace(/\\/g, "/").replace(/^\.\//, "");
13733
+ }
13734
+ function hasLineEnd(path) {
13735
+ return LINE_END.test(path);
13736
+ }
13737
+ function plainGlob(glob, anyDepth = !glob.replace(/\/$/, "").includes("/")) {
13738
+ let g = tidy(glob);
13739
+ if (g.startsWith("/")) {
13740
+ g = g.slice(1);
13741
+ anyDepth = false;
13742
+ }
13743
+ return plainOf(g, anyDepth);
13744
+ }
13745
+ function plainOf(g, anyDepth) {
13746
+ const special = /[*?[{]/;
13747
+ if (!special.test(g))
13748
+ return { kind: anyDepth ? "name" : "is", text: g };
13749
+ if (!anyDepth)
13750
+ return void 0;
13751
+ const rest = g.slice(1);
13752
+ if (g.startsWith("*") && rest && !special.test(rest) && !rest.includes("/"))
13753
+ return { kind: "suffix", text: rest };
13754
+ const head = g.slice(0, -1);
13755
+ if (g.endsWith("*") && head && !special.test(head) && !head.includes("/"))
13756
+ return { kind: "prefix", text: head };
13757
+ return void 0;
13758
+ }
13759
+ function plainTest(g, path) {
13760
+ switch (g.kind) {
13761
+ case "is":
13762
+ return path === g.text;
13763
+ case "name":
13764
+ return path === g.text || path.endsWith(g.text) && path.charCodeAt(path.length - g.text.length - 1) === 47;
13765
+ case "suffix":
13766
+ return path.endsWith(g.text);
13767
+ case "prefix":
13768
+ return path.startsWith(g.text, path.lastIndexOf("/") + 1);
13769
+ }
13770
+ }
13771
+ function neededText(g) {
13772
+ let best = "";
13773
+ let run = "";
13774
+ const cut = () => {
13775
+ if (run.length > best.length)
13776
+ best = run;
13777
+ run = "";
13778
+ };
13779
+ for (let i = 0; i < g.length; i++) {
13780
+ const ch = g[i];
13781
+ if (ch === "*") {
13782
+ cut();
13783
+ if (g[i + 1] === "*")
13784
+ i += g[i + 2] === "/" ? 2 : 1;
13785
+ } else if (ch === "?")
13786
+ cut();
13787
+ else if (ch === "[" && g.indexOf("]", i + 2) >= 0) {
13788
+ cut();
13789
+ i = g.indexOf("]", i + 2);
13790
+ } else if (ch === "{" && g.indexOf("}", i) >= 0) {
13791
+ cut();
13792
+ i = g.indexOf("}", i);
13793
+ } else
13794
+ run += ch;
13795
+ }
13796
+ cut();
13797
+ return best;
13798
+ }
13799
+
13665
13800
  // packages/core/dist/glob.js
13666
13801
  var notSlash = (c) => c !== "/";
13667
- var anyChar = (c) => !/[\n\r\u2028\u2029]/.test(c);
13802
+ var anyChar = (c) => c !== "\n" && c !== "\r" && c !== "\u2028" && c !== "\u2029";
13803
+ var REMEMBERED = 4096;
13668
13804
  var Builder = class {
13669
13805
  states = [];
13670
13806
  add(s) {
@@ -13684,9 +13820,6 @@ var Builder = class {
13684
13820
  return this.add({ kind: "split", outs: [this.loop(anyChar, slash), next] });
13685
13821
  }
13686
13822
  };
13687
- function tidy(glob) {
13688
- return glob.trim().replace(/\\/g, "/").replace(/^\.\//, "");
13689
- }
13690
13823
  function compile(b, g, next) {
13691
13824
  const pieces = [];
13692
13825
  for (let i = 0; i < g.length; i++) {
@@ -13750,6 +13883,8 @@ function globMatcher(glob, anyDepth = !glob.replace(/\/$/, "").includes("/")) {
13750
13883
  if (anyDepth)
13751
13884
  start = b.folders(start);
13752
13885
  const states = b.states;
13886
+ const plain = plainOf(g, anyDepth);
13887
+ const needed = neededText(g);
13753
13888
  const close = (set, s) => {
13754
13889
  const stack = [s];
13755
13890
  while (stack.length) {
@@ -13763,23 +13898,57 @@ function globMatcher(glob, anyDepth = !glob.replace(/\/$/, "").includes("/")) {
13763
13898
  stack.push(o);
13764
13899
  }
13765
13900
  };
13901
+ const lives = /* @__PURE__ */ new Map();
13902
+ let remembered = 0;
13903
+ const liveOf = (set) => {
13904
+ const sorted = [...set].sort((x, y) => x - y);
13905
+ const key = sorted.join(",");
13906
+ const had = lives.get(key);
13907
+ if (had)
13908
+ return had;
13909
+ const made = { set: sorted, accepts: set.has(end), next: /* @__PURE__ */ new Map(), ascii: [] };
13910
+ if (lives.size < REMEMBERED)
13911
+ lives.set(key, made);
13912
+ return made;
13913
+ };
13914
+ const first = /* @__PURE__ */ new Set();
13915
+ close(first, start);
13916
+ const begin = liveOf(first);
13917
+ const step = (from, code) => {
13918
+ const had = code < 128 ? from.ascii[code] : from.next.get(code);
13919
+ if (had !== void 0)
13920
+ return had;
13921
+ const c = String.fromCharCode(code);
13922
+ const next = /* @__PURE__ */ new Set();
13923
+ for (const s of from.set) {
13924
+ const st = states[s];
13925
+ if (st.kind === "char" && st.test(c))
13926
+ close(next, st.out);
13927
+ }
13928
+ const to = next.size ? liveOf(next) : null;
13929
+ if (remembered < REMEMBERED) {
13930
+ remembered++;
13931
+ if (code < 128)
13932
+ from.ascii[code] = to;
13933
+ else
13934
+ from.next.set(code, to);
13935
+ }
13936
+ return to;
13937
+ };
13766
13938
  return {
13767
13939
  test(path) {
13768
- let live = /* @__PURE__ */ new Set();
13769
- close(live, start);
13940
+ if (plain && !hasLineEnd(path))
13941
+ return plainTest(plain, path);
13942
+ if (needed && !path.includes(needed))
13943
+ return false;
13944
+ let live = begin;
13770
13945
  for (let i = 0; i < path.length; i++) {
13771
- const c = path[i];
13772
- const next = /* @__PURE__ */ new Set();
13773
- for (const s of live) {
13774
- const st = states[s];
13775
- if (st.kind === "char" && st.test(c))
13776
- close(next, st.out);
13777
- }
13778
- if (!next.size)
13946
+ const to = step(live, path.charCodeAt(i));
13947
+ if (!to)
13779
13948
  return false;
13780
- live = next;
13949
+ live = to;
13781
13950
  }
13782
- return live.has(end);
13951
+ return live.accepts;
13783
13952
  }
13784
13953
  };
13785
13954
  }
@@ -13845,24 +14014,33 @@ function ignoreRules(text3, base) {
13845
14014
  continue;
13846
14015
  const anchored = line.includes("/");
13847
14016
  try {
13848
- out.push({ base, re: globMatcher(line.replace(/^\//, ""), !anchored), negate, dirOnly });
14017
+ const glob = line.replace(/^\//, "");
14018
+ const plain = plainGlob(glob, !anchored);
14019
+ out.push({
14020
+ base,
14021
+ re: globMatcher(glob, !anchored),
14022
+ negate,
14023
+ dirOnly,
14024
+ ...plain ? { plain } : {}
14025
+ });
13849
14026
  } catch {
13850
14027
  }
13851
14028
  }
13852
14029
  return out;
13853
14030
  }
13854
14031
  function ignoredBy(rules, path, isDir) {
13855
- let out = false;
13856
- for (const r of rules) {
14032
+ const plainPath = !hasLineEnd(path);
14033
+ for (let i = rules.length - 1; i >= 0; i--) {
14034
+ const r = rules[i];
13857
14035
  if (r.dirOnly && !isDir)
13858
14036
  continue;
13859
14037
  if (r.base && !path.startsWith(`${r.base}/`))
13860
14038
  continue;
13861
14039
  const rel = r.base ? path.slice(r.base.length + 1) : path;
13862
- if (r.re.test(rel))
13863
- out = !r.negate;
14040
+ if (r.plain && plainPath ? plainTest(r.plain, rel) : r.re.test(rel))
14041
+ return !r.negate;
13864
14042
  }
13865
- return out;
14043
+ return false;
13866
14044
  }
13867
14045
  var byName = (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
13868
14046
  function folder(entries, rel, inherited, gitignore) {
@@ -13997,8 +14175,11 @@ var RETITLE_WAIT_MS = 7 * 24 * 60 * 60 * 1e3;
13997
14175
  var DAY = 24 * 60 * 60 * 1e3;
13998
14176
 
13999
14177
  // packages/core/dist/printer.js
14000
- import { AsyncLocalStorage } from "node:async_hooks";
14001
- var printer = new AsyncLocalStorage();
14178
+ import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
14179
+ var printer = new AsyncLocalStorage2();
14180
+
14181
+ // packages/core/dist/initialisms.js
14182
+ 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(" "));
14002
14183
 
14003
14184
  // packages/core/dist/zip-read.js
14004
14185
  var ZIP_LIMITS = {
@@ -14139,11 +14320,6 @@ init_kinds();
14139
14320
  init_spec();
14140
14321
  var SPEC_CACHE_VERSION = `spec@${FLOW_SCHEMA_VERSION}.${SPEC_HEADER_SCHEMA_VERSION}`;
14141
14322
 
14142
- // packages/core/dist/cancel.js
14143
- import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
14144
- var store = new AsyncLocalStorage2();
14145
- var commits = new AsyncLocalStorage2();
14146
-
14147
14323
  // packages/core/dist/assistant-actor.js
14148
14324
  init_ai();
14149
14325
  init_orgpack();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@maycombhq/sdk",
3
- "version": "2.0.0-beta.28.2",
3
+ "version": "2.0.0-beta.28.4",
4
4
  "description": "Atticus plugin SDK (contract C4): interfaces for extractors, dialects, ingestors and adapters.",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",