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

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.
Files changed (75) hide show
  1. package/LICENSE +177 -0
  2. package/npm/cache.d.ts +47 -0
  3. package/npm/core/api.d.ts +6098 -0
  4. package/npm/core/assistant-actor.d.ts +15 -0
  5. package/npm/core/branches.d.ts +21 -0
  6. package/npm/core/cancel.d.ts +9 -0
  7. package/npm/core/catalog.d.ts +4733 -0
  8. package/npm/core/change-types-migrate.d.ts +10 -0
  9. package/npm/core/cite.d.ts +54 -0
  10. package/npm/core/curated.d.ts +37 -0
  11. package/npm/core/facts-callers.d.ts +150 -0
  12. package/npm/core/facts-carry.d.ts +36 -0
  13. package/npm/core/facts-join-prototype.d.ts +177 -0
  14. package/npm/core/facts-join-vendor.d.ts +92 -0
  15. package/npm/core/facts-join.d.ts +256 -0
  16. package/npm/core/facts.d.ts +94 -0
  17. package/npm/core/fs.d.ts +47 -0
  18. package/npm/core/gates-migrate.d.ts +10 -0
  19. package/npm/core/host-questions.d.ts +24 -0
  20. package/npm/core/identity.d.ts +17 -0
  21. package/npm/core/index.d.ts +62 -0
  22. package/npm/core/json-schema.d.ts +20 -0
  23. package/npm/core/judgments.d.ts +63 -0
  24. package/npm/core/light.d.ts +8 -0
  25. package/npm/core/log.d.ts +49 -0
  26. package/npm/core/manifest-edit.d.ts +48 -0
  27. package/npm/core/merge.d.ts +78 -0
  28. package/npm/core/metarepo.d.ts +83 -0
  29. package/npm/core/migrate.d.ts +31 -0
  30. package/npm/core/migration-files.d.ts +13 -0
  31. package/npm/core/orgpack-defaults.d.ts +194 -0
  32. package/npm/core/orgpack-load.d.ts +86 -0
  33. package/npm/core/questions.d.ts +267 -0
  34. package/npm/core/record-cache.d.ts +52 -0
  35. package/npm/core/refs.d.ts +9 -0
  36. package/npm/core/repo-description.d.ts +44 -0
  37. package/npm/core/runtime-migrate.d.ts +11 -0
  38. package/npm/core/schema/ai.d.ts +397 -0
  39. package/npm/core/schema/change.d.ts +244 -0
  40. package/npm/core/schema/common.d.ts +135 -0
  41. package/npm/core/schema/dialect.d.ts +801 -0
  42. package/npm/core/schema/executors.d.ts +396 -0
  43. package/npm/core/schema/fact-corrections.d.ts +55 -0
  44. package/npm/core/schema/facts.d.ts +1476 -0
  45. package/npm/core/schema/frameworks.d.ts +371 -0
  46. package/npm/core/schema/judgment.d.ts +77 -0
  47. package/npm/core/schema/kinds.d.ts +5166 -0
  48. package/npm/core/schema/layout.d.ts +25 -0
  49. package/npm/core/schema/orgpack.d.ts +1167 -0
  50. package/npm/core/schema/plugin.d.ts +73 -0
  51. package/npm/core/schema/question.d.ts +152 -0
  52. package/npm/core/schema/repo-type.d.ts +109 -0
  53. package/npm/core/schema/review.d.ts +558 -0
  54. package/npm/core/schema/scan-settings.d.ts +34 -0
  55. package/npm/core/schema/scan-verify.d.ts +535 -0
  56. package/npm/core/schema/spec.d.ts +269 -0
  57. package/npm/core/schema/version.d.ts +9 -0
  58. package/npm/core/schema/workspace.d.ts +312 -0
  59. package/npm/core/serialize.d.ts +17 -0
  60. package/npm/core/sources-migrate.d.ts +15 -0
  61. package/npm/core/specs.d.ts +66 -0
  62. package/npm/core/tar-read.d.ts +13 -0
  63. package/npm/core/template.d.ts +101 -0
  64. package/npm/core/words.d.ts +13 -0
  65. package/npm/core/zip-read.d.ts +37 -0
  66. package/npm/core/zip.d.ts +13 -0
  67. package/npm/fs-repo.d.ts +34 -0
  68. package/npm/index.d.ts +6 -0
  69. package/npm/index.js +8892 -0
  70. package/npm/parse-cache.d.ts +97 -0
  71. package/npm/plugin.d.ts +89 -0
  72. package/npm/runner.d.ts +72 -0
  73. package/npm/sandbox.d.ts +80 -0
  74. package/package.json +28 -3
  75. package/README.md +0 -3
