@aperant/framework 0.19.0 → 0.20.0

package/src/cli/features/area-shape.mjs

@@ -0,0 +1,140 @@
+/**
+ * area-shape.mjs — hand-rolled structural validator for feature-registry
+ * area files, mirroring `src/schemas/feature-registry.ts` (FeatureRegistrySchema)
+ * PLUS the uniqueness refinement (feature ids unique per area; sub_feature ids
+ * unique per feature group).
+ *
+ * WHY A TWIN VALIDATOR EXISTS (ID-07): the bare-node CI check
+ * (`bin/features-reconcile-check.mjs`) runs with NO node_modules, so it cannot
+ * import zod. This module is node:-builtins only (in fact, zero imports).
+ * `feature-registry-schema-parity.test.ts` validates shared fixtures against
+ * BOTH this validator and the zod schema so they cannot drift.
+ *
+ * Semantics mirror zod defaults:
+ *   - unknown keys are ALLOWED (zod objects are non-strict);
+ *   - `components` and `sub_features` may be absent (zod `.default([])`);
+ *   - `route` stays required non-empty — non-routed areas use the literal
+ *     "(cross-cutting)" (chrome.json precedent), never null.
+ *
+ * Returns { ok, errors: [] } — never throws.
+ */
+
+const ID_RE = /^[a-z0-9-]+$/
+const LAST_SCANNED_RE = /^\d{4}-\d{2}-\d{2}(T[\d:.Z+-]+)?$/
+const TESTABLE_VALUES = new Set(['testable', 'observable', 'blocked'])
+const WIRED_VALUES = new Set([true, false, 'stubbed', 'partial'])
+
+function isNonEmptyString(v) {
+	return typeof v === 'string' && v.length > 0
+}
+
+function checkOptionalString(errors, at, v) {
+	if (v !== undefined && !isNonEmptyString(v)) {
+		errors.push(`${at}: must be a non-empty string when present`)
+	}
+}
+
+function validateSubFeature(errors, at, sub) {
+	if (!sub || typeof sub !== 'object' || Array.isArray(sub)) {
+		errors.push(`${at}: must be an object`)
+		return
+	}
+	if (!isNonEmptyString(sub.id) || !ID_RE.test(sub.id)) {
+		errors.push(`${at}.id: must match ${ID_RE}`)
+	}
+	if (!isNonEmptyString(sub.name)) errors.push(`${at}.name: required non-empty string`)
+	checkOptionalString(errors, `${at}.component`, sub.component)
+	if (!isNonEmptyString(sub.type)) errors.push(`${at}.type: required non-empty string`)
+	if (!WIRED_VALUES.has(sub.wired)) {
+		errors.push(`${at}.wired: must be true|false|"stubbed"|"partial"`)
+	}
+	if (sub.handler !== undefined && typeof sub.handler !== 'string') {
+		errors.push(`${at}.handler: must be a string when present`)
+	}
+	if (sub.shortcut !== undefined && typeof sub.shortcut !== 'string') {
+		errors.push(`${at}.shortcut: must be a string when present`)
+	}
+	if (sub.testable !== undefined && !TESTABLE_VALUES.has(sub.testable)) {
+		errors.push(`${at}.testable: must be "testable"|"observable"|"blocked" when present`)
+	}
+	if (sub.test_hint !== undefined && typeof sub.test_hint !== 'string') {
+		errors.push(`${at}.test_hint: must be a string when present`)
+	}
+	// default / range / options are `unknown` in the zod schema — anything goes.
+}
+
+function validateFeatureGroup(errors, at, group) {
+	if (!group || typeof group !== 'object' || Array.isArray(group)) {
+		errors.push(`${at}: must be an object`)
+		return
+	}
+	if (!isNonEmptyString(group.id) || !ID_RE.test(group.id)) {
+		errors.push(`${at}.id: must match ${ID_RE}`)
+	}
+	if (!isNonEmptyString(group.name)) errors.push(`${at}.name: required non-empty string`)
+	checkOptionalString(errors, `${at}.component`, group.component)
+	if (group.sub_features !== undefined) {
+		if (!Array.isArray(group.sub_features)) {
+			errors.push(`${at}.sub_features: must be an array when present`)
+		} else {
+			const seen = new Set()
+			for (const [i, sub] of group.sub_features.entries()) {
+				validateSubFeature(errors, `${at}.sub_features[${i}]`, sub)
+				const id = sub?.id
+				if (isNonEmptyString(id)) {
+					if (seen.has(id)) {
+						errors.push(`${at}.sub_features[${i}].id: duplicate sub_feature id "${id}" in group`)
+					}
+					seen.add(id)
+				}
+			}
+		}
+	}
+}
+
+/**
+ * Structural + uniqueness validation of an area-file value.
+ *
+ * @param {unknown} data — parsed JSON of a `.aperant/features/<area>.json`
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateAreaShape(data) {
+	const errors = []
+	if (!data || typeof data !== 'object' || Array.isArray(data)) {
+		return { ok: false, errors: ['area file must be a JSON object'] }
+	}
+	if (!isNonEmptyString(data.area)) errors.push('area: required non-empty string')
+	if (!isNonEmptyString(data.route)) {
+		errors.push(
+			'route: required non-empty string — use "(cross-cutting)" for non-routed areas, never null',
+		)
+	}
+	if (data.components !== undefined) {
+		if (!Array.isArray(data.components)) {
+			errors.push('components: must be an array when present')
+		} else {
+			for (const [i, c] of data.components.entries()) {
+				if (!isNonEmptyString(c)) errors.push(`components[${i}]: must be a non-empty string`)
+			}
+		}
+	}
+	if (!isNonEmptyString(data.last_scanned) || !LAST_SCANNED_RE.test(data.last_scanned)) {
+		errors.push('last_scanned: must be a YYYY-MM-DD or full ISO 8601 date string')
+	}
+	if (!Array.isArray(data.features)) {
+		errors.push('features: required array')
+	} else {
+		const seen = new Set()
+		for (const [i, group] of data.features.entries()) {
+			validateFeatureGroup(errors, `features[${i}]`, group)
+			const id = group?.id
+			if (isNonEmptyString(id)) {
+				if (seen.has(id)) {
+					errors.push(`features[${i}].id: duplicate feature id "${id}" in area`)
+				}
+				seen.add(id)
+			}
+		}
+	}
+	return { ok: errors.length === 0, errors }
+}