Implement artifact-level render command with Markdown output and update docs

internal/artifact/output_artifact.go

@@ -0,0 +1,178 @@
+package artifact
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/seriatim/schema"
+)
+
+const (
+	OutputSchemaMinimal      = schema.OutputSchemaMinimal
+	OutputSchemaIntermediate = schema.OutputSchemaIntermediate
+	OutputSchemaFull         = schema.OutputSchemaFull
+)
+
+// OutputArtifact stores a parsed seriatim output artifact of one supported schema.
+type OutputArtifact struct {
+	Schema       string
+	Full         *schema.Transcript
+	Intermediate *schema.IntermediateTranscript
+	Minimal      *schema.MinimalTranscript
+}
+
+// ParseOutputArtifactJSON parses and validates serialized seriatim output JSON.
+func ParseOutputArtifactJSON(data []byte) (OutputArtifact, error) {
+	var decoded any
+	if err := json.Unmarshal(data, &decoded); err != nil {
+		return OutputArtifact{}, fmt.Errorf("input JSON is malformed: %w", err)
+	}
+
+	var full schema.Transcript
+	if err := json.Unmarshal(data, &full); err == nil {
+		if err := schema.ValidateTranscript(full); err == nil {
+			return OutputArtifact{
+				Schema: OutputSchemaFull,
+				Full:   &full,
+			}, nil
+		}
+	}
+
+	var intermediate schema.IntermediateTranscript
+	if err := json.Unmarshal(data, &intermediate); err == nil {
+		if err := schema.ValidateIntermediateTranscript(intermediate); err == nil {
+			return OutputArtifact{
+				Schema:       OutputSchemaIntermediate,
+				Intermediate: &intermediate,
+			}, nil
+		}
+	}
+
+	var minimal schema.MinimalTranscript
+	if err := json.Unmarshal(data, &minimal); err == nil {
+		if err := schema.ValidateMinimalTranscript(minimal); err == nil {
+			return OutputArtifact{
+				Schema:  OutputSchemaMinimal,
+				Minimal: &minimal,
+			}, nil
+		}
+	}
+
+	return OutputArtifact{}, fmt.Errorf("input JSON is not a valid seriatim output artifact")
+}
+
+// Value returns the output payload value for serialization.
+func (artifact OutputArtifact) Value() any {
+	switch artifact.Schema {
+	case OutputSchemaFull:
+		if artifact.Full == nil {
+			return schema.Transcript{}
+		}
+		return *artifact.Full
+	case OutputSchemaIntermediate:
+		if artifact.Intermediate == nil {
+			return schema.IntermediateTranscript{}
+		}
+		return *artifact.Intermediate
+	case OutputSchemaMinimal:
+		if artifact.Minimal == nil {
+			return schema.MinimalTranscript{}
+		}
+		return *artifact.Minimal
+	default:
+		return nil
+	}
+}
+
+// SegmentCount returns the number of segments in the output artifact.
+func (artifact OutputArtifact) SegmentCount() int {
+	switch artifact.Schema {
+	case OutputSchemaFull:
+		if artifact.Full == nil {
+			return 0
+		}
+		return len(artifact.Full.Segments)
+	case OutputSchemaIntermediate:
+		if artifact.Intermediate == nil {
+			return 0
+		}
+		return len(artifact.Intermediate.Segments)
+	case OutputSchemaMinimal:
+		if artifact.Minimal == nil {
+			return 0
+		}
+		return len(artifact.Minimal.Segments)
+	default:
+		return 0
+	}
+}
+
+// Application returns output artifact metadata application name.
+func (artifact OutputArtifact) Application() string {
+	switch artifact.Schema {
+	case OutputSchemaFull:
+		if artifact.Full == nil {
+			return ""
+		}
+		return artifact.Full.Metadata.Application
+	case OutputSchemaIntermediate:
+		if artifact.Intermediate == nil {
+			return ""
+		}
+		return artifact.Intermediate.Metadata.Application
+	case OutputSchemaMinimal:
+		if artifact.Minimal == nil {
+			return ""
+		}
+		return artifact.Minimal.Metadata.Application
+	default:
+		return ""
+	}
+}
+
+// Version returns output artifact metadata version.
+func (artifact OutputArtifact) Version() string {
+	switch artifact.Schema {
+	case OutputSchemaFull:
+		if artifact.Full == nil {
+			return ""
+		}
+		return artifact.Full.Metadata.Version
+	case OutputSchemaIntermediate:
+		if artifact.Intermediate == nil {
+			return ""
+		}
+		return artifact.Intermediate.Metadata.Version
+	case OutputSchemaMinimal:
+		if artifact.Minimal == nil {
+			return ""
+		}
+		return artifact.Minimal.Metadata.Version
+	default:
+		return ""
+	}
+}
+
+// FullPayload returns the full-schema payload when present.
+func (artifact OutputArtifact) FullPayload() (*schema.Transcript, error) {
+	if artifact.Full == nil {
+		return nil, fmt.Errorf("full artifact payload is missing")
+	}
+	return artifact.Full, nil
+}
+
+// IntermediatePayload returns the intermediate-schema payload when present.
+func (artifact OutputArtifact) IntermediatePayload() (*schema.IntermediateTranscript, error) {
+	if artifact.Intermediate == nil {
+		return nil, fmt.Errorf("intermediate artifact payload is missing")
+	}
+	return artifact.Intermediate, nil
+}
+
+// MinimalPayload returns the minimal-schema payload when present.
+func (artifact OutputArtifact) MinimalPayload() (*schema.MinimalTranscript, error) {
+	if artifact.Minimal == nil {
+		return nil, fmt.Errorf("minimal artifact payload is missing")
+	}
+	return artifact.Minimal, nil
+}