@maycombhq/sdk 2.0.0-beta.2 → 2.0.0-beta.22
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 +5890 -1210
- package/npm/core/audit.d.ts +165 -0
- package/npm/core/catalog.d.ts +220 -66
- package/npm/core/cite.d.ts +20 -4
- package/npm/core/contract-check.d.ts +261 -0
- package/npm/core/decision-batches.d.ts +29 -0
- package/npm/core/declared-links.d.ts +62 -0
- package/npm/core/eol.d.ts +5 -0
- package/npm/core/fact-paths.d.ts +14 -0
- package/npm/core/facts-callers.d.ts +2 -0
- package/npm/core/facts-carry.d.ts +8 -2
- package/npm/core/facts-join-prototype.d.ts +66 -4
- package/npm/core/facts-join-vendor.d.ts +20 -2
- package/npm/core/facts-join.d.ts +325 -1
- package/npm/core/facts-terms.d.ts +108 -0
- package/npm/core/fs.d.ts +40 -4
- package/npm/core/glob.d.ts +14 -0
- package/npm/core/host-questions.d.ts +93 -1
- package/npm/core/identity.d.ts +28 -0
- package/npm/core/index.d.ts +24 -0
- package/npm/core/link-candidates.d.ts +103 -0
- package/npm/core/link-evidence.d.ts +212 -0
- package/npm/core/manifest-edit.d.ts +53 -4
- package/npm/core/merge.d.ts +28 -0
- package/npm/core/metarepo.d.ts +18 -1
- package/npm/core/migrate.d.ts +3 -2
- package/npm/core/org-notes.d.ts +180 -0
- package/npm/core/orgpack-defaults.d.ts +22 -6
- package/npm/core/orgpack-load.d.ts +19 -0
- package/npm/core/profile-migrate.d.ts +11 -0
- package/npm/core/question-order.d.ts +23 -0
- package/npm/core/question-owners.d.ts +53 -0
- package/npm/core/question-proposals.d.ts +77 -0
- package/npm/core/question-roles.d.ts +24 -0
- package/npm/core/questions.d.ts +90 -6
- package/npm/core/repo-files.d.ts +60 -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 +18 -0
- package/npm/core/schema/ai.d.ts +57 -9
- package/npm/core/schema/common.d.ts +32 -8
- package/npm/core/schema/component-type.d.ts +193 -0
- package/npm/core/schema/conventions.d.ts +80 -0
- package/npm/core/schema/fact-corrections.d.ts +105 -2
- package/npm/core/schema/facts.d.ts +410 -1
- package/npm/core/schema/kinds.d.ts +230 -66
- package/npm/core/schema/orgpack.d.ts +159 -19
- package/npm/core/schema/question.d.ts +228 -5
- package/npm/core/schema/reading-rules.d.ts +51 -0
- package/npm/core/schema/repo-type.d.ts +20 -2
- package/npm/core/schema/review.d.ts +7 -7
- package/npm/core/schema/scan-verify.d.ts +87 -45
- package/npm/core/schema/version.d.ts +4 -1
- package/npm/core/schema/workspace.d.ts +29 -11
- package/npm/core/shared-maps.d.ts +146 -0
- package/npm/core/stack-helpers.d.ts +32 -0
- package/npm/fs-repo.d.ts +2 -1
- package/npm/index.js +6194 -2542
- package/npm/listing.d.ts +14 -0
- package/package.json +1 -1
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import type { CatalogRecord } from "./catalog.js";
|
|
3
|
+
import { type FactEnd, type FactJoinOutside, type JoinRepo } from "./facts-join.js";
|
|
4
|
+
import type { Fact } from "./schema/facts.js";
|
|
5
|
+
/**
|
|
6
|
+
* Another team's Atticus map, read-only (plan item O3, ADR 0160). A team that runs Atticus on its
|
|
7
|
+
* own repos shares its verified facts; a person brings them in as files (`atticus join shared
|
|
8
|
+
* import <their metarepo>`), and only their entries are kept, under `shared/<team>/` in this
|
|
9
|
+
* metarepo: `map.yaml` (whose map it is, the system of our profile it stands for, their commit)
|
|
10
|
+
* and `facts/<repo>.jsonl` (their entry facts, quotes redacted).
|
|
11
|
+
*
|
|
12
|
+
* A call the estate join leaves to that system (its `outside` list: by a person's answer, the
|
|
13
|
+
* call's `to`, or a host the system's aliases name) is matched to the one entry of their map that
|
|
14
|
+
* serves it, by method and path the way the join matches our own (a base path their manifest
|
|
15
|
+
* gives in front, parameters folded), gRPC and SOAP by name. One is a match; two or more equally
|
|
16
|
+
* good, a question for a person; none, a gap: their map serves nothing like it.
|
|
17
|
+
*
|
|
18
|
+
* A match marks the call's Interface (still to their system, never to a record of theirs) with
|
|
19
|
+
* `joined-to-shared-map` and an evidence entry on their entry's line, at their repo and commit,
|
|
20
|
+
* `by` their team. Their facts are never verified, corrected or reported on here: they are theirs.
|
|
21
|
+
* Pure, apart from `readSharedMaps`, which reads the files.
|
|
22
|
+
*/
|
|
23
|
+
export declare const SHARED_MAP_SCHEMA_VERSION: 1;
|
|
24
|
+
/** The `extractor` of the evidence a shared map adds, so a write takes the last write's off. */
|
|
25
|
+
export declare const SHARED_MAP_EVIDENCE = "atticus-shared@1";
|
|
26
|
+
/** A call to a system whose shared map serves nothing like it (a gap on the Interface). */
|
|
27
|
+
export declare const NOT_IN_SHARED_MAP = "not-in-shared-map";
|
|
28
|
+
/** The flags this module writes, and takes off again before every write. */
|
|
29
|
+
export declare const SHARED_MAP_FLAGS: ReadonlySet<string>;
|
|
30
|
+
/** One of their repos, as their manifest gives it and as their facts were read. */
|
|
31
|
+
export declare const SharedMapRepo: z.ZodObject<{
|
|
32
|
+
repo: z.ZodString;
|
|
33
|
+
component: z.ZodOptional<z.ZodString>;
|
|
34
|
+
commit: z.ZodOptional<z.ZodString>;
|
|
35
|
+
hosts: z.ZodDefault<z.ZodArray<z.ZodString>>;
|
|
36
|
+
basePath: z.ZodOptional<z.ZodString>;
|
|
37
|
+
entries: z.ZodNumber;
|
|
38
|
+
}, z.core.$strict>;
|
|
39
|
+
export type SharedMapRepoT = z.infer<typeof SharedMapRepo>;
|
|
40
|
+
/** `shared/<team>/map.yaml`: whose map it is, what it stands for, and at which commit. */
|
|
41
|
+
export declare const SharedMapFile: z.ZodObject<{
|
|
42
|
+
schemaVersion: z.ZodLiteral<1>;
|
|
43
|
+
team: z.ZodString;
|
|
44
|
+
name: z.ZodString;
|
|
45
|
+
system: z.ZodString;
|
|
46
|
+
source: z.ZodOptional<z.ZodString>;
|
|
47
|
+
commit: z.ZodString;
|
|
48
|
+
importedAt: z.ZodISODateTime;
|
|
49
|
+
repos: z.ZodArray<z.ZodObject<{
|
|
50
|
+
repo: z.ZodString;
|
|
51
|
+
component: z.ZodOptional<z.ZodString>;
|
|
52
|
+
commit: z.ZodOptional<z.ZodString>;
|
|
53
|
+
hosts: z.ZodDefault<z.ZodArray<z.ZodString>>;
|
|
54
|
+
basePath: z.ZodOptional<z.ZodString>;
|
|
55
|
+
entries: z.ZodNumber;
|
|
56
|
+
}, z.core.$strict>>;
|
|
57
|
+
}, z.core.$strict>;
|
|
58
|
+
export type SharedMapFileT = z.infer<typeof SharedMapFile>;
|
|
59
|
+
/** A shared map as the join reads it: the file, with each repo's entry facts. */
|
|
60
|
+
export interface SharedMap {
|
|
61
|
+
team: string;
|
|
62
|
+
name: string;
|
|
63
|
+
system: string;
|
|
64
|
+
/** Their metarepo's commit. */
|
|
65
|
+
commit: string;
|
|
66
|
+
repos: readonly (SharedMapRepoT & {
|
|
67
|
+
facts: readonly Fact[];
|
|
68
|
+
})[];
|
|
69
|
+
}
|
|
70
|
+
/** An entry of their map: their repo, fact, component, line and the commit their code is at. */
|
|
71
|
+
export interface SharedEntryEnd extends FactEnd {
|
|
72
|
+
team: string;
|
|
73
|
+
commit?: string;
|
|
74
|
+
}
|
|
75
|
+
export interface SharedJoinMatch {
|
|
76
|
+
call: FactEnd;
|
|
77
|
+
team: string;
|
|
78
|
+
system: string;
|
|
79
|
+
entry: SharedEntryEnd;
|
|
80
|
+
method?: string;
|
|
81
|
+
/** The path (or gRPC/SOAP name) their entry serves, as it writes it. */
|
|
82
|
+
path: string;
|
|
83
|
+
}
|
|
84
|
+
export interface SharedJoinGap {
|
|
85
|
+
call: FactEnd;
|
|
86
|
+
team: string;
|
|
87
|
+
system: string;
|
|
88
|
+
method?: string;
|
|
89
|
+
path: string;
|
|
90
|
+
message: string;
|
|
91
|
+
}
|
|
92
|
+
export interface SharedJoinAsk {
|
|
93
|
+
call: FactEnd;
|
|
94
|
+
team: string;
|
|
95
|
+
system: string;
|
|
96
|
+
question: string;
|
|
97
|
+
candidates: SharedEntryEnd[];
|
|
98
|
+
}
|
|
99
|
+
export interface SharedJoinResult {
|
|
100
|
+
matches: SharedJoinMatch[];
|
|
101
|
+
gaps: SharedJoinGap[];
|
|
102
|
+
asks: SharedJoinAsk[];
|
|
103
|
+
}
|
|
104
|
+
export interface JoinSharedMapsInput {
|
|
105
|
+
/** The calls the estate join left to a system outside the estate (`FactsJoinResult.outside`). */
|
|
106
|
+
outside: readonly FactJoinOutside[];
|
|
107
|
+
/** Our repos, for the call facts and the config facts their hosts come from. */
|
|
108
|
+
repos: readonly JoinRepo[];
|
|
109
|
+
maps: readonly SharedMap[];
|
|
110
|
+
/** Our profiles' outside systems: id, name and aliases, to read the target a call was left to. */
|
|
111
|
+
systems: readonly {
|
|
112
|
+
id: string;
|
|
113
|
+
name: string;
|
|
114
|
+
aliases: readonly string[];
|
|
115
|
+
}[];
|
|
116
|
+
}
|
|
117
|
+
/** Match every call left to a system with a shared map to the entry of their map that serves it. */
|
|
118
|
+
export declare function joinSharedMaps(input: JoinSharedMapsInput): SharedJoinResult;
|
|
119
|
+
/** The records with every mark a shared map made taken off (evidence and flags). */
|
|
120
|
+
export declare function stripSharedMaps(records: readonly CatalogRecord[]): CatalogRecord[];
|
|
121
|
+
/**
|
|
122
|
+
* The records with the marks put on: the Interface a matched call made (from the call's
|
|
123
|
+
* component, to the system, citing the call's line) gets `joined-to-shared-map` and their entry's
|
|
124
|
+
* line as callee evidence, at their repo and commit, `by` their team; a call their map has no
|
|
125
|
+
* entry for gets `not-in-shared-map`. Its confidence, its `to` and its id never change: the
|
|
126
|
+
* Interface stays ours, to their system, and nothing of theirs becomes a record.
|
|
127
|
+
*/
|
|
128
|
+
export declare function applySharedMaps(records: readonly CatalogRecord[], result: SharedJoinResult, systems: JoinSharedMapsInput["systems"]): CatalogRecord[];
|
|
129
|
+
/** The part of a shared join about one repo's calls. */
|
|
130
|
+
export declare function sharedJoinAbout(all: SharedJoinResult, repo: string): SharedJoinResult;
|
|
131
|
+
/** A shared map on disk that couldn't be read, with why. */
|
|
132
|
+
export interface SharedMapProblem {
|
|
133
|
+
team: string;
|
|
134
|
+
message: string;
|
|
135
|
+
}
|
|
136
|
+
/**
|
|
137
|
+
* Every shared map under `shared/` (ADR 0160): each `<team>/map.yaml` and its `facts/<repo>.jsonl`,
|
|
138
|
+
* only their entry facts kept. A folder that doesn't read is a problem, said, and left out; a
|
|
139
|
+
* metarepo with none gives none. Files only.
|
|
140
|
+
*/
|
|
141
|
+
export declare function readSharedMaps(root: string): Promise<{
|
|
142
|
+
maps: (SharedMap & {
|
|
143
|
+
file: SharedMapFileT;
|
|
144
|
+
})[];
|
|
145
|
+
problems: SharedMapProblem[];
|
|
146
|
+
}>;
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The stack helpers (plan item G4): code that knows one stack or framework and helps the read,
|
|
3
|
+
* none of which the read needs. The assistant reads the code and cites every fact (ADR 0124);
|
|
4
|
+
* each helper only saves it work or cross-checks it, and each can be switched off:
|
|
5
|
+
*
|
|
6
|
+
* - `framework-models`: the frameworks taught in `org-pack/frameworks/` (ADR 0054, `atticus
|
|
7
|
+
* frameworks learn`), given to the reader as what a house annotation or client means, and
|
|
8
|
+
* `atticus verify`'s offer to learn a house framework. Off, the reader gets no model: it reads
|
|
9
|
+
* the house layer as ordinary code, cites the wrapper's call line with the path built in
|
|
10
|
+
* `cite.with`, and writes a question naming an annotation it can't place, as FACT_RULES say.
|
|
11
|
+
* - `gateway-walk`: the join through gateway routes to the service behind them (ADR 0124
|
|
12
|
+
* addenda A-gateway, A-gateway2). Off, a call that lands on a gateway route is joined to that
|
|
13
|
+
* route, the gateway's repo; the route's forwarding call is joined on its own, so the caller's
|
|
14
|
+
* link stops one hop short.
|
|
15
|
+
* - `readers`: the built-in readers and dialects of a scan (the cross-check of ADR 0124 §3) and
|
|
16
|
+
* the OpenAPI reader behind `atticus verify --skipped`'s uncovered spec operations (R1). Off, a
|
|
17
|
+
* repo with verified facts is projected from them alone, a repo with none gives no records,
|
|
18
|
+
* and verify lists no uncovered operations.
|
|
19
|
+
* - `derived-names`: the verifier's per-framework naming rules (`verify/src/derived.ts`: an
|
|
20
|
+
* ORM's table for an entity, Rails' routes, Spring Data REST's paths). Off, a claim must be
|
|
21
|
+
* written on its cited line or a `cite.with` part, so a reader cites the `@Table` or
|
|
22
|
+
* `table_name` line, or the route line, rather than the entity's class.
|
|
23
|
+
*
|
|
24
|
+
* Switched off for one run with `ATTICUS_HELPERS_OFF` (a comma list of the names, or `all`);
|
|
25
|
+
* the pure functions take an option of their own.
|
|
26
|
+
*/
|
|
27
|
+
export declare const STACK_HELPERS: readonly ["framework-models", "gateway-walk", "readers", "derived-names"];
|
|
28
|
+
export type StackHelper = (typeof STACK_HELPERS)[number];
|
|
29
|
+
/** The helpers switched off: `ATTICUS_HELPERS_OFF=all` or `gateway-walk,readers`. Unknown names are ignored. */
|
|
30
|
+
export declare function stackHelpersOff(env?: Readonly<Record<string, string | undefined>>): Set<StackHelper>;
|
|
31
|
+
/** Whether a helper is on for this run. */
|
|
32
|
+
export declare const helperOn: (h: StackHelper, env?: Readonly<Record<string, string | undefined>>) => boolean;
|
package/npm/fs-repo.d.ts
CHANGED
|
@@ -29,6 +29,7 @@ export declare class RepoReadError extends Error {
|
|
|
29
29
|
/**
|
|
30
30
|
* A read-only RepoHandle over a folder on disk (a base clone). Paths are repo-relative with
|
|
31
31
|
* forward slashes on every platform and listed in sorted order, so scans are deterministic.
|
|
32
|
-
* Symbolic links are never followed,
|
|
32
|
+
* Symbolic links are never followed, what the repo's .gitignore files ignore isn't listed, and
|
|
33
|
+
* no path may leave the repo folder.
|
|
33
34
|
*/
|
|
34
35
|
export declare function fsRepo(name: string, dir: string, commit: string, options?: FsRepoOptions): FsRepoHandle;
|