@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.
@@ -0,0 +1,275 @@
1
+ import { createHash } from "node:crypto";
2
+ export const DEFAULT_PARSE_CACHE_LIMITS = {
3
+ maxChars: 8_000_000,
4
+ maxEntries: 20_000,
5
+ maxNativeChars: 1_000_000,
6
+ maxNativeEntries: 2_000,
7
+ maxTextChars: 16_000_000,
8
+ };
9
+ /** Throws for any change to a frozen Map or Set. */
10
+ function refuse() {
11
+ throw new TypeError("a parsed value is shared by every reader and can't be changed; copy it");
12
+ }
13
+ /**
14
+ * Freeze a value and everything it holds, so no reader can change it: objects, arrays and class
15
+ * instances (their own properties; prototypes are shared and left alone), and Maps and Sets
16
+ * (their set, delete, clear and add throw). Typed arrays can't be frozen and are left as they are;
17
+ * functions are not walked into.
18
+ */
19
+ export function deepFreeze(value) {
20
+ const stack = [value];
21
+ const seen = new Set();
22
+ while (stack.length > 0) {
23
+ const v = stack.pop();
24
+ if (v === null || typeof v !== "object" || seen.has(v))
25
+ continue;
26
+ seen.add(v);
27
+ if (ArrayBuffer.isView(v) || v instanceof ArrayBuffer)
28
+ continue;
29
+ if (v instanceof Map) {
30
+ for (const [k, x] of v)
31
+ stack.push(k, x);
32
+ for (const m of ["set", "delete", "clear"])
33
+ Object.defineProperty(v, m, { value: refuse });
34
+ }
35
+ else if (v instanceof Set) {
36
+ for (const x of v)
37
+ stack.push(x);
38
+ for (const m of ["add", "delete", "clear"])
39
+ Object.defineProperty(v, m, { value: refuse });
40
+ }
41
+ for (const k of Object.keys(v))
42
+ stack.push(v[k]);
43
+ Object.freeze(v);
44
+ }
45
+ return value;
46
+ }
47
+ const hash = (text) => createHash("sha1").update(text).digest("base64");
48
+ /** A parse cache for one repo scan. */
49
+ export function createParseCache(limits = {}) {
50
+ const l = { ...DEFAULT_PARSE_CACHE_LIMITS, ...limits };
51
+ const values = { map: new Map(), chars: 0, maxChars: l.maxChars, maxEntries: l.maxEntries };
52
+ const native = {
53
+ map: new Map(),
54
+ chars: 0,
55
+ maxChars: l.maxNativeChars,
56
+ maxEntries: l.maxNativeEntries,
57
+ };
58
+ const texts = new Map();
59
+ const reading = new Map();
60
+ let textChars = 0;
61
+ let disposed = false;
62
+ const st = { hits: 0, misses: 0, evictions: 0, textHits: 0, textReads: 0 };
63
+ const byKind = {};
64
+ const count = (kind, hit) => {
65
+ const k = (byKind[kind] ??= { hits: 0, misses: 0 });
66
+ if (hit) {
67
+ k.hits++;
68
+ st.hits++;
69
+ }
70
+ else {
71
+ k.misses++;
72
+ st.misses++;
73
+ }
74
+ };
75
+ const free = (e) => {
76
+ if (e.done && e.dispose)
77
+ e.dispose(e.value);
78
+ };
79
+ const remove = (e) => {
80
+ if (e.pool.map.get(e.key) !== e)
81
+ return;
82
+ e.pool.map.delete(e.key);
83
+ e.pool.chars -= e.weight;
84
+ e.gone = true;
85
+ if (e.pins === 0)
86
+ free(e);
87
+ };
88
+ /** Drop least recently used entries no reader holds until the pool is within its bound. */
89
+ const trim = (pool) => {
90
+ if (pool.chars <= pool.maxChars && pool.map.size <= pool.maxEntries)
91
+ return;
92
+ for (const e of [...pool.map.values()]) {
93
+ if (pool.chars <= pool.maxChars && pool.map.size <= pool.maxEntries)
94
+ break;
95
+ if (e.pins > 0 || !e.done)
96
+ continue;
97
+ remove(e);
98
+ st.evictions++;
99
+ }
100
+ };
101
+ const touch = (e) => {
102
+ // Map order is recency order: move to the end.
103
+ e.pool.map.delete(e.key);
104
+ e.pool.map.set(e.key, e);
105
+ };
106
+ /** The entry for this text, or a new one being parsed. */
107
+ const entry = (kind, path, text, o) => {
108
+ const pool = o.pool === "native" ? native : values;
109
+ const key = `${kind}\u0000${path}\u0000${text.length}\u0000${hash(text)}`;
110
+ const found = pool.map.get(key);
111
+ if (found && found.text === text) {
112
+ touch(found);
113
+ count(kind, true);
114
+ return { e: found, hit: true };
115
+ }
116
+ if (found)
117
+ remove(found);
118
+ count(kind, false);
119
+ const e = {
120
+ key,
121
+ text,
122
+ weight: o.weight ?? text.length,
123
+ pool,
124
+ done: false,
125
+ pins: 0,
126
+ gone: false,
127
+ ...(o.dispose ? { dispose: o.dispose } : {}),
128
+ };
129
+ if (!disposed && pool.maxChars > 0 && pool.maxEntries > 0 && e.weight <= pool.maxChars) {
130
+ pool.map.set(key, e);
131
+ pool.chars += e.weight;
132
+ }
133
+ else
134
+ e.gone = true;
135
+ return { e, hit: false };
136
+ };
137
+ const settle = (e, value, freeze) => {
138
+ e.value = freeze ? deepFreeze(value) : value;
139
+ e.done = true;
140
+ delete e.pending;
141
+ };
142
+ const fail = (e) => {
143
+ // A failed parse isn't kept: the next reader parses again and gets the same error.
144
+ if (e.pool.map.get(e.key) === e) {
145
+ e.pool.map.delete(e.key);
146
+ e.pool.chars -= e.weight;
147
+ }
148
+ e.gone = true;
149
+ };
150
+ /** The entry's value, waiting for a parse in flight. */
151
+ const valueOf = async (e, hit, parse, o) => {
152
+ if (hit)
153
+ return e.done ? e.value : await e.pending;
154
+ const p = (async () => parse(e.text))();
155
+ e.pending = p;
156
+ try {
157
+ const v = await p;
158
+ settle(e, v, o.freeze !== false);
159
+ return e.value;
160
+ }
161
+ catch (err) {
162
+ fail(e);
163
+ throw err;
164
+ }
165
+ };
166
+ return {
167
+ get(kind, path, text, parse, o = {}) {
168
+ const { e, hit } = entry(kind, path, text, o);
169
+ if (hit && e.done)
170
+ return e.value;
171
+ if (hit)
172
+ throw new Error(`${kind} of ${path} is being parsed asynchronously; use getAsync`);
173
+ let v;
174
+ try {
175
+ v = parse(text);
176
+ }
177
+ catch (err) {
178
+ fail(e);
179
+ throw err;
180
+ }
181
+ settle(e, v, o.freeze !== false);
182
+ trim(e.pool);
183
+ return e.value;
184
+ },
185
+ async getAsync(kind, path, text, parse, o = {}) {
186
+ const { e, hit } = entry(kind, path, text, o);
187
+ const v = await valueOf(e, hit, parse, o);
188
+ trim(e.pool);
189
+ return v;
190
+ },
191
+ async use(kind, path, text, parse, use, o = {}) {
192
+ const { e, hit } = entry(kind, path, text, o);
193
+ e.pins++;
194
+ try {
195
+ const v = await valueOf(e, hit, parse, o);
196
+ return await use(v);
197
+ }
198
+ finally {
199
+ e.pins--;
200
+ if (e.pins === 0 && e.gone)
201
+ free(e);
202
+ else
203
+ trim(e.pool);
204
+ }
205
+ },
206
+ async text(path, read) {
207
+ const t = texts.get(path);
208
+ if (t !== undefined) {
209
+ st.textHits++;
210
+ texts.delete(path);
211
+ texts.set(path, t);
212
+ return t;
213
+ }
214
+ // Readers asking for a file at once share one read.
215
+ const inFlight = reading.get(path);
216
+ if (inFlight) {
217
+ st.textHits++;
218
+ return inFlight;
219
+ }
220
+ st.textReads++;
221
+ const p = read();
222
+ reading.set(path, p);
223
+ let text;
224
+ try {
225
+ text = await p;
226
+ }
227
+ finally {
228
+ reading.delete(path);
229
+ }
230
+ if (disposed || l.maxTextChars <= 0 || text.length > l.maxTextChars)
231
+ return text;
232
+ texts.set(path, text);
233
+ textChars += text.length;
234
+ for (const [p, x] of texts) {
235
+ if (textChars <= l.maxTextChars)
236
+ break;
237
+ texts.delete(p);
238
+ textChars -= x.length;
239
+ }
240
+ return text;
241
+ },
242
+ stats() {
243
+ return {
244
+ ...st,
245
+ entries: values.map.size,
246
+ chars: values.chars,
247
+ nativeEntries: native.map.size,
248
+ nativeChars: native.chars,
249
+ texts: texts.size,
250
+ byKind: structuredClone(byKind),
251
+ };
252
+ },
253
+ dispose() {
254
+ disposed = true;
255
+ for (const pool of [values, native])
256
+ for (const e of [...pool.map.values()])
257
+ remove(e);
258
+ texts.clear();
259
+ textChars = 0;
260
+ },
261
+ };
262
+ }
263
+ /**
264
+ * The repo handle with a parse cache: readText reads each file once, and readers find the cache
265
+ * at `parseCache`. Everything else is the wrapped handle's (an fsRepo's skipped files too).
266
+ */
267
+ export function withParseCache(repo, cache) {
268
+ const wrapped = Object.create(repo);
269
+ Object.defineProperties(wrapped, {
270
+ parseCache: { value: cache, enumerable: true },
271
+ readText: { value: (path) => cache.text(path, () => repo.readText(path)) },
272
+ });
273
+ return wrapped;
274
+ }
275
+ //# sourceMappingURL=parse-cache.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"parse-cache.js","sourceRoot":"","sources":["../src/parse-cache.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,89 @@
1
+ import { type CatalogRecord, type FrameworkModel, type RecordIssue } from "@maycombhq/core";
2
+ import { type ParseCache } from "./parse-cache.js";
3
+ /**
4
+ * Contract C4 (v0): the plugin interfaces. Extractors read files and emit catalog records.
5
+ * They never call a network service or an AI model, so every scan is deterministic.
6
+ */
7
+ /** Read-only view of one repository at one commit. */
8
+ export interface RepoHandle {
9
+ /** Repo name from the repo manifest. */
10
+ readonly name: string;
11
+ /** Commit SHA being scanned. */
12
+ readonly commit: string;
13
+ /** Repo-relative paths matching the extractor's claims. */
14
+ listFiles(globs: readonly string[]): AsyncIterable<string>;
15
+ readText(path: string): Promise<string>;
16
+ /**
17
+ * What files parse to, shared by every reader of this repo scan (ADR 0067): optional, so
18
+ * handles without it still work and readers parse for themselves. Values are frozen.
19
+ */
20
+ readonly parseCache?: ParseCache;
21
+ }
22
+ export interface ScanContext {
23
+ /** Dialects that apply to this repo, by name. */
24
+ readonly dialects: readonly string[];
25
+ /** The component this repo builds (repos.manifest.yaml, else the repo id). */
26
+ readonly component?: string;
27
+ /** The catalog System the repo belongs to. */
28
+ readonly system?: string;
29
+ /** The repo type from the manifest, e.g. spring-boot, gateway. */
30
+ readonly repoType?: string;
31
+ /**
32
+ * The repo's modules that build their own component (ADR 0057): a fact in a file under
33
+ * `path` belongs to `component`; anything else to `component` above.
34
+ */
35
+ readonly modules?: readonly {
36
+ path: string;
37
+ component: string;
38
+ }[];
39
+ /** ISO timestamp of this scan, for evidence. */
40
+ readonly scannedAt: string;
41
+ /**
42
+ * Framework models that apply (ADR 0054): what house annotations, wrapper clients and
43
+ * constants mean. Extractors that don't read house frameworks ignore it.
44
+ */
45
+ readonly frameworks?: readonly FrameworkModel[];
46
+ /** Report a problem without failing the scan. */
47
+ warn(message: string, path?: string): void;
48
+ }
49
+ export interface Extractor {
50
+ /** Stable id, e.g. "spring". */
51
+ readonly id: string;
52
+ /** Semver; part of the scan cache key and of every record's evidence. */
53
+ readonly version: string;
54
+ /** File globs this extractor reads. */
55
+ readonly claims: readonly string[];
56
+ scan(repo: RepoHandle, ctx: ScanContext): AsyncIterable<CatalogRecord>;
57
+ }
58
+ export interface Ingestor {
59
+ readonly id: string;
60
+ readonly version: string;
61
+ /** Return a confidence 0..1 that this file is something the ingestor understands. */
62
+ sniff(fileName: string, head: Uint8Array): number;
63
+ ingest(fileName: string, content: Uint8Array, ctx: ScanContext): AsyncIterable<CatalogRecord>;
64
+ }
65
+ /** Identity helper so plugin files get type checking with no boilerplate. */
66
+ export declare function defineExtractor(extractor: Extractor): Extractor;
67
+ export interface CollectedScan {
68
+ records: CatalogRecord[];
69
+ rejected: {
70
+ record: unknown;
71
+ issues: RecordIssue[];
72
+ }[];
73
+ warnings: {
74
+ message: string;
75
+ path?: string;
76
+ }[];
77
+ }
78
+ /**
79
+ * Run one extractor over one repo and validate everything it emits against contract C1.
80
+ * Invalid records are collected, never written.
81
+ */
82
+ export declare function runExtractor(extractor: Extractor, repo: RepoHandle, options?: {
83
+ dialects?: string[];
84
+ scannedAt?: string;
85
+ }): Promise<CollectedScan>;
86
+ /** An in-memory repo, for plugin tests and the fixture ecosystem. */
87
+ export declare function memoryRepo(name: string, commit: string, files: Record<string, string>): RepoHandle;
88
+ /** Minimal glob support: "**" spans folders, "*" stays within one, "?" is one character. */
89
+ export declare function globToRegExp(glob: string): RegExp;
package/dist/plugin.js ADDED
@@ -0,0 +1,85 @@
1
+ import { parseRecord, } from "@maycombhq/core";
2
+ import { createParseCache, withParseCache } from "./parse-cache.js";
3
+ /** Identity helper so plugin files get type checking with no boilerplate. */
4
+ export function defineExtractor(extractor) {
5
+ if (!/^[a-z][a-z0-9-]*$/.test(extractor.id)) {
6
+ throw new Error(`extractor id "${extractor.id}" must be a lowercase slug`);
7
+ }
8
+ if (!/^\d+\.\d+\.\d+(-[0-9a-z.-]+)?$/i.test(extractor.version)) {
9
+ throw new Error(`extractor version "${extractor.version}" must be semver`);
10
+ }
11
+ if (extractor.claims.length === 0) {
12
+ throw new Error(`extractor "${extractor.id}" must claim at least one file glob`);
13
+ }
14
+ return extractor;
15
+ }
16
+ /**
17
+ * Run one extractor over one repo and validate everything it emits against contract C1.
18
+ * Invalid records are collected, never written.
19
+ */
20
+ export async function runExtractor(extractor, repo, options = {}) {
21
+ const out = { records: [], rejected: [], warnings: [] };
22
+ const ctx = {
23
+ dialects: options.dialects ?? [],
24
+ scannedAt: options.scannedAt ?? new Date().toISOString(),
25
+ warn: (message, path) => out.warnings.push(path ? { message, path } : { message }),
26
+ };
27
+ // A parse cache for this run when the caller didn't give one; freed when the run ends.
28
+ const own = repo.parseCache ? undefined : createParseCache();
29
+ const r = own ? withParseCache(repo, own) : repo;
30
+ try {
31
+ for await (const emitted of extractor.scan(r, ctx)) {
32
+ const result = parseRecord(emitted);
33
+ if (result.ok)
34
+ out.records.push(result.record);
35
+ else
36
+ out.rejected.push({ record: emitted, issues: result.issues });
37
+ }
38
+ }
39
+ finally {
40
+ own?.dispose();
41
+ }
42
+ return out;
43
+ }
44
+ /** An in-memory repo, for plugin tests and the fixture ecosystem. */
45
+ export function memoryRepo(name, commit, files) {
46
+ const paths = Object.keys(files).sort();
47
+ return {
48
+ name,
49
+ commit,
50
+ async *listFiles(globs) {
51
+ const matchers = globs.map(globToRegExp);
52
+ for (const p of paths)
53
+ if (matchers.some((m) => m.test(p)))
54
+ yield p;
55
+ },
56
+ async readText(path) {
57
+ const text = files[path];
58
+ if (text === undefined)
59
+ throw new Error(`no such file: ${path}`);
60
+ return text;
61
+ },
62
+ };
63
+ }
64
+ /** Minimal glob support: "**" spans folders, "*" stays within one, "?" is one character. */
65
+ export function globToRegExp(glob) {
66
+ let re = "";
67
+ for (let i = 0; i < glob.length; i++) {
68
+ const c = glob[i];
69
+ if (c === "*") {
70
+ if (glob[i + 1] === "*") {
71
+ const slash = glob[i + 2] === "/";
72
+ re += slash ? "(?:.*/)?" : ".*";
73
+ i += slash ? 2 : 1;
74
+ }
75
+ else
76
+ re += "[^/]*";
77
+ }
78
+ else if (c === "?")
79
+ re += "[^/]";
80
+ else
81
+ re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
82
+ }
83
+ return new RegExp(`^${re}$`);
84
+ }
85
+ //# sourceMappingURL=plugin.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,72 @@
1
+ import { type CatalogRecord, type FrameworkModel, type RecordIssue } from "@maycombhq/core";
2
+ import type { ScanCache } from "./cache.js";
3
+ import { type Extractor, type RepoHandle } from "./plugin.js";
4
+ export interface ScanRepoOptions {
5
+ repo: RepoHandle;
6
+ extractors: readonly Extractor[];
7
+ /** Dialect ids that apply to this repo (from repos.manifest.yaml). */
8
+ dialects?: readonly string[];
9
+ /** One timestamp for the whole scan, so every record of a run carries the same one. */
10
+ scannedAt?: string;
11
+ cache?: ScanCache;
12
+ /** The checkout has uncommitted changes: results are neither read from nor written to the cache. */
13
+ dirty?: boolean;
14
+ /** Hash of configuration that changes an extractor's output, e.g. its dialect rule files. */
15
+ configFor?: (extractor: Extractor) => string | undefined;
16
+ /** What the manifest says about the repo; passed to extractors and part of the cache key. */
17
+ repoInfo?: {
18
+ component?: string;
19
+ system?: string;
20
+ repoType?: string;
21
+ /** Modules that build their own component (ADR 0057). */
22
+ modules?: {
23
+ path: string;
24
+ component: string;
25
+ }[];
26
+ };
27
+ /** Framework models for every extractor's context (ADR 0054); part of the cache key. */
28
+ frameworks?: readonly FrameworkModel[];
29
+ }
30
+ export type RunStatus = "ran" | "cached" | "skipped" | "failed";
31
+ export interface ExtractorRun {
32
+ extractor: string;
33
+ version: string;
34
+ status: RunStatus;
35
+ records: number;
36
+ rejected: number;
37
+ warnings: number;
38
+ durationMs: number;
39
+ error?: string;
40
+ }
41
+ export interface RepoScan {
42
+ repo: string;
43
+ commit: string;
44
+ scannedAt: string;
45
+ /** Valid records from every extractor, sorted by kind, id, then extractor. */
46
+ records: CatalogRecord[];
47
+ runs: ExtractorRun[];
48
+ warnings: {
49
+ extractor: string;
50
+ message: string;
51
+ path?: string;
52
+ }[];
53
+ rejected: {
54
+ extractor: string;
55
+ record: unknown;
56
+ issues: RecordIssue[];
57
+ }[];
58
+ }
59
+ /**
60
+ * Fill in what the runner knows so extractors don't repeat it: the repo, commit, scan time
61
+ * and "id@version" of the extractor on every piece of evidence read from this repo.
62
+ * Values an extractor set itself are kept.
63
+ */
64
+ export declare function stampEvidence(record: unknown, repo: RepoHandle, extractor: string, scannedAt: string): unknown;
65
+ /**
66
+ * Scan one repo with every extractor. Each extractor runs in isolation: one that throws is
67
+ * reported as failed and the others still run. Every emitted record is stamped and
68
+ * validated against contract C1; invalid ones are reported, never returned. Results come
69
+ * from the cache when the commit, extractor version, dialects and configuration are
70
+ * unchanged. Output order is deterministic.
71
+ */
72
+ export declare function scanRepo(options: ScanRepoOptions): Promise<RepoScan>;