@intentius/chant 0.124.104 → 0.124.106

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 (46) hide show
  1. package/dist/bundle-check.d.ts +7 -3
  2. package/dist/bundle-check.js +61 -10
  3. package/dist/capabilities/templates.d.ts +66 -3
  4. package/dist/capabilities/templates.js +220 -81
  5. package/dist/cli/handlers/release-doctor.js +8 -3
  6. package/dist/cli/handlers/release-init.js +7 -4
  7. package/dist/cli/handlers/search.d.ts +1 -1
  8. package/dist/cli/handlers/search.js +24 -2
  9. package/dist/cli/main.js +3 -2
  10. package/dist/cli/parse-args.js +2 -2
  11. package/dist/cli/release-commands/doctor.js +5 -2
  12. package/dist/cloud-lister/aws.d.ts +9 -0
  13. package/dist/cloud-lister/aws.js +20 -0
  14. package/dist/config.d.ts +10 -0
  15. package/dist/config.js +2 -0
  16. package/dist/floor-table.data.js +1 -0
  17. package/dist/graph-refs.d.ts +13 -0
  18. package/dist/graph-refs.js +11 -4
  19. package/dist/lifecycle/derive-edges.d.ts +1 -1
  20. package/dist/lifecycle/derive-edges.js +5 -3
  21. package/dist/lifecycle/index-import.d.ts +12 -5
  22. package/dist/lifecycle/index-import.js +38 -9
  23. package/dist/lifecycle/release-artifacts.js +3 -1
  24. package/dist/lifecycle/release-at.d.ts +5 -1
  25. package/dist/lifecycle/release-at.js +69 -4
  26. package/dist/lifecycle/release-doctor.d.ts +10 -0
  27. package/dist/lifecycle/release-doctor.js +84 -14
  28. package/dist/lifecycle/release-green.d.ts +5 -2
  29. package/dist/lifecycle/release-green.js +40 -8
  30. package/dist/lifecycle/release-images.d.ts +7 -1
  31. package/dist/lifecycle/release-images.js +14 -5
  32. package/dist/lifecycle/release-init.d.ts +16 -7
  33. package/dist/lifecycle/release-init.js +212 -45
  34. package/dist/lifecycle/release-next.d.ts +1 -1
  35. package/dist/lifecycle/release-next.js +9 -4
  36. package/dist/release-floors.d.ts +1 -1
  37. package/dist/release-floors.js +1 -1
  38. package/dist/wave-runtime.mjs +38 -38
  39. package/dist/workspace/capabilities-contract.d.ts +15 -5
  40. package/dist/workspace/capabilities-contract.js +7 -4
  41. package/dist/workspace/capabilities.schema.json +45 -1
  42. package/dist/workspace/release-changed.d.ts +2 -0
  43. package/dist/workspace/release-changed.js +7 -2
  44. package/dist/workspace/release-steps/doctor.js +2 -1
  45. package/dist/workspace/train-cut.js +2 -2
  46. package/package.json +1 -1
@@ -106,9 +106,13 @@ export declare function readBundleCheckConfig(pkgDir: string): BundleCheckConfig
106
106
  * `optional` packages, and each chant import is one the installed chant
107
107
  * serves as compiled JS ({@link chantRuntimeTarget});
108
108
  * - the runtime dependencies are exactly the packages the bundle imports and
109
- * the `needs`, and every `@intentius/chant*` among them and among the
110
- * devDependencies is pinned to the root's `@intentius/chant`, an exact version;
111
- * - each installed chant package is that version, or a local build marked
109
+ * the `needs`; `@intentius/chant` among them and among the devDependencies
110
+ * is the root's pin, an exact version, and every lexicon is an exact version;
111
+ * - each lexicon pin is one whose peerDependencies range on `@intentius/chant`
112
+ * (and on any other chant package the product pins) takes the product's
113
+ * pin of it: lexicons are released on their own, so a lexicon a train did
114
+ * not cut stays at its last release, which still names the chant it needs;
115
+ * - each installed chant package is its pin, or a local build marked
112
116
  * `chantLocal` (`chant dev local`);
