@decocms/blocks 8.0.0 → 8.1.0-next.0

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 (175) hide show
  1. package/bin/deco.js +13 -0
  2. package/package.json +39 -3
  3. package/src/cms/applySectionConventions.ts +26 -2
  4. package/src/cms/blockSource.ts +37 -0
  5. package/src/cms/client.ts +5 -0
  6. package/src/cms/deferredTrigger.ts +58 -0
  7. package/src/cms/draftSource.ts +171 -57
  8. package/src/cms/index.ts +32 -3
  9. package/src/cms/loader.ts +318 -59
  10. package/src/cms/registry.ts +22 -0
  11. package/src/cms/renderJson.ts +179 -0
  12. package/src/cms/resolve.ts +396 -95
  13. package/src/cms/schema.ts +9 -5
  14. package/src/cms/sectionLoaders.ts +106 -56
  15. package/src/hooks/Image.tsx +70 -6
  16. package/src/hooks/LiveControls.tsx +30 -8
  17. package/src/hooks/Stats.tsx +134 -0
  18. package/src/hooks/index.ts +5 -0
  19. package/src/hooks/useLoadMore.ts +100 -0
  20. package/src/index.ts +37 -0
  21. package/src/middleware/observability.ts +173 -16
  22. package/src/preview/DraftPreviewBadge.tsx +306 -0
  23. package/src/preview/decoMark.ts +11 -0
  24. package/src/preview/index.ts +8 -0
  25. package/src/protocol/assets.ts +124 -0
  26. package/src/protocol/canonical.ts +7 -0
  27. package/src/protocol/ciphertext.ts +6 -0
  28. package/src/protocol/client.ts +170 -0
  29. package/src/protocol/conformance/cases/assets.ts +81 -0
  30. package/src/protocol/conformance/cases/guards.ts +314 -0
  31. package/src/protocol/conformance/cases/reads.ts +168 -0
  32. package/src/protocol/conformance/cases/types.ts +9 -0
  33. package/src/protocol/conformance/cases/wire.ts +138 -0
  34. package/src/protocol/conformance/cases/writes.ts +345 -0
  35. package/src/protocol/conformance/contentHashFixtures.ts +79 -0
  36. package/src/protocol/conformance/context.ts +222 -0
  37. package/src/protocol/conformance/index.ts +140 -0
  38. package/src/protocol/errors.ts +142 -0
  39. package/src/protocol/index.ts +39 -0
  40. package/src/protocol/keys.ts +279 -0
  41. package/src/protocol/params.ts +67 -0
  42. package/src/protocol/secrets.ts +231 -0
  43. package/src/protocol/server/assets.ts +119 -0
  44. package/src/protocol/server/auth.ts +49 -0
  45. package/src/protocol/server/bodyCache.ts +84 -0
  46. package/src/protocol/server/content.ts +175 -0
  47. package/src/protocol/server/core.ts +112 -0
  48. package/src/protocol/server/handler.ts +102 -0
  49. package/src/protocol/server/http.ts +139 -0
  50. package/src/protocol/server/index.ts +11 -0
  51. package/src/protocol/server/methods/apply.ts +341 -0
  52. package/src/protocol/server/methods/read.ts +156 -0
  53. package/src/protocol/server/rpc.ts +136 -0
  54. package/src/protocol/storage/fs/hash.ts +21 -0
  55. package/src/protocol/storage/fs/index.ts +338 -0
  56. package/src/protocol/storage/fs/lock.ts +68 -0
  57. package/src/protocol/storage/fs/transaction.ts +183 -0
  58. package/src/protocol/storage/fs/unsupported.ts +15 -0
  59. package/src/protocol/storage/memory.ts +238 -0
  60. package/src/protocol/storage.ts +182 -0
  61. package/src/protocol/types.ts +172 -0
  62. package/src/sdk/abTesting.ts +60 -3
  63. package/src/sdk/analytics.ts +72 -2
  64. package/src/sdk/cacheHeaders.ts +210 -10
  65. package/src/sdk/cacheStorage.ts +287 -0
  66. package/src/sdk/cachedLoader.ts +143 -90
  67. package/src/sdk/crypto.ts +16 -2
  68. package/src/sdk/deepOmit.ts +52 -0
  69. package/src/sdk/encoding.ts +2 -5
  70. package/src/sdk/experiments.ts +314 -0
  71. package/src/sdk/fetchCache.ts +269 -0
  72. package/src/sdk/fetchTimeout.ts +58 -0
  73. package/src/sdk/flags.ts +38 -8
  74. package/src/sdk/index.ts +7 -0
  75. package/src/sdk/instrumentedFetch.ts +25 -2
  76. package/src/sdk/nonce.ts +46 -0
  77. package/src/sdk/normalizeUrls.ts +2 -2
  78. package/src/sdk/observability.ts +8 -1
  79. package/src/sdk/otel.ts +131 -25
  80. package/src/sdk/otelHttpLog.ts +4 -4
  81. package/src/sdk/otelHttpMeter.ts +39 -13
  82. package/src/sdk/otelHttpTracer.ts +4 -4
  83. package/src/sdk/redirects.ts +113 -5
  84. package/src/sdk/responseCache.ts +82 -0
  85. package/src/sdk/urlUtils.ts +49 -0
  86. package/src/sdk/useSuggestions.ts +1 -1
  87. package/src/v8/analytics.ts +50 -0
  88. package/src/v8/background.ts +107 -0
  89. package/src/v8/builtins/data.ts +23 -0
  90. package/src/v8/builtins/index.ts +26 -0
  91. package/src/v8/builtins/lazy.ts +23 -0
  92. package/src/v8/builtins/legacy.ts +65 -0
  93. package/src/v8/builtins/matchers.ts +31 -0
  94. package/src/v8/builtins/multivariate.ts +25 -0
  95. package/src/v8/builtins/secret.ts +82 -0
  96. package/src/v8/canonical.ts +117 -0
  97. package/src/v8/ciphertext.ts +158 -0
  98. package/src/v8/cli/builtins.ts +20 -0
  99. package/src/v8/cli/check/index.ts +774 -0
  100. package/src/v8/cli/check/messages.ts +168 -0
  101. package/src/v8/cli/content.ts +287 -0
  102. package/src/v8/cli/index.ts +17 -0
  103. package/src/v8/cli/log.ts +18 -0
  104. package/src/v8/cli/main.ts +12 -0
  105. package/src/v8/cli/root.ts +66 -0
  106. package/src/v8/cli/run.ts +236 -0
  107. package/src/v8/cli/schema/builtinSchemas.ts +236 -0
  108. package/src/v8/cli/schema/generate.ts +507 -0
  109. package/src/v8/cli/schema/index.ts +63 -0
  110. package/src/v8/cli/schema/tsProgram.ts +497 -0
  111. package/src/v8/cli/schema/typeToSchema.ts +689 -0
  112. package/src/v8/cli/serve/server.ts +303 -0
  113. package/src/v8/cli/watch.ts +86 -0
  114. package/src/v8/client.ts +147 -0
  115. package/src/v8/cms.ts +237 -0
  116. package/src/v8/content.ts +195 -0
  117. package/src/v8/draft.ts +136 -0
  118. package/src/v8/errors.ts +59 -0
  119. package/src/v8/fetch.ts +152 -0
  120. package/src/v8/identity.ts +65 -0
  121. package/src/v8/index.ts +39 -0
  122. package/src/v8/json.ts +74 -0
  123. package/src/v8/matchRoute.ts +204 -0
  124. package/src/v8/remoteLoader.ts +282 -0
  125. package/src/v8/resolver.ts +278 -0
  126. package/src/v8/secrets.ts +17 -0
  127. package/src/v8/telemetry.ts +533 -0
  128. package/src/v8/types.ts +240 -0
  129. package/src/cms/blockSource.test.ts +0 -76
  130. package/src/cms/client.browserBundle.test.ts +0 -44
  131. package/src/cms/draftSource.test.ts +0 -343
  132. package/src/cms/layoutCacheRace.test.ts +0 -181
  133. package/src/cms/loadDecofileDirectory.test.ts +0 -109
  134. package/src/cms/loader.test.ts +0 -200
  135. package/src/cms/registry.test.ts +0 -110
  136. package/src/cms/resolve.test.ts +0 -980
  137. package/src/cms/schema.test.ts +0 -356
  138. package/src/cms/sectionLoaderContext.test.ts +0 -111
  139. package/src/cms/sectionLoaders.test.ts +0 -533
  140. package/src/cms/sectionMixins.test.ts +0 -167
  141. package/src/cms/stickyFlags.test.ts +0 -117
  142. package/src/flags/flags.test.ts +0 -148
  143. package/src/hooks/Image.test.ts +0 -100
  144. package/src/hooks/RenderSection.test.tsx +0 -81
  145. package/src/matchers/builtins.test.ts +0 -318
  146. package/src/matchers/override.test.ts +0 -205
  147. package/src/middleware/hydrationContext.test.ts +0 -61
  148. package/src/middleware/observability.test.ts +0 -242
  149. package/src/middleware/validateSection.test.ts +0 -147
  150. package/src/sdk/abTesting.test.ts +0 -326
  151. package/src/sdk/cacheHeaders.test.ts +0 -115
  152. package/src/sdk/cachedLoader.test.ts +0 -122
  153. package/src/sdk/cachedLoaderModule.test.ts +0 -209
  154. package/src/sdk/cn.test.ts +0 -34
  155. package/src/sdk/composite.test.ts +0 -121
  156. package/src/sdk/cookie.test.ts +0 -108
  157. package/src/sdk/encoding.test.ts +0 -71
  158. package/src/sdk/env.test.ts +0 -33
  159. package/src/sdk/flags.test.ts +0 -91
  160. package/src/sdk/http.test.ts +0 -71
  161. package/src/sdk/inflightTimeout.test.ts +0 -35
  162. package/src/sdk/instrumentedFetch.test.ts +0 -559
  163. package/src/sdk/invoke.test.ts +0 -115
  164. package/src/sdk/logger.test.ts +0 -432
  165. package/src/sdk/otel.test.ts +0 -526
  166. package/src/sdk/otelAdapters.test.ts +0 -89
  167. package/src/sdk/otelHttpLog.test.ts +0 -457
  168. package/src/sdk/otelHttpMeter.test.ts +0 -292
  169. package/src/sdk/otelHttpTracer.test.ts +0 -474
  170. package/src/sdk/requestContextStorage.browser.test.ts +0 -29
  171. package/src/sdk/urlRedaction.test.ts +0 -73
  172. package/src/sdk/useDevice.test.ts +0 -130
  173. package/src/sdk/useScript.test.ts +0 -128
  174. package/src/sdk/useSuggestions.test.ts +0 -230
  175. package/tsconfig.json +0 -7
