@maycombhq/sdk 2.0.0-beta.1 → 2.0.0-beta.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/{dist → npm}/cache.d.ts +1 -1
- package/npm/core/api.d.ts +7964 -0
- package/npm/core/assistant-actor.d.ts +15 -0
- package/npm/core/audit.d.ts +153 -0
- package/npm/core/branches.d.ts +21 -0
- package/npm/core/cancel.d.ts +9 -0
- package/npm/core/catalog.d.ts +4735 -0
- package/npm/core/change-types-migrate.d.ts +10 -0
- package/npm/core/cite.d.ts +54 -0
- package/npm/core/contract-check.d.ts +251 -0
- package/npm/core/curated.d.ts +37 -0
- package/npm/core/fact-paths.d.ts +14 -0
- package/npm/core/facts-callers.d.ts +152 -0
- package/npm/core/facts-carry.d.ts +36 -0
- package/npm/core/facts-join-prototype.d.ts +239 -0
- package/npm/core/facts-join-vendor.d.ts +110 -0
- package/npm/core/facts-join.d.ts +482 -0
- package/npm/core/facts-terms.d.ts +108 -0
- package/npm/core/facts.d.ts +94 -0
- package/npm/core/fs.d.ts +47 -0
- package/npm/core/gates-migrate.d.ts +10 -0
- package/npm/core/host-questions.d.ts +111 -0
- package/npm/core/identity.d.ts +17 -0
- package/npm/core/index.d.ts +77 -0
- package/npm/core/json-schema.d.ts +20 -0
- package/npm/core/judgments.d.ts +63 -0
- package/npm/core/light.d.ts +8 -0
- package/npm/core/link-evidence.d.ts +212 -0
- package/npm/core/log.d.ts +49 -0
- package/npm/core/manifest-edit.d.ts +57 -0
- package/npm/core/merge.d.ts +85 -0
- package/npm/core/metarepo.d.ts +91 -0
- package/npm/core/migrate.d.ts +32 -0
- package/npm/core/migration-files.d.ts +13 -0
- package/npm/core/org-notes.d.ts +180 -0
- package/npm/core/orgpack-defaults.d.ts +199 -0
- package/npm/core/orgpack-load.d.ts +102 -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/questions.d.ts +312 -0
- package/npm/core/record-cache.d.ts +52 -0
- package/npm/core/refs.d.ts +9 -0
- package/npm/core/repo-description.d.ts +44 -0
- 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 +11 -0
- package/npm/core/schema/ai.d.ts +397 -0
- package/npm/core/schema/change.d.ts +244 -0
- package/npm/core/schema/common.d.ts +135 -0
- package/npm/core/schema/conventions.d.ts +80 -0
- package/npm/core/schema/dialect.d.ts +801 -0
- package/npm/core/schema/executors.d.ts +396 -0
- package/npm/core/schema/fact-corrections.d.ts +56 -0
- package/npm/core/schema/facts.d.ts +1773 -0
- package/npm/core/schema/frameworks.d.ts +371 -0
- package/npm/core/schema/judgment.d.ts +77 -0
- package/npm/core/schema/kinds.d.ts +5168 -0
- package/npm/core/schema/layout.d.ts +25 -0
- package/npm/core/schema/orgpack.d.ts +1193 -0
- package/npm/core/schema/plugin.d.ts +73 -0
- package/npm/core/schema/question.d.ts +230 -0
- package/npm/core/schema/repo-type.d.ts +127 -0
- package/npm/core/schema/review.d.ts +558 -0
- package/npm/core/schema/scan-settings.d.ts +34 -0
- package/npm/core/schema/scan-verify.d.ts +535 -0
- package/npm/core/schema/spec.d.ts +269 -0
- package/npm/core/schema/version.d.ts +10 -0
- package/npm/core/schema/workspace.d.ts +330 -0
- package/npm/core/serialize.d.ts +17 -0
- package/npm/core/shared-maps.d.ts +146 -0
- package/npm/core/sources-migrate.d.ts +15 -0
- package/npm/core/specs.d.ts +66 -0
- package/npm/core/stack-helpers.d.ts +32 -0
- package/npm/core/tar-read.d.ts +13 -0
- package/npm/core/template.d.ts +101 -0
- package/npm/core/words.d.ts +13 -0
- package/npm/core/zip-read.d.ts +37 -0
- package/npm/core/zip.d.ts +13 -0
- package/npm/index.js +10097 -0
- package/{dist → npm}/plugin.d.ts +1 -1
- package/{dist → npm}/runner.d.ts +1 -1
- package/package.json +10 -11
- package/dist/cache.js +0 -115
- package/dist/cache.js.map +0 -1
- package/dist/fs-repo.js +0 -120
- package/dist/fs-repo.js.map +0 -1
- package/dist/index.js +0 -7
- package/dist/index.js.map +0 -1
- package/dist/parse-cache.js +0 -275
- package/dist/parse-cache.js.map +0 -1
- package/dist/plugin.js +0 -85
- package/dist/plugin.js.map +0 -1
- package/dist/runner.js +0 -209
- package/dist/runner.js.map +0 -1
- package/dist/sandbox.js +0 -443
- package/dist/sandbox.js.map +0 -1
- /package/{dist → npm}/fs-repo.d.ts +0 -0
- /package/{dist → npm}/index.d.ts +0 -0
- /package/{dist → npm}/parse-cache.d.ts +0 -0
- /package/{dist → npm}/sandbox.d.ts +0 -0
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import type { CatalogRecord } from "./catalog.js";
|
|
2
|
+
import { Fact, type FactOf } from "./schema/facts.js";
|
|
3
|
+
/**
|
|
4
|
+
* The facts file (ADR 0124): read, write and project into catalog C1.
|
|
5
|
+
*
|
|
6
|
+
* `parseFacts` reads JSONL (or a JSON array) and refuses anything the schema refuses, with the
|
|
7
|
+
* line it was on. `serializeFacts` writes one canonical line per fact, sorted by id, so the same
|
|
8
|
+
* facts give the same bytes. `projectFacts` turns facts into C1 records deterministically:
|
|
9
|
+
* nothing downstream of C1 has to know facts exist.
|
|
10
|
+
*/
|
|
11
|
+
export interface FactIssue {
|
|
12
|
+
line?: number;
|
|
13
|
+
factId?: string;
|
|
14
|
+
code: string;
|
|
15
|
+
message: string;
|
|
16
|
+
}
|
|
17
|
+
export type ParseFactsResult = {
|
|
18
|
+
ok: true;
|
|
19
|
+
facts: Fact[];
|
|
20
|
+
} | {
|
|
21
|
+
ok: false;
|
|
22
|
+
issues: FactIssue[];
|
|
23
|
+
};
|
|
24
|
+
export declare function parseFacts(text: string): ParseFactsResult;
|
|
25
|
+
/** A line of a facts file that isn't a fact, with its number, its text and what is wrong. */
|
|
26
|
+
export type BadFactLine = {
|
|
27
|
+
line: number;
|
|
28
|
+
raw: string;
|
|
29
|
+
issues: FactIssue[];
|
|
30
|
+
};
|
|
31
|
+
/**
|
|
32
|
+
* One line of a facts file: the fact it holds, or what is wrong with it, or neither when the line
|
|
33
|
+
* is blank. `seen` holds the ids read so far and gains this one, so a repeated id keeps its first
|
|
34
|
+
* line. The whole of reading a line is here, so a reader that streams the file (ADR 0124 addendum
|
|
35
|
+
* A-room) and one that has the text in hand give the same facts and the same issues.
|
|
36
|
+
*/
|
|
37
|
+
export declare function parseFactLine(raw: string, line: number, seen: Set<string>): {
|
|
38
|
+
fact?: Fact;
|
|
39
|
+
bad?: BadFactLine;
|
|
40
|
+
};
|
|
41
|
+
/**
|
|
42
|
+
* Read a JSONL facts file line by line, keeping every line that reads and returning the others
|
|
43
|
+
* with their issues, so one bad line (a capital in an id, a missing field) costs that fact, not
|
|
44
|
+
* the whole read (feedback from the A4 run). A repeated id keeps its first line.
|
|
45
|
+
*
|
|
46
|
+
* This takes the whole file as one string; a big repo's facts are read a line at a time instead
|
|
47
|
+
* (`streamFacts` in the CLI, ADR 0124 addendum A-room), through the same `parseFactLine`.
|
|
48
|
+
*/
|
|
49
|
+
export declare function parseFactsLines(text: string): {
|
|
50
|
+
facts: Fact[];
|
|
51
|
+
bad: BadFactLine[];
|
|
52
|
+
};
|
|
53
|
+
/** One canonical JSON line per fact, sorted by id; the same facts give the same bytes. */
|
|
54
|
+
export declare function serializeFacts(facts: readonly Fact[]): string;
|
|
55
|
+
export interface ProjectOptions {
|
|
56
|
+
/** The System every projected Component belongs to. Default: the repo's slug. */
|
|
57
|
+
system?: string;
|
|
58
|
+
/** Overrides the facts' own `repo` as the evidence repo (a renamed clone, say). */
|
|
59
|
+
repo?: string;
|
|
60
|
+
}
|
|
61
|
+
export interface ProjectResult {
|
|
62
|
+
records: CatalogRecord[];
|
|
63
|
+
issues: FactIssue[];
|
|
64
|
+
/**
|
|
65
|
+
* The catalog id each fact became, by fact id, in id order (fields that became a Column or a
|
|
66
|
+
* Schema field are left out). A writer follows them through the catalog merge (ADR 0124, A3b).
|
|
67
|
+
*/
|
|
68
|
+
ids: Record<string, string>;
|
|
69
|
+
}
|
|
70
|
+
/** A name as a part of a projected catalog id: its slug, with dots made dashes (a component, a store). */
|
|
71
|
+
export declare const factIdPart: (text: string) => string;
|
|
72
|
+
/** The Endpoint id an entry fact projects to in its component (`projectFacts`). */
|
|
73
|
+
export declare function entryEndpointId(f: FactOf<"entry">, component: string): string;
|
|
74
|
+
/**
|
|
75
|
+
* A call's normalised path: a gRPC method stays `package.Service/Method` and a SOAP operation
|
|
76
|
+
* `Contract/Operation` (a client may write either with a leading slash); an HTTP path loses a parameter's optional marker and constraint first
|
|
77
|
+
* (`{brandId:int?}`), so the `?` isn't read as a query string.
|
|
78
|
+
*/
|
|
79
|
+
export declare function callPath(callType: string, path: string): string;
|
|
80
|
+
/**
|
|
81
|
+
* The `auth` an entry fact may put in the catalog (ADR 0124 addendum A-uncited): the claim stands
|
|
82
|
+
* in C1 only where a line is cited for it (`authCite`), or where a person made the fact, since
|
|
83
|
+
* that is their own word, marked as theirs. The facts file keeps what its writer wrote either
|
|
84
|
+
* way; this is the gate on the way into the catalog, so the catalog never says an auth no line
|
|
85
|
+
* was cited for, and the verifier's `authUncited` warning stays until a line is cited.
|
|
86
|
+
*/
|
|
87
|
+
export declare function catalogAuth(f: FactOf<"entry">): FactOf<"entry">["auth"];
|
|
88
|
+
/**
|
|
89
|
+
* Facts to C1. Ids are made from the claims, so the same facts give the same ids:
|
|
90
|
+
* Endpoint `<component>.<method-path>`, Interface `if-<hash>`, DataStore `<store>`,
|
|
91
|
+
* Table `<store>.<table>`, Column `<store>.<table>.<column>`, Schema `<endpoint>.<side>`,
|
|
92
|
+
* Deployment `<component>.<env>`, Setting `<component>.<key>`, Flow `<component>.<name>`.
|
|
93
|
+
*/
|
|
94
|
+
export declare function projectFacts(input: readonly Fact[], opts?: ProjectOptions): ProjectResult;
|
package/npm/core/fs.d.ts
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Write a file so a crash never leaves it half-written: write a temporary file beside it,
|
|
3
|
+
* then rename it over the old one (a rename within a folder is atomic on every platform
|
|
4
|
+
* Atticus supports). The temporary name is unique, so two writers never share it. On
|
|
5
|
+
* Windows a rename can fail for a moment while a virus scanner or indexer holds the file:
|
|
6
|
+
* it is retried a few times before giving up.
|
|
7
|
+
*/
|
|
8
|
+
export declare function writeFileAtomic(path: string, data: string | Uint8Array): Promise<void>;
|
|
9
|
+
export declare function renameRetrying(from: string, to: string, tries?: number): Promise<void>;
|
|
10
|
+
export interface LockInfo {
|
|
11
|
+
pid: number;
|
|
12
|
+
host: string;
|
|
13
|
+
startedAt: string;
|
|
14
|
+
what: string;
|
|
15
|
+
}
|
|
16
|
+
export declare class LockHeldError extends Error {
|
|
17
|
+
readonly held: LockInfo;
|
|
18
|
+
constructor(held: LockInfo);
|
|
19
|
+
}
|
|
20
|
+
/** Where a metarepo's locks live: .atticus/locks/, on this machine only (git-ignored). */
|
|
21
|
+
export declare const lockFileOf: (root: string, name: string) => string;
|
|
22
|
+
/** Read a lock: undefined when free; `stale` when its process is gone (it was cut short). */
|
|
23
|
+
export declare function readLock(root: string, name: string): Promise<(LockInfo & {
|
|
24
|
+
stale: boolean;
|
|
25
|
+
}) | undefined>;
|
|
26
|
+
/**
|
|
27
|
+
* Take a lock for a long write (a scan): one at a time per metarepo. A lock whose process is
|
|
28
|
+
* gone was cut short (a crash, a closed terminal); it is taken over and reported as
|
|
29
|
+
* `interrupted`, so the caller can say the last run didn't finish.
|
|
30
|
+
*/
|
|
31
|
+
export declare function acquireLock(root: string, name: string, what: string, now?: () => Date): Promise<{
|
|
32
|
+
release: () => Promise<void>;
|
|
33
|
+
interrupted?: LockInfo;
|
|
34
|
+
}>;
|
|
35
|
+
/**
|
|
36
|
+
* What stays on this machine inside .atticus/: the person's settings, the log, locks, upgrade
|
|
37
|
+
* backups, the prompt and response history (ADR 0110), what `atticus probe` measured of the
|
|
38
|
+
* person's assistant (ADR 0124 addendum A-probe) and the parses kept between runs
|
|
39
|
+
* (`cache/`, record-cache.ts).
|
|
40
|
+
*/
|
|
41
|
+
export declare const LOCAL_ONLY: readonly ["me.yaml", "logs/", "locks/", "backups/", "history/", "probe/", "cache/", "map-all/"];
|
|
42
|
+
/**
|
|
43
|
+
* Make sure .atticus/.gitignore keeps this machine's files out of Git. It lives inside
|
|
44
|
+
* .atticus/, so it works the same in a metarepo and in a repo adopted in place (where Atticus
|
|
45
|
+
* writes nothing outside .atticus/).
|
|
46
|
+
*/
|
|
47
|
+
export declare function ensureLocalIgnore(root: string): Promise<void>;
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* gates.yaml version 1 → 2 (ADR 0087). Version 2 reads a gate with no maxAuthorRounds as
|
|
3
|
+
* unlimited; version 1 read it as two rounds. So that nothing loosens without a person
|
|
4
|
+
* choosing it, the migration writes `maxAuthorRounds: 2` on every gate that left it out, and
|
|
5
|
+
* keeps the file's comments and order. Deleting that line afterwards makes the gate unlimited.
|
|
6
|
+
*/
|
|
7
|
+
export declare function migrateGatesText(text: string): {
|
|
8
|
+
text: string;
|
|
9
|
+
changed: boolean;
|
|
10
|
+
};
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which repo answers on a host (ADR 0088): a scan or atticus estate join asks, as a question
|
|
3
|
+
* file (ADR 0078), for each host the estate's calls name that no repo lists in its `hosts`;
|
|
4
|
+
* the answer writes the host under that repo's `hosts` in its repos.manifest.yaml.
|
|
5
|
+
*/
|
|
6
|
+
/** The step that asks which repo answers on a host. */
|
|
7
|
+
export declare const HOSTS_STEP = "scan-hosts";
|
|
8
|
+
/**
|
|
9
|
+
* The step that asks which repo or system answers a call with no target (the scanner's
|
|
10
|
+
* TARGETS_STEP), and its group question's option that says the calls go to more than one place:
|
|
11
|
+
* named here so an answer's rule (ADR 0153) is checked where it is written.
|
|
12
|
+
*/
|
|
13
|
+
export declare const TARGETS_STEP_ID = "facts-targets";
|
|
14
|
+
export declare const TARGETS_SPLIT_LABEL = "Not all to one place";
|
|
15
|
+
/**
|
|
16
|
+
* ADR 0162 (F8): the option of a targets question that opens the picker of the whole estate (the
|
|
17
|
+
* manifest's repos, the profiles' systems, the teams). It names nothing: it is never an answer.
|
|
18
|
+
*/
|
|
19
|
+
export declare const TARGETS_ANOTHER_LABEL = "Another repo\u2026";
|
|
20
|
+
/**
|
|
21
|
+
* ADR 0162 (F8): the step that asks who owns a topic or queue the repo publishes to or listens on
|
|
22
|
+
* that no estate repo serves the other side of, and its option that opens the picker (a system of
|
|
23
|
+
* the profile, or a team): the answer adds the topic to that system's aliases, so the merge lands
|
|
24
|
+
* the publish or the listener on it, as a file change for review.
|
|
25
|
+
*/
|
|
26
|
+
export declare const TOPICS_STEP_ID = "facts-topics";
|
|
27
|
+
export declare const TOPICS_OUTSIDE_LABEL = "A topic owned by another team or vendor";
|
|
28
|
+
/** A topics question's words: what the repo does with the topic, and the topic. */
|
|
29
|
+
export declare const topicQuestionText: (topic: string, component: string, side: "publish" | "listen") => string;
|
|
30
|
+
/** The topic a topics question asks about, read back from its words. */
|
|
31
|
+
export declare function topicOfQuestion(q: {
|
|
32
|
+
question: string;
|
|
33
|
+
}): string | undefined;
|
|
34
|
+
/** The options that open the picker: they name nothing, so they are never an answer. */
|
|
35
|
+
export declare const PICKER_LABELS: ReadonlySet<string>;
|
|
36
|
+
/** The last option of a hosts question: no repo of the estate answers on it. */
|
|
37
|
+
export declare const HOSTS_NONE = "None of these";
|
|
38
|
+
/**
|
|
39
|
+
* The options of a hosts question that say an outside system answers on the host (O1): another
|
|
40
|
+
* team's system (boundary internal, the first, the default) or a vendor's. The answer writes the
|
|
41
|
+
* system into the profile of the repo that asked, with the host as its alias, so the calls to
|
|
42
|
+
* the host go to it (F3: a declared system no estate repo belongs to is outside).
|
|
43
|
+
*/
|
|
44
|
+
export declare const HOSTS_OUTSIDE_INTERNAL = "An outside system (new): another team's";
|
|
45
|
+
export declare const HOSTS_OUTSIDE_VENDOR = "An outside system (new): a vendor";
|
|
46
|
+
/** The boundary an outside-system option of a hosts question gives its system, if it is one. */
|
|
47
|
+
export declare function outsideBoundaryOf(label: string | undefined): "internal" | "vendor" | undefined;
|
|
48
|
+
/** The system an outside-system answer adds for a host: its id and name, both from the host. */
|
|
49
|
+
export declare function outsideSystemOf(host: string): {
|
|
50
|
+
id: string;
|
|
51
|
+
name: string;
|
|
52
|
+
};
|
|
53
|
+
/** The question for a host, with its port when the calls name one: localhost:9966. */
|
|
54
|
+
export declare const hostQuestionText: (host: string) => string;
|
|
55
|
+
/** The host a hosts question asks about, read back from its words. */
|
|
56
|
+
export declare function hostOfQuestion(q: {
|
|
57
|
+
question: string;
|
|
58
|
+
}): string | undefined;
|
|
59
|
+
/**
|
|
60
|
+
* Put an outside system for a host into the profile whose repos.manifest.yaml lists the repo
|
|
61
|
+
* that asked (O1): its id and name from the host, the host as its alias, the boundary given
|
|
62
|
+
* (internal: another team's; vendor). The profile keeps its comments and order, and is made,
|
|
63
|
+
* with the platform's id as its name, when there is none. `added` is false when a system of the
|
|
64
|
+
* profiles already names the host. Throws when no manifest lists the repo, or the profile would
|
|
65
|
+
* not be valid (an id another system has).
|
|
66
|
+
*/
|
|
67
|
+
export declare function addOutsideSystem(root: string, repo: string, host: string, boundary: "internal" | "vendor"): Promise<{
|
|
68
|
+
id: string;
|
|
69
|
+
profile: string;
|
|
70
|
+
added: boolean;
|
|
71
|
+
}>;
|
|
72
|
+
/**
|
|
73
|
+
* ADR 0162 (F8): put a system a person named in a targets answer into the profile whose
|
|
74
|
+
* repos.manifest.yaml lists the repo that asked: a vendor (boundary vendor), or another team's
|
|
75
|
+
* system (boundary internal, owner the team's id from roles.yaml). Written as a file change in the
|
|
76
|
+
* metarepo, for review in the pull request, never to a shared system. `added` is false when a
|
|
77
|
+
* system of the profiles already has the id. Throws when no manifest lists the repo, or the
|
|
78
|
+
* profile would not be valid.
|
|
79
|
+
*/
|
|
80
|
+
export declare function addProfileSystem(root: string, repo: string, s: {
|
|
81
|
+
id: string;
|
|
82
|
+
name: string;
|
|
83
|
+
boundary: "internal" | "vendor";
|
|
84
|
+
owner?: string;
|
|
85
|
+
/**
|
|
86
|
+
* The topics and queues it owns (ADR 0162 amendment): written under `topics`, never
|
|
87
|
+
* `aliases`, with the profile at schema version 2.
|
|
88
|
+
*/
|
|
89
|
+
topics?: string[];
|
|
90
|
+
}): Promise<{
|
|
91
|
+
id: string;
|
|
92
|
+
profile: string;
|
|
93
|
+
added: boolean;
|
|
94
|
+
topics?: string[];
|
|
95
|
+
}>;
|
|
96
|
+
/**
|
|
97
|
+
* Put a host under a repo's `hosts` in the repos.manifest.yaml that lists it, keeping the
|
|
98
|
+
* file's comments and order. `added` is false when the repo already lists it. Throws when no
|
|
99
|
+
* manifest lists the repo, or the host isn't one the manifest takes.
|
|
100
|
+
*/
|
|
101
|
+
export declare function addManifestHost(root: string, repo: string, host: string,
|
|
102
|
+
/**
|
|
103
|
+
* ADR 0153 (Q2): the path the repo answers under on the host, from an answer's path rule, set
|
|
104
|
+
* as its `basePath`. Refused when the repo gives another one.
|
|
105
|
+
*/
|
|
106
|
+
o?: {
|
|
107
|
+
basePath?: string;
|
|
108
|
+
}): Promise<{
|
|
109
|
+
manifest: string;
|
|
110
|
+
added: boolean;
|
|
111
|
+
}>;
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Normalise an HTTP path or topic so the same interface found in different places
|
|
3
|
+
* (caller code, gateway route, callee controller) gets the same identity.
|
|
4
|
+
*
|
|
5
|
+
* - path parameters in any style ({id}, :id, <id>, ${id}) become "{}"
|
|
6
|
+
* - query strings and fragments are dropped
|
|
7
|
+
* - repeated and trailing slashes are removed; a leading slash is ensured for paths
|
|
8
|
+
* - topics (no leading slash in the input and no "/" at all) are returned trimmed
|
|
9
|
+
*/
|
|
10
|
+
export declare function normalizePath(input: string): string;
|
|
11
|
+
/**
|
|
12
|
+
* Stable interface id: a hash of caller, callee, method and normalised path, so the same
|
|
13
|
+
* edge seen by several extractors merges into one Interface record.
|
|
14
|
+
*/
|
|
15
|
+
export declare function interfaceId(from: string, to: string, method: string | undefined, path: string): string;
|
|
16
|
+
/** Lowercase slug suitable as a record id, built from free text such as a system name. */
|
|
17
|
+
export declare function slugify(text: string): string;
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
export * from "./schema/common.js";
|
|
2
|
+
export * from "./schema/kinds.js";
|
|
3
|
+
export * from "./schema/facts.js";
|
|
4
|
+
export * from "./schema/fact-corrections.js";
|
|
5
|
+
export * from "./facts.js";
|
|
6
|
+
export * from "./fact-paths.js";
|
|
7
|
+
export * from "./migration-files.js";
|
|
8
|
+
export * from "./facts-join.js";
|
|
9
|
+
export * from "./facts-join-vendor.js";
|
|
10
|
+
export * from "./facts-join-prototype.js";
|
|
11
|
+
export * from "./facts-carry.js";
|
|
12
|
+
export * from "./facts-callers.js";
|
|
13
|
+
export * from "./facts-terms.js";
|
|
14
|
+
export * from "./org-notes.js";
|
|
15
|
+
export * from "./link-evidence.js";
|
|
16
|
+
export * from "./shared-maps.js";
|
|
17
|
+
export * from "./contract-check.js";
|
|
18
|
+
export * from "./audit.js";
|
|
19
|
+
export * from "./stack-helpers.js";
|
|
20
|
+
export * from "./cite.js";
|
|
21
|
+
export * from "./catalog.js";
|
|
22
|
+
export * from "./identity.js";
|
|
23
|
+
export * from "./serialize.js";
|
|
24
|
+
export * from "./json-schema.js";
|
|
25
|
+
export * from "./schema/workspace.js";
|
|
26
|
+
export * from "./schema/change.js";
|
|
27
|
+
export * from "./branches.js";
|
|
28
|
+
export * from "./template.js";
|
|
29
|
+
export * from "./schema/dialect.js";
|
|
30
|
+
export * from "./schema/frameworks.js";
|
|
31
|
+
export * from "./schema/scan-settings.js";
|
|
32
|
+
export * from "./schema/scan-verify.js";
|
|
33
|
+
export * from "./schema/repo-type.js";
|
|
34
|
+
export * from "./schema/layout.js";
|
|
35
|
+
export * from "./schema/plugin.js";
|
|
36
|
+
export * from "./schema/review.js";
|
|
37
|
+
export * from "./schema/orgpack.js";
|
|
38
|
+
export * from "./schema/conventions.js";
|
|
39
|
+
export * from "./schema/executors.js";
|
|
40
|
+
export * from "./orgpack-defaults.js";
|
|
41
|
+
export * from "./orgpack-load.js";
|
|
42
|
+
export * from "./schema/ai.js";
|
|
43
|
+
export * as Api from "./api.js";
|
|
44
|
+
export { API_VERSION, DEFAULT_PORT, openApiDocument } from "./api.js";
|
|
45
|
+
export * from "./merge.js";
|
|
46
|
+
export * from "./refs.js";
|
|
47
|
+
export * from "./curated.js";
|
|
48
|
+
export * from "./migrate.js";
|
|
49
|
+
export * from "./gates-migrate.js";
|
|
50
|
+
export * from "./change-types-migrate.js";
|
|
51
|
+
export * from "./sources-migrate.js";
|
|
52
|
+
export * from "./runtime-migrate.js";
|
|
53
|
+
export * from "./roles-migrate.js";
|
|
54
|
+
export * from "./profile-migrate.js";
|
|
55
|
+
export * from "./metarepo.js";
|
|
56
|
+
export * from "./fs.js";
|
|
57
|
+
export * from "./record-cache.js";
|
|
58
|
+
export * from "./log.js";
|
|
59
|
+
export * from "./zip.js";
|
|
60
|
+
export * from "./words.js";
|
|
61
|
+
export * from "./zip-read.js";
|
|
62
|
+
export * from "./tar-read.js";
|
|
63
|
+
export * from "./schema/question.js";
|
|
64
|
+
export * from "./questions.js";
|
|
65
|
+
export * from "./schema/judgment.js";
|
|
66
|
+
export * from "./judgments.js";
|
|
67
|
+
export * from "./host-questions.js";
|
|
68
|
+
export * from "./repo-reads.js";
|
|
69
|
+
export * from "./question-order.js";
|
|
70
|
+
export * from "./question-owners.js";
|
|
71
|
+
export * from "./question-proposals.js";
|
|
72
|
+
export * from "./repo-description.js";
|
|
73
|
+
export * from "./manifest-edit.js";
|
|
74
|
+
export * from "./schema/spec.js";
|
|
75
|
+
export * from "./specs.js";
|
|
76
|
+
export * from "./cancel.js";
|
|
77
|
+
export * from "./assistant-actor.js";
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { type RecordKind } from "./schema/kinds.js";
|
|
2
|
+
/**
|
|
3
|
+
* JSON Schema for every record kind, generated from the zod source of truth, for editors,
|
|
4
|
+
* other tools and org-pack validation outside TypeScript.
|
|
5
|
+
*/
|
|
6
|
+
export declare function catalogJsonSchemas(): Record<RecordKind, object>;
|
|
7
|
+
/**
|
|
8
|
+
* JSON Schema for the workspace files: repos.manifest.yaml, and a change's repos.yaml,
|
|
9
|
+
* change.yaml (its lifecycle state) and review/outcomes.yaml (ADR 0045), and a view's kept
|
|
10
|
+
* arrangement, diagrams/layouts/<view-key>.yaml (ADR 0081).
|
|
11
|
+
*/
|
|
12
|
+
export declare function workspaceJsonSchemas(): Record<"RepoManifest" | "ChangeRepos" | "ChangeLifecycle" | "ChangeOutcomes" | "CatalogBaseline" | "MetarepoStamp" | "DiagramLayout", object>;
|
|
13
|
+
/** JSON Schema for the dialect rule file (C2) and checklist packs and findings (C3). */
|
|
14
|
+
export declare function rulesJsonSchemas(): Record<"Dialect" | "ChecklistPack" | "Finding", object>;
|
|
15
|
+
/** JSON Schema for every org-pack file (C6). */
|
|
16
|
+
export declare function orgPackJsonSchemas(): Record<string, object>;
|
|
17
|
+
/** JSON Schema for the AI runtime's run files (C5). */
|
|
18
|
+
export declare function aiJsonSchemas(): Record<string, object>;
|
|
19
|
+
/** The facts file the assistant writes (ADR 0124): one Fact per JSON line, or a FactsFile array. */
|
|
20
|
+
export declare function factsJsonSchemas(): Record<"Fact" | "FactsFile", object>;
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
import { Judgment, type JudgmentConfirmer, type JudgmentVerdict } from "./schema/judgment.js";
|
|
2
|
+
/**
|
|
3
|
+
* The judgments store (ADR 0117): judgments/<kind>/<key>.yaml, the key a hash of the inputs.
|
|
4
|
+
* Any step that asks a model a closed question about meaning keeps the answer here (the judge
|
|
5
|
+
* step in @maycombhq/ai, and the context engine's query expansion and rerank), so the same
|
|
6
|
+
* commit with the same inputs reads the stored verdict and never asks again, and a changed input
|
|
7
|
+
* invalidates only its own judgment.
|
|
8
|
+
*
|
|
9
|
+
* The interface is two calls, get and put by kind and key; `judgmentKey` makes the key.
|
|
10
|
+
*/
|
|
11
|
+
export interface JudgmentStore {
|
|
12
|
+
get(kind: string, key: string): Promise<Judgment | undefined>;
|
|
13
|
+
/**
|
|
14
|
+
* Keep a judgment. A person's verdict on file is never replaced by a model's or a check's:
|
|
15
|
+
* the stored one comes back instead.
|
|
16
|
+
*/
|
|
17
|
+
put(j: Judgment): Promise<Judgment>;
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* The key of a judgment: 24 hex characters of the sha256 of the kind and the inputs in
|
|
21
|
+
* canonical form (keys sorted, undefined left out), so the same inputs in any key order give
|
|
22
|
+
* the same key.
|
|
23
|
+
*/
|
|
24
|
+
export declare function judgmentKey(kind: string, inputs: unknown): string;
|
|
25
|
+
/** A new judgment at the current schema version, its key made from the inputs. */
|
|
26
|
+
export declare function makeJudgment(o: {
|
|
27
|
+
kind: string;
|
|
28
|
+
inputs: Record<string, unknown>;
|
|
29
|
+
verdict: JudgmentVerdict;
|
|
30
|
+
confirmedBy: JudgmentConfirmer;
|
|
31
|
+
at: string;
|
|
32
|
+
value?: unknown;
|
|
33
|
+
quotes?: {
|
|
34
|
+
of: string;
|
|
35
|
+
text: string;
|
|
36
|
+
}[];
|
|
37
|
+
why?: string;
|
|
38
|
+
}): Judgment;
|
|
39
|
+
/** The store in the metarepo: judgments/ (or .atticus/judgments/ when adopted). */
|
|
40
|
+
export declare function fileJudgments(root: string): JudgmentStore & {
|
|
41
|
+
list(kind?: string): Promise<{
|
|
42
|
+
judgments: Judgment[];
|
|
43
|
+
problems: {
|
|
44
|
+
file: string;
|
|
45
|
+
message: string;
|
|
46
|
+
}[];
|
|
47
|
+
}>;
|
|
48
|
+
};
|
|
49
|
+
/** A store in memory, for tests and for a step run without a metarepo. */
|
|
50
|
+
export declare function memoryJudgments(initial?: Judgment[]): JudgmentStore & {
|
|
51
|
+
all(): Judgment[];
|
|
52
|
+
};
|
|
53
|
+
/**
|
|
54
|
+
* A person overrides a judgment: their verdict is kept, with the one it replaced under
|
|
55
|
+
* `overrides`. Every step that reads the judgment follows the person from then on.
|
|
56
|
+
*/
|
|
57
|
+
export declare function overrideJudgment(store: JudgmentStore, kind: string, key: string, o: {
|
|
58
|
+
verdict: JudgmentVerdict;
|
|
59
|
+
value?: unknown;
|
|
60
|
+
name: string;
|
|
61
|
+
at: string;
|
|
62
|
+
why?: string;
|
|
63
|
+
}): Promise<Judgment>;
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@maycombhq/core/light`: the few parts of core the command line needs before it knows which
|
|
3
|
+
* command runs (its help's first line and its log). They load no schema, no zod and no YAML
|
|
4
|
+
* reader, so `atticus --help` and the start of every command don't pay for building C1-C6.
|
|
5
|
+
* Each is the same export as the package's own (`@maycombhq/core`); nothing here is new.
|
|
6
|
+
*/
|
|
7
|
+
export { SCHEMA_VERSION } from "./schema/version.js";
|
|
8
|
+
export { createLog, logFileOf, NO_LOG, type Log, type LogEntry, type LogLevel } from "./log.js";
|
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import type { CatalogRecord } from "./catalog.js";
|
|
3
|
+
import { type FactsJoinResult, type JoinRepo } from "./facts-join.js";
|
|
4
|
+
import type { EvidenceT } from "./schema/common.js";
|
|
5
|
+
/**
|
|
6
|
+
* Links confirmed from outside the code (ADR 0151): contract files a consumer keeps (J3) and
|
|
7
|
+
* traffic exports a person imported as aggregate counts (J4). Neither makes a link: the join
|
|
8
|
+
* makes links from cited code. They add evidence and a flag to an Interface the join already
|
|
9
|
+
* made, and say where the two disagree: a contract or traffic the join has no link for, a
|
|
10
|
+
* contract naming another provider, a link no traffic used over the range.
|
|
11
|
+
*
|
|
12
|
+
* A contract or traffic never raises a guess (`inferred`) to verified: a guess stays a guess
|
|
13
|
+
* until the code names the callee (ADR 0151 §3). Pure: the same join and evidence files give
|
|
14
|
+
* the same marks and findings, whatever order they come in.
|
|
15
|
+
*/
|
|
16
|
+
/** An Interface a consumer's contract file (a Pact interaction, a consumer-side OpenAPI operation) confirms. */
|
|
17
|
+
export declare const CONFIRMED_BY_CONTRACT = "confirmed-by-contract";
|
|
18
|
+
/** An Interface a contract file names another provider for: a gap a person settles. */
|
|
19
|
+
export declare const CONTRACT_DISAGREES = "contract-disagrees";
|
|
20
|
+
/** An Interface an imported traffic export shows used over its range. */
|
|
21
|
+
export declare const SEEN_IN_TRAFFIC = "seen-in-traffic";
|
|
22
|
+
/** The flags this module writes, and takes off again before every write. */
|
|
23
|
+
export declare const LINK_EVIDENCE_FLAGS: ReadonlySet<string>;
|
|
24
|
+
/** The flags that are evidence a link holds, never a gap (as `JOIN_HOW_FLAGS`). */
|
|
25
|
+
export declare const LINK_EVIDENCE_NOT_GAPS: ReadonlySet<string>;
|
|
26
|
+
/** The `extractor` of the evidence this module adds, so a write takes the last write's off. */
|
|
27
|
+
export declare const CONTRACT_EVIDENCE = "atticus-contract@1";
|
|
28
|
+
export declare const TRAFFIC_EVIDENCE = "atticus-traffic@1";
|
|
29
|
+
/** One request a consumer's contract file says it makes. */
|
|
30
|
+
export declare const ContractEntry: z.ZodObject<{
|
|
31
|
+
format: z.ZodEnum<{
|
|
32
|
+
openapi: "openapi";
|
|
33
|
+
pact: "pact";
|
|
34
|
+
}>;
|
|
35
|
+
file: z.ZodString;
|
|
36
|
+
line: z.ZodNumber;
|
|
37
|
+
consumer: z.ZodOptional<z.ZodString>;
|
|
38
|
+
provider: z.ZodOptional<z.ZodString>;
|
|
39
|
+
hosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
40
|
+
method: z.ZodOptional<z.ZodString>;
|
|
41
|
+
path: z.ZodString;
|
|
42
|
+
}, z.core.$strict>;
|
|
43
|
+
export type ContractEntryT = z.infer<typeof ContractEntry>;
|
|
44
|
+
/**
|
|
45
|
+
* The facts companion `<repo>.contracts.yaml` (ADR 0151): the contract files read in a repo's
|
|
46
|
+
* checkout at the facts' commit by `atticus verify <repo> --write`, so every later write of any
|
|
47
|
+
* repo reads the same entries without the checkout.
|
|
48
|
+
*/
|
|
49
|
+
export declare const ContractsFile: z.ZodObject<{
|
|
50
|
+
schemaVersion: z.ZodLiteral<1>;
|
|
51
|
+
repo: z.ZodString;
|
|
52
|
+
commit: z.ZodOptional<z.ZodString>;
|
|
53
|
+
entries: z.ZodArray<z.ZodObject<{
|
|
54
|
+
format: z.ZodEnum<{
|
|
55
|
+
openapi: "openapi";
|
|
56
|
+
pact: "pact";
|
|
57
|
+
}>;
|
|
58
|
+
file: z.ZodString;
|
|
59
|
+
line: z.ZodNumber;
|
|
60
|
+
consumer: z.ZodOptional<z.ZodString>;
|
|
61
|
+
provider: z.ZodOptional<z.ZodString>;
|
|
62
|
+
hosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
63
|
+
method: z.ZodOptional<z.ZodString>;
|
|
64
|
+
path: z.ZodString;
|
|
65
|
+
}, z.core.$strict>>;
|
|
66
|
+
}, z.core.$strict>;
|
|
67
|
+
export type ContractsFileT = z.infer<typeof ContractsFile>;
|
|
68
|
+
/** One aggregate of an imported traffic export: never a raw row. */
|
|
69
|
+
export declare const TrafficRow: z.ZodObject<{
|
|
70
|
+
app: z.ZodString;
|
|
71
|
+
component: z.ZodOptional<z.ZodString>;
|
|
72
|
+
method: z.ZodString;
|
|
73
|
+
path: z.ZodString;
|
|
74
|
+
proxy: z.ZodOptional<z.ZodString>;
|
|
75
|
+
basepath: z.ZodOptional<z.ZodString>;
|
|
76
|
+
count: z.ZodNumber;
|
|
77
|
+
}, z.core.$strict>;
|
|
78
|
+
export type TrafficRowT = z.infer<typeof TrafficRow>;
|
|
79
|
+
/** `evidence/traffic/<source>-<from>-<to>.yaml`: what an import kept, reviewed in a pull request. */
|
|
80
|
+
export declare const TrafficFile: z.ZodObject<{
|
|
81
|
+
schemaVersion: z.ZodLiteral<1>;
|
|
82
|
+
source: z.ZodString;
|
|
83
|
+
from: z.ZodString;
|
|
84
|
+
to: z.ZodString;
|
|
85
|
+
inputSha256: z.ZodString;
|
|
86
|
+
rows: z.ZodArray<z.ZodObject<{
|
|
87
|
+
app: z.ZodString;
|
|
88
|
+
component: z.ZodOptional<z.ZodString>;
|
|
89
|
+
method: z.ZodString;
|
|
90
|
+
path: z.ZodString;
|
|
91
|
+
proxy: z.ZodOptional<z.ZodString>;
|
|
92
|
+
basepath: z.ZodOptional<z.ZodString>;
|
|
93
|
+
count: z.ZodNumber;
|
|
94
|
+
}, z.core.$strict>>;
|
|
95
|
+
}, z.core.$strict>;
|
|
96
|
+
export type TrafficFileT = z.infer<typeof TrafficFile>;
|
|
97
|
+
/** The file name a traffic aggregate is written under. */
|
|
98
|
+
export declare const trafficFileName: (f: Pick<TrafficFileT, "source" | "from" | "to">) => string;
|
|
99
|
+
/** The canonical text of a traffic aggregate: keys in schema order, one row a block. */
|
|
100
|
+
export declare function trafficFileText(f: TrafficFileT): string;
|
|
101
|
+
/** A traffic file read back, each row with the line it starts on (what its evidence cites). */
|
|
102
|
+
export interface TrafficOnFile {
|
|
103
|
+
/** Its path in the metarepo, forward slashes (`evidence/traffic/...`). */
|
|
104
|
+
rel: string;
|
|
105
|
+
file: TrafficFileT;
|
|
106
|
+
lines: number[];
|
|
107
|
+
}
|
|
108
|
+
/** Read a traffic aggregate with its rows' lines; a problem when it isn't one. */
|
|
109
|
+
export declare function readTrafficFile(rel: string, text: string): {
|
|
110
|
+
ok: true;
|
|
111
|
+
traffic: TrafficOnFile;
|
|
112
|
+
} | {
|
|
113
|
+
ok: false;
|
|
114
|
+
message: string;
|
|
115
|
+
};
|
|
116
|
+
/** A link end as a finding names it. */
|
|
117
|
+
export interface LinkRef {
|
|
118
|
+
interface: string;
|
|
119
|
+
from: string;
|
|
120
|
+
to: string;
|
|
121
|
+
method?: string;
|
|
122
|
+
path: string;
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* What a contract file says that the join doesn't: `provider-differs` (the consumer's request is
|
|
126
|
+
* a link the join made to another component), `no-link` (the join has no link for it),
|
|
127
|
+
* `unknown-provider` (the provider it names is no component or repo of the estate).
|
|
128
|
+
*/
|
|
129
|
+
export interface ContractFinding {
|
|
130
|
+
reason: "provider-differs" | "no-link" | "unknown-provider";
|
|
131
|
+
repo: string;
|
|
132
|
+
/** file:line in the consumer's repo. */
|
|
133
|
+
at: string;
|
|
134
|
+
format: "pact" | "openapi";
|
|
135
|
+
consumer: string;
|
|
136
|
+
provider?: string;
|
|
137
|
+
method?: string;
|
|
138
|
+
path: string;
|
|
139
|
+
/** The links the request matched (for `provider-differs`, `unknown-provider`). */
|
|
140
|
+
links: LinkRef[];
|
|
141
|
+
message: string;
|
|
142
|
+
}
|
|
143
|
+
/**
|
|
144
|
+
* What a traffic export says that the join doesn't: `missed-link` (traffic no link carries),
|
|
145
|
+
* `unknown-app` (an app named like no component: a person names it in the row's `component`),
|
|
146
|
+
* `unseen-link` (a link the export covers that no traffic used over the range).
|
|
147
|
+
*/
|
|
148
|
+
export interface TrafficFinding {
|
|
149
|
+
reason: "missed-link" | "unknown-app" | "unseen-link";
|
|
150
|
+
/** The traffic file, and the row's line (not for `unseen-link`). */
|
|
151
|
+
file: string;
|
|
152
|
+
at?: string;
|
|
153
|
+
range: {
|
|
154
|
+
from: string;
|
|
155
|
+
to: string;
|
|
156
|
+
};
|
|
157
|
+
app?: string;
|
|
158
|
+
component?: string;
|
|
159
|
+
method?: string;
|
|
160
|
+
path?: string;
|
|
161
|
+
count?: number;
|
|
162
|
+
link?: LinkRef;
|
|
163
|
+
message: string;
|
|
164
|
+
}
|
|
165
|
+
/** A link the traffic showed, with how much and over what range. */
|
|
166
|
+
export interface TrafficSeen extends LinkRef {
|
|
167
|
+
count: number;
|
|
168
|
+
file: string;
|
|
169
|
+
range: {
|
|
170
|
+
from: string;
|
|
171
|
+
to: string;
|
|
172
|
+
};
|
|
173
|
+
}
|
|
174
|
+
export interface LinkEvidenceResult {
|
|
175
|
+
/** By Interface id: the flags and evidence to add. */
|
|
176
|
+
marks: Record<string, {
|
|
177
|
+
flags: string[];
|
|
178
|
+
evidence: EvidenceT[];
|
|
179
|
+
}>;
|
|
180
|
+
contracts: {
|
|
181
|
+
entries: number;
|
|
182
|
+
confirmed: LinkRef[];
|
|
183
|
+
findings: ContractFinding[];
|
|
184
|
+
};
|
|
185
|
+
traffic: {
|
|
186
|
+
rows: number;
|
|
187
|
+
seen: TrafficSeen[];
|
|
188
|
+
findings: TrafficFinding[];
|
|
189
|
+
};
|
|
190
|
+
}
|
|
191
|
+
export interface LinkEvidenceInput {
|
|
192
|
+
/** The whole estate's join (every repo with verified facts). */
|
|
193
|
+
join: FactsJoinResult;
|
|
194
|
+
repos: readonly JoinRepo[];
|
|
195
|
+
contracts?: readonly ContractsFileT[];
|
|
196
|
+
traffic?: readonly TrafficOnFile[];
|
|
197
|
+
}
|
|
198
|
+
/**
|
|
199
|
+
* Mark the joins the contract files and traffic aggregates bear out, and list where they and the
|
|
200
|
+
* join disagree (ADR 0151).
|
|
201
|
+
*/
|
|
202
|
+
export declare function linkEvidenceOf(input: LinkEvidenceInput): LinkEvidenceResult;
|
|
203
|
+
/**
|
|
204
|
+
* The records without what an earlier write's contract and traffic evidence added: its flags and
|
|
205
|
+
* evidence entries. A record left with no evidence at all (none could be) is dropped.
|
|
206
|
+
*/
|
|
207
|
+
export declare function stripLinkEvidence(records: readonly CatalogRecord[]): CatalogRecord[];
|
|
208
|
+
/**
|
|
209
|
+
* The records with the marks added: each marked Interface gets its flags (after its own) and
|
|
210
|
+
* evidence (after its own, each line once). Its confidence is never changed (ADR 0151 §3).
|
|
211
|
+
*/
|
|
212
|
+
export declare function applyLinkEvidence(records: readonly CatalogRecord[], marks: LinkEvidenceResult["marks"]): CatalogRecord[];
|