@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,49 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The local log (ADR 0050): one JSON object per line in `.atticus/logs/atticus.log`,
|
|
3
|
+
* kept on this machine. It records what ran (command and flag names, never their values),
|
|
4
|
+
* how it ended, how long it took and, on a crash, the error with its stack. Every entry is
|
|
5
|
+
* redacted before it is written: secrets, credentials in URLs, tokens and the person's home
|
|
6
|
+
* folder never reach the file.
|
|
7
|
+
*/
|
|
8
|
+
export type LogLevel = "debug" | "info" | "warn" | "error" | "off";
|
|
9
|
+
export interface LogEntry {
|
|
10
|
+
at: string;
|
|
11
|
+
level: Exclude<LogLevel, "off">;
|
|
12
|
+
event: string;
|
|
13
|
+
[field: string]: unknown;
|
|
14
|
+
}
|
|
15
|
+
export interface Log {
|
|
16
|
+
readonly file: string;
|
|
17
|
+
debug(event: string, fields?: Record<string, unknown>): void;
|
|
18
|
+
info(event: string, fields?: Record<string, unknown>): void;
|
|
19
|
+
warn(event: string, fields?: Record<string, unknown>): void;
|
|
20
|
+
error(event: string, err: unknown, fields?: Record<string, unknown>): void;
|
|
21
|
+
}
|
|
22
|
+
export declare const LOG_MAX_BYTES: number;
|
|
23
|
+
export declare const LOG_KEEP = 3;
|
|
24
|
+
/** Where the log of a metarepo lives. */
|
|
25
|
+
export declare const logFileOf: (root: string) => string;
|
|
26
|
+
/** Strings with anything that looks like a secret replaced by "***", and home folders by "~". */
|
|
27
|
+
export declare function redactText(s: string, o?: {
|
|
28
|
+
home?: string;
|
|
29
|
+
user?: string;
|
|
30
|
+
}): string;
|
|
31
|
+
/** A value with secret-named keys masked and every string redacted. */
|
|
32
|
+
export declare function redact(v: unknown, o?: {
|
|
33
|
+
home?: string;
|
|
34
|
+
user?: string;
|
|
35
|
+
}): unknown;
|
|
36
|
+
/** The level from ATTICUS_LOG (debug, info, warn, error or off); info by default. */
|
|
37
|
+
export declare function logLevelFrom(env?: NodeJS.ProcessEnv): LogLevel;
|
|
38
|
+
/**
|
|
39
|
+
* A log for a metarepo. Writing never throws: a log that can't be written (a read-only folder,
|
|
40
|
+
* a full disk) is skipped rather than failing the command it describes.
|
|
41
|
+
*/
|
|
42
|
+
export declare function createLog(root: string, o?: {
|
|
43
|
+
level?: LogLevel;
|
|
44
|
+
now?: () => Date;
|
|
45
|
+
maxBytes?: number;
|
|
46
|
+
keep?: number;
|
|
47
|
+
}): Log;
|
|
48
|
+
/** A log that writes nothing (tests, and commands run with no metarepo). */
|
|
49
|
+
export declare const NO_LOG: Log;
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import { RepoDescription } from "./schema/workspace.js";
|
|
2
|
+
/**
|
|
3
|
+
* Editing `org-pack/profiles/<platform>/repos.manifest.yaml` in place, keeping the file's
|
|
4
|
+
* comments and the order a person put its entries in: a repo's description (ADR 0128), and the
|
|
5
|
+
* schema-version rewrite `atticus upgrade` runs. Every write is checked against the manifest
|
|
6
|
+
* schema first, so a manifest Atticus can't read is never written.
|
|
7
|
+
*/
|
|
8
|
+
/** One profile's manifest: where it is on disk and how the metarepo names it. */
|
|
9
|
+
export interface ManifestFile {
|
|
10
|
+
path: string;
|
|
11
|
+
rel: string;
|
|
12
|
+
platform: string;
|
|
13
|
+
}
|
|
14
|
+
/** Every profile's manifest, by platform name. */
|
|
15
|
+
export declare function manifestFiles(root: string): Promise<ManifestFile[]>;
|
|
16
|
+
export declare class ManifestEditError extends Error {
|
|
17
|
+
readonly code: "not-found" | "invalid";
|
|
18
|
+
constructor(code: "not-found" | "invalid", message: string);
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Set, replace or remove a repo's description in the manifest that lists it. A person's own
|
|
22
|
+
* words come in as `verified`; a draft the assistant wrote comes in as `suggested` with its
|
|
23
|
+
* cites, and stays marked unconfirmed until a person confirms it.
|
|
24
|
+
*/
|
|
25
|
+
export declare function setManifestDescription(root: string, repo: string, description: RepoDescription | undefined): Promise<ManifestFile>;
|
|
26
|
+
/**
|
|
27
|
+
* Add a repo to a platform's manifest, keeping the file's comments and the order its entries
|
|
28
|
+
* are in. The entry is written with the fields that are set and no more, and the whole manifest
|
|
29
|
+
* is checked before it is written, so a duplicate id or a password in the URL is refused here.
|
|
30
|
+
*/
|
|
31
|
+
export declare function addManifestRepo(root: string, platform: string, entry: {
|
|
32
|
+
id: string;
|
|
33
|
+
url: string;
|
|
34
|
+
type: string;
|
|
35
|
+
owner: string;
|
|
36
|
+
/** The branch to read, when known (a clone's current branch); the manifest's default is main. */
|
|
37
|
+
defaultBranch?: string;
|
|
38
|
+
system?: string;
|
|
39
|
+
component?: string;
|
|
40
|
+
description?: RepoDescription;
|
|
41
|
+
}): Promise<ManifestFile>;
|
|
42
|
+
/**
|
|
43
|
+
* F5: move a repo's id in the manifest that lists it, in place (comments and order kept). Refused
|
|
44
|
+
* when no manifest lists the repo, or any lists the new id already (ids are unique across every
|
|
45
|
+
* profile, ADR 0009). Only the id changes; the files filed under it are the caller's to move.
|
|
46
|
+
*/
|
|
47
|
+
export declare function renameManifestRepo(root: string, repo: string, to: string): Promise<ManifestFile>;
|
|
48
|
+
/**
|
|
49
|
+
* Rewrite every manifest at a version below `to` (the current one when left out) at that
|
|
50
|
+
* version, keeping its comments and order (ADR 0009, 0128, 0134). Nothing a person wrote
|
|
51
|
+
* changes: older manifests are read as they are and stay valid, and this only keeps diffs clean.
|
|
52
|
+
* `dryRun` lists what it would change.
|
|
53
|
+
*/
|
|
54
|
+
export declare function migrateManifests(root: string, o?: {
|
|
55
|
+
dryRun?: boolean;
|
|
56
|
+
to?: number;
|
|
57
|
+
}): Promise<string[]>;
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import { type CatalogRecord, type RecordIssue } from "./catalog.js";
|
|
2
|
+
/**
|
|
3
|
+
* Merge and identity: turns the records every repo's scan produced into one catalog.
|
|
4
|
+
*
|
|
5
|
+
* - Records with the same identity merge (evidence is unioned, the best value wins).
|
|
6
|
+
* - REST endpoints are keyed by component, method and normalised path and get a canonical id.
|
|
7
|
+
* - Loose ends (Unresolved records, ADR 0016) are resolved: HTTP calls into Interfaces
|
|
8
|
+
* (through the gateway when a route's base path matches), publishes and subscribes into
|
|
9
|
+
* event Interfaces, database access into Tables' readers and writers; GraphQL, gRPC and
|
|
10
|
+
* webhook loose ends (ADR 0040) into Interfaces to the matching typed endpoints.
|
|
11
|
+
* - A direct synchronous call between two components with a `mesh` Setting goes via mesh.
|
|
12
|
+
* - Interfaces are verified only when both ends are seen; otherwise inferred.
|
|
13
|
+
* - Whatever can't be resolved stays as an Unresolved record with its owner.
|
|
14
|
+
*
|
|
15
|
+
* Deterministic: the same input gives the same catalog, sorted by kind and id. See ADR 0017.
|
|
16
|
+
*/
|
|
17
|
+
export interface MergeRepo {
|
|
18
|
+
id: string;
|
|
19
|
+
component?: string;
|
|
20
|
+
system?: string;
|
|
21
|
+
type: string;
|
|
22
|
+
/** Hosts the repo's component (or, for a gateway repo, the gateway) answers on (ADR 0053). */
|
|
23
|
+
hosts?: string[];
|
|
24
|
+
}
|
|
25
|
+
export interface MergeSystem {
|
|
26
|
+
id: string;
|
|
27
|
+
name: string;
|
|
28
|
+
boundary: "product" | "internal" | "vendor";
|
|
29
|
+
owner?: string;
|
|
30
|
+
aliases: string[];
|
|
31
|
+
/** ADR 0162 amendment: the topics and queues it owns, kept apart from its aliases. */
|
|
32
|
+
topics?: string[];
|
|
33
|
+
/** Copied to the System record (ADR 0040: saas marks a SaaS vendor). */
|
|
34
|
+
tags?: string[];
|
|
35
|
+
}
|
|
36
|
+
/** What merge needs from an integration pattern (C6) to infer it on a hop. */
|
|
37
|
+
export interface MergePattern {
|
|
38
|
+
code: string;
|
|
39
|
+
status: string;
|
|
40
|
+
detection: {
|
|
41
|
+
via: string[];
|
|
42
|
+
sync?: string;
|
|
43
|
+
targetBoundary?: string;
|
|
44
|
+
sameSystem?: boolean;
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* ADR 0162 (F8): the flag on an Interface a topic or queue makes to an outside system because the
|
|
49
|
+
* profile names the topic under the system's topics: a person's word, not the code's.
|
|
50
|
+
*/
|
|
51
|
+
export declare const DECLARED_TOPIC = "declared-topic";
|
|
52
|
+
export interface MergeInput {
|
|
53
|
+
records: CatalogRecord[];
|
|
54
|
+
repos: MergeRepo[];
|
|
55
|
+
systems: MergeSystem[];
|
|
56
|
+
patterns?: MergePattern[];
|
|
57
|
+
/** Where the systems came from, for their evidence (e.g. "org-pack/profiles/forge/profile.yaml"). */
|
|
58
|
+
profilePath?: string;
|
|
59
|
+
/**
|
|
60
|
+
* Route a call to an undeclared host through the gateway route its path starts with, as before
|
|
61
|
+
* ADR 0053. Only for callers without the repos manifest (drift on a fetched copy of the
|
|
62
|
+
* catalog), where no host is declared; a full scan never sets it.
|
|
63
|
+
*/
|
|
64
|
+
gatewayByBasepath?: boolean;
|
|
65
|
+
}
|
|
66
|
+
export interface MergeResult {
|
|
67
|
+
records: CatalogRecord[];
|
|
68
|
+
/** Records merge produced that failed C1 (a bug if ever non-empty). */
|
|
69
|
+
invalid: {
|
|
70
|
+
record: unknown;
|
|
71
|
+
issues: RecordIssue[];
|
|
72
|
+
}[];
|
|
73
|
+
stats: {
|
|
74
|
+
interfaces: number;
|
|
75
|
+
verified: number;
|
|
76
|
+
unresolved: number;
|
|
77
|
+
};
|
|
78
|
+
/** Things worth knowing that aren't wrong, e.g. hosts that look like a gateway nobody declared. */
|
|
79
|
+
notes: string[];
|
|
80
|
+
}
|
|
81
|
+
/** Canonical REST endpoint id: <component>.<method>-<last fixed path segment, singular>. */
|
|
82
|
+
export declare function endpointId(component: string, method: string | undefined, normalizedPath: string): string;
|
|
83
|
+
export declare function mergeCatalog(input: MergeInput): MergeResult;
|
|
84
|
+
/** The Setting key that says a component runs in a service mesh (ADR 0040); its value names the mesh. */
|
|
85
|
+
export declare const MESH_KEY = "mesh";
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
/** True when the org pack is in `.atticus/org-pack/` (a repo adopted in place). */
|
|
2
|
+
export declare function isAdopted(root: string): boolean;
|
|
3
|
+
/** The org pack folder: `org-pack/` at the root, else `.atticus/org-pack/` when adopted. */
|
|
4
|
+
export declare function orgPackDirOf(root: string): string;
|
|
5
|
+
/** The org pack folder relative to the root with forward slashes, for messages and stored paths. */
|
|
6
|
+
export declare function orgPackRelOf(root: string): string;
|
|
7
|
+
/** The folder holding local state (`.index/`, `.runs/`, `workspace/`): the root, or `.atticus/`. */
|
|
8
|
+
export declare function stateDirOf(root: string): string;
|
|
9
|
+
/** Run folders (`.runs/<change>/<runId>/`: prompts, packs, build logs): under the state folder. */
|
|
10
|
+
export declare function runsDirOf(root: string): string;
|
|
11
|
+
/** The run folders relative to the root with forward slashes, for messages and stored paths. */
|
|
12
|
+
export declare function runsRelOf(root: string): string;
|
|
13
|
+
/** Where intake looks for what people drop in: `inputs/`, or `.atticus/inputs/` when adopted. */
|
|
14
|
+
export declare function inputsDirOf(root: string): string;
|
|
15
|
+
/** Where Atticus writes proposals for people to review, relative to the root with forward slashes. */
|
|
16
|
+
export declare function proposalsRelOf(root: string): string;
|
|
17
|
+
/** The proposals folder: `proposals/`, or `.atticus/proposals/` when adopted. */
|
|
18
|
+
export declare function proposalsDirOf(root: string): string;
|
|
19
|
+
/** Where questions to people live (ADR 0078), relative to the root: `questions`, or `.atticus/questions` when adopted. */
|
|
20
|
+
export declare function questionsRelOf(root: string): string;
|
|
21
|
+
/** The questions folder (ADR 0078). */
|
|
22
|
+
export declare function questionsDirOf(root: string): string;
|
|
23
|
+
/** Where the facts an assistant writes live, with forward slashes (ADR 0124): `facts`, or `.atticus/facts` when adopted. */
|
|
24
|
+
export declare function factsRelOf(root: string): string;
|
|
25
|
+
/** The facts folder (ADR 0124): `<repo>.jsonl` the assistant writes, `<repo>.rejected.jsonl` and `<repo>.verify.yaml` the verifier writes. */
|
|
26
|
+
export declare function factsDirOf(root: string): string;
|
|
27
|
+
/** Where evidence from outside the code lives (ADR 0151), relative to the root: `evidence`, or `.atticus/evidence` when adopted. */
|
|
28
|
+
export declare function evidenceRelOf(root: string): string;
|
|
29
|
+
/** Where other teams' shared maps live (ADR 0160), relative to the root: `shared`, or `.atticus/shared` when adopted. */
|
|
30
|
+
export declare function sharedRelOf(root: string): string;
|
|
31
|
+
/** The shared maps folder (ADR 0160): `<team>/map.yaml` and `<team>/facts/<repo>.jsonl`, their entries, read-only. */
|
|
32
|
+
export declare function sharedDirOf(root: string): string;
|
|
33
|
+
/** The evidence folder (ADR 0151): `traffic/<source>-<from>-<to>.yaml`, the traffic aggregates a person imported. */
|
|
34
|
+
export declare function evidenceDirOf(root: string): string;
|
|
35
|
+
/**
|
|
36
|
+
* The files the facts folder keeps beside a repo's facts file (ADR 0124): the questions the
|
|
37
|
+
* assistant raised, what the verifier rejected, the files read and found to hold no fact, a
|
|
38
|
+
* person's corrections, the verifier's report, and the read plan of a repo read in parts
|
|
39
|
+
* (addendum A-ledger). None of them is a facts file of its own.
|
|
40
|
+
*/
|
|
41
|
+
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"];
|
|
42
|
+
/**
|
|
43
|
+
* The repo a file in the facts folder belongs to, and whether it is the repo's facts file
|
|
44
|
+
* (`<repo>.jsonl`) or one of its companions; undefined for any other file. Every place that lists
|
|
45
|
+
* the facts folder reads it through this, so a companion is never taken for another repo.
|
|
46
|
+
*/
|
|
47
|
+
export declare function factsFileOf(name: string): {
|
|
48
|
+
repo: string;
|
|
49
|
+
facts: boolean;
|
|
50
|
+
} | undefined;
|
|
51
|
+
/** Where the map rendered from a repo's verified facts lives, with forward slashes (ADR 0124): `map`, or `.atticus/map` when adopted. */
|
|
52
|
+
export declare function mapRelOf(root: string): string;
|
|
53
|
+
/** The map folder (ADR 0124): `<repo>/map.md`, `<repo>/flows/` and `<repo>/contracts/`, written by atticus map render. */
|
|
54
|
+
export declare function mapDirOf(root: string): string;
|
|
55
|
+
/** Where judgments live (ADR 0117), relative to the root: `judgments`, or `.atticus/judgments` when adopted. */
|
|
56
|
+
export declare function judgmentsRelOf(root: string): string;
|
|
57
|
+
/** The judgments folder (ADR 0117): judgments/<kind>/<key>.yaml. */
|
|
58
|
+
export declare function judgmentsDirOf(root: string): string;
|
|
59
|
+
/** Where repo specs live (ADR 0079), relative to the root: `specs`, or `.atticus/specs` when adopted. */
|
|
60
|
+
export declare function specsRelOf(root: string): string;
|
|
61
|
+
/** The specs folder (ADR 0079), holding one folder per repo. */
|
|
62
|
+
export declare function specsDirOf(root: string): string;
|
|
63
|
+
/** One repo's spec folder, relative to the root: `specs/<repo>` (spec.yaml and one file per flow). */
|
|
64
|
+
export declare function specRelOf(root: string, repo: string): string;
|
|
65
|
+
/** One repo's spec folder (ADR 0079). */
|
|
66
|
+
export declare function specDirOf(root: string, repo: string): string;
|
|
67
|
+
/**
|
|
68
|
+
* Where knowledge lives (ADR 0083), relative to the root: `knowledge`, or `.atticus/knowledge`
|
|
69
|
+
* when adopted. It holds `snapshots/<source>/<date>/` (what a sync copied) and `items/` (what
|
|
70
|
+
* the knowledge scan read from a snapshot).
|
|
71
|
+
*/
|
|
72
|
+
export declare function knowledgeRelOf(root: string): string;
|
|
73
|
+
/** The knowledge folder (ADR 0083). */
|
|
74
|
+
export declare function knowledgeDirOf(root: string): string;
|
|
75
|
+
/** The layout from sources.yaml, or the defaults. */
|
|
76
|
+
export declare function layoutOf(root: string): {
|
|
77
|
+
catalog: string;
|
|
78
|
+
openspec: string;
|
|
79
|
+
};
|
|
80
|
+
/** The catalog folder (holding generated/ and curated/). */
|
|
81
|
+
export declare function catalogDirOf(root: string): string;
|
|
82
|
+
/**
|
|
83
|
+
* Where OpenSpec keeps changes, relative to the root with forward slashes: `changes/` under
|
|
84
|
+
* `layout.openspec` (`openspec/changes` by default, `.atticus/openspec/changes` in a repo
|
|
85
|
+
* adopted without its own OpenSpec folder). For messages, PR file lists and CODEOWNERS paths.
|
|
86
|
+
*/
|
|
87
|
+
export declare function changesRelOf(root: string): string;
|
|
88
|
+
/** The OpenSpec folder (holding config.yaml, specs/ and changes/). */
|
|
89
|
+
export declare function openspecDirOf(root: string): string;
|
|
90
|
+
/** The folder holding change folders (`<id>/`) and `archive/`. */
|
|
91
|
+
export declare function changesDirOf(root: string): string;
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
export interface MigrationResult {
|
|
2
|
+
/** Files rewritten at the current schema version (relative to the folder, "/"-separated). */
|
|
3
|
+
migrated: string[];
|
|
4
|
+
/** Record files already at the current version, left alone. */
|
|
5
|
+
current: string[];
|
|
6
|
+
/** Old record files that don't pass C1: left exactly as they are, with why. */
|
|
7
|
+
problems: {
|
|
8
|
+
file: string;
|
|
9
|
+
message: string;
|
|
10
|
+
}[];
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* Rewrite every older record file under a catalog folder (generated and curated) at the
|
|
14
|
+
* current schema version, in canonical form. Readers accept old files anyway; migrating once
|
|
15
|
+
* keeps diffs clean afterwards. A file that isn't a catalog record (no known `kind`) is not
|
|
16
|
+
* touched, nor is an old one that fails C1: it is reported, so nothing is half-migrated.
|
|
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
|
|
20
|
+
* canonical form also writes list defaults a hand-written file left out, exactly as a scan
|
|
21
|
+
* would write the record. `versions` limits it to files at those versions (each `atticus
|
|
22
|
+
* upgrade` step lists its own); what it writes is always the current version.
|
|
23
|
+
*
|
|
24
|
+
* `pendingOnly` is for a question about what is to do (`atticus doctor`, the app's Set up
|
|
25
|
+
* screen): `current` stays empty, and with `versions` a file whose text alone says it is at
|
|
26
|
+
* another version is not read as YAML. `migrated` and `problems` are the same as without it.
|
|
27
|
+
*/
|
|
28
|
+
export declare function migrateCatalog(dir: string, o?: {
|
|
29
|
+
dryRun?: boolean;
|
|
30
|
+
versions?: readonly number[];
|
|
31
|
+
pendingOnly?: boolean;
|
|
32
|
+
}): Promise<MigrationResult>;
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Whether a cited file is a database migration, by the file naming the common migration tools
|
|
3
|
+
* use (ADR 0124 addendum B-places): the facts cite a column where it is declared, and when that
|
|
4
|
+
* is a migration the store's migrations are known from the facts, so a change to its tables is a
|
|
5
|
+
* new migration beside them rather than an edit of a schema file. `tool` is C1's Migration tool;
|
|
6
|
+
* `version` is the part of the name the tool orders by. A schema file, an entity, a tool's own
|
|
7
|
+
* scaffolding (an environment script, a designer or snapshot file) is no migration.
|
|
8
|
+
*/
|
|
9
|
+
export interface MigrationFile {
|
|
10
|
+
tool: "flyway" | "liquibase" | "alembic" | "prisma" | "other";
|
|
11
|
+
version: string;
|
|
12
|
+
}
|
|
13
|
+
export declare function migrationOf(path: string): MigrationFile | undefined;
|
|
@@ -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 {};
|