@caelo-cms/shared 0.11.21 → 0.12.1

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 (109) hide show
  1. package/dist/ai-tools.d.ts +4 -0
  2. package/dist/ai-tools.d.ts.map +1 -1
  3. package/dist/ai-tools.js +6 -0
  4. package/dist/ai-tools.js.map +1 -1
  5. package/dist/bug-intake.d.ts +15 -0
  6. package/dist/bug-intake.d.ts.map +1 -1
  7. package/dist/bug-intake.js +14 -0
  8. package/dist/bug-intake.js.map +1 -1
  9. package/dist/change-journal.d.ts.map +1 -1
  10. package/dist/change-journal.js +1 -0
  11. package/dist/change-journal.js.map +1 -1
  12. package/dist/context.d.ts +26 -0
  13. package/dist/context.d.ts.map +1 -1
  14. package/dist/context.js +2 -1
  15. package/dist/context.js.map +1 -1
  16. package/dist/index.d.ts +2 -0
  17. package/dist/index.d.ts.map +1 -1
  18. package/dist/index.js +2 -0
  19. package/dist/index.js.map +1 -1
  20. package/dist/link-refs.d.ts +18 -2
  21. package/dist/link-refs.d.ts.map +1 -1
  22. package/dist/link-refs.js +24 -6
  23. package/dist/link-refs.js.map +1 -1
  24. package/dist/lists/address.d.ts +6 -0
  25. package/dist/lists/address.d.ts.map +1 -1
  26. package/dist/lists/address.js +9 -1
  27. package/dist/lists/address.js.map +1 -1
  28. package/dist/lists/resolve-values.d.ts +11 -0
  29. package/dist/lists/resolve-values.d.ts.map +1 -1
  30. package/dist/lists/resolve-values.js +19 -0
  31. package/dist/lists/resolve-values.js.map +1 -1
  32. package/dist/lists/resolve.d.ts +5 -0
  33. package/dist/lists/resolve.d.ts.map +1 -1
  34. package/dist/lists/resolve.js +7 -0
  35. package/dist/lists/resolve.js.map +1 -1
  36. package/dist/owner-setup-token.d.ts +28 -0
  37. package/dist/owner-setup-token.d.ts.map +1 -0
  38. package/dist/owner-setup-token.js +41 -0
  39. package/dist/owner-setup-token.js.map +1 -0
  40. package/dist/redirect-emit-front-door.d.ts.map +1 -1
  41. package/dist/redirect-emit-front-door.js +4 -0
  42. package/dist/redirect-emit-front-door.js.map +1 -1
  43. package/dist/redirect-emit-gcp.d.ts +8 -0
  44. package/dist/redirect-emit-gcp.d.ts.map +1 -1
  45. package/dist/redirect-emit-gcp.js +4 -1
  46. package/dist/redirect-emit-gcp.js.map +1 -1
  47. package/dist/redirect-plan.d.ts +2 -2
  48. package/dist/redirect-plan.d.ts.map +1 -1
  49. package/dist/redirect-plan.js +13 -4
  50. package/dist/redirect-plan.js.map +1 -1
  51. package/dist/redirect-target.d.ts +57 -7
  52. package/dist/redirect-target.d.ts.map +1 -1
  53. package/dist/redirect-target.js +130 -8
  54. package/dist/redirect-target.js.map +1 -1
  55. package/dist/seo.d.ts +21 -0
  56. package/dist/seo.d.ts.map +1 -1
  57. package/dist/seo.js +21 -0
  58. package/dist/seo.js.map +1 -1
  59. package/dist/site-security-headers.d.ts +323 -0
  60. package/dist/site-security-headers.d.ts.map +1 -0
  61. package/dist/site-security-headers.js +424 -0
  62. package/dist/site-security-headers.js.map +1 -0
  63. package/dist/staged-site.d.ts +11 -0
  64. package/dist/staged-site.d.ts.map +1 -1
  65. package/dist/staged-site.js +26 -0
  66. package/dist/staged-site.js.map +1 -1
  67. package/dist/template-engine.d.ts +7 -0
  68. package/dist/template-engine.d.ts.map +1 -1
  69. package/dist/template-engine.js +38 -1
  70. package/dist/template-engine.js.map +1 -1
  71. package/dist/template-sections.d.ts +23 -1
  72. package/dist/template-sections.d.ts.map +1 -1
  73. package/dist/template-sections.js +124 -17
  74. package/dist/template-sections.js.map +1 -1
  75. package/dist/version.d.ts +2 -2
  76. package/dist/version.d.ts.map +1 -1
  77. package/dist/version.js +1 -1
  78. package/dist/version.js.map +1 -1
  79. package/package.json +1 -1
  80. package/src/ai-tools.ts +7 -0
  81. package/src/bug-intake.ts +16 -0
  82. package/src/change-journal.ts +1 -0
  83. package/src/context.ts +28 -0
  84. package/src/index.ts +2 -0
  85. package/src/link-refs.test.ts +38 -4
  86. package/src/link-refs.ts +39 -6
  87. package/src/lists/address.ts +16 -1
  88. package/src/lists/lists.test.ts +2 -0
  89. package/src/lists/resolve-values.ts +19 -0
  90. package/src/lists/resolve.test.ts +8 -0
  91. package/src/lists/resolve.ts +8 -0
  92. package/src/owner-setup-token.ts +49 -0
  93. package/src/redirect-emit-front-door.ts +6 -0
  94. package/src/redirect-emit-gcp.ts +12 -1
  95. package/src/redirect-emit.test.ts +44 -0
  96. package/src/redirect-plan.test.ts +57 -0
  97. package/src/redirect-plan.ts +12 -5
  98. package/src/redirect-target.test.ts +110 -4
  99. package/src/redirect-target.ts +142 -8
  100. package/src/seo.test.ts +24 -0
  101. package/src/seo.ts +25 -0
  102. package/src/site-security-headers.test.ts +263 -0
  103. package/src/site-security-headers.ts +509 -0
  104. package/src/staged-site.ts +30 -0
  105. package/src/template-engine-link-field.test.ts +148 -0
  106. package/src/template-engine-lists.test.ts +1 -1
  107. package/src/template-engine.ts +41 -1
  108. package/src/template-sections.ts +136 -20
  109. package/src/version.ts +1 -1
