@stonecrop/stonecrop 0.10.15 → 0.11.0

package/src/registry.ts

@@ -1,4 +1,5 @@
-import type { SchemaTypes } from '@stonecrop/aform'
+import type { SchemaTypes, TableSchema } from '@stonecrop/aform'
+import type { DoctypeMeta, LinkDeclaration } from '@stonecrop/schema'
 import { Router } from 'vue-router'
 
 import Doctype from './doctype'
@@ -20,13 +21,33 @@ export default class Registry {
 	 *
 	 * @defaultValue 'Registry'
 	 */
-	readonly name: string
+	readonly name: string = 'Registry'
 
 	/**
 	 * The registry property contains a collection of doctypes
+	 *
+	 * @defaultValue `{}`
 	 * @see {@link Doctype}
 	 */
-	readonly registry: Record<string, Doctype>
+	readonly registry: Record<string, Doctype> = {}
+
+	/**
+	 * Reverse index: backlink fieldname → list of \{ doctype slug, link fieldname \}.
+	 * Multiple doctypes can declare a link with the same backlink name, so each key
+	 * maps to an array. Built at schema load time for O(1) ancestor lookups.
+	 *
+	 * @defaultValue `new Map()`
+	 * @internal
+	 */
+	private _ancestorIndex: Map<string, Array<{ slug: string; fieldname: string }>> = new Map()
+
+	/**
+	 * Whether the ancestor index needs rebuilding
+	 *
+	 * @defaultValue `true`
+	 * @internal
+	 */
+	private _ancestorIndexDirty: boolean = true
 
 	/**
 	 * The Vue router instance
@@ -44,8 +65,6 @@ export default class Registry {
 			return Registry._root
 		}
 		Registry._root = this
-		this.name = 'Registry'
-		this.registry = {}
 		this.router = router
 		this.getMeta = getMeta
 	}
@@ -65,6 +84,7 @@ export default class Registry {
 	addDoctype(doctype: Doctype) {
 		if (!(doctype.slug in this.registry)) {
 			this.registry[doctype.slug] = doctype
+			this._ancestorIndexDirty = true
 		}
 
 		// Register actions (including field triggers) with the field trigger engine
@@ -87,108 +107,138 @@ export default class Registry {
 	/**
 	 * Resolve nested Doctype fields in a schema by embedding child schemas inline.
 	 *
-	 * @remarks
-	 * Walks the schema array and for each field with `fieldtype: 'Doctype'` and a string
-	 * `options` value, looks up the referenced doctype in the registry and:
+	 * Accepts a Doctype and extracts `fields` and `links` internally.
+	 * Fields array contains both scalar fields and link fields (with fieldtype: 'Link').
+	 * Render order is determined by the order of fields in the fields array.
 	 *
-	 * - If `cardinality: 'many'`: auto-derives `columns` from the child doctype's schema,
-	 *   sets `component: 'ATable'`, `config: { view: 'list' }`, and initializes `rows: []`.
-	 * - Otherwise (default/`cardinality: 'one'`): embeds the child schema as the field's
-	 *   `schema` property for 1:1 nested forms.
+	 * For each link field:
+	 * - Looks up the corresponding link declaration in `links` by fieldname
+	 * - `cardinality: 'noneOrMany'` or `'atLeastOne'`: auto-derives `columns` from the target's schema,
+	 *   sets `component` to `link.component ?? 'ATable'`, `config: { view: 'list' }`, `rows: []`.
+	 * - `cardinality: 'one'` or `'atMostOne'`: embeds the target schema as the entry's
+	 *   `schema` property, sets `component` to `link.component ?? 'AForm'`.
 	 *
 	 * Recurses for deeply nested doctypes. Circular references are protected against.
+	 * Returns a new array — does not mutate the original.
 	 *
-	 * Returns a new array — does not mutate the original schema.
-	 *
-	 * @param schema - The schema array to resolve
-	 * @returns A new schema array with nested Doctype fields resolved
-	 *
-	 * @example
-	 * ```ts
-	 * registry.addDoctype(addressDoctype)
-	 * registry.addDoctype(customerDoctype)
-	 *
-	 * // Before: customer schema has { fieldname: 'address', fieldtype: 'Doctype', options: 'address' }
-	 * const resolved = registry.resolveSchema(customerSchema)
-	 * // After: address field now has schema: [...address fields...]
-	 * ```
+	 * @param doctype - The doctype to resolve
+	 * @param visited - Internal — set of already-visited doctype slugs for cycle detection
+	 * @returns A new schema array with nested links resolved
 	 *
 	 * @public
 	 */
-	resolveSchema(schema: SchemaTypes[], visited?: Set<string>): SchemaTypes[] {
-		const seen = visited || new Set<string>()
-
-		return schema.map(field => {
-			// Check for Doctype fieldtype with a string options (slug reference)
-			if (
-				'fieldtype' in field &&
-				field.fieldtype === 'Doctype' &&
-				'options' in field &&
-				typeof field.options === 'string'
-			) {
-				const doctypeSlug = field.options
-
-				// Circular reference protection
-				if (seen.has(doctypeSlug)) {
-					return { ...field }
+	resolveSchema(doctype: Doctype, visited?: Set<string>): SchemaTypes[] {
+		const seen = visited ?? new Set<string>()
+		const slug = doctype.slug
+
+		// Prevent circular resolution
+		if (seen.has(slug)) {
+			return doctype.schema ? (Array.isArray(doctype.schema) ? doctype.schema : Array.from(doctype.schema)) : []
+		}
+		seen.add(slug)
+
+		// Convert schema to array
+		const schemaArray: SchemaTypes[] = doctype.schema
+			? Array.isArray(doctype.schema)
+				? doctype.schema
+				: Array.from(doctype.schema)
+			: []
+
+		// Build a map of link declarations by fieldname for quick lookup
+		// Use the link's fieldname property if set, otherwise use the key
+		const linksByFieldname = new Map<string, LinkDeclaration>()
+		if (doctype.links) {
+			for (const [key, link] of Object.entries(doctype.links)) {
+				const linkFieldname = link.fieldname ?? key
+				linksByFieldname.set(linkFieldname, link)
+			}
+		}
+
+		// Process fields in order: scalar fields copied as-is, link fields resolved
+		const resolvedFields: SchemaTypes[] = []
+		for (const field of schemaArray) {
+			// Check if this field is a link field (fieldtype: 'Link')
+			if ('fieldtype' in field && field.fieldtype === 'Link') {
+				const link = linksByFieldname.get(field.fieldname)
+				if (!link) {
+					// Link field without corresponding link declaration - copy as-is
+					resolvedFields.push({ ...field })
+					continue
 				}
 
-				const doctype = this.registry[doctypeSlug]
-				if (doctype && doctype.schema) {
-					// Convert Immutable.List to plain array if needed
-					const childSchema: SchemaTypes[] = Array.isArray(doctype.schema) ? doctype.schema : Array.from(doctype.schema)
-
-					// Check cardinality to determine handling
-					const cardinality = 'cardinality' in field ? field.cardinality : undefined
-
-					if (cardinality === 'many') {
-						// 1:many child table - derive columns, set component, config, rows
-						const resolved: Record<string, any> = { ...field }
-
-						// Auto-derive columns from child schema fields if not already provided
-						if (!('columns' in field) || !field.columns) {
-							resolved.columns = childSchema.map(childField => ({
-								name: childField.fieldname,
-								fieldname: childField.fieldname,
-								label: ('label' in childField && childField.label) || childField.fieldname,
-								fieldtype: 'fieldtype' in childField ? childField.fieldtype : 'Data',
-								align: ('align' in childField && childField.align) || 'left',
-								edit: 'edit' in childField ? childField.edit : true,
-								width: ('width' in childField && childField.width) || '20ch',
-							}))
-						}
-
-						// Set default component if not already specified
-						if (!resolved.component) {
-							resolved.component = 'ATable'
-						}
-
-						// Set default config if not already specified
-						if (!('config' in field) || !field.config) {
-							resolved.config = { view: 'list' }
-						}
-
-						// Initialize rows to empty array so componentProps fallback
-						// routes data from the form's dataModel[fieldname]
-						if (!('rows' in field) || !field.rows) {
-							resolved.rows = []
-						}
-
-						return resolved as SchemaTypes
-					} else {
-						// 1:1 nested form (default cardinality: 'one')
-						// Recurse into child schema to resolve deeply nested doctypes
-						seen.add(doctypeSlug)
-						const resolvedChild = this.resolveSchema(childSchema, seen)
-						seen.delete(doctypeSlug)
+				const targetDoctype = this.registry[link.target]
+				if (!targetDoctype) {
+					// Target not found - copy as-is
+					resolvedFields.push({ ...field })
+					continue
+				}
 
-						return { ...field, schema: resolvedChild }
-					}
+				const childSchema = this.resolveSchema(targetDoctype, seen)
+
+				if (link.cardinality === 'noneOrMany' || link.cardinality === 'atLeastOne') {
+					// Many relationship — build table config
+					resolvedFields.push(
+						this.buildTableConfig(
+							{ fieldname: field.fieldname, label: field.label || field.fieldname },
+							childSchema,
+							link.component
+						)
+					)
+				} else {
+					// One relationship — embed form schema
+					resolvedFields.push({
+						fieldname: field.fieldname,
+						label: field.label || field.fieldname,
+						component: link.component || 'AForm',
+						schema: childSchema,
+					})
 				}
+			} else {
+				// Scalar field — copy as-is
+				resolvedFields.push({ ...field })
 			}
+		}
 
-			return { ...field }
-		})
+		seen.delete(slug)
+
+		return resolvedFields
+	}
+
+	/**
+	 * Build an ATable configuration from a field and child schema
+	 * @internal
+	 */
+	private buildTableConfig(field: Record<string, any>, childSchema: SchemaTypes[], component?: string): TableSchema {
+		const resolved: TableSchema = {
+			fieldname: field.fieldname,
+			component: component || field.component || 'ATable',
+			columns: field.columns,
+			config: field.config,
+			rows: field.rows,
+		}
+
+		if (!resolved.columns) {
+			resolved.columns = childSchema
+				.filter(childField => 'fieldtype' in childField)
+				.map(childField => ({
+					name: childField.fieldname,
+					label: ('label' in childField && childField.label) || childField.fieldname,
+					fieldtype: 'fieldtype' in childField ? childField.fieldtype : 'Data',
+					align: 'align' in childField ? childField.align : 'left',
+					edit: 'edit' in childField ? childField.edit : true,
+					width: ('width' in childField && childField.width) || '20ch',
+				}))
+		}
+
+		if (!resolved.config) {
+			resolved.config = { view: 'list' }
+		}
+
+		if (!resolved.rows) {
+			resolved.rows = []
+		}
+
+		return resolved
 	}
 
 	/**
@@ -201,7 +251,7 @@ export default class Registry {
 	 * - Check → `false`
 	 * - Int, Float, Decimal, Currency, Quantity → `0`
 	 * - JSON → `{}`
-	 * - Doctype with `cardinality: 'many'` → `[]`
+	 * - Doctype with `cardinality: 'noneOrMany'` or `'atLeastOne'` → `[]`
 	 * - Doctype without `cardinality` or `cardinality: 'one'` → recursively initializes nested record
 	 * - All others → `null`
 	 *
@@ -223,7 +273,26 @@ export default class Registry {
 		const record: Record<string, any> = {}
 
 		schema.forEach(field => {
-			const fieldtype = 'fieldtype' in field ? (field.fieldtype as string) : 'Data'
+			const fieldtype = 'fieldtype' in field ? field.fieldtype : 'Data'
+			const cardinality = 'cardinality' in field ? field.cardinality : undefined
+
+			// 1:many — cardinality signals an array
+			if (cardinality === 'noneOrMany' || cardinality === 'atLeastOne') {
+				record[field.fieldname] = []
+				return
+			}
+
+			// Resolved 1:many table entry — has rows property
+			if ('rows' in field) {
+				record[field.fieldname] = []
+				return
+			}
+
+			// Resolved 1:1 link entry — has schema property (e.g., FieldsetSchema with nested schema)
+			if ('schema' in field && Array.isArray(field.schema)) {
+				record[field.fieldname] = this.initializeRecord(field.schema)
+				return
+			}
 
 			switch (fieldtype) {
 				case 'Data':
@@ -244,21 +313,6 @@ export default class Registry {
 				case 'JSON':
 					record[field.fieldname] = {}
 					break
-				case 'Doctype': {
-					// Check cardinality to determine initial value
-					const cardinality = 'cardinality' in field ? field.cardinality : undefined
-					if (cardinality === 'many') {
-						// 1:many child table - initialize as empty array
-						record[field.fieldname] = []
-					} else if ('schema' in field && Array.isArray(field.schema)) {
-						// 1:1 nested form with resolved schema - recursively initialize
-						record[field.fieldname] = this.initializeRecord(field.schema)
-					} else {
-						// 1:1 without resolved schema - empty object
-						record[field.fieldname] = {}
-					}
-					break
-				}
 				default:
 					record[field.fieldname] = null
 			}
@@ -277,6 +331,130 @@ export default class Registry {
 		return this.registry[slug]
 	}
 
+	/**
+	 * Get all links declared on a doctype.
+	 *
+	 * @param doctypeSlug - The doctype slug to get links for
+	 * @returns Array of link declarations with fieldname, or empty array if none
+	 *
+	 * @example
+	 * ```ts
+	 * const links = registry.getDescendantLinks('recipe')
+	 * // [{ fieldname: 'tasks', target: 'recipe-task', cardinality: 'noneOrMany', backlink: 'recipe' }]
+	 * ```
+	 *
+	 * @public
+	 */
+	getDescendantLinks(doctypeSlug: string): Array<LinkDeclaration & { fieldname: string }> {
+		const doctype = this.registry[doctypeSlug]
+		if (!doctype?.links) return []
+
+		return Object.entries(doctype.links).map(([fieldname, link]) => ({
+			...link,
+			fieldname,
+		}))
+	}
+
+	/**
+	 * Get links on other doctypes that target the given doctype.
+	 *
+	 * @param doctypeSlug - The doctype slug to find ancestor links for
+	 * @returns Array of link declarations with fieldname and declaring doctype slug, or empty array
+	 *
+	 * @example
+	 * ```ts
+	 * const ancestors = registry.getAncestorLinks('recipe-task')
+	 * // [{ fieldname: 'tasks', target: 'recipe-task', cardinality: 'noneOrMany', backlink: 'recipe', doctype: 'recipe' }]
+	 * ```
+	 *
+	 * @public
+	 */
+	getAncestorLinks(doctypeSlug: string): Array<LinkDeclaration & { fieldname: string; doctype: string }> {
+		this._ensureAncestorIndex()
+
+		const results: Array<LinkDeclaration & { fieldname: string; doctype: string }> = []
+
+		for (const [_backlink, entries] of this._ancestorIndex) {
+			for (const { slug: declaringSlug, fieldname } of entries) {
+				const declaringDoctype = this.registry[declaringSlug]
+				if (!declaringDoctype?.links) continue
+
+				const link = declaringDoctype.links[fieldname]
+				if (link?.target === doctypeSlug) {
+					results.push({
+						...link,
+						fieldname,
+						doctype: declaringSlug,
+					})
+				}
+			}
+		}
+
+		return results
+	}
+
+	/**
+	 * Ensure the ancestor index is up to date
+	 * @internal
+	 */
+	private _ensureAncestorIndex(): void {
+		if (!this._ancestorIndexDirty) return
+		this._ancestorIndexDirty = false
+		this._ancestorIndex.clear()
+
+		for (const [slug, doctype] of Object.entries(this.registry)) {
+			if (!doctype.links) continue
+			for (const [fieldname, link] of Object.entries(doctype.links)) {
+				if (link.backlink) {
+					const existing = this._ancestorIndex.get(link.backlink)
+					if (existing) {
+						existing.push({ slug, fieldname })
+					} else {
+						this._ancestorIndex.set(link.backlink, [{ slug, fieldname }])
+					}
+				}
+			}
+		}
+	}
+
+	/**
+	 * Convert the registry to a Map of DoctypeMeta objects for use with StonecropClient.
+	 *
+	 * This allows passing a Registry instance to StonecropClient by deriving the
+	 * Map\<string, DoctypeMeta\> that StonecropClient needs for building nested GraphQL queries.
+	 *
+	 * @returns Map of doctype metadata keyed by doctype name
+	 *
+	 * @example
+	 * ```typescript
+	 * const registry = new Registry()
+	 * registry.addDoctype(Doctype.fromObject(customerSchema))
+	 * registry.addDoctype(Doctype.fromObject(orderSchema))
+	 *
+	 * const client = new StonecropClient({
+	 *   endpoint: '/graphql',
+	 *   registry: registry.toMetaMap(),  // Convert once, use with client
+	 * })
+	 * ```
+	 *
+	 * @public
+	 */
+	toMetaMap(): Map<string, DoctypeMeta> {
+		const map = new Map<string, DoctypeMeta>()
+		for (const [slug, doctype] of Object.entries(this.registry)) {
+			const fields = doctype.schema ? doctype.schema.toArray() : []
+			const meta: DoctypeMeta = {
+				name: doctype.name,
+				slug: slug,
+				fields: fields as DoctypeMeta['fields'],
+				links: doctype.links,
+				workflow: doctype.workflow as DoctypeMeta['workflow'],
+			}
+			map.set(doctype.name, meta)
+		}
+		return map
+	}
+
 	// TODO: should we allow clearing the registry at all?
 	// clear() {
 	// 	this.registry = {}

package/src/schema-validator.ts

@@ -5,6 +5,7 @@
  */
 
 import type { SchemaTypes } from '@stonecrop/aform'
+import type { LinkDeclaration } from '@stonecrop/schema'
 import type { List, Map as ImmutableMap } from 'immutable'
 import type { AnyStateNodeConfig } from 'xstate'
 
@@ -28,6 +29,7 @@ export class SchemaValidator {
 		this.options = {
 			registry: options.registry || null!,
 			validateLinkTargets: options.validateLinkTargets ?? true,
+			validateLinks: options.validateLinks ?? true,
 			validateActions: options.validateActions ?? true,
 			validateWorkflows: options.validateWorkflows ?? true,
 			validateRequiredProperties: options.validateRequiredProperties ?? true,
@@ -40,13 +42,15 @@ export class SchemaValidator {
 	 * @param schema - Schema fields (List or Array)
 	 * @param workflow - Optional workflow configuration
 	 * @param actions - Optional actions map
+	 * @param links - Optional links object
 	 * @returns Validation result
 	 */
 	validate(
 		doctype: string,
 		schema: List<SchemaTypes> | SchemaTypes[] | undefined,
 		workflow?: AnyStateNodeConfig,
-		actions?: ImmutableMap<string, string[]> | Map<string, string[]>
+		actions?: ImmutableMap<string, string[]> | Map<string, string[]>,
+		links?: Record<string, LinkDeclaration>
 	): ValidationResult {
 		const issues: ValidationIssue[] = []
 
@@ -63,6 +67,11 @@ export class SchemaValidator {
 			issues.push(...this.validateLinkFields(doctype, schemaArray, this.options.registry))
 		}
 
+		// Validate links object
+		if (this.options.validateLinks && this.options.registry && links) {
+			issues.push(...this.validateLinkDeclarations(doctype, links, schemaArray, this.options.registry))
+		}
+
 		// Validate workflow configuration
 		if (this.options.validateWorkflows && workflow) {
 			issues.push(...this.validateWorkflow(doctype, workflow))
@@ -196,6 +205,116 @@ export class SchemaValidator {
 		return issues
 	}
 
+	/**
+	 * Validates link declarations: target resolution, backlink consistency, Link field correspondence
+	 * @internal
+	 */
+	private validateLinkDeclarations(
+		doctype: string,
+		links: Record<string, LinkDeclaration>,
+		schema: SchemaTypes[],
+		registry: Registry
+	): ValidationIssue[] {
+		const issues: ValidationIssue[] = []
+
+		// Build a map of Link fields by fieldname for quick lookup
+		const linkFieldsByFieldname = new Map<string, SchemaTypes>()
+		for (const field of schema) {
+			if ('fieldtype' in field && field.fieldtype === 'Link') {
+				linkFieldsByFieldname.set(field.fieldname, field)
+			}
+		}
+
+		for (const [fieldname, link] of Object.entries(links)) {
+			// Check target resolves in registry
+			const targetDoctype = registry.registry[link.target]
+			if (!targetDoctype) {
+				issues.push({
+					severity: ValidationSeverity.ERROR,
+					rule: 'link-invalid-target',
+					message: `Link "${fieldname}" references non-existent doctype: "${link.target}"`,
+					doctype,
+					fieldname,
+					context: { target: link.target },
+				})
+				continue
+			}
+
+			// Warn on self-referential target
+			if (link.target === doctype) {
+				issues.push({
+					severity: ValidationSeverity.WARNING,
+					rule: 'link-self-referential',
+					message: `Link "${fieldname}" is self-referential (target: "${link.target}")`,
+					doctype,
+					fieldname,
+					context: { target: link.target },
+				})
+			}
+
+			// Check backlink consistency
+			if (link.backlink && targetDoctype.links) {
+				const reciprocalLink = targetDoctype.links[link.backlink]
+				if (!reciprocalLink) {
+					issues.push({
+						severity: ValidationSeverity.ERROR,
+						rule: 'link-backlink-missing',
+						message: `Backlink "${link.backlink}" not found on target doctype "${link.target}"`,
+						doctype,
+						fieldname,
+						context: { backlink: link.backlink, target: link.target },
+					})
+				} else if (reciprocalLink.target !== doctype) {
+					issues.push({
+						severity: ValidationSeverity.WARNING,
+						rule: 'link-backlink-mismatch',
+						message: `Backlink "${link.backlink}" on "${link.target}" points to "${reciprocalLink.target}" instead of "${doctype}"`,
+						doctype,
+						fieldname,
+						context: { backlink: link.backlink, target: link.target, actualTarget: reciprocalLink.target },
+					})
+				}
+			}
+
+			// If Link field exists with same fieldname, verify it has matching target
+			// Only check if link has fieldname set (otherwise it's a standalone link without a field)
+			if (link.fieldname) {
+				const linkField = linkFieldsByFieldname.get(link.fieldname)
+				if (linkField) {
+					const linkFieldOptions = 'options' in linkField ? (linkField as { options: unknown }).options : undefined
+					const linkFieldTarget = typeof linkFieldOptions === 'string' ? linkFieldOptions : undefined
+					if (linkFieldTarget && linkFieldTarget !== link.target) {
+						issues.push({
+							severity: ValidationSeverity.ERROR,
+							rule: 'link-field-target-mismatch',
+							message: `Link field "${link.fieldname}" targets "${linkFieldTarget}" but link declaration targets "${link.target}"`,
+							doctype,
+							fieldname: link.fieldname,
+							context: { linkFieldTarget, linkTarget: link.target },
+						})
+					}
+				}
+			}
+		}
+
+		// Check that every Link field has a corresponding link declaration
+		// A Link field corresponds to a link if the link's fieldname property matches the field's fieldname
+		for (const [fieldname, _field] of linkFieldsByFieldname) {
+			const hasCorrespondingLink = Object.values(links).some(link => link.fieldname === fieldname)
+			if (!hasCorrespondingLink) {
+				issues.push({
+					severity: ValidationSeverity.ERROR,
+					rule: 'link-field-without-declaration',
+					message: `Link field "${fieldname}" has no corresponding link declaration`,
+					doctype,
+					fieldname,
+				})
+			}
+		}
+
+		return issues
+	}
+
 	/**
 	 * Validates workflow state machine configuration
 	 * @internal