feat(ai): implement op-design-lint Rust crate (S1)

Port the pen-ai-skills diagnostics layer to a new pure Rust crate
`op-design-lint`: 14 design-lint detectors, the detect_all aggregator,
apply_fixes / detect_and_fix, and golden parity tests against the TS
oracle. Wire it into op-mcp as the read-only debug_validation_report
tool, gated by OPENPENCIL_DEBUG_TOOLS=1.

Detectors: empty_paths, unexpected_rotation, excessive_frame_effects,
invisible_containers, text_explicit_heights, text_effect,
text_corner_radius, text_stroke, text_bg_contrast, edge_section_padding,
stacked_horizontal_padding, sibling_inconsistencies (+ check_consistency),
detect_all.

Also includes: node_util shared helpers + pen-core color/visibility
ports, node_mut field accessors, set_property issue->node mutation
dispatch, golden fixture corpus + TS dump script, structural-parity
test, a CI golden-drift guard, and the gitignore fix so the fixture
docs/ dir is tracked.

This branch's per-commit history was squashed: the original 28 commits
carried fabricated timestamps and could not be honestly reconstructed,
so the work is recorded as a single commit at its real completion time.

Author: finiking

.github/workflows/rust-check.yml

@@ -11,6 +11,8 @@ on:
       - 'deny.toml'
       - 'tools/check-jian-boundaries.sh'
       - 'tools/check-widget-boundary.sh'
+      - 'tools/dump-diagnostics-golden.ts'
+      - 'packages/pen-ai-skills/**'
       - '.github/workflows/rust-check.yml'
   push:
     branches: ['**']
@@ -24,6 +26,8 @@ on:
       - 'rustfmt.toml'
       - 'tools/check-jian-boundaries.sh'
       - 'tools/check-widget-boundary.sh'
+      - 'tools/dump-diagnostics-golden.ts'
+      - 'packages/pen-ai-skills/**'
       - '.github/workflows/rust-check.yml'
 
 jobs:
@@ -93,3 +97,27 @@ jobs:
       - uses: EmbarkStudios/cargo-deny-action@v2 # auto-updates within v2.x; runner cargo at this stage carries cargo-deny 0.18+ which handles modern transitive manifests (Phase 1 Task 1.8 finding)
         with:
           command: check
+
+  # S1 Plan C Task 6 — golden parity drift guard (spec §8, Risk R4).
+  # The TS `pen-ai-skills` diagnostics layer is the parity oracle for the
+  # Rust `op-design-lint` detectors. This job re-runs the golden-dump script
+  # against the live TS detectors and fails if the regenerated golden differs
+  # from the committed copy — catching a TS detector change that would
+  # silently stale the Rust parity baseline (`tests/parity.rs`).
+  diagnostics-golden-drift:
+    name: diagnostics golden drift
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: oven-sh/setup-bun@v2
+      - name: Install workspace dependencies
+        run: bun install --frozen-lockfile
+      - name: Regenerate diagnostics golden from the TS oracle
+        run: bun run tools/dump-diagnostics-golden.ts
+      - name: Fail on golden drift
+        # A non-empty diff means the committed golden no longer matches the
+        # TS detectors — regenerate locally (`bun run tools/dump-diagnostics-golden.ts`)
+        # and re-verify the Rust parity test before committing.
+        run: git diff --exit-code crates/op-design-lint/tests/fixtures/golden/

.gitignore

@@ -17,6 +17,9 @@ editor-*.png
 scripts/ab-corpus/runs/
 
 docs/
+# The bare `docs/` pattern above also shadows this test-fixture dir, which
+# MUST be tracked (the CI diagnostics-golden drift guard reads it).
+!crates/op-design-lint/tests/fixtures/docs/
 
 # Build outputs
 out/

Cargo.lock

@@ -0,0 +1,16 @@
+[package]
+name = "op-design-lint"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+description = "OpenPencil design diagnostics — pure detectors + fixes over jian PenDocument"
+
+[lib]
+name = "op_design_lint"
+path = "src/lib.rs"
+
+[dependencies]
+jian-ops-schema = { path = "../../vendor/jian/crates/jian-ops-schema" }
+serde = { workspace = true }
+serde_json = { workspace = true }

crates/op-design-lint/Cargo.toml

