@maycombhq/sdk 2.0.0-beta.28.3 → 2.0.0-beta.28.5

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.
@@ -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;
@@ -0,0 +1,53 @@
1
+ import { type FileHash } from "./file-pool.js";
2
+ /**
3
+ * The text hashes of a folder's files, kept between runs (beta.28.5, the owner's field report of
4
+ * beta.28.4: every build spent 20 to 34 s "reading the catalog's files to check the build" on a
5
+ * Windows laptop with antivirus, 12,832 record files opened and hashed by each command of a run
6
+ * of forty, although none had changed; an open is what such a machine makes slow, a stat is not).
7
+ *
8
+ * Each file's hash (`textShaOf`, what `hashFilesIn` gives) is kept in
9
+ * `<cacheRoot>/.atticus/cache/`, by the file's path, size and modification time, under the rule
10
+ * the kept parses go by (record-cache.ts, ADR 0119 with its addendum, Git's "racily clean"):
11
+ *
12
+ * - a file whose size, time, change time or identity (its inode, NTFS's file id; not compared
13
+ * where the platform reports none) is another than the one its hash was kept by is read
14
+ * and hashed. The change time (ctime) is the system's own record of the last change to the
15
+ * file's bytes or its times, and no program sets it: an edit that puts the file's time back
16
+ * (a copy that keeps times, a restore) still moves it, which size and time alone would miss;
17
+ * - so is a file whose time or change time is within `RACY_MS` of the moment its hash was kept
18
+ * (a same-size edit within the timestamp's grain could keep them), until a later read finds
19
+ * it older;
20
+ * - any other file is not opened: any edit after its hash was kept has a later change time.
21
+ *
22
+ * So a hand edit of a record file is seen as it was before (the build's guards compare these
23
+ * hashes with build.json's), a same-size edit included, and a run with nothing changed costs a
24
+ * stat per file. The cache is derived, local to this machine and never committed; one that can't
25
+ * be read costs the hashes, one that can't be written costs the next run's. A read that names no
26
+ * `cacheRoot` keeps nothing and writes nothing (ADR 0038), and one with `keep: false` (a
27
+ * preview) reads what is kept and writes nothing.
28
+ */
29
+ /**
30
+ * Tests hear how many files each call opened and hashed; with `off`, every file is read and
31
+ * hashed and nothing is kept, as before there were kept hashes (an equivalence test's other side).
32
+ */
33
+ export declare const hashCacheHooks: {
34
+ onHashed?: (files: number) => void;
35
+ off?: boolean;
36
+ };
37
+ /**
38
+ * Every named file under `dir` with its text hash, size and time, in the order of `files`, as
39
+ * `hashFilesIn` gives them: from the hashes kept under `cacheRoot` for the files that haven't
40
+ * changed since, from the files for the rest. A file that can't be opened fails the call, as
41
+ * there (ENOENT for one gone since it was listed).
42
+ */
43
+ export declare function hashFilesKept(o: {
44
+ dir: string;
45
+ /** Relative to `dir`, with forward slashes. */
46
+ files: readonly string[];
47
+ /** The metarepo this run is working in; none: every file is hashed and nothing is kept. */
48
+ cacheRoot?: string;
49
+ /** False: the kept hashes are read and nothing is written (a preview). */
50
+ keep?: boolean;
51
+ /** A job's Stop: ends the read with CancelledError; nothing is kept of a stopped read. */
52
+ signal?: AbortSignal;
53
+ }): Promise<FileHash[]>;
@@ -16,6 +16,7 @@ export * from "./org-notes.js";
16
16
  export * from "./link-evidence.js";
17
17
  export * from "./shared-maps.js";
18
18
  export * from "./contract-check.js";
19
+ export * from "./field-places.js";
19
20
  export * from "./audit.js";
20
21
  export * from "./canary.js";
21
22
  export * from "./stack-helpers.js";
@@ -61,6 +62,7 @@ export * from "./glob.js";
61
62
  export * from "./repo-files.js";
62
63
  export * from "./record-cache.js";
63
64
  export * from "./file-pool.js";
65
+ export * from "./hash-cache.js";
64
66
  export * from "./kept-files.js";
65
67
  export * from "./log.js";
66
68
  export * from "./run-log.js";
@@ -92,4 +94,5 @@ export * from "./link-candidates.js";
92
94
  export * from "./ai-decisions.js";
93
95
  export * from "./decision-batches.js";
94
96
  export * from "./declared-links.js";
97
+ export * from "./declarable-routes.js";
95
98
  export * from "./schema/reading-rules.js";
@@ -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;
@@ -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[];
@@ -334,10 +334,10 @@ export declare const RunSummary: z.ZodObject<{
334
334
  }, z.core.$strict>>;
335
335
  stepClass: z.ZodOptional<z.ZodEnum<{
336
336
  read: "read";
337
+ quick: "quick";
337
338
  draft: "draft";
338
339
  critic: "critic";
339
340
  knowledge: "knowledge";
340
- quick: "quick";
341
341
  }>>;
342
342
  model: z.ZodOptional<z.ZodString>;
343
343
  assistant: z.ZodOptional<z.ZodObject<{
@@ -416,7 +416,7 @@ export declare const readRunSummary: (raw: unknown) => z.ZodSafeParseResult<{
416
416
  } | undefined;
417
417
  meaning?: string | undefined;
418
418
  } | undefined;
419
- stepClass?: "read" | "draft" | "critic" | "knowledge" | "quick" | undefined;
419
+ stepClass?: "read" | "quick" | "draft" | "critic" | "knowledge" | undefined;
420
420
  model?: string | undefined;
421
421
  assistant?: {
422
422
  name: string;
@@ -772,10 +772,10 @@ export type AssistantId = z.infer<typeof AssistantId>;
772
772
  export declare const STEP_CLASSES: readonly ["read", "draft", "critic", "knowledge", "quick"];
773
773
  export declare const StepClass: z.ZodEnum<{
774
774
  read: "read";
775
+ quick: "quick";
775
776
  draft: "draft";
776
777
  critic: "critic";
777
778
  knowledge: "knowledge";
778
- quick: "quick";
779
779
  }>;
780
780
  export type StepClass = z.infer<typeof StepClass>;
781
781
  /**