@intentius/chant 0.124.104 → 0.124.105

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 (43) hide show
  1. package/dist/capabilities/templates.d.ts +66 -3
  2. package/dist/capabilities/templates.js +220 -81
  3. package/dist/cli/handlers/release-doctor.js +8 -3
  4. package/dist/cli/handlers/release-init.js +7 -4
  5. package/dist/cli/handlers/search.d.ts +1 -1
  6. package/dist/cli/handlers/search.js +24 -2
  7. package/dist/cli/parse-args.js +2 -2
  8. package/dist/cli/release-commands/doctor.js +5 -2
  9. package/dist/cloud-lister/aws.d.ts +9 -0
  10. package/dist/cloud-lister/aws.js +20 -0
  11. package/dist/config.d.ts +10 -0
  12. package/dist/config.js +2 -0
  13. package/dist/floor-table.data.js +1 -0
  14. package/dist/graph-refs.d.ts +13 -0
  15. package/dist/graph-refs.js +11 -4
  16. package/dist/lifecycle/derive-edges.d.ts +1 -1
  17. package/dist/lifecycle/derive-edges.js +5 -3
  18. package/dist/lifecycle/index-import.d.ts +12 -5
  19. package/dist/lifecycle/index-import.js +38 -9
  20. package/dist/lifecycle/release-artifacts.js +3 -1
  21. package/dist/lifecycle/release-at.d.ts +5 -1
  22. package/dist/lifecycle/release-at.js +69 -4
  23. package/dist/lifecycle/release-doctor.d.ts +10 -0
  24. package/dist/lifecycle/release-doctor.js +84 -14
  25. package/dist/lifecycle/release-green.d.ts +5 -2
  26. package/dist/lifecycle/release-green.js +40 -8
  27. package/dist/lifecycle/release-images.d.ts +7 -1
  28. package/dist/lifecycle/release-images.js +14 -5
  29. package/dist/lifecycle/release-init.d.ts +16 -7
  30. package/dist/lifecycle/release-init.js +212 -45
  31. package/dist/lifecycle/release-next.d.ts +1 -1
  32. package/dist/lifecycle/release-next.js +9 -4
  33. package/dist/release-floors.d.ts +1 -1
  34. package/dist/release-floors.js +1 -1
  35. package/dist/wave-runtime.mjs +38 -38
  36. package/dist/workspace/capabilities-contract.d.ts +15 -5
  37. package/dist/workspace/capabilities-contract.js +7 -4
  38. package/dist/workspace/capabilities.schema.json +45 -1
  39. package/dist/workspace/release-changed.d.ts +2 -0
  40. package/dist/workspace/release-changed.js +7 -2
  41. package/dist/workspace/release-steps/doctor.js +2 -1
  42. package/dist/workspace/train-cut.js +2 -2
  43. package/package.json +1 -1
@@ -1,5 +1,15 @@
1
1
  /** The first chant whose capabilities document carries `templates` (#4531). */
2
2
  export declare const CAPABILITY_TEMPLATES_FLOOR = "0.124.54";
3
+ /**
4
+ * The first chant whose capabilities document lists a project's own templates
5
+ * from `.chant/templates.json`, marks each entry's `origin`, may carry `kinds`,
6
+ * and lists refused project entries under `refused` (behold issue 1142).
7
+ */
8
+ export declare const PROJECT_TEMPLATES_FLOOR = "0.124.105";
9
+ /** Where a project declares its own templates, relative to the workspace or project root. */
10
+ export declare const PROJECT_TEMPLATES_FILE = ".chant/templates.json";
11
+ /** chant's own templates file, as a refusal names it. */
12
+ export declare const CHANT_TEMPLATES_FILE = "@intentius/chant/capabilities/templates.json";
3
13
  /** The version of templates.json's shape. */
4
14
  export declare const TEMPLATES_DATA_VERSION = 1;
5
15
  export type TemplateQueryKind = "path" | "cypher";