@@ -0,0 +1,148 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+
3
+ /**
4
+ * #1433 — a top-level `link` field reads the way a link inside a list entry
5
+ * does (`docs/lists.md` §2): `{{f}}` = href, `{{f.href}}`, `{{f.target}}`,
6
+ * `{{f.title}}`. A path no value can answer stays raw and is reported with a
7
+ * marker the Stage refuses (never literal `{{…}}` in published HTML).
8
+ */
9
+
10
+ import { describe, expect, it } from "bun:test";
11
+ import { LINK_VALUE_KEYS, linkValue } from "./lists/resolve-values.js";
12
+ import {
13
+ describeFieldPathProblems,
14
+ fieldPathProblems,
15
+ renderTemplate,
16
+ type TemplateField,
17
+ } from "./template-engine.js";
18
+
19
+ const CTA: TemplateField = { name: "primary_cta", kind: "link" };
20
+
21
+ function render(html: string, value: unknown, fields: readonly TemplateField[] = [CTA]) {
22
+ return renderTemplate({
23
+ html,
24
+ fields,
25
+ contentValues: value === undefined ? {} : { primary_cta: value },
26
+ });
27
+ }
28
+
29
+ describe("#1433 top-level link field", () => {
30
+ it("resolves dot paths outside a list", () => {
31
+ const r = render('<a href="{{primary_cta.href}}" target="{{primary_cta.target}}">x</a>', {
32
+ href: "/pricing",
33
+ target: "_blank",
34
+ });
35
+ expect(r.html).toBe('<a href="/pricing" target="_blank">x</a>');
36
+ expect(r.missingSlots).toEqual([]);
37
+ });
38
+
39
+ it("the bare key is the href, never [object Object]", () => {
40
+ const r = render('<a href="{{primary_cta}}">x</a>', { href: "/pricing" });
41
+ expect(r.html).toBe('<a href="/pricing">x</a>');
42
+ expect(r.missingSlots).toEqual([]);
43
+ expect(render('<a href="{{{primary_cta}}}">x</a>', { href: "/p" }).html).toBe(
44
+ '<a href="/p">x</a>',
45
+ );
46
+ });
47
+
48
+ it("an object with an empty href is no value, never [object Object]", () => {
49
+ expect(render("{{primary_cta}}", { href: "" }).html).toBe("{{primary_cta}}");
50
+ expect(render("{{{primary_cta}}}", { href: "" }).html).toBe("{{{primary_cta}}}");
51
+ });
52
+
53
+ it("a string value reads the same", () => {
54
+ const r = render("{{primary_cta}}|{{primary_cta.href}}|{{primary_cta.target}}", "/p");
55
+ expect(r.html).toBe("/p|/p|");
56
+ expect(r.missingSlots).toEqual([]);
57
+ });
58
+
59
+ it("reads the field default when the placement has no value", () => {
60
+ const r = renderTemplate({
61
+ html: "{{primary_cta.href}}",
62
+ fields: [{ ...CTA, default: { href: "/d" } }],
63
+ });
64
+ expect(r.html).toBe("/d");
65
+ });
66
+
67
+ it("works inside a scalar conditional and for a path used as one", () => {
68
+ expect(
69
+ render('{{#primary_cta}}<a href="{{.}}">x</a>{{/primary_cta}}', { href: "/p" }).html,
70
+ ).toBe('<a href="/p">x</a>');
71
+ expect(render("{{#primary_cta}}x{{/primary_cta}}", undefined).html).toBe("");
72
+ const t = '{{#primary_cta.target}} target="{{primary_cta.target}}"{{/primary_cta.target}}';
73
+ expect(render(t, { href: "/p" }).html).toBe("");
74
+ expect(render(t, { href: "/p", target: "_blank" }).html).toBe(' target="_blank"');
75
+ });
76
+
77
+ it("an unknown path stays raw and reports the marker the Stage refuses", () => {
78
+ const r = render("{{primary_cta.label}}", { href: "/p", label: "Go" });
79
+ expect(r.html).toBe("{{primary_cta.label}}");
80
+ expect(r.missingSlots).toEqual(["field-path-unknown:primary_cta.label"]);
81
+ });
82
+
83
+ it("a path into an empty link and a malformed value are reported, never empty", () => {
84
+ const empty = render('<a href="{{primary_cta.href}}">x</a>', undefined);
85
+ expect(empty.html).toBe('<a href="{{primary_cta.href}}">x</a>');
86
+ expect(empty.missingSlots).toEqual(["field-value-empty:primary_cta.href"]);
87
+ const bad = render("{{primary_cta.href}}", { url: "/p" });
88
+ expect(bad.missingSlots).toEqual(["field-value-malformed:primary_cta"]);
89
+ });
90
+
91
+ it("a path into a field of another kind is reported too", () => {
92
+ const r = renderTemplate({
93
+ html: "{{title.text}}",
94
+ fields: [{ name: "title", kind: "text" }],
95
+ contentValues: { title: "Hi" },
96
+ });
97
+ expect(r.html).toBe("{{title.text}}");
98
+ expect(r.missingSlots).toEqual(["field-path-unknown:title.text"]);
99
+ });
100
+
101
+ it("a dotted name of no field stays literal copy", () => {
102
+ const r = render("{{acme.version}}", { href: "/p" });
103
+ expect(r.html).toBe("{{acme.version}}");
104
+ expect(r.missingSlots).toEqual([]);
105
+ });
106
+
107
+ it("LINK_VALUE_KEYS are the paths a link value answers", () => {
108
+ const v = linkValue({ href: "/p" }, null);
109
+ if (v.kind !== "record") throw new Error("a link is a record");
110
+ for (const key of LINK_VALUE_KEYS) expect(v.get(key)).toBeDefined();
111
+ });
112
+ });
113
+
114
+ describe("#1433 fieldPathProblems", () => {
115
+ const FIELDS = [
116
+ { name: "cta", kind: "link" },
117
+ { name: "title", kind: "text" },
118
+ { name: "nav", kind: "list" },
119
+ ];
120
+
121
+ it("accepts what renders", () => {
122
+ const html =
123
+ '{{cta}}{{cta.href}}{{cta.target}}{{cta.title}}{{page.title}}{{site_text.x}}{{other.y}}{{#cta.target}}{{/cta.target}}{{#nav}}<a href="{{link.href}}">{{link.label}}</a>{{/nav}}';
124
+ expect(fieldPathProblems(html, FIELDS)).toEqual([]);
125
+ });
126
+
127
+ it("names a path no value can answer, with the form that works", () => {
128
+ const problems = fieldPathProblems("{{cta.label}} {{title.text}} {{nav.items}}", FIELDS);
129
+ expect(problems.map((p) => p.tag)).toEqual([
130
+ "{{cta.label}}",
131
+ "{{title.text}}",
132
+ "{{nav.items}}",
133
+ ]);
134
+ const message = describeFieldPathProblems(problems);
135
+ expect(message).toContain("{{cta.href}}");
136
+ expect(message).toContain("`cta_label`");
137
+ expect(message).toContain("{{title}}");
138
+ expect(message).toContain("{{#nav}}");
139
+ });
140
+
141
+ it("reads inside a scalar conditional, not inside a section of entries", () => {
142
+ expect(fieldPathProblems("{{#cta}}{{cta.label}}{{/cta}}", FIELDS)).toHaveLength(1);
143
+ expect(fieldPathProblems("{{#cta.href}}{{cta.label}}{{/cta.href}}", FIELDS)).toHaveLength(1);
144
+ expect(
145
+ fieldPathProblems("{{#page.terms.tags}}{{cta.label}}{{/page.terms.tags}}", FIELDS),
146
+ ).toEqual([]);
147
+ });
148
+ });
@@ -231,7 +231,7 @@ describe("lists — dot access and compound values", () => {
231
231
  it("a dotted key the value does not have stays raw and is reported", () => {
232
232
  const r = render("{{#menu}}{{link.nope}}{{/menu}}", [HEADER]);
233
233
  expect(r.html).toContain("{{link.nope}}");
234
- expect(r.missingSlots).toContain("field-not-declared:menu.link.nope");
234
+ expect(r.missingSlots).toContain("field-path-unknown:menu.link.nope");
235
235
  });
236
236
  });
