Diagnostics Guide

This page explains the shared structured diagnostics model used across Buffalo Wings workflows. Use it when you want to understand what a diagnostic contains, how severities and locations are meant to be interpreted, and which code namespaces are currently used by the airfoil workflows. For the design-oriented source of truth, see docs/design/foundations/diagnostics_model.md in the repository.

Canonical API Surface

The canonical shared diagnostics API lives in buffalo_core.diagnostics. Subsystem packages may re-export these types for convenience, but the diagnostics package is the stable cross-workflow reference point.

buffalo_core.diagnostics.DiagnosticSeverity

Severity level for a structured diagnostic.

buffalo_core.diagnostics.DiagnosticLocation

Optional context identifying where a diagnostic applies.

buffalo_core.diagnostics.Diagnostic

Structured diagnostic suitable for programmatic reporting.

buffalo_core.diagnostics.DiagnosticReport

Grouped diagnostics emitted by one workflow.

buffalo_core.diagnostics.OperationResult

Return one value together with structured diagnostics.

Core Types

DiagnosticSeverity is the severity enum with the machine-readable values error, warning, and info. DiagnosticLocation adds optional context through object_path, field_path, and geometry_region. Diagnostic is one structured entry with severity, code, message, and optional location. DiagnosticReport is an ordered collection of Diagnostic entries with convenience filters such as has_errors and for_severity(...). OperationResult[T] wraps one workflow payload together with the DiagnosticReport produced while creating it.

Severity Meaning

Use error when a report-oriented workflow intentionally returns a result object but the associated operation was not valid or usable. Use warning for non-fatal issues, degraded quality, advisories, or caller-visible caveats that should not automatically stop the workflow. Use info for provenance, normalization, detection, or status details that are useful to show but are not themselves problems.

In Buffalo Wings, hard failures are still primarily represented by exceptions. Structured diagnostics supplement exceptions when a workflow can still return something meaningful or when a result object is the intended API boundary.

Location Meaning

object_path identifies the logical workflow object or schema object associated with the diagnostic. Examples include airfoil, airfoil.sample, and file-source specific workflow roots.

field_path localizes a diagnostic to a schema field or payload attribute. Examples include params.p, path, and slope.

geometry_region localizes the message to a geometric area when that helps the caller present the issue. Examples include leading_edge, trailing_edge, upper_surface, and lower_surface.

Not every diagnostic needs every location field. Callers should treat missing location fields as “not specified” rather than as an error in the diagnostic itself.

Diagnostic Codes

Diagnostic codes are intended to be stable and machine-readable. They are suitable for tests, filtering, CLI presentation, and future GUI routing. The current convention is a dotted namespace that starts with the package area and then narrows by workflow family.

Examples of current code families include:

  • airfoil.validation.* for schema and rule-validation diagnostics.

  • airfoil.support.* for supported-versus-unsupported runtime capability diagnostics.

  • airfoil.surface_sampling.* for downstream sampling advisories.

  • airfoil.info.* for informational file and workflow notes.

The exact set of active codes is defined by the workflows that emit them. The validation modules under src/buffalo_wings/airfoil/internal/validation/ and the sampling workflow in src/buffalo_wings/airfoil/internal/sampling.py are the current implementation references. For the current rendered inventory of implemented code families, see Diagnostic Code Catalog.

User-Facing Workflow Patterns

The airfoil validation workflow returns AirfoilValidationResult, which carries a DiagnosticReport. Use this path when you want stable feedback for malformed schema content, unsupported runtime families, or file-backed source issues without relying only on exceptions.

The diagnostics-aware airfoil sampling workflows return OperationResult[AirfoilSurfaceSamples]. Use sample_airfoil_result(...), sample_airfoil_at_xi_result(...), or sample_airfoil_at_arc_length_result(...) when you want typed surface samples together with explicit diagnostics handling.

Example:

import buffalo_wings.airfoil as bwa

airfoil = bwa.AirfoilFactory.naca4_from_designation("2412")
result = bwa.sample_airfoil_result(
    airfoil,
    num_points_per_surface=11,
    warning_policy="diagnostics_only",
)

if result.has_warnings:
    warning_entries = result.diagnostics.for_severity(
        bwa.DiagnosticSeverity.WARNING
    )

Developer Guidance

Use diagnostics at workflow boundaries rather than on low-level geometry primitives. Geometry methods such as xy(...), xy_u(...), k(...), and parameter-conversion helpers should generally stay exception-first and should not return diagnostics directly.

When adding a new diagnostics-aware workflow:

  1. Reuse buffalo_core.diagnostics rather than introducing local diagnostic types.

  2. Choose stable dotted diagnostic codes.

  3. Add location data when it materially helps the caller route or present the message.

  4. Prefer a dedicated workflow result type or OperationResult[T] rather than returning raw (value, diagnostics) tuples.

  5. Keep diagnostics queryable enough for direct CLI or GUI presentation.

Current Airfoil Examples

Current validation workflows already emit diagnostics such as malformed-field errors, unsupported-family diagnostics, file-format detection notes, and point-layout problems. Current sampling workflows emit the airfoil.surface_sampling.slope_singularity warning with field_path="slope" and geometry_region="leading_edge".

For more workflow-specific detail, see: