@nuasite/cms-core 0.43.0-beta.1

package/src/collection-scanner.ts

@@ -0,0 +1,935 @@
+import type { CollectionDefinition, CollectionEntryInfo, FieldDefinition, FieldType } from '@nuasite/cms-types'
+import path from 'node:path'
+import { isMap, isPair, isScalar, parse as parseYaml, parseDocument } from 'yaml'
+import { type ParseCache, parseContentConfig, type ParsedConfig, type ParsedField } from './content-config-ast'
+import type { CmsFileSystem } from './fs/types'
+import { slugifyHref } from './shared'
+
+/** Regex patterns for type inference */
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}/
+const URL_PATTERN = /^(https?:\/\/|\/)/
+const IMAGE_EXTENSIONS = /\.(jpg|jpeg|png|gif|webp|svg|avif)$/i
+
+/** Maximum unique values before treating as free-form text instead of select */
+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',
+])
+
+/** 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',
+	'name',
+	'description',
+	'summary',
+	'excerpt',
+	'subtitle',
+	'heading',
+	'headline',
+	'slug',
+	'alt',
+	'caption',
+])
+
+/** Normalized names (lowercased, underscores/hyphens stripped) that mark a field as the publish toggle. */
+const PUBLISH_TOGGLE_NAMES = new Set(['draft', 'isdraft', 'published', 'ispublished', 'unpublished'])
+
+/** Normalized names that mark a field as the publish/release date anchor. */
+const PUBLISH_DATE_NAMES = new Set([
+	'date',
+	'pubdate',
+	'publishdate',
+	'publisheddate',
+	'publishedate',
+	'publishedat',
+	'datepublished',
+])
+
+/** Normalize a field name for case- and separator-insensitive matching against the *_NAMES sets above. */
+function normalizeFieldName(name: string): string {
+	return name.toLowerCase().replace(/[_-]/g, '')
+}
+
+/**
+ * Observed values for a single field across multiple files
+ */
+interface FieldObservation {
+	name: string
+	values: unknown[]
+	presentCount: number
+	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 @position and @group comment directives from raw YAML frontmatter.
+ * Uses the YAML AST which preserves comments via `commentBefore` on nodes.
+ */
+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.commentBefore
+		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(normalizeFieldName(field.name)) || field.type === 'image' || field.type === 'boolean') {
+			field.position = 'sidebar'
+		} else {
+			field.position = 'header'
+		}
+
+		// 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
+		}
+	}
+}
+
+/**
+ * Infer the field type from a value
+ */
+function inferFieldType(value: unknown, key: string): FieldType {
+	if (value === null || value === undefined) {
+		return 'text'
+	}
+
+	if (typeof value === 'boolean') {
+		return 'boolean'
+	}
+
+	if (typeof value === 'number') {
+		return 'number'
+	}
+
+	if (Array.isArray(value)) {
+		return 'array'
+	}
+
+	if (typeof value === 'object') {
+		return 'object'
+	}
+
+	if (typeof value === 'string') {
+		// Check for date pattern
+		if (DATE_PATTERN.test(value)) {
+			return 'date'
+		}
+
+		// Check for image paths
+		if (IMAGE_EXTENSIONS.test(value)) {
+			return 'image'
+		}
+
+		// Check for image-specific field names (exact word boundaries, not substrings)
+		const lowerKey = key.toLowerCase()
+		if (/(?:^|[_-])(?:image|thumbnail|cover|avatar|logo|icon|banner|photo)(?:$|[_-])/.test(lowerKey)) {
+			return 'image'
+		}
+
+		// Check for URLs
+		if (URL_PATTERN.test(value)) {
+			return 'url'
+		}
+
+		// Check for textarea (long text or contains newlines)
+		if (value.includes('\n') || value.length > TEXTAREA_MIN_LENGTH) {
+			return 'textarea'
+		}
+
+		return 'text'
+	}
+
+	return 'text'
+}
+
+/**
+ * Merge field observations from multiple files to determine final field definition.
+ * `depth` guards against pathological deeply-nested content blowing the stack —
+ * real-world YAML/JSON rarely exceeds 5 levels, so the cap is well above realistic use.
+ */
+const MAX_NESTED_FIELD_DEPTH = 16
+
+function mergeFieldObservations(observations: FieldObservation[], depth: number = 0): FieldDefinition[] {
+	if (depth >= MAX_NESTED_FIELD_DEPTH) return []
+	const fields: FieldDefinition[] = []
+
+	for (const obs of observations) {
+		const nonNullValues = obs.values.filter(v => v !== null && v !== undefined)
+		if (nonNullValues.length === 0) continue
+
+		// Determine type by consensus (most common inferred type)
+		const typeCounts = new Map<FieldType, number>()
+		for (const value of nonNullValues) {
+			const type = inferFieldType(value, obs.name)
+			typeCounts.set(type, (typeCounts.get(type) || 0) + 1)
+		}
+
+		// Get most common type
+		let fieldType: FieldType = 'text'
+		let maxCount = 0
+		for (const [type, count] of typeCounts) {
+			if (count > maxCount) {
+				maxCount = count
+				fieldType = type
+			}
+		}
+
+		const field: FieldDefinition = {
+			name: obs.name,
+			type: fieldType,
+			required: obs.presentCount === obs.totalEntries,
+			examples: nonNullValues.slice(0, 3),
+		}
+
+		// For text fields, check if we should treat as select (limited unique values)
+		if (fieldType === 'text' && !FREE_TEXT_FIELD_NAMES.has(normalizeFieldName(obs.name))) {
+			const uniqueValues = [...new Set(nonNullValues.map(v => String(v)))]
+			const uniqueRatio = uniqueValues.length / nonNullValues.length
+			// Only treat as select if unique values are limited AND not nearly all unique
+			// (a high unique ratio means entries have distinct values, indicating free-text)
+			if (uniqueValues.length > 0 && uniqueValues.length <= MAX_SELECT_OPTIONS && nonNullValues.length >= 2 && uniqueRatio <= 0.8) {
+				field.type = 'select'
+				field.options = uniqueValues.sort()
+			}
+		}
+
+		// For arrays, try to infer item type
+		if (fieldType === 'array') {
+			const allItems = nonNullValues.flatMap(v => (Array.isArray(v) ? v : []))
+			if (allItems.length > 0) {
+				const itemType = inferFieldType(allItems[0], obs.name)
+				field.itemType = itemType
+
+				// Check if array items should be select
+				if (itemType === 'text') {
+					const uniqueItems = [...new Set(allItems.map(v => String(v)))]
+					if (uniqueItems.length <= MAX_SELECT_OPTIONS * 2) {
+						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()), depth + 1)
+					}
+				}
+			}
+		}
+
+		// For plain object values, recurse into sub-fields so the editor can render them.
+		if (fieldType === 'object') {
+			const objectValues = nonNullValues.filter(
+				(v): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v),
+			)
+			if (objectValues.length > 0) {
+				const subFieldMap = new Map<string, FieldObservation>()
+				for (const item of objectValues) {
+					collectFieldObservations(subFieldMap, item, objectValues.length)
+				}
+				field.fields = mergeFieldObservations(Array.from(subFieldMap.values()), depth + 1)
+			}
+		}
+
+		fields.push(field)
+	}
+
+	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 assembleCollectionDefinition(
+	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,
+	}
+}
+
+/**
+ * Compute the root-relative base path of a collection's source directory.
+ * `basePath` is root-relative (e.g. `src/content/blog` for the default layout,
+ * or a glob loader base like `src/content/jsem`). When it matches the default
+ * `<contentDir>/<name>` location, the canonical default path is returned;
+ * otherwise the (already root-relative) base path is returned verbatim.
+ */
+function getCollectionSourceBasePath(basePath: string, collectionName: string, contentDir: string): string {
+	const defaultCollectionPath = path.join(contentDir, collectionName)
+	if (path.normalize(basePath) === path.normalize(defaultCollectionPath)) {
+		return path.join(contentDir, collectionName)
+	}
+	return basePath
+}
+
+async function buildCollectionDefinition(
+	fs: CmsFileSystem,
+	basePath: string,
+	sources: Array<{ slug: string; relPath: string }>,
+	collectionName: string,
+	contentDir: string,
+): Promise<CollectionDefinition | null> {
+	if (sources.length === 0) return null
+
+	const sourceBasePath = getCollectionSourceBasePath(basePath, collectionName, contentDir)
+	const hasMd = sources.some(s => s.relPath.endsWith('.md'))
+	const fileExtension: 'md' | 'mdx' = hasMd ? 'md' : 'mdx'
+
+	const fieldMap = new Map<string, FieldObservation>()
+	const allDirectives: Record<string, { position?: 'sidebar' | 'header'; group?: string }> = {}
+	const entryInfos: CollectionEntryInfo[] = []
+	let hasDraft = false
+
+	const fileContents = await Promise.all(
+		sources.map(s => fs.readFile(path.join(basePath, s.relPath))),
+	)
+
+	for (let i = 0; i < sources.length; i++) {
+		const source = sources[i]!
+		const content = fileContents[i]!
+		const frontmatter = parseFrontmatter(content)
+
+		const directives = parseFieldDirectives(content)
+		for (const [key, value] of Object.entries(directives)) {
+			if (!allDirectives[key]) {
+				allDirectives[key] = value
+			}
+		}
+
+		const entryInfo: CollectionEntryInfo = {
+			slug: source.slug,
+			sourcePath: path.join(sourceBasePath, source.relPath),
+		}
+		if (frontmatter) {
+			if (typeof frontmatter.title === 'string') {
+				entryInfo.title = frontmatter.title
+			}
+			if (typeof frontmatter.draft === 'boolean' && frontmatter.draft) {
+				entryInfo.draft = true
+			}
+			entryInfo.data = frontmatter
+		}
+		entryInfos.push(entryInfo)
+
+		if (!frontmatter) continue
+
+		if (frontmatter.draft === true) hasDraft = true
+		collectFieldObservations(fieldMap, frontmatter, sources.length)
+	}
+
+	const def = assembleCollectionDefinition(collectionName, contentDir, fieldMap, entryInfos, sources.length, {
+		path: sourceBasePath,
+		supportsDraft: hasDraft,
+		fileExtension,
+	})
+	assignFieldMetadata(def.fields, allDirectives)
+	return def
+}
+
+/**
+ * Scan a single collection directory and infer its schema
+ */
+async function scanCollection(
+	fs: CmsFileSystem,
+	collectionPath: string,
+	collectionName: string,
+	contentDir: string,
+): Promise<CollectionDefinition | null> {
+	const dirEntries = await fs.list(collectionPath)
+	if (dirEntries.length === 0) return null
+
+	const sources: Array<{ slug: string; relPath: string }> = []
+	const takenSlugs = new Set<string>()
+
+	for (const entry of dirEntries) {
+		if (entry.isDirectory) continue
+		if (!entry.name.endsWith('.md') && !entry.name.endsWith('.mdx')) continue
+		const slug = entry.name.replace(/\.(md|mdx)$/, '')
+		sources.push({ slug, relPath: entry.name })
+		takenSlugs.add(slug)
+	}
+
+	// Hugo-style layout: <slug>/index.md(x). Flat files win on slug conflict.
+	const subdirs = dirEntries.filter(e => e.isDirectory && !e.name.startsWith('_') && !e.name.startsWith('.'))
+	const indexLookups = await Promise.all(subdirs.map(async dir => {
+		if (takenSlugs.has(dir.name)) return null
+		for (const ext of ['md', 'mdx'] as const) {
+			const relPath = path.join(dir.name, `index.${ext}`)
+			if (await fs.exists(path.join(collectionPath, relPath))) {
+				return { slug: dir.name, relPath }
+			}
+		}
+		return null
+	}))
+	for (const entry of indexLookups) {
+		if (entry) sources.push(entry)
+	}
+
+	if (sources.length === 0) return null
+	return await buildCollectionDefinition(fs, collectionPath, sources, collectionName, contentDir)
+}
+
+/**
+ * Scan a collection declared in content config via a glob loader (base + pattern),
+ * which may share a base directory with another collection (nested layout).
+ */
+async function scanGlobCollection(
+	fs: CmsFileSystem,
+	collectionName: string,
+	baseRel: string,
+	pattern: string,
+	contentDir: string,
+): Promise<CollectionDefinition | null> {
+	// The port's glob walks the root; scope it to the loader base and re-relativize matches.
+	// The scanner ignores files/dirs whose path segments start with `_` or `.` (private/hidden),
+	// matching the directory-walk behavior of the original scanner — the glob pattern alone
+	// would otherwise match them.
+	const matches = await fs.glob(path.join(baseRel, pattern))
+	const sources = matches
+		.filter(rel => rel.endsWith('.md') || rel.endsWith('.mdx'))
+		.map(rel => path.relative(baseRel, rel))
+		.filter(relToBase => !relToBase.split('/').some(seg => seg.startsWith('_') || seg.startsWith('.')))
+		.map(relToBase => ({ slug: relToBase.replace(/\.(md|mdx)$/, ''), relPath: relToBase }))
+
+	if (sources.length === 0) return null
+	return await buildCollectionDefinition(fs, baseRel, sources, collectionName, contentDir)
+}
+
+/**
+ * Filter scanned fields to schema-only and apply per-field overrides (type, hints, required)
+ * in a single pass. Filtering must happen first since it can shrink `def.fields`.
+ */
+function applyParsedConfig(
+	collections: Record<string, CollectionDefinition>,
+	parsed: ParsedConfig,
+): void {
+	for (const [collectionName, parsedColl] of parsed) {
+		const def = collections[collectionName]
+		if (!def) continue
+
+		if (parsedColl.fields.length > 0) {
+			const schemaNames = new Set(parsedColl.fields.map(f => f.name))
+			def.fields = def.fields.filter(f => schemaNames.has(f.name))
+		}
+
+		const fieldsByName = new Map(def.fields.map(f => [f.name, f]))
+		for (const pf of parsedColl.fields) {
+			const field = fieldsByName.get(pf.name)
+			if (!field) continue
+			applyParsedFieldOverrides(field, pf)
+		}
+	}
+}
+
+/**
+ * Apply parsed schema overrides to an inferred field, recursing into nested object/array fields.
+ *
+ * Note on schema-vs-inferred merging at nested levels: schema-declared sub-fields replace
+ * the inferred list rather than merging. Inferred-only sub-fields are *not* lost — the
+ * editor's `ObjectFields` recovers them via its `extraKeys` calculation (field value keys
+ * minus schemaNames), routes them through `FrontmatterField` (value-based auto-detect),
+ * and offers a remove button. Merging here would defeat that.
+ */
+function applyParsedFieldOverrides(field: FieldDefinition, pf: ParsedField): void {
+	if (pf.type) {
+		field.type = pf.type
+		if (pf.options) field.options = pf.options
+	}
+	if (pf.itemType) field.itemType = pf.itemType
+	if (pf.hints) field.hints = pf.hints
+	if (pf.astroImage) field.astroImage = true
+	field.required = pf.required
+
+	if (pf.fields) {
+		const existingByName = new Map((field.fields ?? []).map(f => [f.name, f]))
+		field.fields = pf.fields.map((subPf) => {
+			const existing = existingByName.get(subPf.name)
+			if (existing) {
+				applyParsedFieldOverrides(existing, subPf)
+				return existing
+			}
+			return parsedFieldToFieldDefinition(subPf)
+		})
+	}
+}
+
+/**
+ * Build a FieldDefinition from a parsed schema field when no inferred counterpart exists.
+ * Falls back to `'text'` when the parser couldn't pin a type — keeps the field visible
+ * and editable. Schema-declared-but-data-absent fields would otherwise vanish.
+ */
+function parsedFieldToFieldDefinition(pf: ParsedField): FieldDefinition {
+	const fd: FieldDefinition = {
+		name: pf.name,
+		// A parsed field with nested children but no explicit type is necessarily an object.
+		// Otherwise default to 'text' so users can still fill in schema-declared fields
+		// whose helper the parser didn't recognize.
+		type: pf.type ?? (pf.fields ? 'object' : 'text'),
+		required: pf.required,
+	}
+	if (pf.options) fd.options = pf.options
+	if (pf.itemType) fd.itemType = pf.itemType
+	if (pf.hints) fd.hints = pf.hints
+	if (pf.astroImage) fd.astroImage = true
+	if (pf.fields) fd.fields = pf.fields.map(parsedFieldToFieldDefinition)
+	return fd
+}
+
+/** Apply orderBy configuration: set the field name and direction on the definition, then re-sort entries. */
+function applyCollectionOrderBy(
+	collections: Record<string, CollectionDefinition>,
+	parsed: ParsedConfig,
+): void {
+	for (const [collectionName, parsedColl] of parsed) {
+		const orderField = parsedColl.fields.find(f => f.orderBy)
+		if (!orderField?.orderBy) continue
+		const def = collections[collectionName]
+		if (!def) continue
+
+		const fieldName = orderField.name
+		const direction = orderField.orderBy.direction
+		def.orderBy = fieldName
+		def.orderDirection = direction
+		if (def.entries && def.entries.length > 1) {
+			const dir = direction === 'desc' ? -1 : 1
+			def.entries.sort((a, b) => {
+				const aVal = a.data?.[fieldName]
+				const bVal = b.data?.[fieldName]
+				if (aVal == null && bVal == null) return 0
+				if (aVal == null) return 1
+				if (bVal == null) return -1
+				if (typeof aVal === 'number' && typeof bVal === 'number') return (aVal - bVal) * dir
+				if (aVal instanceof Date && bVal instanceof Date) return (aVal.getTime() - bVal.getTime()) * dir
+				return String(aVal).localeCompare(String(bVal)) * dir
+			})
+		}
+	}
+}
+
+/**
+ * Detect reference fields. Prefers explicit `reference()` declarations from the content
+ * config; if none are found anywhere, falls back to heuristic slug matching.
+ */
+function detectReferenceFields(
+	collections: Record<string, CollectionDefinition>,
+	parsed: ParsedConfig,
+): void {
+	let appliedAny = false
+	for (const [collectionName, parsedColl] of parsed) {
+		const def = collections[collectionName]
+		if (!def) continue
+		for (const pf of parsedColl.fields) {
+			if (!pf.reference) continue
+			const field = def.fields.find(f => f.name === pf.name)
+			if (!field) continue
+			appliedAny = true
+			if (pf.reference.isArray) {
+				field.type = 'array'
+				field.itemType = 'reference'
+			} else {
+				field.type = 'reference'
+			}
+			field.collection = pf.reference.target
+			field.options = undefined
+		}
+	}
+
+	if (!appliedAny) 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)))
+		}
+	}
+
+	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 })
+					}
+				}
+
+				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
+				}
+			}
+		}
+	}
+}
+
+/**
+ * Tag fields with semantic roles so the editor UI can position them without
+ * matching on Astro-specific field names. Detection lives here — the layer
+ * that already knows it's parsing Astro content collections.
+ */
+function assignSemanticRoles(collections: Record<string, CollectionDefinition>): void {
+	for (const def of Object.values(collections)) {
+		let toggle: FieldDefinition | undefined
+		let dateByName: FieldDefinition | undefined
+		let dateByType: FieldDefinition | undefined
+		for (const field of def.fields) {
+			if (field.hidden || field.role) continue
+			const normalized = normalizeFieldName(field.name)
+			if (!toggle && field.type === 'boolean' && PUBLISH_TOGGLE_NAMES.has(normalized)) {
+				toggle = field
+			} else if (!dateByName && PUBLISH_DATE_NAMES.has(normalized)) {
+				dateByName = field
+			} else if (!dateByType && (field.type === 'date' || field.type === 'datetime')) {
+				dateByType = field
+			}
+		}
+		if (toggle) toggle.role = 'publish-toggle'
+		const date = dateByName ?? dateByType
+		if (date) date.role = 'publish-date'
+	}
+}
+
+/** Suffixes that indicate a field is a derived href/url/slug companion */
+const HREF_SUFFIXES = ['href', 'url', 'link', 'slug', 'path'] as const
+
+/**
+ * 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
+				}
+			}
+		}
+	}
+}
+
+/**
+ * Scan a data collection (JSON/YAML files) and infer its schema
+ */
+async function scanDataCollection(
+	fs: CmsFileSystem,
+	collectionPath: string,
+	collectionName: string,
+	contentDir: string,
+): Promise<CollectionDefinition | null> {
+	const dirEntries = await fs.list(collectionPath)
+	if (dirEntries.length === 0) return null
+
+	const sources: Array<{ slug: string; relPath: string }> = []
+	const takenSlugs = new Set<string>()
+
+	for (const entry of dirEntries) {
+		if (entry.isDirectory) continue
+		if (!entry.name.endsWith('.json') && !entry.name.endsWith('.yaml') && !entry.name.endsWith('.yml')) continue
+		const slug = entry.name.replace(/\.(json|ya?ml)$/, '')
+		sources.push({ slug, relPath: entry.name })
+		takenSlugs.add(slug)
+	}
+
+	// Hugo-style layout: <slug>/index.{json,yaml,yml}. Flat files win on slug conflict.
+	const subdirs = dirEntries.filter(e => e.isDirectory && !e.name.startsWith('_') && !e.name.startsWith('.'))
+	const indexLookups = await Promise.all(subdirs.map(async dir => {
+		if (takenSlugs.has(dir.name)) return null
+		for (const indexExt of ['json', 'yaml', 'yml'] as const) {
+			const relPath = path.join(dir.name, `index.${indexExt}`)
+			if (await fs.exists(path.join(collectionPath, relPath))) {
+				return { slug: dir.name, relPath }
+			}
+		}
+		return null
+	}))
+	for (const entry of indexLookups) {
+		if (entry) sources.push(entry)
+	}
+
+	if (sources.length === 0) return null
+
+	const fieldMap = new Map<string, FieldObservation>()
+	const entryInfos: CollectionEntryInfo[] = []
+	const ext = sources.some(s => s.relPath.endsWith('.json'))
+		? 'json' as const
+		: sources.some(s => s.relPath.endsWith('.yaml'))
+		? 'yaml' as const
+		: 'yml' as const
+
+	const fileContents = await Promise.all(
+		sources.map(s => fs.readFile(path.join(collectionPath, s.relPath)).catch(() => null)),
+	)
+
+	for (let i = 0; i < sources.length; i++) {
+		const source = sources[i]!
+		const raw = fileContents[i]!
+		if (raw === null) continue
+		let data: Record<string, unknown> | null = null
+		try {
+			data = source.relPath.endsWith('.json') ? JSON.parse(raw) : parseYaml(raw) as Record<string, unknown>
+		} catch {
+			continue
+		}
+		if (!data || typeof data !== 'object') continue
+
+		const title = typeof data.name === 'string' ? data.name : typeof data.title === 'string' ? data.title : undefined
+		entryInfos.push({
+			slug: source.slug,
+			title,
+			sourcePath: path.join(contentDir, collectionName, source.relPath),
+			data,
+		})
+
+		collectFieldObservations(fieldMap, data, sources.length)
+	}
+
+	return assembleCollectionDefinition(collectionName, contentDir, fieldMap, entryInfos, sources.length, {
+		type: 'data',
+		fileExtension: ext,
+	})
+}
+
+/**
+ * Scan all collections in the content directory.
+ *
+ * `contentDir` is a root-relative directory (default `src/content`); all I/O is
+ * resolved against the injected `CmsFileSystem`'s root. `parseCache` keeps the
+ * mtime-keyed content-config parse result across calls within one core instance.
+ */
+export async function scanCollections(
+	fs: CmsFileSystem,
+	contentDir: string = 'src/content',
+	parseCache: ParseCache = new Map(),
+): Promise<Record<string, CollectionDefinition>> {
+	const collections: Record<string, CollectionDefinition> = {}
+
+	const entries = await fs.list(contentDir)
+
+	const scanPromises = entries
+		.filter(entry => entry.isDirectory && !entry.name.startsWith('_') && !entry.name.startsWith('.'))
+		.map(async entry => {
+			const collectionPath = path.join(contentDir, entry.name)
+			const definition = await scanCollection(fs, collectionPath, entry.name, contentDir)
+				?? await scanDataCollection(fs, collectionPath, entry.name, contentDir)
+			if (definition) {
+				collections[entry.name] = definition
+			}
+		})
+
+	await Promise.all(scanPromises)
+
+	// Post-scan: apply schema-driven field config, detect references, derived fields, and ordering
+	const parsed = await parseContentConfig(fs, parseCache)
+	for (const [collectionName, parsedCollection] of parsed) {
+		if (collections[collectionName]) continue
+		if (!parsedCollection.loaderBase || !parsedCollection.loaderPattern) continue
+		const definition = await scanGlobCollection(fs, collectionName, parsedCollection.loaderBase, parsedCollection.loaderPattern, contentDir)
+		if (!definition) continue
+		// Nest under the collection that owns the shared base directory (e.g. jsem-otazky -> jsem),
+		// so the CMS browser can group it under its parent page instead of listing it flat.
+		const baseName = parsedCollection.loaderBase.replace(/[/\\]+$/, '').split(/[/\\]/).pop()
+		if (baseName && baseName !== collectionName && collections[baseName]) {
+			definition.parentCollection = baseName
+		}
+		collections[collectionName] = definition
+	}
+
+	applyParsedConfig(collections, parsed)
+	detectReferenceFields(collections, parsed)
+	detectDerivedHrefFields(collections)
+	assignSemanticRoles(collections)
+	applyCollectionOrderBy(collections, parsed)
+
+	return collections
+}