@@ -0,0 +1,158 @@
+//! WCAG color helpers shared across diagnostic detectors.
+//!
+//! Ported behaviour-for-behaviour from
+//! `packages/pen-ai-skills/src/diagnostics/color-utils.ts`. Any change here
+//! must keep the contrast epsilon tests green (spec §8).
+
+/// A parsed sRGB color. Alpha is dropped during parsing.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Rgb {
+    pub r: u8,
+    pub g: u8,
+    pub b: u8,
+}
+
+/// Parse `#rgb` / `#rrggbb` / `#rrggbbaa` to `Rgb` (alpha dropped).
+/// Returns `None` on parse failure — mirrors TS `parseHexColor`.
+pub fn parse_hex_color(s: &str) -> Option<Rgb> {
+    let hex = s.trim().strip_prefix('#')?;
+    if !(3..=8).contains(&hex.len()) || !hex.bytes().all(|b| b.is_ascii_hexdigit()) {
+        return None;
+    }
+    let expanded: String = if hex.len() == 3 {
+        hex.chars().flat_map(|c| [c, c]).collect()
+    } else {
+        hex.to_string()
+    };
+    // TS rejects lengths 4/5/7 here — only 6 (rrggbb) or 8 (rrggbbaa) pass.
+    if expanded.len() != 6 && expanded.len() != 8 {
+        return None;
+    }
+    let r = u8::from_str_radix(&expanded[0..2], 16).ok()?;
+    let g = u8::from_str_radix(&expanded[2..4], 16).ok()?;
+    let b = u8::from_str_radix(&expanded[4..6], 16).ok()?;
+    Some(Rgb { r, g, b })
+}
+
+/// WCAG 2.x relative luminance for sRGB. Returns 0.0–1.0.
+pub fn relative_luminance(c: Rgb) -> f64 {
+    fn lin(v: u8) -> f64 {
+        let s = v as f64 / 255.0;
+        if s <= 0.039_28 {
+            s / 12.92
+        } else {
+            ((s + 0.055) / 1.055).powf(2.4)
+        }
+    }
+    0.2126 * lin(c.r) + 0.7152 * lin(c.g) + 0.0722 * lin(c.b)
+}
+
+/// WCAG relative-luminance contrast ratio between two color strings.
+/// Returns `1.0` for identical strings (before parsing — mirrors TS),
+/// grows toward `21.0` as colors diverge, or `f64::INFINITY` if either
+/// string fails to parse (e.g. unresolved variable refs).
+pub fn color_contrast(a: &str, b: &str) -> f64 {
+    if a == b {
+        return 1.0;
+    }
+    let (Some(pa), Some(pb)) = (parse_hex_color(a), parse_hex_color(b)) else {
+        return f64::INFINITY;
+    };
+    let lum_a = relative_luminance(pa);
+    let lum_b = relative_luminance(pb);
+    let lighter = lum_a.max(lum_b);
+    let darker = lum_a.min(lum_b);
+    (lighter + 0.05) / (darker + 0.05)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const EPS: f64 = 1e-9;
+
+    #[test]
+    fn parse_hex_expands_shorthand_and_drops_alpha() {
+        assert_eq!(
+            parse_hex_color("#fff"),
+            Some(Rgb {
+                r: 255,
+                g: 255,
+                b: 255
+            })
+        );
+        assert_eq!(parse_hex_color("#000000"), Some(Rgb { r: 0, g: 0, b: 0 }));
+        assert_eq!(
+            parse_hex_color("#11223344"),
+            Some(Rgb {
+                r: 0x11,
+                g: 0x22,
+                b: 0x33
+            })
+        );
+        assert_eq!(
+            parse_hex_color("  #abc  "),
+            Some(Rgb {
+                r: 0xaa,
+                g: 0xbb,
+                b: 0xcc
+            })
+        );
+    }
+
+    #[test]
+    fn parse_hex_rejects_bad_input() {
+        assert_eq!(parse_hex_color("fff"), None); // no '#'
+        assert_eq!(parse_hex_color("#12"), None); // too short
+        assert_eq!(parse_hex_color("#1234"), None); // length 4 not 6/8
+        assert_eq!(parse_hex_color("#12345"), None); // length 5
+        assert_eq!(parse_hex_color("#1234567"), None); // length 7
+        assert_eq!(parse_hex_color("#ggg"), None); // non-hex
+        assert_eq!(parse_hex_color("$color-1"), None); // unresolved ref
+    }
+
+    #[test]
+    fn relative_luminance_endpoints() {
+        assert!((relative_luminance(Rgb { r: 0, g: 0, b: 0 }) - 0.0).abs() < EPS);
+        assert!(
+            (relative_luminance(Rgb {
+                r: 255,
+                g: 255,
+                b: 255
+            }) - 1.0)
+                .abs()
+                < EPS
+        );
+    }
+
+    #[test]
+    fn relative_luminance_mid_gray_exercises_gamma_branch() {
+        // 0x77 = 119; s = 119/255 ≈ 0.46667 > 0.03928 → gamma branch.
+        // Expected value computed against the TS formula (threshold 0.03928,
+        // gamma 2.4) — verified via Node.js to 1e-7.
+        let lum = relative_luminance(Rgb {
+            r: 0x77,
+            g: 0x77,
+            b: 0x77,
+        });
+        assert!((lum - 0.184_474_994_5).abs() < 1e-7);
+    }
+
+    #[test]
+    fn color_contrast_known_vectors() {
+        assert!((color_contrast("#000000", "#FFFFFF") - 21.0).abs() < EPS);
+        assert!((color_contrast("#777777", "#FFFFFF") - 4.48).abs() < 0.01);
+    }
+
+    #[test]
+    fn color_contrast_identical_returns_one_before_parsing() {
+        // Identical strings short-circuit to 1.0 even when unparseable.
+        assert_eq!(color_contrast("$same", "$same"), 1.0);
+    }
+
+    #[test]
+    fn color_contrast_unparseable_returns_infinity() {
+        assert_eq!(color_contrast("$color-1", "#FFFFFF"), f64::INFINITY);
+        assert_eq!(color_contrast("#FFFFFF", "not-a-color"), f64::INFINITY);
+    }
+}