Function ValidateLockSchemaCompatibility

pkg/workflow/lock_validation.go:37–68

ValidateLockSchemaCompatibility validates that a lock file's schema is compatible. Returns an error with actionable guidance if incompatible.

(content string, lockFilePath string)

// ValidateLockSchemaCompatibility validates that a lock file's schema is compatible.
// Returns an error with actionable guidance if incompatible.
func ValidateLockSchemaCompatibility(content string, lockFilePath string) error {
	metadata, isLegacy, err := ExtractMetadataFromLockFile(content)
	if err != nil {
		return fmt.Errorf("failed to extract metadata from %s: %w", lockFilePath, err)
	}

	// Legacy files (no schema version) are supported for backward compatibility
	if isLegacy {
		lockSchemaLog.Printf("Legacy lock file accepted: %s", lockFilePath)
		return nil
	}

	// Missing metadata entirely is suspicious
	if metadata == nil {
		return fmt.Errorf("lock file %s is missing required metadata. This file may be corrupted or manually edited.\n\nTo fix this, recompile the workflow:\n  gh aw compile %s",
			lockFilePath,
			strings.TrimSuffix(lockFilePath, ".lock.yml")+".md")
	}

	// Check schema compatibility
	if !IsSchemaVersionSupported(metadata.SchemaVersion) {
		// Future version detected
		return fmt.Errorf("lock file %s uses unsupported schema version '%s'.\n\nThis file was generated by a newer version of gh-aw that uses incompatible features.\n\nSupported versions: %s\n\nTo fix this:\n  1. Upgrade gh-aw: gh extension upgrade gh-aw\n  2. Or downgrade the lock file by editing the source .md file and recompiling:\n     gh aw compile %s",
			lockFilePath,
			metadata.SchemaVersion,
			formatSupportedVersions(),
			strings.TrimSuffix(lockFilePath, ".lock.yml")+".md")
	}

	lockSchemaLog.Printf("Lock file schema validated: %s (version=%s)", lockFilePath, metadata.SchemaVersion)
	return nil
}

// ValidateActionSHAsInLockFile validates action SHAs in a lock file and emits warnings
func ValidateActionSHAsInLockFile(ctx context.Context, lockFilePath string, cache *ActionCache, verbose bool) error {