@maycombhq/sdk 2.0.0-beta.21 → 2.0.0-beta.23

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.
@@ -33,16 +33,32 @@ export declare function claimOnLines(lines: readonly string[], line: number, cla
33
33
  export declare function normalizeQuote(q: string): string;
34
34
  /** Whether a quote is the line, starts it, or sits inside it, after normalisation. */
35
35
  export declare function quoteMatches(line: string, quote: string | undefined): boolean;
36
+ /** Whether a path names a binary file by its extension (an image, an archive, a font, a build). */
37
+ export declare function isBinaryPath(path: string): boolean;
36
38
  /** A quote is not required from a binary, a notebook, a minified file, or a very long line. */
37
39
  export declare function quoteNotRequired(path: string, line: string): boolean;
38
- /** Paths whose lines are never quoted into a map. */
40
+ /**
41
+ * Paths whose lines are never quoted into a map. Each part is read as NTFS opens it (review round
42
+ * 46): a stream's name after `:` (`.env::$DATA` is `.env`) and trailing dots and spaces dropped.
43
+ */
39
44
  export declare function isSecretPath(path: string): boolean;
40
45
  /**
41
- * Redact a line that carries a secret-looking key with a literal value; a placeholder or a
42
- * reference (`${X}`, `env:X`, `vault:...`) stays, as does a line that names no such key.
43
- * A private-key block is redacted whole.
46
+ * Redact the secrets on a line, keeping what names them: a value after a secret-looking key
47
+ * (at the line's start, whatever the value; anywhere on it, a quoted literal), a setter's
48
+ * literal, a URL's password, a bearer or basic token and well-known token shapes. A
49
+ * placeholder or a reference (`${X}`, `env:X`, `vault:...`) stays, as does code that only names
50
+ * a secret word (`if (password == null)`, `tokenizer.next()`). A private-key block is redacted
51
+ * whole. A key's value is redacted to the end of the line.
44
52
  */
45
53
  export declare function redactSecrets(line: string): string;
54
+ /**
55
+ * Whether a quote redaction left as it is still holds what looks like a secret: an identifier
56
+ * with a secret word and an opaque quoted literal (8 or more characters with letters and digits,
57
+ * no spaces, not a path, URL or placeholder) on the same line, e.g.
58
+ * `creds.put(PASSWORD_KEY, "Xk9fQ2mZ7p")`. Code that only names a secret word
59
+ * (`passwordEncoder.encode(x)`, `getToken("Authorization")`) doesn't.
60
+ */
61
+ export declare function quoteHoldsSecret(quote: string): boolean;
46
62
  /**
47
63
  * Whether a word claim is put together from `cite.with` parts (ADR 0124 addendum A-derived): a
48
64
  * rake task's `namespace:task`, a key a helper prefixes (`${prefix}_conferenceCache`). Each part's
@@ -6,13 +6,19 @@ import type { Fact } from "./schema/facts.js";
6
6
  * that was edited, renamed or deleted is read again. Pure: the diff comes from the git adapter
7
7
  * (`changedFiles` in @maycombhq/workspace), so the same facts and the same diff split the same way.
8
8
  */
9
- /** One file changed between two commits, as `git diff --name-status -M` says it. */
9
+ /** One file changed between two commits, as `git diff --raw -M` says it. */
10
10
  export interface FileChange {
11
11
  status: "added" | "modified" | "deleted" | "renamed" | "copied" | "type-changed";
12
12
  /** The path at the newer commit (a deleted file's path at the older one). */
13
13
  path: string;
14
14
  /** A rename's or copy's path at the older commit. */
15
15
  from?: string;
16
+ /**
17
+ * Review round 49: the path is a submodule's gitlink (mode 160000 at either commit), so the
18
+ * diff names the folder, not the files in it that changed. Every cited file under it is read
19
+ * again.
20
+ */
21
+ gitlink?: boolean;
16
22
  }
17
23
  /** Why a fact must be read again: the first file it cites that changed, and how. */
18
24
  export interface StaleCite {
@@ -24,7 +30,7 @@ export interface StaleCite {
24
30
  }
25
31
  /**
26
32
  * The files a fact rests on: its cite and the cite's `with` parts, an entry's `authCite` (ADR
27
- * 0124 addendum A-read), and for a flow every step's and error path's cite and parts. Unique and
33
+ * 0124 addendum A-read) and a call's `authCite` and `tlsCite` (ADR 0163), with their parts, and for a flow every step's and error path's cite and parts. Unique and
28
34
  * sorted, except that a fact's own cited file comes first for a non-flow fact.
29
35
  */
30
36
  export declare function citedFiles(f: Fact): string[];
@@ -41,6 +41,14 @@ import type { Fact, FactOf } from "./schema/facts.js";
41
41
  * gateway-walk): without it a call is joined to the route it lands on, and each route's
42
42
  * forwarding call to its service on its own, so the chain is there in two links, not one.
43
43
  *
44
+ * The path suffix (an Apigee proxy to its service): a forwarding call cited in a bundle whose
45
+ * path no entry serves in the same shape is joined per route of its proxy (the route it is from,
46
+ * else the proxy's flows, else its `<BasePath>/**`) at the target's path with the route's suffix
47
+ * after it (none when `target.copy.pathsuffix` is false; everything under it for a pass-through),
48
+ * matched against the service's entries with its base path taken off: the manifest's, an
49
+ * exposure's, its context and servlet path settings, else the longest overlap, a guess
50
+ * (`joined-by-path-overlap`). Each such join cites the route (`forRoute`) and the base (`base`).
51
+ *
44
52
  * Placeholders (J0): a base URL, host or topic written as `${X}`, `${X:default}` or `env:X` is
45
53
  * each value the config facts setting `X` give it, read in the caller's repo and in any repo of
46
54
  * the estate whose setting is for the caller's component (its folder, its deployment, its
@@ -115,6 +123,27 @@ export interface GatewayHop {
115
123
  scopes?: string[];
116
124
  /** Which side this gateway faces, when the manifest or the proxy's virtual host says. */
117
125
  facing?: GatewayFacing;
126
+ /** The base path the service behind this hop serves under, as `FactJoin.base`. */
127
+ base?: JoinBase;
128
+ }
129
+ /**
130
+ * The base path a service's entries sit under that the join took off the path an Apigee proxy
131
+ * forwards before matching them (the path suffix): the manifest's `basePath`, an exposure's
132
+ * (`deploy`: an OpenShift Route's or an Ingress's path), the service's own context path and
133
+ * servlet path settings (`config`), or, with none of those, the longest run of the target's path
134
+ * that starts the entry's (`overlap`, a guess: `joined-by-path-overlap`). `by` is the facts it
135
+ * came from (none for the manifest or an overlap).
136
+ */
137
+ export interface JoinBase {
138
+ path: string;
139
+ /**
140
+ * `url`: nothing names the base, and one route's whole URL (the target's path and the flow's
141
+ * suffix) ends in exactly one entry's whole path, at least one of the target's own segments
142
+ * included: code at both ends, not a guess. `overlap` is that for a pass-through (every entry
143
+ * under a guessed base), a guess.
144
+ */
145
+ from: "manifest" | "deploy" | "config" | "url" | "overlap";
146
+ by?: FactEnd[];
118
147
  }
119
148
  /** One end of a join: a fact, its repo and component, and the line it cites. */
120
149
  export interface FactEnd {
@@ -197,6 +226,16 @@ export declare const JOINED_DESPITE_CONFLICT = "joined-despite-conflict";
197
226
  export declare const JOINED_BY_SERVICE_NAME = "joined-by-service-name";
198
227
  /** G1 (ADR 0174): a person paired the call with this entry on the canvas. */
199
228
  export declare const JOINED_BY_PERSON = "joined-by-person";
229
+ /**
230
+ * An Apigee proxy's forwarding call matched the service's entry only by taking off the front of
231
+ * the target's path that nothing names as the service's base path (no manifest `basePath`, no
232
+ * Route or Ingress path, no context path setting): `/forge-limits/v3/limits` and the suffix
233
+ * `/check` against `/limits/check`. A guess, so the link is inferred; the Interface's flag only,
234
+ * not one of `JOIN_GUESS_FLAGS` (the local API's guesses), and its how is the host's.
235
+ */
236
+ export declare const JOINED_BY_PATH_OVERLAP = "joined-by-path-overlap";
237
+ /** How many entries a `<BasePath>/**` pass-through links to at most, in path order. */
238
+ export declare const MAX_PASS_THROUGH_LINKS = 50;
200
239
  /**
201
240
  * ADR 0181: the AI decided the link (a pairing, or a target answer), applied by Atticus from its
202
241
  * run without a person. A how, never a person's word: the Interface is inferred, its evidence is
@@ -304,6 +343,20 @@ export interface FactJoin {
304
343
  aiHop?: JoinAi & {
305
344
  call: FactEnd;
306
345
  };
346
+ /**
347
+ * An Apigee proxy's forwarding call (the path suffix): the proxy's route whose requests it
348
+ * carries, when the path the target receives is the target's path and this route's suffix (or,
349
+ * for a `<BasePath>/**` pass-through, everything under the target's path). A call that serves
350
+ * several routes has a join per route.
351
+ */
352
+ forRoute?: FactEnd;
353
+ /** The service's base path the join took off before matching its entry (the path suffix). */
354
+ base?: JoinBase;
355
+ /**
356
+ * The setting that keeps the proxy's path suffix off (`target.copy.pathsuffix` false, in a
357
+ * JavaScript or AssignMessage policy), so the target receives its own path as it is.
358
+ */
359
+ suffixOff?: FactEnd;
307
360
  }
308
361
  /** ADR 0181: the AI run a decision came from. */
309
362
  export interface JoinAi {
@@ -435,6 +488,11 @@ export interface PersonPair {
435
488
  by: string;
436
489
  /** ADR 0181: the pairing is the AI's, with its run; joined `joined-by-ai`. */
437
490
  ai?: JoinAi;
491
+ /**
492
+ * Review round 48: a person said the call reaches none (their `unlink` is the newest): no
493
+ * pairing, and an AI answer naming a target doesn't join it (a person's answer still does).
494
+ */
495
+ none?: boolean;
438
496
  }
439
497
  export interface JoinFactsInput {
440
498
  repos: readonly JoinRepo[];
@@ -542,8 +600,23 @@ export declare function basePathOf(e: Entry): string;
542
600
  * by a Service's short name (J1). Empty for a join nobody had to guess.
543
601
  */
544
602
  export declare function joinGuessesOf(j: Pick<FactJoin, "inferred" | "byLabel" | "guesses">): JoinGuessFlag[];
603
+ /**
604
+ * Whether an Apigee forwarding call on the way matched its entry only by a guessed base path
605
+ * (`joined-by-path-overlap`): the join's own, or a gateway hop's.
606
+ */
607
+ export declare const isOverlapJoin: (j: {
608
+ base?: JoinBase | undefined;
609
+ gateway?: readonly {
610
+ base?: JoinBase | undefined;
611
+ }[] | undefined;
612
+ }) => boolean;
545
613
  /** Whether a join guessed its callee anywhere on the way (`joinGuessesOf` gives how). */
546
- export declare const isGuessedJoin: (j: Pick<FactJoin, "inferred" | "byLabel" | "guesses">) => boolean;
614
+ export declare const isGuessedJoin: (j: Pick<FactJoin, "inferred" | "byLabel" | "guesses"> & {
615
+ base?: JoinBase | undefined;
616
+ gateway?: readonly {
617
+ base?: JoinBase | undefined;
618
+ }[] | undefined;
619
+ }) => boolean;
547
620
  /**
548
621
  * How a join found its callee, as its Interface's flags (C1, ADR 0135): a guess by its own F2
549
622
  * flags alone (`JOIN_GUESS_FLAGS`: by path or label, F2; by a platform setting or a folder name,
@@ -557,6 +630,10 @@ export declare const aiOfJoin: (j: Pick<FactJoin, "how" | "paired"> & {
557
630
  export declare function joinFlagsOf(j: Pick<FactJoin, "how" | "inferred" | "byLabel" | "guesses" | "paired"> & {
558
631
  aiAnswer?: JoinAi | undefined;
559
632
  aiHop?: JoinAi | undefined;
633
+ base?: JoinBase | undefined;
634
+ gateway?: readonly {
635
+ base?: JoinBase | undefined;
636
+ }[] | undefined;
560
637
  }): string[];
561
638
  /**
562
639
  * A shared link's flags (ADR 0135, section 5): each once, the union of its joins'. A verified link
package/npm/core/fs.d.ts CHANGED
@@ -51,6 +51,31 @@ o?: {
51
51
  release: () => Promise<void>;
52
52
  interrupted?: LockInfo;
53
53
  }>;
54
+ /** The lock file beside a file two processes write (`<file>.lock`): no facts-folder reader takes it for a file of its own. */
55
+ export declare const sharedLockFileOf: (path: string) => string;
56
+ /**
57
+ * Review of beta.23: the options of a lock that guards only a quick write (a stage's loop file,
58
+ * its thread, the stories' numbers): older than two minutes, it is stale whoever holds it.
59
+ */
60
+ export declare const QUICK_WRITE_LOCK: {
61
+ readonly maxAgeMs: 120000;
62
+ };
63
+ /**
64
+ * Review round 46: run `work` holding a file that another process may append to or rewrite at
65
+ * the same time (a repo's corrections: the app server appends, a CLI command rewrites it), so a
66
+ * read, change and write never loses what the other wrote meanwhile. In this process the writers
67
+ * of one file queue; between processes `<file>.lock` is created with `wx` (which fails when it is
68
+ * there), retried with a short backoff. A lock whose process is gone, or older than `staleMs`, is
69
+ * taken over; after `waitMs` it gives up with LockHeldError naming the holder. No `flock`, so it
70
+ * works the same on Windows, where a lock file being deleted can refuse for a moment (EPERM,
71
+ * EBUSY): those are retried.
72
+ */
73
+ export declare function withSharedFileLock<T>(path: string, work: () => Promise<T>, o?: {
74
+ staleMs?: number;
75
+ waitMs?: number;
76
+ what?: string;
77
+ maxAgeMs?: number;
78
+ }): Promise<T>;
54
79
  /**
55
80
  * What stays on this machine inside .atticus/: the person's settings, the log, locks, upgrade
56
81
  * backups, the prompt and response history (ADR 0110), what `atticus probe` measured of the
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Path globs for the code tools (grep `paths`, files, and every .gitignore line of a scanned
3
+ * repo), matched in linear time. A glob is compiled to a small automaton and run over the path
4
+ * one character at a time with a set of live states, so no glob, however its `*`s are laid out,
5
+ * can backtrack: these run on the main thread with no time limit (final review, 2.0.0-beta.21).
6
+ */
7
+ export interface GlobMatcher {
8
+ test(path: string): boolean;
9
+ }
10
+ /**
11
+ * A glob as a matcher over a repo-relative path. A glob with no / matches a name at any depth;
12
+ * a leading / anchors it at the top.
13
+ */
14
+ export declare function globMatcher(glob: string, anyDepth?: boolean): GlobMatcher;
@@ -8,6 +8,21 @@
8
8
  * - topics (no leading slash in the input and no "/" at all) are returned trimmed
9
9
  */
10
10
  export declare function normalizePath(input: string): string;
11
+ /**
12
+ * A path with each `{...}` parameter cut to its name: what follows the first `:`, `?` or `=` in
13
+ * braces nested inside a constraint (`{code:regex(^\\d{3}$)}`) are matched, not cut at the first `}`.
14
+ * braces nested inside a constraint (`{code:regex(^\\d{{3}}$)}`) are matched, not cut at the first `}`.
15
+ * An unclosed `{` leaves the rest as written.
16
+ */
17
+ export declare function stripParamConstraints(path: string): string;
18
+ /** Code-unit string order, the same in every locale (`localeCompare` is not: ICU orders `_`/`-`
19
+ * and, in `da`, `aa` differently), for every sort that feeds records, ids, hashes or a merge. */
20
+ export declare function cmpText(a: string, b: string): number;
21
+ /**
22
+ * `cmpText`, but a run of digits is compared as a number (`a.ts:9` before `a.ts:10`): what
23
+ * `localeCompare(b, "en", { numeric: true })` was used for, without ICU.
24
+ */
25
+ export declare function cmpNatural(a: string, b: string): number;
11
26
  /**
12
27
  * Stable interface id: a hash of caller, callee, method and normalised path, so the same
13
28
  * edge seen by several extractors merges into one Interface record.
@@ -15,3 +30,16 @@ export declare function normalizePath(input: string): string;
15
30
  export declare function interfaceId(from: string, to: string, method: string | undefined, path: string): string;
16
31
  /** Lowercase slug suitable as a record id, built from free text such as a system name. */
17
32
  export declare function slugify(text: string): string;
33
+ /**
34
+ * Round 47: a name with no Latin letter or digit in it (`注文`, `Заказы`, `...`) slugs to
35
+ * nothing, so every such name used to become the same `unnamed` and their records merged.
36
+ * It gets `unnamed-<short hash of the name>` instead: stable, and different per name. Blank
37
+ * text stays `unnamed`.
38
+ */
39
+ export declare function unnamedId(text: string): string;
40
+ /**
41
+ * A slug that is never a Windows device name (review round 46): a record is the file
42
+ * `<kind>/<id>.yaml` and Windows can't create `aux.yaml`, so the slug's first dot-separated part,
43
+ * when it is one, gets `-1` (`aux` is `aux-1`, `con.v2` is `con-1.v2`). C1's RecordId is unchanged.
44
+ */
45
+ export declare function notDeviceName(slug: string): string;
@@ -55,8 +55,13 @@ export * from "./roles-migrate.js";
55
55
  export * from "./profile-migrate.js";
56
56
  export * from "./metarepo.js";
57
57
  export * from "./fs.js";
58
+ export * from "./glob.js";
59
+ export * from "./repo-files.js";
58
60
  export * from "./record-cache.js";
61
+ export * from "./kept-files.js";
59
62
  export * from "./log.js";
63
+ export * from "./run-log.js";
64
+ export * from "./printer.js";
60
65
  export * from "./zip.js";
61
66
  export * from "./words.js";
62
67
  export * from "./zip-read.js";
@@ -73,6 +78,7 @@ export * from "./question-roles.js";
73
78
  export * from "./question-proposals.js";
74
79
  export * from "./repo-description.js";
75
80
  export * from "./manifest-edit.js";
81
+ export * from "./setup-edit.js";
76
82
  export * from "./schema/spec.js";
77
83
  export * from "./specs.js";
78
84
  export * from "./cancel.js";
@@ -0,0 +1,17 @@
1
+ /** While `isQuiet()` says so, files checked since the last change aren't checked again; none to stop. */
2
+ export declare function trustKeptFiles(isQuiet?: () => boolean): void;
3
+ /**
4
+ * A file may have changed: each kept file is checked again when next asked; with `path` (a
5
+ * file or a folder), only those at or under it.
6
+ */
7
+ export declare function keptFilesMayHaveChanged(path?: string): void;
8
+ /**
9
+ * What `parse` makes of the file's text, from the last read while the file is unchanged.
10
+ * Undefined when there is no such file. A parse that throws is not kept: the error goes to the
11
+ * caller, as a fresh read's would.
12
+ */
13
+ export declare function keptParse<T>(path: string, kind: string, parse: (text: string) => T, o?: {
14
+ copy?: boolean;
15
+ }): Promise<T | undefined>;
16
+ /** For tests: forget every file kept. */
17
+ export declare function forgetKeptFiles(): void;
@@ -6,3 +6,5 @@
6
6
  */
7
7
  export { SCHEMA_VERSION } from "./schema/version.js";
8
8
  export { createLog, logFileOf, NO_LOG, type Log, type LogEntry, type LogLevel } from "./log.js";
9
+ export { recordedCommand, startTerminalRun, type TerminalRunRecorder } from "./run-log.js";
10
+ export { printToCurrent, withPrinter } from "./printer.js";
package/npm/core/log.d.ts CHANGED
@@ -45,5 +45,7 @@ export declare function createLog(root: string, o?: {
45
45
  maxBytes?: number;
46
46
  keep?: number;
47
47
  }): Log;
48
+ /** ensureLocalIgnore, for the log's synchronous writes (and a terminal run's, ADR 0187). */
49
+ export declare function ignoreLocalSync(root: string): void;
48
50
  /** A log that writes nothing (tests, and commands run with no metarepo). */
49
51
  export declare const NO_LOG: Log;
@@ -28,7 +28,9 @@ export declare function setManifestDescription(root: string, repo: string, descr
28
28
  * are in. The entry is written with the fields that are set and no more, and the whole manifest
29
29
  * is checked before it is written, so a duplicate id or a password in the URL is refused here.
30
30
  */
31
- export declare function addManifestRepo(root: string, platform: string, entry: {
31
+ export declare function addManifestRepo(root: string, platform: string, entry: NewManifestRepo): Promise<ManifestFile>;
32
+ /** One repo to add to a manifest: the fields that are set, and no more. */
33
+ export interface NewManifestRepo {
32
34
  id: string;
33
35
  url: string;
34
36
  type: string;
@@ -38,7 +40,21 @@ export declare function addManifestRepo(root: string, platform: string, entry: {
38
40
  system?: string;
39
41
  component?: string;
40
42
  description?: RepoDescription;
41
- }): Promise<ManifestFile>;
43
+ }
44
+ /**
45
+ * ADR 0190: many repos into a platform's manifest at once (the app's paste of ~40 clone URLs),
46
+ * as addManifestRepo adds one: appended in order, comments and order kept, the file's own line
47
+ * endings, the whole manifest checked before anything is written. An id another manifest (or
48
+ * an earlier entry of the batch) lists is refused, naming it. With `preview`, nothing is
49
+ * written: the lines it would change come back, for the app's diff before the write.
50
+ */
51
+ export declare function addManifestRepos(root: string, platform: string, entries: readonly NewManifestRepo[], o?: {
52
+ preview?: boolean;
53
+ }): Promise<{
54
+ file: ManifestFile;
55
+ changes: LineChange[];
56
+ written: boolean;
57
+ }>;
42
58
  /**
43
59
  * F5: move a repo's id in the manifest that lists it, in place (comments and order kept). Refused
44
60
  * when no manifest lists the repo, or any lists the new id already (ids are unique across every
@@ -74,7 +90,9 @@ export declare function changedLines(before: string, after: string): LineChange[
74
90
  * file's comments and order; checked before it is written. With `preview`, nothing is written:
75
91
  * the lines it would change come back.
76
92
  */
77
- export declare function setManifestField(root: string, repo: string, field: "owner" | "system", value: string, o?: {
93
+ export declare function setManifestField(root: string, repo: string,
94
+ /** ADR 0190: `type` too, from the app's Detect the type (atticus repo-type detect). */
95
+ field: "owner" | "system" | "type", value: string, o?: {
78
96
  preview?: boolean;
79
97
  }): Promise<{
80
98
  file: ManifestFile;
@@ -88,6 +88,14 @@ export declare function layoutOf(root: string): {
88
88
  };
89
89
  /** The catalog folder (holding generated/ and curated/). */
90
90
  export declare function catalogDirOf(root: string): string;
91
+ /**
92
+ * Whether a changed file (root-relative, "/"-separated, as the server's live events name it) can
93
+ * change the catalog: a file in the catalog folder the layout names, that folder or one above it
94
+ * (the watcher names top folders when many files change), or the org pack, whose sources.yaml
95
+ * says where the catalog is. The server reads the catalog again only then, and tags each
96
+ * `file.changed` event with it (`catalog`), so a page follows the layout too.
97
+ */
98
+ export declare function catalogMayHaveChangedAt(root: string, path: string): boolean;
91
99
  /**
92
100
  * Where OpenSpec keeps changes, relative to the root with forward slashes: `changes/` under
93
101
  * `layout.openspec` (`openspec/changes` by default, `.atticus/openspec/changes` in a repo
@@ -30,11 +30,12 @@ export declare const DEFAULT_GATES: {
30
30
  }[];
31
31
  };
32
32
  export declare const DEFAULT_ROLES: {
33
- schemaVersion: 1 | 2;
33
+ schemaVersion: 1 | 2 | 3;
34
34
  teams: {
35
35
  id: string;
36
36
  people: string[];
37
37
  name?: string | undefined;
38
+ roles?: Record<string, string[]> | undefined;
38
39
  }[];
39
40
  custom: {
40
41
  id: string;
@@ -55,6 +56,7 @@ export declare const DEFAULT_ROLES: {
55
56
  actions: [string, string];
56
57
  reason: string;
57
58
  }[];
59
+ defaults?: Record<string, string[]> | undefined;
58
60
  };
59
61
  export declare const DEFAULT_RUNTIME: {
60
62
  schemaVersion: 1 | 2 | 3 | 4;
@@ -0,0 +1,4 @@
1
+ /** Run `work` with every line printed inside it (at any depth, across awaits) going to `print`. */
2
+ export declare function withPrinter<T>(print: (line: string) => void, work: () => T): T;
3
+ /** Print a line to the job this code runs in, if any. */
4
+ export declare function printToCurrent(line: string): void;
@@ -17,8 +17,12 @@ export type QuestionOwner = {
17
17
  /** The teams roles.yaml names, and why they couldn't be read when they couldn't. */
18
18
  export declare function readTeams(root: string): Promise<{
19
19
  teams: Team[];
20
+ /** Version 3 (ADR 0191): the organisation's person for each role, when no team names one. */
21
+ defaults?: Record<string, string[]>;
20
22
  problem?: string;
21
23
  }>;
24
+ /** A handle as compared: no leading @, lower case (Git hosts' handles are case-insensitive). */
25
+ export declare const handleKey: (h: string) => string;
22
26
  /** The teams a person is on, by their Git handle. */
23
27
  export declare function teamsOfPerson(handle: string, teams: readonly Team[]): Team[];
24
28
  /**
@@ -1,15 +1,74 @@
1
1
  import { BUILT_IN_ROLES } from "./schema/orgpack.js";
2
- import { type Question, type QuestionRole } from "./schema/question.js";
2
+ import { type Question, type QuestionAsks, type QuestionRole } from "./schema/question.js";
3
3
  /**
4
4
  * The role that owns what a step asks: the stage's own for a change's stage (`change-feature`,
5
5
  * `change-stories`, a task's run), else, for a step that serves every stage (a context gap, a
6
6
  * knowledge conflict), the stage its rerun command names. Undefined outside a change's phases.
7
7
  */
8
8
  export declare function roleOfStep(step: string, rerun?: string): QuestionRole | undefined;
9
- /** A question's role: its own (version 5), else derived from the step that asked and its rerun. */
10
- export declare function roleOfQuestion(q: Pick<Question, "askedBy" | "rerun"> & {
9
+ /**
10
+ * ADR 0191: the role that owns what a question asks. Design is the architect's and delivery the
11
+ * tech lead's, whichever stage asked. Business is the product owner's, or the business analyst's
12
+ * once the stories are being written (a question the stories or tasks stage raises about what the
13
+ * change must do is the analyst's to answer at that level).
14
+ */
15
+ export declare function roleOfAsks(asks: QuestionAsks, stageRole?: QuestionRole): QuestionRole;
16
+ /** ADR 0191: what a role's questions ask, for a question that has no `asks` of its own. */
17
+ export declare function asksOfRole(role: QuestionRole): QuestionAsks;
18
+ type RoutedQuestion = Pick<Question, "askedBy" | "rerun"> & {
11
19
  role?: QuestionRole | undefined;
12
- }): QuestionRole | undefined;
20
+ asks?: QuestionAsks | undefined;
21
+ };
22
+ /**
23
+ * A question's role: a person's re-routing or the one it was raised with (versions 5 and 6), else
24
+ * what it asks (version 6), else derived from the step that asked and its rerun.
25
+ */
26
+ export declare function roleOfQuestion(q: RoutedQuestion): QuestionRole | undefined;
27
+ /** What a question asks: its own tag (version 6), else its role's level; undefined with neither. */
28
+ export declare function asksOfQuestion(q: RoutedQuestion): QuestionAsks | undefined;
29
+ /**
30
+ * ADR 0191: what a critic finding asks of people, by the same three levels, so a product owner's
31
+ * Home shows only the business ones (the audit: running the critic from the brief made findings
32
+ * about circuit breakers and alerts, and Home showed the product owner a change blocked by them).
33
+ * A finding on the design's files is design; on tasks.md, the build or the release, delivery; one
34
+ * on the brief, the proposal, the UX or the stories is business unless its rule, lens or words are
35
+ * about how the estate does it (resilience, timeouts, alerts, interfaces). On the brief, only the
36
+ * architecture lens or words no business sentence uses (a timeout, a retry, a circuit breaker)
37
+ * make it design: an alert, a queue or an interface there may be the business's own.
38
+ */
39
+ export declare function asksOfFinding(f: {
40
+ artifact: string;
41
+ rule?: string | undefined;
42
+ lens?: string | undefined;
43
+ summary?: string | undefined;
44
+ }): QuestionAsks;
45
+ /**
46
+ * ADR 0191: the levels a change's phase is decided at. In Define only the business level holds
47
+ * the change (a design finding waits for the architect); in Design, business and design; from
48
+ * Plan on, all three.
49
+ */
50
+ export declare function asksOfPhase(state: string): QuestionAsks[];
51
+ /** The change.yaml owner key of each phase's role, in the order a change goes. */
52
+ export declare const OWNER_OF_ROLE: Readonly<Record<QuestionRole, string>>;
53
+ /**
54
+ * ADR 0191: whose turn a phase's hand-off is: the next role's owner key (define → the architect,
55
+ * design → the business analyst, plan → the tech lead), so the hand-off names its
56
+ * reviewers and At a glance says who it waits on.
57
+ */
58
+ export declare function nextOwnerOf(phase: string): string | undefined;
59
+ /** The people a phase's hand-off waits on: the next role's owners on the change (handles, no @). */
60
+ export declare function nextOwnersOf(phase: string, owners: Readonly<Record<string, readonly string[]>>, custom?: readonly CustomRole[]): {
61
+ role: string;
62
+ people: string[];
63
+ } | undefined;
64
+ /**
65
+ * ADR 0191 review: the people a built-in owner key names on a change, its keys read as
66
+ * rolesOfPerson reads them: any case, the words people write for it (`tech-lead`, `developer`
67
+ * and `delivery-lead` for the team lead), or a custom role of roles.yaml based on it, the key
68
+ * itself first. Another built-in role (a security reviewer beside the architect) is its own.
69
+ * Handles, no @, once each as handles compare; a team (`forge/platform`) is not a person.
70
+ */
71
+ export declare function ownersOfRole(key: string, owners: Readonly<Record<string, readonly string[]>>, custom?: readonly CustomRole[]): string[];
13
72
  /** A custom role of roles.yaml (`custom`): its id and the built-in role it is based on. */
14
73
  export interface CustomRole {
15
74
  id: string;
@@ -22,3 +81,4 @@ export declare function roleOfOwner(key: string, custom?: readonly CustomRole[])
22
81
  * question role, once each, in the order of the phases.
23
82
  */
24
83
  export declare function rolesOfPerson(handle: string, owners: Readonly<Record<string, readonly string[]>>, custom?: readonly CustomRole[]): QuestionRole[];
84
+ export {};
@@ -1,5 +1,5 @@
1
1
  import { type JudgmentStore } from "./judgments.js";
2
- import { Question, type AiBy, type AppliedRule, type QuestionDraft, type QuestionScopeLevel, type QuestionState } from "./schema/question.js";
2
+ import { Question, type AiBy, type AppliedRule, type QuestionDraft, type QuestionRole, type QuestionScopeLevel, type QuestionState } from "./schema/question.js";
3
3
  /**
4
4
  * Questions as files (ADR 0078): raise, list, read and answer questions/<id>.yaml. The CLI
5
5
  * (atticus questions) and the local API (/api/questions) both call these, so the app and the
@@ -47,6 +47,17 @@ export interface AskedBy {
47
47
  }
48
48
  /** An open question from what an AI step raised. */
49
49
  export declare function questionFromDraft(d: QuestionDraft, by: AskedBy): Question;
50
+ /**
51
+ * ADR 0191: a person re-routes a question to another role (a business question the architect was
52
+ * given goes to the product owner). `role` becomes the new one and `routed` says from which, by
53
+ * whom and when; what it asks follows the role unless the AI tagged it. Open or answered alike:
54
+ * the answer, if any, stays. Written only if the file is as it was read.
55
+ */
56
+ export declare function routeQuestion(root: string, id: string, o: {
57
+ role: QuestionRole;
58
+ by: string;
59
+ at: string;
60
+ }): Promise<Question>;
50
61
  /**
51
62
  * Write a question as it is (a person's comment on a critic finding, ADR 0124 addendum D-app,
52
63
  * is a question they answered as they asked it). Every other writer goes through
@@ -227,12 +238,17 @@ export declare function raiseQuestions(root: string, drafts: QuestionDraft[], by
227
238
  }>;
228
239
  /**
229
240
  * Rewrite questions/<id>.yaml files written at an older question schema version (1, ADR 0078;
230
- * 2, ADR 0117) at the current one (3, ADR 0153): only the version changes, since what each
231
- * version adds is optional. Returns the files, relative to the root; with dryRun, the files it
241
+ * 2, ADR 0117; 3, ADR 0153; 4, ADR 0162; 5, ADR 0181) at the current one (6, ADR 0191): only the
242
+ * version changes, since what each version adds is optional. Returns the files, relative to the root; with dryRun, the files it
232
243
  * would rewrite.
233
244
  */
234
245
  export declare function migrateQuestions(root: string, o?: {
235
246
  dryRun?: boolean;
247
+ /** Round 49: the files left as they are, with why (a file not named by its question's id). */
248
+ problems?: {
249
+ file: string;
250
+ message: string;
251
+ }[];
236
252
  }): Promise<string[]>;
237
253
  /** What a step says of a question it reused: who asked it first, and that it waits on it. */
238
254
  export declare const reusedLine: (q: Question) => string;
@@ -0,0 +1,60 @@
1
+ import { type GlobMatcher } from "./glob.js";
2
+ /**
3
+ * A file's bytes as text, the same way for every reader: UTF-16 (LE or BE) when it starts with
4
+ * that byte-order mark (SQL Server Management Studio saves .sql files so), else UTF-8 with any
5
+ * byte-order mark dropped, else, when the bytes aren't valid UTF-8, windows-1252 (a Latin-1 file
6
+ * from an older editor). Line numbers and quotes then agree between the read, the scan and the
7
+ * check.
8
+ */
9
+ export declare function decodeText(bytes: Uint8Array): string;
10
+ /** Whether a file's bytes are binary: a NUL in the first 8,000, unless it is marked UTF-16. */
11
+ export declare function isBinaryBytes(bytes: Uint8Array): boolean;
12
+ /** The same, for text `decodeText` made: a NUL is left only where the bytes were binary. */
13
+ export declare function isBinaryText(text: string): boolean;
14
+ /** A Git LFS pointer a checkout wasn't smudged with: three lines that stand for the real file. */
15
+ export declare function isLfsPointer(text: string): boolean;
16
+ /**
17
+ * Tokens a text costs, as every budget counts them (ADR 0112): four ASCII characters a token,
18
+ * and each character outside ASCII a token of its own. Characters / 4 alone counted Japanese,
19
+ * Chinese or Cyrillic at a quarter of what a tokenizer gives, so prompts over the model's limit
20
+ * were planned as fitting. `tokenUnits` is the same count in quarters, to sum over parts.
21
+ */
22
+ export declare function estimateTokens(text: string): number;
23
+ /** Quarter tokens: 1 for each ASCII character, 4 for each other (an astral one counted once). */
24
+ export declare function tokenUnits(text: string): number;
25
+ export interface IgnoreRule {
26
+ /** The folder of the .gitignore, repo-relative ("" for the root). */
27
+ base: string;
28
+ /** Matched in linear time (glob.ts): a scanned repo's .gitignore can't stall the scan. */
29
+ re: GlobMatcher;
30
+ negate: boolean;
31
+ dirOnly: boolean;
32
+ }
33
+ /** The rules of one .gitignore file (git's syntax: #, !, a trailing /, a leading or inner /). */
34
+ export declare function ignoreRules(text: string, base: string): IgnoreRule[];
35
+ /** Whether git would ignore a path by these rules: the last rule that matches decides. */
36
+ export declare function ignoredBy(rules: readonly IgnoreRule[], path: string, isDir: boolean): boolean;
37
+ export interface WalkOptions {
38
+ /**
39
+ * Whether a folder is left out: `above` are the folders it is in (repo-relative parts), `name`
40
+ * its own, `siblings` every name beside it. Asked after .git, links and .gitignore.
41
+ */
42
+ skipFolder?: (above: readonly string[], name: string, siblings: readonly string[]) => boolean;
43
+ }
44
+ /**
45
+ * A checkout's files, repo-relative with `/`, in the order a walk by name meets them: never a
46
+ * symbolic link (so no loop, no file outside the repo and no secret under another name), never
47
+ * `.git`, and nothing a .gitignore in the repo ignores (an ignored folder isn't walked). Only the
48
+ * repo's own .gitignore files are read. Deterministic: the same tree gives the same list.
49
+ */
50
+ export declare function listRepoFilesSync(root: string, o?: WalkOptions): string[];
51
+ /**
52
+ * The same walk, a file at a time: `visit` returns false to stop. Stops after `max` files and
53
+ * says it was cut.
54
+ */
55
+ export declare function walkRepo(root: string, visit: (path: string) => Promise<boolean | void>, o?: WalkOptions & {
56
+ max?: number;
57
+ }): Promise<{
58
+ files: number;
59
+ cut: boolean;
60
+ }>;