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

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,16 @@ 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 or Basic 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
+ * `basic: false` leaves the Basic token out, as beta.24 released the check: the facts schema
50
+ * keeps it so (the verifier and Trust's secrets check take the Basic token).
51
+ */
52
+ export declare function hasSecretShape(text: string, o?: {
53
+ basic?: boolean;
54
+ }): boolean;
45
55
  /**
46
56
  * Redact the secrets on a line, keeping what names them: a value after a secret-looking key
47
57
  * (at the line's start, whatever the value; anywhere on it, a quoted literal), a setter's
@@ -63,8 +73,9 @@ export declare function quoteHoldsSecret(quote: string): boolean;
63
73
  * Whether a word claim is put together from `cite.with` parts (ADR 0124 addendum A-derived): a
64
74
  * rake task's `namespace:task`, a key a helper prefixes (`${prefix}_conferenceCache`). Each part's
65
75
  * 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.
76
+ * `: . _ / #`, or another part; `-` joins a word), and whatever is left between the parts,
77
+ * separators aside, must be written on the cited lines: at least one piece, so the cited lines
78
+ * name some of the word. The parts' own lines are checked by the caller.
68
79
  */
69
80
  export declare function partsBuildWord(claim: string, parts: readonly string[], lines: readonly string[]): boolean;
70
81
  export declare function partsNamePath(lines: readonly string[], path: string): boolean;
@@ -0,0 +1,85 @@
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
+ /**
26
+ * Review of beta.25: one dependency fact a link rests on, with the coordinates it names (a link
27
+ * between two components holds every coordinate one builds on of the other's: `kit-api` and
28
+ * `kit-core` of component `kit` are one arrow).
29
+ */
30
+ export interface DependencyFactEnd extends DependencyEnd {
31
+ group: string;
32
+ name: string;
33
+ version?: string;
34
+ /** Its scope, when not compile. */
35
+ scope?: DependencyScope;
36
+ }
37
+ export interface DependencyLink {
38
+ /** The dependency fact, in the component that builds on the library (the first by id). */
39
+ from: DependencyEnd;
40
+ /**
41
+ * Beta.25: every dependency fact the link rests on, `from` first, each with its lines: two
42
+ * module poms of one component, a `<profile>`'s copy, `implementation` and `runtimeOnly` of the
43
+ * same coordinates, and (review of beta.25) every other coordinate of the same library
44
+ * component, each with its coordinates. The link goes only once each of them is wrong.
45
+ */
46
+ facts?: (DependencyEnd & Partial<Pick<DependencyFactEnd, "group" | "name" | "version" | "scope">>)[];
47
+ /** The artifact fact, in the library's component, that publishes the coordinates. */
48
+ to: DependencyEnd;
49
+ /**
50
+ * Review of beta.25: every artifact fact of the library's component a dependency on the link
51
+ * names, `to` first (one per coordinate).
52
+ */
53
+ published?: DependencyEnd[];
54
+ group: string;
55
+ name: string;
56
+ /**
57
+ * The dependency's declared scope, when it says one other than compile; on a link merged from
58
+ * several facts (review of beta.25), only when every one of them has it, else left out.
59
+ */
60
+ scope?: DependencyScope;
61
+ /** The version the dependency declares, when it says one. */
62
+ version?: string;
63
+ }
64
+ /** Coordinates two or more components of the estate publish: nothing is drawn to either. */
65
+ export interface AmbiguousCoordinates {
66
+ group: string;
67
+ name: string;
68
+ by: FactEnd[];
69
+ }
70
+ export interface DependencyJoinResult {
71
+ links: DependencyLink[];
72
+ ambiguous: AmbiguousCoordinates[];
73
+ /** Dependencies on coordinates nobody in the estate publishes: drawn as nothing. */
74
+ outside: number;
75
+ /** Test-scoped dependencies on the estate's own coordinates: drawn as nothing. */
76
+ test: number;
77
+ }
78
+ export declare function joinDependencies(input: {
79
+ repos: readonly JoinRepo[];
80
+ }): DependencyJoinResult;
81
+ /**
82
+ * The id a "depends on" link is known by, for a view's join: stable across reads of one pom, and
83
+ * (review of beta.25) one per pair of components, as the join makes one link per pair.
84
+ */
85
+ export declare const dependencyLinkId: (l: Pick<DependencyLink, "from" | "to">) => string;
@@ -73,6 +73,14 @@ export interface JoinRepo {
73
73
  hosts: readonly string[];
74
74
  basePath?: string;
75
75
  }[];
76
+ /**
77
+ * Beta.25 (ADR 0192 addendum): every module the manifest lists, by its folder, hosts or not: a
78
+ * build fact (`artifact`, `dependency`) that names no component is its build file's module's.
79
+ */
80
+ moduleDirs?: readonly {
81
+ path: string;
82
+ component: string;
83
+ }[];
76
84
  /** An API gateway (the manifest's `type: gateway`): its entries are routes it forwards. */
77
85
  gateway?: boolean;
78
86
  /**
@@ -207,6 +215,13 @@ export declare const JOINED_BY_ANSWER = "joined-by-answer";
207
215
  export declare const JOINED_BY_NAME = "joined-by-name";
208
216
  export declare const JOINED_BY_REPO = "joined-by-repo";
209
217
  export declare const JOINED_BY_HOST = "joined-by-host";
218
+ /**
219
+ * A call whose host nothing resolves, joined to a gateway proxy's flow by its whole path: the one
220
+ * proxy whose cited `<BasePath>` starts it, the one flow of its method under it. Code at both
221
+ * ends: a how, never a guess. Beta.25: verified only for a gateway's forwarding call that names
222
+ * no host (a chained proxy); a call whose host nothing resolves is inferred, `joined-by-path` first.
223
+ */
224
+ export declare const JOINED_BY_BASE_PATH = "joined-by-base-path";
210
225
  /**
211
226
  * J0, J1: the guesses a join by host can rest on, though the host itself was cited. The setting
212
227
  * that gave the host is a platform-wide one nobody aimed at the caller (`setsForAll`), or one that
@@ -263,7 +278,7 @@ export declare const JOINED_TO_SHARED_MAP = "joined-to-shared-map";
263
278
  * or the component's own name as the host), `path` (no target named: the only entry of the
264
279
  * estate that serves it), `topic` (a listener of the published topic).
265
280
  */
266
- export type JoinHow = "answer" | "named" | "repo" | "host" | "path" | "topic";
281
+ export type JoinHow = "answer" | "named" | "repo" | "host" | "base-path" | "path" | "topic";
267
282
  export interface FactJoin {
268
283
  call: FactEnd;
269
284
  entry: FactEnd;
@@ -289,6 +304,8 @@ export interface FactJoin {
289
304
  * A join by path (the join fallback): nobody named the callee, so it is inferred. `within`
290
305
  * says where the one entry that serves the call was found: the caller's own repo first, else
291
306
  * the estate; `named` is the target the call gave, when it named one the estate doesn't have.
307
+ * Beta.25: also a join by a proxy's BasePath (`how: "base-path"`) whose caller's host nothing
308
+ * resolves (`within: "estate"`): the path is code at both ends, the host a guess.
292
309
  */
293
310
  inferred?: {
294
311
  within: "repo" | "estate";
@@ -545,8 +562,23 @@ export declare function routeScore(called: string, served: string): number;
545
562
  export declare function nameScore(called: string, served: string): number;
546
563
  /** The question for a call no single repo answers: the same words as the facts-targets question. */
547
564
  export declare function callTargetQuestion(f: Call, component: string): string;
565
+ /**
566
+ * The question for a gateway's forwarding call whose host nothing resolves. A host still written
567
+ * as a token (`@targetUrl@`, `{{host}}`, `${HOST}`) is most often one a deploy tool's file sets
568
+ * per environment (the Apigee config plugin's `config.json`), which a read before beta.24 didn't
569
+ * record: the next step it says is to read the gateway repo again, never a guess at a repo.
570
+ */
571
+ export declare function forwardHostQuestion(host: string, repo: string): string;
548
572
  /** The question for a call whose gateway routes lead back where they came from (A-gateway2). */
549
573
  export declare function gatewayCycleQuestion(f: Call, component: string, gateway: string): string;
574
+ /**
575
+ * A host's registrable domain (`northwind.example` for `api.northwind.example`,
576
+ * `northwind.co.uk` for `api.northwind.co.uk`), or undefined for a name the outside rule can't
577
+ * place: one label, `localhost`, an address, a private or in-cluster name (`.corp`, `.svc`), a
578
+ * Service and its namespace (`wallets.payments`, `wallets.qa`, `forge-wallets.dev`: two labels
579
+ * whose last is no `PUBLIC_TLDS` name). A wildcard and a port are left off.
580
+ */
581
+ export declare function registrableDomain(host: string): string | undefined;
550
582
  /**
551
583
  * The host a call goes to as the join reads it (P1): the call's own host, else the host of the
552
584
  * config fact its `base` names (the first by id), else the base itself; `host:port` when the text
@@ -554,12 +586,6 @@ export declare function gatewayCycleQuestion(f: Call, component: string, gateway
554
586
  * no key that reads as a host). The measure uses it to tell which outside system took a call.
555
587
  */
556
588
  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
589
  export declare function placeholderIn(s: string | undefined): {
564
590
  name: string;
565
591
  fallback?: string;
@@ -1,3 +1,4 @@
1
+ import { z } from "zod";
1
2
  import type { CatalogRecord } from "./catalog.js";
2
3
  import { Fact, type FactOf } from "./schema/facts.js";
3
4
  /**
@@ -14,14 +15,48 @@ export interface FactIssue {
14
15
  code: string;
15
16
  message: string;
16
17
  }
18
+ /**
19
+ * A fact of a kind this Atticus doesn't know (beta.25, ADR 0192 addendum): a newer Atticus wrote
20
+ * it. It is left out of what is read, and said, rather than refusing the whole file; whoever
21
+ * writes the file back must keep it (or not write), since it is a teammate's fact.
22
+ */
23
+ export interface NewerFact {
24
+ line?: number;
25
+ factId: string;
26
+ kind: string;
27
+ message: string;
28
+ /** The line as written (a line-by-line read), for a writer to keep it as it is. */
29
+ raw?: string;
30
+ }
17
31
  export type ParseFactsResult = {
18
32
  ok: true;
19
33
  facts: Fact[];
34
+ /** Beta.25: the facts of kinds a newer Atticus wrote, left out of `facts`. */
35
+ newer?: NewerFact[];
20
36
  } | {
21
37
  ok: false;
22
38
  issues: FactIssue[];
23
39
  };
40
+ /** A JSON value that is a fact of a kind this Atticus doesn't know, said as one; else undefined. */
41
+ export declare function newerFactOf(json: unknown, line?: number): NewerFact | undefined;
42
+ /**
43
+ * Review of beta.25: a fact of a kind this Atticus knows that a newer Atticus wrote: every reason
44
+ * it doesn't read is a field this Atticus doesn't know (a name as Atticus writes them, never a
45
+ * slip of one the kind has: `nearFieldOf`) or a value of one of its lists it doesn't know (a
46
+ * lowercase word more than two edits from each of the list's values, as `scope: "shaded"`; never
47
+ * `scope: "system"`, which is recorded as provided). Said as such, so the fact is left out on its
48
+ * own and kept as written; anything else wrong is a wrong fact, refused for the assistant to fix.
49
+ */
50
+ export declare function newerShapeOf(json: unknown, issues: readonly z.core.$ZodIssue[], line?: number): NewerFact | undefined;
24
51
  export declare function parseFacts(text: string): ParseFactsResult;
52
+ /**
53
+ * A facts file's line as it may be kept where people read it (`<repo>.rejected.jsonl`), beta.25
54
+ * review: a config fact any of whose fields carries a secret (`configSecretField`, beta.24's value
55
+ * check included, or a quote `redactSecrets` changes) has its value, source, parts and quote
56
+ * redacted, the rest kept as written. A line that isn't JSON is redacted as a line of code is,
57
+ * and any quoted literal that reads as a credential goes too. Anything else is kept as it is.
58
+ */
59
+ export declare function redactFactLine(raw: string): string;
25
60
  /** A line of a facts file that isn't a fact, with its number, its text and what is wrong. */
26
61
  export type BadFactLine = {
27
62
  line: number;
@@ -37,6 +72,7 @@ export type BadFactLine = {
37
72
  export declare function parseFactLine(raw: string, line: number, seen: Set<string>): {
38
73
  fact?: Fact;
39
74
  bad?: BadFactLine;
75
+ newer?: NewerFact;
40
76
  };
41
77
  /**
42
78
  * Read a JSONL facts file line by line, keeping every line that reads and returning the others
@@ -49,6 +85,8 @@ export declare function parseFactLine(raw: string, line: number, seen: Set<strin
49
85
  export declare function parseFactsLines(text: string): {
50
86
  facts: Fact[];
51
87
  bad: BadFactLine[];
88
+ /** Beta.25: facts of kinds a newer Atticus wrote, left out of `facts` (`newerFactOf`). */
89
+ newer: NewerFact[];
52
90
  };
53
91
  /** One canonical JSON line per fact, sorted by id; the same facts give the same bytes. */
54
92
  export declare function serializeFacts(facts: readonly Fact[]): string;
@@ -71,6 +109,27 @@ export interface ProjectResult {
71
109
  export declare const factIdPart: (text: string) => string;
72
110
  /** The Endpoint id an entry fact projects to in its component (`projectFacts`). */
73
111
  export declare function entryEndpointId(f: FactOf<"entry">, component: string): string;
112
+ /**
113
+ * The component a fact is placed in that names one its repo's manifest doesn't have (review of
114
+ * beta.25, ADR 0192 addendum §2): a repo whose manifest entry lists no modules ships as its one
115
+ * component, so a fact (an entry, a call, a store, any but a build's coordinates, which the
116
+ * verifier refuses instead) naming a component that is neither the repo's own nor one the
117
+ * manifest names anywhere (`ledger-api`, a folder's name) is the repo's component's, and its
118
+ * endpoints are in the box its depends-on arrow starts from. Undefined when the fact stays as it
119
+ * is: it names none, or one the manifest names, or the repo lists modules, or it is a prototype
120
+ * (ADR 0133: its UI, BFF and mocks are components of their own, read and compared, never
121
+ * written into the catalog).
122
+ */
123
+ export declare function placedComponentOf(f: Fact, manifest: {
124
+ /** The repo's own component (the manifest's `component`, else its id). */
125
+ component: string;
126
+ /** The repo's modules as the manifest lists them. */
127
+ modules?: readonly unknown[] | undefined;
128
+ /** Every component (and repo id) the estate's manifests name. */
129
+ components: readonly string[];
130
+ /** The repo is a prototype (its manifest `type`). */
131
+ prototype?: boolean | undefined;
132
+ }): string | undefined;
74
133
  /**
75
134
  * A call's normalised path: a gRPC method stays `package.Service/Method` and a SOAP operation
76
135
  * `Contract/Operation` (a client may write either with a leading slash); an HTTP path loses a parameter's optional marker and constraint first
@@ -1,3 +1,4 @@
1
+ import { type Document } from "yaml";
1
2
  import { type LineChange } from "./manifest-edit.js";
2
3
  /**
3
4
  * Which repo answers on a host (ADR 0088): a scan or atticus estate join asks, as a question
@@ -36,6 +37,118 @@ export declare function topicOfQuestion(q: {
36
37
  export declare const PICKER_LABELS: ReadonlySet<string>;
37
38
  /** The last option of a hosts question: no repo of the estate answers on it. */
38
39
  export declare const HOSTS_NONE = "None of these";
40
+ /**
41
+ * The step `atticus estate join` asks which component a spec step's call-out reaches by (named
42
+ * here so the answer's rules below are checked where it is written; the CLI raises it).
43
+ */
44
+ export declare const ESTATE_TARGETS_STEP_ID = "estate-targets";
45
+ /**
46
+ * Beta.24 review (answers made into boxes): the questions about where calls go, whose answer the
47
+ * join reads: hosts, targets (an ambiguous call or an unknown host's), topics and the estate's
48
+ * call-outs. Each takes Ignore, and none takes words that name nothing as a system.
49
+ */
50
+ export declare const JOIN_STEPS: ReadonlySet<string>;
51
+ /**
52
+ * The option every join question has (beta.24 review): the calls it asks about aren't real calls
53
+ * (CI/CD, a test, a template), so the join leaves them, the same as "None of these", and never
54
+ * draws a box for them. Its words with a reason are `Ignore: <reason>`.
55
+ */
56
+ export declare const JOIN_IGNORE_LABEL = "Ignore: not a real call (e.g. CI/CD, a test, a template)";
57
+ /** How an Ignore answer with a reason starts (the person's words follow it). */
58
+ export declare const IGNORE_PREFIX = "Ignore:";
59
+ /** The Ignore option, as a question file holds it. */
60
+ export declare const ignoreOption: () => {
61
+ label: string;
62
+ means: string;
63
+ changes: string;
64
+ };
65
+ /** Beta.25: the longest reason an Ignore keeps, as the local API takes it. */
66
+ export declare const IGNORE_REASON_MAX = 300;
67
+ /** An Ignore answer's words: `Ignore: <reason>`. */
68
+ export declare const ignoreText: (reason: string) => string;
69
+ /**
70
+ * Whether a question's answer is Ignore (beta.24 review), and its reason when one was given: the
71
+ * Ignore option, or words that start `Ignore:`. Undefined for any other answer, or none.
72
+ */
73
+ export declare function ignoredAnswer(q: {
74
+ options: readonly {
75
+ label: string;
76
+ }[];
77
+ answer?: {
78
+ option?: number;
79
+ text?: string;
80
+ by: unknown;
81
+ } | undefined;
82
+ }): {
83
+ reason?: string;
84
+ } | undefined;
85
+ /** The longest name an outside system an answer adds may have. */
86
+ export declare const SYSTEM_NAME_MAX = 40;
87
+ /**
88
+ * Beta.25 (review of beta.24): whether a system's name reads as a sentence: by its words only,
89
+ * two or more of a sentence's small words ("ignore this, its cicd related"). Never by its marks:
90
+ * a real system's name may have a comma, a full stop or a `!` in it ("Northwind, Inc.", "Harbor
91
+ * Co."), and a profile holds what its people wrote.
92
+ */
93
+ export declare function nameReadsAsSentence(name: string): boolean;
94
+ /**
95
+ * Beta.25 (review of beta.24): whether words read as a sentence rather than a name: a sentence's
96
+ * marks (a comma, a semicolon, `!`, `?`, a quote, or a full stop that ends a word: never the dots
97
+ * of a host), or two or more of a sentence's small words ("ignore this, its cicd related"). A name
98
+ * of any length in words ("Payments API Gateway North East") is a name, and so is one with a
99
+ * single small word in it ("IT Service Desk", "Plan A").
100
+ */
101
+ export declare function readsAsSentence(words: string): boolean;
102
+ /**
103
+ * Why words can't be a new outside system's name (beta.24 review), or undefined when they can: a
104
+ * short name of letters, digits, spaces and dashes, at most 40 characters, that doesn't read as a
105
+ * sentence (`readsAsSentence`). Lenient for names: "IT Service Desk", "Plan A" and a five-word
106
+ * name are names.
107
+ */
108
+ export declare function systemNameProblem(name: string): string | undefined;
109
+ /** The names Atticus knows a target by (`knownTargetNames`). */
110
+ export interface KnownTargets {
111
+ ids: Set<string>;
112
+ names: Set<string>;
113
+ /**
114
+ * Beta.25: the profiles' systems' names exactly, lower case, marks and all ("northwind, inc."),
115
+ * of those whose name isn't a sentence by its words (`nameReadsAsSentence`).
116
+ */
117
+ systemNames?: Set<string>;
118
+ }
119
+ /**
120
+ * Beta.25: the names Atticus knows a target by, as `namesKnownTarget` reads them: `ids` the ids
121
+ * (repos, components, a system's id, alias or topic, teams) exactly, lower case; `names` those and
122
+ * the systems' names, each also as the id it slugs to; `systemNames` the systems' names exactly.
123
+ * Systems whose id is in `except` are left out (the boxes an answer's words made, which name
124
+ * nothing real).
125
+ */
126
+ export declare function knownTargetNames(root: string, o?: {
127
+ except?: ReadonlySet<string>;
128
+ }): Promise<Required<KnownTargets>>;
129
+ /**
130
+ * Whether words name a target of `knownTargetNames`: a profile system's name exactly, case aside
131
+ * (beta.25: "Northwind, Inc." names the system so named, its marks and all); else case and spacing
132
+ * aside, or by the id they slug to; words that read as a sentence only when they are an id exactly
133
+ * (a sentence is never a system's name, even one an answer's words once wrote into a profile).
134
+ */
135
+ export declare function namesKnown(known: KnownTargets, words: string): boolean;
136
+ /**
137
+ * Beta.24 review: whether words name a repo, component, system or team Atticus knows, as an
138
+ * answer about where calls go may: a repo of the manifests (its id, component or a module's
139
+ * component), a system of the profiles (its id, name, an alias or a topic), a team of roles.yaml,
140
+ * or a component a repo's facts name. Case and spacing aside, or by the id the words slug to.
141
+ * Beta.25: words that read as a sentence name only an id they are exactly, and the systems in
142
+ * `except` (the boxes an answer's words made) are none.
143
+ */
144
+ export declare function namesKnownTarget(root: string, words: string, o?: {
145
+ except?: ReadonlySet<string>;
146
+ }): Promise<boolean>;
147
+ /**
148
+ * Beta.24 review: the refusal of words that name no repo, component or system as the answer of a
149
+ * question about where calls go, in a person's words: what to do instead.
150
+ */
151
+ export declare const wordsNameNothing: (words: string) => string;
39
152
  /**
40
153
  * The options of a hosts question that say an outside system answers on the host (O1): another
41
154
  * team's system (boundary internal, the first, the default) or a vendor's. The answer writes the
@@ -57,6 +170,41 @@ export declare const hostQuestionText: (host: string) => string;
57
170
  export declare function hostOfQuestion(q: {
58
171
  question: string;
59
172
  }): string | undefined;
173
+ /**
174
+ * Beta.24 review: the host a targets question the join raised for a host nothing resolves asks
175
+ * about (a gateway's forwarding call whose target URL is a token, `@targetUrl@`): its words start
176
+ * as a hosts question's do, and may go on to say what to do next (`forwardHostQuestion`). A
177
+ * targets question asked of a call (`Which repo or system answers ...`) has none. Beta.25: the
178
+ * host up to the first `?` that ends the question, so a token with spaces in it (`{{ vendor_url
179
+ * }}`, as `forwardHostQuestion` writes it) is read back whole.
180
+ */
181
+ export declare function joinHostOfQuestion(q: {
182
+ question: string;
183
+ }): string | undefined;
184
+ /**
185
+ * The outside system an answer to a join host question adds (beta.24 review): named by the host,
186
+ * or for a host still written as a token, by the token's name (`@targetVendorUrl@` →
187
+ * `targetVendorUrl`), never with the token's marks in its id.
188
+ */
189
+ export declare function outsideSystemOfJoinHost(host: string): {
190
+ id: string;
191
+ name: string;
192
+ };
193
+ /**
194
+ * Beta.25 (review of beta.24): the one way every profile edit is written (an outside system, a
195
+ * system a person named, a box put right), so a preview shows only the lines that really change:
196
+ * no line folded (`lineWidth: 0`), flow collections padded as the file pads them (`[ a ]` or
197
+ * `[a]`), and each line the edit didn't change kept exactly as the file had it (the library pads
198
+ * a file's maps and lists alike, so a file that mixes `{ a: 1 }` with `[b]` keeps both). LF only;
199
+ * the caller writes it in the file's own line endings.
200
+ */
201
+ export declare function profileText(doc: Document, before: string | undefined): string;
202
+ /**
203
+ * Beta.25 (review of beta.24): a profile edit Atticus doesn't make, said in a person's words (the
204
+ * local API answers 422): the file stays as it is, for a person to change by hand.
205
+ */
206
+ export declare class ProfileEditError extends Error {
207
+ }
60
208
  /**
61
209
  * Put an outside system for a host into the profile whose repos.manifest.yaml lists the repo
62
210
  * that asked (O1): its id and name from the host, the host as its alias, the boundary given
@@ -97,7 +245,39 @@ export declare function addProfileSystem(root: string, repo: string, s: {
97
245
  topics?: string[];
98
246
  /** The lines a new system changes in the profile (as the write makes them). */
99
247
  changes?: LineChange[];
248
+ /**
249
+ * Beta.25: for a new system, the file, the text it was read as (undefined: none yet) and the
250
+ * text written (or, previewed, to write), so a caller can write it with others, all or none.
251
+ */
252
+ write?: {
253
+ file: string;
254
+ before: string | undefined;
255
+ after: string;
256
+ };
100
257
  }>;
258
+ /**
259
+ * Beta.24 review: take a system out of the profile that has it, or (with `rename`) give it another
260
+ * id and name, keeping its other fields, the file's comments and its order (a comment above a
261
+ * system taken out stays, above the next). For a system an answer's words made (a box on Map ›
262
+ * Trust): written as a file change in the
263
+ * metarepo, for review in the pull request. `preview` writes nothing. Undefined when no profile
264
+ * has the system. Throws when the profile would not be valid (the new id another system has).
265
+ */
266
+ export declare function editProfileSystem(root: string, id: string, o?: {
267
+ rename?: {
268
+ id: string;
269
+ name: string;
270
+ };
271
+ preview?: boolean;
272
+ }): Promise<{
273
+ profile: string;
274
+ changes: LineChange[];
275
+ written: boolean;
276
+ /** Beta.25: the file, the text it was read as and the text written (or to write). */
277
+ file: string;
278
+ before: string;
279
+ after: string;
280
+ } | undefined>;
101
281
  /**
102
282
  * Put a host under a repo's `hosts` in the repos.manifest.yaml that lists it, keeping the
103
283
  * file's comments and order. `added` is false when the repo already lists it. Throws when no
@@ -1,20 +1,4 @@
1
- /**
2
- * Normalise an HTTP path or topic so the same interface found in different places
3
- * (caller code, gateway route, callee controller) gets the same identity.
4
- *
5
- * - path parameters in any style ({id}, :id, <id>, ${id}) become "{}"
6
- * - query strings and fragments are dropped
7
- * - repeated and trailing slashes are removed; a leading slash is ensured for paths
8
- * - topics (no leading slash in the input and no "/" at all) are returned trimmed
9
- */
10
- export declare function normalizePath(input: string): string;
11
- /**
12
- * A path with each `{...}` parameter cut to its name: what follows the first `:`, `?` or `=` in
13
- * braces nested inside a constraint (`{code:regex(^\\d{3}$)}`) are matched, not cut at the first `}`.
14
- * braces nested inside a constraint (`{code:regex(^\\d{{3}}$)}`) are matched, not cut at the first `}`.
15
- * An unclosed `{` leaves the rest as written.
16
- */
17
- export declare function stripParamConstraints(path: string): string;
1
+ export { normalizePath, stripParamConstraints } from "./paths.js";
18
2
  /** Code-unit string order, the same in every locale (`localeCompare` is not: ICU orders `_`/`-`
19
3
  * and, in `da`, `aa` differently), for every sort that feeds records, ids, hashes or a merge. */
20
4
  export declare function cmpText(a: string, b: string): number;
@@ -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";
@@ -0,0 +1,23 @@
1
+ /**
2
+ * `@maycombhq/core/paths`: how the join normalises an HTTP path or a topic, with no imports, so
3
+ * the app (a browser bundle that takes nothing else of core at run time) matches a call's path to
4
+ * a link's exactly as the join made the link (review of beta.24). The same export as the
5
+ * package's own (`@maycombhq/core`).
6
+ */
7
+ /**
8
+ * Normalise an HTTP path or topic so the same interface found in different places
9
+ * (caller code, gateway route, callee controller) gets the same identity.
10
+ *
11
+ * - path parameters in any style ({id}, :id, <id>, ${id}) become "{}"
12
+ * - query strings and fragments are dropped
13
+ * - repeated and trailing slashes are removed; a leading slash is ensured for paths
14
+ * - topics (no leading slash in the input and no "/" at all) are returned trimmed
15
+ */
16
+ export declare function normalizePath(input: string): string;
17
+ /**
18
+ * A path with each `{...}` parameter cut to its name: what follows the first `:`, `?` or `=` in
19
+ * braces nested inside a constraint (`{code:regex(^\\d{3}$)}`) are matched, not cut at the first `}`.
20
+ * braces nested inside a constraint (`{code:regex(^\\d{{3}}$)}`) are matched, not cut at the first `}`.
21
+ * An unclosed `{` leaves the rest as written.
22
+ */
23
+ export declare function stripParamConstraints(path: string): string;
@@ -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";