113
117
  * - the bundle and the tarball stay within `maxBytes` and `maxPackBytes`;
114
118
  * - no metafile input matches a `deny` pattern.
@@ -13,16 +13,20 @@
13
13
  * names its bundle, its ceiling and its denied inputs (`chantBundleCheck` in
14
14
  * the package's package.json, read by `chant dev bundle-check`).
15
15
  *
16
- * This module imports only Node's own modules, so a product's build script
17
- * can import it from plain Node.
16
+ * This module imports only Node's own modules and chant's version-range
17
+ * reader, which imports nothing, so a product's build script can import it
18
+ * from plain Node.
18
19
  */
19
20
  import { execFileSync } from "node:child_process";
20
21
  import { existsSync, readFileSync, statSync } from "node:fs";
21
22
  import { builtinModules } from "node:module";
22
23
  import { dirname, join, resolve } from "node:path";
24
+ import { parseVersion, satisfies } from "./workspace/lineage-version.js";
23
25
  /** Any `@intentius/chant` package, with or without a subpath: core and every lexicon. */
24
26
  const CHANT = /^(@intentius\/chant(?:-[a-z0-9-]+)?)(\/.*)?$/;
25
27
  const CONDITIONS = ["import", "node", "default"];
28
+ /** An exact version, as a product pins each chant package. */
29
+ const EXACT = /^\d+\.\d+\.\d+(?:-[\w.]+)?$/;
26
30
  /** The target Node's ESM conditions pick from one exports value, in key order. */
27
31
  function pick(value) {
28
32
  if (typeof value === "string")
@@ -197,9 +201,13 @@ function packSize(pkgDir) {
197
201
  * `optional` packages, and each chant import is one the installed chant
198
202
  * serves as compiled JS ({@link chantRuntimeTarget});
199
203
  * - the runtime dependencies are exactly the packages the bundle imports and
200
- * the `needs`, and every `@intentius/chant*` among them and among the
201
- * devDependencies is pinned to the root's `@intentius/chant`, an exact version;
202
- * - each installed chant package is that version, or a local build marked
204
+ * the `needs`; `@intentius/chant` among them and among the devDependencies
205
+ * is the root's pin, an exact version, and every lexicon is an exact version;
206
+ * - each lexicon pin is one whose peerDependencies range on `@intentius/chant`
207
+ * (and on any other chant package the product pins) takes the product's
208
+ * pin of it: lexicons are released on their own, so a lexicon a train did
209
+ * not cut stays at its last release, which still names the chant it needs;
210
+ * - each installed chant package is its pin, or a local build marked
203
211
  * `chantLocal` (`chant dev local`);
204
212
  * - the bundle and the tarball stay within `maxBytes` and `maxPackBytes`;
205
213
  * - no metafile input matches a `deny` pattern.
@@ -213,7 +221,7 @@ export function checkBundle(pkgDir, config) {
213
221
  const pin = rootPkg.dependencies?.["@intentius/chant"] ?? rootPkg.devDependencies?.["@intentius/chant"];
214
222
  if (pin === undefined)
215
223
  problems.push(`${join(root, "package.json")} does not name @intentius/chant`);
216
- else if (!/^\d+\.\d+\.\d+(?:-[\w.]+)?$/.test(pin))
224
+ else if (!EXACT.test(pin))
217
225
  problems.push(`@intentius/chant is '${pin}' in ${join(root, "package.json")}, not an exact version`);
218
226
  const bundleFile = join(dir, config.bundle);
219
227
  let text = "";
@@ -259,13 +267,28 @@ export function checkBundle(pkgDir, config) {
259
267
  if (!used.has(name))
260
268
  problems.push(`${name} is a runtime dependency that the bundle does not import and chantBundleCheck.needs does not name`);
261
269
  }
270
+ // The version the product pins each chant package at: core at the root's
271
+ // pin, every other one at its exact version in this package or the root.
272
+ const pins = new Map();
273
+ for (const list of [rootPkg.devDependencies, rootPkg.dependencies, pkg.devDependencies, pkg.dependencies]) {
274
+ for (const [name, v] of Object.entries(list ?? {}))
275
+ if (CHANT.test(name) && EXACT.test(v))
276
+ pins.set(name, v);
277
+ }
262
278
  if (pin !== undefined) {
279
+ pins.set("@intentius/chant", pin);
263
280
  for (const [kind, list] of [["dependencies", deps], ["devDependencies", pkg.devDependencies ?? {}]]) {
264
281
  if (dir === root && kind === "devDependencies")
265
282
  continue;
266
283
  for (const [name, v] of Object.entries(list)) {
267
- if (CHANT.test(name) && v !== pin)
268
- problems.push(`${name} is '${v}' in ${kind}, not the root's chant pin ${pin}`);
284
+ if (!CHANT.test(name))
285
+ continue;
286
+ if (name === "@intentius/chant") {
287
+ if (v !== pin)
288
+ problems.push(`${name} is '${v}' in ${kind}, not the root's chant pin ${pin}`);
289
+ }
290
+ else if (!EXACT.test(v))
291
+ problems.push(`${name} is '${v}' in ${kind}, not an exact version`);
269
292
  }
270
293
  }
271
294
  }
@@ -278,6 +301,7 @@ export function checkBundle(pkgDir, config) {
278
301
  const core = readManifest(join(coreDir, "package.json"));
279
302
  chant = core.chantLocal ? `local chant ${core.version} (${String(core.chantLocal.commit).slice(0, 12)})` : `chant ${core.version}`;
280
303
  }
304
+ const installedChant = new Map();
281
305
  for (const name of new Set([...Object.keys(deps), ...Object.keys(pkg.devDependencies ?? {})])) {
282
306
  if (!CHANT.test(name) || pin === undefined)
283
307
  continue;
@@ -288,8 +312,35 @@ export function checkBundle(pkgDir, config) {
288
312
  continue;
289
313
  }
290
314
  const installed = readManifest(join(at, "package.json"));
291
- if (!installed.chantLocal && installed.version !== pin)
292
- problems.push(`the installed ${name} is ${installed.version}, not the pin ${pin}; run npm ci`);
315
+ installedChant.set(name, installed);
316
+ const own = pins.get(name);
317
+ if (own !== undefined && !installed.chantLocal && installed.version !== own)
318
+ problems.push(`the installed ${name} is ${installed.version}, not the pin ${own}; run npm ci`);
319
+ }
320
+ // A lexicon is released on its own and states the chant it works with in
321
+ // its peerDependencies (`^<core's label>` when its release train cut it), so
322
+ // a lexicon pin is compatible when the product's pin of each chant package
323
+ // the lexicon names there falls in that range. A `chant dev local` build
324
+ // stamps its packages' ranges to each other, so it is left out.
325
+ for (const [name, installed] of installedChant) {
326
+ if (installed.chantLocal || installed.version !== pins.get(name))
327
+ continue;
328
+ const needs = { ...installed.dependencies, ...installed.peerDependencies };
329
+ for (const [peer, range] of Object.entries(needs)) {
330
+ const at = pins.get(peer);
331
+ if (!CHANT.test(peer) || at === undefined || installedChant.get(peer)?.chantLocal)
332
+ continue;
333
+ const v = parseVersion(at);
334
+ let ok;
335
+ try {
336
+ ok = v !== null && satisfies(v, range);
337
+ }
338
+ catch {
339
+ ok = false;
340
+ }
341
+ if (!ok)
342
+ problems.push(`${name} ${installed.version} works with ${peer} ${range} (its peerDependencies), and the product pins ${peer} ${at}; pin a ${name} release whose range takes ${at}`);
343
+ }
293
344
  }
294
345
  if (config.deny?.length) {
295
346
  const metafile = config.metafile === undefined ? undefined : join(dir, config.metafile);
@@ -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.`));