@@ -24,6 +34,8 @@ export interface TemplateEntry {
24
34
  question: string;
25
35
  /** The sources whose nodes it applies to (behold's source kinds); absent means every source. */
26
36
  sources?: string[];
37
+ /** The node kinds it applies to, as the graph holds them (`aws_s3_bucket`, `AWS::S3::Bucket`); absent means every kind. */
38
+ kinds?: string[];
27
39
  inputs: TemplateInput[];
28
40
  reads: TemplateReads;
29
41
  query: {
@@ -33,18 +45,69 @@ export interface TemplateEntry {
33
45
  /** What it does not answer, said where it is offered. */
34
46
  note?: string;
35
47
  }
36
- /** A templates file that does not hold to the entry kind, naming the template. */
48
+ /** Where a catalog entry came from: chant's own file, or the project's `.chant/templates.json`. */
49
+ export type TemplateOrigin = "chant" | "project";
50
+ /** An entry of the catalog the capabilities document lists. */
51
+ export interface CatalogTemplate extends TemplateEntry {
52
+ origin: TemplateOrigin;
53
+ }
54
+ /** A project entry left out of the catalog, and why. */
55
+ export interface RefusedTemplate {
56
+ /** The entry's id, when it has a usable one. */
57
+ id?: string;
58
+ /** The file it was read from, relative to the workspace or project root. */
59
+ file: string;
60
+ /** The field at fault, such as `templates[2].query.text`; absent when the file is not JSON. */
61
+ field?: string;
62
+ /** What is wrong, naming the file and the field. */
63
+ message: string;
64
+ }
65
+ /** What {@link templateCatalog} found: chant's templates, then the project's, and the project entries it refused. */
66
+ export interface TemplateCatalog {
67
+ templates: CatalogTemplate[];
68
+ refused: RefusedTemplate[];
69
+ }
70
+ /**
71
+ * A templates file or entry that does not hold to the entry kind, naming the
72
+ * template. `field` is the path to the field at fault and `file` the file it
73
+ * was read from, when known.
74
+ */
37
75
  export declare class TemplateCatalogError extends Error {
76
+ readonly field?: string | undefined;
77
+ readonly file?: string | undefined;
78
+ constructor(message: string, field?: string | undefined, file?: string | undefined);
38
79
  }
39
80
  /**
40
81
  * Read a templates file, checking each entry against the entry kind: a
41
82
  * unique id, exactly one resource input first, a query of a known kind
42
83
  * whose placeholders (path) or parameters (Cypher) are its inputs, and every
43
- * input used.
84
+ * input used. The first entry that does not hold is thrown.
85
+ */
86
+ export declare function parseTemplates(raw: unknown, file?: string): TemplateEntry[];
87
+ /**
88
+ * Check a templates file entry by entry: the entries that hold, and a
89
+ * {@link TemplateCatalogError} for each that does not. A file whose shape is
90
+ * wrong (not an object, another version, no list) is thrown whole. An id
91
+ * defined twice keeps its first entry.
44
92
  */
45
- export declare function parseTemplates(raw: unknown): TemplateEntry[];
93
+ export declare function checkTemplates(raw: unknown, file?: string): {
94
+ templates: TemplateEntry[];
95
+ refused: TemplateCatalogError[];
96
+ };
46
97
  /** The templates chant ships, checked. */
47
98
  export declare function investigationTemplates(): TemplateEntry[];
99
+ /** The directory a project's templates file is read in: the workspace root, or the project root when `dir` is in no workspace. */
100
+ export declare function templatesRoot(dir: string): string;
101
+ /**
102
+ * The template catalog for the project at `dir` (behold#1142): chant's
103
+ * templates, then the project's own from {@link PROJECT_TEMPLATES_FILE} at
104
+ * {@link templatesRoot}, each marked with its origin. A workspace member's
105
+ * own file is not read. A project entry that does not hold to the entry kind,
106
+ * or whose id is one of chant's, is left out and listed under `refused`, and
107
+ * the others load. A file that cannot be read as a templates file is refused
108
+ * whole, as one entry. No file means chant's templates alone.
109
+ */
110
+ export declare function templateCatalog(dir: string): TemplateCatalog;
48
111
  export interface ExpandedTemplate {
49
112
  template: string;
50
113
  kind: TemplateQueryKind;
@@ -17,18 +17,48 @@
17
17
  * behold and choudoufu read it as data. The initial set is the one behold#1027
18
18
  * stubbed in behold's src/graph-db/templates.ts.
19
19
  *
20
+ * A project adds its own templates in `.chant/templates.json`, in the same
21
+ * shape (behold#1142). {@link templateCatalog} reads it from the workspace
22
+ * root, or from the project root when there is no workspace, and lists its
23
+ * entries after chant's with `origin: "project"`. An entry that does not hold
24
+ * to the entry kind, or that reuses one of chant's ids, is refused alone and
25
+ * listed under `refused`, so one bad entry never takes the rest with it: a
26
+ * reader such as choudoufu refuses a whole list on one bad entry.
27
+ *
20
28
  * Filling in: a path template's `{{<input>}}` is replaced by the input's
21
29
  * value, the resource's id for `{{node}}`. A Cypher template takes its inputs
22
30
  * as query parameters, never spliced into the text: the resource's key is
23
31
  * `$key` and every other input is `$<name>`.
24
32
  */
33
+ import { readFileSync } from "node:fs";
34
+ import { join } from "node:path";
35
+ import { findProjectRoot, findWorkspaceRoot } from "../project-root.js";
25
36
  import data from "./templates.json" with { type: "json" };
26
37
  /** The first chant whose capabilities document carries `templates` (#4531). */
27
38
  export const CAPABILITY_TEMPLATES_FLOOR = "0.124.54";
39
+ /**
40
+ * The first chant whose capabilities document lists a project's own templates
41
+ * from `.chant/templates.json`, marks each entry's `origin`, may carry `kinds`,
42
+ * and lists refused project entries under `refused` (behold issue 1142).
43
+ */
44
+ export const PROJECT_TEMPLATES_FLOOR = "0.124.105";
45
+ /** Where a project declares its own templates, relative to the workspace or project root. */
46
+ export const PROJECT_TEMPLATES_FILE = ".chant/templates.json";
47
+ /** chant's own templates file, as a refusal names it. */
48
+ export const CHANT_TEMPLATES_FILE = "@intentius/chant/capabilities/templates.json";
28
49
  /** The version of templates.json's shape. */
29
50
  export const TEMPLATES_DATA_VERSION = 1;
30
- /** A templates file that does not hold to the entry kind, naming the template. */
51
+ /**
52
+ * A templates file or entry that does not hold to the entry kind, naming the
53
+ * template. `field` is the path to the field at fault and `file` the file it
54
+ * was read from, when known.
55
+ */
31
56
  export class TemplateCatalogError extends Error {
57
+ constructor(message, field, file) {
58
+ super(message);
59
+ this.field = field;
60
+ this.file = file;
61
+ }
32
62
  }
33
63
  const ID = /^[a-z][a-z0-9-]*$/;
34
64
  const INPUT_NAME = /^[a-z][A-Za-z0-9_]*$/;
@@ -42,94 +72,133 @@ const str = (v) => typeof v === "string" && v.trim() !== "";
42
72
  * Read a templates file, checking each entry against the entry kind: a
43
73
  * unique id, exactly one resource input first, a query of a known kind
44
74
  * whose placeholders (path) or parameters (Cypher) are its inputs, and every
45
- * input used.
75
+ * input used. The first entry that does not hold is thrown.
76
+ */
77
+ export function parseTemplates(raw, file) {
78
+ const { templates, refused } = checkTemplates(raw, file);
79
+ if (refused.length > 0)
80
+ throw refused[0];
81
+ return templates;
82
+ }
83
+ /**
84
+ * Check a templates file entry by entry: the entries that hold, and a
85
+ * {@link TemplateCatalogError} for each that does not. A file whose shape is
86
+ * wrong (not an object, another version, no list) is thrown whole. An id
87
+ * defined twice keeps its first entry.
46
88
  */
47
- export function parseTemplates(raw) {
89
+ export function checkTemplates(raw, file) {
48
90
  const doc = raw;
49
- if (!doc || typeof doc !== "object")
50
- throw new TemplateCatalogError("a templates file is an object");
91
+ const whole = (m, field) => {
92
+ throw new TemplateCatalogError(file ? `${file}${field ? ` ${field}` : ""}: ${m}` : m, field, file);
93
+ };
94
+ if (!doc || typeof doc !== "object" || Array.isArray(doc))
95
+ whole("a templates file is an object");
51
96
  if (doc.version !== TEMPLATES_DATA_VERSION)
52
- throw new TemplateCatalogError(`templates file version ${String(doc.version)} is not ${TEMPLATES_DATA_VERSION}`);
97
+ whole(`templates file version ${String(doc.version)} is not ${TEMPLATES_DATA_VERSION}`, "version");
53
98
  if (!Array.isArray(doc.templates))
54
- throw new TemplateCatalogError("templates is a list");
99
+ whole("templates is a list", "templates");
55
100
  const seen = new Set();
56
- return doc.templates.map((t, i) => {
57
- const e = t;
58
- const where = str(e?.id) ? `template ${e.id}` : `template ${i}`;
59
- const fail = (m) => {
60
- throw new TemplateCatalogError(`${where}: ${m}`);
61
- };
62
- if (!e || typeof e !== "object")
63
- fail("is not an object");
64
- if (!str(e.id) || !ID.test(e.id))
65
- fail("needs an id of lowercase letters, digits and -");
66
- if (seen.has(e.id))
67
- fail("is defined twice");
68
- seen.add(e.id);
69
- if (!str(e.title))
70
- fail("needs a title");
71
- if (!str(e.question))
72
- fail("needs the question it answers");
73
- if (!READS.includes(e.reads))
74
- fail(`reads is one of ${READS.join(", ")}`);
75
- if (e.sources !== undefined && (!Array.isArray(e.sources) || !e.sources.every(str)))
76
- fail("sources is a list of source kinds");
77
- if (e.note !== undefined && !str(e.note))
78
- fail("a note is text");
79
- if (!Array.isArray(e.inputs))
80
- fail("needs its inputs");
81
- const names = new Set();
82
- for (const input of e.inputs) {
83
- if (!input || !str(input.name) || !INPUT_NAME.test(input.name))
84
- fail("an input needs a name");
85
- if (names.has(input.name))
86
- fail(`input ${input.name} is listed twice`);
87
- names.add(input.name);
88
- if (!INPUT_KINDS.includes(input.kind))
89
- fail(`input ${input.name}'s kind is one of ${INPUT_KINDS.join(", ")}`);
90
- if (!str(input.description))
91
- fail(`input ${input.name} needs a description`);
101
+ const templates = [];
102
+ const refused = [];
103
+ doc.templates.forEach((t, i) => {
104
+ try {
105
+ templates.push(checkEntry(t, i, seen, file));
92
106
  }
93
- const resources = e.inputs.filter((x) => x.kind === "resource");
94
- if (resources.length !== 1 || e.inputs[0] !== resources[0])
95
- fail("takes one resource input, first");
96
- const q = e.query;
97
- if (!q || !KINDS.includes(q.kind) || !str(q.text))
98
- fail(`query is { kind: ${KINDS.join(" | ")}, text }`);
99
- const resource = resources[0].name;
100
- if (q.kind === "path") {
101
- if (/\$[A-Za-z_]/.test(q.text))
102
- fail("a path pattern takes {{input}} placeholders, not $parameters");
103
- const used = new Set([...q.text.matchAll(PLACEHOLDER)].map((m) => m[1]));
104
- for (const u of used)
105
- if (!names.has(u))
106
- fail(`{{${u}}} names no input`);
107
- // A scope is where the query is read, not part of its text.
108
- for (const input of e.inputs)
109
- if (input.kind !== "scope" && !used.has(input.name))
110
- fail(`the path pattern never uses ${input.name}`);
107
+ catch (e) {
108
+ if (!(e instanceof TemplateCatalogError))
109
+ throw e;
110
+ refused.push(e);
111
111
  }
112
- else {
113
- if (/\{\{/.test(q.text))
114
- fail("a Cypher query takes $parameters, never spliced {{input}} text");
115
- if (!/^\s*(MATCH|OPTIONAL MATCH|WITH|CALL|UNWIND)\b/i.test(q.text))
116
- fail("a Cypher query starts with a reading clause");
117
- if (/\b(CREATE|MERGE|DELETE|DETACH|SET|REMOVE|DROP)\b/i.test(q.text))
118
- fail("a Cypher query only reads");
119
- if (!balanced(q.text))
120
- fail("its brackets do not balance");
121
- const params = new Set([...q.text.matchAll(PARAM)].map((m) => m[1]));
122
- if (!params.has("key"))
123
- fail("a Cypher query binds the resource as $key");
124
- for (const p of params)
125
- if (p !== "key" && !names.has(p))
126
- fail(`$${p} names no input`);
127
- for (const input of e.inputs)
128
- if (input.name !== resource && input.kind !== "scope" && !params.has(input.name))
129
- fail(`the query never uses $${input.name}`);
130
- }
131
- return e;
132
112
  });
113
+ return { templates, refused };
114
+ }
115
+ /** One entry, checked; `seen` holds the ids before it. */
116
+ function checkEntry(t, i, seen, file) {
117
+ const e = t;
118
+ const at = `templates[${i}]`;
119
+ const where = str(e?.id) ? `template ${e.id}` : `template ${i}`;
120
+ const fail = (m, field = "") => {
121
+ const path = `${at}${field}`;
122
+ throw new TemplateCatalogError(file ? `${file} ${path}: ${where}: ${m}` : `${where}: ${m}`, path, file);
123
+ };
124
+ if (!e || typeof e !== "object" || Array.isArray(e))
125
+ fail("is not an object");
126
+ if (!str(e.id) || !ID.test(e.id))
127
+ fail("needs an id of lowercase letters, digits and -", ".id");
128
+ if (seen.has(e.id))
129
+ fail("is defined twice", ".id");
130
+ seen.add(e.id);
131
+ if (!str(e.title))
132
+ fail("needs a title", ".title");
133
+ if (!str(e.question))
134
+ fail("needs the question it answers", ".question");
135
+ if (!READS.includes(e.reads))
136
+ fail(`reads is one of ${READS.join(", ")}`, ".reads");
137
+ if (e.sources !== undefined && (!Array.isArray(e.sources) || !e.sources.every(str)))
138
+ fail("sources is a list of source kinds", ".sources");
139
+ if (e.kinds !== undefined && (!Array.isArray(e.kinds) || e.kinds.length === 0 || !e.kinds.every(str)))
140
+ fail("kinds is a list of node kinds, or absent for every kind", ".kinds");
141
+ if (e.note !== undefined && !str(e.note))
142
+ fail("a note is text", ".note");
143
+ if (!Array.isArray(e.inputs))
144
+ fail("needs its inputs", ".inputs");
145
+ const names = new Set();
146
+ e.inputs.forEach((input, j) => {
147
+ const f = `.inputs[${j}]`;
148
+ if (!input || !str(input.name) || !INPUT_NAME.test(input.name))
149
+ fail("an input needs a name", `${f}.name`);
150
+ if (names.has(input.name))
151
+ fail(`input ${input.name} is listed twice`, `${f}.name`);
152
+ names.add(input.name);
153
+ if (!INPUT_KINDS.includes(input.kind))
154
+ fail(`input ${input.name}'s kind is one of ${INPUT_KINDS.join(", ")}`, `${f}.kind`);
155
+ if (!str(input.description))
156
+ fail(`input ${input.name} needs a description`, `${f}.description`);
157
+ });
158
+ const resources = e.inputs.filter((x) => x.kind === "resource");
159
+ if (resources.length !== 1 || e.inputs[0] !== resources[0])
160
+ fail("takes one resource input, first", ".inputs");
161
+ const q = e.query;
162
+ if (!q || typeof q !== "object")
163
+ fail(`query is { kind: ${KINDS.join(" | ")}, text }`, ".query");
164
+ if (!KINDS.includes(q.kind))
165
+ fail(`query is { kind: ${KINDS.join(" | ")}, text }`, ".query.kind");
166
+ if (!str(q.text))
167
+ fail(`query is { kind: ${KINDS.join(" | ")}, text }`, ".query.text");
168
+ const text = ".query.text";
169
+ const resource = resources[0].name;
170
+ if (q.kind === "path") {
171
+ if (/\$[A-Za-z_]/.test(q.text))
172
+ fail("a path pattern takes {{input}} placeholders, not $parameters", text);
173
+ const used = new Set([...q.text.matchAll(PLACEHOLDER)].map((m) => m[1]));
174
+ for (const u of used)
175
+ if (!names.has(u))
176
+ fail(`{{${u}}} names no input`, text);
177
+ // A scope is where the query is read, not part of its text.
178
+ for (const input of e.inputs)
179
+ if (input.kind !== "scope" && !used.has(input.name))
180
+ fail(`the path pattern never uses ${input.name}`, text);
181
+ }
182
+ else {
183
+ if (/\{\{/.test(q.text))
184
+ fail("a Cypher query takes $parameters, never spliced {{input}} text", text);
185
+ if (!/^\s*(MATCH|OPTIONAL MATCH|WITH|CALL|UNWIND)\b/i.test(q.text))
186
+ fail("a Cypher query starts with a reading clause", text);
187
+ if (/\b(CREATE|MERGE|DELETE|DETACH|SET|REMOVE|DROP)\b/i.test(q.text))
188
+ fail("a Cypher query only reads", text);
189
+ if (!balanced(q.text))
190
+ fail("its brackets do not balance", text);
191
+ const params = new Set([...q.text.matchAll(PARAM)].map((m) => m[1]));
192
+ if (!params.has("key"))
193
+ fail("a Cypher query binds the resource as $key", text);
194
+ for (const p of params)
195
+ if (p !== "key" && !names.has(p))
196
+ fail(`$${p} names no input`, text);
197
+ for (const input of e.inputs)
198
+ if (input.name !== resource && input.kind !== "scope" && !params.has(input.name))
199
+ fail(`the query never uses $${input.name}`, text);
200
+ }
201
+ return e;
133
202
  }
134
203
  /** Whether (), [] and {} nest, outside quoted strings. */
135
204
  function balanced(text) {
@@ -157,6 +226,76 @@ export function investigationTemplates() {
157
226
  cache ?? (cache = parseTemplates(data));
158
227
  return cache;
159
228
  }
229
+ /** The directory a project's templates file is read in: the workspace root, or the project root when `dir` is in no workspace. */
230
+ export function templatesRoot(dir) {
231
+ return findWorkspaceRoot(dir)?.dir ?? findProjectRoot(dir);
232
+ }
233
+ /**
234
+ * The template catalog for the project at `dir` (behold#1142): chant's
235
+ * templates, then the project's own from {@link PROJECT_TEMPLATES_FILE} at
236
+ * {@link templatesRoot}, each marked with its origin. A workspace member's
237
+ * own file is not read. A project entry that does not hold to the entry kind,
238
+ * or whose id is one of chant's, is left out and listed under `refused`, and
239
+ * the others load. A file that cannot be read as a templates file is refused
240
+ * whole, as one entry. No file means chant's templates alone.
241
+ */
242
+ export function templateCatalog(dir) {
243
+ const chant = investigationTemplates().map((t) => ({ ...t, origin: "chant" }));
244
+ const file = PROJECT_TEMPLATES_FILE;
245
+ let text;
246
+ try {
247
+ text = readFileSync(join(templatesRoot(dir), file), "utf-8");
248
+ }
249
+ catch (e) {
250
+ if (e.code === "ENOENT")
251
+ return { templates: chant, refused: [] };
252
+ return { templates: chant, refused: [{ file, message: `${file}: cannot be read: ${e.message}` }] };
253
+ }
254
+ let raw;
255
+ try {
256
+ raw = JSON.parse(text);
257
+ }
258
+ catch (e) {
259
+ return { templates: chant, refused: [{ file, message: `${file}: is not JSON: ${e.message}` }] };
260
+ }
261
+ let checked;
262
+ try {
263
+ checked = checkTemplates(raw, file);
264
+ }
265
+ catch (e) {
266
+ if (!(e instanceof TemplateCatalogError))
267
+ throw e;
268
+ return { templates: chant, refused: [refusal(e, file)] };
269
+ }
270
+ const refused = checked.refused.map((e) => refusal(e, file, raw.templates));
271
+ const chantIds = new Set(chant.map((t) => t.id));
272
+ const own = [];
273
+ for (const t of checked.templates) {
274
+ if (chantIds.has(t.id)) {
275
+ const i = raw.templates.indexOf(t);
276
+ const field = `templates[${i}].id`;
277
+ refused.push({
278
+ id: t.id,
279
+ file,
280
+ field,
281
+ message: `${file} ${field}: template ${t.id}: ${CHANT_TEMPLATES_FILE} already defines ${t.id}, and an id keeps chant's meaning; rename this one`,
282
+ });
283
+ continue;
284
+ }
285
+ own.push({ ...t, origin: "project" });
286
+ }
287
+ return { templates: [...chant, ...own], refused };
288
+ }
289
+ function refusal(e, file, entries) {
290
+ const index = e.field?.match(/^templates\[(\d+)\]/)?.[1];
291
+ const id = index !== undefined ? entries?.[Number(index)]?.id : undefined;
292
+ return {
293
+ ...(typeof id === "string" && ID.test(id) ? { id } : {}),
294
+ file,
295
+ ...(e.field ? { field: e.field } : {}),
296
+ message: e.message,
297
+ };
298
+ }
160
299
  /** A value spliced into a path pattern is one search term: letters, digits and `_ : . - / * ( ) , [ ]` only. */
161
300
  const TERM_VALUE = /^[A-Za-z0-9_:.\-/*(),[\]]+$/;
162
301
  /**
@@ -9,7 +9,7 @@
9
9
  import { existsSync, realpathSync } from "node:fs";
10
10
  import { join, resolve } from "node:path";
11
11
  import { formatBold, formatError, formatSuccess } from "../format.js";
12
- const USAGE = "chant release doctor [--json]";
12
+ const USAGE = "chant release doctor [--from cut] [--json]";
13
13
  /** The release workflow file from the repository root: `release.workflow.file` in the workspace root's config, or the forge's default. */
14
14
  async function releaseWorkflowFile(cwd) {
15
15
  const { findWorkspaceRoot } = await import("../../project-root.js");
@@ -59,7 +59,7 @@ export function formatDoctorReport(report) {
59
59
  const e = report.environment;
60
60
  const where = e.ci === "github" ? `GitHub Actions${e.workflow ? `, ${e.workflow}` : ""}` : e.ci === "gitlab" ? "GitLab CI" : e.ci === "other" ? "CI" : "a workstation";
61
61
  const lines = [
62
- `Release doctor, from ${where}: OIDC ${e.oidc ? "yes" : "no"}; the release workflow is ${e.releaseWorkflow ?? "not known"}${e.repository ? ` in ${e.repository}` : ""}`,
62
+ `Release doctor, from ${where}${e.from === "cut" ? ", the cut job" : ""}: OIDC ${e.oidc ? "yes" : "no"}; the release workflow is ${e.releaseWorkflow ?? "not known"}${e.repository ? ` in ${e.repository}` : ""}`,
63
63
  ];
64
64
  for (const t of report.targets) {
65
65
  lines.push(formatBold(t.name));
@@ -76,6 +76,11 @@ export function formatDoctorReport(report) {
76
76
  export async function runReleaseDoctor(ctx) {
77
77
  const { args } = ctx;
78
78
  const cwd = resolve(".");
79
+ const from = ctx.args.migrateFrom;
80
+ if (from !== undefined && from !== "cut") {
81
+ console.error(formatError({ message: `--from ${from} is not a job the doctor knows: the release workflow's cut job is --from cut [doctor-from-invalid]`, hint: USAGE }));
82
+ return 1;
83
+ }
79
84
  let publish;
80
85
  let declaredGreen;
81
86
  let signing;
@@ -101,7 +106,7 @@ export async function runReleaseDoctor(ctx) {
101
106
  catch {
102
107
  groups = new Set();
103
108
  }
104
- const report = await releaseDoctor({ cwd, publish, releaseWorkflow: await releaseWorkflowFile(cwd), green: await greenGate(cwd, declaredGreen), ...(signing !== undefined ? { signing } : {}), groups });
109
+ const report = await releaseDoctor({ cwd, publish, releaseWorkflow: await releaseWorkflowFile(cwd), ...(from === "cut" ? { from } : {}), green: await greenGate(cwd, declaredGreen), ...(signing !== undefined ? { signing } : {}), groups });
105
110
  if (args.json) {
106
111
  console.log(JSON.stringify(report, null, 2));
107
112
  }
@@ -6,8 +6,8 @@
6
6
  * and `release.train` at the root, unless `--one-release`. See
7
7
  * ../../lifecycle/release-init.ts.
8
8
  */
9
- import { appendFileSync, existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
10
- import { join, relative, resolve, sep } from "node:path";
9
+ import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
10
+ import { dirname, join, relative, resolve, sep } from "node:path";
11
11
  import { formatBold, formatError, formatSuccess, formatWarning } from "../format.js";
12
12
  const USAGE = "chant release init [--yes] [--force] [--one-release] [--forge github|gitlab|forgejo] [--json]";
13
13
  export async function runReleaseInit(ctx) {
@@ -318,7 +318,7 @@ async function runTrainInit(ctx, root, plan, fg, fail) {
318
318
  return 0;
319
319
  }
320
320
  if (!json) {
321
- console.log(formatBold(`${write ? "" : "Dry run: "}a release train of ${members.length} packages, each released at its own version`));
321
+ console.log(formatBold(`${write ? "" : "Dry run: "}a release train of ${members.length} ${members.every((m) => m.package !== null) ? "packages" : "members"}, each released at its own version`));
322
322
  console.log(formatBold(`\nchant.workspace.json${wsCreated ? " (a new file)" : added.length > 0 ? ` (adds ${added.join(", ")})` : ""}`));
323
323
  console.log(`\n${wsText.replace(/^/gm, " ").trimEnd()}\n`);
324
324
  console.log(formatBold(`${prepared.configName}${prepared.created ? " (a new file)" : ""}`));
@@ -338,8 +338,11 @@ async function runTrainInit(ctx, root, plan, fg, fail) {
338
338
  }
339
339
  if (write) {
340
340
  writeFileSync(wsPath, wsText);
341
- for (const m of members)
341
+ for (const m of members) {
342
+ // #5271: a member of its own at release/<name> is a new directory.
343
+ mkdirSync(dirname(m.path), { recursive: true });
342
344
  writeFileSync(m.path, m.text);
345
+ }
343
346
  writeFileSync(prepared.configPath, prepared.configText);
344
347
  if (!json)
345
348
  console.log(formatSuccess(`Wrote chant.workspace.json, ${prepared.configName} and ${members.length} member configs.`));
@@ -90,7 +90,7 @@ export declare function printCapabilities(args: {
90
90
  countBy?: string;
91
91
  explain?: boolean;
92
92
  show?: string;
93
- }, query: string, lexicons: string[]): Promise<number>;
93
+ }, query: string, lexicons: string[], dir?: string): Promise<number>;
94
94
  /**
95
95
  * Answer capability terms over a graph that is not this project's own (#4375):
96
96
  * `chant workspace search` composes its members' graphs and views and asks
@@ -12,6 +12,7 @@ import { replaySnapshots, hasSnapshot } from "../../lifecycle/replay.js";
12
12
  import { diffLive } from "../../lifecycle/live-diff.js";
13
13
  import { formatUnobserved } from "../../observation.js";
14
14
  import { readChantPackageVersion } from "../../package-version.js";
15
+ import { applyLiveEndpoint } from "../../live-endpoint.js";
15
16
  import { loadChantConfig, matchesDeclaredEnvironment, resolveSourceDir } from "../../config.js";
16
17
  import { collectBuildRootContributors, loadPlugins, resolveProjectLexicons } from "../plugins.js";
17
18
  import { declaredBuildRootContributors, mergeDeclaredBuildRoots, withLexiconEdges } from "./declared-graph.js";
@@ -54,6 +55,17 @@ import { countJoins, formatIndexRef, indexOnlyGraph, joinCell, joinDeclaredToInd
54
55
  * thousands.
55
56
  */
56
57
  export async function runSearch(ctx) {
58
+ // The environment's declared endpoint (#5289) lives in the process env for
59
+ // the length of a live read, and is put back on every way out.
60
+ const endpoint = { restore: () => { } };
61
+ try {
62
+ return await searchAnswer(ctx, endpoint);
63
+ }
64
+ finally {
65
+ endpoint.restore();
66
+ }
67
+ }
68
+ async function searchAnswer(ctx, endpoint) {
57
69
  const { args } = ctx;
58
70
  const query = (args.path ?? "").trim();
59
71
  // A refusal (#4367): the error on stderr as always, and under --json the
@@ -150,6 +162,12 @@ export async function runSearch(ctx) {
150
162
  return refuse({ code: "build-failed", message: "Build failed — fix errors before searching live state" });
151
163
  }
152
164
  const observing = plugins.filter((p) => p.describeResources);
165
+ // An environment can declare its own endpoint (#1166, #5289), so a read
166
+ // against an emulator needs no exported AWS_ENDPOINT_URL. Ambient wins.
167
+ const applied = applyLiveEndpoint(config.environments, environment, observing);
168
+ endpoint.restore = applied.restore;
169
+ if (applied.notice)
170
+ console.error(formatWarning({ message: applied.notice }));
153
171
  ambientKinds = observing.flatMap((p) => p.ambientKinds?.() ?? []);
154
172
  const stacks = (config.stacks ?? []).map((s) => ({ name: s.name, region: s.region, src: s.src }));
155
173
  let observations;
@@ -694,7 +712,7 @@ async function declaredGraph(ctx, projectPath, srcDir, loaded) {
694
712
  * search` and `chant workspace search`, which differ only in the lexicons
695
713
  * they report on.
696
714
  */
697
- export async function printCapabilities(args, query, lexicons) {
715
+ export async function printCapabilities(args, query, lexicons, dir = resolve(".")) {
698
716
  const { capabilitiesDocument, capabilitiesFailure, formatCapabilities } = await import("../../workspace/capabilities-contract.js");
699
717
  const extra = [
700
718
  // `args.path` is "." when no query was given.
@@ -714,7 +732,11 @@ export async function printCapabilities(args, query, lexicons) {
714
732
  console.log(JSON.stringify(await capabilitiesFailure(error)));
715
733
  return 1;
716
734
  }
717
- const doc = await capabilitiesDocument(lexicons);
735
+ const doc = await capabilitiesDocument(lexicons, undefined, dir);
736
+ // A project template left out (behold#1142) is said on stderr, so a person
737
+ // sees it under --json too.
738
+ for (const r of doc.refused)
739
+ console.error(`template refused: ${r.message}`);
718
740
  if (args.json)
719
741
  console.log(JSON.stringify(doc));
720
742
  else
@@ -308,8 +308,8 @@ export function parseArgs(args) {
308
308
  else if (arg === "--from") {
309
309
  // Shared by `migrate --from <lexicon>`, `import --from <env>`,
310
310
  // `components promote --from <env>`, `init --from <repo>@<ref>` and
311
- // `ci last-green --from <rev>` (#4031); the commands never run
312
- // together, so one field carries all five.
311
+ // `ci last-green --from <rev>` (#4031) and `release doctor --from cut`; the commands never run
312
+ // together, so one field carries all six.
313
313
  result.migrateFrom = args[++i];
314
314
  }
315
315
  else if (arg === "--kustomize") {
@@ -3,12 +3,15 @@ export const doctorCommand = {
3
3
  name: "doctor",
4
4
  helpOrder: 70,
5
5
  help: [
6
- " release doctor [--json]",
6
+ " release doctor [--from cut] [--json]",
7
7
  " Before a cut, ask each release.publish target whether",
8
8
  " a publish from here can succeed: credentials, OIDC,",
9
9
  " npm trusted publishers and dist-tags, registry and",
10
10
  " forge access. Says what it can't observe from here.",
11
+ " --from cut: this is the release workflow's cut job,",
12
+ " which has no OIDC token; the checks that need one",
13
+ " say the publish job holds it instead of failing.",
11
14
  " Exits 1 when a check fails.",
12
15
  ],
13
- usage: { order: 40, text: "release doctor [--json]" },
16
+ usage: { order: 40, text: "release doctor [--from cut] [--json]" },
14
17
  };
@@ -32,3 +32,12 @@ export declare const DEFAULT_AWS_TYPES: readonly string[];
32
32
  export declare function isGlobalAwsType(type: string): boolean;
33
33
  export declare function cloudControlUrl(target: AwsTarget, region: string): string;
34
34
  export declare function listAws(ctx: ListerContext, target: AwsTarget, chains: CredentialChains, retryDelays?: readonly number[]): Promise<void>;
35
+ /**
36
+ * A queue's ARN (#5285). Cloud Control lists an SQS queue by its name or its
37
+ * URL and gives no ARN, while a Lambda environment value or a dead-letter
38
+ * policy names the queue by `arn:<partition>:sqs:<region>:<account>:<name>`.
39
+ * The name is the property when the model has one, else the last path segment
40
+ * of the identifier (a queue URL ends in the name). `scopeId` is the account
41
+ * the read was made in.
42
+ */
43
+ export declare function sqsQueueArn(account: string, region: string, props: Record<string, unknown>, identifier: string): string | undefined;
@@ -170,6 +170,11 @@ async function listOne(ctx, target, credentials, type, region, location, retryDe
170
170
  cloudIds.push({ kind: "arn", value: d.Identifier });
171
171
  if (typeof props.Arn === "string" && props.Arn.startsWith("arn:"))
172
172
  cloudIds.push({ kind: "arn", value: props.Arn });
173
+ if (type === "AWS::SQS::Queue" && cloudIds.length === 0) {
174
+ const queueArn = sqsQueueArn(ctx.scope.scopeId, location, props, d.Identifier);
175
+ if (queueArn)
176
+ cloudIds.push({ kind: "arn", value: queueArn });
177
+ }
173
178
  cloudIds.push({ kind: "import-id", value: d.Identifier });
174
179
  found.push({ listedType: type, location, nativeId: d.Identifier, cloudIds, tags, properties: props, observedAt, labels: false });
175
180
  }
@@ -181,6 +186,21 @@ async function listOne(ctx, target, credentials, type, region, location, retryDe
181
186
  ctx.resources.push(buildResource(ctx, r));
182
187
  ctx.coverage.push({ listedType: type, location, ...listedVerdict(ctx.scope) });
183
188
  }
189
+ /**
190
+ * A queue's ARN (#5285). Cloud Control lists an SQS queue by its name or its
191
+ * URL and gives no ARN, while a Lambda environment value or a dead-letter
192
+ * policy names the queue by `arn:<partition>:sqs:<region>:<account>:<name>`.
193
+ * The name is the property when the model has one, else the last path segment
194
+ * of the identifier (a queue URL ends in the name). `scopeId` is the account
195
+ * the read was made in.
196
+ */
197
+ export function sqsQueueArn(account, region, props, identifier) {
198
+ const name = typeof props.QueueName === "string" && props.QueueName !== "" ? props.QueueName : identifier.split("/").filter(Boolean).pop();
199
+ if (!name || !/^\d{12}$/.test(account))
200
+ return undefined;
201
+ const partition = region.startsWith("cn-") ? "aws-cn" : region.startsWith("us-gov-") ? "aws-us-gov" : "aws";
202
+ return `arn:${partition}:sqs:${region}:${account}:${name}`;
203
+ }
184
204
  function recordFailure(ctx, type, location, res) {
185
205
  const err = awsError(res);
186
206
  const detail = describeFailure(res, err.code, err.message);