@@ -0,0 +1,97 @@
1
+ import type { RepoHandle } from "./plugin.js";
2
+ /**
3
+ * The parse cache (ADR 0067): what a file parses to, made once per repo scan and shared by every
4
+ * reader of that scan, built-in extractors, dialects and plugins alike. An entry is keyed by the
5
+ * reader's kind (what was made: "yaml", "java", "tree:java"), the file's path and its content, so a
6
+ * changed file or a different string under the same path (a rendered template) parses again.
7
+ *
8
+ * Values are deep-frozen before anyone sees them: a reader that changes what it was given fails
9
+ * at once instead of changing what the next reader reads. Readers that need to change a value
10
+ * copy it first. Memory is bounded twice over: plain values, and native values (tree-sitter
11
+ * trees, which live in the WebAssembly heap and must be freed), each under their own size
12
+ * bound, least recently used first out. A native value is freed when it leaves the cache, never
13
+ * while a reader holds it, and everything is freed when the scan ends.
14
+ */
15
+ export interface ParseCache {
16
+ /** What `parse` makes of this text, parsed once; frozen unless `freeze: false`. */
17
+ get<T>(kind: string, path: string, text: string, parse: (text: string) => T, o?: GetOptions): T;
18
+ /** The same for a parser that is asynchronous; readers asking at once share one parse. */
19
+ getAsync<T>(kind: string, path: string, text: string, parse: (text: string) => Promise<T> | T, o?: GetOptions): Promise<T>;
20
+ /**
21
+ * Hand the value to `use` and keep it alive until `use` is done, for values that are freed
22
+ * (`dispose`): a syntax tree is never freed under a reader walking it. After the scan has
23
+ * ended, the value is made, used and freed at once.
24
+ */
25
+ use<T, R>(kind: string, path: string, text: string, parse: (text: string) => Promise<T> | T, use: (value: T) => R | Promise<R>, o?: UseOptions<T>): Promise<R>;
26
+ /** A file's text, read once (`withParseCache` reads through this). */
27
+ text(path: string, read: () => Promise<string>): Promise<string>;
28
+ stats(): ParseCacheStats;
29
+ /** Free every value and keep nothing more: the end of the repo scan. Safe to call twice. */
30
+ dispose(): void;
31
+ }
32
+ export interface GetOptions {
33
+ /** Deep-freeze the value (default). Only values holding native handles pass false. */
34
+ freeze?: boolean;
35
+ /** "native" for values outside the JavaScript heap (syntax trees): a separate, smaller bound. */
36
+ pool?: "values" | "native";
37
+ /** What the value counts against its bound; the text's length when not given. */
38
+ weight?: number;
39
+ }
40
+ export interface UseOptions<T> extends GetOptions {
41
+ /** Free the value when it leaves the cache: `tree.delete()` for a syntax tree. */
42
+ dispose?: (value: T) => void;
43
+ }
44
+ /**
45
+ * The bounds, in characters of the source each value was parsed from. Measured: a parsed value
46
+ * holds 10 (a JavaFile, an HCL file, flattened YAML) to 37 (YAML documents, a SourceFile) bytes of
47
+ * JavaScript heap per source character, and a syntax tree up to 36 bytes of WebAssembly heap,
48
+ * which never shrinks once grown. The defaults keep one repo scan's cache to about 300 MB of heap
49
+ * and 36 MB of WebAssembly memory at worst, for a 7 GB laptop.
50
+ */
51
+ export interface ParseCacheLimits {
52
+ /** Plain values: the total length of the texts they were parsed from. Default 8M characters. */
53
+ maxChars?: number;
54
+ /** Plain values: how many. Default 20,000. */
55
+ maxEntries?: number;
56
+ /** Native values (syntax trees): total text length. Default 1M characters. */
57
+ maxNativeChars?: number;
58
+ /** Native values: how many. Default 2,000. */
59
+ maxNativeEntries?: number;
60
+ /** File texts kept by `text()`. Default 16M characters. */
61
+ maxTextChars?: number;
62
+ }
63
+ export interface ParseCacheStats {
64
+ hits: number;
65
+ misses: number;
66
+ evictions: number;
67
+ /** Plain values held now, and the length of the texts they came from. */
68
+ entries: number;
69
+ chars: number;
70
+ /** Native values held now, and their texts' length. */
71
+ nativeEntries: number;
72
+ nativeChars: number;
73
+ /** File texts held now; reads served from the cache and from the repo. */
74
+ texts: number;
75
+ textHits: number;
76
+ textReads: number;
77
+ /** Misses and hits by kind, for measuring which readers share. */
78
+ byKind: Record<string, {
79
+ hits: number;
80
+ misses: number;
81
+ }>;
82
+ }
83
+ export declare const DEFAULT_PARSE_CACHE_LIMITS: Required<ParseCacheLimits>;
84
+ /**
85
+ * Freeze a value and everything it holds, so no reader can change it: objects, arrays and class
86
+ * instances (their own properties; prototypes are shared and left alone), and Maps and Sets
87
+ * (their set, delete, clear and add throw). Typed arrays can't be frozen and are left as they are;
88
+ * functions are not walked into.
89
+ */
90
+ export declare function deepFreeze<T>(value: T): T;
91
+ /** A parse cache for one repo scan. */
92
+ export declare function createParseCache(limits?: ParseCacheLimits): ParseCache;
93
+ /**
94
+ * The repo handle with a parse cache: readText reads each file once, and readers find the cache
95
+ * at `parseCache`. Everything else is the wrapped handle's (an fsRepo's skipped files too).
96
+ */
97
+ export declare function withParseCache<R extends RepoHandle>(repo: R, cache: ParseCache): R;
@@ -0,0 +1,89 @@
1
+ import { type CatalogRecord, type FrameworkModel, type RecordIssue } from "./core/index.js";
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;
@@ -0,0 +1,72 @@
1
+ import { type CatalogRecord, type FrameworkModel, type RecordIssue } from "./core/index.js";
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>;
@@ -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;
package/package.json CHANGED
@@ -1,6 +1,31 @@
1
1
  {
2
2
  "name": "@maycombhq/sdk",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "2.0.0-beta.2",
4
+ "description": "Atticus plugin SDK (contract C4): interfaces for extractors, dialects, ingestors and adapters.",
5
+ "license": "Apache-2.0",
6
+ "type": "module",
7
+ "main": "./npm/index.js",
8
+ "types": "./npm/index.d.ts",
9
+ "exports": {
10
+ ".": {
11
+ "types": "./npm/index.d.ts",
12
+ "import": "./npm/index.js"
13
+ }
14
+ },
15
+ "files": [
16
+ "npm"
17
+ ],
18
+ "dependencies": {
19
+ "yaml": "^2.9.1",
20
+ "zod": "^4.6.0"
21
+ },
22
+ "atticusBundled": true,
23
+ "publishConfig": {
24
+ "access": "public"
25
+ },
26
+ "scripts": {
27
+ "build": "tsc -p tsconfig.build.json && node ../../scripts/bundle/npm-sdk.mjs",
28
+ "typecheck": "tsc -p tsconfig.json --noEmit",
29
+ "test": "vitest run --config ../../vitest.shared.mjs --fsModuleCachePath=node_modules/.vitest-cache --testTimeout=30000 --hookTimeout=60000"
30
+ }
6
31
  }
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.