@maycombhq/sdk 0.0.0-stage → 2.0.0-beta.1

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/runner.js ADDED
@@ -0,0 +1,209 @@
1
+ import { parseRecord, } from "@maycombhq/core";
2
+ import { createParseCache, withParseCache } from "./parse-cache.js";
3
+ import { tooLargeMessage } from "./fs-repo.js";
4
+ import { globToRegExp } from "./plugin.js";
5
+ const EVIDENCE_FROM_REPO = new Set([
6
+ "code",
7
+ "config",
8
+ "spec",
9
+ "gateway",
10
+ "event-config",
11
+ "infrastructure",
12
+ "pipeline",
13
+ "migration",
14
+ ]);
15
+ /**
16
+ * Fill in what the runner knows so extractors don't repeat it: the repo, commit, scan time
17
+ * and "id@version" of the extractor on every piece of evidence read from this repo.
18
+ * Values an extractor set itself are kept.
19
+ */
20
+ export function stampEvidence(record, repo, extractor, scannedAt) {
21
+ if (record === null || typeof record !== "object")
22
+ return record;
23
+ const r = record;
24
+ if (!Array.isArray(r.evidence))
25
+ return record;
26
+ return {
27
+ ...r,
28
+ evidence: r.evidence.map((e) => {
29
+ if (e === null || typeof e !== "object")
30
+ return e;
31
+ const ev = { ...e };
32
+ if (typeof ev.source !== "string" || !EVIDENCE_FROM_REPO.has(ev.source))
33
+ return ev;
34
+ ev.repo ??= repo.name;
35
+ if (ev.repo === repo.name) {
36
+ ev.commit ??= repo.commit;
37
+ ev.scannedAt ??= scannedAt;
38
+ }
39
+ ev.extractor ??= extractor;
40
+ return ev;
41
+ }),
42
+ };
43
+ }
44
+ async function hasClaimedFiles(repo, claims) {
45
+ for await (const _ of repo.listFiles(claims))
46
+ return true;
47
+ return false;
48
+ }
49
+ function compareRecords(a, b) {
50
+ const ka = `${a.r.kind}\u0000${a.r.id}\u0000${a.x}`;
51
+ const kb = `${b.r.kind}\u0000${b.r.id}\u0000${b.x}`;
52
+ return ka < kb ? -1 : ka > kb ? 1 : 0;
53
+ }
54
+ /**
55
+ * Scan one repo with every extractor. Each extractor runs in isolation: one that throws is
56
+ * reported as failed and the others still run. Every emitted record is stamped and
57
+ * validated against contract C1; invalid ones are reported, never returned. Results come
58
+ * from the cache when the commit, extractor version, dialects and configuration are
59
+ * unchanged. Output order is deterministic.
60
+ */
61
+ export async function scanRepo(options) {
62
+ // One parse cache for every extractor of this repo scan (ADR 0067), unless the caller gave
63
+ // the repo its own; ours is freed when the scan ends, however it ends.
64
+ const own = options.repo.parseCache ? undefined : createParseCache();
65
+ try {
66
+ return await scanWith(own ? { ...options, repo: withParseCache(options.repo, own) } : options);
67
+ }
68
+ finally {
69
+ own?.dispose();
70
+ }
71
+ }
72
+ async function scanWith(options) {
73
+ const { repo } = options;
74
+ const dialects = [...(options.dialects ?? [])].sort();
75
+ const scannedAt = options.scannedAt ?? new Date().toISOString();
76
+ const useCache = options.cache !== undefined && !options.dirty;
77
+ const seenIds = new Set();
78
+ for (const x of options.extractors) {
79
+ if (seenIds.has(x.id))
80
+ throw new Error(`extractor ${x.id} is registered twice`);
81
+ seenIds.add(x.id);
82
+ }
83
+ const out = {
84
+ repo: repo.name,
85
+ commit: repo.commit,
86
+ scannedAt,
87
+ records: [],
88
+ runs: [],
89
+ warnings: [],
90
+ rejected: [],
91
+ };
92
+ const collected = [];
93
+ for (const extractor of [...options.extractors].sort((a, b) => a.id.localeCompare(b.id))) {
94
+ const tag = `${extractor.id}@${extractor.version}`;
95
+ const started = Date.now();
96
+ const run = {
97
+ extractor: extractor.id,
98
+ version: extractor.version,
99
+ status: "ran",
100
+ records: 0,
101
+ rejected: 0,
102
+ warnings: 0,
103
+ durationMs: 0,
104
+ };
105
+ const key = {
106
+ repo: repo.name,
107
+ commit: repo.commit,
108
+ extractor: extractor.id,
109
+ version: extractor.version,
110
+ dialects,
111
+ config: [
112
+ options.configFor?.(extractor) ?? "",
113
+ JSON.stringify(options.repoInfo ?? {}),
114
+ // A changed framework model means a different reading of the same code.
115
+ options.frameworks?.length ? JSON.stringify(options.frameworks) : "",
116
+ ].join("|"),
117
+ };
118
+ try {
119
+ const hit = useCache ? await options.cache.get(key) : undefined;
120
+ if (hit) {
121
+ run.status = "cached";
122
+ run.records = hit.records.length;
123
+ run.rejected = hit.rejected;
124
+ run.warnings = hit.warnings.length;
125
+ for (const r of hit.records)
126
+ collected.push({ r, x: extractor.id });
127
+ for (const w of hit.warnings)
128
+ out.warnings.push({ extractor: extractor.id, ...w });
129
+ }
130
+ else if (!(await hasClaimedFiles(repo, extractor.claims))) {
131
+ run.status = "skipped";
132
+ }
133
+ else {
134
+ const records = [];
135
+ const warnings = [];
136
+ const ids = new Set();
137
+ let rejected = 0;
138
+ const info = options.repoInfo ?? {};
139
+ const ctx = {
140
+ dialects,
141
+ ...(info.component ? { component: info.component } : {}),
142
+ ...(info.system ? { system: info.system } : {}),
143
+ ...(info.repoType ? { repoType: info.repoType } : {}),
144
+ ...(info.modules?.length ? { modules: info.modules } : {}),
145
+ ...(options.frameworks?.length ? { frameworks: options.frameworks } : {}),
146
+ scannedAt,
147
+ warn: (message, path) => warnings.push(path === undefined ? { message } : { message, path }),
148
+ };
149
+ // A file the repo left out for its size (fsRepo) is this extractor's warning when it
150
+ // claims it: kept in the cache with the extractor's results, so a rescan still says so.
151
+ const claimed = extractor.claims.map(globToRegExp);
152
+ const skippedNow = () => repo
153
+ .skippedFiles?.()
154
+ .filter((f) => claimed.some((m) => m.test(f.path))) ?? [];
155
+ for await (const emitted of extractor.scan(repo, ctx)) {
156
+ const parsed = parseRecord(stampEvidence(emitted, repo, tag, scannedAt));
157
+ if (!parsed.ok) {
158
+ rejected++;
159
+ out.rejected.push({ extractor: extractor.id, record: emitted, issues: parsed.issues });
160
+ continue;
161
+ }
162
+ const id = `${parsed.record.kind}/${parsed.record.id}`;
163
+ if (ids.has(id)) {
164
+ warnings.push({ message: `emitted ${id} more than once; kept the first` });
165
+ continue;
166
+ }
167
+ ids.add(id);
168
+ records.push(parsed.record);
169
+ }
170
+ for (const f of skippedNow())
171
+ warnings.push({
172
+ message: tooLargeMessage(f.bytes, repo.maxFileBytes),
173
+ path: f.path,
174
+ });
175
+ run.records = records.length;
176
+ run.rejected = rejected;
177
+ run.warnings = warnings.length;
178
+ for (const r of records)
179
+ collected.push({ r, x: extractor.id });
180
+ for (const w of warnings)
181
+ out.warnings.push({ extractor: extractor.id, ...w });
182
+ if (useCache)
183
+ await options.cache.put(key, { records, warnings, rejected });
184
+ }
185
+ }
186
+ catch (err) {
187
+ run.status = "failed";
188
+ run.error = err instanceof Error ? err.message : String(err);
189
+ // Drop anything this extractor produced before failing: partial output is misleading.
190
+ for (let i = collected.length - 1; i >= 0; i--)
191
+ if (collected[i].x === extractor.id)
192
+ collected.splice(i, 1);
193
+ for (let i = out.warnings.length - 1; i >= 0; i--)
194
+ if (out.warnings[i].extractor === extractor.id)
195
+ out.warnings.splice(i, 1);
196
+ for (let i = out.rejected.length - 1; i >= 0; i--)
197
+ if (out.rejected[i].extractor === extractor.id)
198
+ out.rejected.splice(i, 1);
199
+ run.rejected = 0;
200
+ run.warnings = 0;
201
+ run.records = 0;
202
+ }
203
+ run.durationMs = Date.now() - started;
204
+ out.runs.push(run);
205
+ }
206
+ out.records = collected.sort(compareRecords).map((c) => c.r);
207
+ return out;
208
+ }
209
+ //# sourceMappingURL=runner.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"runner.js","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,80 @@
1
+ import type { Extractor } from "./plugin.js";
2
+ /**
3
+ * The scanner plugin sandbox (ADR 0080, C4). An org-pack plugin is plain JavaScript the AI
4
+ * wrote and a person reviewed; it still runs as if it were hostile:
5
+ *
6
+ * - in its own worker thread, with a heap limit (`resourceLimits`) and a wall-clock limit
7
+ * after which the worker is terminated;
8
+ * - as an ES module compiled with `vm.SourceTextModule` in a fresh `vm` context: no `require`,
9
+ * no `process`, no `fetch`, no timers, no Node globals at all, and every import (static or
10
+ * dynamic) refused;
11
+ * - code generation from strings off (`eval`, `Function`), and the built-in prototypes frozen
12
+ * before the plugin's code runs;
13
+ * - files only through a message channel the host answers from the RepoHandle, for
14
+ * repo-relative paths only.
15
+ *
16
+ * Anything it tries that is forbidden stops the run, reported as a failed run with what it
17
+ * tried; the scan goes on. Node's `vm` is not a security boundary against a determined
18
+ * attacker (ADR 0080 says what is and isn't enforced); the review, the pin and the golden
19
+ * tests are the first line, this is the second.
20
+ */
21
+ /** What the sandbox needs from a plugin's manifest, and its entry file's source. */
22
+ export interface SandboxPlugin {
23
+ id: string;
24
+ version: string;
25
+ /** Record kinds it may emit; any other kind fails the run. */
26
+ emits: readonly string[];
27
+ limits: {
28
+ timeoutMs: number;
29
+ memoryMb: number;
30
+ };
31
+ /** The entry file's text: an ES module whose default export is an Extractor. */
32
+ source: string;
33
+ /** The entry file's name, for messages and stack traces. */
34
+ entry?: string;
35
+ }
36
+ /** Plugins' records carry this prefix on their extractor id, so they can't pose as a built-in. */
37
+ export declare const PLUGIN_EXTRACTOR_PREFIX = "plugin-";
38
+ /** The sha256 of an entry file, with line endings normalised so every checkout agrees. */
39
+ export declare function pluginEntryHash(text: string): string;
40
+ /** Read a plugin's entry file, refusing one that isn't pinned or changed after it was pinned. */
41
+ export declare function readPinnedEntry(dir: string, manifest: {
42
+ entry: string;
43
+ sha256?: string | undefined;
44
+ }): Promise<{
45
+ ok: true;
46
+ source: string;
47
+ } | {
48
+ ok: false;
49
+ message: string;
50
+ }>;
51
+ /** Why a plugin run stopped, for the scan's problems. */
52
+ export declare class PluginRunError extends Error {
53
+ readonly reason: "blocked" | "timeout" | "memory" | "failed" | "invalid";
54
+ constructor(message: string, reason: "blocked" | "timeout" | "memory" | "failed" | "invalid");
55
+ }
56
+ /** A model-provider plugin's code (ADR 0121 item 4), as the sandbox runs it. */
57
+ export interface TranslatorPlugin {
58
+ id: string;
59
+ version: string;
60
+ /** The entry file's text: an ES module whose default export has the functions called. */
61
+ source: string;
62
+ entry?: string;
63
+ limits: {
64
+ timeoutMs: number;
65
+ memoryMb: number;
66
+ };
67
+ }
68
+ /**
69
+ * Call one function of a translator plugin (ADR 0121 item 4) in a fresh sandbox, with data, and
70
+ * resolve with the data it returns. It has no files, no network and no clock: it only turns a
71
+ * prompt into a request and an answer into text. What it tries that is forbidden, a time or
72
+ * memory limit passed, or an entry file that says it is another plugin rejects with
73
+ * PluginRunError.
74
+ */
75
+ export declare function runTranslator(p: TranslatorPlugin, fn: string, arg: unknown): Promise<unknown>;
76
+ /**
77
+ * An org-pack plugin as an Extractor: each scan runs it in a fresh sandbox. Its id is
78
+ * `plugin-<id>`; the scan validates what it returns against C1 like any extractor's.
79
+ */
80
+ export declare function sandboxedExtractor(p: SandboxPlugin): Extractor;