@maycombhq/sdk 2.0.0-beta.3 → 2.0.0-beta.30

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 (88) hide show
  1. package/npm/core/ai-decisions.d.ts +373 -0
  2. package/npm/core/api.d.ts +15888 -3797
  3. package/npm/core/app-memory.d.ts +69 -0
  4. package/npm/core/assistant-actor.d.ts +28 -7
  5. package/npm/core/audit.d.ts +174 -0
  6. package/npm/core/canary.d.ts +369 -0
  7. package/npm/core/cancel.d.ts +20 -0
  8. package/npm/core/catalog.d.ts +220 -66
  9. package/npm/core/change-types-migrate.d.ts +14 -0
  10. package/npm/core/cite.d.ts +88 -6
  11. package/npm/core/contract-check.d.ts +276 -0
  12. package/npm/core/curated.d.ts +10 -0
  13. package/npm/core/decision-batches.d.ts +29 -0
  14. package/npm/core/declarable-routes.d.ts +52 -0
  15. package/npm/core/declared-links.d.ts +210 -0
  16. package/npm/core/eol.d.ts +5 -0
  17. package/npm/core/fact-paths.d.ts +14 -0
  18. package/npm/core/facts-callers.d.ts +23 -1
  19. package/npm/core/facts-carry.d.ts +8 -2
  20. package/npm/core/facts-deps.d.ts +85 -0
  21. package/npm/core/facts-join-prototype.d.ts +66 -4
  22. package/npm/core/facts-join-vendor.d.ts +67 -7
  23. package/npm/core/facts-join.d.ts +476 -2
  24. package/npm/core/facts-terms.d.ts +108 -0
  25. package/npm/core/facts.d.ts +155 -1
  26. package/npm/core/field-places.d.ts +109 -0
  27. package/npm/core/file-pool.d.ts +84 -0
  28. package/npm/core/fs.d.ts +205 -7
  29. package/npm/core/glob-plain.d.ts +34 -0
  30. package/npm/core/glob.d.ts +14 -0
  31. package/npm/core/hash-cache.d.ts +53 -0
  32. package/npm/core/host-questions.d.ts +273 -1
  33. package/npm/core/identity.d.ts +20 -8
  34. package/npm/core/index.d.ts +38 -0
  35. package/npm/core/initialisms.d.ts +62 -0
  36. package/npm/core/kept-files.d.ts +17 -0
  37. package/npm/core/light.d.ts +5 -0
  38. package/npm/core/link-candidates.d.ts +224 -0
  39. package/npm/core/link-evidence.d.ts +212 -0
  40. package/npm/core/log.d.ts +2 -0
  41. package/npm/core/manifest-edit.d.ts +83 -6
  42. package/npm/core/merge.d.ts +28 -0
  43. package/npm/core/metarepo.d.ts +26 -1
  44. package/npm/core/migrate.d.ts +3 -2
  45. package/npm/core/org-notes.d.ts +180 -0
  46. package/npm/core/orgpack-defaults.d.ts +30 -6
  47. package/npm/core/orgpack-load.d.ts +24 -0
  48. package/npm/core/paths.d.ts +23 -0
  49. package/npm/core/printer.d.ts +18 -0
  50. package/npm/core/process-trees.d.ts +109 -0
  51. package/npm/core/profile-migrate.d.ts +13 -0
  52. package/npm/core/question-order.d.ts +23 -0
  53. package/npm/core/question-owners.d.ts +57 -0
  54. package/npm/core/question-proposals.d.ts +77 -0
  55. package/npm/core/question-roles.d.ts +84 -0
  56. package/npm/core/questions.d.ts +123 -6
  57. package/npm/core/record-cache.d.ts +122 -2
  58. package/npm/core/repo-files.d.ts +66 -0
  59. package/npm/core/repo-reads.d.ts +44 -0
  60. package/npm/core/roles-migrate.d.ts +10 -0
  61. package/npm/core/run-log.d.ts +341 -0
  62. package/npm/core/runtime-migrate.d.ts +18 -0
  63. package/npm/core/schema/ai.d.ts +61 -13
  64. package/npm/core/schema/common.d.ts +32 -8
  65. package/npm/core/schema/component-type.d.ts +193 -0
  66. package/npm/core/schema/conventions.d.ts +80 -0
  67. package/npm/core/schema/dialect.d.ts +12 -12
  68. package/npm/core/schema/fact-corrections.d.ts +112 -2
  69. package/npm/core/schema/facts.d.ts +743 -23
  70. package/npm/core/schema/frameworks.d.ts +12 -12
  71. package/npm/core/schema/kinds.d.ts +230 -66
  72. package/npm/core/schema/orgpack.d.ts +248 -24
  73. package/npm/core/schema/question.d.ts +281 -5
  74. package/npm/core/schema/reading-rules.d.ts +51 -0
  75. package/npm/core/schema/repo-type.d.ts +20 -2
  76. package/npm/core/schema/review.d.ts +30 -9
  77. package/npm/core/schema/scan-verify.d.ts +77 -0
  78. package/npm/core/schema/version.d.ts +4 -1
  79. package/npm/core/schema/workspace.d.ts +29 -11
  80. package/npm/core/setup-edit.d.ts +107 -0
  81. package/npm/core/shared-maps.d.ts +146 -0
  82. package/npm/core/stack-helpers.d.ts +32 -0
  83. package/npm/core/version-order.d.ts +14 -0
  84. package/npm/fs-repo.d.ts +2 -1
  85. package/npm/index.js +14248 -6710
  86. package/npm/listing.d.ts +14 -0
  87. package/npm/sandbox.d.ts +2 -1
  88. package/package.json +1 -1
