@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
|
@@ -28,21 +28,98 @@ export declare function setManifestDescription(root: string, repo: string, descr
|
|
|
28
28
|
* are in. The entry is written with the fields that are set and no more, and the whole manifest
|
|
29
29
|
* is checked before it is written, so a duplicate id or a password in the URL is refused here.
|
|
30
30
|
*/
|
|
31
|
-
export declare function addManifestRepo(root: string, platform: string, entry:
|
|
31
|
+
export declare function addManifestRepo(root: string, platform: string, entry: NewManifestRepo): Promise<ManifestFile>;
|
|
32
|
+
/** One repo to add to a manifest: the fields that are set, and no more. */
|
|
33
|
+
export interface NewManifestRepo {
|
|
32
34
|
id: string;
|
|
33
35
|
url: string;
|
|
34
36
|
type: string;
|
|
35
37
|
owner: string;
|
|
38
|
+
/** The branch to read, when known (a clone's current branch); the manifest's default is main. */
|
|
39
|
+
defaultBranch?: string;
|
|
36
40
|
system?: string;
|
|
37
41
|
component?: string;
|
|
38
42
|
description?: RepoDescription;
|
|
39
|
-
}
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* ADR 0190: many repos into a platform's manifest at once (the app's paste of ~40 clone URLs),
|
|
46
|
+
* as addManifestRepo adds one: appended in order, comments and order kept, the file's own line
|
|
47
|
+
* endings, the whole manifest checked before anything is written. An id another manifest (or
|
|
48
|
+
* an earlier entry of the batch) lists is refused, naming it. With `preview`, nothing is
|
|
49
|
+
* written: the lines it would change come back, for the app's diff before the write.
|
|
50
|
+
*/
|
|
51
|
+
export declare function addManifestRepos(root: string, platform: string, entries: readonly NewManifestRepo[], o?: {
|
|
52
|
+
preview?: boolean;
|
|
53
|
+
}): Promise<{
|
|
54
|
+
file: ManifestFile;
|
|
55
|
+
changes: LineChange[];
|
|
56
|
+
written: boolean;
|
|
57
|
+
}>;
|
|
58
|
+
/**
|
|
59
|
+
* F5: move a repo's id in the manifest that lists it, in place (comments and order kept). Refused
|
|
60
|
+
* when no manifest lists the repo, or any lists the new id already (ids are unique across every
|
|
61
|
+
* profile, ADR 0009). Only the id changes; the files filed under it are the caller's to move.
|
|
62
|
+
*/
|
|
63
|
+
export declare function renameManifestRepo(root: string, repo: string, to: string): Promise<ManifestFile>;
|
|
64
|
+
/**
|
|
65
|
+
* ADR 0195 (the rename computes before it writes): the manifest that lists a repo, with its
|
|
66
|
+
* text now and its text with the id moved (comments, order and line endings kept), checked as
|
|
67
|
+
* `renameManifestRepo` checks it, and nothing written. The caller writes `next` to `file.path`.
|
|
68
|
+
*/
|
|
69
|
+
export declare function renamedManifest(root: string, repo: string, to: string): Promise<{
|
|
70
|
+
file: ManifestFile;
|
|
71
|
+
text: string;
|
|
72
|
+
next: string;
|
|
73
|
+
}>;
|
|
40
74
|
/**
|
|
41
|
-
* Rewrite every manifest
|
|
42
|
-
* comments and order (ADR 0009, 0128). Nothing a person wrote
|
|
43
|
-
* read as they are and stay valid, and this only keeps diffs clean.
|
|
44
|
-
* would change.
|
|
75
|
+
* Rewrite every manifest at a version below `to` (the current one when left out) at that
|
|
76
|
+
* version, keeping its comments and order (ADR 0009, 0128, 0134). Nothing a person wrote
|
|
77
|
+
* changes: older manifests are read as they are and stay valid, and this only keeps diffs clean.
|
|
78
|
+
* `dryRun` lists what it would change.
|
|
45
79
|
*/
|
|
46
80
|
export declare function migrateManifests(root: string, o?: {
|
|
47
81
|
dryRun?: boolean;
|
|
82
|
+
to?: number;
|
|
48
83
|
}): Promise<string[]>;
|
|
84
|
+
/** A file's line ending, its text with LF only, and the text back in its own endings. */
|
|
85
|
+
export declare const eolOf: (raw: string) => "\r\n" | "\n";
|
|
86
|
+
export declare const lfOnly: (raw: string) => string;
|
|
87
|
+
export declare const inEol: (text: string, eol: "\r\n" | "\n") => string;
|
|
88
|
+
/** A line the edit changes: what it was (none when added) and what it is now. */
|
|
89
|
+
export interface LineChange {
|
|
90
|
+
was?: string;
|
|
91
|
+
now?: string;
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* The lines two texts differ in, in order: a line diff (longest common subsequence), each run of
|
|
95
|
+
* removed and added lines paired up as was and now. For a preview of a file's change.
|
|
96
|
+
*/
|
|
97
|
+
export declare function changedLines(before: string, after: string): LineChange[];
|
|
98
|
+
/**
|
|
99
|
+
* G2 (ADR 0174): set a repo's `owner` or `system` in the manifest that lists it, keeping the
|
|
100
|
+
* file's comments and order; checked before it is written. With `preview`, nothing is written:
|
|
101
|
+
* the lines it would change come back.
|
|
102
|
+
*/
|
|
103
|
+
export declare function setManifestField(root: string, repo: string,
|
|
104
|
+
/** ADR 0190: `type` too, from the app's Detect the type (atticus repo-type detect). */
|
|
105
|
+
field: "owner" | "system" | "type", value: string, o?: {
|
|
106
|
+
preview?: boolean;
|
|
107
|
+
}): Promise<{
|
|
108
|
+
file: ManifestFile;
|
|
109
|
+
changes: LineChange[];
|
|
110
|
+
written: boolean;
|
|
111
|
+
}>;
|
|
112
|
+
/**
|
|
113
|
+
* G2 (ADR 0174): add a team to roles.yaml (moved to version 2 first when it is older), for
|
|
114
|
+
* review: its id and name, no people. With `preview`, nothing is written.
|
|
115
|
+
*/
|
|
116
|
+
export declare function addRolesTeam(root: string, team: {
|
|
117
|
+
id: string;
|
|
118
|
+
name: string;
|
|
119
|
+
}, o?: {
|
|
120
|
+
preview?: boolean;
|
|
121
|
+
}): Promise<{
|
|
122
|
+
rel: string;
|
|
123
|
+
changes: LineChange[];
|
|
124
|
+
written: boolean;
|
|
125
|
+
}>;
|
package/npm/core/merge.d.ts
CHANGED
|
@@ -21,6 +21,12 @@ export interface MergeRepo {
|
|
|
21
21
|
type: string;
|
|
22
22
|
/** Hosts the repo's component (or, for a gateway repo, the gateway) answers on (ADR 0053). */
|
|
23
23
|
hosts?: string[];
|
|
24
|
+
/**
|
|
25
|
+
* beta.18: the repo's facts are read, so its endpoints are known: a call to one of its hosts
|
|
26
|
+
* joins it only where one of them serves the call (the facts join's own rule). Unset, as
|
|
27
|
+
* before: a host the manifest lists joins every call to it.
|
|
28
|
+
*/
|
|
29
|
+
read?: boolean;
|
|
24
30
|
}
|
|
25
31
|
export interface MergeSystem {
|
|
26
32
|
id: string;
|
|
@@ -28,6 +34,8 @@ export interface MergeSystem {
|
|
|
28
34
|
boundary: "product" | "internal" | "vendor";
|
|
29
35
|
owner?: string;
|
|
30
36
|
aliases: string[];
|
|
37
|
+
/** ADR 0162 amendment: the topics and queues it owns, kept apart from its aliases. */
|
|
38
|
+
topics?: string[];
|
|
31
39
|
/** Copied to the System record (ADR 0040: saas marks a SaaS vendor). */
|
|
32
40
|
tags?: string[];
|
|
33
41
|
}
|
|
@@ -42,8 +50,19 @@ export interface MergePattern {
|
|
|
42
50
|
sameSystem?: boolean;
|
|
43
51
|
};
|
|
44
52
|
}
|
|
53
|
+
/**
|
|
54
|
+
* ADR 0162 (F8): the flag on an Interface a topic or queue makes to an outside system because the
|
|
55
|
+
* profile names the topic under the system's topics: a person's word, not the code's.
|
|
56
|
+
*/
|
|
57
|
+
export declare const DECLARED_TOPIC = "declared-topic";
|
|
45
58
|
export interface MergeInput {
|
|
46
59
|
records: CatalogRecord[];
|
|
60
|
+
/**
|
|
61
|
+
* The component type ids the organisation has (ADR 0180: the built-ins with the org pack's
|
|
62
|
+
* applied). A Component's type that is one of these is never replaced by a repo type from the
|
|
63
|
+
* manifest. Left out, Atticus's documented types (ADR 0040).
|
|
64
|
+
*/
|
|
65
|
+
componentTypes?: ReadonlySet<string>;
|
|
47
66
|
repos: MergeRepo[];
|
|
48
67
|
systems: MergeSystem[];
|
|
49
68
|
patterns?: MergePattern[];
|
|
@@ -71,6 +90,15 @@ export interface MergeResult {
|
|
|
71
90
|
/** Things worth knowing that aren't wrong, e.g. hosts that look like a gateway nobody declared. */
|
|
72
91
|
notes: string[];
|
|
73
92
|
}
|
|
93
|
+
/** A record id cut to fit: its start, then a hash of the whole id, the same for the same id. */
|
|
94
|
+
export declare const fitRecordId: (id: string) => string;
|
|
95
|
+
/**
|
|
96
|
+
* A plural noun's singular, by plain English rules (one for endpoint ids and the glossary):
|
|
97
|
+
* "transfers" → "transfer", "policies" → "policy", "addresses" → "address", "statuses" →
|
|
98
|
+
* "status", "aliases" → "alias"; "status", "analysis" and "access" stay as they are; "causes",
|
|
99
|
+
* "excuses", "cases" and "responses" lose only their s.
|
|
100
|
+
*/
|
|
101
|
+
export declare function singularNoun(word: string): string;
|
|
74
102
|
/** Canonical REST endpoint id: <component>.<method>-<last fixed path segment, singular>. */
|
|
75
103
|
export declare function endpointId(component: string, method: string | undefined, normalizedPath: string): string;
|
|
76
104
|
export declare function mergeCatalog(input: MergeInput): MergeResult;
|
package/npm/core/metarepo.d.ts
CHANGED
|
@@ -16,6 +16,13 @@ export declare function inputsDirOf(root: string): string;
|
|
|
16
16
|
export declare function proposalsRelOf(root: string): string;
|
|
17
17
|
/** The proposals folder: `proposals/`, or `.atticus/proposals/` when adopted. */
|
|
18
18
|
export declare function proposalsDirOf(root: string): string;
|
|
19
|
+
/**
|
|
20
|
+
* ADR 0181: the record of each batch of decisions applied at once (by the AI, or by a person's
|
|
21
|
+
* rule), so Undo removes exactly its lines: `decisions/<batch id>.yaml`, or under `.atticus/`.
|
|
22
|
+
*/
|
|
23
|
+
export declare function decisionsRelOf(root: string): string;
|
|
24
|
+
/** The decisions folder (ADR 0181). */
|
|
25
|
+
export declare function decisionsDirOf(root: string): string;
|
|
19
26
|
/** Where questions to people live (ADR 0078), relative to the root: `questions`, or `.atticus/questions` when adopted. */
|
|
20
27
|
export declare function questionsRelOf(root: string): string;
|
|
21
28
|
/** The questions folder (ADR 0078). */
|
|
@@ -24,13 +31,23 @@ export declare function questionsDirOf(root: string): string;
|
|
|
24
31
|
export declare function factsRelOf(root: string): string;
|
|
25
32
|
/** The facts folder (ADR 0124): `<repo>.jsonl` the assistant writes, `<repo>.rejected.jsonl` and `<repo>.verify.yaml` the verifier writes. */
|
|
26
33
|
export declare function factsDirOf(root: string): string;
|
|
34
|
+
/** The diagrams folder (kept arrangements and views, ADR 0081, 0175), relative to the root: `diagrams`, or `.atticus/diagrams` when adopted. */
|
|
35
|
+
export declare function diagramsRelOf(root: string): string;
|
|
36
|
+
/** Where evidence from outside the code lives (ADR 0151), relative to the root: `evidence`, or `.atticus/evidence` when adopted. */
|
|
37
|
+
export declare function evidenceRelOf(root: string): string;
|
|
38
|
+
/** Where other teams' shared maps live (ADR 0160), relative to the root: `shared`, or `.atticus/shared` when adopted. */
|
|
39
|
+
export declare function sharedRelOf(root: string): string;
|
|
40
|
+
/** The shared maps folder (ADR 0160): `<team>/map.yaml` and `<team>/facts/<repo>.jsonl`, their entries, read-only. */
|
|
41
|
+
export declare function sharedDirOf(root: string): string;
|
|
42
|
+
/** The evidence folder (ADR 0151): `traffic/<source>-<from>-<to>.yaml`, the traffic aggregates a person imported. */
|
|
43
|
+
export declare function evidenceDirOf(root: string): string;
|
|
27
44
|
/**
|
|
28
45
|
* The files the facts folder keeps beside a repo's facts file (ADR 0124): the questions the
|
|
29
46
|
* assistant raised, what the verifier rejected, the files read and found to hold no fact, a
|
|
30
47
|
* person's corrections, the verifier's report, and the read plan of a repo read in parts
|
|
31
48
|
* (addendum A-ledger). None of them is a facts file of its own.
|
|
32
49
|
*/
|
|
33
|
-
export declare const FACTS_COMPANIONS: readonly [".questions.jsonl", ".rejected.jsonl", ".reviewed.jsonl", ".corrections.jsonl", ".verify.yaml", ".read-plan.yaml"];
|
|
50
|
+
export declare const FACTS_COMPANIONS: readonly [".questions.jsonl", ".rejected.jsonl", ".reviewed.jsonl", ".corrections.jsonl", ".verify.yaml", ".read-plan.yaml", ".audit.yaml", ".contracts.yaml", ".specs.yaml", ".gaps.md", ".crosscheck.yaml"];
|
|
34
51
|
/**
|
|
35
52
|
* The repo a file in the facts folder belongs to, and whether it is the repo's facts file
|
|
36
53
|
* (`<repo>.jsonl`) or one of its companions; undefined for any other file. Every place that lists
|
|
@@ -71,6 +88,14 @@ export declare function layoutOf(root: string): {
|
|
|
71
88
|
};
|
|
72
89
|
/** The catalog folder (holding generated/ and curated/). */
|
|
73
90
|
export declare function catalogDirOf(root: string): string;
|
|
91
|
+
/**
|
|
92
|
+
* Whether a changed file (root-relative, "/"-separated, as the server's live events name it) can
|
|
93
|
+
* change the catalog: a file in the catalog folder the layout names, that folder or one above it
|
|
94
|
+
* (the watcher names top folders when many files change), or the org pack, whose sources.yaml
|
|
95
|
+
* says where the catalog is. The server reads the catalog again only then, and tags each
|
|
96
|
+
* `file.changed` event with it (`catalog`), so a page follows the layout too.
|
|
97
|
+
*/
|
|
98
|
+
export declare function catalogMayHaveChangedAt(root: string, path: string): boolean;
|
|
74
99
|
/**
|
|
75
100
|
* Where OpenSpec keeps changes, relative to the root with forward slashes: `changes/` under
|
|
76
101
|
* `layout.openspec` (`openspec/changes` by default, `.atticus/openspec/changes` in a repo
|
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 {};
|
|
@@ -1,3 +1,9 @@
|
|
|
1
|
+
import { ChangeType } from "./schema/orgpack.js";
|
|
2
|
+
/**
|
|
3
|
+
* The quick path's type (ADR 0201): a plain OpenSpec change, with no stage. `specs` is listed
|
|
4
|
+
* because a change with no spec delta isn't valid OpenSpec. Quick by its shape (`quickPathOf`).
|
|
5
|
+
*/
|
|
6
|
+
export declare const QUICK_CHANGE_TYPE: ChangeType;
|
|
1
7
|
export declare const DEFAULT_CHANGE_TYPES: {
|
|
2
8
|
schemaVersion: 1 | 2;
|
|
3
9
|
types: {
|
|
@@ -5,7 +11,7 @@ export declare const DEFAULT_CHANGE_TYPES: {
|
|
|
5
11
|
name: string;
|
|
6
12
|
phases: ("release" | "design" | "qa" | "define" | "plan" | "build")[];
|
|
7
13
|
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"
|
|
14
|
+
lenses: ("release" | "true" | "complete" | "safe" | "ship" | "business" | "architecture" | "story" | "ux" | "delivery" | "code-and-test")[];
|
|
9
15
|
approvals: Partial<Record<"release" | "design" | "qa" | "define" | "plan" | "build", string[]>>;
|
|
10
16
|
postReleaseReview: boolean;
|
|
11
17
|
description?: string | undefined;
|
|
@@ -30,7 +36,13 @@ export declare const DEFAULT_GATES: {
|
|
|
30
36
|
}[];
|
|
31
37
|
};
|
|
32
38
|
export declare const DEFAULT_ROLES: {
|
|
33
|
-
schemaVersion: 1;
|
|
39
|
+
schemaVersion: 1 | 2 | 3;
|
|
40
|
+
teams: {
|
|
41
|
+
id: string;
|
|
42
|
+
people: string[];
|
|
43
|
+
name?: string | undefined;
|
|
44
|
+
roles?: Record<string, string[]> | undefined;
|
|
45
|
+
}[];
|
|
34
46
|
custom: {
|
|
35
47
|
id: string;
|
|
36
48
|
name: string;
|
|
@@ -50,9 +62,10 @@ export declare const DEFAULT_ROLES: {
|
|
|
50
62
|
actions: [string, string];
|
|
51
63
|
reason: string;
|
|
52
64
|
}[];
|
|
65
|
+
defaults?: Record<string, string[]> | undefined;
|
|
53
66
|
};
|
|
54
67
|
export declare const DEFAULT_RUNTIME: {
|
|
55
|
-
schemaVersion: 1 | 2;
|
|
68
|
+
schemaVersion: 1 | 2 | 3 | 4;
|
|
56
69
|
assistants: {
|
|
57
70
|
allowed: ("copilot" | "claude-code" | "cursor" | "gemini-cli" | "windsurf" | "agents-md")[];
|
|
58
71
|
default: "copilot" | "claude-code" | "cursor" | "gemini-cli" | "windsurf" | "agents-md";
|
|
@@ -60,8 +73,8 @@ export declare const DEFAULT_RUNTIME: {
|
|
|
60
73
|
editors: ("vscode" | "intellij")[];
|
|
61
74
|
ai: "on" | "text-only" | "off";
|
|
62
75
|
modes: {
|
|
63
|
-
allowed: ("model" | "hand-off" | "headless-claude-code")[];
|
|
64
|
-
default: "model" | "hand-off" | "headless-claude-code";
|
|
76
|
+
allowed: ("model" | "hand-off" | "headless-claude-code" | "copilot-acp")[];
|
|
77
|
+
default: "model" | "hand-off" | "headless-claude-code" | "copilot-acp";
|
|
65
78
|
};
|
|
66
79
|
models: {
|
|
67
80
|
allowed: string[];
|
|
@@ -128,13 +141,24 @@ export declare const DEFAULT_RUNTIME: {
|
|
|
128
141
|
expansion: boolean;
|
|
129
142
|
rerank: boolean;
|
|
130
143
|
} | undefined;
|
|
144
|
+
copilotAcp?: {
|
|
145
|
+
command?: string | undefined;
|
|
146
|
+
model?: string | undefined;
|
|
147
|
+
maxTurns?: number | undefined;
|
|
148
|
+
timeoutMs?: number | undefined;
|
|
149
|
+
} | undefined;
|
|
150
|
+
decide?: {
|
|
151
|
+
links: "auto" | "propose";
|
|
152
|
+
questions: "auto" | "propose";
|
|
153
|
+
minPrecision: number;
|
|
154
|
+
} | undefined;
|
|
131
155
|
buildEngine?: {
|
|
132
156
|
default: "atticus" | "speckit";
|
|
133
157
|
perRepo: Record<string, "atticus" | "speckit">;
|
|
134
158
|
} | undefined;
|
|
135
159
|
};
|
|
136
160
|
export declare const DEFAULT_SOURCES: {
|
|
137
|
-
schemaVersion:
|
|
161
|
+
schemaVersion: 1 | 2 | 3;
|
|
138
162
|
layout: {
|
|
139
163
|
openspec: string;
|
|
140
164
|
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,10 +61,20 @@ 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[];
|
|
63
72
|
}
|
|
73
|
+
/**
|
|
74
|
+
* ADR 0203 A.1: the prefix of the built-in gates a stage's own blocking findings are written to
|
|
75
|
+
* (`stage-feature`, `stage-architecture`, …). A gates.yaml gate may not take it.
|
|
76
|
+
*/
|
|
77
|
+
export declare const STAGE_GATE_PREFIX = "stage-";
|
|
64
78
|
/**
|
|
65
79
|
* Read and validate a whole org pack. Never throws for content problems: every schema or
|
|
66
80
|
* cross-file problem is listed in `problems` with its file, so a team sees all of them at
|
|
@@ -84,3 +98,13 @@ export declare function loadEstimates(dir: string): Promise<{
|
|
|
84
98
|
estimates?: Estimates;
|
|
85
99
|
problem?: string;
|
|
86
100
|
}>;
|
|
101
|
+
/** The conventions of a pack (ADR 0147), its defaults when it has none. */
|
|
102
|
+
export declare const conventionsOf: (op: Pick<OrgPack, "conventions"> | undefined) => Conventions;
|
|
103
|
+
/** What the estate join takes from a pack's conventions (ADR 0147): its facing words and bundle folders. */
|
|
104
|
+
export declare function joinConventions(op: Pick<OrgPack, "conventions"> | undefined): {
|
|
105
|
+
facing: {
|
|
106
|
+
internal: readonly string[];
|
|
107
|
+
external: readonly string[];
|
|
108
|
+
};
|
|
109
|
+
bundleFolders: readonly string[];
|
|
110
|
+
};
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@maycombhq/core/paths`: how the join normalises an HTTP path or a topic, with no imports, so
|
|
3
|
+
* the app (a browser bundle that takes nothing else of core at run time) matches a call's path to
|
|
4
|
+
* a link's exactly as the join made the link (review of beta.24). The same export as the
|
|
5
|
+
* package's own (`@maycombhq/core`).
|
|
6
|
+
*/
|
|
7
|
+
/**
|
|
8
|
+
* Normalise an HTTP path or topic so the same interface found in different places
|
|
9
|
+
* (caller code, gateway route, callee controller) gets the same identity.
|
|
10
|
+
*
|
|
11
|
+
* - path parameters in any style ({id}, :id, <id>, ${id}) become "{}"
|
|
12
|
+
* - query strings and fragments are dropped
|
|
13
|
+
* - repeated and trailing slashes are removed; a leading slash is ensured for paths
|
|
14
|
+
* - topics (no leading slash in the input and no "/" at all) are returned trimmed
|
|
15
|
+
*/
|
|
16
|
+
export declare function normalizePath(input: string): string;
|
|
17
|
+
/**
|
|
18
|
+
* A path with each `{...}` parameter cut to its name: what follows the first `:`, `?` or `=` in
|
|
19
|
+
* braces nested inside a constraint (`{code:regex(^\\d{3}$)}`) are matched, not cut at the first `}`.
|
|
20
|
+
* braces nested inside a constraint (`{code:regex(^\\d{{3}}$)}`) are matched, not cut at the first `}`.
|
|
21
|
+
* An unclosed `{` leaves the rest as written.
|
|
22
|
+
*/
|
|
23
|
+
export declare function stripParamConstraints(path: string): string;
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ADR 0187: where a line printed by a command goes besides its own output, while it runs inside
|
|
3
|
+
* the app's job. The job (in the server) sets the printer; the command line's `main`, and the
|
|
4
|
+
* app's routes that run a command's code, pass each line they print to `printToCurrent`. Outside
|
|
5
|
+
* a job there is no printer and nothing happens. No schema here: the command line loads it first.
|
|
6
|
+
*/
|
|
7
|
+
/**
|
|
8
|
+
* Beta.28.1: how a line is printed. `now`: a progress line (a step of long work), sent to the
|
|
9
|
+
* Console at once rather than in the next batch of lines, so it is there before the step's work
|
|
10
|
+
* keeps the thread.
|
|
11
|
+
*/
|
|
12
|
+
export interface PrintOptions {
|
|
13
|
+
now?: boolean;
|
|
14
|
+
}
|
|
15
|
+
/** Run `work` with every line printed inside it (at any depth, across awaits) going to `print`. */
|
|
16
|
+
export declare function withPrinter<T>(print: (line: string, o?: PrintOptions) => void, work: () => T): T;
|
|
17
|
+
/** Print a line to the job this code runs in, if any. */
|
|
18
|
+
export declare function printToCurrent(line: string, o?: PrintOptions): void;
|