export type FeatureManifestClassification = "core" | "plugin-candidate" | "remove-candidate" | "mixed"; export type FeatureManifestStatus = "active" | "proposed" | "review-needed"; export type FeatureManifestDiagnosticCode = "invalid_type" | "missing_required" | "invalid_enum" | "invalid_format" | "invalid_item"; export interface FeatureManifestDiagnostic { code: FeatureManifestDiagnosticCode; manifestId: string | null; path: string; message: string; } export interface FeatureManifestValidationContext { manifestId?: string; path?: string; } export interface FeatureManifestValidationResult { ok: boolean; manifest: FeatureManifest | null; diagnostics: FeatureManifestDiagnostic[]; } export interface FeatureManifestComponent { id: string; title: string; rationale: string; codeAreas: string[]; notes?: string; } export interface FeatureManifest { schemaVersion: "1.0"; id: string; title: string; classification: FeatureManifestClassification; status: FeatureManifestStatus; owner: string; description: string; rationale: string[]; codeAreas: string[]; dependencies: string[]; consumers: string[]; components?: FeatureManifestComponent[]; integration: { ownership: "tenant-owned" | "admin-managed" | "hybrid" | "system-only"; surfaces: { adminRoutes: string[]; tenantRoutes: string[]; publicRoutes: string[]; apiRoutes: string[] }; configuration: { admin: string[]; tenant: string[]; environment: string[]; secrets: string[] }; workers: { required: boolean; queues: string[]; jobs: string[]; notes: string[] }; externalProviders: string[]; permissions: string[]; auditEvents: string[]; billingImpacts: string[]; uat: string[]; }; boundaries: { mustKeep: string[]; mayMoveToPlugin: string[]; mustNotTouch: string[] }; pruning: { phase: string; action: "keep" | "extract-plugin" | "remove" | "review"; notes: string[] }; validation: { source: string[]; lastReviewed: string }; } const ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/; const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/; const PERMISSION_TOKEN_PATTERN = /^[a-z][A-Za-z0-9]*(?:\.(?:[A-Za-z][A-Za-z0-9]*|\*))+$/; const AUDIT_EVENT_PATTERN = /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$/; const CLASSIFICATIONS = ["core", "plugin-candidate", "remove-candidate", "mixed"] as const; const STATUSES = ["active", "proposed", "review-needed"] as const; const OWNERSHIPS = ["tenant-owned", "admin-managed", "hybrid", "system-only"] as const; const PRUNING_ACTIONS = ["keep", "extract-plugin", "remove", "review"] as const; function isRecord(value: unknown): value is Record { return typeof value === "object" && value !== null && !Array.isArray(value); } function add(diagnostics: FeatureManifestDiagnostic[], code: FeatureManifestDiagnosticCode, manifestId: string | null, path: string, message: string) { diagnostics.push({ code, manifestId, path, message }); } function manifestIdFor(input: Record, context: FeatureManifestValidationContext): string | null { return context.manifestId ?? (typeof input.id === "string" && input.id.length > 0 ? input.id : null); } function requireString(source: Record, key: string, path: string, diagnostics: FeatureManifestDiagnostic[], manifestId: string | null, options: { nonEmpty?: boolean; pattern?: RegExp; constValue?: string } = {}) { const value = source[key]; if (value === undefined) return add(diagnostics, "missing_required", manifestId, path, `${path} is required.`); if (typeof value !== "string") return add(diagnostics, "invalid_type", manifestId, path, `${path} must be a string.`); if (options.nonEmpty && value.length === 0) add(diagnostics, "invalid_format", manifestId, path, `${path} must not be empty.`); if (options.constValue !== undefined && value !== options.constValue) add(diagnostics, "invalid_enum", manifestId, path, `${path} must be ${options.constValue}.`); if (options.pattern && !options.pattern.test(value)) add(diagnostics, "invalid_format", manifestId, path, `${path} has an invalid format.`); } function requireEnum(source: Record, key: string, values: T, path: string, diagnostics: FeatureManifestDiagnostic[], manifestId: string | null) { const value = source[key]; if (value === undefined) return add(diagnostics, "missing_required", manifestId, path, `${path} is required.`); if (typeof value !== "string") return add(diagnostics, "invalid_type", manifestId, path, `${path} must be a string.`); if (!values.includes(value)) add(diagnostics, "invalid_enum", manifestId, path, `${path} must be one of: ${values.join(", ")}.`); } function requireStringArray(source: Record, key: string, path: string, diagnostics: FeatureManifestDiagnostic[], manifestId: string | null, options: { itemPattern?: RegExp } = {}) { const value = source[key]; if (value === undefined) return add(diagnostics, "missing_required", manifestId, path, `${path} is required.`); if (!Array.isArray(value)) return add(diagnostics, "invalid_type", manifestId, path, `${path} must be an array.`); value.forEach((item, index) => { const itemPath = `${path}.${index}`; if (typeof item !== "string") return add(diagnostics, "invalid_item", manifestId, itemPath, `${itemPath} must be a string.`); if (options.itemPattern && !options.itemPattern.test(item)) add(diagnostics, "invalid_format", manifestId, itemPath, `${itemPath} has an invalid format.`); }); } function requireObject(source: Record, key: string, path: string, diagnostics: FeatureManifestDiagnostic[], manifestId: string | null): Record | null { const value = source[key]; if (value === undefined) { add(diagnostics, "missing_required", manifestId, path, `${path} is required.`); return null; } if (!isRecord(value)) { add(diagnostics, "invalid_type", manifestId, path, `${path} must be an object.`); return null; } return value; } function requireBoolean(source: Record, key: string, path: string, diagnostics: FeatureManifestDiagnostic[], manifestId: string | null) { const value = source[key]; if (value === undefined) return add(diagnostics, "missing_required", manifestId, path, `${path} is required.`); if (typeof value !== "boolean") add(diagnostics, "invalid_type", manifestId, path, `${path} must be a boolean.`); } function validateComponents(input: Record, diagnostics: FeatureManifestDiagnostic[], manifestId: string | null) { if (input.components === undefined) return; if (!Array.isArray(input.components)) return add(diagnostics, "invalid_type", manifestId, "components", "components must be an array."); input.components.forEach((component, index) => { const path = `components.${index}`; if (!isRecord(component)) return add(diagnostics, "invalid_item", manifestId, path, `${path} must be an object.`); requireString(component, "id", `${path}.id`, diagnostics, manifestId, { pattern: ID_PATTERN }); requireString(component, "title", `${path}.title`, diagnostics, manifestId); requireString(component, "rationale", `${path}.rationale`, diagnostics, manifestId); requireStringArray(component, "codeAreas", `${path}.codeAreas`, diagnostics, manifestId); if (component.notes !== undefined && typeof component.notes !== "string") add(diagnostics, "invalid_type", manifestId, `${path}.notes`, `${path}.notes must be a string.`); }); } function validateIntegration(input: Record, diagnostics: FeatureManifestDiagnostic[], manifestId: string | null) { const integration = requireObject(input, "integration", "integration", diagnostics, manifestId); if (!integration) return; requireEnum(integration, "ownership", OWNERSHIPS, "integration.ownership", diagnostics, manifestId); const surfaces = requireObject(integration, "surfaces", "integration.surfaces", diagnostics, manifestId); if (surfaces) { requireStringArray(surfaces, "adminRoutes", "integration.surfaces.adminRoutes", diagnostics, manifestId); requireStringArray(surfaces, "tenantRoutes", "integration.surfaces.tenantRoutes", diagnostics, manifestId); requireStringArray(surfaces, "publicRoutes", "integration.surfaces.publicRoutes", diagnostics, manifestId); requireStringArray(surfaces, "apiRoutes", "integration.surfaces.apiRoutes", diagnostics, manifestId); } const configuration = requireObject(integration, "configuration", "integration.configuration", diagnostics, manifestId); if (configuration) { requireStringArray(configuration, "admin", "integration.configuration.admin", diagnostics, manifestId); requireStringArray(configuration, "tenant", "integration.configuration.tenant", diagnostics, manifestId); requireStringArray(configuration, "environment", "integration.configuration.environment", diagnostics, manifestId); requireStringArray(configuration, "secrets", "integration.configuration.secrets", diagnostics, manifestId); } const workers = requireObject(integration, "workers", "integration.workers", diagnostics, manifestId); if (workers) { requireBoolean(workers, "required", "integration.workers.required", diagnostics, manifestId); requireStringArray(workers, "queues", "integration.workers.queues", diagnostics, manifestId); requireStringArray(workers, "jobs", "integration.workers.jobs", diagnostics, manifestId); requireStringArray(workers, "notes", "integration.workers.notes", diagnostics, manifestId); } requireStringArray(integration, "externalProviders", "integration.externalProviders", diagnostics, manifestId); requireStringArray(integration, "permissions", "integration.permissions", diagnostics, manifestId, { itemPattern: PERMISSION_TOKEN_PATTERN }); requireStringArray(integration, "auditEvents", "integration.auditEvents", diagnostics, manifestId, { itemPattern: AUDIT_EVENT_PATTERN }); requireStringArray(integration, "billingImpacts", "integration.billingImpacts", diagnostics, manifestId); requireStringArray(integration, "uat", "integration.uat", diagnostics, manifestId); } function isValidDate(value: string) { if (!DATE_PATTERN.test(value)) return false; const date = new Date(`${value}T00:00:00.000Z`); return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value; } export function validateFeatureManifestShape(input: unknown, context: FeatureManifestValidationContext = {}): FeatureManifestValidationResult { if (!isRecord(input)) { const path = context.path ?? "$"; return { ok: false, manifest: null, diagnostics: [{ code: "invalid_type", manifestId: context.manifestId ?? null, path, message: `${path} must be an object.` }] }; } const diagnostics: FeatureManifestDiagnostic[] = []; const manifestId = manifestIdFor(input, context); requireString(input, "schemaVersion", "schemaVersion", diagnostics, manifestId, { constValue: "1.0" }); requireString(input, "id", "id", diagnostics, manifestId, { pattern: ID_PATTERN }); requireString(input, "title", "title", diagnostics, manifestId, { nonEmpty: true }); requireEnum(input, "classification", CLASSIFICATIONS, "classification", diagnostics, manifestId); requireEnum(input, "status", STATUSES, "status", diagnostics, manifestId); requireString(input, "owner", "owner", diagnostics, manifestId); requireString(input, "description", "description", diagnostics, manifestId); requireStringArray(input, "rationale", "rationale", diagnostics, manifestId); requireStringArray(input, "codeAreas", "codeAreas", diagnostics, manifestId); requireStringArray(input, "dependencies", "dependencies", diagnostics, manifestId, { itemPattern: ID_PATTERN }); requireStringArray(input, "consumers", "consumers", diagnostics, manifestId); validateComponents(input, diagnostics, manifestId); validateIntegration(input, diagnostics, manifestId); const boundaries = requireObject(input, "boundaries", "boundaries", diagnostics, manifestId); if (boundaries) { requireStringArray(boundaries, "mustKeep", "boundaries.mustKeep", diagnostics, manifestId); requireStringArray(boundaries, "mayMoveToPlugin", "boundaries.mayMoveToPlugin", diagnostics, manifestId); requireStringArray(boundaries, "mustNotTouch", "boundaries.mustNotTouch", diagnostics, manifestId); } const pruning = requireObject(input, "pruning", "pruning", diagnostics, manifestId); if (pruning) { requireString(pruning, "phase", "pruning.phase", diagnostics, manifestId); requireEnum(pruning, "action", PRUNING_ACTIONS, "pruning.action", diagnostics, manifestId); requireStringArray(pruning, "notes", "pruning.notes", diagnostics, manifestId); } const validation = requireObject(input, "validation", "validation", diagnostics, manifestId); if (validation) { requireStringArray(validation, "source", "validation.source", diagnostics, manifestId); requireString(validation, "lastReviewed", "validation.lastReviewed", diagnostics, manifestId); if (typeof validation.lastReviewed === "string" && !isValidDate(validation.lastReviewed)) add(diagnostics, "invalid_format", manifestId, "validation.lastReviewed", "validation.lastReviewed must be an ISO date in YYYY-MM-DD format."); } return { ok: diagnostics.length === 0, manifest: diagnostics.length === 0 ? (input as unknown as FeatureManifest) : null, diagnostics }; }