237
237
 
@@ -23,7 +23,8 @@
23
23
  * {{>name}} — single nested module reference
24
24
  * (module field kind)
25
25
  * {{page.title}}, {{a.b}} — dot access (`page.*`, compound entry
26
- * values); inside a list entry the
26
+ * values, a `link` field's `href`,
27
+ * `target`, `title`); inside a list entry the
27
28
  * entry's keys, `{{>recurse}}`,
28
29
  * `{{>f}}` (embedded module) and the
29
30
  * system keys — see template-sections.ts
@@ -55,6 +56,12 @@
55
56
  * for a key no entry, enclosing entry or module field has, and
56
57
  * `list-context-unavailable:<field>` / `…:page` for a list rendered by a
57
58
  * caller that gave the engine no list context (never legitimate output).
59
+ * #1433: `field-path-unknown:<path>` for a dotted placeholder whose head
60
+ * exists and whose rest does not (`{{cta.label}}` on a link field),
61
+ * `field-value-empty:<path>` for a path into a `link` field with no value,
62
+ * `field-value-malformed:<field>` for a `link` value of no link shape.
63
+ * Unlike `field-not-declared` these stop a Stage: an unknown `{{name}}` can
64
+ * be literal copy, a broken path cannot.
58
65
  * Epic #724: `link-target-missing:page/<id>` / `…:media/<id>` for an
