@maycombhq/sdk 2.0.0-beta.2 → 2.0.0-beta.21
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 +360 -0
- package/npm/core/api.d.ts +5806 -1212
- package/npm/core/audit.d.ts +165 -0
- package/npm/core/catalog.d.ts +220 -66
- package/npm/core/contract-check.d.ts +261 -0
- package/npm/core/decision-batches.d.ts +29 -0
- package/npm/core/declared-links.d.ts +62 -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 +2 -0
- package/npm/core/facts-join-prototype.d.ts +66 -4
- package/npm/core/facts-join-vendor.d.ts +20 -2
- package/npm/core/facts-join.d.ts +320 -1
- package/npm/core/facts-terms.d.ts +108 -0
- package/npm/core/fs.d.ts +23 -4
- package/npm/core/host-questions.d.ts +93 -1
- package/npm/core/index.d.ts +22 -0
- package/npm/core/link-candidates.d.ts +103 -0
- package/npm/core/link-evidence.d.ts +212 -0
- package/npm/core/manifest-edit.d.ts +53 -4
- package/npm/core/merge.d.ts +28 -0
- package/npm/core/metarepo.d.ts +18 -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 +22 -6
- package/npm/core/orgpack-load.d.ts +19 -0
- package/npm/core/profile-migrate.d.ts +11 -0
- package/npm/core/question-order.d.ts +23 -0
- package/npm/core/question-owners.d.ts +53 -0
- package/npm/core/question-proposals.d.ts +77 -0
- package/npm/core/question-roles.d.ts +24 -0
- package/npm/core/questions.d.ts +85 -6
- package/npm/core/repo-reads.d.ts +44 -0
- package/npm/core/roles-migrate.d.ts +9 -0
- package/npm/core/runtime-migrate.d.ts +18 -0
- package/npm/core/schema/ai.d.ts +57 -9
- 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/fact-corrections.d.ts +96 -2
- package/npm/core/schema/facts.d.ts +410 -1
- package/npm/core/schema/kinds.d.ts +230 -66
- package/npm/core/schema/orgpack.d.ts +110 -7
- package/npm/core/schema/question.d.ts +228 -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 +7 -7
- package/npm/core/schema/scan-verify.d.ts +87 -45
- package/npm/core/schema/version.d.ts +4 -1
- package/npm/core/schema/workspace.d.ts +29 -11
- package/npm/core/shared-maps.d.ts +146 -0
- package/npm/core/stack-helpers.d.ts +32 -0
- package/npm/index.js +5614 -2343
- package/package.json +1 -1
package/npm/core/migrate.d.ts
CHANGED
|
@@ -14,8 +14,9 @@ export interface MigrationResult {
|
|
|
14
14
|
* current schema version, in canonical form. Readers accept old files anyway; migrating once
|
|
15
15
|
* keeps diffs clean afterwards. A file that isn't a catalog record (no known `kind`) is not
|
|
16
16
|
* touched, nor is an old one that fails C1: it is reported, so nothing is half-migrated.
|
|
17
|
-
* Version 1 → 2 (ADR 0031)
|
|
18
|
-
* `required` on a Schema field, and a migrated record gains none, since nothing
|
|
17
|
+
* Version 1 → 2 (ADR 0031), 2 → 3 (ADR 0125) and 3 → 4 (ADR 0164) change only `schemaVersion`:
|
|
18
|
+
* version 3 adds `required` on a Schema field, and a migrated record gains none, since nothing
|
|
19
|
+
* knew it; version 4 adds `protobuf` to a Schema's formats, which no older record can hold. The
|
|
19
20
|
* canonical form also writes list defaults a hand-written file left out, exactly as a scan
|
|
20
21
|
* would write the record. `versions` limits it to files at those versions (each `atticus
|
|
21
22
|
* upgrade` step lists its own); what it writes is always the current version.
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
import type { FactEnd, FactsJoinResult, JoinRepo } from "./facts-join.js";
|
|
2
|
+
import type { TermsResult, TermSeen } from "./facts-terms.js";
|
|
3
|
+
import type { Conventions } from "./schema/conventions.js";
|
|
4
|
+
import type { QuestionDraft } from "./schema/question.js";
|
|
5
|
+
import type { RepoType } from "./schema/repo-type.js";
|
|
6
|
+
import type { ChecklistRule } from "./schema/review.js";
|
|
7
|
+
/**
|
|
8
|
+
* Org notes (ADR 0163): what the organisation's terms mean in a kind of repo, and what must hold
|
|
9
|
+
* there, in its own words. Atticus never parses a note: it hands the notes of a repo's type, and
|
|
10
|
+
* the org-wide ones, to the assistant as data, numbered, and the assistant cites the one a term
|
|
11
|
+
* fact relies on. Everything that follows from them here is deterministic: the notes a read is
|
|
12
|
+
* given, the rule drafts offered for a person to review, the check an accepted rule runs, and the
|
|
13
|
+
* question an unknown term becomes.
|
|
14
|
+
*/
|
|
15
|
+
/** A note as a read is handed it: its number (from 1), its key, its words and where it is written. */
|
|
16
|
+
export interface NumberedNote {
|
|
17
|
+
n: number;
|
|
18
|
+
/**
|
|
19
|
+
* A short hash of its words (`noteKey`): what a term fact's `note` and a rule draft's id name,
|
|
20
|
+
* so reordering the notes points nothing at another note, and a changed note is told apart.
|
|
21
|
+
*/
|
|
22
|
+
key: string;
|
|
23
|
+
text: string;
|
|
24
|
+
/** `repo-types/<type>/type.yaml` or `conventions.yaml`, relative to the org pack. */
|
|
25
|
+
source: string;
|
|
26
|
+
/** The note's place in that file's `notes`, from 0. */
|
|
27
|
+
index: number;
|
|
28
|
+
}
|
|
29
|
+
/** A note's key: 8 hex digits of the sha256 of its words, spacing and letter case aside. */
|
|
30
|
+
export declare const noteKey: (text: string) => string;
|
|
31
|
+
/**
|
|
32
|
+
* The notes a read of a repo is handed: its repo type's first, then the org-wide ones, numbered
|
|
33
|
+
* from 1 in that order. Empty when neither has any, which is how a read without notes goes.
|
|
34
|
+
*/
|
|
35
|
+
export declare function notesFor(type: Pick<RepoType, "id" | "notes"> | undefined, conventions: Pick<Conventions, "notes"> | undefined): NumberedNote[];
|
|
36
|
+
/**
|
|
37
|
+
* The notes as the prompt gives them (review 6): one data block, each note one line, its number,
|
|
38
|
+
* its key and its words JSON-quoted, after the sentence that they are data, never instructions.
|
|
39
|
+
*/
|
|
40
|
+
export declare function notesText(notes: readonly NumberedNote[], repoType?: string): string;
|
|
41
|
+
/** The fewest words a term fact quotes a note by: fewer could be found in any note. */
|
|
42
|
+
export declare const NOTE_QUOTE_WORDS = 4;
|
|
43
|
+
/**
|
|
44
|
+
* Whether a term fact's `note` is one of the notes the read was given: a key one of them has, or
|
|
45
|
+
* at least four words found in one of them (spacing and letter case aside). Undefined when it is.
|
|
46
|
+
* `term-note-stale`: a key none of them has now, the note having been changed or removed since
|
|
47
|
+
* the read, so the term is read again by the notes as they are.
|
|
48
|
+
*/
|
|
49
|
+
export declare function noteProblem(note: string, notes: readonly NumberedNote[]): {
|
|
50
|
+
code: "term-meaning" | "term-note-stale";
|
|
51
|
+
message: string;
|
|
52
|
+
} | undefined;
|
|
53
|
+
/** A note reads as a rule when it says all, every or must. A draft only: a person decides. */
|
|
54
|
+
export declare const RULE_WORDS: RegExp;
|
|
55
|
+
/** The deterministic check a call rule runs (ADR 0163). */
|
|
56
|
+
export declare const CALL_SECURITY_CHECK = "call-security";
|
|
57
|
+
/** What a person says is done outside the repos, for a call the check would find. */
|
|
58
|
+
export interface DeclaredOutside {
|
|
59
|
+
repo: string;
|
|
60
|
+
/** The call's fact id; left out, every call of the repo the rule covers. */
|
|
61
|
+
call?: string;
|
|
62
|
+
why: string;
|
|
63
|
+
by: string;
|
|
64
|
+
}
|
|
65
|
+
/** The params of a `call-security` rule, as a person sets them. */
|
|
66
|
+
export interface CallSecurityParams {
|
|
67
|
+
/**
|
|
68
|
+
* The calls it covers: those to a system the profile gives boundary `vendor` (`vendor`), those
|
|
69
|
+
* to any system outside the estate, another team's included (`outside`), or every call.
|
|
70
|
+
*/
|
|
71
|
+
to: "vendor" | "outside" | "any";
|
|
72
|
+
/** The transport security the call that reaches the target must show. */
|
|
73
|
+
tls?: "mtls" | "tls";
|
|
74
|
+
/** Whether an auth must be shown on the call that reaches the target. */
|
|
75
|
+
auth?: boolean;
|
|
76
|
+
/** What a person says is done outside the repos: recorded as their word, never verified. */
|
|
77
|
+
declared?: DeclaredOutside[];
|
|
78
|
+
}
|
|
79
|
+
/** A rule's params read as `call-security` params, or why they can't be. */
|
|
80
|
+
export declare function callSecurityParams(params: Record<string, unknown>): CallSecurityParams | {
|
|
81
|
+
problem: string;
|
|
82
|
+
};
|
|
83
|
+
/**
|
|
84
|
+
* A checklist rule draft (C3, `status: draft`) for each note that reads as a rule, for a person
|
|
85
|
+
* to review and accept in a pull request. A note about calls and mTLS, TLS or auth is drafted as
|
|
86
|
+
* the deterministic `call-security` check with its params filled from the words it uses; any
|
|
87
|
+
* other as an AI check that quotes the note. The words only fill a draft: a person sets what the
|
|
88
|
+
* accepted rule checks, and the check itself reads facts, never the note.
|
|
89
|
+
*/
|
|
90
|
+
export declare function noteRuleDrafts(notes: readonly NumberedNote[]): ChecklistRule[];
|
|
91
|
+
/** What a call shows, and the line each rests on. */
|
|
92
|
+
interface Shown {
|
|
93
|
+
tls?: {
|
|
94
|
+
value: string;
|
|
95
|
+
at: string;
|
|
96
|
+
};
|
|
97
|
+
auth?: {
|
|
98
|
+
value: string;
|
|
99
|
+
at: string;
|
|
100
|
+
};
|
|
101
|
+
}
|
|
102
|
+
export interface CallSecurityResult {
|
|
103
|
+
/** The call the rule judges: the one that reaches the target (a gateway's forwarding call, or a service's own). */
|
|
104
|
+
call: FactEnd;
|
|
105
|
+
/** The gateway route it forwards from, when it does, then the call itself. */
|
|
106
|
+
chain: FactEnd[];
|
|
107
|
+
/** The calls of other repos that land on that route: the legs in front, never judged. */
|
|
108
|
+
callers: FactEnd[];
|
|
109
|
+
target?: string;
|
|
110
|
+
outcome: "pass" | "finding" | "declared";
|
|
111
|
+
/** What the call shows, cited. */
|
|
112
|
+
shown: Shown;
|
|
113
|
+
/** For a finding: what it doesn't show. */
|
|
114
|
+
missing?: ("tls" | "auth")[];
|
|
115
|
+
/** What its code cites as none, for what the rule asks: a finding no person's word covers. */
|
|
116
|
+
none?: Shown;
|
|
117
|
+
/** For a declared one: the person's word, never verified. */
|
|
118
|
+
declared?: DeclaredOutside;
|
|
119
|
+
message: string;
|
|
120
|
+
}
|
|
121
|
+
/** A system of the profiles, as `checkCallSecurity` tells a vendor from another team's system. */
|
|
122
|
+
export interface CallSecuritySystem {
|
|
123
|
+
id: string;
|
|
124
|
+
name?: string;
|
|
125
|
+
boundary: string;
|
|
126
|
+
aliases?: readonly string[];
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Every call a `call-security` rule covers, checked on the facts (ADR 0163, review 5): for
|
|
130
|
+
* `to: vendor`, each call the join leaves to a system the profiles give boundary `vendor`; for
|
|
131
|
+
* `to: outside`, each it leaves outside the estate (another team's system too); for `to: any`,
|
|
132
|
+
* every call. The leg judged is the one that reaches the target: the call itself, which for a
|
|
133
|
+
* gateway is its forwarding call. The legs in front of it (a caller's mTLS to the gateway, the
|
|
134
|
+
* route's own client-certificate check) are listed in `callers` and `chain`, never counted. It
|
|
135
|
+
* passes when the call shows the TLS asked for (`tls` with its `tlsCite`) and, if asked, an auth
|
|
136
|
+
* other than none (`auth` with its `authCite`); otherwise it is a finding for the call's repo.
|
|
137
|
+
* A person's word that it is done outside the repos is recorded as declared, theirs, never
|
|
138
|
+
* verified, except where the call's code cites `none` for what is asked: the code is right.
|
|
139
|
+
*/
|
|
140
|
+
export declare function checkCallSecurity(params: CallSecurityParams, input: {
|
|
141
|
+
repos: readonly JoinRepo[];
|
|
142
|
+
join: FactsJoinResult;
|
|
143
|
+
/** The profiles' systems, for each outside target's boundary. */
|
|
144
|
+
systems?: readonly CallSecuritySystem[];
|
|
145
|
+
}): CallSecurityResult[];
|
|
146
|
+
/** The step a term question is asked by. */
|
|
147
|
+
export declare const TERM_STEP = "term-meaning";
|
|
148
|
+
export interface TermQuestionDraft {
|
|
149
|
+
draft: QuestionDraft;
|
|
150
|
+
/** The repo the question is raised for (the group's first, by id). */
|
|
151
|
+
repo: string;
|
|
152
|
+
term: string;
|
|
153
|
+
file: string;
|
|
154
|
+
repoType?: string;
|
|
155
|
+
/** Every term fact the answer is about, by repo. */
|
|
156
|
+
terms: TermSeen[];
|
|
157
|
+
}
|
|
158
|
+
/**
|
|
159
|
+
* One question per term, file and repo type for the terms whose role is unknown (ADR 0163):
|
|
160
|
+
* "What does `cmdb` mean in userAccess.json across 3 forge-apigee-proxy repos?". The answer is
|
|
161
|
+
* meant to be saved as a note on the repo type (`atticus repo-type note`), so the next read of
|
|
162
|
+
* every repo of the type records the role, cited. A repo with no type is asked on its own.
|
|
163
|
+
*/
|
|
164
|
+
export declare function termQuestionDrafts(result: Pick<TermsResult, "terms">, typeOf: (repo: string) => string | undefined): TermQuestionDraft[];
|
|
165
|
+
/**
|
|
166
|
+
* The note an answered term question offers to save on its repo type: the person's own words,
|
|
167
|
+
* or the option they picked put as a plain sentence about the term and the file.
|
|
168
|
+
*/
|
|
169
|
+
export declare function termAnswerNote(o: {
|
|
170
|
+
term: string;
|
|
171
|
+
file: string;
|
|
172
|
+
option?: "owner" | "consumer" | "none";
|
|
173
|
+
text?: string;
|
|
174
|
+
}): string;
|
|
175
|
+
/** The term and file a term question asks about, read back from its words. */
|
|
176
|
+
export declare function termOfQuestion(question: string): {
|
|
177
|
+
term: string;
|
|
178
|
+
file: string;
|
|
179
|
+
} | undefined;
|
|
180
|
+
export {};
|
|
@@ -5,7 +5,7 @@ export declare const DEFAULT_CHANGE_TYPES: {
|
|
|
5
5
|
name: string;
|
|
6
6
|
phases: ("release" | "design" | "qa" | "define" | "plan" | "build")[];
|
|
7
7
|
artifacts: ("interfaces" | "data" | "ux" | "brief" | "proposal" | "specs" | "mappings" | "design" | "stories" | "tasks" | "snow")[];
|
|
8
|
-
lenses: ("true" | "complete" | "safe" | "ship" | "business" | "architecture" | "story" | "ux" | "delivery" | "code-and-test"
|
|
8
|
+
lenses: ("release" | "true" | "complete" | "safe" | "ship" | "business" | "architecture" | "story" | "ux" | "delivery" | "code-and-test")[];
|
|
9
9
|
approvals: Partial<Record<"release" | "design" | "qa" | "define" | "plan" | "build", string[]>>;
|
|
10
10
|
postReleaseReview: boolean;
|
|
11
11
|
description?: string | undefined;
|
|
@@ -30,7 +30,12 @@ export declare const DEFAULT_GATES: {
|
|
|
30
30
|
}[];
|
|
31
31
|
};
|
|
32
32
|
export declare const DEFAULT_ROLES: {
|
|
33
|
-
schemaVersion: 1;
|
|
33
|
+
schemaVersion: 1 | 2;
|
|
34
|
+
teams: {
|
|
35
|
+
id: string;
|
|
36
|
+
people: string[];
|
|
37
|
+
name?: string | undefined;
|
|
38
|
+
}[];
|
|
34
39
|
custom: {
|
|
35
40
|
id: string;
|
|
36
41
|
name: string;
|
|
@@ -52,7 +57,7 @@ export declare const DEFAULT_ROLES: {
|
|
|
52
57
|
}[];
|
|
53
58
|
};
|
|
54
59
|
export declare const DEFAULT_RUNTIME: {
|
|
55
|
-
schemaVersion: 1 | 2;
|
|
60
|
+
schemaVersion: 1 | 2 | 3 | 4;
|
|
56
61
|
assistants: {
|
|
57
62
|
allowed: ("copilot" | "claude-code" | "cursor" | "gemini-cli" | "windsurf" | "agents-md")[];
|
|
58
63
|
default: "copilot" | "claude-code" | "cursor" | "gemini-cli" | "windsurf" | "agents-md";
|
|
@@ -60,8 +65,8 @@ export declare const DEFAULT_RUNTIME: {
|
|
|
60
65
|
editors: ("vscode" | "intellij")[];
|
|
61
66
|
ai: "on" | "text-only" | "off";
|
|
62
67
|
modes: {
|
|
63
|
-
allowed: ("model" | "hand-off" | "headless-claude-code")[];
|
|
64
|
-
default: "model" | "hand-off" | "headless-claude-code";
|
|
68
|
+
allowed: ("model" | "hand-off" | "headless-claude-code" | "copilot-acp")[];
|
|
69
|
+
default: "model" | "hand-off" | "headless-claude-code" | "copilot-acp";
|
|
65
70
|
};
|
|
66
71
|
models: {
|
|
67
72
|
allowed: string[];
|
|
@@ -128,13 +133,24 @@ export declare const DEFAULT_RUNTIME: {
|
|
|
128
133
|
expansion: boolean;
|
|
129
134
|
rerank: boolean;
|
|
130
135
|
} | undefined;
|
|
136
|
+
copilotAcp?: {
|
|
137
|
+
command?: string | undefined;
|
|
138
|
+
model?: string | undefined;
|
|
139
|
+
maxTurns?: number | undefined;
|
|
140
|
+
timeoutMs?: number | undefined;
|
|
141
|
+
} | undefined;
|
|
142
|
+
decide?: {
|
|
143
|
+
links: "auto" | "propose";
|
|
144
|
+
questions: "auto" | "propose";
|
|
145
|
+
minPrecision: number;
|
|
146
|
+
} | undefined;
|
|
131
147
|
buildEngine?: {
|
|
132
148
|
default: "atticus" | "speckit";
|
|
133
149
|
perRepo: Record<string, "atticus" | "speckit">;
|
|
134
150
|
} | undefined;
|
|
135
151
|
};
|
|
136
152
|
export declare const DEFAULT_SOURCES: {
|
|
137
|
-
schemaVersion:
|
|
153
|
+
schemaVersion: 1 | 2 | 3;
|
|
138
154
|
layout: {
|
|
139
155
|
openspec: string;
|
|
140
156
|
catalog: string;
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { FrameworkModel } from "./schema/frameworks.js";
|
|
2
2
|
import { ScanSettings } from "./schema/scan-settings.js";
|
|
3
3
|
import { RepoType } from "./schema/repo-type.js";
|
|
4
|
+
import { type LoadedComponentType } from "./schema/component-type.js";
|
|
4
5
|
import { ModelProviderPlugin, ScannerPlugin } from "./schema/plugin.js";
|
|
5
6
|
import { SpecTemplate } from "./schema/spec.js";
|
|
6
7
|
import type { z } from "zod";
|
|
@@ -9,6 +10,7 @@ import { Dialect } from "./schema/dialect.js";
|
|
|
9
10
|
import { ChangeTypes, Estimates, Gates, OpenSpecSettings, IntegrationPattern, PackManifest, Procedure, Profile, Roles, Runtime, ServiceRequestTemplate, SkillMeta, Sources, TestStrategy } from "./schema/orgpack.js";
|
|
10
11
|
import { ChecklistPack } from "./schema/review.js";
|
|
11
12
|
import { RepoManifest } from "./schema/workspace.js";
|
|
13
|
+
import { Conventions } from "./schema/conventions.js";
|
|
12
14
|
export interface OrgPackProblem {
|
|
13
15
|
/** File relative to the org-pack folder. */
|
|
14
16
|
file: string;
|
|
@@ -37,6 +39,8 @@ export interface OrgPack {
|
|
|
37
39
|
scanSettings: ScanSettings[];
|
|
38
40
|
/** Repo types (ADR 0077), from repo-types/<id>/type.yaml. */
|
|
39
41
|
repoTypes: RepoType[];
|
|
42
|
+
/** The organisation's component types (ADR 0180), from component-types/<id>/type.yaml, with their notes.md. */
|
|
43
|
+
componentTypes: LoadedComponentType[];
|
|
40
44
|
/** Scanner plugins (ADR 0080), from plugins/<id>/plugin.yaml, with their folders. */
|
|
41
45
|
plugins: {
|
|
42
46
|
manifest: ScannerPlugin;
|
|
@@ -57,6 +61,11 @@ export interface OrgPack {
|
|
|
57
61
|
/** Procedures (ADR 0033), from process/procedures/. */
|
|
58
62
|
procedures: Procedure[];
|
|
59
63
|
agents: AgentDefinition[];
|
|
64
|
+
/**
|
|
65
|
+
* The house conventions a read leans on (ADR 0147), from conventions.yaml: the built-in lists
|
|
66
|
+
* when the pack has none. Optional so a pack built in code (a test's) needs none.
|
|
67
|
+
*/
|
|
68
|
+
conventions?: Conventions;
|
|
60
69
|
/** Files that came from built-in defaults because the pack doesn't have them. */
|
|
61
70
|
defaulted: string[];
|
|
62
71
|
problems: OrgPackProblem[];
|
|
@@ -84,3 +93,13 @@ export declare function loadEstimates(dir: string): Promise<{
|
|
|
84
93
|
estimates?: Estimates;
|
|
85
94
|
problem?: string;
|
|
86
95
|
}>;
|
|
96
|
+
/** The conventions of a pack (ADR 0147), its defaults when it has none. */
|
|
97
|
+
export declare const conventionsOf: (op: Pick<OrgPack, "conventions"> | undefined) => Conventions;
|
|
98
|
+
/** What the estate join takes from a pack's conventions (ADR 0147): its facing words and bundle folders. */
|
|
99
|
+
export declare function joinConventions(op: Pick<OrgPack, "conventions"> | undefined): {
|
|
100
|
+
facing: {
|
|
101
|
+
internal: readonly string[];
|
|
102
|
+
external: readonly string[];
|
|
103
|
+
};
|
|
104
|
+
bundleFolders: readonly string[];
|
|
105
|
+
};
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* profile.yaml version 1 → 2 (ADR 0162 amendment). Version 2 adds a system's `topics`; a file
|
|
3
|
+
* without them names no topic, as version 1 did, so the step writes the new number only and keeps
|
|
4
|
+
* the file's comments, order and line layout. Nothing is moved from `aliases` to `topics`: which
|
|
5
|
+
* alias is a topic is a person's call. A version-1 profile stays valid, so `atticus upgrade` has no
|
|
6
|
+
* step for it; `addProfileSystem` applies this when it writes a topic.
|
|
7
|
+
*/
|
|
8
|
+
export declare function migrateProfileText(text: string): {
|
|
9
|
+
text: string;
|
|
10
|
+
changed: boolean;
|
|
11
|
+
};
|
|
@@ -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,53 @@
|
|
|
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
|
+
problem?: string;
|
|
21
|
+
}>;
|
|
22
|
+
/** The teams a person is on, by their Git handle. */
|
|
23
|
+
export declare function teamsOfPerson(handle: string, teams: readonly Team[]): Team[];
|
|
24
|
+
/**
|
|
25
|
+
* Who a question goes to: the team the manifest names as its repo's owner, with the name
|
|
26
|
+
* roles.yaml gives it. A change's own questions, and a repo no manifest lists, have no team.
|
|
27
|
+
*/
|
|
28
|
+
export declare function ownerOfQuestion(q: Pick<Question, "repo">, o: {
|
|
29
|
+
/** Each listed repo's owner, from the repo manifests. */
|
|
30
|
+
owners: ReadonlyMap<string, string>;
|
|
31
|
+
teams: readonly Team[];
|
|
32
|
+
/** The ids of the changes, whose own questions are filed under them. */
|
|
33
|
+
changes?: ReadonlySet<string>;
|
|
34
|
+
}): QuestionOwner;
|
|
35
|
+
/**
|
|
36
|
+
* Who a question goes to, a change's people included (ADR 0153, Q4): a change's own question,
|
|
37
|
+
* filed under the change's id, goes to the people its change.yaml names under `owners`, whatever
|
|
38
|
+
* they do on it; every other question goes to its repo's team (`ownerOfQuestion`).
|
|
39
|
+
*/
|
|
40
|
+
export type QuestionRoute = QuestionOwner | {
|
|
41
|
+
change: string;
|
|
42
|
+
people: string[];
|
|
43
|
+
};
|
|
44
|
+
/** Everyone a change.yaml's `owners` names, by handle, once each, sorted. */
|
|
45
|
+
export declare function peopleOfChange(owners: Readonly<Record<string, readonly string[]>>): string[];
|
|
46
|
+
export declare function routeOfQuestion(q: Pick<Question, "repo">, o: Parameters<typeof ownerOfQuestion>[1] & {
|
|
47
|
+
/** The people of each change (`peopleOfChange`), by change id. */
|
|
48
|
+
changePeople?: ReadonlyMap<string, readonly string[]>;
|
|
49
|
+
}): QuestionRoute;
|
|
50
|
+
/** Whether a question is the person's: they are on its team, or one of its change's people. */
|
|
51
|
+
export declare function isPersonsQuestion(handle: string, route: QuestionRoute, teams: readonly Team[]): boolean;
|
|
52
|
+
/** The owner in a few words: "team-ledger (Ledger team)", "add-pins's people: ari, sam", or "no owner: why". */
|
|
53
|
+
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,24 @@
|
|
|
1
|
+
import { BUILT_IN_ROLES } from "./schema/orgpack.js";
|
|
2
|
+
import { type Question, 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
|
+
/** 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"> & {
|
|
11
|
+
role?: QuestionRole | undefined;
|
|
12
|
+
}): QuestionRole | undefined;
|
|
13
|
+
/** A custom role of roles.yaml (`custom`): its id and the built-in role it is based on. */
|
|
14
|
+
export interface CustomRole {
|
|
15
|
+
id: string;
|
|
16
|
+
basedOn: (typeof BUILT_IN_ROLES)[number] | string;
|
|
17
|
+
}
|
|
18
|
+
/** The question role of an owner key in change.yaml (`architect`, or a custom role of roles.yaml). */
|
|
19
|
+
export declare function roleOfOwner(key: string, custom?: readonly CustomRole[]): QuestionRole | undefined;
|
|
20
|
+
/**
|
|
21
|
+
* The roles a person has on a change: every owner key of its change.yaml that names them, as a
|
|
22
|
+
* question role, once each, in the order of the phases.
|
|
23
|
+
*/
|
|
24
|
+
export declare function rolesOfPerson(handle: string, owners: Readonly<Record<string, readonly string[]>>, custom?: readonly CustomRole[]): QuestionRole[];
|
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 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;
|
|
@@ -154,6 +169,14 @@ export interface RaiseOptions {
|
|
|
154
169
|
hold?: (q: Question, answered: Question[]) => boolean;
|
|
155
170
|
/** Where judgments are kept; default the metarepo's judgments/. */
|
|
156
171
|
judgments?: JudgmentStore;
|
|
172
|
+
/**
|
|
173
|
+
* Beta.12: an open, unanswered question on file by the draft's id, that this step asked, gets
|
|
174
|
+
* the draft's options and words in place (the same id, its history kept), so what a step
|
|
175
|
+
* offers now (ranked suggestions, their reasons, a repo read since) reaches a question asked
|
|
176
|
+
* before. Returned in `refreshed` (and `known`). An answered or retired question is never
|
|
177
|
+
* touched.
|
|
178
|
+
*/
|
|
179
|
+
refresh?: boolean;
|
|
157
180
|
}
|
|
158
181
|
/** A question held back: the one it would have been, and the answered ones that may decide it. */
|
|
159
182
|
export interface HeldQuestion {
|
|
@@ -178,7 +201,8 @@ export declare function sameTarget(a: {
|
|
|
178
201
|
}, repo?: string): boolean;
|
|
179
202
|
/**
|
|
180
203
|
* 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
|
|
204
|
+
* left as it is and returned in `known` (with `refresh`, an open one this step asked takes the
|
|
205
|
+
* draft's options and words first). Otherwise it is weighed against the questions on file
|
|
182
206
|
* for the same repo:
|
|
183
207
|
* 1. the veto: the two name different ids, fields or numbers, so they differ;
|
|
184
208
|
* 2. the step's own reading (`sameAs`), when the id is a candidate and its words are in it;
|
|
@@ -198,11 +222,14 @@ export declare function raiseQuestions(root: string, drafts: QuestionDraft[], by
|
|
|
198
222
|
held: HeldQuestion[];
|
|
199
223
|
/** The answered questions whose answer decides a draft, by the draft's index (ADR 0117 addendum). */
|
|
200
224
|
decidedBy: Map<number, Question>;
|
|
225
|
+
/** With `refresh`: open questions on file that took the draft's options and words. */
|
|
226
|
+
refreshed: Question[];
|
|
201
227
|
}>;
|
|
202
228
|
/**
|
|
203
|
-
* Rewrite questions/<id>.yaml files written at question schema version 1
|
|
204
|
-
* 0117): only the version changes, since what
|
|
205
|
-
* relative to the root; with dryRun, the files it
|
|
229
|
+
* 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
|
|
232
|
+
* would rewrite.
|
|
206
233
|
*/
|
|
207
234
|
export declare function migrateQuestions(root: string, o?: {
|
|
208
235
|
dryRun?: boolean;
|
|
@@ -225,6 +252,15 @@ export declare function retireQuestion(root: string, id: string, o: {
|
|
|
225
252
|
replacedBy?: string[];
|
|
226
253
|
at: string;
|
|
227
254
|
}): Promise<Question>;
|
|
255
|
+
/**
|
|
256
|
+
* ADR 0162 (F8): open an answered targets question again, because the code read since disagrees
|
|
257
|
+
* with its answer (the repo it named has no route that serves the call). The answer it had is
|
|
258
|
+
* kept under `reopened` with why, so the person sees what they said and what the code says.
|
|
259
|
+
*/
|
|
260
|
+
export declare function reopenQuestion(root: string, id: string, o: {
|
|
261
|
+
why: string;
|
|
262
|
+
at: string;
|
|
263
|
+
}): Promise<Question>;
|
|
228
264
|
export declare function answerWords(q: Question): string | undefined;
|
|
229
265
|
/**
|
|
230
266
|
* An answer as a step's next prompt gives it (B-run2-fixes 8): the option picked with what it
|
|
@@ -243,9 +279,35 @@ export interface AnswerInput {
|
|
|
243
279
|
scope?: QuestionScopeLevel;
|
|
244
280
|
/** The repo type, when the person widens a repo question to its type. */
|
|
245
281
|
repoType?: string;
|
|
246
|
-
|
|
282
|
+
/**
|
|
283
|
+
* ADR 0153 (Q2): the rule the answer covers, for a target or hosts question: a host pattern
|
|
284
|
+
* (`*.payments.forge.internal`) or a path prefix (`/forge/limits/**`).
|
|
285
|
+
*/
|
|
286
|
+
match?: string;
|
|
287
|
+
/** ADR 0153 (Q5): the assistant's proposal this answer accepts (acceptProposal sets it). */
|
|
288
|
+
proposal?: NonNullable<Question["answer"]>["proposal"];
|
|
289
|
+
/**
|
|
290
|
+
* Review item 14: a file change the answer brings (a system written into the profile, ADR
|
|
291
|
+
* 0162), made only once the answer is checked and just before it is written. When it throws,
|
|
292
|
+
* nothing is answered (a `bad-answer` with its first line).
|
|
293
|
+
*/
|
|
294
|
+
beforeWrite?: () => Promise<void>;
|
|
295
|
+
/**
|
|
296
|
+
* The person (their Git user); or, ADR 0181, the AI with its runtime and run, for a decision
|
|
297
|
+
* Atticus applies from an AI run (only an option on file, of a targets question, at the repo).
|
|
298
|
+
*/
|
|
299
|
+
by: string | AiBy;
|
|
247
300
|
at: string;
|
|
301
|
+
/** ADR 0181: the batch applying it (by AI, or by a person's rule). */
|
|
302
|
+
batch?: string;
|
|
303
|
+
/** ADR 0181: a person's rule applies it, from their correction. */
|
|
304
|
+
rule?: AppliedRule;
|
|
248
305
|
}
|
|
306
|
+
/**
|
|
307
|
+
* Whether a host a hosts question asks about (`localhost:9966`, `limits.payments.forge.internal`)
|
|
308
|
+
* is one a rule's host pattern covers, as the manifest matches hosts.
|
|
309
|
+
*/
|
|
310
|
+
export declare function hostRuleCovers(pattern: string, asked: string): boolean;
|
|
249
311
|
/**
|
|
250
312
|
* Record a person's answer in the question's file. A repo-type answer also goes, as a line
|
|
251
313
|
* under "## Answers", in the type's skill file when that file is there; the path is kept in
|
|
@@ -263,5 +325,22 @@ export declare function answerQuestion(root: string, id: string, a: AnswerInput)
|
|
|
263
325
|
host: string;
|
|
264
326
|
manifest: string;
|
|
265
327
|
added: boolean;
|
|
328
|
+
basePath?: string;
|
|
329
|
+
};
|
|
330
|
+
/**
|
|
331
|
+
* ADR 0153 (Q2): the other open hosts questions the answer's host pattern covers, retired as
|
|
332
|
+
* answered by it.
|
|
333
|
+
*/
|
|
334
|
+
covered?: string[];
|
|
335
|
+
/**
|
|
336
|
+
* For a hosts question answered with an outside system (O1): the system written to the
|
|
337
|
+
* profile, with the host as its alias.
|
|
338
|
+
*/
|
|
339
|
+
system?: {
|
|
340
|
+
id: string;
|
|
341
|
+
host: string;
|
|
342
|
+
boundary: "internal" | "vendor";
|
|
343
|
+
profile: string;
|
|
344
|
+
added: boolean;
|
|
266
345
|
};
|
|
267
346
|
}>;
|