@maycombhq/sdk 2.0.0-beta.23 → 2.0.0-beta.24

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.
@@ -42,6 +42,12 @@ export declare function quoteNotRequired(path: string, line: string): boolean;
42
42
  * 46): a stream's name after `:` (`.env::$DATA` is `.env`) and trailing dots and spaces dropped.
43
43
  */
44
44
  export declare function isSecretPath(path: string): boolean;
45
+ /**
46
+ * Whether a text holds a secret by its shape alone, whatever names it (beta.24 review): a URL's
47
+ * password (`jdbc:postgresql://user:pass@host`), a bearer token or one of the well-known token
48
+ * shapes `redactSecrets` takes out. A reference (`${X}`, `env:X`) in the password's place is none.
49
+ */
50
+ export declare function hasSecretShape(text: string): boolean;
45
51
  /**
46
52
  * Redact the secrets on a line, keeping what names them: a value after a secret-looking key
47
53
  * (at the line's start, whatever the value; anywhere on it, a quoted literal), a setter's
@@ -63,8 +69,9 @@ export declare function quoteHoldsSecret(quote: string): boolean;
63
69
  * Whether a word claim is put together from `cite.with` parts (ADR 0124 addendum A-derived): a
64
70
  * rake task's `namespace:task`, a key a helper prefixes (`${prefix}_conferenceCache`). Each part's
65
71
  * value must be in the claim as a whole piece (bounded by the claim's start or end, a separator
66
- * `: . _ - / #`, or another part), and whatever is left between the parts, separators aside, must
67
- * be written on the cited lines. The parts' own lines are checked by the caller.
72
+ * `: . _ / #`, or another part; `-` joins a word), and whatever is left between the parts,
73
+ * separators aside, must be written on the cited lines: at least one piece, so the cited lines
74
+ * name some of the word. The parts' own lines are checked by the caller.
68
75
  */
69
76
  export declare function partsBuildWord(claim: string, parts: readonly string[], lines: readonly string[]): boolean;
70
77
  export declare function partsNamePath(lines: readonly string[], path: string): boolean;
@@ -0,0 +1,55 @@
1
+ import type { FactEnd, JoinRepo } from "./facts-join.js";
2
+ import type { DependencyScope } from "./schema/facts.js";
3
+ /**
4
+ * The estate's build dependencies (ADR 0192): a component's `dependency` fact that names the
5
+ * coordinates (group and name) another component's `artifact` fact publishes is a "depends on"
6
+ * link from the one to the other, with a cited line at both ends: the dependency's in the
7
+ * depending build file, the published coordinates' in the library's. Matching is by those
8
+ * coordinates alone, letter case aside: no group prefix, naming convention or repo type says
9
+ * what is the organisation's own; what some repo of the estate publishes is.
10
+ *
11
+ * - A dependency on coordinates nobody in the estate publishes (a vendor SDK, an open-source
12
+ * library) draws nothing and asks nothing: it is counted in `outside`.
13
+ * - A test-scoped dependency draws nothing (`test`): it builds the tests, not the component.
14
+ * - Coordinates two components publish draw nothing either: they are `ambiguous`, for a person.
15
+ * - A component's dependency on its own coordinates draws nothing.
16
+ *
17
+ * The library's own calls are the library's: nothing here touches a call, and nothing of the
18
+ * library is given to the components that depend on it. Pure: the same facts give the same
19
+ * links, whatever order the repos come in.
20
+ */
21
+ /** One end of a "depends on" link: its fact, and every line the claim rests on (`file:line`). */
22
+ export interface DependencyEnd extends FactEnd {
23
+ lines: string[];
24
+ }
25
+ export interface DependencyLink {
26
+ /** The dependency fact, in the component that builds on the library. */
27
+ from: DependencyEnd;
28
+ /** The artifact fact, in the library's component, that publishes the coordinates. */
29
+ to: DependencyEnd;
30
+ group: string;
31
+ name: string;
32
+ /** The dependency's declared scope, when it says one other than compile. */
33
+ scope?: DependencyScope;
34
+ /** The version the dependency declares, when it says one. */
35
+ version?: string;
36
+ }
37
+ /** Coordinates two or more components of the estate publish: nothing is drawn to either. */
38
+ export interface AmbiguousCoordinates {
39
+ group: string;
40
+ name: string;
41
+ by: FactEnd[];
42
+ }
43
+ export interface DependencyJoinResult {
44
+ links: DependencyLink[];
45
+ ambiguous: AmbiguousCoordinates[];
46
+ /** Dependencies on coordinates nobody in the estate publishes: drawn as nothing. */
47
+ outside: number;
48
+ /** Test-scoped dependencies on the estate's own coordinates: drawn as nothing. */
49
+ test: number;
50
+ }
51
+ export declare function joinDependencies(input: {
52
+ repos: readonly JoinRepo[];
53
+ }): DependencyJoinResult;
54
+ /** The id a "depends on" link is known by, for a view's join: stable across reads of one pom. */
55
+ export declare const dependencyLinkId: (l: Pick<DependencyLink, "from" | "to">) => string;
@@ -207,6 +207,12 @@ export declare const JOINED_BY_ANSWER = "joined-by-answer";
207
207
  export declare const JOINED_BY_NAME = "joined-by-name";
