@nuasite/cms-core 0.53.0 → 0.55.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 (42) hide show
  1. package/dist/types/asset-paths.d.ts +28 -0
  2. package/dist/types/asset-paths.d.ts.map +1 -0
  3. package/dist/types/check-entries.d.ts +50 -0
  4. package/dist/types/check-entries.d.ts.map +1 -0
  5. package/dist/types/check-live.d.ts +25 -0
  6. package/dist/types/check-live.d.ts.map +1 -0
  7. package/dist/types/check-shape.d.ts +28 -0
  8. package/dist/types/check-shape.d.ts.map +1 -0
  9. package/dist/types/check-write.d.ts +35 -0
  10. package/dist/types/check-write.d.ts.map +1 -0
  11. package/dist/types/check.d.ts +18 -1
  12. package/dist/types/check.d.ts.map +1 -1
  13. package/dist/types/collection-scanner.d.ts.map +1 -1
  14. package/dist/types/content-config-ast.d.ts +7 -1
  15. package/dist/types/content-config-ast.d.ts.map +1 -1
  16. package/dist/types/editor-write-model.d.ts +48 -0
  17. package/dist/types/editor-write-model.d.ts.map +1 -0
  18. package/dist/types/handlers/entry-ops.d.ts.map +1 -1
  19. package/dist/types/index.d.ts +10 -2
  20. package/dist/types/index.d.ts.map +1 -1
  21. package/dist/types/schema-port.d.ts +43 -0
  22. package/dist/types/schema-port.d.ts.map +1 -0
  23. package/dist/types/schema-probe.d.ts +53 -0
  24. package/dist/types/schema-probe.d.ts.map +1 -0
  25. package/dist/types/shared.d.ts +34 -10
  26. package/dist/types/shared.d.ts.map +1 -1
  27. package/dist/types/tsconfig.tsbuildinfo +1 -1
  28. package/package.json +7 -2
  29. package/src/asset-paths.ts +54 -0
  30. package/src/check-entries.ts +120 -0
  31. package/src/check-live.ts +61 -0
  32. package/src/check-shape.ts +137 -0
  33. package/src/check-write.ts +280 -0
  34. package/src/check.ts +192 -62
  35. package/src/collection-scanner.ts +14 -0
  36. package/src/content-config-ast.ts +301 -18
  37. package/src/editor-write-model.ts +82 -0
  38. package/src/handlers/entry-ops.ts +153 -73
  39. package/src/index.ts +41 -2
  40. package/src/schema-port.ts +46 -0
  41. package/src/schema-probe.ts +133 -0
  42. package/src/shared.ts +60 -18
package/src/check.ts CHANGED
@@ -12,10 +12,15 @@
12
12
  * `astro sync` already provides.
13
13
  */
14
14
 
15
- import path from 'node:path'
16
- import yaml from 'yaml'
15
+ import { assetBaseDir, resolveAssetCandidates } from './asset-paths'
16
+ import { isPlainObject, loadCollections, type LoadedEntry } from './check-entries'
17
+ import { checkAgainstSchemas } from './check-live'
18
+ import { checkFieldShapes } from './check-shape'
19
+ import { checkEditorWrites } from './check-write'
17
20
  import { parseContentConfig, type ParsedCollection, type ParsedField } from './content-config-ast'
18
21
  import type { CmsFileSystem } from './fs/types'
22
+ import { type LiveSchemas, schemaFor } from './schema-port'
23
+ import { computePathnameFromSpec } from './shared'
19
24
 
20
25
  export type CheckSeverity = 'error' | 'warning'
21
26
 
@@ -30,6 +35,14 @@ export interface CheckFinding {
30
35
  column?: number
31
36
  field?: string
32
37
  message: string
38
+ /**
39
+ * What to change to make the finding go away, when there is a specific answer.
40
+ *
41
+ * Separate from `message` because it is a different kind of claim: the message states
42
+ * what the checker observed, the hint proposes an edit it cannot verify. Rules add one
43
+ * only where the remedy follows from the evidence — never as a restatement.
44
+ */
45
+ hint?: string
33
46
  }
34
47
 
