@nuasite/cms 0.18.1 → 0.19.1

package/package.json

@@ -14,7 +14,7 @@
     "directory": "packages/astro-cms"
   },
   "license": "Apache-2.0",
-  "version": "0.18.1",
+  "version": "0.19.1",
   "module": "src/index.ts",
   "types": "src/index.ts",
   "type": "module",
@@ -32,19 +32,21 @@
     "yaml": "^2.8.3"
   },
   "devDependencies": {
-    "@milkdown/core": "^7.19.2",
-    "@milkdown/ctx": "^7.19.2",
-    "@milkdown/plugin-listener": "^7.19.2",
-    "@milkdown/preset-commonmark": "^7.19.2",
-    "@milkdown/preset-gfm": "^7.19.2",
-    "@milkdown/prose": "^7.19.2",
-    "@milkdown/utils": "^7.19.2",
+    "@milkdown/core": "^7.20.0",
+    "@milkdown/ctx": "^7.20.0",
+    "@milkdown/plugin-listener": "^7.20.0",
+    "@milkdown/preset-commonmark": "^7.20.0",
+    "@milkdown/preset-gfm": "^7.20.0",
+    "@milkdown/prose": "^7.20.0",
+    "@milkdown/transformer": "^7.20.0",
+    "@milkdown/utils": "^7.20.0",
+    "remark-mdx": "^3.1.0",
     "@preact/signals": "^2.9.0",
     "@tailwindcss/vite": "^4.2.2",
     "@types/bun": "1.3.11",
     "clsx": "^2.1.1",
-    "marked": "^17.0.5",
-    "preact": "^10.29.0",
+    "marked": "^17.0.6",
+    "preact": "^10.29.1",
     "prosemirror-commands": "^1.7.1",
     "prosemirror-inputrules": "^1.5.1",
     "prosemirror-keymap": "^1.2.3",
@@ -52,14 +54,14 @@
     "prosemirror-safari-ime-span": "^1.0.2",
     "prosemirror-schema-list": "^1.5.1",
     "prosemirror-state": "^1.4.4",
-    "prosemirror-transform": "^1.10.5",
-    "prosemirror-view": "^1.41.7",
+    "prosemirror-transform": "^1.12.0",
+    "prosemirror-view": "^1.41.8",
     "tailwind-merge": "^3.5.0"
   },
   "peerDependencies": {
-    "astro": "^6.1.1",
+    "astro": "6.1.3",
     "typescript": "^6.0.2",
-    "vite": "^8.0.3",
+    "vite": "^7.0.0",
     "@aws-sdk/client-s3": "^3.0.0"
   },
   "peerDependenciesMeta": {

package/src/build-processor.ts

@@ -21,6 +21,7 @@ import {
 	updateAttributeSources,
 	updateColorClassSources,
 } from './source-finder'
+import type { ComponentInstance } from './types'
 import type { CmsMarkerOptions, CollectionEntry } from './types'
 
 // Concurrency limit for parallel processing
@@ -215,7 +216,7 @@ async function parseComponentInvocations(
 async function detectEntrylessComponents(
 	pagePath: string,
 	root: ReturnType<typeof parse>,
-	components: Record<string, import('./types').ComponentInstance>,
+	components: Record<string, ComponentInstance>,
 	componentDirs: string[],
 	relPath: string,
 	idGenerator: () => string,
@@ -351,6 +352,8 @@ async function processFile(
 				: undefined,
 			// Pass SEO options
 			seo: config.seo,
+			// Pass collection definitions for resolving frontmatter text on listing pages
+			collectionDefinitions: manifestWriter.getCollectionDefinitions(),
 		},
 		idGenerator,
 	)

package/src/collection-scanner.ts

@@ -1,7 +1,8 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
-import { parse as parseYaml } from 'yaml'
+import { isMap, isPair, isScalar, parse as parseYaml, parseDocument } from 'yaml'
 import { getProjectRoot } from './config'
+import { slugifyHref } from './shared'
 import type { CollectionDefinition, CollectionEntryInfo, FieldDefinition, FieldType } from './types'
 
 /** Regex patterns for type inference */
@@ -15,6 +16,25 @@ const MAX_SELECT_OPTIONS = 10
 /** Minimum length for textarea detection */
 const TEXTAREA_MIN_LENGTH = 200
 
+/** Field names that default to sidebar position */
+const SIDEBAR_FIELD_NAMES = new Set([
+	'title',
+	'date',
+	'pubdate',
+	'publishdate',
+	'draft',
+	'image',
+	'featuredimage',
+	'cover',
+	'coverimage',
+	'thumbnail',
+	'author',
+])
+
+/** Directive pattern: # @position <value> or # @group <value> */
+/** Matches `@position <value>` or `@group <value>` in YAML comment text (# already stripped by parser) */
+const DIRECTIVE_PATTERN = /^\s*@(position|group)\s+(.+)$/
+
 /** Field names that should never be inferred as select (always free-text) */
 const FREE_TEXT_FIELD_NAMES = new Set([
 	'title',
@@ -40,14 +60,80 @@ interface FieldObservation {
 	totalEntries: number
 }
 
+const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---/
+
+function extractFrontmatterBlock(content: string): string | null {
+	const match = content.match(FRONTMATTER_PATTERN)
+	return match?.[1] ?? null
+}
+
+function parseFrontmatter(content: string): Record<string, unknown> | null {
+	const block = extractFrontmatterBlock(content)
+	if (!block) return null
+	return parseYaml(block) as Record<string, unknown> | null
+}
+
 /**
- * Parse YAML frontmatter from markdown content
+ * Parse @position and @group comment directives from raw YAML frontmatter.
+ * Uses the YAML AST which preserves comments via `commentBefore` on nodes.
  */
-function parseFrontmatter(content: string): Record<string, unknown> | null {
-	const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
-	if (!match?.[1]) return null
+function parseFieldDirectives(content: string): Record<string, { position?: 'sidebar' | 'header'; group?: string }> {
+	const block = extractFrontmatterBlock(content)
+	if (!block) return {}
+
+	const doc = parseDocument(block)
+	if (!isMap(doc.contents)) return {}
+
+	const result: Record<string, { position?: 'sidebar' | 'header'; group?: string }> = {}
+
+	for (const pair of doc.contents.items) {
+		if (!isPair(pair) || !isScalar(pair.key)) continue
+		const comment = (pair.key as any).commentBefore as string | undefined
+		if (!comment) continue
+
+		const directives: { position?: 'sidebar' | 'header'; group?: string } = {}
+		for (const line of comment.split('\n')) {
+			const match = line.trim().match(DIRECTIVE_PATTERN)
+			if (!match) continue
+			const [, dirKey, dirValue] = match
+			if (dirKey === 'position' && (dirValue === 'sidebar' || dirValue === 'header')) {
+				directives.position = dirValue
+			} else if (dirKey === 'group' && dirValue) {
+				directives.group = dirValue.trim()
+			}
+		}
+
+		if (directives.position || directives.group) {
+			result[String(pair.key.value)] = directives
+		}
+	}
+
+	return result
+}
+
+/**
+ * Assign default positions to fields based on field name heuristics,
+ * then overlay frontmatter comment directives.
+ */
+function assignFieldMetadata(
+	fields: FieldDefinition[],
+	directives: Record<string, { position?: 'sidebar' | 'header'; group?: string }>,
+): void {
+	for (const field of fields) {
+		// Scanner defaults: well-known fields go to sidebar
+		if (SIDEBAR_FIELD_NAMES.has(field.name.toLowerCase()) || field.type === 'image' || field.type === 'boolean') {
+			field.position = 'sidebar'
+		} else {
+			field.position = 'header'
+		}
 
-	return parseYaml(match[1]) as Record<string, unknown> | null
+		// Overlay frontmatter comment directives
+		const directive = directives[field.name]
+		if (directive) {
+			if (directive.position) field.position = directive.position
+			if (directive.group) field.group = directive.group
+		}
+	}
 }
 
 /**
@@ -167,6 +253,20 @@ function mergeFieldObservations(observations: FieldObservation[]): FieldDefiniti
 						field.options = uniqueItems.sort()
 					}
 				}
+
+				// Infer sub-field definitions for array-of-objects
+				if (itemType === 'object') {
+					const objectItems = allItems.filter(
+						(v): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v),
+					)
+					if (objectItems.length > 0) {
+						const subFieldMap = new Map<string, FieldObservation>()
+						for (const item of objectItems) {
+							collectFieldObservations(subFieldMap, item, objectItems.length)
+						}
+						field.fields = mergeFieldObservations(Array.from(subFieldMap.values()))
+					}
+				}
 			}
 		}
 
@@ -176,6 +276,51 @@ function mergeFieldObservations(observations: FieldObservation[]): FieldDefiniti
 	return fields
 }
 
+function collectFieldObservations(
+	fieldMap: Map<string, FieldObservation>,
+	data: Record<string, unknown>,
+	totalEntries: number,
+): void {
+	for (const [key, value] of Object.entries(data)) {
+		let obs = fieldMap.get(key)
+		if (!obs) {
+			obs = { name: key, values: [], presentCount: 0, totalEntries }
+			fieldMap.set(key, obs)
+		}
+		obs.values.push(value)
+		obs.presentCount++
+	}
+}
+
+function buildCollectionDefinition(
+	collectionName: string,
+	contentDir: string,
+	fieldMap: Map<string, FieldObservation>,
+	entryInfos: CollectionEntryInfo[],
+	entryCount: number,
+	extra: Partial<CollectionDefinition>,
+): CollectionDefinition {
+	for (const obs of fieldMap.values()) {
+		obs.totalEntries = entryCount
+	}
+
+	entryInfos.sort((a, b) => (a.title ?? a.slug).localeCompare(b.title ?? b.slug))
+
+	const fields = mergeFieldObservations(Array.from(fieldMap.values()))
+	const label = collectionName.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase())
+
+	return {
+		name: collectionName,
+		label,
+		path: path.join(contentDir, collectionName),
+		entryCount,
+		fields,
+		fileExtension: 'md',
+		entries: entryInfos,
+		...extra,
+	}
+}
+
 /**
  * Scan a single collection directory and infer its schema
  */
@@ -186,21 +331,30 @@ async function scanCollection(collectionPath: string, collectionName: string, co
 
 		if (markdownFiles.length === 0) return null
 
-		// Determine file extension (prefer md, use mdx if that's all we have)
 		const hasMd = markdownFiles.some(f => f.name.endsWith('.md'))
 		const fileExtension: 'md' | 'mdx' = hasMd ? 'md' : 'mdx'
 
-		// Collect field observations and entry info across all files
 		const fieldMap = new Map<string, FieldObservation>()
+		const allDirectives: Record<string, { position?: 'sidebar' | 'header'; group?: string }> = {}
 		const entryInfos: CollectionEntryInfo[] = []
 		let hasDraft = false
 
-		for (const file of markdownFiles) {
-			const filePath = path.join(collectionPath, file.name)
-			const content = await fs.readFile(filePath, 'utf-8')
+		const fileContents = await Promise.all(
+			markdownFiles.map(file => fs.readFile(path.join(collectionPath, file.name), 'utf-8')),
+		)
+
+		for (let i = 0; i < markdownFiles.length; i++) {
+			const file = markdownFiles[i]!
+			const content = fileContents[i]!
 			const frontmatter = parseFrontmatter(content)
 
-			// Collect entry info
+			const directives = parseFieldDirectives(content)
+			for (const [key, value] of Object.entries(directives)) {
+				if (!allDirectives[key]) {
+					allDirectives[key] = value
+				}
+			}
+
 			const slug = file.name.replace(/\.(md|mdx)$/, '')
 			const entryInfo: CollectionEntryInfo = {
 				slug,
@@ -213,61 +367,279 @@ async function scanCollection(collectionPath: string, collectionName: string, co
 				if (typeof frontmatter.draft === 'boolean' && frontmatter.draft) {
 					entryInfo.draft = true
 				}
+				entryInfo.data = frontmatter
 			}
 			entryInfos.push(entryInfo)
 
 			if (!frontmatter) continue
 
-			for (const [key, value] of Object.entries(frontmatter)) {
-				if (key === 'draft' && typeof value === 'boolean') {
-					hasDraft = true
+			if (frontmatter.draft === true) hasDraft = true
+			collectFieldObservations(fieldMap, frontmatter, markdownFiles.length)
+		}
+
+		const def = buildCollectionDefinition(collectionName, contentDir, fieldMap, entryInfos, markdownFiles.length, {
+			supportsDraft: hasDraft,
+			fileExtension,
+		})
+		assignFieldMetadata(def.fields, allDirectives)
+		return def
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Parse the Astro content config file to extract explicit reference() declarations.
+ * Returns a map: collectionName → { fieldName → { target, isArray } }
+ */
+async function parseContentConfigReferences(): Promise<Map<string, Map<string, { target: string; isArray: boolean }>>> {
+	const result = new Map<string, Map<string, { target: string; isArray: boolean }>>()
+	const projectRoot = getProjectRoot()
+
+	for (const configPath of ['src/content/config.ts', 'src/content.config.ts']) {
+		try {
+			const fullPath = path.join(projectRoot, configPath)
+			const content = await fs.readFile(fullPath, 'utf-8')
+
+			// Parse defineCollection blocks to extract schema bodies
+			const collectionBlocks = content.matchAll(
+				/(?:const\s+(\w+)\s*=\s*)?defineCollection\s*\(\s*\{[\s\S]*?schema\s*:\s*z\.object\s*\(\s*\{([\s\S]*?)\}\s*\)/g,
+			)
+
+			// Map variable names to collection names from exports
+			const varToName = new Map<string, string>()
+			const exportMatch = content.match(/export\s+const\s+collections\s*=\s*\{([\s\S]*?)\}/)
+			if (exportMatch) {
+				const pairs = exportMatch[1]!.matchAll(/(\w+)\s*:\s*(\w+)/g)
+				for (const m of pairs) {
+					varToName.set(m[2]!, m[1]!)
 				}
+			}
+
+			for (const block of collectionBlocks) {
+				const varName = block[1]
+				const schemaBody = block[2]!
+				const collectionName = varName ? varToName.get(varName) : undefined
+				if (!collectionName) continue
+
+				const fields = new Map<string, { target: string; isArray: boolean }>()
+				const fieldRefs = schemaBody.matchAll(/(\w+)\s*:\s*(z\.array\s*\(\s*)?reference\s*\(\s*['"](\w+)['"]\s*\)/g)
+				for (const m of fieldRefs) {
+					fields.set(m[1]!, { target: m[3]!, isArray: !!m[2] })
+				}
+
+				if (fields.size > 0) {
+					result.set(collectionName, fields)
+				}
+			}
+
+			if (result.size > 0) break // Found a config file with references
+		} catch {
+			// File doesn't exist, try next
+		}
+	}
+	return result
+}
+
+/**
+ * After all collections are scanned, detect reference fields.
+ * Prefers explicit reference() declarations from the content config file.
+ * Falls back to heuristic slug matching when no config is available.
+ */
+async function detectReferenceFields(collections: Record<string, CollectionDefinition>): Promise<void> {
+	// Try parsing the content config first — this is the source of truth
+	const configRefs = await parseContentConfigReferences()
+	if (configRefs.size > 0) {
+		for (const [collectionName, fieldRefs] of configRefs) {
+			const def = collections[collectionName]
+			if (!def) continue
+			for (const [fieldName, ref] of fieldRefs) {
+				const field = def.fields.find(f => f.name === fieldName)
+				if (!field) continue
+				if (ref.isArray) {
+					field.type = 'array'
+					field.itemType = 'reference'
+				} else {
+					field.type = 'reference'
+				}
+				field.collection = ref.target
+				field.options = undefined
+			}
+		}
+		return
+	}
+
+	// Fallback: heuristic detection by matching field values against collection slugs
+	detectReferenceFieldsBySlugMatch(collections)
+}
+
+function detectReferenceFieldsBySlugMatch(collections: Record<string, CollectionDefinition>): void {
+	const collectionSlugs = new Map<string, Set<string>>()
+	for (const [name, def] of Object.entries(collections)) {
+		if (def.entries && def.entries.length > 0) {
+			collectionSlugs.set(name, new Set(def.entries.map(e => e.slug)))
+		}
+	}
 
-				let obs = fieldMap.get(key)
-				if (!obs) {
-					obs = {
-						name: key,
-						values: [],
-						presentCount: 0,
-						totalEntries: markdownFiles.length,
+	for (const [collectionName, def] of Object.entries(collections)) {
+		for (const field of def.fields) {
+			if ((field.type === 'text' || field.type === 'select') && field.examples) {
+				const stringExamples = field.examples.filter((v): v is string => typeof v === 'string')
+				if (stringExamples.length === 0) continue
+
+				// Find all candidate collections where all examples match slugs
+				const candidates: Array<{ name: string; slugs: Set<string> }> = []
+				for (const [targetName, slugs] of collectionSlugs) {
+					if (targetName === collectionName) continue
+					const matchCount = stringExamples.filter(v => slugs.has(v)).length
+					if (matchCount > 0 && matchCount === stringExamples.length) {
+						candidates.push({ name: targetName, slugs })
 					}
-					fieldMap.set(key, obs)
 				}
 
-				obs.values.push(value)
-				obs.presentCount++
+				let bestTarget: string | undefined
+				if (candidates.length === 1) {
+					bestTarget = candidates[0]!.name
+				} else if (candidates.length > 1) {
+					// Multiple matches — disambiguate using all field values
+					const allValues = def.entries?.flatMap(e => {
+						const v = e.data?.[field.name]
+						return typeof v === 'string' ? [v] : []
+					}) ?? stringExamples
+					let bestOverlap = 0
+					for (const c of candidates) {
+						const overlap = allValues.filter(v => c.slugs.has(v)).length
+						if (overlap > bestOverlap) {
+							bestOverlap = overlap
+							bestTarget = c.name
+						}
+					}
+				}
+				if (bestTarget) {
+					field.type = 'reference'
+					field.collection = bestTarget
+					field.options = undefined
+				}
+			}
+
+			if (field.type === 'array' && field.itemType === 'text' && field.options) {
+				let bestTarget: string | undefined
+				let bestOverlap = 0
+				for (const [targetName, slugs] of collectionSlugs) {
+					if (targetName === collectionName) continue
+					const matchCount = field.options.filter(v => slugs.has(v)).length
+					if (matchCount > 0 && matchCount >= field.options.length * 0.5) {
+						if (matchCount > bestOverlap) {
+							bestOverlap = matchCount
+							bestTarget = targetName
+						}
+					}
+				}
+				if (bestTarget) {
+					field.type = 'array'
+					field.itemType = 'reference'
+					field.collection = bestTarget
+					field.options = undefined
+				}
 			}
 		}
+	}
+}
 
-		// Sort entries alphabetically by title (fallback to slug)
-		entryInfos.sort((a, b) => {
-			const aLabel = a.title ?? a.slug
-			const bLabel = b.title ?? b.slug
-			return aLabel.localeCompare(bLabel)
-		})
+/** Suffixes that indicate a field is a derived href/url/slug companion */
+const HREF_SUFFIXES = ['href', 'url', 'link', 'slug', 'path'] as const
 
-		// Update totalEntries for all observations
-		for (const obs of fieldMap.values()) {
-			obs.totalEntries = markdownFiles.length
+/**
+ * Detect fields like `categoryHref` that are derived from a source field (`category`).
+ * When every value is a slugified href of the source, mark it hidden with derivedFrom.
+ */
+function detectDerivedHrefFields(collections: Record<string, CollectionDefinition>): void {
+	for (const def of Object.values(collections)) {
+		const fieldsByName = new Map(def.fields.map(f => [f.name, f]))
+
+		for (const field of def.fields) {
+			if (field.hidden || field.derivedFrom) continue
+
+			const lowerName = field.name.toLowerCase()
+			for (const suffix of HREF_SUFFIXES) {
+				if (!lowerName.endsWith(suffix)) continue
+				const baseName = field.name.slice(0, -suffix.length)
+				if (!baseName) continue
+
+				// Case-insensitive lookup: exact match first, then scan by lowercased name
+				let sourceField = fieldsByName.get(baseName)
+				if (!sourceField) {
+					const lowerBase = baseName.toLowerCase()
+					for (const f of fieldsByName.values()) {
+						if (f.name.toLowerCase() === lowerBase) {
+							sourceField = f
+							break
+						}
+					}
+				}
+				if (!sourceField || !sourceField.examples || !field.examples) continue
+
+				const sourceExamples = sourceField.examples.filter((v): v is string => typeof v === 'string')
+				const derivedExamples = field.examples.filter((v): v is string => typeof v === 'string')
+				if (sourceExamples.length === 0 || derivedExamples.length === 0) continue
+
+				// Order-independent: check that every derived value matches some source value's href
+				const expectedHrefs = new Set(sourceExamples.map(slugifyHref))
+				const allMatch = derivedExamples.every(v => expectedHrefs.has(v))
+				if (allMatch) {
+					field.hidden = true
+					field.derivedFrom = sourceField.name
+					break
+				}
+			}
 		}
+	}
+}
 
-		const fields = mergeFieldObservations(Array.from(fieldMap.values()))
+/**
+ * Scan a data collection (JSON/YAML files) and infer its schema
+ */
+async function scanDataCollection(collectionPath: string, collectionName: string, contentDir: string): Promise<CollectionDefinition | null> {
+	try {
+		const entries = await fs.readdir(collectionPath, { withFileTypes: true })
+		const dataFiles = entries.filter(e => e.isFile() && (e.name.endsWith('.json') || e.name.endsWith('.yaml') || e.name.endsWith('.yml')))
+		if (dataFiles.length === 0) return null
 
-		// Generate a human-readable label
-		const label = collectionName
-			.replace(/[-_]/g, ' ')
-			.replace(/\b\w/g, c => c.toUpperCase())
+		const fieldMap = new Map<string, FieldObservation>()
+		const entryInfos: CollectionEntryInfo[] = []
+		const ext = dataFiles.some(file => file.name.endsWith('.json'))
+			? 'json' as const
+			: dataFiles.some(file => file.name.endsWith('.yaml'))
+			? 'yaml' as const
+			: 'yml' as const
+
+		const fileContents = await Promise.all(
+			dataFiles.map(file => fs.readFile(path.join(collectionPath, file.name), 'utf-8').catch(() => null)),
+		)
+
+		for (let i = 0; i < dataFiles.length; i++) {
+			const file = dataFiles[i]!
+			const raw = fileContents[i]!
+			if (raw === null) continue
+			let data: Record<string, unknown> | null = null
+			try {
+				data = file.name.endsWith('.json') ? JSON.parse(raw) : parseYaml(raw) as Record<string, unknown>
+			} catch {
+				continue
+			}
+			if (!data || typeof data !== 'object') continue
 
-		return {
-			name: collectionName,
-			label,
-			path: path.join(contentDir, collectionName),
-			entryCount: markdownFiles.length,
-			fields,
-			supportsDraft: hasDraft,
-			fileExtension,
-			entries: entryInfos,
+			const slug = file.name.replace(/\.(json|ya?ml)$/, '')
+			const title = typeof data.name === 'string' ? data.name : typeof data.title === 'string' ? data.title : undefined
+			entryInfos.push({ slug, title, sourcePath: path.join(contentDir, collectionName, file.name), data })
+
+			collectFieldObservations(fieldMap, data, dataFiles.length)
 		}
+
+		return buildCollectionDefinition(collectionName, contentDir, fieldMap, entryInfos, dataFiles.length, {
+			type: 'data',
+			fileExtension: ext,
+		})
 	} catch {
 		return null
 	}
@@ -290,6 +662,7 @@ export async function scanCollections(contentDir: string = 'src/content'): Promi
 			.map(async entry => {
 				const collectionPath = path.join(fullContentDir, entry.name)
 				const definition = await scanCollection(collectionPath, entry.name, contentDir)
+					?? await scanDataCollection(collectionPath, entry.name, contentDir)
 				if (definition) {
 					collections[entry.name] = definition
 				}
@@ -300,5 +673,9 @@ export async function scanCollections(contentDir: string = 'src/content'): Promi
 		// Content directory doesn't exist or isn't readable
 	}
 
+	// Post-scan: detect cross-collection references and derived fields
+	await detectReferenceFields(collections)
+	detectDerivedHrefFields(collections)
+
 	return collections
 }