From b837b04d613ab53f775e62b80aab5a7b0b2e8c61 Mon Sep 17 00:00:00 2001
From: danielporterda <daniel.porter@digitalasset.com>
Date: Fri, 7 Aug 2026 12:24:57 -0400
Subject: [PATCH] Add local snippet ref remediation

Signed-off-by: danielporterda <daniel.porter@digitalasset.com>
---
 scripts/snippets/diagnostics.py               | 23 ++++++++++++++++
 .../test_local_snippet_source_remediation.py  | 26 +++++++++++++++++++
 2 files changed, 49 insertions(+)
 create mode 100644 scripts/snippets/diagnostics.py
 create mode 100644 tests/test_local_snippet_source_remediation.py

diff --git a/scripts/snippets/diagnostics.py b/scripts/snippets/diagnostics.py
new file mode 100644
index 000000000..8d0a74fc4
--- /dev/null
+++ b/scripts/snippets/diagnostics.py
@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .model import Diagnostic, LocalSourcePolicyIssue
+
+LOCAL_SOURCE_REMEDIATION = (
+    "Run `npm run snippets:resolve-local -- --page <page.source.mdx>` before pushing."
+)
+
+
+def local_source_policy_diagnostic(
+    path: Path, issue: LocalSourcePolicyIssue
+) -> Diagnostic:
+    """Add committed-page remediation to a local-ref policy failure."""
+
+    return Diagnostic(
+        path=path,
+        span=issue.span,
+        code="SNIP007",
+        message=issue.message,
+        remediation=LOCAL_SOURCE_REMEDIATION,
+    )
diff --git a/tests/test_local_snippet_source_remediation.py b/tests/test_local_snippet_source_remediation.py
new file mode 100644
index 000000000..7217561ca
--- /dev/null
+++ b/tests/test_local_snippet_source_remediation.py
@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from scripts.snippets.diagnostics import local_source_policy_diagnostic
+from scripts.snippets.model import LocalSourcePolicyIssue, Span
+
+
+def test_reports_resolve_local_command_at_source_location() -> None:
+    diagnostic = local_source_policy_diagnostic(
+        Path("docs-main/validator.source.mdx"),
+        LocalSourcePolicyIssue(
+            span=Span(start=20, end=30, line=7, column=3),
+            message=(
+                "Local snippet references are preview-only and cannot be committed"
+            ),
+        ),
+    )
+
+    assert diagnostic.code == "SNIP007"
+    assert diagnostic.span.line == 7
+    assert diagnostic.span.column == 3
+    assert diagnostic.remediation == (
+        "Run `npm run snippets:resolve-local -- --page <page.source.mdx>` "
+        "before pushing."
+    )