@celilo/cli 0.1.0

package/src/manifest/validate.ts

@@ -0,0 +1,415 @@
+import { KNOWN_CAPABILITY_NAMES } from '@celilo/capabilities';
+import { parse as parseYaml } from 'yaml';
+import type { ZodError } from 'zod';
+import { validateModuleZoneRequirements } from '../services/zone-policy';
+import { resolveContract, supportedContractVersions } from './contracts';
+import { ModuleManifestSchema } from './schema';
+import type { ModuleManifest } from './schema';
+
+/**
+ * Validation result types
+ */
+export interface ValidationSuccess {
+  success: true;
+  data: ModuleManifest;
+}
+
+export interface ValidationError {
+  success: false;
+  errors: Array<{
+    path: string;
+    message: string;
+  }>;
+}
+
+export type ValidationResult = ValidationSuccess | ValidationError;
+
+/**
+ * Parse YAML string into unknown object
+ * This is the first stage - just parse the YAML
+ */
+function parseManifestYaml(yamlContent: string): unknown {
+  try {
+    return parseYaml(yamlContent);
+  } catch (error) {
+    throw new Error(
+      `Failed to parse YAML: ${error instanceof Error ? error.message : 'Unknown error'}`,
+    );
+  }
+}
+
+/**
+ * Format Zod errors into readable validation errors
+ */
+function formatZodErrors(error: ZodError): ValidationError {
+  return {
+    success: false,
+    errors: error.errors.map((err) => ({
+      path: err.path.join('.'),
+      message: err.message,
+    })),
+  };
+}
+
+/**
+ * Validate module manifest
+ *
+ * Policy function (Rule 10.1) - validates input only
+ * Does NOT perform any side effects or business logic
+ *
+ * @param yamlContent - Raw YAML string from manifest.yml
+ * @returns Validation result with parsed manifest or errors
+ */
+export function validateManifest(yamlContent: string): ValidationResult {
+  if (!yamlContent || yamlContent.trim().length === 0) {
+    return {
+      success: false,
+      errors: [{ path: '', message: 'Manifest content cannot be empty' }],
+    };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = parseManifestYaml(yamlContent);
+  } catch (error) {
+    return {
+      success: false,
+      errors: [
+        {
+          path: '',
+          message: error instanceof Error ? error.message : 'Failed to parse YAML',
+        },
+      ],
+    };
+  }
+
+  const result = ModuleManifestSchema.safeParse(parsed);
+
+  if (!result.success) {
+    return formatZodErrors(result.error);
+  }
+
+  return {
+    success: true,
+    data: result.data,
+  };
+}
+
+/**
+ * Validate that required capabilities exist
+ *
+ * Policy function - checks capability requirements against available capabilities
+ * Does NOT perform database queries - caller provides capability list
+ *
+ * @param manifest - Validated manifest
+ * @param availableCapabilities - List of capability names available in the system
+ * @returns Validation errors if any required capabilities are missing
+ */
+export function validateCapabilityRequirements(
+  manifest: ModuleManifest,
+  availableCapabilities: string[],
+): ValidationError | null {
+  const errors: Array<{ path: string; message: string }> = [];
+
+  for (const required of manifest.requires.capabilities) {
+    if (!availableCapabilities.includes(required.name)) {
+      errors.push({
+        path: `requires.capabilities.${required.name}`,
+        message: `Required capability '${required.name}' is not provided by any installed module`,
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    return { success: false, errors };
+  }
+
+  return null;
+}
+
+/**
+ * Validate that every capability name listed in `requires.capabilities` and
+ * `optional.capabilities` is a known capability in the framework registry.
+ *
+ * Policy function (Rule 10.1) — pure validation, no side effects.
+ *
+ * Why (HOOK_API_V2 Phase 3 / D3): catches typos and stale references in the
+ * manifest before they become silent runtime no-ops. Without this check, a
+ * misspelled capability name (`requires: [{ name: dns_register }]`) would
+ * pass schema validation, fail to load any provider, and give the user a
+ * confusing "capability not provided" error far downstream. The known
+ * registry lives in `@celilo/capabilities` so the TS interface and the
+ * runtime list stay in sync.
+ *
+ * @param manifest - Validated manifest
+ * @returns Validation error if any name is unknown, null otherwise
+ */
+export function validateCapabilityNames(manifest: ModuleManifest): ValidationError | null {
+  const errors: Array<{ path: string; message: string }> = [];
+  const knownNames: readonly string[] = KNOWN_CAPABILITY_NAMES;
+
+  for (const required of manifest.requires.capabilities) {
+    if (!knownNames.includes(required.name)) {
+      errors.push({
+        path: `requires.capabilities.${required.name}`,
+        message: `Unknown capability '${required.name}'. Known capabilities: ${knownNames.join(', ')}.`,
+      });
+    }
+  }
+
+  for (const opt of manifest.optional?.capabilities ?? []) {
+    if (!knownNames.includes(opt.name)) {
+      errors.push({
+        path: `optional.capabilities.${opt.name}`,
+        message: `Unknown capability '${opt.name}'. Known capabilities: ${knownNames.join(', ')}.`,
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    return { success: false, errors };
+  }
+
+  return null;
+}
+
+/**
+ * Validate that variable sources are valid
+ *
+ * Policy function - checks that capability references in variables exist
+ *
+ * @param manifest - Validated manifest
+ * @returns Validation errors if any variable sources are invalid
+ */
+export function validateVariableSources(manifest: ModuleManifest): ValidationError | null {
+  const errors: Array<{ path: string; message: string }> = [];
+
+  // Variables can import from capabilities listed in requires OR optional —
+  // both are declared dependencies of this module.
+  const declaredCapabilityNames = new Set([
+    ...manifest.requires.capabilities.map((c) => c.name),
+    ...(manifest.optional?.capabilities ?? []).map((c) => c.name),
+  ]);
+
+  for (const varImport of manifest.variables.imports) {
+    if (varImport.source === 'capability') {
+      const capabilityName = varImport.from.split('.')[0];
+
+      if (!capabilityName) {
+        errors.push({
+          path: `variables.imports.${varImport.name}`,
+          message: `Variable '${varImport.name}' has invalid capability reference: '${varImport.from}'`,
+        });
+        continue;
+      }
+
+      if (!declaredCapabilityNames.has(capabilityName)) {
+        errors.push({
+          path: `variables.imports.${varImport.name}`,
+          message: `Variable '${varImport.name}' imports capability '${capabilityName}' but module does not declare it in requires or optional`,
+        });
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return { success: false, errors };
+  }
+
+  return null;
+}
+
+/**
+ * Validate zone requirements for module capabilities
+ *
+ * Policy function - checks that module provides capabilities in correct zones
+ *
+ * Zone-based policy enforcement
+ * - Modules providing well-known capabilities must be deployed to specific zones
+ * - Example: public_web must be in 'dmz' zone (defense perimeter, internet-facing)
+ * - Example: public_web must be in 'dmz' zone (defense perimeter)
+ *
+ * @param manifest - Validated manifest
+ * @returns Validation errors if zone requirements are violated
+ */
+export function validateZoneRequirements(manifest: ModuleManifest): ValidationError | null {
+  const errors: Array<{ path: string; message: string }> = [];
+
+  // Check if module has infrastructure spec (requires.machine)
+  const hasInfrastructureSpec = manifest.requires?.machine;
+
+  // If module requires infrastructure, zone field is mandatory
+  if (hasInfrastructureSpec) {
+    const zone = manifest.requires?.machine?.zone;
+
+    if (!zone) {
+      errors.push({
+        path: 'requires.machine.zone',
+        message: 'Zone field is required for modules with infrastructure requirements',
+      });
+      // Can't validate zone requirements without a zone
+      return { success: false, errors };
+    }
+
+    // Validate zone requirements for provided capabilities
+    if (manifest.provides.capabilities.length > 0) {
+      const capabilityNames = manifest.provides.capabilities.map((cap) => cap.name);
+      const zoneValidation = validateModuleZoneRequirements(capabilityNames, zone);
+
+      if (!zoneValidation.valid && zoneValidation.error) {
+        errors.push({
+          path: 'requires.machine.zone',
+          message: zoneValidation.error,
+        });
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return { success: false, errors };
+  }
+
+  return null;
+}
+
+/**
+ * Validate that the prefix of every variable's `derive_from` template
+ * matches its declared `source`.
+ *
+ * Why: a manifest like
+ *   `source: capability, derive_from: "$system:primary_domain"`
+ * is incoherent — the source says the value comes from a capability but the
+ * derivation reads from system config. Zod can't catch this because both
+ * fields are individually valid; this validator enforces the coherence rule
+ * at runtime so the bug fails import instead of confusing a future reader.
+ *
+ * Rules:
+ * - `source: capability` → `derive_from` must only reference `$capability:`
+ *   tokens (and may also include `{var}` placeholders).
+ * - `source: system` → `derive_from` must only reference `$system:` tokens
+ *   (and `{var}` placeholders).
+ * - Other sources (`user`, `infrastructure`, `terraform`) — `derive_from` is
+ *   optional and unconstrained; we don't check the prefix.
+ */
+export function validateDeriveFromSources(manifest: ModuleManifest): ValidationError | null {
+  const errors: Array<{ path: string; message: string }> = [];
+
+  // Match $foo:bar tokens (foo is the prefix, bar is the path)
+  const tokenPattern = /\$([a-z_]+):/g;
+
+  for (const variable of manifest.variables.owns) {
+    if (!variable.derive_from) continue;
+
+    let expected: string | null = null;
+    if (variable.source === 'capability') expected = 'capability';
+    else if (variable.source === 'system') expected = 'system';
+    if (!expected) continue;
+
+    const tokens = [...variable.derive_from.matchAll(tokenPattern)].map((m) => m[1]);
+    const offending = tokens.filter((t) => t !== expected);
+    if (offending.length > 0) {
+      const unique = Array.from(new Set(offending)).join(', ');
+      errors.push({
+        path: `variables.owns.${variable.name}.derive_from`,
+        message: `Variable '${variable.name}' has source: ${variable.source} but derive_from references $${unique}: tokens. Either change source to match or rewrite the derivation.`,
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    return { success: false, errors };
+  }
+
+  return null;
+}
+
+/**
+ * Validate that every declared hook is part of the contract version the
+ * manifest targets.
+ *
+ * Why: the Zod schema's `.strict()` on the hooks block already prevents
+ * unknown hook names structurally, but the contract registry is the
+ * authoritative list of which hooks Celilo will actually invoke. This
+ * validator surfaces a clear error if someone declares a hook that the
+ * declared contract version doesn't promise to call.
+ */
+export function validateHookContract(manifest: ModuleManifest): ValidationError | null {
+  const errors: Array<{ path: string; message: string }> = [];
+
+  const contract = resolveContract(manifest.celilo_contract);
+  if (!contract) {
+    errors.push({
+      path: 'celilo_contract',
+      message: `Unsupported celilo_contract version '${manifest.celilo_contract}'. Supported: ${supportedContractVersions().join(', ')}`,
+    });
+    return { success: false, errors };
+  }
+
+  if (!manifest.hooks) {
+    return null;
+  }
+
+  for (const hookName of Object.keys(manifest.hooks)) {
+    if (!(hookName in contract.hooks)) {
+      errors.push({
+        path: `hooks.${hookName}`,
+        message: `Hook '${hookName}' is not part of celilo_contract ${manifest.celilo_contract}. Known hooks: ${Object.keys(contract.hooks).join(', ')}`,
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    return { success: false, errors };
+  }
+
+  return null;
+}
+
+/**
+ * Validate that capability data templates in `provides.capabilities[].data`
+ * do not contain cross-capability references.
+ *
+ * Why (D9 firm rule): well-known and module-provided capability data
+ * templates must not embed `$capability:other_capability.x` references. If a
+ * capability value depends on another capability, the providing module
+ * derives it in its own variables and exposes the resolved value through
+ * `provides.capabilities[].data`. Cross-capability references in data
+ * templates create implicit ordering dependencies between capability
+ * providers, which the variable resolver isn't designed to handle and which
+ * make the dependency graph hard to reason about.
+ */
+export function validateProvidesNoCrossCapabilityRefs(
+  manifest: ModuleManifest,
+): ValidationError | null {
+  const errors: Array<{ path: string; message: string }> = [];
+
+  function walk(node: unknown, path: string): void {
+    if (typeof node === 'string') {
+      if (node.includes('$capability:')) {
+        errors.push({
+          path,
+          message: `Capability data template at ${path} contains a $capability: reference. Per D9, capability data must not cross-reference other capabilities — derive the value in this module's variables instead and expose the resolved value here.`,
+        });
+      }
+      return;
+    }
+    if (node === null || typeof node !== 'object') return;
+    if (Array.isArray(node)) {
+      node.forEach((item, idx) => walk(item, `${path}[${idx}]`));
+      return;
+    }
+    for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
+      walk(value, `${path}.${key}`);
+    }
+  }
+
+  for (const cap of manifest.provides.capabilities) {
+    walk(cap.data, `provides.capabilities.${cap.name}.data`);
+  }
+
+  if (errors.length > 0) {
+    return { success: false, errors };
+  }
+
+  return null;
+}