208
208
  export declare const JOINED_BY_REPO = "joined-by-repo";
209
209
  export declare const JOINED_BY_HOST = "joined-by-host";
210
+ /**
211
+ * A call whose host nothing resolves, joined to a gateway proxy's flow by its whole path: the one
212
+ * proxy whose cited `<BasePath>` starts it, the one flow of its method under it. Code at both
213
+ * ends: a how, never a guess.
214
+ */
215
+ export declare const JOINED_BY_BASE_PATH = "joined-by-base-path";
210
216
  /**
211
217
  * J0, J1: the guesses a join by host can rest on, though the host itself was cited. The setting
212
218
  * that gave the host is a platform-wide one nobody aimed at the caller (`setsForAll`), or one that
@@ -263,7 +269,7 @@ export declare const JOINED_TO_SHARED_MAP = "joined-to-shared-map";
263
269
  * or the component's own name as the host), `path` (no target named: the only entry of the
264
270
  * estate that serves it), `topic` (a listener of the published topic).
265
271
  */
266
- export type JoinHow = "answer" | "named" | "repo" | "host" | "path" | "topic";
272
+ export type JoinHow = "answer" | "named" | "repo" | "host" | "base-path" | "path" | "topic";
267
273
  export interface FactJoin {
268
274
  call: FactEnd;
269
275
  entry: FactEnd;
@@ -545,8 +551,22 @@ export declare function routeScore(called: string, served: string): number;
545
551
  export declare function nameScore(called: string, served: string): number;
546
552
  /** The question for a call no single repo answers: the same words as the facts-targets question. */
547
553
  export declare function callTargetQuestion(f: Call, component: string): string;
554
+ /**
555
+ * The question for a gateway's forwarding call whose host nothing resolves. A host still written
556
+ * as a token (`@targetUrl@`, `{{host}}`, `${HOST}`) is most often one a deploy tool's file sets
557
+ * per environment (the Apigee config plugin's `config.json`), which a read before beta.24 didn't
558
+ * record: the next step it says is to read the gateway repo again, never a guess at a repo.
559
+ */
560
+ export declare function forwardHostQuestion(host: string, repo: string): string;
548
561
  /** The question for a call whose gateway routes lead back where they came from (A-gateway2). */
549
562
  export declare function gatewayCycleQuestion(f: Call, component: string, gateway: string): string;
563
+ /**
564
+ * A host's registrable domain (`northwind.example` for `api.northwind.example`,
565
+ * `northwind.co.uk` for `api.northwind.co.uk`), or undefined for a name the outside rule can't
566
+ * place: one label, `localhost`, an address, a private or in-cluster name (`.corp`, `.svc`), a
567
+ * Service and its namespace (`wallets.payments`). A wildcard and a port are left off.
568
+ */
569
+ export declare function registrableDomain(host: string): string | undefined;
550
570
  /**
551
571
  * The host a call goes to as the join reads it (P1): the call's own host, else the host of the
552
572
  * config fact its `base` names (the first by id), else the base itself; `host:port` when the text
@@ -554,12 +574,6 @@ export declare function gatewayCycleQuestion(f: Call, component: string, gateway
554
574
  * no key that reads as a host). The measure uses it to tell which outside system took a call.
555
575
  */
556
576
  export declare function callHostOf(f: Call, repoFacts: readonly Fact[]): string | undefined;
557
- /**
558
- * J0: a config placeholder: `${X}` or Spring's `${X:default}` anywhere in a value (a URL may be
559
- * written around it, `https://${HOST}/v2`), `env:X` as the whole value, or a build or deploy
560
- * token `@X@` (Maven filtering, a gateway bundle's token replace from CI properties). With two in one value
561
- * (`${SCHEME}://${HOST}/v1`) this is the first, the rest left in `after`.
562
- */
563
577
  export declare function placeholderIn(s: string | undefined): {
564
578
  name: string;
565
579
  fallback?: string;
@@ -36,6 +36,75 @@ export declare function topicOfQuestion(q: {
36
36
  export declare const PICKER_LABELS: ReadonlySet<string>;
37
37
  /** The last option of a hosts question: no repo of the estate answers on it. */
38
38
  export declare const HOSTS_NONE = "None of these";
39
+ /**
40
+ * The step `atticus estate join` asks which component a spec step's call-out reaches by (named
41
+ * here so the answer's rules below are checked where it is written; the CLI raises it).
42
+ */
43
+ export declare const ESTATE_TARGETS_STEP_ID = "estate-targets";
44
+ /**
45
+ * Beta.24 review (answers made into boxes): the questions about where calls go, whose answer the
46
+ * join reads: hosts, targets (an ambiguous call or an unknown host's), topics and the estate's
47
+ * call-outs. Each takes Ignore, and none takes words that name nothing as a system.
48
+ */
49
+ export declare const JOIN_STEPS: ReadonlySet<string>;
50
+ /**
51
+ * The option every join question has (beta.24 review): the calls it asks about aren't real calls
52
+ * (CI/CD, a test, a template), so the join leaves them, the same as "None of these", and never
53
+ * draws a box for them. Its words with a reason are `Ignore: <reason>`.
54
+ */
55
+ export declare const JOIN_IGNORE_LABEL = "Ignore: not a real call (e.g. CI/CD, a test, a template)";
56
+ /** How an Ignore answer with a reason starts (the person's words follow it). */
57
+ export declare const IGNORE_PREFIX = "Ignore:";
58
+ /** The Ignore option, as a question file holds it. */
59
+ export declare const ignoreOption: () => {
60
+ label: string;
61
+ means: string;
62
+ changes: string;
63
+ };
64
+ /** An Ignore answer's words: `Ignore: <reason>`. */
65
+ export declare const ignoreText: (reason: string) => string;
66
+ /**
67
+ * Whether a question's answer is Ignore (beta.24 review), and its reason when one was given: the
68
+ * Ignore option, or words that start `Ignore:`. Undefined for any other answer, or none.
69
+ */
70
+ export declare function ignoredAnswer(q: {
71
+ options: readonly {
72
+ label: string;
73
+ }[];
74
+ answer?: {
75
+ option?: number;
76
+ text?: string;
77
+ by: unknown;
78
+ } | undefined;
79
+ }): {
80
+ reason?: string;
81
+ } | undefined;
82
+ /** The longest name an outside system an answer adds may have. */
83
+ export declare const SYSTEM_NAME_MAX = 40;
84
+ /**
85
+ * Why words can't be a new outside system's name (beta.24 review), or undefined when they can: a
86
+ * short name of letters, digits, spaces and dashes, at most 40 characters, not a sentence (four
87
+ * words at most, none of "ignore", "this", "is", "a", "to", "the", "related", "not", "it").
88
+ */
89
+ export declare function systemNameProblem(name: string): string | undefined;
90
+ /**
91
+ * Beta.24 review: whether a system (its id, and its name when it has one) looks made from an
92
+ * answer's words rather than named: an id of five or more dash-separated words, or with a word
93
+ * of a sentence in it, or a name with spaces longer than 40 characters.
94
+ */
95
+ export declare function madeFromWords(id: string, name?: string): boolean;
96
+ /**
97
+ * Beta.24 review: whether words name a repo, component, system or team Atticus knows, as an
98
+ * answer about where calls go may: a repo of the manifests (its id, component or a module's
99
+ * component), a system of the profiles (its id, name, an alias or a topic), a team of roles.yaml,
100
+ * or a component a repo's facts name. Case and spacing aside, or by the id the words slug to.
101
+ */
102
+ export declare function namesKnownTarget(root: string, words: string): Promise<boolean>;
103
+ /**
104
+ * Beta.24 review: the refusal of words that name no repo, component or system as the answer of a
105
+ * question about where calls go, in a person's words: what to do instead.
106
+ */
107
+ export declare const wordsNameNothing: (words: string) => string;
39
108
  /**
40
109
  * The options of a hosts question that say an outside system answers on the host (O1): another
41
110
  * team's system (boundary internal, the first, the default) or a vendor's. The answer writes the
@@ -57,6 +126,24 @@ export declare const hostQuestionText: (host: string) => string;
57
126
  export declare function hostOfQuestion(q: {
58
127
  question: string;
59
128
  }): string | undefined;
129
+ /**
130
+ * Beta.24 review: the host a targets question the join raised for a host nothing resolves asks
131
+ * about (a gateway's forwarding call whose target URL is a token, `@targetUrl@`): its words start
132
+ * as a hosts question's do, and may go on to say what to do next (`forwardHostQuestion`). A
133
+ * targets question asked of a call (`Which repo or system answers ...`) has none.
134
+ */
135
+ export declare function joinHostOfQuestion(q: {
136
+ question: string;
137
+ }): string | undefined;
138
+ /**
139
+ * The outside system an answer to a join host question adds (beta.24 review): named by the host,
140
+ * or for a host still written as a token, by the token's name (`@targetVendorUrl@` →
141
+ * `targetVendorUrl`), never with the token's marks in its id.
142
+ */
143
+ export declare function outsideSystemOfJoinHost(host: string): {
144
+ id: string;
145
+ name: string;
146
+ };
60
147
  /**
61
148
  * Put an outside system for a host into the profile whose repos.manifest.yaml lists the repo
62
149
  * that asked (O1): its id and name from the host, the host as its alias, the boundary given
@@ -98,6 +185,24 @@ export declare function addProfileSystem(root: string, repo: string, s: {
98
185
  /** The lines a new system changes in the profile (as the write makes them). */
99
186
  changes?: LineChange[];
100
187
  }>;
188
+ /**
189
+ * Beta.24 review: take a system out of the profile that has it, or (with `rename`) give it another
190
+ * id and name, keeping its other fields, the file's comments and its order. For a system an
191
+ * answer's words made (`madeFromWords`), from Map › Trust: written as a file change in the
192
+ * metarepo, for review in the pull request. `preview` writes nothing. Undefined when no profile
193
+ * has the system. Throws when the profile would not be valid (the new id another system has).
194
+ */
195
+ export declare function editProfileSystem(root: string, id: string, o?: {
196
+ rename?: {
197
+ id: string;
198
+ name: string;
199
+ };
200
+ preview?: boolean;
201
+ }): Promise<{
202
+ profile: string;
203
+ changes: LineChange[];
204
+ written: boolean;
205
+ } | undefined>;
101
206
  /**
102
207
  * Put a host under a repo's `hosts` in the repos.manifest.yaml that lists it, keeping the
103
208
  * file's comments and order. `added` is false when the repo already lists it. Throws when no
@@ -11,6 +11,7 @@ export * from "./facts-join-prototype.js";
11
11
  export * from "./facts-carry.js";
12
12
  export * from "./facts-callers.js";
13
13
  export * from "./facts-terms.js";
14
+ export * from "./facts-deps.js";
14
15
  export * from "./org-notes.js";
15
16
  export * from "./link-evidence.js";
16
17
  export * from "./shared-maps.js";
@@ -318,6 +318,20 @@ export interface AnswerInput {
318
318
  batch?: string;
319
319
  /** ADR 0181: a person's rule applies it, from their correction. */
320
320
  rule?: AppliedRule;
321
+ /**
322
+ * Beta.24 review: Ignore, for a question about where calls go: they aren't real calls (CI/CD, a
323
+ * test, a template), so the join leaves them. In place of option and text; the reason, when
324
+ * given, is the answer's words (`Ignore: <reason>`), else the Ignore option is picked (added to
325
+ * the question's options when it was asked before Ignore was offered).
326
+ */
327
+ ignore?: {
328
+ reason?: string;
329
+ };
330
+ /**
331
+ * Beta.24 review: the id of the system `beforeWrite` adds to the profile, which the answer's
332
+ * words name, so they aren't refused as naming nothing.
333
+ */
334
+ adds?: string;
321
335
  }
322
336
  /**
323
337
  * Whether a host a hosts question asks about (`localhost:9966`, `limits.payments.forge.internal`)
@@ -108,8 +108,8 @@ export declare const ContextSource: z.ZodObject<{
108
108
  pattern: "pattern";
109
109
  code: "code";
110
110
  document: "document";
111
- catalog: "catalog";
112
111
  artifact: "artifact";
112
+ catalog: "catalog";
113
113
  checklist: "checklist";
114
114
  skill: "skill";
115
115
  instruction: "instruction";
@@ -134,8 +134,8 @@ export declare const ContextPackManifest: z.ZodObject<{
134
134
  pattern: "pattern";
135
135
  code: "code";
136
136
  document: "document";
137
- catalog: "catalog";
138
137
  artifact: "artifact";
138
+ catalog: "catalog";
139
139
  checklist: "checklist";
140
140
  skill: "skill";
141
141
  instruction: "instruction";
@@ -8,14 +8,14 @@ import { z } from "zod";
8
8
  export declare const DIALECT_SCHEMA_VERSION: 1;
9
9
  /** Grammars shipped with Atticus for syntax matches (ADR 0060). */
10
10
  export declare const SyntaxLanguage: z.ZodEnum<{
11
+ python: "python";
12
+ go: "go";
11
13
  java: "java";
12
14
  kotlin: "kotlin";
13
15
  typescript: "typescript";
14
16
  tsx: "tsx";
15
17
  javascript: "javascript";
16
18
  c_sharp: "c_sharp";
17
- python: "python";
18
- go: "go";
19
19
  scala: "scala";
20
20
  ruby: "ruby";
21
21
  php: "php";
@@ -59,14 +59,14 @@ export declare const DialectMatch: z.ZodUnion<readonly [z.ZodObject<{
59
59
  contains: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
60
60
  syntax: z.ZodString;
61
61
  language: z.ZodOptional<z.ZodEnum<{
62
+ python: "python";
63
+ go: "go";
62
64
  java: "java";
63
65
  kotlin: "kotlin";
64
66
  typescript: "typescript";
65
67
  tsx: "tsx";
66
68
  javascript: "javascript";
67
69
  c_sharp: "c_sharp";
68
- python: "python";
69
- go: "go";
70
70
  scala: "scala";
71
71
  ruby: "ruby";
72
72
  php: "php";
@@ -208,14 +208,14 @@ export declare const DialectRule: z.ZodObject<{
208
208
  contains: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
209
209
  syntax: z.ZodString;
210
210
  language: z.ZodOptional<z.ZodEnum<{
211
+ python: "python";
212
+ go: "go";
211
213
  java: "java";
212
214
  kotlin: "kotlin";
213
215
  typescript: "typescript";
214
216
  tsx: "tsx";
215
217
  javascript: "javascript";
216
218
  c_sharp: "c_sharp";
217
- python: "python";
218
- go: "go";
219
219
  scala: "scala";
220
220
  ruby: "ruby";
221
221
  php: "php";
@@ -405,14 +405,14 @@ export declare const DialectLookup: z.ZodObject<{
405
405
  contains: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
406
406
  syntax: z.ZodString;
407
407
  language: z.ZodOptional<z.ZodEnum<{
408
+ python: "python";
409
+ go: "go";
408
410
  java: "java";
409
411
  kotlin: "kotlin";
410
412
  typescript: "typescript";
411
413
  tsx: "tsx";
412
414
  javascript: "javascript";
413
415
  c_sharp: "c_sharp";
414
- python: "python";
415
- go: "go";
416
416
  scala: "scala";
417
417
  ruby: "ruby";
418
418
  php: "php";
@@ -534,14 +534,14 @@ export declare const Dialect: z.ZodObject<{
534
534
  contains: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
535
535
  syntax: z.ZodString;
536
536
  language: z.ZodOptional<z.ZodEnum<{
537
+ python: "python";
538
+ go: "go";
537
539
  java: "java";
538
540
  kotlin: "kotlin";
539
541
  typescript: "typescript";
540
542
  tsx: "tsx";
541
543
  javascript: "javascript";
542
544
  c_sharp: "c_sharp";
543
- python: "python";
544
- go: "go";
545
545
  scala: "scala";
546
546
  ruby: "ruby";
547
547
  php: "php";
@@ -600,14 +600,14 @@ export declare const Dialect: z.ZodObject<{
600
600
  contains: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
601
601
  syntax: z.ZodString;
602
602
  language: z.ZodOptional<z.ZodEnum<{
603
+ python: "python";
604
+ go: "go";
603
605
  java: "java";
604
606
  kotlin: "kotlin";
605
607
  typescript: "typescript";
606
608
  tsx: "tsx";
607
609
  javascript: "javascript";
608
610
  c_sharp: "c_sharp";
609
- python: "python";
610
- go: "go";
611
611
  scala: "scala";
612
612
  ruby: "ruby";
613
613
  php: "php";
@@ -59,6 +59,7 @@ export declare const FactCorrection: z.ZodObject<{
59
59
  config: "config";
60
60
  component: "component";
61
61
  field: "field";
62
+ dependency: "dependency";
62
63
  term: "term";
63
64
  framework: "framework";
64
65
  entry: "entry";
@@ -66,6 +67,7 @@ export declare const FactCorrection: z.ZodObject<{
66
67
  call: "call";
67
68
  deploy: "deploy";
68
69
  flow: "flow";
70
+ artifact: "artifact";
69
71
  }>;
70
72
  file: z.ZodString;
71
73
  line: z.ZodNumber;