35
48
  export interface CheckReport {
@@ -38,14 +51,6 @@ export interface CheckReport {
38
51
  entries: number
39
52
  }
40
53
 
41
- const DATA_EXTENSIONS = new Set(['.json', '.yaml', '.yml'])
42
-
43
- /** `./content/articles` and `content/articles/` both mean the same directory. */
44
- const normalizeBase = (base: string): string => path.normalize(base).replace(/^\.\//, '').replace(/\/+$/, '')
45
-
46
- /** The id Astro's `glob()` loader derives from a file, and therefore what a `reference()` must hold. */
47
- const entryStem = (file: string): string => path.basename(file).replace(/\.(md|mdx|json|ya?ml)$/, '')
48
-
49
54
  const typeName = (value: unknown): string => {
50
55
  if (value === null) return 'null'
51
56
  if (Array.isArray(value)) return 'array'
@@ -53,10 +58,6 @@ const typeName = (value: unknown): string => {
53
58
  return typeof value
54
59
  }
55
60
 
56
- function isPlainObject(value: unknown): value is Record<string, unknown> {
57
- return typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date)
58
- }
59
-
60
61
  /** Whether a value satisfies a field's declared type. `null` means "no opinion". */
61
62
  function typeMismatch(field: ParsedField, value: unknown): string | null {
62
63
  switch (field.type) {
@@ -97,36 +98,124 @@ function typeMismatch(field: ParsedField, value: unknown): string | null {
97
98
  }
98
99
  }
99
100
 
100
- async function collectEntryFiles(fs: CmsFileSystem, collection: ParsedCollection, base: string): Promise<string[]> {
101
- const pattern = collection.loaderPattern ?? '**/*.{md,mdx,json,yaml,yml}'
102
- const files = await fs.glob(`${base}/${pattern}`)
103
- return files.filter(file => !path.basename(file).startsWith('_')).sort()
101
+ /**
102
+ * The on-disk path an `image` value names, or `null` when it names none: the s3/contember
103
+ * media adapters store absolute URLs, and a `~/…`/`@…` value is a Vite alias, which Astro
104
+ * hands to Vite's resolver (see `astro/src/content/utils.ts`) and this cannot follow.
105
+ * A cache-busting `?v=2`/`#frag` is trimmed off rather than discarding the whole value.
106
+ */
107
+ function projectAssetPath(value: string): string | null {
108
+ if (value === '' || value.startsWith('//')) return null
109
+ // A scheme — `https:`, `data:`, `file:`.
110
+ if (/^[a-z][a-z\d+\-.]*:/i.test(value)) return null
111
+ // A Vite alias or a `#imports` subpath — an import specifier, not a path.
112
+ if (/^[~@#]/.test(value)) return null
113
+ const withoutQuery = value.split(/[?#]/)[0] ?? ''
114
+ return withoutQuery === '' ? null : withoutQuery
104
115
  }
105
116
 
106
- function parseEntry(file: string, raw: string): { frontmatter: Record<string, unknown> } | { error: string } {
107
- const extension = path.extname(file)
108
- if (DATA_EXTENSIONS.has(extension)) {
109
- try {
110
- const parsed: unknown = extension === '.json' ? JSON.parse(raw) : yaml.parse(raw)
111
- // A data collection file may legitimately hold an array of entries; nothing to field-check then.
112
- return { frontmatter: isPlainObject(parsed) ? parsed : {} }
113
- } catch (error) {
114
- return { error: error instanceof Error ? error.message.split('\n')[0]! : String(error) }
117
+ /**
118
+ * Report `image` values pointing at no file, walking nested objects and object-array items
119
+ * the same way the field data is shaped. Resolution goes through `resolveAssetCandidates`
120
+ * with the entry's own directory, which is what `getEntryAsset` serves a relative value
121
+ * from — the check therefore looks exactly where serving the asset looks.
122
+ */
123
+ async function checkAssets(
124
+ fs: CmsFileSystem,
125
+ fields: ParsedField[],
126
+ data: Record<string, unknown>,
127
+ file: string,
128
+ prefix: string,
129
+ findings: CheckFinding[],
130
+ ): Promise<void> {
131
+ for (const field of fields) {
132
+ const value = data[field.name]
133
+ if (value === undefined || value === null) continue
134
+ const label = prefix === '' ? field.name : `${prefix}.${field.name}`
135
+
136
+ if (field.type === 'object' && field.fields && isPlainObject(value)) {
137
+ await checkAssets(fs, field.fields, value, file, label, findings)
138
+ continue
139
+ }
140
+
141
+ if (field.type === 'array' && field.itemType === 'object' && field.fields && Array.isArray(value)) {
142
+ for (const [index, item] of value.entries()) {
143
+ if (isPlainObject(item)) await checkAssets(fs, field.fields, item, file, `${label}[${index}]`, findings)
144
+ }
145
+ continue
146
+ }
147
+
148
+ if (field.type !== 'image' || typeof value !== 'string') continue
149
+ const assetPath = projectAssetPath(value)
150
+ if (assetPath === null) continue
151
+
152
+ const candidates = resolveAssetCandidates(assetBaseDir(file), assetPath)
153
+ // No candidates left means the path climbs above the project root — outside what this can judge.
154
+ if (candidates.length === 0) continue
155
+
156
+ let found = false
157
+ for (const candidate of candidates) {
158
+ if (await fs.exists(candidate)) {
159
+ found = true
160
+ break
161
+ }
115
162
  }
163
+ if (found) continue
164
+
165
+ findings.push({
166
+ severity: 'warning',
167
+ code: 'entry/missing-asset',
168
+ file,
169
+ field: label,
170
+ message: `${label}: "${value}" points at no file (tried ${candidates.join(', ')}).`,
171
+ })
116
172
  }
173
+ }
117
174
 
118
- const trimmed = raw.trimStart()
119
- if (!trimmed.startsWith('---')) return { frontmatter: {} }
120
- const lines = trimmed.split('\n')
121
- const end = lines.findIndex((line, index) => index > 0 && line.trimEnd() === '---')
122
- if (end === -1) return { error: 'frontmatter is never closed (missing the second `---`)' }
123
-
124
- try {
125
- const parsed: unknown = yaml.parse(lines.slice(1, end).join('\n').trim())
126
- return { frontmatter: isPlainObject(parsed) ? parsed : {} }
127
- } catch (error) {
128
- return { error: error instanceof Error ? error.message.split('\n')[0]! : String(error) }
175
+ /**
176
+ * Entries whose declarative `cms.pathname` rule resolves to a URL another entry already took —
177
+ * the later ones render over the first, so only one of them is reachable. A warning, not an
178
+ * error: this builds green and only goes wrong at render time.
179
+ *
180
+ * `collection-scanner.ts` warns about the same thing on the dev-server path; the duplication
181
+ * is deliberate, because this check must stay scanner-free.
182
+ */
183
+ function pathnameCollisions(collection: ParsedCollection, entries: LoadedEntry[]): CheckFinding[] {
184
+ // `fragment` needs no guard here — parsing already drops the `pathname` of a fragment collection.
185
+ if (!collection.pathname) return []
186
+
187
+ const findings: CheckFinding[] = []
188
+ const firstAt = new Map<string, LoadedEntry>()
189
+ for (const entry of entries) {
190
+ if (!entry.frontmatter) continue
191
+ const pathname = computePathnameFromSpec(collection.pathname, entry.frontmatter)
192
+ // An unresolved spec (a missing/uncoercible field) yields no URL, so there is nothing to collide.
193
+ if (pathname === undefined) continue
194
+
195
+ const first = firstAt.get(pathname)
196
+ if (!first) {
197
+ firstAt.set(pathname, entry)
198
+ continue
199
+ }
200
+ findings.push({
201
+ severity: 'warning',
202
+ code: 'entry/pathname-collision',
203
+ file: entry.file,
204
+ field: collection.name,
205
+ // The path, not the stem: bundle entries are all named `index`.
206
+ message: `The pathname rule maps this entry and ${first.file} to ${pathname} — they collide on one page.`,
207
+ })
129
208
  }
209
+ return findings
210
+ }
211
+
212
+ export interface CheckContentOptions {
213
+ /**
214
+ * The project's real collection schemas. Given these, the check also reports what the
215
+ * build would reject and what the editor's next write would break — see `check-live.ts`
216
+ * and `check-write.ts`. Absent, only the AST/data rules below run.
217
+ */
218
+ schemas?: LiveSchemas
130
219
  }
131
220
 
132
221
  /**
@@ -135,7 +224,7 @@ function parseEntry(file: string, raw: string): { frontmatter: Record<string, un
135
224
  * Errors are things that fail the build; warnings are things that pass it and then go wrong
136
225
  * at render time (a reference pointing at nothing is the documented example).
137
226
  */
138
- export async function checkContent(fs: CmsFileSystem): Promise<CheckReport> {
227
+ export async function checkContent(fs: CmsFileSystem, options: CheckContentOptions = {}): Promise<CheckReport> {
139
228
  const findings: CheckFinding[] = []
140
229
  const config = await parseContentConfig(fs, new Map())
141
230
 
@@ -149,36 +238,29 @@ export async function checkContent(fs: CmsFileSystem): Promise<CheckReport> {
149
238
  return { findings, collections: 0, entries: 0 }
150
239
  }
151
240
 
152
- // Resolve every collection's files first: a reference can point at a collection checked later.
153
- const bases = new Map<string, string>()
154
- const files = new Map<string, string[]>()
241
+ // Read everything first: a reference can point at a collection checked later.
242
+ const collections = await loadCollections(fs, config)
155
243
  const stems = new Map<string, Set<string>>()
156
244
 
157
- for (const [name, collection] of config) {
158
- const base = normalizeBase(collection.loaderBase ?? `src/content/${name}`)
159
- bases.set(name, base)
160
- if (!(await fs.exists(base))) {
245
+ for (const [name, loaded] of collections) {
246
+ stems.set(name, new Set(loaded.entries.map(entry => entry.stem)))
247
+ if (!loaded.exists) {
161
248
  findings.push({
162
249
  severity: 'error',
163
250
  code: 'config/missing-dir',
164
251
  file: 'src/content.config.ts',
165
252
  field: name,
166
- message: `Collection "${name}" loads from ${base}/, which does not exist.`,
253
+ message: `Collection "${name}" loads from ${loaded.base}/, which does not exist.`,
167
254
  })
168
- files.set(name, [])
169
- stems.set(name, new Set())
170
255
  continue
171
256
  }
172
- const collectionFiles = await collectEntryFiles(fs, collection, base)
173
- files.set(name, collectionFiles)
174
- stems.set(name, new Set(collectionFiles.map(entryStem)))
175
- if (collectionFiles.length === 0) {
257
+ if (loaded.entries.length === 0) {
176
258
  findings.push({
177
259
  severity: 'warning',
178
260
  code: 'config/empty-collection',
179
- file: base,
261
+ file: loaded.base,
180
262
  field: name,
181
- message: `Collection "${name}" matched no entries under ${base}/.`,
263
+ message: `Collection "${name}" matched no entries under ${loaded.base}/.`,
182
264
  })
183
265
  }
184
266
  }
@@ -188,20 +270,35 @@ export async function checkContent(fs: CmsFileSystem): Promise<CheckReport> {
188
270
  for (const [name, collection] of config) {
189
271
  // A bare `reference()` carries no field type, so it has to be kept explicitly.
190
272
  const typedFields = collection.fields.filter(field => field.type !== undefined || field.required || field.reference)
273
+ const declared = new Set(collection.fields.map(field => field.name))
274
+ const loadedEntries = collections.get(name)?.entries ?? []
275
+ /**
276
+ * Whether the real schema is available to judge this collection's entries.
277
+ *
278
+ * When it is, `entry/missing-required` and `entry/field-type` stand down: both infer a rule
279
+ * from the config's *surface* and are wrong wherever the surface and the schema differ.
280
+ * `required` is only "no `.optional()` was visible" — a field schema wrapped in a helper call
281
+ * hides it. And a type name does not fix a type: `n.date()` is
282
+ * `z.preprocess(toISODate, z.string())` with no validation, so `date: ''` is legal content
283
+ * that this rule called a broken date. Both produced build-failing errors on production sites
284
+ * that build. `entry/schema-rejected` answers properly, and `cms/required-drift` reports the
285
+ * disagreement itself, once, against the config rather than once per entry.
286
+ */
287
+ const schemaJudgesEntries = options.schemas !== undefined && schemaFor(options.schemas, name) !== undefined
191
288
 
192
- for (const file of files.get(name) ?? []) {
289
+ for (const entry of loadedEntries) {
193
290
  entries++
194
- const parsed = parseEntry(file, await fs.readFile(file))
195
- if ('error' in parsed) {
196
- findings.push({ severity: 'error', code: 'entry/syntax', file, message: `Frontmatter does not parse: ${parsed.error}` })
291
+ const file = entry.file
292
+ if (entry.frontmatter === undefined) {
293
+ findings.push({ severity: 'error', code: 'entry/syntax', file, message: `Frontmatter does not parse: ${entry.parseError}` })
197
294
  continue
198
295
  }
199
296
 
200
297
  for (const field of typedFields) {
201
- const value = parsed.frontmatter[field.name]
298
+ const value = entry.frontmatter[field.name]
202
299
 
203
300
  if (value === undefined || value === null) {
204
- if (field.required) {
301
+ if (field.required && !schemaJudgesEntries) {
205
302
  findings.push({
206
303
  severity: 'error',
207
304
  code: 'entry/missing-required',
@@ -213,7 +310,7 @@ export async function checkContent(fs: CmsFileSystem): Promise<CheckReport> {
213
310
  continue
214
311
  }
215
312
 
216
- const mismatch = field.type === undefined ? null : typeMismatch(field, value)
313
+ const mismatch = field.type === undefined || schemaJudgesEntries ? null : typeMismatch(field, value)
217
314
  if (mismatch) {
218
315
  findings.push({ severity: 'error', code: 'entry/field-type', file, field: field.name, message: `${field.name}: ${mismatch}` })
219
316
  continue
@@ -237,7 +334,34 @@ export async function checkContent(fs: CmsFileSystem): Promise<CheckReport> {
237
334
  })
238
335
  }
239
336
  }
337
+
338
+ await checkAssets(fs, collection.fields, entry.frontmatter, file, '', findings)
339
+
340
+ // Only a field list known to be complete can call a key unknown. It is short when the
341
+ // schema never unwrapped at all (renamed import, an unsupported wrapper) and when a
342
+ // spread or computed key was skipped — warning on every key of a valid project is the
343
+ // false positive this check exists to avoid.
344
+ if (declared.size > 0 && !collection.partialFields) {
345
+ for (const key of Object.keys(entry.frontmatter)) {
346
+ if (declared.has(key)) continue
347
+ findings.push({
348
+ severity: 'warning',
349
+ code: 'entry/unknown-key',
350
+ file,
351
+ field: key,
352
+ // Astro's schema strips what it does not declare, so the value is written and then never read.
353
+ message: `"${key}" is not a field of "${name}" — nothing reads it.`,
354
+ })
355
+ }
356
+ }
240
357
  }
358
+
359
+ findings.push(...pathnameCollisions(collection, loadedEntries))
360
+ }
361
+
362
+ if (options.schemas) {
363
+ const input = { config, collections, schemas: options.schemas }
364
+ findings.push(...await checkAgainstSchemas(input), ...await checkEditorWrites(input), ...await checkFieldShapes(input))
241
365
  }
242
366
 
243
367
  return { findings, collections: config.size, entries }
@@ -257,10 +381,16 @@ export function formatCheckReport(report: CheckReport): string {
257
381
  const lines: string[] = []
258
382
  for (const [file, findings] of byFile) {
259
383
  lines.push(file)
384
+ // One remedy usually covers a run of findings — five missing fields in one collection get the
385
+ // same sentence. Printed once per run, and reset per file so a block never opens without it.
386
+ let lastHint: string | undefined
260
387
  for (const finding of findings) {
261
388
  // eslint's shape: position, severity, message, rule. Familiar, and greppable by column.
262
389
  const at = finding.line === undefined ? '' : `${finding.line}:${finding.column ?? 0}`
263
390
  lines.push(` ${at.padEnd(8)}${(finding.severity === 'error' ? 'error' : 'warn').padEnd(6)} ${finding.message} [${finding.code}]`)
391
+ // Indented under its finding, so the proposal never reads as another observation.
392
+ if (finding.hint !== undefined && finding.hint !== lastHint) lines.push(` ${' '.repeat(14)}→ ${finding.hint}`)
393
+ lastHint = finding.hint
264
394
  }
265
395
  }
266
396
  return lines.join('\n')
@@ -681,6 +681,20 @@ function applyParsedFieldLayout(field: FieldDefinition, pf: ParsedField): void {
681
681
  if (layout.width !== undefined) field.width = layout.width
682
682
  if (layout.order !== undefined) field.order = layout.order
683
683
  if (layout.sidebar) field.position = 'sidebar'
684
+ if (layout.derivedFrom) {
685
+ // A declared derivation beats `detectDerivedHrefFields`: that pass runs after this one
686
+ // and skips any field already carrying `derivedFrom`, so the config wins by construction.
687
+ field.derivedFrom = layout.derivedFrom
688
+ // A derivation read out of the config is a statement, not the guess `detectDerivedHrefFields`
689
+ // makes from three sampled values — and only a statement is recomputed on write. Mark it so
690
+ // consumers reading the wire definition can tell the two apart; the guess never sets this.
691
+ field.derivedDeclared = true
692
+ if (layout.derivedTransform) field.derivedTransform = layout.derivedTransform
693
+ // The value is computed on every write, so hand-editing it makes no sense — hide it
694
+ // unless the author explicitly asked for the opposite.
695
+ field.hidden = layout.hidden ?? true
696
+ return
697
+ }
684
698
  if (layout.hidden) field.hidden = true
685
699
  }
686
700