@maycombhq/sdk 2.0.0-beta.28.2 → 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.
@@ -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;
@@ -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)[]>;
@@ -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;
@@ -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> {
package/npm/index.js CHANGED
@@ -13647,6 +13647,11 @@ init_common();
13647
13647
  init_kinds();
13648
13648
  init_kept_files();
13649
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
+
13650
13655
  // packages/core/dist/gates-migrate.js
13651
13656
  init_orgpack();
13652
13657
  import { isMap as isMap6, isSeq as isSeq4, parseDocument as parseDocument6 } from "yaml";
@@ -13997,8 +14002,11 @@ var RETITLE_WAIT_MS = 7 * 24 * 60 * 60 * 1e3;
13997
14002
  var DAY = 24 * 60 * 60 * 1e3;
13998
14003
 
13999
14004
  // packages/core/dist/printer.js
14000
- import { AsyncLocalStorage } from "node:async_hooks";
14001
- var printer = new AsyncLocalStorage();
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(" "));
14002
14010
 
14003
14011
  // packages/core/dist/zip-read.js
14004
14012
  var ZIP_LIMITS = {
@@ -14139,11 +14147,6 @@ init_kinds();
14139
14147
  init_spec();
14140
14148
  var SPEC_CACHE_VERSION = `spec@${FLOW_SCHEMA_VERSION}.${SPEC_HEADER_SCHEMA_VERSION}`;
14141
14149
 
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
14150
  // packages/core/dist/assistant-actor.js
14148
14151
  init_ai();
14149
14152
  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.3",
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",