@maycombhq/sdk 2.0.0-beta.1 → 2.0.0-beta.10

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 (98) hide show
  1. package/{dist → npm}/cache.d.ts +1 -1
  2. package/npm/core/api.d.ts +7462 -0
  3. package/npm/core/assistant-actor.d.ts +15 -0
  4. package/npm/core/audit.d.ts +153 -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/fact-paths.d.ts +14 -0
  12. package/npm/core/facts-callers.d.ts +152 -0
  13. package/npm/core/facts-carry.d.ts +36 -0
  14. package/npm/core/facts-join-prototype.d.ts +234 -0
  15. package/npm/core/facts-join-vendor.d.ts +110 -0
  16. package/npm/core/facts-join.d.ts +482 -0
  17. package/npm/core/facts.d.ts +94 -0
  18. package/npm/core/fs.d.ts +47 -0
  19. package/npm/core/gates-migrate.d.ts +10 -0
  20. package/npm/core/host-questions.d.ts +66 -0
  21. package/npm/core/identity.d.ts +17 -0
  22. package/npm/core/index.d.ts +73 -0
  23. package/npm/core/json-schema.d.ts +20 -0
  24. package/npm/core/judgments.d.ts +63 -0
  25. package/npm/core/light.d.ts +8 -0
  26. package/npm/core/link-evidence.d.ts +212 -0
  27. package/npm/core/log.d.ts +49 -0
  28. package/npm/core/manifest-edit.d.ts +57 -0
  29. package/npm/core/merge.d.ts +78 -0
  30. package/npm/core/metarepo.d.ts +91 -0
  31. package/npm/core/migrate.d.ts +31 -0
  32. package/npm/core/migration-files.d.ts +13 -0
  33. package/npm/core/orgpack-defaults.d.ts +199 -0
  34. package/npm/core/orgpack-load.d.ts +102 -0
  35. package/npm/core/question-order.d.ts +23 -0
  36. package/npm/core/question-owners.d.ts +53 -0
  37. package/npm/core/question-proposals.d.ts +77 -0
  38. package/npm/core/questions.d.ts +297 -0
  39. package/npm/core/record-cache.d.ts +52 -0
  40. package/npm/core/refs.d.ts +9 -0
  41. package/npm/core/repo-description.d.ts +44 -0
  42. package/npm/core/repo-reads.d.ts +44 -0
  43. package/npm/core/roles-migrate.d.ts +9 -0
  44. package/npm/core/runtime-migrate.d.ts +11 -0
  45. package/npm/core/schema/ai.d.ts +397 -0
  46. package/npm/core/schema/change.d.ts +244 -0
  47. package/npm/core/schema/common.d.ts +135 -0
  48. package/npm/core/schema/conventions.d.ts +75 -0
  49. package/npm/core/schema/dialect.d.ts +801 -0
  50. package/npm/core/schema/executors.d.ts +396 -0
  51. package/npm/core/schema/fact-corrections.d.ts +55 -0
  52. package/npm/core/schema/facts.d.ts +1491 -0
  53. package/npm/core/schema/frameworks.d.ts +371 -0
  54. package/npm/core/schema/judgment.d.ts +77 -0
  55. package/npm/core/schema/kinds.d.ts +5166 -0
  56. package/npm/core/schema/layout.d.ts +25 -0
  57. package/npm/core/schema/orgpack.d.ts +1185 -0
  58. package/npm/core/schema/plugin.d.ts +73 -0
  59. package/npm/core/schema/question.d.ts +195 -0
  60. package/npm/core/schema/repo-type.d.ts +109 -0
  61. package/npm/core/schema/review.d.ts +558 -0
  62. package/npm/core/schema/scan-settings.d.ts +34 -0
  63. package/npm/core/schema/scan-verify.d.ts +535 -0
  64. package/npm/core/schema/spec.d.ts +269 -0
  65. package/npm/core/schema/version.d.ts +9 -0
  66. package/npm/core/schema/workspace.d.ts +330 -0
  67. package/npm/core/serialize.d.ts +17 -0
  68. package/npm/core/shared-maps.d.ts +146 -0
  69. package/npm/core/sources-migrate.d.ts +15 -0
  70. package/npm/core/specs.d.ts +66 -0
  71. package/npm/core/stack-helpers.d.ts +32 -0
  72. package/npm/core/tar-read.d.ts +13 -0
  73. package/npm/core/template.d.ts +101 -0
  74. package/npm/core/words.d.ts +13 -0
  75. package/npm/core/zip-read.d.ts +37 -0
  76. package/npm/core/zip.d.ts +13 -0
  77. package/npm/index.js +9780 -0
  78. package/{dist → npm}/plugin.d.ts +1 -1
  79. package/{dist → npm}/runner.d.ts +1 -1
  80. package/package.json +10 -11
  81. package/dist/cache.js +0 -115
  82. package/dist/cache.js.map +0 -1
  83. package/dist/fs-repo.js +0 -120
  84. package/dist/fs-repo.js.map +0 -1
  85. package/dist/index.js +0 -7
  86. package/dist/index.js.map +0 -1
  87. package/dist/parse-cache.js +0 -275
  88. package/dist/parse-cache.js.map +0 -1
  89. package/dist/plugin.js +0 -85
  90. package/dist/plugin.js.map +0 -1
  91. package/dist/runner.js +0 -209
  92. package/dist/runner.js.map +0 -1
  93. package/dist/sandbox.js +0 -443
  94. package/dist/sandbox.js.map +0 -1
  95. /package/{dist → npm}/fs-repo.d.ts +0 -0
  96. /package/{dist → npm}/index.d.ts +0 -0
  97. /package/{dist → npm}/parse-cache.d.ts +0 -0
  98. /package/{dist → npm}/sandbox.d.ts +0 -0
@@ -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,15 @@
1
+ /**
2
+ * sources.yaml moved up a version, changing nothing but the number and keeping the file's
3
+ * comments and order. Version 2 (ADR 0127) adds a wiki's `include` and `exclude`, and a wiki with
4
+ * neither reads every page, as in version 1. Version 3 (ADR 0132) adds authority, scope and the
5
+ * export types, and a wiki with none of them ranks as a team's and applies everywhere: what every
6
+ * page was before. So each step is the number only. By default every older version goes to the
7
+ * current one; `from` and `to` take one step (`atticus upgrade`'s sources-v2 and sources-v3).
8
+ */
9
+ export declare function migrateSourcesText(text: string, o?: {
10
+ from?: number;
11
+ to?: number;
12
+ }): {
13
+ text: string;
14
+ changed: boolean;
15
+ };
@@ -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,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;
@@ -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;