fix(link-notes): fail the build on a missing note_snippet

A note_snippet path that cannot be resolved was previously only a warning
(fatal only under --strict) and fell back to the inline note or silently
dropped the rule -- which for an affiliate disclosure means it could vanish
with no signal. Record the unresolved reference and throw from ProcessAsync
(outside PluginHost.Configure's try/catch) so the build fails with a clear
"snippet not found" error and a non-zero exit even without --strict.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Netdocs

docs-site/docs/plugins/link-notes.md

@@ -69,8 +69,8 @@ stays consistent everywhere:
 The path is resolved against the project root and the `docs/` directory, each with a
 conventional `snippets` subdirectory — so `snippets/ebay-affiliate.md`,
 `docs/snippets/ebay-affiliate.md`, or a bare `ebay-affiliate.md` (found in `docs/snippets`)
-all work. If the snippet can't be found, the plugin logs a warning and falls back to the
-inline `note` (when one is set).
+all work. If a referenced snippet **cannot be found, the build fails** with a clear error
+(even without `--strict`) — a mistyped path can never silently drop an affiliate disclosure.
 
 When the snippet is a single **admonition** — the usual pretty affiliate box:
 
@@ -172,14 +172,15 @@ Each **rule** object:
 |---|---|---|---|
 | `name` | string | yes | Rule id; used to build the footnote label (`linknote-<name>`). |
 | `note` | string | yes* | Markdown shown as the tooltip and footer note. Legacy alias: `disclosure`. |
-| `note_snippet` | string | yes* | Path to a Markdown snippet whose content is used as the note (resolved against the project root / `docs` dir and their `snippets` subdirs). A single-admonition snippet contributes its title (→ `label`) and kind, and its body becomes the note. Legacy alias: `disclosure_snippet`. |
+| `note_snippet` | string | yes* | Path to a Markdown snippet whose content is used as the note (resolved against the project root / `docs` dir and their `snippets` subdirs). A single-admonition snippet contributes its title (→ `label`) and kind, and its body becomes the note. A referenced-but-missing snippet **fails the build**. Legacy alias: `disclosure_snippet`. |
 | `domains` | array | no† | Hosts that identify the link. Each entry is a domain string or `{ "domain": "...", "query_contains": "..." }`. Subdomains match automatically. |
 | `patterns` | array | no† | Regular expressions matched (case-insensitively) against the full URL. |
 | `query_contains` | string | no | Default substring a matching URL must contain (per-domain values override this). |
 | `label` | string | no | Title for the standalone fallback admonition (table-only links). Defaults to the snippet's admonition title, else `Links`. |
 
-\* A rule must provide the note text via either `note` or `note_snippet` (if both are set and
-the snippet resolves, the snippet wins; otherwise `note` is the fallback).
+\* A rule must provide the note text via either `note` or `note_snippet`. If `note_snippet`
+is set it takes precedence; a referenced snippet that cannot be found fails the build rather
+than falling back, so a mistyped path is caught instead of silently dropping the note.
 
 † A rule must provide at least one of `domains` or `patterns`.
 

src/Netdocs.Plugins/LinkNotesPlugin.cs

@@ -32,6 +32,7 @@ private sealed record Rule(string Id, DomainRule[] Domains, Regex[] Patterns, st
 
     private readonly List<Rule> _rules = [];
     private readonly List<string> _snippetBasePaths = [];
+    private readonly List<string> _configErrors = [];
     private ILogger? _log;
 
     public string Name => "link-notes";
@@ -104,11 +105,21 @@ public void Configure(IPluginContext ctx)
                 string? snippetTitle = null;
                 if (!string.IsNullOrWhiteSpace(snippetPath))
                 {
-                    var content = ReadSnippet(snippetPath!, id!);
-                    if (content is not null)
+                    var content = ReadSnippet(snippetPath!);
+                    if (content is null)
                     {
-                        (kind, snippetTitle, note) = ExtractNote(content);
+                        // An explicitly referenced snippet that cannot be found is a configuration
+                        // mistake (typically a typo in the path). Silently dropping the rule would
+                        // omit an affiliate disclosure without any signal, which is worse than a
+                        // failed build — so record it as a fatal error. It is thrown from
+                        // ProcessAsync (below) rather than here so it aborts the build even outside
+                        // `--strict` (plugin Configure exceptions are otherwise swallowed).
+                        _configErrors.Add(
+                            $"rule '{id}' references note_snippet '{snippetPath}' which was not found " +
+                            $"(searched: {string.Join(", ", _snippetBasePaths)})");
+                        continue;
                     }
+                    (kind, snippetTitle, note) = ExtractNote(content);
                 }
 
                 if (string.IsNullOrWhiteSpace(note))
@@ -126,16 +137,16 @@ public void Configure(IPluginContext ctx)
             _log.LogWarning("link-notes: no link rules configured; plugin is a no-op");
     }
 
-    // Resolves a snippet path against the configured base directories and returns its text, or null.
-    private string? ReadSnippet(string path, string ruleId)
+    // Resolves a snippet path against the configured base directories and returns its text, or null
+    // when it cannot be found (the caller turns an unresolved explicit reference into a build error).
+    private string? ReadSnippet(string path)
     {
         if (Path.IsPathRooted(path) && File.Exists(path)) return File.ReadAllText(path);
         foreach (var basePath in _snippetBasePaths)
         {
             var candidate = Path.GetFullPath(Path.Combine(basePath, path));
             if (File.Exists(candidate)) return File.ReadAllText(candidate);
         }
-        _log?.LogWarning("link-notes: rule '{Id}' snippet '{Path}' not found; falling back to inline note", ruleId, path);
         return null;
     }
 
@@ -174,6 +185,14 @@ private static (string Kind, string? Title, string Body) ExtractNote(string cont
 
     public Task<string> ProcessAsync(Page page, string markdown, SiteContext site, CancellationToken ct)
     {
+        // A referenced-but-missing note_snippet is a fatal configuration error. Throwing here (from
+        // the build's preprocess loop, outside PluginHost.Configure's try/catch) aborts the build
+        // with a non-zero exit even without `--strict`, so a mistyped snippet path can never
+        // silently omit an affiliate disclosure.
+        if (_configErrors.Count > 0)
+            throw new FileNotFoundException(
+                "link-notes: " + string.Join("; ", _configErrors));
+
         if (_rules.Count == 0 || markdown.Length == 0) return Task.FromResult(markdown);
 
         // Rules whose links got an inline footnote reference (definition will be rendered by the

tests/Netdocs.Core.Tests/LinkNotesPluginTests.cs

@@ -311,7 +311,7 @@ public void NoteSnippet_Admonition_UsesBodyForFootnoteAndTitleForFallback()
     }
 
     [Fact]
-    public void NoteSnippet_MissingFile_FallsBackToInlineNote()
+    public void NoteSnippet_MissingFile_FailsBuild()
     {
         var dir = Path.Combine(Path.GetTempPath(), "netdocs-linknotes-" + Guid.NewGuid().ToString("N"));
         Directory.CreateDirectory(dir);
@@ -321,12 +321,15 @@ public void NoteSnippet_MissingFile_FallsBackToInlineNote()
             {
                 ["name"] = "ebay",
                 ["domains"] = new List<object?> { "ebay.us" },
+                // Even with an inline note present, a referenced-but-missing snippet is a fatal
+                // configuration error rather than a silent fallback.
                 ["note"] = "Inline fallback note.",
                 ["note_snippet"] = "does-not-exist.md",
             };
             var plugin = ConfiguredWithRoot(dir, rule);
-            var result = Run(plugin, "Buy on [eBay](https://ebay.us/abc).");
-            Assert.Contains("[^linknote-ebay]: Inline fallback note.", result);
+            var ex = Assert.Throws<FileNotFoundException>(
+                () => Run(plugin, "Buy on [eBay](https://ebay.us/abc)."));
+            Assert.Contains("does-not-exist.md", ex.Message);
         }
         finally
         {