Merge pull request #157 from shift-editor/glyph-compatibility-diagnostics

Add structured glyph compatibility diagnostics

Author: kostyafarber

crates/shift-font/docs/DOCS.md

@@ -44,6 +44,7 @@ crates/shift-font/src/
 - `GlyphLayer` is authored editable data for one glyph at one source.
 - `InterpolationBasis` is coordinate-independent variation math for an ordered source set. It contains normalized supports and source coefficient rows, never glyph coordinates or metrics.
 - `GlyphInterpolation` combines a reusable basis with one glyph's compatible authored source values. Its default-source template owns topology.
+- `LayerCompatibility` records every hard structural difference between an interpolation reference layer and another source layer. `LayerDifference` retains ordered path, node, anchor, and component evidence for diagnostics.
 - `GlyphProjection` is a compact location-independent glyph payload: fallback shape, optional compatible interpolation, exact-source shapes for incompatible topology, and component identities.
 - `FontProjection` is a read-only, location-bound view that reuses resolved component layers across one or many glyph requests.
 - `ResolvedGlyph` is derived, flattened geometry plus x advance. An existing blank glyph resolves to an empty contour list; a missing glyph resolves to `None`.
@@ -72,6 +73,10 @@ Stable IDs are identity. Names and Unicode values are editable metadata.
 
 `Font::glyph_interpolation(glyph_id)` builds compatible source values over an `InterpolationBasis`. The default source defines structural topology. The basis depends only on axes and ordered source locations, so the same mechanism can interpolate other numeric domains without copying glyph concepts into them.
 
+`GlyphLayer::interpolation_compatibility_with(source)` is the source of truth for hard structural compatibility. The receiver is the interpolation reference. It compares paths, nodes, anchors, and components in authored order and never sorts them. OpenType requires corresponding outlines to have the same contour and point structure, and `gvar` addresses composite components by their ordered component index. Shift therefore treats component identity and order as structural. See the [OpenType Font Variations overview](https://learn.microsoft.com/en-us/typography/opentype/spec/otvaroverview), the [`gvar` composite processing rules](https://learn.microsoft.com/en-us/typography/opentype/spec/gvar#point-numbers-and-processing-for-composite-glyphs), and [fontTools interpolatability diagnostics](https://fonttools.readthedocs.io/en/latest/varLib/interpolatable.html).
+
+Coordinates, advance width, smooth flags, anchor positions, and component transforms are interpolated values, not structural compatibility. Matching anchor count, names, and order is currently a Shift-specific restriction because anchor positions share the ordered glyph interpolation vector; OpenType `gvar` and fontTools do not define source-anchor compatibility. Variable component scale or matrix transforms need a separate export diagnostic because `gvar` varies component placement rather than those transforms. Correspondence and quality warnings such as contour order, wrong start point, and kinks are separate from this hard structural result.
+
 `Font::glyph_projection(glyph_id)` preserves the preferred fallback, compatible interpolation, and incompatible authored source shapes without resolving a location. The fallback is normally the default-source layer and uses the glyph's preferred layer when the default source has no layer for that glyph. A renderer can retain this compact payload and combine its basis with current authored source signals. No arbitrary location result is persisted.
 
 `Font::source_metric_interpolation()` combines the same coordinate-independent basis with complete master-source metric vectors. Optional technical fields participate only when every master authors them, so interpolation does not invent sparse values.

crates/shift-font/src/interpolation.rs

@@ -9,9 +9,11 @@ use fontdrasil::variations::VariationModel;
 
 use crate::{Axis, AxisId, CoreError, CoreResult, Font, GlyphId, GlyphLayer, Location, SourceId};
 
+mod compatibility;
 mod metrics;
 mod values;
 
+pub use compatibility::{LayerCompatibility, LayerDifference};
 pub use metrics::{
     ResolvedSourceMetrics, SourceMetricField, SourceMetricInterpolation, SourceMetricValues,
 };
@@ -253,7 +255,10 @@ impl Font {
             let Some(layer) = glyph.layer_for_source(source.id()) else {
                 continue;
             };
-            if !layers_are_compatible(default_layer, layer) {
+            if !default_layer
+                .interpolation_compatibility_with(layer)
+                .is_compatible()
+            {
                 continue;
             }
 
@@ -358,46 +363,6 @@ fn normalized_location(location: &Location, axes: &[Axis]) -> NormalizedLocation
         .collect()
 }
 
-/// Returns whether two layers can share structure-ordered interpolation values.
-pub(crate) fn layers_are_compatible(template: &GlyphLayer, candidate: &GlyphLayer) -> bool {
-    if template.contours().len() != candidate.contours().len()
-        || template.anchors().len() != candidate.anchors().len()
-        || template.components().len() != candidate.components().len()
-    {
-        return false;
-    }
-
-    for (template, candidate) in template.contours_iter().zip(candidate.contours_iter()) {
-        if template.is_closed() != candidate.is_closed()
-            || template.points().len() != candidate.points().len()
-        {
-            return false;
-        }
-
-        if template
-            .points()
-            .iter()
-            .zip(candidate.points())
-            .any(|(template, candidate)| template.is_on_curve() != candidate.is_on_curve())
-        {
-            return false;
-        }
-    }
-
-    if template
-        .anchors_iter()
-        .zip(candidate.anchors_iter())
-        .any(|(template, candidate)| template.name() != candidate.name())
-    {
-        return false;
-    }
-
-    !template
-        .components_iter()
-        .zip(candidate.components_iter())
-        .any(|(template, candidate)| template.base_glyph_id() != candidate.base_glyph_id())
-}
-
 fn region_scalar(
     region: &InterpolationRegion,
     location: &Location,
@@ -520,7 +485,9 @@ mod tests {
             .unwrap();
         point.set_smooth(!point.is_smooth());
 
-        assert!(super::layers_are_compatible(template, &candidate));
+        assert!(template
+            .interpolation_compatibility_with(&candidate)
+            .is_compatible());
     }
 
     #[test]