59
66
  * internal reference (`caelo:page/<id>`, `caelo:media/<id>`) whose
60
67
  * target does not exist, `link-resolver-unavailable:<kind>/<id>` for
@@ -87,9 +94,16 @@ import { type LinkResolver, resolveLinkRefsInHtml } from "./link-refs.js";
87
94
  import { type SourceDef, sourceDefSchema } from "./lists/list-type.js";
88
95
  import type { ListPaginationSettings } from "./lists/pagination.js";
89
96
  import type { ListHolder, ListPageContext } from "./lists/resolve.js";
97
+ import { parseLinkFieldValue } from "./lists/resolve-values.js";
90
98
  import { stripCdataGuards } from "./strip-cdata.js";
91
99
  import { renderSections } from "./template-sections.js";
92
100
 
101
+ export {
102
+ describeFieldPathProblems,
103
+ type FieldPathProblem,
104
+ fieldPathProblems,
105
+ } from "./template-sections.js";
106
+
93
107
  // Override Mustache's default HTML escape — module HTML substitutes
94
108
  // raw. The engine module is the only workspace importer of mustache,
95
109
  // so the singleton mutation is scoped in effect. Plan §2 risk #1: the
@@ -411,6 +425,19 @@ export function renderTemplate(input: RenderTemplateInput): RenderTemplateOutput
411
425
  if (SECTION_KINDS.has(f.kind) || f.kind === "module") continue;
