@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,66 @@
1
+ import { type RecordOf } from "./catalog.js";
2
+ import { EstateJoins, SpecFindings, SpecHeader } from "./schema/spec.js";
3
+ /**
4
+ * A repo's spec as files (ADR 0079): specs/<repo>/spec.yaml (the header), one canonical YAML
5
+ * file per flow named by its id, and findings.yaml (the critic's last findings). In a repo
6
+ * adopted in place the folder is .atticus/specs/<repo>/.
7
+ */
8
+ export type FlowRecord = RecordOf<"Flow">;
9
+ export declare const SPEC_HEADER_FILE = "spec.yaml";
10
+ export declare const SPEC_FINDINGS_FILE = "findings.yaml";
11
+ export interface RepoSpec {
12
+ header?: SpecHeader;
13
+ flows: FlowRecord[];
14
+ /** Files in the folder that aren't valid, with why (relative to the root). */
15
+ problems: {
16
+ file: string;
17
+ message: string;
18
+ }[];
19
+ }
20
+ /**
21
+ * Read a repo's spec: header, flows (sorted by id) and the files that didn't read. `cacheRoot`
22
+ * is the metarepo this run is working in, and the only place the parses are kept (record-cache.ts);
23
+ * reading another team's estate leaves it out, and then nothing is written into it.
24
+ */
25
+ export declare function readRepoSpec(root: string, repo: string, o?: {
26
+ cacheRoot?: string;
27
+ }): Promise<RepoSpec>;
28
+ /**
29
+ * Every flow file in specs/, by flow id, from the file names alone — no file is read (ADR 0079:
30
+ * a flow lives at specs/<repo>/<id>.yaml, and a file holding another id is a problem
31
+ * `readRepoSpec` reports and leaves out). A command that needs a handful of flows out of
32
+ * hundreds reads those with `readFlow` instead of parsing every one.
33
+ */
34
+ export declare function specFlowFiles(root: string): Promise<Map<string, {
35
+ repo: string;
36
+ file: string;
37
+ }>>;
38
+ /**
39
+ * One flow of a repo's spec, or undefined when there is no such file, it isn't valid, or it
40
+ * holds another flow — exactly the flows `readRepoSpec` returns, one at a time.
41
+ */
42
+ export declare function readFlow(root: string, repo: string, id: string): Promise<FlowRecord | undefined>;
43
+ /** Write one flow at specs/<repo>/<id>.yaml in canonical YAML. */
44
+ export declare function writeFlow(root: string, repo: string, flow: FlowRecord): Promise<string>;
45
+ /** Remove a flow's file (a flow redrafted under another id, or dropped). */
46
+ export declare function removeFlow(root: string, repo: string, id: string): Promise<void>;
47
+ /** Write specs/<repo>/spec.yaml. */
48
+ export declare function writeSpecHeader(root: string, header: SpecHeader): Promise<void>;
49
+ /** The critic's last findings for a repo, or undefined before the first check. */
50
+ export declare function readSpecFindings(root: string, repo: string): Promise<SpecFindings | undefined>;
51
+ /** Write specs/<repo>/findings.yaml. */
52
+ export declare function writeSpecFindings(root: string, f: SpecFindings): Promise<void>;
53
+ /** The short hash a spec header keeps per cited file: sha-256, first 16 hex, of the text with LF endings. */
54
+ export declare function specFileHash(text: string): string;
55
+ /** The fingerprint of a critic finding: sha-256, first 12 hex, of rule, target and evidence. */
56
+ export declare function specFindingFingerprint(rule: string, target: string, evidence?: string): string;
57
+ /** The estate pass's joins (ADR 0085), beside the repo folders: specs/estate.yaml. */
58
+ export declare const ESTATE_FILE = "estate.yaml";
59
+ /** The repos that have a spec folder, sorted. */
60
+ export declare function specRepos(root: string): Promise<string[]>;
61
+ /** specs/estate.yaml, or undefined when the estate pass hasn't run (or the file doesn't read). */
62
+ export declare function readEstateJoins(root: string): Promise<EstateJoins | undefined>;
63
+ /** Write specs/estate.yaml in canonical YAML. Returns its path relative to the root. */
64
+ export declare function writeEstateJoins(root: string, joins: EstateJoins): Promise<string>;
65
+ /** Every repo-relative file a flow cites (trigger, steps, errors), sorted. */
66
+ export declare function flowFiles(flow: FlowRecord): string[];
@@ -0,0 +1,13 @@
1
+ import type { ZipArchive, ZipLimits } from "./zip-read.js";
2
+ /**
3
+ * A small reader for gzipped tar archives, for published npm packages (`npm pack` output, a
4
+ * registry .tgz), the way the ZIP reader serves JARs. Same defences: the uncompressed size is
5
+ * capped before anything is parsed (gunzip stops at the cap), entry counts and sizes are capped,
6
+ * names that climb out of the archive are refused, and nothing is extracted to disk. npm's
7
+ * `package/` folder is dropped from names. Regular files only; long names come from pax (`x`)
8
+ * and GNU (`L`) headers.
9
+ */
10
+ export declare class TarError extends Error {
11
+ name: string;
12
+ }
13
+ export declare function readTarGz(bytes: Uint8Array, limits?: Partial<ZipLimits>): ZipArchive;
@@ -0,0 +1,101 @@
1
+ /**
2
+ * Field templates used by dialect rules (C2) and checklist owner questions (C3).
3
+ *
4
+ * "${attr.path}" an attribute of the matched annotation or call
5
+ * "${annotation.ForgeService.name}" an attribute of an annotation on the enclosing class
6
+ * "${config:gateway.url}" a key from the repo's config files
7
+ * "${yaml:forge.yaml#service}" a key from a named file in the repo
8
+ * "${member.name}" "${class.name}" names of the matched member and its class
9
+ * "${file.path}" "${file.line}" where the match is
10
+ * "${repo.name}" the repo id
11
+ * "${match.1}" a regex group from the rule's match
12
+ * "${node.key}" "${node.up.url}" the structure around a jsonPath, xpath or hclBlock
13
+ * match: its key, a field of the object above (ADR 0058)
14
+ * "${lookup:servers(attr.name).host}" a value from a dialect lookup table, by key (ADR 0058)
15
+ * "${capture.path}" a capture of a syntax match's query (ADR 0060)
16
+ * "${item.name}" the node a collecting list item is at (ADR 0061)
17
+ * "${repo.component}" the component the matched file belongs to (ADR 0061)
18
+ * "${system}" "${field}" "${kind}" subject of a checklist need (questions only)
19
+ *
20
+ * Filters follow a pipe: "${attr.method | upper}", "${attr.path | normalizePath}",
21
+ * "${attr.name | default('unknown')}", "${attr.route_key | after(' ')}" (ADR 0063: the text after,
22
+ * or with before the text before, the first occurrence; empty when it isn't there). Anything
23
+ * outside ${...} is literal text.
24
+ */
25
+ export declare const TEMPLATE_FILTERS: readonly ["lower", "upper", "slug", "normalizePath", "trimSlash", "default", "parent", "basename", "map", "before", "after"];
26
+ export type TemplateFilter = (typeof TEMPLATE_FILTERS)[number];
27
+ export type TemplateSource = {
28
+ type: "attr";
29
+ name: string;
30
+ } | {
31
+ type: "annotation";
32
+ annotation: string;
33
+ name: string;
34
+ } | {
35
+ type: "config";
36
+ key: string;
37
+ } | {
38
+ type: "yaml";
39
+ file: string;
40
+ key: string;
41
+ } | {
42
+ type: "member" | "class" | "file" | "repo";
43
+ name: string;
44
+ } | {
45
+ type: "match";
46
+ group: number;
47
+ }
48
+ /** The node a collecting list item is at (ADR 0061): itself, or a dotted field of it. */
49
+ | {
50
+ type: "item";
51
+ name: string;
52
+ }
53
+ /** A capture of a `syntax` match's tree-sitter query (ADR 0060). */
54
+ | {
55
+ type: "capture";
56
+ name: string;
57
+ }
58
+ /** The matched node's key (name "key"), or a field of an object `up` levels above it. */
59
+ | {
60
+ type: "node";
61
+ up: number;
62
+ name: string;
63
+ }
64
+ /** A row of a dialect lookup table, by the value of `key`. */
65
+ | {
66
+ type: "lookup";
67
+ table: string;
68
+ key: TemplateExpr;
69
+ field: string;
70
+ } | {
71
+ type: "subject";
72
+ name: "system" | "field" | "kind" | "record";
73
+ };
74
+ export interface TemplateExpr {
75
+ source: TemplateSource;
76
+ filters: {
77
+ name: TemplateFilter;
78
+ arg?: string;
79
+ }[];
80
+ }
81
+ export type TemplatePart = {
82
+ text: string;
83
+ } | {
84
+ expr: TemplateExpr;
85
+ };
86
+ export declare class TemplateError extends Error {
87
+ readonly template: string;
88
+ constructor(message: string, template: string);
89
+ }
90
+ /** Parse a template into literal text and expressions. Throws TemplateError on bad syntax. */
91
+ export declare function parseTemplate(template: string): TemplatePart[];
92
+ /** Sources a template uses (a lookup's key's too), for checking which ones a rule may refer to. */
93
+ export declare function templateSources(template: string): TemplateSource[];
94
+ /** One expression's value with its filters applied, or undefined when unknown with no default. */
95
+ export declare function renderExpr(expr: TemplateExpr, resolve: (source: TemplateSource) => string | undefined): string | undefined;
96
+ /**
97
+ * Render a template. `resolve` returns a source's value or undefined when unknown.
98
+ * Returns undefined when any value is unknown and has no default, so a rule never emits
99
+ * a half-filled field.
100
+ */
101
+ export declare function renderTemplate(template: string, resolve: (source: TemplateSource) => string | undefined): string | undefined;
@@ -0,0 +1,13 @@
1
+ /**
2
+ * The words an identifier is made of (ADR 0116): camelCase, PascalCase, ACRONYMCase,
3
+ * snake_case, kebab-case, dots and slashes, lower case. `renamedAt` → renamed, at;
4
+ * `HTTPServer` → http, server; `v2Payments` → v2, payments. A path parameter (`{id}`) is
5
+ * dropped. Deterministic and small: it reads names, not prose.
6
+ */
7
+ export declare function identifierWords(s: string): string[];
8
+ /**
9
+ * The split forms of the identifiers in a text, for a search index: each word of the text
10
+ * that splits into more than one word (`renamedAt`, `daily_limit`) gives its words, once, in
11
+ * the order met. Words that don't split are left to the text itself.
12
+ */
13
+ export declare function splitForms(text: string, max?: number): string[];
@@ -0,0 +1,37 @@
1
+ /**
2
+ * A small ZIP reader for .vsdx, .docx, .pptx, .xlsx and .jar files (no ZIP library is available
3
+ * and none is needed). It reads the central directory, then stored or deflated entries on
4
+ * demand. Archives come from people's laptops and shared drives, so it is defensive: sizes are
5
+ * capped per entry and in total (a zip bomb stops at the cap, whatever the header claims),
6
+ * names that climb out of the archive are refused, and checksums are verified.
7
+ */
8
+ export declare class ZipError extends Error {
9
+ name: string;
10
+ }
11
+ export interface ZipLimits {
12
+ /** Most entries an archive may list. */
13
+ maxEntries: number;
14
+ /** Largest uncompressed entry, in bytes. */
15
+ maxEntryBytes: number;
16
+ /** Most uncompressed bytes read from one archive, all entries together. */
17
+ maxTotalBytes: number;
18
+ }
19
+ export declare const ZIP_LIMITS: ZipLimits;
20
+ export interface ZipArchive {
21
+ /** Entry names in central-directory order (folders left out). */
22
+ readonly names: string[];
23
+ has(name: string): boolean;
24
+ /** The entry's bytes, or undefined if there is no such entry. Throws ZipError if it is bad. */
25
+ read(name: string): Uint8Array | undefined;
26
+ /** The entry as UTF-8 text (a byte-order mark is dropped). */
27
+ text(name: string): string | undefined;
28
+ }
29
+ export declare function readZip(bytes: Uint8Array, limits?: Partial<ZipLimits>): ZipArchive;
30
+ /**
31
+ * Peek at the start of a ZIP for sniffing: the first entry's name and as much of its content
32
+ * as the head holds ([Content_Types].xml comes first in Office and Visio files). Never throws.
33
+ */
34
+ export declare function peekZip(head: Uint8Array): {
35
+ name: string;
36
+ content: string;
37
+ } | undefined;
@@ -0,0 +1,13 @@
1
+ /**
2
+ * A plain zip writer (deflate, UTF-8 names, Unix modes): for the support bundle and the offline
3
+ * install bundle. Every unzip tool reads it, Windows Explorer and Expand-Archive included.
4
+ * Not zip64: under 65,535 entries and 4 GB, which both bundles are far from.
5
+ */
6
+ export interface ZipEntry {
7
+ /** Forward slashes; a trailing slash makes a folder entry. */
8
+ name: string;
9
+ data: string | Uint8Array;
10
+ /** Unix mode bits, e.g. 0o755 for a script; default 0o644. */
11
+ mode?: number;
12
+ }
13
+ export declare function zip(entries: ZipEntry[], at?: Date): Buffer;
@@ -0,0 +1,34 @@
1
+ import { type RepoHandle } from "./plugin.js";
2
+ /** Folders never scanned: VCS data, dependencies and build output. */
3
+ export declare const DEFAULT_IGNORES: readonly [".git", "node_modules", "target", "build", "dist", "out", ".gradle", ".idea", ".vscode", "__pycache__", ".venv"];
4
+ export interface FsRepoOptions {
5
+ /** Folder names skipped anywhere in the tree. Defaults to DEFAULT_IGNORES. */
6
+ ignore?: readonly string[];
7
+ /**
8
+ * Files larger than this (minified bundles, data dumps) are left out of listings and readText
9
+ * refuses them; skippedFiles() says which were left out. Default 5 MB.
10
+ */
11
+ maxFileBytes?: number;
12
+ }
13
+ /** A RepoHandle over a folder, which can also say which files it left out for their size. */
14
+ export interface FsRepoHandle extends RepoHandle {
15
+ /** The size limit: files over it are left out of listings. */
16
+ readonly maxFileBytes: number;
17
+ /** Files a listing left out because they are over maxFileBytes, in path order. */
18
+ skippedFiles(): {
19
+ path: string;
20
+ bytes: number;
21
+ }[];
22
+ }
23
+ /** The warning for a file left out for its size: "left out: 5242881 bytes is over the 5 MB a file may be". */
24
+ export declare function tooLargeMessage(bytes: number, maxBytes: number): string;
25
+ export declare class RepoReadError extends Error {
26
+ readonly path: string;
27
+ constructor(message: string, path: string);
28
+ }
29
+ /**
30
+ * A read-only RepoHandle over a folder on disk (a base clone). Paths are repo-relative with
31
+ * forward slashes on every platform and listed in sorted order, so scans are deterministic.
32
+ * Symbolic links are never followed, and no path may leave the repo folder.
33
+ */
34
+ export declare function fsRepo(name: string, dir: string, commit: string, options?: FsRepoOptions): FsRepoHandle;
package/npm/index.d.ts ADDED
@@ -0,0 +1,6 @@
1
+ export * from "./plugin.js";
2
+ export * from "./fs-repo.js";
3
+ export * from "./cache.js";
4
+ export * from "./runner.js";
5
+ export * from "./parse-cache.js";
6
+ export * from "./sandbox.js";