@maycombhq/sdk 2.0.0-beta.3 → 2.0.0-beta.30
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/npm/core/ai-decisions.d.ts +373 -0
- package/npm/core/api.d.ts +15888 -3797
- package/npm/core/app-memory.d.ts +69 -0
- package/npm/core/assistant-actor.d.ts +28 -7
- package/npm/core/audit.d.ts +174 -0
- package/npm/core/canary.d.ts +369 -0
- package/npm/core/cancel.d.ts +20 -0
- package/npm/core/catalog.d.ts +220 -66
- package/npm/core/change-types-migrate.d.ts +14 -0
- package/npm/core/cite.d.ts +88 -6
- package/npm/core/contract-check.d.ts +276 -0
- package/npm/core/curated.d.ts +10 -0
- package/npm/core/decision-batches.d.ts +29 -0
- package/npm/core/declarable-routes.d.ts +52 -0
- package/npm/core/declared-links.d.ts +210 -0
- package/npm/core/eol.d.ts +5 -0
- package/npm/core/fact-paths.d.ts +14 -0
- package/npm/core/facts-callers.d.ts +23 -1
- package/npm/core/facts-carry.d.ts +8 -2
- package/npm/core/facts-deps.d.ts +85 -0
- package/npm/core/facts-join-prototype.d.ts +66 -4
- package/npm/core/facts-join-vendor.d.ts +67 -7
- package/npm/core/facts-join.d.ts +476 -2
- package/npm/core/facts-terms.d.ts +108 -0
- package/npm/core/facts.d.ts +155 -1
- package/npm/core/field-places.d.ts +109 -0
- package/npm/core/file-pool.d.ts +84 -0
- package/npm/core/fs.d.ts +205 -7
- package/npm/core/glob-plain.d.ts +34 -0
- package/npm/core/glob.d.ts +14 -0
- package/npm/core/hash-cache.d.ts +53 -0
- package/npm/core/host-questions.d.ts +273 -1
- package/npm/core/identity.d.ts +20 -8
- package/npm/core/index.d.ts +38 -0
- package/npm/core/initialisms.d.ts +62 -0
- package/npm/core/kept-files.d.ts +17 -0
- package/npm/core/light.d.ts +5 -0
- package/npm/core/link-candidates.d.ts +224 -0
- package/npm/core/link-evidence.d.ts +212 -0
- package/npm/core/log.d.ts +2 -0
- package/npm/core/manifest-edit.d.ts +83 -6
- package/npm/core/merge.d.ts +28 -0
- package/npm/core/metarepo.d.ts +26 -1
- package/npm/core/migrate.d.ts +3 -2
- package/npm/core/org-notes.d.ts +180 -0
- package/npm/core/orgpack-defaults.d.ts +30 -6
- package/npm/core/orgpack-load.d.ts +24 -0
- package/npm/core/paths.d.ts +23 -0
- package/npm/core/printer.d.ts +18 -0
- package/npm/core/process-trees.d.ts +109 -0
- package/npm/core/profile-migrate.d.ts +13 -0
- package/npm/core/question-order.d.ts +23 -0
- package/npm/core/question-owners.d.ts +57 -0
- package/npm/core/question-proposals.d.ts +77 -0
- package/npm/core/question-roles.d.ts +84 -0
- package/npm/core/questions.d.ts +123 -6
- package/npm/core/record-cache.d.ts +122 -2
- package/npm/core/repo-files.d.ts +66 -0
- package/npm/core/repo-reads.d.ts +44 -0
- package/npm/core/roles-migrate.d.ts +10 -0
- package/npm/core/run-log.d.ts +341 -0
- package/npm/core/runtime-migrate.d.ts +18 -0
- package/npm/core/schema/ai.d.ts +61 -13
- package/npm/core/schema/common.d.ts +32 -8
- package/npm/core/schema/component-type.d.ts +193 -0
- package/npm/core/schema/conventions.d.ts +80 -0
- package/npm/core/schema/dialect.d.ts +12 -12
- package/npm/core/schema/fact-corrections.d.ts +112 -2
- package/npm/core/schema/facts.d.ts +743 -23
- package/npm/core/schema/frameworks.d.ts +12 -12
- package/npm/core/schema/kinds.d.ts +230 -66
- package/npm/core/schema/orgpack.d.ts +248 -24
- package/npm/core/schema/question.d.ts +281 -5
- package/npm/core/schema/reading-rules.d.ts +51 -0
- package/npm/core/schema/repo-type.d.ts +20 -2
- package/npm/core/schema/review.d.ts +30 -9
- package/npm/core/schema/scan-verify.d.ts +77 -0
- package/npm/core/schema/version.d.ts +4 -1
- package/npm/core/schema/workspace.d.ts +29 -11
- package/npm/core/setup-edit.d.ts +107 -0
- package/npm/core/shared-maps.d.ts +146 -0
- package/npm/core/stack-helpers.d.ts +32 -0
- package/npm/core/version-order.d.ts +14 -0
- package/npm/fs-repo.d.ts +2 -1
- package/npm/index.js +14248 -6710
- package/npm/listing.d.ts +14 -0
- package/npm/sandbox.d.ts +2 -1
- package/package.json +1 -1
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
import { type ChildProcess } from "node:child_process";
|
|
2
|
+
/**
|
|
3
|
+
* Beta.27 review: the processes Atticus starts in a process group of their own (a build, a git
|
|
4
|
+
* the app may stop), kept so none outlives Atticus. A process in its own group no longer gets the
|
|
5
|
+
* terminal's signals (Ctrl+C, the terminal closed), so while any runs, or a task run holds on to a
|
|
6
|
+
* stop (holdStop), one handler per signal (SIGINT, SIGTERM, SIGHUP) stops them all, tells each
|
|
7
|
+
* listener (onStopping: taskrun aborts its model call), and lets the signal end Atticus once nothing
|
|
8
|
+
* holds on (or after TREE_SIGNAL_GRACE_MS). When Atticus exits, every tree still running is killed
|
|
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.
|
|
17
|
+
*/
|
|
18
|
+
/** How a tracked tree is stopped: its own way (git's tree, a build's group), by the signal. */
|
|
19
|
+
export type StopTree = (signal: NodeJS.Signals) => void;
|
|
20
|
+
/** However long the runs take to record themselves, Atticus ends by the signal within this. */
|
|
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
|
+
};
|
|
26
|
+
/**
|
|
27
|
+
* Stop every tracked tree (SIGTERM, each its own way) and tell each listener: Atticus is
|
|
28
|
+
* stopping (atticus ui on its way out, or a signal).
|
|
29
|
+
*/
|
|
30
|
+
export declare function stopTrackedTrees(): void;
|
|
31
|
+
/** Hear Atticus stopping (stopTrackedTrees, a signal). Gives back the way to stop hearing. */
|
|
32
|
+
export declare function onStopping(fn: () => void): () => void;
|
|
33
|
+
/**
|
|
34
|
+
* Beta.27 re-review: Atticus's own handlers of a signal, the ones that end (or stop) Atticus
|
|
35
|
+
* themselves: atticus ui's, map --all's Ctrl+C. Counting the process's listeners took any
|
|
36
|
+
* library's for one (signal-exit, which @inquirer/core loads through OpenSpec, listens to every
|
|
37
|
+
* signal and ends the process only when it alone listens), so neither ended it and Ctrl+C did
|
|
38
|
+
* nothing. A `once` handler that has heard the signal still counts until that signal's listeners
|
|
39
|
+
* have all run. A `fallback` one (a terminal run's record) ends Atticus only when nobody else
|
|
40
|
+
* does, nor these trees (stopPending): it never counts here.
|
|
41
|
+
*/
|
|
42
|
+
type SignalFn = (sig: NodeJS.Signals) => void;
|
|
43
|
+
/**
|
|
44
|
+
* Hear a signal as Atticus's own handler: one that ends or stops Atticus (process-trees and the
|
|
45
|
+
* run log then leave the ending to it), or with `fallback`, one that ends it only when nothing
|
|
46
|
+
* else does. Gives back the way to stop hearing it.
|
|
47
|
+
*/
|
|
48
|
+
export declare function onAtticusSignal(sig: NodeJS.Signals, fn: SignalFn, o?: {
|
|
49
|
+
once?: boolean;
|
|
50
|
+
fallback?: boolean;
|
|
51
|
+
}): () => void;
|
|
52
|
+
/**
|
|
53
|
+
* Whether Atticus has a handler of its own for `sig` (other than `except`, never a fallback one)
|
|
54
|
+
* that ends it.
|
|
55
|
+
*/
|
|
56
|
+
export declare function atticusHandles(sig: NodeJS.Signals, except?: SignalFn): boolean;
|
|
57
|
+
/**
|
|
58
|
+
* Whether these trees hold a signal that ends Atticus once they have ended and the runs recorded
|
|
59
|
+
* the stop (it is raised again then): a fallback handler leaves the end to it until then.
|
|
60
|
+
*/
|
|
61
|
+
export declare const stopPending: () => boolean;
|
|
62
|
+
/**
|
|
63
|
+
* Keep a child in its own process group until it ends: stopped with Atticus (a signal,
|
|
64
|
+
* stopTrackedTrees) by `stop`, killed by it with SIGKILL when Atticus exits. Gives back the way
|
|
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.
|
|
68
|
+
*/
|
|
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
|
+
};
|
|
80
|
+
/**
|
|
81
|
+
* Hold a stop for a task run, from its start until its record is saved: a signal meanwhile
|
|
82
|
+
* stops its trees, and Atticus ends only once it is released.
|
|
83
|
+
*/
|
|
84
|
+
export declare function holdStop(): () => void;
|
|
85
|
+
/** How many trees are tracked now (tests). */
|
|
86
|
+
export declare const trackedTrees: () => number;
|
|
87
|
+
/**
|
|
88
|
+
* The child and everything it started: on Windows its whole tree (taskkill /T /F), elsewhere its
|
|
89
|
+
* process group (it was started detached), else the child alone.
|
|
90
|
+
*/
|
|
91
|
+
export declare function stopProcessGroup(child: ChildProcess, signal?: NodeJS.Signals): void;
|
|
92
|
+
/**
|
|
93
|
+
* Every process below `pid` (POSIX `ps`, read without blocking), each with when it started (as
|
|
94
|
+
* ps says), deepest last; none when ps can't be run. When it started tells a process from another
|
|
95
|
+
* given the same pid later.
|
|
96
|
+
*/
|
|
97
|
+
export declare function processDescendants(pid: number): Promise<Map<number, string>>;
|
|
98
|
+
/** How long a stopped tree gets to end before it is killed outright. */
|
|
99
|
+
export declare const TREE_KILL_AFTER_MS = 5000;
|
|
100
|
+
/**
|
|
101
|
+
* Kill a process and everything it started (git clone runs git-remote-https and index-pack). On
|
|
102
|
+
* Windows, taskkill /T takes the tree; elsewhere the process ran in its own group, which is
|
|
103
|
+
* signalled whole, with each process found below it (where a new group can't be made, a sandbox,
|
|
104
|
+
* the group alone would miss them); what hasn't ended a moment later is killed outright. The
|
|
105
|
+
* second pass reads the processes again and kills only those still there with the same start, so
|
|
106
|
+
* a pid given to another process meanwhile is never signalled. `ps` is read without blocking.
|
|
107
|
+
*/
|
|
108
|
+
export declare function killProcessTree(child: ChildProcess, signal?: NodeJS.Signals): void;
|
|
109
|
+
export {};
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* profile.yaml moved up to the version a write needs (ADR 0162 amendment: 2 for a system's
|
|
3
|
+
* `topics`; ADR 0204: 3 for the declared arrows, `links`). A file without what the new version
|
|
4
|
+
* adds says what it said, so the step writes the new number only and keeps the file's comments,
|
|
5
|
+
* order and line layout. Nothing is moved: which alias is a topic is a person's call. A version-1
|
|
6
|
+
* or 2 profile stays valid, so `atticus upgrade` has no step for it; `addProfileSystem` applies
|
|
7
|
+
* this when it writes a topic (to 2), `declareArrow` when it writes an arrow (to 3). A file at
|
|
8
|
+
* `to` or above is left as it is.
|
|
9
|
+
*/
|
|
10
|
+
export declare function migrateProfileText(text: string, to?: number): {
|
|
11
|
+
text: string;
|
|
12
|
+
changed: boolean;
|
|
13
|
+
};
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import type { Question } from "./schema/question.js";
|
|
2
|
+
/** The changes in flight: their ids, sorted. */
|
|
3
|
+
export declare function changesInFlight(root: string): Promise<string[]>;
|
|
4
|
+
/**
|
|
5
|
+
* The questions each change in flight rests on, by question id: the changes, sorted. A change's
|
|
6
|
+
* own questions are found by `questionWeights` (their repo is the change's id); this reads the
|
|
7
|
+
* question files the newest round of each of its gates cites.
|
|
8
|
+
*/
|
|
9
|
+
export declare function questionsInFlight(root: string): Promise<Map<string, string[]>>;
|
|
10
|
+
/** Why a question is where it is in the list. */
|
|
11
|
+
export interface QuestionWeight {
|
|
12
|
+
/** The changes in flight that rest on it, sorted; empty when none. */
|
|
13
|
+
restsOn: string[];
|
|
14
|
+
/** How many calls its answer joins; 0 for a question that isn't about a link. */
|
|
15
|
+
joins: number;
|
|
16
|
+
}
|
|
17
|
+
/** The weight of each question (see `QuestionWeight`), by id. */
|
|
18
|
+
export declare function questionWeights(root: string, questions: readonly Question[]): Promise<Map<string, QuestionWeight>>;
|
|
19
|
+
/**
|
|
20
|
+
* The questions in the order to ask them: what a change in flight rests on first, then the
|
|
21
|
+
* answers that join the most calls; otherwise as they came (oldest first, from listQuestions).
|
|
22
|
+
*/
|
|
23
|
+
export declare function orderQuestions<Q extends Pick<Question, "id">>(questions: readonly Q[], weights: ReadonlyMap<string, QuestionWeight>): Q[];
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import { type Team } from "./schema/orgpack.js";
|
|
2
|
+
import type { Question } from "./schema/question.js";
|
|
3
|
+
/**
|
|
4
|
+
* Route each question to its owner (ADR 0140, Q4): the team that owns the question's repo is the
|
|
5
|
+
* repo manifest's `owner`; roles.yaml's `teams` (version 2) gives the team a name and says who is
|
|
6
|
+
* on it, so `atticus questions list --mine` and the app's Questions page can list a person's own.
|
|
7
|
+
* The person is the metarepo's Git user (ADR 0073). Words, not permissions: anyone can still
|
|
8
|
+
* read and answer any question.
|
|
9
|
+
*/
|
|
10
|
+
/** The team a question goes to, or why none does. */
|
|
11
|
+
export type QuestionOwner = {
|
|
12
|
+
team: string;
|
|
13
|
+
name?: string;
|
|
14
|
+
} | {
|
|
15
|
+
none: string;
|
|
16
|
+
};
|
|
17
|
+
/** The teams roles.yaml names, and why they couldn't be read when they couldn't. */
|
|
18
|
+
export declare function readTeams(root: string): Promise<{
|
|
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[]>;
|
|
22
|
+
problem?: string;
|
|
23
|
+
}>;
|
|
24
|
+
/** A handle as compared: no leading @, lower case (Git hosts' handles are case-insensitive). */
|
|
25
|
+
export declare const handleKey: (h: string) => string;
|
|
26
|
+
/** The teams a person is on, by their Git handle. */
|
|
27
|
+
export declare function teamsOfPerson(handle: string, teams: readonly Team[]): Team[];
|
|
28
|
+
/**
|
|
29
|
+
* Who a question goes to: the team the manifest names as its repo's owner, with the name
|
|
30
|
+
* roles.yaml gives it. A change's own questions, and a repo no manifest lists, have no team.
|
|
31
|
+
*/
|
|
32
|
+
export declare function ownerOfQuestion(q: Pick<Question, "repo">, o: {
|
|
33
|
+
/** Each listed repo's owner, from the repo manifests. */
|
|
34
|
+
owners: ReadonlyMap<string, string>;
|
|
35
|
+
teams: readonly Team[];
|
|
36
|
+
/** The ids of the changes, whose own questions are filed under them. */
|
|
37
|
+
changes?: ReadonlySet<string>;
|
|
38
|
+
}): QuestionOwner;
|
|
39
|
+
/**
|
|
40
|
+
* Who a question goes to, a change's people included (ADR 0153, Q4): a change's own question,
|
|
41
|
+
* filed under the change's id, goes to the people its change.yaml names under `owners`, whatever
|
|
42
|
+
* they do on it; every other question goes to its repo's team (`ownerOfQuestion`).
|
|
43
|
+
*/
|
|
44
|
+
export type QuestionRoute = QuestionOwner | {
|
|
45
|
+
change: string;
|
|
46
|
+
people: string[];
|
|
47
|
+
};
|
|
48
|
+
/** Everyone a change.yaml's `owners` names, by handle, once each, sorted. */
|
|
49
|
+
export declare function peopleOfChange(owners: Readonly<Record<string, readonly string[]>>): string[];
|
|
50
|
+
export declare function routeOfQuestion(q: Pick<Question, "repo">, o: Parameters<typeof ownerOfQuestion>[1] & {
|
|
51
|
+
/** The people of each change (`peopleOfChange`), by change id. */
|
|
52
|
+
changePeople?: ReadonlyMap<string, readonly string[]>;
|
|
53
|
+
}): QuestionRoute;
|
|
54
|
+
/** Whether a question is the person's: they are on its team, or one of its change's people. */
|
|
55
|
+
export declare function isPersonsQuestion(handle: string, route: QuestionRoute, teams: readonly Team[]): boolean;
|
|
56
|
+
/** The owner in a few words: "team-ledger (Ledger team)", "add-pins's people: ari, sam", or "no owner: why". */
|
|
57
|
+
export declare function ownerWords(o: QuestionRoute): string;
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { answerQuestion } from "./questions.js";
|
|
3
|
+
import { QuestionScopeLevel, type Question } from "./schema/question.js";
|
|
4
|
+
/**
|
|
5
|
+
* The assistant proposes, a person confirms (ADR 0144, Q5). The `/atticus-propose` step reads the
|
|
6
|
+
* code and config behind each open question and writes a proposed answer beside it, in
|
|
7
|
+
* `proposals/questions/<id>.yaml` (under `.atticus/` in a repo adopted in place), with the lines
|
|
8
|
+
* it rests on. It never answers: the question file is untouched until a person accepts.
|
|
9
|
+
*
|
|
10
|
+
* Every citation is checked here, deterministically, before a proposal is shown: its repo is the
|
|
11
|
+
* question's or one a manifest lists, and has a checkout here (only a change's own question cites
|
|
12
|
+
* the metarepo, and never Atticus's own folders: proposals, questions, facts, knowledge, judgments,
|
|
13
|
+
* runs); the file is in that checkout once links are followed; the line is there; and the quoted
|
|
14
|
+
* words are on it (spacing, curly quotes and case aside, as `quotedIn`). A refused citation's
|
|
15
|
+
* problem never says what the file holds. A proposal that fails is never shown as a proposal, only as its problems.
|
|
16
|
+
* `acceptProposal` checks it again and records the answer as the person's (`answerQuestion`).
|
|
17
|
+
*
|
|
18
|
+
* The proposals folder holds drafts for a person to review, not a contract. An accepted answer
|
|
19
|
+
* records, in the question file, that it was a proposal (ADR 0153): who proposed it, when, and the
|
|
20
|
+
* lines it cited.
|
|
21
|
+
*/
|
|
22
|
+
export declare const QUESTION_PROPOSAL_SCHEMA_VERSION: 1;
|
|
23
|
+
/** A line the proposal rests on (the same shape an accepted answer keeps, ADR 0153). */
|
|
24
|
+
export declare const ProposalCite: z.ZodObject<{
|
|
25
|
+
repo: z.ZodOptional<z.ZodString>;
|
|
26
|
+
file: z.ZodString;
|
|
27
|
+
line: z.ZodNumber;
|
|
28
|
+
quote: z.ZodString;
|
|
29
|
+
}, z.core.$strict>;
|
|
30
|
+
export type ProposalCite = z.infer<typeof ProposalCite>;
|
|
31
|
+
export declare const QuestionProposal: z.ZodObject<{
|
|
32
|
+
schemaVersion: z.ZodLiteral<1>;
|
|
33
|
+
answer: z.ZodObject<{
|
|
34
|
+
option: z.ZodOptional<z.ZodNumber>;
|
|
35
|
+
text: z.ZodOptional<z.ZodString>;
|
|
36
|
+
}, z.core.$strict>;
|
|
37
|
+
why: z.ZodString;
|
|
38
|
+
cites: z.ZodArray<z.ZodObject<{
|
|
39
|
+
repo: z.ZodOptional<z.ZodString>;
|
|
40
|
+
file: z.ZodString;
|
|
41
|
+
line: z.ZodNumber;
|
|
42
|
+
quote: z.ZodString;
|
|
43
|
+
}, z.core.$strict>>;
|
|
44
|
+
by: z.ZodString;
|
|
45
|
+
at: z.ZodISODateTime;
|
|
46
|
+
}, z.core.$strict>;
|
|
47
|
+
export type QuestionProposal = z.infer<typeof QuestionProposal>;
|
|
48
|
+
/** Where a question's proposal lives, relative to the root. */
|
|
49
|
+
export declare const proposalRelOf: (root: string, id: string) => string;
|
|
50
|
+
/** A proposal as read and checked. `ok` only when it read and every check passed. */
|
|
51
|
+
export interface CheckedProposal {
|
|
52
|
+
id: string;
|
|
53
|
+
/** Relative to the root. */
|
|
54
|
+
file: string;
|
|
55
|
+
proposal?: QuestionProposal;
|
|
56
|
+
ok: boolean;
|
|
57
|
+
/** Its question is answered, retired or gone: nothing to propose. */
|
|
58
|
+
stale?: true;
|
|
59
|
+
problems: string[];
|
|
60
|
+
}
|
|
61
|
+
/** The problems of one proposal against its question and the files it cites; none: it holds. */
|
|
62
|
+
export declare function checkProposal(root: string, q: Question, p: QuestionProposal): Promise<string[]>;
|
|
63
|
+
/** Every proposal on file, each read and checked against its question; by question id. */
|
|
64
|
+
export declare function checkedProposals(root: string): Promise<CheckedProposal[]>;
|
|
65
|
+
/** One question's proposal, checked; undefined when there is none. */
|
|
66
|
+
export declare function proposalOf(root: string, id: string): Promise<CheckedProposal | undefined>;
|
|
67
|
+
/**
|
|
68
|
+
* A person accepts the proposal: checked again, then written as their answer, by them, at the
|
|
69
|
+
* scope they confirm (the question's own by default). Refused when there is none or it fails.
|
|
70
|
+
*/
|
|
71
|
+
export declare function acceptProposal(root: string, id: string, a: {
|
|
72
|
+
by: string;
|
|
73
|
+
at: string;
|
|
74
|
+
scope?: QuestionScopeLevel;
|
|
75
|
+
repoType?: string;
|
|
76
|
+
match?: string;
|
|
77
|
+
}): ReturnType<typeof answerQuestion>;
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import { BUILT_IN_ROLES } from "./schema/orgpack.js";
|
|
2
|
+
import { type Question, type QuestionAsks, type QuestionRole } from "./schema/question.js";
|
|
3
|
+
/**
|
|
4
|
+
* The role that owns what a step asks: the stage's own for a change's stage (`change-feature`,
|
|
5
|
+
* `change-stories`, a task's run), else, for a step that serves every stage (a context gap, a
|
|
6
|
+
* knowledge conflict), the stage its rerun command names. Undefined outside a change's phases.
|
|
7
|
+
*/
|
|
8
|
+
export declare function roleOfStep(step: string, rerun?: string): QuestionRole | undefined;
|
|
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"> & {
|
|
19
|
+
role?: 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[];
|
|
72
|
+
/** A custom role of roles.yaml (`custom`): its id and the built-in role it is based on. */
|
|
73
|
+
export interface CustomRole {
|
|
74
|
+
id: string;
|
|
75
|
+
basedOn: (typeof BUILT_IN_ROLES)[number] | string;
|
|
76
|
+
}
|
|
77
|
+
/** The question role of an owner key in change.yaml (`architect`, or a custom role of roles.yaml). */
|
|
78
|
+
export declare function roleOfOwner(key: string, custom?: readonly CustomRole[]): QuestionRole | undefined;
|
|
79
|
+
/**
|
|
80
|
+
* The roles a person has on a change: every owner key of its change.yaml that names them, as a
|
|
81
|
+
* question role, once each, in the order of the phases.
|
|
82
|
+
*/
|
|
83
|
+
export declare function rolesOfPerson(handle: string, owners: Readonly<Record<string, readonly string[]>>, custom?: readonly CustomRole[]): QuestionRole[];
|
|
84
|
+
export {};
|
package/npm/core/questions.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { type JudgmentStore } from "./judgments.js";
|
|
2
|
-
import { Question, 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
|
|
@@ -21,6 +21,21 @@ export declare function questionId(o: {
|
|
|
21
21
|
question: string;
|
|
22
22
|
evidence: string[];
|
|
23
23
|
}): string;
|
|
24
|
+
/** The step a critic knowledge gap's owner question is asked by (ninth UX walk). */
|
|
25
|
+
export declare const ASKED_GAP_STEP = "critic-ask";
|
|
26
|
+
/**
|
|
27
|
+
* Ninth UX walk: the id of the owner question a person's Ask raises for a critic knowledge gap.
|
|
28
|
+
* It is a fingerprint of the change and the gap's own fingerprint (its rule, artifact, record and
|
|
29
|
+
* summary), so the same gap carried to a later round or gate finds the same question.
|
|
30
|
+
*/
|
|
31
|
+
export declare function askedGapQuestionId(change: string, f: {
|
|
32
|
+
rule: string;
|
|
33
|
+
artifact: string;
|
|
34
|
+
locator: {
|
|
35
|
+
record?: string | undefined;
|
|
36
|
+
};
|
|
37
|
+
summary: string;
|
|
38
|
+
}): string;
|
|
24
39
|
/** Who asked: the step, the repo, the command as typed, the command that reads the answer. */
|
|
25
40
|
export interface AskedBy {
|
|
26
41
|
step: string;
|
|
@@ -32,6 +47,25 @@ export interface AskedBy {
|
|
|
32
47
|
}
|
|
33
48
|
/** An open question from what an AI step raised. */
|
|
34
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>;
|
|
61
|
+
/**
|
|
62
|
+
* Write a question's file. With `before` (the text it was read as), only when the file still
|
|
63
|
+
* holds that text: a change made meanwhile (a person's answer in the app, another command) is
|
|
64
|
+
* never overwritten, and FileChangedError says so instead (round 46).
|
|
65
|
+
*/
|
|
66
|
+
/** A question's file, and the text `writeQuestion` writes there (a rename computes it first, ADR 0195). */
|
|
67
|
+
export declare const questionFileOf: (root: string, id: string) => string;
|
|
68
|
+
export declare const questionFileText: (q: Question) => string;
|
|
35
69
|
/**
|
|
36
70
|
* Write a question as it is (a person's comment on a critic finding, ADR 0124 addendum D-app,
|
|
37
71
|
* is a question they answered as they asked it). Every other writer goes through
|
|
@@ -154,6 +188,14 @@ export interface RaiseOptions {
|
|
|
154
188
|
hold?: (q: Question, answered: Question[]) => boolean;
|
|
155
189
|
/** Where judgments are kept; default the metarepo's judgments/. */
|
|
156
190
|
judgments?: JudgmentStore;
|
|
191
|
+
/**
|
|
192
|
+
* Beta.12: an open, unanswered question on file by the draft's id, that this step asked, gets
|
|
193
|
+
* the draft's options and words in place (the same id, its history kept), so what a step
|
|
194
|
+
* offers now (ranked suggestions, their reasons, a repo read since) reaches a question asked
|
|
195
|
+
* before. Returned in `refreshed` (and `known`). An answered or retired question is never
|
|
196
|
+
* touched.
|
|
197
|
+
*/
|
|
198
|
+
refresh?: boolean;
|
|
157
199
|
}
|
|
158
200
|
/** A question held back: the one it would have been, and the answered ones that may decide it. */
|
|
159
201
|
export interface HeldQuestion {
|
|
@@ -178,7 +220,8 @@ export declare function sameTarget(a: {
|
|
|
178
220
|
}, repo?: string): boolean;
|
|
179
221
|
/**
|
|
180
222
|
* 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
|
|
223
|
+
* left as it is and returned in `known` (with `refresh`, an open one this step asked takes the
|
|
224
|
+
* draft's options and words first). Otherwise it is weighed against the questions on file
|
|
182
225
|
* for the same repo:
|
|
183
226
|
* 1. the veto: the two name different ids, fields or numbers, so they differ;
|
|
184
227
|
* 2. the step's own reading (`sameAs`), when the id is a candidate and its words are in it;
|
|
@@ -198,14 +241,22 @@ export declare function raiseQuestions(root: string, drafts: QuestionDraft[], by
|
|
|
198
241
|
held: HeldQuestion[];
|
|
199
242
|
/** The answered questions whose answer decides a draft, by the draft's index (ADR 0117 addendum). */
|
|
200
243
|
decidedBy: Map<number, Question>;
|
|
244
|
+
/** With `refresh`: open questions on file that took the draft's options and words. */
|
|
245
|
+
refreshed: Question[];
|
|
201
246
|
}>;
|
|
202
247
|
/**
|
|
203
|
-
* Rewrite questions/<id>.yaml files written at question schema version 1
|
|
204
|
-
* 0117
|
|
205
|
-
* relative to the root; with dryRun, the files it
|
|
248
|
+
* Rewrite questions/<id>.yaml files written at an older question schema version (1, ADR 0078;
|
|
249
|
+
* 2, ADR 0117; 3, ADR 0153; 4, ADR 0162; 5, ADR 0181) at the current one (6, ADR 0191): only the
|
|
250
|
+
* version changes, since what each version adds is optional. Returns the files, relative to the root; with dryRun, the files it
|
|
251
|
+
* would rewrite.
|
|
206
252
|
*/
|
|
207
253
|
export declare function migrateQuestions(root: string, o?: {
|
|
208
254
|
dryRun?: boolean;
|
|
255
|
+
/** Round 49: the files left as they are, with why (a file not named by its question's id). */
|
|
256
|
+
problems?: {
|
|
257
|
+
file: string;
|
|
258
|
+
message: string;
|
|
259
|
+
}[];
|
|
209
260
|
}): Promise<string[]>;
|
|
210
261
|
/** What a step says of a question it reused: who asked it first, and that it waits on it. */
|
|
211
262
|
export declare const reusedLine: (q: Question) => string;
|
|
@@ -225,6 +276,15 @@ export declare function retireQuestion(root: string, id: string, o: {
|
|
|
225
276
|
replacedBy?: string[];
|
|
226
277
|
at: string;
|
|
227
278
|
}): Promise<Question>;
|
|
279
|
+
/**
|
|
280
|
+
* ADR 0162 (F8): open an answered targets question again, because the code read since disagrees
|
|
281
|
+
* with its answer (the repo it named has no route that serves the call). The answer it had is
|
|
282
|
+
* kept under `reopened` with why, so the person sees what they said and what the code says.
|
|
283
|
+
*/
|
|
284
|
+
export declare function reopenQuestion(root: string, id: string, o: {
|
|
285
|
+
why: string;
|
|
286
|
+
at: string;
|
|
287
|
+
}): Promise<Question>;
|
|
228
288
|
export declare function answerWords(q: Question): string | undefined;
|
|
229
289
|
/**
|
|
230
290
|
* An answer as a step's next prompt gives it (B-run2-fixes 8): the option picked with what it
|
|
@@ -243,9 +303,49 @@ export interface AnswerInput {
|
|
|
243
303
|
scope?: QuestionScopeLevel;
|
|
244
304
|
/** The repo type, when the person widens a repo question to its type. */
|
|
245
305
|
repoType?: string;
|
|
246
|
-
|
|
306
|
+
/**
|
|
307
|
+
* ADR 0153 (Q2): the rule the answer covers, for a target or hosts question: a host pattern
|
|
308
|
+
* (`*.payments.forge.internal`) or a path prefix (`/forge/limits/**`).
|
|
309
|
+
*/
|
|
310
|
+
match?: string;
|
|
311
|
+
/** ADR 0153 (Q5): the assistant's proposal this answer accepts (acceptProposal sets it). */
|
|
312
|
+
proposal?: NonNullable<Question["answer"]>["proposal"];
|
|
313
|
+
/**
|
|
314
|
+
* Review item 14: a file change the answer brings (a system written into the profile, ADR
|
|
315
|
+
* 0162), made only once the answer is checked and just before it is written. When it throws,
|
|
316
|
+
* nothing is answered (a `bad-answer` with its first line).
|
|
317
|
+
*/
|
|
318
|
+
beforeWrite?: () => Promise<void>;
|
|
319
|
+
/**
|
|
320
|
+
* The person (their Git user); or, ADR 0181, the AI with its runtime and run, for a decision
|
|
321
|
+
* Atticus applies from an AI run (only an option on file, of a targets question, at the repo).
|
|
322
|
+
*/
|
|
323
|
+
by: string | AiBy;
|
|
247
324
|
at: string;
|
|
325
|
+
/** ADR 0181: the batch applying it (by AI, or by a person's rule). */
|
|
326
|
+
batch?: string;
|
|
327
|
+
/** ADR 0181: a person's rule applies it, from their correction. */
|
|
328
|
+
rule?: AppliedRule;
|
|
329
|
+
/**
|
|
330
|
+
* Beta.24 review: Ignore, for a question about where calls go: they aren't real calls (CI/CD, a
|
|
331
|
+
* test, a template), so the join leaves them. In place of option and text; the reason, when
|
|
332
|
+
* given, is the answer's words (`Ignore: <reason>`), else the Ignore option is picked (added to
|
|
333
|
+
* the question's options when it was asked before Ignore was offered).
|
|
334
|
+
*/
|
|
335
|
+
ignore?: {
|
|
336
|
+
reason?: string;
|
|
337
|
+
};
|
|
338
|
+
/**
|
|
339
|
+
* Beta.24 review: the id of the system `beforeWrite` adds to the profile, which the answer's
|
|
340
|
+
* words name, so they aren't refused as naming nothing.
|
|
341
|
+
*/
|
|
342
|
+
adds?: string;
|
|
248
343
|
}
|
|
344
|
+
/**
|
|
345
|
+
* Whether a host a hosts question asks about (`localhost:9966`, `limits.payments.forge.internal`)
|
|
346
|
+
* is one a rule's host pattern covers, as the manifest matches hosts.
|
|
347
|
+
*/
|
|
348
|
+
export declare function hostRuleCovers(pattern: string, asked: string): boolean;
|
|
249
349
|
/**
|
|
250
350
|
* Record a person's answer in the question's file. A repo-type answer also goes, as a line
|
|
251
351
|
* under "## Answers", in the type's skill file when that file is there; the path is kept in
|
|
@@ -263,5 +363,22 @@ export declare function answerQuestion(root: string, id: string, a: AnswerInput)
|
|
|
263
363
|
host: string;
|
|
264
364
|
manifest: string;
|
|
265
365
|
added: boolean;
|
|
366
|
+
basePath?: string;
|
|
367
|
+
};
|
|
368
|
+
/**
|
|
369
|
+
* ADR 0153 (Q2): the other open hosts questions the answer's host pattern covers, retired as
|
|
370
|
+
* answered by it.
|
|
371
|
+
*/
|
|
372
|
+
covered?: string[];
|
|
373
|
+
/**
|
|
374
|
+
* For a hosts question answered with an outside system (O1): the system written to the
|
|
375
|
+
* profile, with the host as its alias.
|
|
376
|
+
*/
|
|
377
|
+
system?: {
|
|
378
|
+
id: string;
|
|
379
|
+
host: string;
|
|
380
|
+
boundary: "internal" | "vendor";
|
|
381
|
+
profile: string;
|
|
382
|
+
added: boolean;
|
|
266
383
|
};
|
|
267
384
|
}>;
|