@maycombhq/sdk 2.0.0-beta.1 → 2.0.0-beta.11

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.
Files changed (102) hide show
  1. package/{dist → npm}/cache.d.ts +1 -1
  2. package/npm/core/api.d.ts +7964 -0
  3. package/npm/core/assistant-actor.d.ts +15 -0
  4. package/npm/core/audit.d.ts +153 -0
  5. package/npm/core/branches.d.ts +21 -0
  6. package/npm/core/cancel.d.ts +9 -0
  7. package/npm/core/catalog.d.ts +4735 -0
  8. package/npm/core/change-types-migrate.d.ts +10 -0
  9. package/npm/core/cite.d.ts +54 -0
  10. package/npm/core/contract-check.d.ts +251 -0
  11. package/npm/core/curated.d.ts +37 -0
  12. package/npm/core/fact-paths.d.ts +14 -0
  13. package/npm/core/facts-callers.d.ts +152 -0
  14. package/npm/core/facts-carry.d.ts +36 -0
  15. package/npm/core/facts-join-prototype.d.ts +239 -0
  16. package/npm/core/facts-join-vendor.d.ts +110 -0
  17. package/npm/core/facts-join.d.ts +482 -0
  18. package/npm/core/facts-terms.d.ts +108 -0
  19. package/npm/core/facts.d.ts +94 -0
  20. package/npm/core/fs.d.ts +47 -0
  21. package/npm/core/gates-migrate.d.ts +10 -0
  22. package/npm/core/host-questions.d.ts +111 -0
  23. package/npm/core/identity.d.ts +17 -0
  24. package/npm/core/index.d.ts +77 -0
  25. package/npm/core/json-schema.d.ts +20 -0
  26. package/npm/core/judgments.d.ts +63 -0
  27. package/npm/core/light.d.ts +8 -0
  28. package/npm/core/link-evidence.d.ts +212 -0
  29. package/npm/core/log.d.ts +49 -0
  30. package/npm/core/manifest-edit.d.ts +57 -0
  31. package/npm/core/merge.d.ts +85 -0
  32. package/npm/core/metarepo.d.ts +91 -0
  33. package/npm/core/migrate.d.ts +32 -0
  34. package/npm/core/migration-files.d.ts +13 -0
  35. package/npm/core/org-notes.d.ts +180 -0
  36. package/npm/core/orgpack-defaults.d.ts +199 -0
  37. package/npm/core/orgpack-load.d.ts +102 -0
  38. package/npm/core/profile-migrate.d.ts +11 -0
  39. package/npm/core/question-order.d.ts +23 -0
  40. package/npm/core/question-owners.d.ts +53 -0
  41. package/npm/core/question-proposals.d.ts +77 -0
  42. package/npm/core/questions.d.ts +312 -0
  43. package/npm/core/record-cache.d.ts +52 -0
  44. package/npm/core/refs.d.ts +9 -0
  45. package/npm/core/repo-description.d.ts +44 -0
  46. package/npm/core/repo-reads.d.ts +44 -0
  47. package/npm/core/roles-migrate.d.ts +9 -0
  48. package/npm/core/runtime-migrate.d.ts +11 -0
  49. package/npm/core/schema/ai.d.ts +397 -0
  50. package/npm/core/schema/change.d.ts +244 -0
  51. package/npm/core/schema/common.d.ts +135 -0
  52. package/npm/core/schema/conventions.d.ts +80 -0
  53. package/npm/core/schema/dialect.d.ts +801 -0
  54. package/npm/core/schema/executors.d.ts +396 -0
  55. package/npm/core/schema/fact-corrections.d.ts +56 -0
  56. package/npm/core/schema/facts.d.ts +1773 -0
  57. package/npm/core/schema/frameworks.d.ts +371 -0
  58. package/npm/core/schema/judgment.d.ts +77 -0
  59. package/npm/core/schema/kinds.d.ts +5168 -0
  60. package/npm/core/schema/layout.d.ts +25 -0
  61. package/npm/core/schema/orgpack.d.ts +1193 -0
  62. package/npm/core/schema/plugin.d.ts +73 -0
  63. package/npm/core/schema/question.d.ts +230 -0
  64. package/npm/core/schema/repo-type.d.ts +127 -0
  65. package/npm/core/schema/review.d.ts +558 -0
  66. package/npm/core/schema/scan-settings.d.ts +34 -0
  67. package/npm/core/schema/scan-verify.d.ts +535 -0
  68. package/npm/core/schema/spec.d.ts +269 -0
  69. package/npm/core/schema/version.d.ts +10 -0
  70. package/npm/core/schema/workspace.d.ts +330 -0
  71. package/npm/core/serialize.d.ts +17 -0
  72. package/npm/core/shared-maps.d.ts +146 -0
  73. package/npm/core/sources-migrate.d.ts +15 -0
  74. package/npm/core/specs.d.ts +66 -0
  75. package/npm/core/stack-helpers.d.ts +32 -0
  76. package/npm/core/tar-read.d.ts +13 -0
  77. package/npm/core/template.d.ts +101 -0
  78. package/npm/core/words.d.ts +13 -0
  79. package/npm/core/zip-read.d.ts +37 -0
  80. package/npm/core/zip.d.ts +13 -0
  81. package/npm/index.js +10097 -0
  82. package/{dist → npm}/plugin.d.ts +1 -1
  83. package/{dist → npm}/runner.d.ts +1 -1
  84. package/package.json +10 -11
  85. package/dist/cache.js +0 -115
  86. package/dist/cache.js.map +0 -1
  87. package/dist/fs-repo.js +0 -120
  88. package/dist/fs-repo.js.map +0 -1
  89. package/dist/index.js +0 -7
  90. package/dist/index.js.map +0 -1
  91. package/dist/parse-cache.js +0 -275
  92. package/dist/parse-cache.js.map +0 -1
  93. package/dist/plugin.js +0 -85
  94. package/dist/plugin.js.map +0 -1
  95. package/dist/runner.js +0 -209
  96. package/dist/runner.js.map +0 -1
  97. package/dist/sandbox.js +0 -443
  98. package/dist/sandbox.js.map +0 -1
  99. /package/{dist → npm}/fs-repo.d.ts +0 -0
  100. /package/{dist → npm}/index.d.ts +0 -0
  101. /package/{dist → npm}/parse-cache.d.ts +0 -0
  102. /package/{dist → npm}/sandbox.d.ts +0 -0