@@ -0,0 +1,774 @@
1
+ /**
2
+ * `deco check`: validates every saved block against `.deco/schema.gen.json`,
3
+ * as both are on disk (spec: checking; internals › How deco check works). It
4
+ * writes nothing, generates no schema and loads no TypeScript.
5
+ *
6
+ * Validation is a walk over each saved block that dispatches on
7
+ * `__resolveType`, plus a JSON Schema validator (Ajv) for the props of each
8
+ * block it meets:
9
+ *
10
+ * - the walk resolves each name (block type, built-in, alias or saved block),
11
+ * checks that the block fits the field it sits in (by the field's list of
12
+ * functions whose return type fits it), and handles the structural blocks
13
+ * (`multivariate`, `lazy`, `secret`) and references;
14
+ * - Ajv checks one block's props at a time. Its schema is the generated one
15
+ * with every field also accepting any block, so nested blocks never show up
16
+ * as union noise in the parent: the walk checks them on their own, against
17
+ * their own type's schema.
18
+ */
19
+
20
+ import fs from "node:fs";
21
+ import Ajv, { type ValidateFunction } from "ajv";
22
+ import { isWellFormedCiphertext } from "../../../protocol/secrets";
23
+ import { isBlock, own } from "../../json";
24
+ import { findRouteConflicts } from "../../matchRoute";
25
+ import { isBuiltIn, storesPlainVariants } from "../builtins";
26
+ import { readSavedBlocks, type SavedBlocks } from "../content";
27
+ import { consoleReporter, type Reporter } from "../log";
28
+ import { CliError, decoPaths, findDecoRoot } from "../root";
29
+ import type { DecoMeta } from "../schema/generate";
30
+ import { SECTION_REF_KEY, toBase64 } from "../schema/typeToSchema";
31
+ import { BLOCK_DEF, joinPath, rewriteErrors } from "./messages";
32
+
33
+ export interface Problem {
34
+ /** The saved block's file, relative to the root: `.deco/blocks/HomePage.json`. */
35
+ file: string;
36
+ /** Where in the block, like `sections[2].title`; empty for the block itself. */
37
+ path: string;
38
+ message: string;
39
+ severity: "error" | "warning";
40
+ }
41
+
42
+ type Json = any;
43
+ const DOC_ID = "deco";
44
+
45
+ /** JSON-parsed objects only, so any non-array object is a plain one. */
46
+ function isObject(value: unknown): value is Record<string, Json> {
47
+ return typeof value === "object" && value !== null && !Array.isArray(value);
48
+ }
49
+
50
+ function resolveTypeEnum(schema: Json): string[] | null {
51
+ const prop = schema?.properties?.__resolveType;
52
+ return Array.isArray(prop?.enum) ? prop.enum : null;
53
+ }
54
+
55
+ /** A `lazy` block's shape inline in a field: the field is `Lazy<T>`. */
56
+ function isLazyShape(schema: Json): boolean {
57
+ const e = resolveTypeEnum(schema);
58
+ return !!e && e.length === 1 && e[0] === "lazy" && !!schema.properties.value;
59
+ }
60
+
61
+ /** A `secret` block's shape inline in a field: the field is `Secret`. */
62
+ function isSecretShape(schema: Json): boolean {
63
+ const e = resolveTypeEnum(schema);
64
+ return !!e && e.length === 1 && e[0] === "secret" && schema.format === "secret";
65
+ }
66
+
67
+ /** The definition key of a block type, if `schema` is a block type's definition. */
68
+ function blockDefinitionName(schema: Json): string | null {
69
+ const e = resolveTypeEnum(schema);
70
+ return e && e.length === 1 && typeof schema.title === "string" && !schema.format ? e[0] : null;
71
+ }
72
+
73
+ // ---------------------------------------------------------------------------
74
+ // The validation document: the schema, with every field also accepting a block
75
+ // ---------------------------------------------------------------------------
76
+
77
+ const BLOCK_REF = { $ref: `${DOC_ID}#/definitions/${BLOCK_DEF}` };
78
+
79
+ function absoluteRef(ref: string): string {
80
+ return ref.startsWith("#") ? `${DOC_ID}${ref}` : ref;
81
+ }
82
+
83
+ class ValidationDocument {
84
+ readonly doc: Json;
85
+ private readonly map = new WeakMap<object, object>();
86
+
87
+ /** Block types' definition keys: a ref to one only ever holds a block. */
88
+ private readonly blockKeys: Set<string>;
89
+
90
+ constructor(meta: DecoMeta) {
91
+ this.blockKeys = new Set(
92
+ Object.entries(meta.schema.definitions)
93
+ .filter(([, def]) => blockDefinitionName(def) !== null)
94
+ .map(([key]) => key),
95
+ );
96
+ const definitions: Record<string, Json> = {};
97
+ for (const [key, def] of Object.entries(meta.schema.definitions)) {
98
+ definitions[key] = this.transform(def, false, true);
99
+ }
100
+ definitions[BLOCK_DEF] = {
101
+ type: "object",
102
+ required: ["__resolveType"],
103
+ properties: { __resolveType: { type: "string" } },
104
+ };
105
+ const root: Record<string, Json> = {};
106
+ for (const [key, union] of Object.entries(meta.schema.root ?? {})) {
107
+ root[key] = this.transform(union, false, true);
108
+ }
109
+ this.doc = { $id: DOC_ID, definitions, root };
110
+ }
111
+
112
+ /** The transformed counterpart of a schema node of the generated schema. */
113
+ counterpart(node: object): object | undefined {
114
+ return this.map.get(node);
115
+ }
116
+
117
+ private transform(node: Json, wrap: boolean, top = false): Json {
118
+ if (!isObject(node)) return node;
119
+ // Fields that hold a structural block (Lazy<T>, Secret), as a field or a
120
+ // list item, are entirely the walk's job: it reports a plain value there
121
+ // and checks a block on its own. Ajv accepts anything in them.
122
+ if (!top && (isLazyShape(node) || isSecretShape(node))) {
123
+ // Still register the lazy value's form: the walk validates it.
124
+ if (isLazyShape(node)) this.transform(node.properties.value, true);
125
+ return {};
126
+ }
127
+ const copy: Record<string, Json> = {};
128
+ for (const [k, v] of Object.entries(node)) {
129
+ switch (k) {
130
+ case "$ref": {
131
+ // Only a block can fill a ref to a block type or a root union, and
132
+ // the walk checks blocks itself: here it's just "any block".
133
+ const ref = String(v);
134
+ const toBlock =
135
+ ref.startsWith("#/root/") ||
136
+ (ref.startsWith("#/definitions/") &&
137
+ this.blockKeys.has(ref.slice("#/definitions/".length)));
138
+ copy.$ref = toBlock ? BLOCK_REF.$ref : absoluteRef(ref);
139
+ break;
140
+ }
141
+ case "properties":
142
+ case "patternProperties":
143
+ copy[k] = Object.fromEntries(
144
+ Object.entries(v as Record<string, Json>).map(([p, s]) => [p, this.transform(s, true)]),
145
+ );
146
+ break;
147
+ case "items":
148
+ copy.items = Array.isArray(v)
149
+ ? v.map((s) => this.transform(s, true))
150
+ : this.transform(v, true);
151
+ break;
152
+ case "additionalProperties":
153
+ copy.additionalProperties = isObject(v) ? this.transform(v, true) : v;
154
+ break;
155
+ case "anyOf":
156
+ case "allOf":
157
+ case "oneOf":
158
+ copy[k] = (v as Json[]).map((s) => this.transform(s, false));
159
+ break;
160
+ case "not":
161
+ case "if":
162
+ case "then":
163
+ case "else":
164
+ copy[k] = this.transform(v, false);
165
+ break;
166
+ case "nullable":
167
+ case "inputSchema":
168
+ break;
169
+ default:
170
+ copy[k] = v;
171
+ }
172
+ }
173
+ // A field the code doesn't declare is an error: the site editor drops it
174
+ // on the next save. Keys starting with _, $ or @ are never fields.
175
+ if (
176
+ copy.properties &&
177
+ copy.additionalProperties === undefined &&
178
+ !copy.allOf &&
179
+ !copy.patternProperties
180
+ ) {
181
+ copy.additionalProperties = false;
182
+ copy.patternProperties = { "^[_$@]": {} };
183
+ }
184
+ this.map.set(node, copy);
185
+ let result: Json = copy;
186
+ if (node.nullable === true) result = { anyOf: [copy, { type: "null" }] };
187
+ if (wrap) result = { anyOf: [result, BLOCK_REF] };
188
+ return result;
189
+ }
190
+ }
191
+
192
+ // ---------------------------------------------------------------------------
193
+ // Formats
194
+ // ---------------------------------------------------------------------------
195
+
196
+ const DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
197
+ const TIME = /^\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?$/i;
198
+
199
+ function isDate(value: string): boolean {
200
+ const m = DATE.exec(value);
201
+ if (!m) return false;
202
+ const [year, month, day] = [Number(m[1]), Number(m[2]), Number(m[3])];
203
+ const d = new Date(Date.UTC(year, month - 1, day));
204
+ return d.getUTCFullYear() === year && d.getUTCMonth() === month - 1 && d.getUTCDate() === day;
205
+ }
206
+
207
+ /**
208
+ * The formats `deco check` enforces: the standard ones the schema's widgets
209
+ * write (`@format date`, `date-time`, `uri`). A date-time is a date, `T` (or a
210
+ * space) and a time whose seconds and zone are optional, since that is what
211
+ * the site editor's date-time picker saves. Every other format names a
212
+ * site-editor widget (`image-uri`, `color`, `rich-text`, …), not a rule, so it
213
+ * accepts any string.
214
+ */
215
+ const STANDARD_FORMATS: Record<string, (value: string) => boolean> = {
216
+ date: isDate,
217
+ "date-time": (value) => {
218
+ const at = value.search(/[Tt ]/);
219
+ return at === 10 && isDate(value.slice(0, 10)) && TIME.test(value.slice(11));
220
+ },
221
+ uri: (value) => /^[a-z][a-z0-9+.-]*:/i.test(value) && URL.canParse(value),
222
+ };
223
+
224
+ function formatsFor(doc: Json): Record<string, true | ((value: string) => boolean)> {
225
+ const formats: Record<string, true | ((value: string) => boolean)> = { ...STANDARD_FORMATS };
226
+ const seen = new Set<object>();
227
+ const visit = (node: Json) => {
228
+ if (node === null || typeof node !== "object" || seen.has(node)) return;
229
+ seen.add(node);
230
+ if (
231
+ !Array.isArray(node) &&
232
+ typeof node.format === "string" &&
233
+ !Object.hasOwn(formats, node.format)
234
+ ) {
235
+ formats[node.format] = true;
236
+ }
237
+ for (const value of Object.values(node)) visit(value);
238
+ };
239
+ visit(doc);
240
+ return formats;
241
+ }
242
+
243
+ const CIPHERTEXT_PROBLEM = "not a well-formed ciphertext (v1.<wrappedKey>.<iv>.<ciphertext>)";
244
+
245
+ // ---------------------------------------------------------------------------
246
+ // The checker
247
+ // ---------------------------------------------------------------------------
248
+
249
+ interface Context {
250
+ file: string;
251
+ problems: Problem[];
252
+ }
253
+
254
+ class Checker {
255
+ private readonly ajv: Ajv;
256
+ private readonly validation: ValidationDocument;
257
+ private readonly validators = new WeakMap<object, ValidateFunction>();
258
+ private readonly groupOf = new Map<string, string>();
259
+ private readonly aliases: Record<string, string>;
260
+ private readonly definitions: Record<string, Json>;
261
+
262
+ constructor(
263
+ private readonly meta: DecoMeta,
264
+ private readonly saved: SavedBlocks,
265
+ ) {
266
+ this.definitions = meta.schema?.definitions ?? {};
267
+ this.aliases = meta.aliases ?? {};
268
+ for (const [group, entries] of Object.entries(meta.manifest?.blocks ?? {})) {
269
+ for (const key of Object.keys(entries)) {
270
+ if (!this.groupOf.has(key)) this.groupOf.set(key, group);
271
+ }
272
+ }
273
+ this.validation = new ValidationDocument(meta);
274
+ this.ajv = new Ajv({
275
+ strict: false,
276
+ allErrors: true,
277
+ allowUnionTypes: true,
278
+ formats: formatsFor(this.validation.doc),
279
+ });
280
+ this.ajv.addSchema(this.validation.doc);
281
+ }
282
+
283
+ /** The block type a name calls, after the alias table; null if it isn't one. */
284
+ private canonicalType(name: string): string | null {
285
+ const target = own(this.aliases, name) ?? name;
286
+ if (this.groupOf.has(target) || this.groupOf.has(name)) return target;
287
+ return isBuiltIn(target) ? target : null;
288
+ }
289
+
290
+ private definitionOf(name: string): Json | undefined {
291
+ return (
292
+ own(this.definitions, toBase64(name)) ??
293
+ own(this.definitions, toBase64(own(this.aliases, name) ?? name))
294
+ );
295
+ }
296
+
297
+ private validatorFor(node: object): ValidateFunction | null {
298
+ const cached = this.validators.get(node);
299
+ if (cached) return cached;
300
+ const counterpart = this.validation.counterpart(node);
301
+ if (!counterpart) return null;
302
+ const validate = this.ajv.compile(counterpart);
303
+ this.validators.set(node, validate);
304
+ return validate;
305
+ }
306
+
307
+ private deref(schema: Json): Json {
308
+ let cur = schema;
309
+ for (let i = 0; i < 32 && isObject(cur) && typeof cur.$ref === "string"; i++) {
310
+ const ref: string = cur.$ref;
311
+ if (ref.startsWith("#/definitions/"))
312
+ cur = own(this.definitions, ref.slice("#/definitions/".length));
313
+ else if (ref.startsWith("#/root/"))
314
+ cur = own(this.meta.schema.root, ref.slice("#/root/".length));
315
+ else return cur;
316
+ }
317
+ return cur;
318
+ }
319
+
320
+ /** The block types a field takes, by name (canonical), or null for "any". */
321
+ private allowedTypes(field: Json, seen = new Set<Json>()): Set<string> {
322
+ const out = new Set<string>();
323
+ const visit = (node: Json) => {
324
+ if (!isObject(node) || seen.has(node)) return;
325
+ seen.add(node);
326
+ if (typeof node.$ref === "string") {
327
+ const ref: string = node.$ref;
328
+ if (ref.startsWith("#/root/")) {
329
+ const group = ref.slice("#/root/".length);
330
+ for (const key of Object.keys(own(this.meta.manifest.blocks, group) ?? {})) {
331
+ out.add(own(this.aliases, key) ?? key);
332
+ }
333
+ return;
334
+ }
335
+ if (ref === `#/definitions/${SECTION_REF_KEY}`) {
336
+ for (const key of Object.keys(this.meta.manifest.blocks.sections ?? {})) {
337
+ out.add(own(this.aliases, key) ?? key);
338
+ }
339
+ return;
340
+ }
341
+ const target = this.deref(node);
342
+ const name = blockDefinitionName(target);
343
+ if (name) out.add(own(this.aliases, name) ?? name);
344
+ return;
345
+ }
346
+ for (const branch of node.anyOf ?? []) visit(branch);
347
+ for (const branch of node.oneOf ?? []) visit(branch);
348
+ };
349
+ visit(field);
350
+ return out;
351
+ }
352
+
353
+ /** Follow saved references to the block type they end at. */
354
+ private underlyingType(
355
+ name: string,
356
+ chain: string[] = [],
357
+ ): { type: string | null; cycle?: string[] } {
358
+ if (chain.includes(name)) return { type: null, cycle: [...chain, name] };
359
+ const canonical = this.canonicalType(name);
360
+ if (canonical) return { type: canonical };
361
+ const entry = own(this.saved.blocks, name);
362
+ if (!entry || typeof entry.__resolveType !== "string") return { type: null };
363
+ return this.underlyingType(entry.__resolveType, [...chain, name]);
364
+ }
365
+
366
+ private report(
367
+ ctx: Context,
368
+ path: string,
369
+ message: string,
370
+ severity: Problem["severity"] = "error",
371
+ ) {
372
+ ctx.problems.push({ file: ctx.file, path, message, severity });
373
+ }
374
+
375
+ /** Does a block of type `type` fit `field`? Returns why not, or null. */
376
+ private fitProblem(type: string, field: Json | null): string | null {
377
+ if (field === null) return null;
378
+ if (type === "multivariate") return null; // any field can have variants
379
+ const resolved = this.deref(field);
380
+ if (type === "lazy") {
381
+ return isLazyShape(resolved) ? null : "a lazy block only fits a Lazy<T> field";
382
+ }
383
+ if (isLazyShape(resolved)) return "this field is Lazy<T>: wrap the value in a lazy block";
384
+ if (isSecretShape(resolved)) {
385
+ return type === "secret" ? null : "this field is a Secret: it takes a secret block";
386
+ }
387
+ const allowed = this.allowedTypes(field);
388
+ if (allowed.has(type)) return null;
389
+ if (allowed.size === 0) return "this field takes a plain value";
390
+ return "its function doesn't return this field's type";
391
+ }
392
+
393
+ /** Check one value that sits in `field` (null: anywhere, as a whole saved block). */
394
+ private checkValue(ctx: Context, value: Json, path: string, field: Json | null) {
395
+ if (isBlock(value)) {
396
+ this.checkBlock(ctx, value, path, field);
397
+ return;
398
+ }
399
+ if (field === null) return;
400
+ if (this.structuralProblem(ctx, value, path, field)) return;
401
+ const validate = this.validatorFor(field);
402
+ if (validate && !validate(value)) {
403
+ for (const e of rewriteErrors(validate.errors, value, path))
404
+ this.report(ctx, e.path, e.message);
405
+ }
406
+ this.walkNested(ctx, value, path, field);
407
+ }
408
+
409
+ /**
410
+ * A plain value in a field that only takes a structural block: `Lazy<T>`
411
+ * needs a `lazy` block and `Secret` a `secret` block, in a list item or a
412
+ * union member as much as in a field of its own. Reports it and returns
413
+ * true when the field is one of those (nothing else to check then).
414
+ */
415
+ private structuralProblem(ctx: Context, value: Json, path: string, field: Json): boolean {
416
+ const resolved = this.deref(field);
417
+ if (isLazyShape(resolved)) {
418
+ if (value !== undefined && value !== null) {
419
+ this.report(ctx, path, "this field is Lazy<T>: wrap the value in a lazy block");
420
+ }
421
+ return true;
422
+ }
423
+ if (isSecretShape(resolved)) {
424
+ if (value !== undefined && value !== null) {
425
+ this.report(ctx, path, "plain text in a Secret field: save it as a secret block");
426
+ }
427
+ return true;
428
+ }
429
+ return false;
430
+ }
431
+
432
+ /** Find the blocks nested in a plain value, with the field each one sits in. */
433
+ private walkNested(ctx: Context, value: Json, path: string, field: Json, depth = 0) {
434
+ if (depth > 64 || value === null || typeof value !== "object") return;
435
+ const schema = this.deref(field);
436
+ if (!isObject(schema)) return;
437
+ const branches: Json[] = [...(schema.anyOf ?? []), ...(schema.oneOf ?? [])];
438
+ if (branches.length > 0) {
439
+ const branch = branches
440
+ .map((b: Json) => this.deref(b))
441
+ .find(
442
+ (b: Json) =>
443
+ isObject(b) &&
444
+ !blockDefinitionName(b) &&
445
+ (Array.isArray(value) ? b.type === "array" : b.type === "object" || !!b.properties),
446
+ );
447
+ if (branch) this.walkNested(ctx, value, path, branch, depth + 1);
448
+ return;
449
+ }
450
+ if (Array.isArray(value)) {
451
+ if (isObject(schema.items)) {
452
+ value.forEach((item, i) => {
453
+ if (isBlock(item)) this.checkBlock(ctx, item, `${path}[${i}]`, schema.items);
454
+ else if (!this.structuralProblem(ctx, item, `${path}[${i}]`, schema.items)) {
455
+ this.walkNested(ctx, item, `${path}[${i}]`, schema.items, depth + 1);
456
+ }
457
+ });
458
+ }
459
+ return;
460
+ }
461
+ const props: Record<string, Json> = { ...(schema.properties ?? {}) };
462
+ for (const part of schema.allOf ?? []) Object.assign(props, this.deref(part)?.properties ?? {});
463
+ for (const [key, child] of Object.entries(value)) {
464
+ if (key === "__resolveType") continue;
465
+ const childField =
466
+ props[key] ??
467
+ (isObject(schema.additionalProperties) ? schema.additionalProperties : undefined);
468
+ if (!childField) continue;
469
+ const childPath = joinPath(path, `/${key.replace(/~/g, "~0").replace(/\//g, "~1")}`);
470
+ if (isBlock(child)) this.checkBlock(ctx, child, childPath, childField);
471
+ else if (!this.structuralProblem(ctx, child, childPath, childField)) {
472
+ this.walkNested(ctx, child, childPath, childField, depth + 1);
473
+ }
474
+ }
475
+ }
476
+
477
+ /** Check a block that sits in `field`, dispatching on its `__resolveType`. */
478
+ checkBlock(ctx: Context, block: Record<string, Json>, path: string, field: Json | null) {
479
+ const name: string = block.__resolveType;
480
+ const type = this.canonicalType(name);
481
+
482
+ if (type === null) {
483
+ if (!Object.hasOwn(this.saved.blocks, name)) {
484
+ this.report(ctx, path, `unknown block type "${name}"`);
485
+ return;
486
+ }
487
+ // A reference to a saved block: check what it resolves to against the field.
488
+ const { type: underlying, cycle } = this.underlyingType(name);
489
+ if (cycle) {
490
+ this.report(ctx, path, `references form a cycle: ${cycle.join(" → ")}`);
491
+ return;
492
+ }
493
+ if (underlying === null) return; // the saved block reports its own problem
494
+ const fit = this.fitProblem(underlying, field);
495
+ if (fit) {
496
+ this.report(
497
+ ctx,
498
+ path,
499
+ `saved block "${name}" (a "${underlying}") doesn't fit here: ${fit}`,
500
+ );
501
+ return;
502
+ }
503
+ // Overrides are merged over the saved arguments for this use.
504
+ const overrides = Object.keys(block).filter((k) => k !== "__resolveType");
505
+ if (overrides.length > 0) {
506
+ const target = this.saved.blocks[name];
507
+ const targetType = String(target.__resolveType);
508
+ const merged = { ...target, ...block, __resolveType: targetType };
509
+ if (this.canonicalType(targetType)) this.checkProps(ctx, merged, path, true);
510
+ }
511
+ return;
512
+ }
513
+
514
+ const fit = this.fitProblem(type, field);
515
+ if (fit) {
516
+ this.report(
517
+ ctx,
518
+ path,
519
+ type === "lazy" || fit.startsWith("this field is Lazy")
520
+ ? fit
521
+ : `"${type}" doesn't fit here: ${fit}`,
522
+ );
523
+ return;
524
+ }
525
+
526
+ switch (type) {
527
+ case "multivariate":
528
+ this.checkVariants(ctx, block, path, field);
529
+ return;
530
+ case "lazy": {
531
+ this.checkProps(ctx, block, path, false);
532
+ const inner = field === null ? null : (this.deref(field)?.properties?.value ?? null);
533
+ if ("value" in block) this.checkValue(ctx, block.value, joinPath(path, "/value"), inner);
534
+ return;
535
+ }
536
+ case "secret": {
537
+ this.checkProps(ctx, block, path, false);
538
+ if ("ciphertext" in block && !isWellFormedCiphertext(block.ciphertext)) {
539
+ this.report(ctx, joinPath(path, "/ciphertext"), CIPHERTEXT_PROBLEM);
540
+ }
541
+ return;
542
+ }
543
+ default:
544
+ this.checkProps(ctx, block, path, true);
545
+ }
546
+ }
547
+
548
+ /** Ajv over one block's own props, then the walk into the blocks nested in them. */
549
+ private checkProps(ctx: Context, block: Record<string, Json>, path: string, nested: boolean) {
550
+ const def = this.definitionOf(block.__resolveType);
551
+ if (!def) return;
552
+ const validate = this.validatorFor(def);
553
+ if (validate && !validate(block)) {
554
+ for (const e of rewriteErrors(validate.errors, block, path))
555
+ this.report(ctx, e.path, e.message);
556
+ }
557
+ if (nested) this.walkNested(ctx, block, path, def);
558
+ }
559
+
560
+ private checkVariants(
561
+ ctx: Context,
562
+ block: Record<string, Json>,
563
+ path: string,
564
+ field: Json | null,
565
+ ) {
566
+ const name: string = block.__resolveType;
567
+ const def = this.definitionOf(name);
568
+ // The block's own shape (a variants list, an experiment id), not its values.
569
+ if (def) {
570
+ const validate = this.validatorFor(def);
571
+ if (validate && !validate(block)) {
572
+ for (const e of rewriteErrors(validate.errors, block, path)) {
573
+ // Rules and values are checked below, each against its own field.
574
+ const variantPart = /(^|\.)variants\[\d+\]\.(rule|value)\b/.test(e.path);
575
+ const variantUnion =
576
+ /(^|\.)variants\[\d+\]$/.test(e.path) && e.message === "doesn't match any allowed form";
577
+ if (!variantPart && !variantUnion) this.report(ctx, e.path, e.message);
578
+ }
579
+ }
580
+ }
581
+ if (!Array.isArray(block.variants)) return;
582
+ const plainValues = storesPlainVariants(name);
583
+ // The field the variants stand in for; a saved multivariate block on its
584
+ // own takes its type's value form (under `multivariate`, a lazy block's).
585
+ let valueField: Json | null = field;
586
+ if (valueField === null) {
587
+ const declared = def?.properties?.variants?.items?.properties?.value ?? null;
588
+ const resolved = declared === null ? null : this.deref(declared);
589
+ valueField = !plainValues && isLazyShape(resolved) ? resolved.properties.value : declared;
590
+ }
591
+ const rule = { $ref: "#/root/matchers" };
592
+ let alwaysAt = -1;
593
+ block.variants.forEach((variant: Json, i: number) => {
594
+ const at = joinPath(path, `/variants/${i}`);
595
+ if (!isObject(variant)) return;
596
+ if (alwaysAt >= 0) {
597
+ this.report(
598
+ ctx,
599
+ at,
600
+ `can never be picked: variants[${alwaysAt}] has an always rule`,
601
+ "warning",
602
+ );
603
+ }
604
+ if ("rule" in variant) {
605
+ if (isBlock(variant.rule)) {
606
+ this.checkBlock(ctx, variant.rule, joinPath(at, "/rule"), rule);
607
+ if (alwaysAt < 0 && this.underlyingType(variant.rule.__resolveType).type === "always") {
608
+ alwaysAt = i;
609
+ }
610
+ } else {
611
+ this.report(
612
+ ctx,
613
+ joinPath(at, "/rule"),
614
+ "a rule must be a block whose function returns a boolean",
615
+ );
616
+ }
617
+ }
618
+ if (!("value" in variant)) return;
619
+ const valuePath = joinPath(at, "/value");
620
+ if (plainValues) {
621
+ this.checkValue(ctx, variant.value, valuePath, valueField);
622
+ } else if (isBlock(variant.value) && variant.value.__resolveType === "lazy") {
623
+ if ("value" in variant.value) {
624
+ this.checkValue(ctx, variant.value.value, joinPath(valuePath, "/value"), valueField);
625
+ }
626
+ } else {
627
+ this.report(ctx, valuePath, "a variant's value must be a lazy block");
628
+ }
629
+ });
630
+ }
631
+
632
+ /** Check every saved block, the names and the routes. */
633
+ run(): Problem[] {
634
+ const problems: Problem[] = [];
635
+ const names = Object.keys(this.saved.blocks).sort();
636
+ for (const name of names) {
637
+ const ctx: Context = { file: `.deco/blocks/${this.saved.files[name]}`, problems };
638
+ const entry = this.saved.blocks[name];
639
+
640
+ // Names share one registry with block types (spec: saved-blocks › Names).
641
+ if (own(this.aliases, name) !== undefined) {
642
+ this.report(ctx, "", `saved block "${name}" has the name of an alias`);
643
+ } else if (isBuiltIn(name)) {
644
+ this.report(ctx, "", `saved block "${name}" has the name of a built-in block`);
645
+ } else if (this.groupOf.has(name)) {
646
+ this.report(ctx, "", `saved block "${name}" has the name of a block type`);
647
+ }
648
+
649
+ if (!isBlock(entry)) {
650
+ this.report(ctx, "", "missing __resolveType: a saved block names the function it calls");
651
+ continue;
652
+ }
653
+ this.checkBlock(ctx, entry, "", null);
654
+ }
655
+ problems.push(...this.routeProblems());
656
+ return problems;
657
+ }
658
+
659
+ private routeProblems(): Problem[] {
660
+ type RouteEntry = { name: string; path: string };
661
+ const routes: RouteEntry[] = [];
662
+ const redirects: RouteEntry[] = [];
663
+ for (const name of Object.keys(this.saved.blocks).sort()) {
664
+ const entry = this.saved.blocks[name];
665
+ if (!isBlock(entry)) continue;
666
+ const { type } = this.underlyingType(entry.__resolveType);
667
+ if (type === null) continue;
668
+ const group = this.groupOf.get(type);
669
+ if (group === "redirects") {
670
+ const legacy = isObject(entry.redirect) ? entry.redirect.from : undefined;
671
+ const from = typeof entry.from === "string" ? entry.from : legacy;
672
+ if (typeof from === "string") redirects.push({ name, path: from });
673
+ } else if (group === "pages" && typeof entry.path === "string") {
674
+ routes.push({ name, path: entry.path });
675
+ }
676
+ }
677
+ const problems: Problem[] = [];
678
+ for (const [entries, what] of [
679
+ [routes, "path"],
680
+ [redirects, "from"],
681
+ ] as const) {
682
+ for (const { entry, other } of findRouteConflicts(entries)) {
683
+ problems.push({
684
+ file: `.deco/blocks/${this.saved.files[entry.name]}`,
685
+ path: what,
686
+ severity: "error",
687
+ message:
688
+ entry.path === other.path
689
+ ? `"${entry.path}" is also the ${what} of "${other.name}"`
690
+ : `"${entry.path}" matches the same URLs as "${other.path}" in "${other.name}"`,
691
+ });
692
+ }
693
+ }
694
+ return problems;
695
+ }
696
+ }
697
+
698
+ /** Check saved blocks against a schema. Pure: no filesystem. */
699
+ export function checkContent(meta: DecoMeta, saved: SavedBlocks): Problem[] {
700
+ const problems: Problem[] = saved.diagnostics.map((d) => ({
701
+ file: `.deco/blocks/${d.file}`,
702
+ path: "",
703
+ message: d.message,
704
+ severity: d.severity,
705
+ }));
706
+ problems.push(...new Checker(meta, saved).run());
707
+ const seen = new Set<string>();
708
+ return problems.filter((p) => {
709
+ const key = `${p.file}\0${p.path}\0${p.message}\0${p.severity}`;
710
+ if (seen.has(key)) return false;
711
+ seen.add(key);
712
+ return true;
713
+ });
714
+ }
715
+
716
+ /** Print problems grouped per file, the format the docs show. */
717
+ export function formatProblems(problems: Problem[]): string {
718
+ const byFile = new Map<string, Problem[]>();
719
+ for (const p of problems) {
720
+ const list = byFile.get(p.file) ?? [];
721
+ list.push(p);
722
+ byFile.set(p.file, list);
723
+ }
724
+ const lines: string[] = [];
725
+ for (const file of [...byFile.keys()].sort()) {
726
+ lines.push(file);
727
+ for (const p of byFile.get(file)!) {
728
+ const prefix = p.severity === "warning" ? "warning: " : "";
729
+ lines.push(` ${prefix}${p.path ? `${p.path}: ` : ""}${p.message}`);
730
+ }
731
+ }
732
+ return lines.join("\n");
733
+ }
734
+
735
+ export interface CheckOptions {
736
+ root?: string;
737
+ cwd?: string;
738
+ reporter?: Reporter;
739
+ }
740
+
741
+ function readSchemaFile(file: string): DecoMeta {
742
+ let text: string;
743
+ try {
744
+ text = fs.readFileSync(file, "utf8");
745
+ } catch {
746
+ throw new CliError(`no ${file}; run deco schema first`);
747
+ }
748
+ try {
749
+ return JSON.parse(text) as DecoMeta;
750
+ } catch (error) {
751
+ throw new CliError(`${file}: invalid JSON: ${(error as Error).message}`);
752
+ }
753
+ }
754
+
755
+ /** `deco check`. Returns the exit code: 0 when everything fits (warnings aside), 1 otherwise. */
756
+ export function check(options: CheckOptions = {}): number {
757
+ const reporter = options.reporter ?? consoleReporter;
758
+ const paths = decoPaths(findDecoRoot(options));
759
+ const meta = readSchemaFile(paths.schema);
760
+ const saved = readSavedBlocks(paths.blocks);
761
+ const problems = checkContent(meta, saved);
762
+ const errors = problems.filter((p) => p.severity === "error").length;
763
+ const warnings = problems.length - errors;
764
+ if (problems.length > 0) {
765
+ const text = formatProblems(problems);
766
+ if (errors > 0) reporter.error(text);
767
+ else reporter.warn(text);
768
+ }
769
+ const count = Object.keys(saved.blocks).length;
770
+ const summary = `${count} saved block${count === 1 ? "" : "s"} checked: ${errors} error${errors === 1 ? "" : "s"}, ${warnings} warning${warnings === 1 ? "" : "s"}`;
771
+ if (errors > 0) reporter.error(summary);
772
+ else reporter.info(summary);
773
+ return errors > 0 ? 1 : 0;
774
+ }