@@ -79,6 +79,17 @@ export declare const VerifyFix: z.ZodUnion<readonly [z.ZodObject<{
79
79
  "repo-type": "repo-type";
80
80
  }>>;
81
81
  repoType: z.ZodOptional<z.ZodString>;
82
+ role: z.ZodOptional<z.ZodEnum<{
83
+ product: "product";
84
+ architecture: "architecture";
85
+ delivery: "delivery";
86
+ analysis: "analysis";
87
+ }>>;
88
+ asks: z.ZodOptional<z.ZodEnum<{
89
+ business: "business";
90
+ delivery: "delivery";
91
+ design: "design";
92
+ }>>;
82
93
  sameAs: z.ZodOptional<z.ZodObject<{
83
94
  id: z.ZodString;
84
95
  verdict: z.ZodEnum<{
@@ -135,6 +146,17 @@ export declare const VerifyMissed: z.ZodObject<{
135
146
  "repo-type": "repo-type";
136
147
  }>>;
137
148
  repoType: z.ZodOptional<z.ZodString>;
149
+ role: z.ZodOptional<z.ZodEnum<{
150
+ product: "product";
151
+ architecture: "architecture";
152
+ delivery: "delivery";
153
+ analysis: "analysis";
154
+ }>>;
155
+ asks: z.ZodOptional<z.ZodEnum<{
156
+ business: "business";
157
+ delivery: "delivery";
158
+ design: "design";
159
+ }>>;
138
160
  sameAs: z.ZodOptional<z.ZodObject<{
139
161
  id: z.ZodString;
140
162
  verdict: z.ZodEnum<{
@@ -201,6 +223,17 @@ export declare const VerifyWrong: z.ZodObject<{
201
223
  "repo-type": "repo-type";
202
224
  }>>;
203
225
  repoType: z.ZodOptional<z.ZodString>;
226
+ role: z.ZodOptional<z.ZodEnum<{
227
+ product: "product";
228
+ architecture: "architecture";
229
+ delivery: "delivery";
230
+ analysis: "analysis";
231
+ }>>;
232
+ asks: z.ZodOptional<z.ZodEnum<{
233
+ business: "business";
234
+ delivery: "delivery";
235
+ design: "design";
236
+ }>>;
204
237
  sameAs: z.ZodOptional<z.ZodObject<{
205
238
  id: z.ZodString;
206
239
  verdict: z.ZodEnum<{
@@ -270,6 +303,17 @@ export declare const VerifyAnswer: z.ZodObject<{
270
303
  "repo-type": "repo-type";
271
304
  }>>;
272
305
  repoType: z.ZodOptional<z.ZodString>;
306
+ role: z.ZodOptional<z.ZodEnum<{
307
+ product: "product";
308
+ architecture: "architecture";
309
+ delivery: "delivery";
310
+ analysis: "analysis";
311
+ }>>;
312
+ asks: z.ZodOptional<z.ZodEnum<{
313
+ business: "business";
314
+ delivery: "delivery";
315
+ design: "design";
316
+ }>>;
273
317
  sameAs: z.ZodOptional<z.ZodObject<{
274
318
  id: z.ZodString;
275
319
  verdict: z.ZodEnum<{
@@ -334,6 +378,17 @@ export declare const VerifyAnswer: z.ZodObject<{
334
378
  "repo-type": "repo-type";
335
379
  }>>;
336
380
  repoType: z.ZodOptional<z.ZodString>;
381
+ role: z.ZodOptional<z.ZodEnum<{
382
+ product: "product";
383
+ architecture: "architecture";
384
+ delivery: "delivery";
385
+ analysis: "analysis";
386
+ }>>;
387
+ asks: z.ZodOptional<z.ZodEnum<{
388
+ business: "business";
389
+ delivery: "delivery";
390
+ design: "design";
391
+ }>>;
337
392
  sameAs: z.ZodOptional<z.ZodObject<{
338
393
  id: z.ZodString;
339
394
  verdict: z.ZodEnum<{
@@ -432,6 +487,17 @@ export declare const ScanVerifyProposal: z.ZodObject<{
432
487
  "repo-type": "repo-type";
433
488
  }>>;
434
489
  repoType: z.ZodOptional<z.ZodString>;
490
+ role: z.ZodOptional<z.ZodEnum<{
491
+ product: "product";
492
+ architecture: "architecture";
493
+ delivery: "delivery";
494
+ analysis: "analysis";
495
+ }>>;
496
+ asks: z.ZodOptional<z.ZodEnum<{
497
+ business: "business";
498
+ delivery: "delivery";
499
+ design: "design";
500
+ }>>;
435
501
  sameAs: z.ZodOptional<z.ZodObject<{
436
502
  id: z.ZodString;
437
503
  verdict: z.ZodEnum<{
@@ -496,6 +562,17 @@ export declare const ScanVerifyProposal: z.ZodObject<{
496
562
  "repo-type": "repo-type";
497
563
  }>>;
498
564
  repoType: z.ZodOptional<z.ZodString>;
565
+ role: z.ZodOptional<z.ZodEnum<{
566
+ product: "product";
567
+ architecture: "architecture";
568
+ delivery: "delivery";
569
+ analysis: "analysis";
570
+ }>>;
571
+ asks: z.ZodOptional<z.ZodEnum<{
572
+ business: "business";
573
+ delivery: "delivery";
574
+ design: "design";
575
+ }>>;
499
576
  sameAs: z.ZodOptional<z.ZodObject<{
500
577
  id: z.ZodString;
501
578
  verdict: z.ZodEnum<{
@@ -2,8 +2,11 @@
2
2
  * Current catalog schema version. Bumping it requires an ADR and a migration.
3
3
  * Version 2 (ADR 0031) added the Capability kind and changed no existing field.
4
4
  * Version 3 (ADR 0125) added `required` on a Schema field, optional, and changed no other field.
5
+ * Version 4 (ADR 0164) added `protobuf` to a Schema's `format`, and changed no other field.
6
+ * Version 5 (ADR 0181) added the evidence source `ai` and an evidence's `run` (a link the AI
7
+ * decided, flagged `joined-by-ai`), and changed no other field.
5
8
  *
6
9
  * It lives in its own file, with no schema beside it, so the command line can print it in its
7
10
  * help without loading zod (`@maycombhq/core/light`); `./common.js` exports it with C1.
8
11
  */
9
- export declare const SCHEMA_VERSION: 3;
12
+ export declare const SCHEMA_VERSION: 5;
@@ -12,16 +12,30 @@ import { z } from "zod";
12
12
  *
13
13
  * Version 2 (ADR 0128) added `description` on a repo, optional, and changed no other field.
14
14
  */
15
- export declare const WORKSPACE_SCHEMA_VERSION: 2;
15
+ export declare const WORKSPACE_SCHEMA_VERSION: 3;
16
16
  /** Every workspace-file schema version a reader accepts, oldest first. */
17
- export declare const SUPPORTED_WORKSPACE_SCHEMA_VERSIONS: readonly [1, 2];
17
+ export declare const SUPPORTED_WORKSPACE_SCHEMA_VERSIONS: readonly [1, 2, 3];
18
18
  /**
19
- * A workspace file's schema version. Version-1 files differ from version 2 only in this number
20
- * (nothing they hold changed meaning), so they are read as they are and come back as version 2
21
- * in memory; writers always write the current version, and `atticus upgrade` rewrites old files.
19
+ * A workspace file's schema version. Version-1 and version-2 files differ from version 3 only in
20
+ * this number (version 2 let a repo say what it is, version 3 its base path; nothing they hold
21
+ * changed meaning), so they are read as they are and come back as version 3 in memory; writers
22
+ * always write the current version, and `atticus upgrade` rewrites old files.
22
23
  */
23
- export declare const WorkspaceSchemaVersion: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>;
24
+ export declare const WorkspaceSchemaVersion: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
25
+ /**
26
+ * The path a repo's routes sit under on its hosts (ADR 0134): what a platform's ingress or a
27
+ * shared gateway host puts in front of them (`/forge/limits`, `/forge-onboarding/1.0`). Plain
28
+ * segments, a leading slash and no trailing one.
29
+ */
30
+ export declare const BasePath: z.ZodString;
24
31
  export declare const GitRef: z.ZodString;
32
+ /**
33
+ * A host a component answers on, as calls name it: "ledger-api.apps.bank.internal", or with *
34
+ * for one label or part of one, "pay-api-*.apps.bank.internal". Lower case. Without a port it
35
+ * takes calls on any port; with one ("localhost:9966", ADR 0088) only calls on that port, so
36
+ * two services on one host are told apart.
37
+ */
38
+ export declare const HostPattern: z.ZodString;
25
39
  /**
26
40
  * A URL's host (lower case) and port (the scheme's when it names none), or undefined for a
27
41
  * path with no host.
@@ -99,15 +113,17 @@ export declare const ManifestRepo: z.ZodObject<{
99
113
  build: z.ZodOptional<z.ZodString>;
100
114
  archived: z.ZodDefault<z.ZodBoolean>;
101
115
  hosts: z.ZodDefault<z.ZodArray<z.ZodString>>;
116
+ basePath: z.ZodOptional<z.ZodString>;
102
117
  modules: z.ZodDefault<z.ZodArray<z.ZodObject<{
103
118
  path: z.ZodString;
104
119
  component: z.ZodString;
105
120
  hosts: z.ZodDefault<z.ZodArray<z.ZodString>>;
121
+ basePath: z.ZodOptional<z.ZodString>;
106
122
  }, z.core.$strict>>>;
107
123
  }, z.core.$strict>;
108
124
  export type ManifestRepo = z.infer<typeof ManifestRepo>;
109
125
  export declare const RepoManifest: z.ZodObject<{
110
- schemaVersion: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>;
126
+ schemaVersion: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
111
127
  platform: z.ZodString;
112
128
  repos: z.ZodArray<z.ZodObject<{
113
129
  id: z.ZodString;
@@ -137,10 +153,12 @@ export declare const RepoManifest: z.ZodObject<{
137
153
  build: z.ZodOptional<z.ZodString>;
138
154
  archived: z.ZodDefault<z.ZodBoolean>;
139
155
  hosts: z.ZodDefault<z.ZodArray<z.ZodString>>;
156
+ basePath: z.ZodOptional<z.ZodString>;
140
157
  modules: z.ZodDefault<z.ZodArray<z.ZodObject<{
141
158
  path: z.ZodString;
142
159
  component: z.ZodString;
143
160
  hosts: z.ZodDefault<z.ZodArray<z.ZodString>>;
161
+ basePath: z.ZodOptional<z.ZodString>;
144
162
  }, z.core.$strict>>>;
145
163
  }, z.core.$strict>>;
146
164
  }, z.core.$strict>;
@@ -212,7 +230,7 @@ export declare const ChangeRepo: z.ZodObject<{
212
230
  }, z.core.$strict>;
213
231
  export type ChangeRepo = z.infer<typeof ChangeRepo>;
214
232
  export declare const ChangeRepos: z.ZodObject<{
215
- schemaVersion: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>;
233
+ schemaVersion: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
216
234
  change: z.ZodString;
217
235
  repos: z.ZodArray<z.ZodObject<{
218
236
  id: z.ZodString;
@@ -270,7 +288,7 @@ export declare const OutcomeMeasure: z.ZodObject<{
270
288
  }, z.core.$strict>;
271
289
  export type OutcomeMeasure = z.infer<typeof OutcomeMeasure>;
272
290
  export declare const ChangeOutcomes: z.ZodObject<{
273
- schemaVersion: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>;
291
+ schemaVersion: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
274
292
  change: z.ZodString;
275
293
  measures: z.ZodArray<z.ZodObject<{
276
294
  id: z.ZodString;
@@ -290,7 +308,7 @@ export type ChangeOutcomes = z.infer<typeof ChangeOutcomes>;
290
308
  * Home shows the setup checklist.
291
309
  */
292
310
  export declare const CatalogBaseline: z.ZodObject<{
293
- schemaVersion: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>;
311
+ schemaVersion: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
294
312
  acceptedBy: z.ZodString;
295
313
  acceptedAt: z.ZodISODateTime;
296
314
  kinds: z.ZodRecord<z.ZodString, z.ZodNumber>;
@@ -303,7 +321,7 @@ export type CatalogBaseline = z.infer<typeof CatalogBaseline>;
303
321
  * the migrations it has had. An older Atticus refuses to upgrade a metarepo a newer one wrote.
304
322
  */
305
323
  export declare const MetarepoStamp: z.ZodObject<{
306
- schemaVersion: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>;
324
+ schemaVersion: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
307
325
  atticus: z.ZodString;
308
326
  upgradedAt: z.ZodISODateTime;
309
327
  upgradedBy: z.ZodString;
@@ -0,0 +1,107 @@
1
+ import type { z } from "zod";
2
+ import { type LineChange } from "./manifest-edit.js";
3
+ /**
4
+ * ADR 0190: settings and setup are done in the app, "Edit, then Propose". Each edit writes one
5
+ * file of the org pack through its schema, keeping the file's comments, order and line endings,
6
+ * and shows the lines it changes before it writes (`preview`); Propose for review then opens the
7
+ * PR. Nothing here reaches a shared system, and no edit takes a secret: a setting whose name
8
+ * looks like one is refused by the runtime.yaml schema itself.
9
+ */
10
+ /** runtime.yaml's outside systems the app sets up, in the order the Adapters panel shows them. */
11
+ export declare const ADAPTER_KINDS: readonly ["gitHost", "workTracker", "serviceDesk", "notify", "wiki", "design"];
12
+ export type AdapterKind = (typeof ADAPTER_KINDS)[number];
13
+ /**
14
+ * The types runtime.yaml's schema takes for each, read from it so the two never drift (manual
15
+ * first: a person does the step and records the result, ADR 0032). `mock` is for tests and isn't
16
+ * offered; a file that has it shows it.
17
+ */
18
+ export declare const ADAPTER_TYPES: Record<AdapterKind, readonly string[]>;
19
+ /**
20
+ * The settings Atticus itself reads for each kind (the manual adapters and the steps that name a
21
+ * repo on the Git host), each a value or a list. A live adapter's plugin may read more: those
22
+ * are written as further settings, checked by the same schema (never a secret's value).
23
+ */
24
+ export declare const ADAPTER_FIELDS: Record<AdapterKind, readonly {
25
+ name: string;
26
+ list?: boolean;
27
+ }[]>;
28
+ export declare class SetupEditError extends Error {
29
+ readonly code: "invalid" | "not-found" | "exists";
30
+ constructor(code: "invalid" | "not-found" | "exists", message: string);
31
+ }
32
+ /** What an edit changed (or would change, with preview), file by file name. */
33
+ export interface FileEdit {
34
+ /** The file, relative to the metarepo ("/"-separated). */
35
+ path: string;
36
+ changes: LineChange[];
37
+ written: boolean;
38
+ }
39
+ /** An adapter as the app sends it: its type and settings, or null to take it out. */
40
+ export interface AdapterValue {
41
+ type: string;
42
+ settings?: Record<string, string | number | boolean | string[]>;
43
+ }
44
+ /** The flow style a file uses (`[a]` or `[ a ]`), so a write keeps it and changes only its lines. */
45
+ export declare const flowPaddingOf: (text: string) => boolean;
46
+ /**
47
+ * Set (or with null, take out) one outside system in runtime.yaml: `adapters.<kind>`, written as
48
+ * the type alone when it has no settings (`gitHost: manual`). The entry is edited in place: a
49
+ * setting sent as it is stays as it is (its comments, its style), one changed is that line, one
50
+ * left out is taken out. The whole file is checked with the Runtime schema first, so a type it
51
+ * doesn't take, or a setting named like a secret, is refused. With `baseSha256` (the file's
52
+ * sha256 as the form read it), a file changed since is refused (`exists`), never overwritten.
53
+ */
54
+ export declare function setRuntimeAdapter(root: string, kind: AdapterKind, value: AdapterValue | null, o?: {
55
+ preview?: boolean;
56
+ baseSha256?: string;
57
+ }): Promise<FileEdit>;
58
+ /**
59
+ * The schema an org-pack file is read with, by its path in the org pack; none for other files.
60
+ * Matched in any case: on a disk that doesn't tell case apart (Windows, macOS) `Runtime.yaml` is
61
+ * runtime.yaml, and is checked as it.
62
+ */
63
+ export declare function orgPackFileSchema(rel: string): z.ZodTypeAny | undefined;
64
+ /** A path in the org pack the raw editor may open: relative, inside it, a text file. */
65
+ export declare function orgPackFileRel(rel: string): string;
66
+ export declare const sha256Of: (text: string) => string;
67
+ /** An org-pack file as the raw editor shows it, with the schema it is checked with. */
68
+ export declare function readOrgPackFile(root: string, rel: string): Promise<{
69
+ path: string;
70
+ rel: string;
71
+ content: string;
72
+ sha256: string;
73
+ exists: boolean;
74
+ checked: boolean;
75
+ }>;
76
+ /** The problems Atticus would have reading this text as that org-pack file (empty when none). */
77
+ export declare function orgPackFileProblems(rel: string, content: string): string[];
78
+ /**
79
+ * The raw editor's write (the fallback for anything without a form): the file's whole text,
80
+ * checked with its schema, written onto the file as the person opened it (`baseSha256`, from
81
+ * readOrgPackFile; an edit meanwhile is refused), in the file's own line endings.
82
+ */
83
+ export declare function writeOrgPackFile(root: string, rel: string, content: string, o: {
84
+ baseSha256: string;
85
+ preview?: boolean;
86
+ }): Promise<FileEdit>;
87
+ /** An integration pattern as the app's form gives it (patterns/<code>.yaml). */
88
+ export interface PatternInput {
89
+ code: string;
90
+ name: string;
91
+ definition: string;
92
+ interaction: string;
93
+ route: string;
94
+ targetType: string;
95
+ controls?: string[];
96
+ source: string;
97
+ version?: string;
98
+ status?: string;
99
+ }
100
+ /**
101
+ * A new integration pattern from the form, as its own file `patterns/<code>.yaml` (the shape the
102
+ * starter pack's patterns have), checked with the pattern schema. A code already there is refused:
103
+ * an existing pattern is edited in the raw editor.
104
+ */
105
+ export declare function addPattern(root: string, p: PatternInput, o?: {
106
+ preview?: boolean;
107
+ }): Promise<FileEdit>;
@@ -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,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,14 @@
1
+ /**
2
+ * The order of two Atticus versions, and the shape of one. Kept here so the command line (the
3
+ * metarepo's stamp, `atticus status`) and the build (the Atticus a newer build.json names, ADR
4
+ * 0202 point 7) tell newer from older by the same rule.
5
+ */
6
+ /** The shape of an Atticus version: the only value that goes into a command a person copies. */
7
+ export declare const ATTICUS_VERSION_SHAPE: RegExp;
8
+ /** `v` when it has the shape of a version (trimmed), else undefined. */
9
+ export declare const atticusVersionOf: (v: string | undefined) => string | undefined;
10
+ /**
11
+ * Round 38: semver order with pre-releases (2.0.0-beta.30 > 2.0.0-beta.21 > 2.0.0-beta.9, and a
12
+ * release above its pre-releases), so an older beta refuses a metarepo a newer beta upgraded.
13
+ */
14
+ export declare function newerThan(a: string, b: string): boolean;
package/npm/fs-repo.d.ts CHANGED
@@ -29,6 +29,7 @@ export declare class RepoReadError extends Error {
29
29
  /**
30
30
  * A read-only RepoHandle over a folder on disk (a base clone). Paths are repo-relative with
31
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.
32
+ * Symbolic links are never followed, what the repo's .gitignore files ignore isn't listed, and
33
+ * no path may leave the repo folder.
33
34
  */
34
35
  export declare function fsRepo(name: string, dir: string, commit: string, options?: FsRepoOptions): FsRepoHandle;