@@ -0,0 +1,312 @@
1
+ import { type JudgmentStore } from "./judgments.js";
2
+ import { Question, type QuestionDraft, type QuestionScopeLevel, type QuestionState } from "./schema/question.js";
3
+ /**
4
+ * Questions as files (ADR 0078): raise, list, read and answer questions/<id>.yaml. The CLI
5
+ * (atticus questions) and the local API (/api/questions) both call these, so the app and the
6
+ * terminal write the same file.
7
+ */
8
+ /** A refusal in words a person reads; `code` says which. */
9
+ export declare class QuestionError extends Error {
10
+ readonly code: "not-found" | "bad-answer" | "retired";
11
+ constructor(code: "not-found" | "bad-answer" | "retired", message: string);
12
+ }
13
+ /**
14
+ * The stable id of a question: a fingerprint of the step that asks, the repo, the question
15
+ * (spacing and case aside) and the evidence (in any order). The same question asked again by a
16
+ * rerun has the same id, so it is never asked twice.
17
+ */
18
+ export declare function questionId(o: {
19
+ step: string;
20
+ repo: string;
21
+ question: string;
22
+ evidence: string[];
23
+ }): string;
24
+ /** Who asked: the step, the repo, the command as typed, the command that reads the answer. */
25
+ export interface AskedBy {
26
+ step: string;
27
+ repo: string;
28
+ command: string;
29
+ rerun: string;
30
+ run?: string;
31
+ at: string;
32
+ }
33
+ /** An open question from what an AI step raised. */
34
+ export declare function questionFromDraft(d: QuestionDraft, by: AskedBy): Question;
35
+ /**
36
+ * Write a question as it is (a person's comment on a critic finding, ADR 0124 addendum D-app,
37
+ * is a question they answered as they asked it). Every other writer goes through
38
+ * `raiseQuestions` and `answerQuestion`.
39
+ */
40
+ export declare function writeQuestion(root: string, q: Question): Promise<void>;
41
+ /** Read one question, or undefined when there is no such file. Throws on a file that isn't valid. */
42
+ export declare function readQuestion(root: string, id: string): Promise<Question | undefined>;
43
+ export interface QuestionList {
44
+ questions: Question[];
45
+ /** Files in questions/ that aren't a valid question, with why. */
46
+ problems: {
47
+ file: string;
48
+ message: string;
49
+ }[];
50
+ }
51
+ /** Every question, oldest first; with `state`, only those in it. */
52
+ export declare function listQuestions(root: string, o?: {
53
+ state?: QuestionState;
54
+ repo?: string;
55
+ step?: string;
56
+ }): Promise<QuestionList>;
57
+ /** Whether a step is one that asked the question, or one that waits on it (ADR 0089). */
58
+ export declare const askedByStep: (q: Question, step: string) => boolean;
59
+ /** The kind of judgment that says whether a new question is one already on file (ADR 0117). */
60
+ export declare const SAME_QUESTION = "same-question";
61
+ export type SameVerdict = "same" | "narrower" | "different" | "unsure";
62
+ export declare const SAME_VERDICTS: readonly SameVerdict[];
63
+ /**
64
+ * The ids, fields, paths and numbers a question names, as written: a word with a capital inside
65
+ * it (renamedAt), an underscore (renamed_at), a dot or slash between letters
66
+ * (nadiengine-db.chat, /api/charts), a hyphen between letters and digits (forge-legacy) or a
67
+ * digit (1000, 5xx). Folded only in case and underscores, so renamedAt and renamed_at are one
68
+ * field. Format parsing, not meaning: it is what the veto compares.
69
+ */
70
+ export declare function namedIdentifiers(text: string, repo?: string): Set<string>;
71
+ /**
72
+ * The veto that runs before any judgment (ADR 0117): two questions that each name an id, field,
73
+ * path or number the other doesn't are about different things, so they are never the same
74
+ * question, whatever a model says. renamedAt and renamedBy of one table are two columns; a
75
+ * classification answered for one is never read for the other.
76
+ */
77
+ export declare function differentThings(a: {
78
+ question: string;
79
+ }, b: {
80
+ question: string;
81
+ }, repo?: string): string | undefined;
82
+ /** What a same-question judgment is about, as hashed into its key. */
83
+ export declare function sameQuestionInputs(repo: string, d: {
84
+ question: string;
85
+ evidence: readonly string[];
86
+ }, existing: Pick<Question, "id" | "question" | "evidence">): Record<string, unknown>;
87
+ /** A pair the checks couldn't settle, for a judge. */
88
+ export interface QuestionPair {
89
+ /** The judgment's key: judgmentKey(SAME_QUESTION, inputs). */
90
+ key: string;
91
+ inputs: Record<string, unknown>;
92
+ repo: string;
93
+ draft: QuestionDraft;
94
+ existing: Question;
95
+ }
96
+ /**
97
+ * Judges the pairs in one go (a model through the AI runtime, @maycombhq/ai's
98
+ * questionJudge): each judgment it settles is kept in the store under its pair's key, and its
99
+ * verdict comes back. A pair left out (the model was unsure, or the run waits in a hand-off) is
100
+ * raised as a question, listed as related.
101
+ */
102
+ export type QuestionJudge = (pairs: QuestionPair[]) => Promise<Map<string, SameVerdict>>;
103
+ /**
104
+ * The kind of judgment that says whether a person's answer on file already decides a new
105
+ * question (ADR 0117 addendum, 2026-10-24): yes, and the question isn't asked again; no, and it
106
+ * is weighed as any other question. Asked of an answered question with its answer, which the
107
+ * same-question judgment never sees.
108
+ */
109
+ export declare const ANSWERED_BY = "answered-by";
110
+ export type AnsweredVerdict = "yes" | "no" | "unsure";
111
+ /** What an answered-by judgment is about, as hashed into its key: the answer is part of it. */
112
+ export declare function answeredByInputs(repo: string, d: {
113
+ question: string;
114
+ evidence: readonly string[];
115
+ }, answered: Question): Record<string, unknown>;
116
+ /**
117
+ * The veto of the answered-by judgment, a fact: the ids, fields, paths and numbers the new
118
+ * question names that neither the answered question nor its answer names. A person answered
119
+ * about those things, not these, so the answer is never read for it (ADR 0117 §4).
120
+ */
121
+ export declare function namedBeyondAnswer(d: {
122
+ question: string;
123
+ }, answered: {
124
+ question: string;
125
+ answer: string;
126
+ }, repo?: string): string[];
127
+ /** A new question and an answered one the checks couldn't settle, for a judge. */
128
+ export interface AnsweredPair {
129
+ /** The judgment's key: judgmentKey(ANSWERED_BY, inputs). */
130
+ key: string;
131
+ inputs: Record<string, unknown>;
132
+ repo: string;
133
+ draft: QuestionDraft;
134
+ answered: Question;
135
+ /** The answer in words. */
136
+ answer: string;
137
+ }
138
+ /** Judges answered-by pairs in one go (@maycombhq/ai's answerJudge); a pair left out is open. */
139
+ export type AnswerJudge = (pairs: AnsweredPair[]) => Promise<Map<string, AnsweredVerdict>>;
140
+ export interface RaiseOptions {
141
+ /** Judge pairs the checks and the step's own reading leave open. None: they are raised. */
142
+ judge?: QuestionJudge;
143
+ /**
144
+ * Judge whether an answer on file decides a new question, for the pairs the step's own
145
+ * reading (`sameAs: answered`) and a stored judgment leave open. None: they stay open.
146
+ */
147
+ answerJudge?: AnswerJudge;
148
+ /**
149
+ * Hold back a question an answered one may already decide, where nothing settled it (no
150
+ * reading, no judgment, no judge, or the judge unsure): it isn't written, and comes back in
151
+ * `held` with the answered questions, so the step can hand it back to its drafter instead of
152
+ * asking the person again. Called once per such question; true holds it.
153
+ */
154
+ hold?: (q: Question, answered: Question[]) => boolean;
155
+ /** Where judgments are kept; default the metarepo's judgments/. */
156
+ judgments?: JudgmentStore;
157
+ }
158
+ /** A question held back: the one it would have been, and the answered ones that may decide it. */
159
+ export interface HeldQuestion {
160
+ question: Question;
161
+ draft: QuestionDraft;
162
+ answered: Question[];
163
+ }
164
+ /** Whether `quote` is word for word in `text` (whitespace, curly quotes and case aside). */
165
+ export declare const quotedIn: (text: string, quote: string) => boolean;
166
+ /**
167
+ * Whether two questions are about the same target (ADR 0117 addendum, 2026-10-25), as far as
168
+ * facts tell: they name an id in common, or cite a file in common and share at least two words
169
+ * of substance. Whether they ask the same thing about it is the judgment's; this keeps an answer
170
+ * from being weighed for a question about something else.
171
+ */
172
+ export declare function sameTarget(a: {
173
+ question: string;
174
+ evidence: readonly string[];
175
+ }, b: {
176
+ question: string;
177
+ evidence: readonly string[];
178
+ }, repo?: string): boolean;
179
+ /**
180
+ * Write the questions a step raised (ADR 0078, 0089, 0117). One already on file by its id is
181
+ * left as it is and returned in `known`. Otherwise it is weighed against the questions on file
182
+ * for the same repo:
183
+ * 1. the veto: the two name different ids, fields or numbers, so they differ;
184
+ * 2. the step's own reading (`sameAs`), when the id is a candidate and its words are in it;
185
+ * 3. a judgment already in judgments/same-question/;
186
+ * 4. the judge, when one is given.
187
+ * Same: the step is added to the earlier question's `alsoAskedBy` and reads its answer (it is
188
+ * returned in `reused` and `known`), except an answered question the new one names more ids
189
+ * than: that is narrower, so a person sees it. Narrower or unsure: the question is raised with
190
+ * the earlier one under `related`. `of` is the question each draft became, in order.
191
+ */
192
+ export declare function raiseQuestions(root: string, drafts: QuestionDraft[], by: AskedBy, o?: RaiseOptions): Promise<{
193
+ raised: Question[];
194
+ known: Question[];
195
+ reused: Question[];
196
+ of: (Question | undefined)[];
197
+ /** Questions held back for the step's drafter (`hold`); not written. */
198
+ held: HeldQuestion[];
199
+ /** The answered questions whose answer decides a draft, by the draft's index (ADR 0117 addendum). */
200
+ decidedBy: Map<number, Question>;
201
+ }>;
202
+ /**
203
+ * Rewrite questions/<id>.yaml files written at an older question schema version (1, ADR 0078;
204
+ * 2, ADR 0117) at the current one (3, ADR 0153): only the version changes, since what each
205
+ * version adds is optional. Returns the files, relative to the root; with dryRun, the files it
206
+ * would rewrite.
207
+ */
208
+ export declare function migrateQuestions(root: string, o?: {
209
+ dryRun?: boolean;
210
+ }): Promise<string[]>;
211
+ /** What a step says of a question it reused: who asked it first, and that it waits on it. */
212
+ export declare const reusedLine: (q: Question) => string;
213
+ /**
214
+ * The skill file of a repo type, relative to the root, where a repo-type answer goes: the
215
+ * first skill the type lists (repo-types/<id>/type.yaml, ADR 0077), else process/skills/<id>/.
216
+ */
217
+ export declare function repoTypeSkillRel(root: string, type: string): Promise<string>;
218
+ /** The answer in words: the option's label or the person's own text. */
219
+ /**
220
+ * Retire an open question (ADR 0117 addendum, V0): it is no longer asked and nothing reads an
221
+ * answer to it. It says why, and which questions ask it now. An answered question keeps its
222
+ * answer and is never retired here.
223
+ */
224
+ export declare function retireQuestion(root: string, id: string, o: {
225
+ why: string;
226
+ replacedBy?: string[];
227
+ at: string;
228
+ }): Promise<Question>;
229
+ /**
230
+ * ADR 0162 (F8): open an answered targets question again, because the code read since disagrees
231
+ * with its answer (the repo it named has no route that serves the call). The answer it had is
232
+ * kept under `reopened` with why, so the person sees what they said and what the code says.
233
+ */
234
+ export declare function reopenQuestion(root: string, id: string, o: {
235
+ why: string;
236
+ at: string;
237
+ }): Promise<Question>;
238
+ export declare function answerWords(q: Question): string | undefined;
239
+ /**
240
+ * An answer as a step's next prompt gives it (B-run2-fixes 8): the option picked with what it
241
+ * means and what it changes, or the person's own words. `answerWords` (the label alone) stays what
242
+ * judgments are keyed by, so their stored verdicts hold.
243
+ */
244
+ export declare function answerText(q: Question): string | undefined;
245
+ /** Put (or replace) the answer's line under "## Answers" in a skill file's text. */
246
+ export declare function withSkillAnswer(body: string, q: Question): string;
247
+ export interface AnswerInput {
248
+ /** The option picked, counting from 1. */
249
+ option?: number;
250
+ /** Or the person's own words. */
251
+ text?: string;
252
+ /** The scope the person confirms; default the one proposed. */
253
+ scope?: QuestionScopeLevel;
254
+ /** The repo type, when the person widens a repo question to its type. */
255
+ repoType?: string;
256
+ /**
257
+ * ADR 0153 (Q2): the rule the answer covers, for a target or hosts question: a host pattern
258
+ * (`*.payments.forge.internal`) or a path prefix (`/forge/limits/**`).
259
+ */
260
+ match?: string;
261
+ /** ADR 0153 (Q5): the assistant's proposal this answer accepts (acceptProposal sets it). */
262
+ proposal?: NonNullable<Question["answer"]>["proposal"];
263
+ /**
264
+ * Review item 14: a file change the answer brings (a system written into the profile, ADR
265
+ * 0162), made only once the answer is checked and just before it is written. When it throws,
266
+ * nothing is answered (a `bad-answer` with its first line).
267
+ */
268
+ beforeWrite?: () => Promise<void>;
269
+ by: string;
270
+ at: string;
271
+ }
272
+ /**
273
+ * Whether a host a hosts question asks about (`localhost:9966`, `limits.payments.forge.internal`)
274
+ * is one a rule's host pattern covers, as the manifest matches hosts.
275
+ */
276
+ export declare function hostRuleCovers(pattern: string, asked: string): boolean;
277
+ /**
278
+ * Record a person's answer in the question's file. A repo-type answer also goes, as a line
279
+ * under "## Answers", in the type's skill file when that file is there; the path is kept in
280
+ * the answer either way.
281
+ */
282
+ export declare function answerQuestion(root: string, id: string, a: AnswerInput): Promise<{
283
+ question: Question;
284
+ skill?: {
285
+ path: string;
286
+ written: boolean;
287
+ };
288
+ /** For a hosts question answered with a repo (ADR 0088): the host written to the manifest. */
289
+ hosts?: {
290
+ repo: string;
291
+ host: string;
292
+ manifest: string;
293
+ added: boolean;
294
+ basePath?: string;
295
+ };
296
+ /**
297
+ * ADR 0153 (Q2): the other open hosts questions the answer's host pattern covers, retired as
298
+ * answered by it.
299
+ */
300
+ covered?: string[];
301
+ /**
302
+ * For a hosts question answered with an outside system (O1): the system written to the
303
+ * profile, with the host as its alias.
304
+ */
305
+ system?: {
306
+ id: string;
307
+ host: string;
308
+ boundary: "internal" | "vendor";
309
+ profile: string;
310
+ added: boolean;
311
+ };
312
+ }>;
@@ -0,0 +1,52 @@
1
+ /**
2
+ * Record files read and parsed once, then kept between runs (ADR 0119, with its addendum of
3
+ * 2026-10-26). A metarepo's catalog is about 1,500 files and its specs 400 more; reading and
4
+ * parsing every one took seconds on every `atticus next` or `atticus change status`, and a
5
+ * person runs those all day. So each parse is kept in `<cacheRoot>/.atticus/cache/`, keyed by
6
+ * the file's path, size and modification time, the way the search index (packages/index) and the
7
+ * manual step store already key theirs. A file whose size or time changed is read again; the
8
+ * cache is derived, local-only and never committed, and a cache that can't be read or written
9
+ * costs nothing but the parse.
10
+ *
11
+ * `cacheRoot` is the metarepo the command is working in, and the caller names it: nothing here
12
+ * works out a root from the folder being read. A read with no `cacheRoot` keeps nothing and
13
+ * writes nothing, which is what reading someone else's metarepo must be — absorb, federation, a
14
+ * linked estate. Atticus never writes where it was only asked to read (hard rule 6, ADR 0038),
15
+ * and that holds for its own cache as much as for anything else.
16
+ *
17
+ * Nothing here decides what a file means: the caller's `parse` does, and only its output (the
18
+ * record, or the problem with the file) is kept.
19
+ */
20
+ /** One file's parse: the value, or why the file isn't valid. Never both. */
21
+ export interface Parsed<T> {
22
+ /** The file, relative to the folder, with forward slashes. */
23
+ rel: string;
24
+ value?: T;
25
+ problem?: string;
26
+ }
27
+ /** What a caller's parse says about one file. */
28
+ export type ParseOutcome<T> = {
29
+ ok: true;
30
+ value: T;
31
+ } | {
32
+ ok: false;
33
+ message: string;
34
+ };
35
+ /** Run `f` over the items, up to `AT_ONCE` at a time, keeping the order. */
36
+ export declare function mapAtOnce<I, O>(items: I[], f: (item: I) => Promise<O>): Promise<O[]>;
37
+ /**
38
+ * Read and parse every named file of a folder, reusing the parses kept from an earlier run for
39
+ * the files that haven't changed. `name` names the kind of file (`catalog`, `spec`), `version`
40
+ * the shape of what the parse gives back; `files` are relative to `dir`, with forward slashes.
41
+ * `cacheRoot` is the metarepo this run is working in, and the only place a cache is ever
42
+ * written; without it the read keeps nothing and writes nothing, and costs only the parse.
43
+ */
44
+ export declare function readParsedFiles<T>(o: {
45
+ dir: string;
46
+ files: string[];
47
+ name: string;
48
+ version: string;
49
+ parse: (text: string, rel: string) => ParseOutcome<T>;
50
+ /** The root of the metarepo this run is working in; none means no cache (read-only). */
51
+ cacheRoot?: string;
52
+ }): Promise<Parsed<T>[]>;
@@ -0,0 +1,9 @@
1
+ import type { CatalogRecord } from "./catalog.js";
2
+ import { type RecordKind } from "./schema/kinds.js";
3
+ /** The reference fields of a record kind, e.g. Interface → from, to, endpoint, route. */
4
+ export declare function referenceFields(kind: RecordKind): string[];
5
+ /** Every reference a record makes: the field path and the id it points at. */
6
+ export declare function recordReferences(record: CatalogRecord): {
7
+ field: string;
8
+ id: string;
9
+ }[];
@@ -0,0 +1,44 @@
1
+ import type { RepoDescription } from "./schema/workspace.js";
2
+ /**
3
+ * What a repo is, in a person's words (ADR 0128), and the few things Atticus reads out of it.
4
+ *
5
+ * A description is a note, never a finding: it is put into a prompt as data, it may make a
6
+ * proposal easier to reach, and it is part of what a repo is matched on — but it never overrides
7
+ * a fact verified from code, and a drafted one is marked unconfirmed everywhere it is shown.
8
+ */
9
+ /** A drafted description nobody has confirmed yet. */
10
+ export declare const isSuggested: (d?: RepoDescription) => boolean;
11
+ /** The word for a description's trust, as every surface says it. */
12
+ export declare const descriptionTrust: (d: RepoDescription) => string;
13
+ /**
14
+ * A description on one line with who it came from: a person's words, or a draft nobody has
15
+ * confirmed. Used in lists, the repo page, map.md and the question options.
16
+ */
17
+ export declare function descriptionLine(d: RepoDescription): string;
18
+ /**
19
+ * The description as a reading prompt carries it (ADR 0124): said to be a note about the repo,
20
+ * and said to be beaten by the code. The text itself goes in as an untrusted source, wrapped as
21
+ * data by the context pack, so a line written inside it is never an instruction.
22
+ */
23
+ export declare function descriptionNote(repo: string, d: RepoDescription): string;
24
+ /** What a description says a repo mostly holds, where it says so plainly. */
25
+ export interface DescriptionShape {
26
+ /** Pages of documentation rather than a product. */
27
+ docs: boolean;
28
+ /** A body of data, fixtures or sample records. */
29
+ data: boolean;
30
+ /** Code copied in from elsewhere rather than written here. */
31
+ vendored: boolean;
32
+ }
33
+ /**
34
+ * What a description plainly says a repo holds, for the proposals that benefit from it: a
35
+ * description that calls a repo a documentation site, a text corpus or vendored code makes
36
+ * `atticus map --estimate` readier to propose leaving its folders out. It only lowers the bar
37
+ * for a proposal a person still accepts; it never excludes anything by itself, and a folder
38
+ * that holds a build, deploy or config file is never proposed whatever the description says.
39
+ */
40
+ export declare function descriptionShape(d?: RepoDescription): DescriptionShape;
41
+ /** Whether a description says the repo is mostly not product code. */
42
+ export declare const saysNotProduct: (d?: RepoDescription) => boolean;
43
+ /** The words of a description, for matching a repo on what it is as well as on its id. */
44
+ export declare function descriptionWords(d?: RepoDescription): string[];
@@ -0,0 +1,44 @@
1
+ import type { Fact, FactOf } from "./schema/facts.js";
2
+ import type { Question } from "./schema/question.js";
3
+ /**
4
+ * The commit a checkout is at, read from its `.git` files: HEAD, a loose ref or packed-refs,
5
+ * following a worktree's `gitdir:` and `commondir`. Undefined when there is no checkout.
6
+ */
7
+ export declare function headFromFiles(dir: string): Promise<string | undefined>;
8
+ /** Where a repo is checked out: the metarepo's workspace/<repo>, or the repo itself when adopted. */
9
+ export declare const checkoutDirOf: (root: string, repo: string) => string;
10
+ /**
11
+ * not-read: no facts and no verifier's report (a repo the readers alone mapped, or none);
12
+ * stale: the facts were read at another commit than the checkout is at; incomplete: facts were
13
+ * rejected, some aren't verified, there is no verifier's report, or files went unread; read: none
14
+ * of these.
15
+ */
16
+ export type RepoReadState = "not-read" | "stale" | "incomplete" | "read";
17
+ export interface RepoRead {
18
+ repo: string;
19
+ state: RepoReadState;
20
+ /** Why it is stale or incomplete, in words a person reads; empty when it is read. */
21
+ why: string[];
22
+ /** The command that reads it again or checks it. */
23
+ next?: string;
24
+ /** The commit its facts were read at, and the checkout's. */
25
+ commit?: string;
26
+ head?: string;
27
+ /** Its facts, for the questions that cite their lines. */
28
+ facts: Fact[];
29
+ }
30
+ /** The read of one repo (see `RepoRead`). Never throws: an unreadable file is a reason. */
31
+ export declare function repoReadOf(root: string, repo: string): Promise<RepoRead>;
32
+ /**
33
+ * The steps whose questions are about a link (ADR 0140): which repo or system answers a call
34
+ * (`facts-targets`, scanner's TARGETS_STEP; `estate-targets`, the estate join's) and which repo
35
+ * answers on a host (`scan-hosts`). Their answers join calls.
36
+ */
37
+ export declare const LINK_QUESTION_STEPS: ReadonlySet<string>;
38
+ export declare const isLinkQuestion: (q: Pick<Question, "askedBy">) => boolean;
39
+ /**
40
+ * The calls a link question asks about: a targets question's are the call facts of its repo on
41
+ * the lines it cites (one per call, a group's every call, Q1); a hosts question's are every call
42
+ * to its host, in any repo (its evidence cites only the first few). `facts` are the facts by repo.
43
+ */
44
+ export declare function callsOfQuestion(q: Pick<Question, "askedBy" | "repo" | "evidence" | "question">, facts: ReadonlyMap<string, readonly Fact[]>): FactOf<"call">[];
@@ -0,0 +1,9 @@
1
+ /**
2
+ * roles.yaml version 1 → 2 (ADR 0140). Version 2 adds `teams`; a file without them names no
3
+ * team, as version 1 did, so the step writes the new number only and keeps the file's comments,
4
+ * order and line layout (`atticus upgrade`'s roles-v2).
5
+ */
6
+ export declare function migrateRolesText(text: string): {
7
+ text: string;
8
+ changed: boolean;
9
+ };
@@ -0,0 +1,11 @@
1
+ /**
2
+ * runtime.yaml version 1 → 2 (ADR 0121 addendum, per-step models). Version 2 adds a model per
3
+ * kind of step (`models.read`, `draft`, `critic`, `knowledge`, `quick`); a file that names none
4
+ * runs every step on the one model, as every step ran in version 1. So the migration only writes
5
+ * the new version and keeps the file's comments and order: no step changes model until a person
6
+ * names one. `models.recommended` stays as it is (the critic still reads `recommended.critic`).
7
+ */
8
+ export declare function migrateRuntimeText(text: string): {
9
+ text: string;
10
+ changed: boolean;
11
+ };