412
426
  if (f.default !== undefined && f.default !== null) view[lower] = f.default;
413
427
  }
428
+ // A `{{{cta}}}` of a link field: the section pass answers `{{cta}}`, and
429
+ // a triple tag must not stringify the object either.
430
+ for (const f of input.fields) {
431
+ if (f.kind !== "link") continue;
432
+ const lower = f.name.toLowerCase();
433
+ const value = view[lower];
434
+ if (typeof value !== "object" || value === null) continue;
435
+ const link = parseLinkFieldValue(value);
436
+ if (link === null) continue;
437
+ // An object with no href is no value: it stays raw like any empty field.
438
+ if (link.href.length > 0) view[lower] = link.href;
439
+ else delete view[lower];
440
+ }
414
441
 
415
442
  // v0.11.1 (issue #76) — pre-populate four theme-asset substitutions
416
443
  // when the caller supplied `themeAssets`. `contentValues` already
@@ -540,6 +567,19 @@ export function shieldLiteralText(html: string, mkKey: (text: string) => string)
540
567
  });
541
568
  }
542
569
 
570
+ /**
571
+ * A marker of a dotted path its field cannot answer (#1433). The preview
572
+ * surfaces these and the Stage refuses them: unlike an unknown `{{name}}`,
573
+ * they are never literal copy.
574
+ */
575
+ export function isFieldPathMarker(marker: string): boolean {
576
+ return (
577
+ marker.startsWith("field-path-unknown:") ||
578
+ marker.startsWith("field-value-empty:") ||
579
+ marker.startsWith("field-value-malformed:")
580
+ );
581
+ }
582
+
543
583
  function renderModuleList(
544
584
  name: string,
545
585
  field: TemplateField,
@@ -4,7 +4,8 @@
4
4
  * Section pass of the template engine (`template-engine.ts`): every
5
5
  * `{{#name}}…{{/name}}` and `{{^name}}…{{/name}}`, list iteration with
6
6
  * entry scopes, `{{>recurse}}`, `{{>f}}` for an entry's embedded module,
7
- * dot access and `{{page.*}}` (epic #1107, `docs/lists.md` §8).
7
+ * dot access, a module `link` field's `{{f.href}}` and `{{page.*}}`
8
+ * (epic #1107, `docs/lists.md` §8).
8
9
  *
9
10
  * The template is tokenized ONCE and sections are matched with one stack
10
11
  * per name, so a children loop may repeat inside itself
@@ -22,6 +23,7 @@
22
23
  */
23
24
 
24
25
  import type { ListFieldSpec, ListHolder, ListPageContext } from "./lists/resolve.js";
26
+ import { LINK_VALUE_KEYS, linkValue, parseLinkFieldValue } from "./lists/resolve-values.js";
25
27
  import type { ScopeEntry, ScopeValue } from "./lists/scope.js";
26
28
 
27
29
  /** A field as the section pass needs it (subset of `TemplateField`). */
@@ -230,6 +232,35 @@ class SectionRenderer {
230
232
  return v;
231
233
  }
232
234
 
235
+ /**
236
+ * A module field of kind `link` as a scope value, the shape a link in a
237
+ * list entry has (#1433): `undefined` when `head` is no such field, a
238
+ * `failed` value when its stored value is no link.
239
+ */
240
+ private moduleLink(head: string): ScopeValue | undefined {
241
+ const field = this.env.fields.get(head);
242
+ if (field?.kind !== "link") return undefined;
243
+ const raw = Object.hasOwn(this.env.values, head) ? this.env.values[head] : field.default;
244
+ const link = parseLinkFieldValue(raw);
245
+ if (link === null) return { kind: "failed", marker: `field-value-malformed:${head}` };
246
+ return this.env.lists?.linkScope(link) ?? linkValue(link, null);
247
+ }
248
+
249
+ /** `name` (`f` or `f.key`) read from a module `link` field; `undefined` when it is none. */
250
+ private linkPath(name: string): ScopeValue | { missing: true } | undefined {
251
+ const [head, ...path] = name.toLowerCase().split(".");
252
+ const root = this.moduleLink(head as string);
253
+ if (root === undefined || root.kind !== "record" || path.length === 0) return root;
254
+ const key = path.length === 1 ? (path[0] as string) : "";
255
+ return root.get(key) ?? { missing: true };
256
+ }
257
+
258
+ /** True when `name`'s head is a module `link` field with no value. */
259
+ private linkUnset(name: string): boolean {
260
+ const v = this.moduleLink((name.split(".")[0] as string).toLowerCase());
261
+ return v?.kind === "record" && !v.present;
262
+ }
263
+
233
264
  private isModuleLevel(name: string): boolean {
234
265
  const lower = name.toLowerCase();
235
266
  return (
@@ -242,6 +273,22 @@ class SectionRenderer {
242
273
  return field.length > 0 ? `field-not-declared:${field}.${name}` : `field-not-declared:${name}`;
243
274
  }
244
275
 
276
+ /**
277
+ * The marker of a dotted path whose head exists and whose rest does not.
278
+ * Unlike an unknown `{{name}}`, which can be literal copy, this is a
279
+ * broken placeholder, so its marker stops a Stage (#1433). `page.*` and
280
+ * `site_text.*` keep theirs.
281
+ */
282
+ private unknownPath(name: string, st: RenderState): string {
283
+ if (isContextHead(name)) {
284
+ return this.env.lists === undefined
285
+ ? `list-context-unavailable:${contextHead(name)}`
286
+ : this.notDeclared(name, st);
287
+ }
288
+ const field = this.listField(st);
289
+ return `field-path-unknown:${field.length > 0 ? `${field}.` : ""}${name}`;
290
+ }
291
+
245
292
  // ── Plain tags ──
246
293
 
247
294
  private tag(t: Token, st: RenderState): string {
@@ -252,23 +299,25 @@ class SectionRenderer {
252
299
  return this.env.mkSentinel(st.dot);
253
300
  }
254
301
  const dotted = t.name.includes(".");
255
- if (st.chain.length === 0 && !dotted) return source;
256
- const v = this.lookup(t.name, st);
302
+ const linkField = this.env.fields.get(t.name.toLowerCase())?.kind === "link";
303
+ if (st.chain.length === 0 && !dotted && !linkField) return source;
304
+ const entryValue = this.lookup(t.name, st);
305
+ const v = entryValue ?? this.linkPath(t.name);
257
306
  if (v === undefined) {
258
307
  if (dotted) {
259
308
  const head = t.name.slice(0, t.name.indexOf("."));
260
- if (st.chain.length === 0 && !this.isModuleLevel(head)) return source;
309
+ if (this.isModuleLevel(head)) return this.raw(source, this.unknownPath(t.name, st));
310
+ if (st.chain.length === 0) return source;
261
311
  return this.raw(source, this.notDeclared(t.name, st));
262
312
  }
263
313
  if (this.isModuleLevel(t.name)) return source;
264
314
  return this.raw(source, this.notDeclared(t.name, st));
265
315
  }
266
- if ("missing" in v) {
267
- const marker =
268
- isContextHead(t.name) && this.env.lists === undefined
269
- ? `list-context-unavailable:${contextHead(t.name)}`
270
- : this.notDeclared(t.name, st);
271
- return this.raw(source, marker);
316
+ if ("missing" in v) return this.raw(source, this.unknownPath(t.name, st));
317
+ if (entryValue === undefined && this.linkUnset(t.name)) {
318
+ // A bare `{{f}}` with no value stays raw like any declared field; a
319
+ // path into it is a broken link in the page, so it stops a Stage.
320
+ return dotted ? this.raw(source, `field-value-empty:${t.name}`) : source;
272
321
  }
273
322
  return this.valueText(v, source, t.name, st);
274
323
  }
@@ -331,15 +380,9 @@ class SectionRenderer {
331
380
 
332
381
  private section(t: Token, block: Frame["block"], source: string, st: RenderState): string {
333
382
  const inverted = t.sigil === "^";
334
- const v = this.lookup(t.name, st);
383
+ const v = this.lookup(t.name, st) ?? (t.name.includes(".") ? this.linkPath(t.name) : undefined);
335
384
  if (v !== undefined) {
336
- if ("missing" in v) {
337
- const marker =
338
- isContextHead(t.name) && this.env.lists === undefined
339
- ? `list-context-unavailable:${contextHead(t.name)}`
340
- : this.notDeclared(t.name, st);
341
- return this.raw(source, marker);
342
- }
385
+ if ("missing" in v) return this.raw(source, this.unknownPath(t.name, st));
343
386
  return this.scopeSection(v, t.name, inverted, block, source, st);
344
387
  }
345
388
  if (t.name.includes(".")) return this.raw(source, this.notDeclared(t.name, st));
@@ -420,9 +463,15 @@ class SectionRenderer {
420
463
  // value, dropped when empty — never a kind-mismatch, which used to
421
464
  // silently drop real scalar content. `{{.}}` / `{{item}}` inside it
422
465
  // read the scalar. An empty conditional is intentional, not missing.
423
- const present = isPresentSectionValue(raw);
466
+ const link = field.kind === "link" ? this.moduleLink(name) : undefined;
467
+ if (link?.kind === "failed") return this.raw(source, link.marker);
468
+ const present = link?.kind === "record" ? link.present : isPresentSectionValue(raw);
424
469
  if (present === inverted) return "";
425
- const dot = present ? scalarSectionString(raw) : "";
470
+ const dot = !present
471
+ ? ""
472
+ : link?.kind === "record"
473
+ ? (link.text ?? "")
474
+ : scalarSectionString(raw);
426
475
  return this.body(block, st, dot.length > 0 ? dot : st.dot);
427
476
  }
428
477
 
@@ -475,6 +524,73 @@ function scalarSectionString(raw: unknown): string {
475
524
  return "";
476
525
  }
477
526
 
527
+ /** A dotted placeholder a module's fields cannot answer ({@link fieldPathProblems}). */
528
+ export interface FieldPathProblem {
529
+ /** The tag as written, e.g. `{{primary_cta.label}}`. */
530
+ readonly tag: string;
531
+ readonly field: string;
532
+ readonly kind: string;
533
+ }
534
+
535
+ /**
536
+ * The dotted placeholders in `html` whose head is a field of this module
537
+ * and whose path that field cannot answer: every path into a field other
538
+ * than `link`, and a `link` path past {@link LINK_VALUE_KEYS}. The inside of
539
+ * a list section is skipped: its keys belong to the entries, which only the
540
+ * render knows. Read at write time so a broken placeholder is refused where
541
+ * it is authored, instead of surfacing at the Stage.
542
+ */
543
+ export function fieldPathProblems(
544
+ html: string,
545
+ fields: readonly { readonly name: string; readonly kind?: string }[],
546
+ ): FieldPathProblem[] {
547
+ const byName = new Map(fields.map((f) => [f.name, f.kind ?? "text"]));
548
+ const tokens = tokenize(html);
549
+ const pairs = matchSections(tokens);
550
+ const out: FieldPathProblem[] = [];
551
+ for (let i = 0; i < tokens.length; i += 1) {
552
+ const t = tokens[i] as Token;
553
+ const close = pairs.get(i);
554
+ if (close !== undefined) {
555
+ // A section over no field of this module (a plugin list source,
556
+ // `page.terms.*`) opens entries too.
557
+ const kind = byName.get((t.name.split(".")[0] as string).toLowerCase());
558
+ if (kind === undefined || (ENTRY_SCOPE_KINDS.has(kind) && !t.name.includes("."))) {
559
+ i = close;
560
+ continue;
561
+ }
562
+ }
563
+ if (t.sigil === "/" || t.sigil === ">" || !t.name.includes(".") || isContextHead(t.name)) {
564
+ continue;
565
+ }
566
+ const [head, ...path] = t.name.toLowerCase().split(".") as [string, ...string[]];
567
+ const kind = byName.get(head);
568
+ if (kind === undefined) continue;
569
+ const linkPath =
570
+ path.length === 1 && (LINK_VALUE_KEYS as readonly string[]).includes(path[0] as string);
571
+ if (kind === "link" && linkPath) continue;
572
+ out.push({ tag: html.slice(t.start, t.end), field: head, kind });
573
+ }
574
+ return out;
575
+ }
576
+
577
+ /** The field kinds whose section opens entries, with keys of their own. */
578
+ const ENTRY_SCOPE_KINDS: ReadonlySet<string> = new Set(["list", "module-list"]);
579
+
580
+ /** What the author does about `problems` (non-empty): names the forms that work. */
581
+ export function describeFieldPathProblems(problems: readonly FieldPathProblem[]): string {
582
+ const lines = problems.map(({ tag, field, kind }) => {
583
+ if (kind === "link") {
584
+ return `${tag}: \`${field}\` is a link field with the paths href, target and title. Use {{${field}}} or {{${field}.href}} for the URL; text beside the link, like its label, is a text field of its own (\`${field}_label\`).`;
585
+ }
586
+ if (ENTRY_SCOPE_KINDS.has(kind)) {
587
+ return `${tag}: \`${field}\` is a ${kind} field. Iterate it with {{#${field}}}…{{/${field}}} and use the entry's keys inside.`;
588
+ }
589
+ return `${tag}: \`${field}\` is a ${kind} field and has no paths. Use {{${field}}}.`;
590
+ });
591
+ return `Placeholder(s) this module's fields cannot answer, nothing was saved. ${lines.join(" ")}`;
592
+ }
593
+
478
594
  /** The attribute a rendered list entry's root element carries (`docs/lists.md` §13). */
479
595
  export const LIST_ITEM_ATTRIBUTE = "data-caelo-list-item";
480
596
 
package/src/version.ts CHANGED
@@ -22,7 +22,7 @@
22
22
  * follow standard SemVer.
23
23
  */
24
24
 
25
- export const CAELO_VERSION = "0.11.21";
25
+ export const CAELO_VERSION = "0.12.1";
26
26
 
27
27
  /**
28
28
  * Deprecated alias for back-compat — early P17 work spelled this