add_html_dependency: implement version, warn once per dependency (bd-add-html-dependency-version-5tnub5ds)

claude-notes/plans/add-html-dependency-version-investigation/repro/.gitignore

@@ -0,0 +1,6 @@
+/_site/
+/_site-q1/
+/.quarto/
+**/*.html
+
+**/*.quarto_ipynb

claude-notes/plans/add-html-dependency-version-investigation/repro/README.md

@@ -0,0 +1,72 @@
+# `add_html_dependency`'s `version` field is unsupported, and warns once per call
+
+**Observed with:** q2 0.20.0.
+**Repro:** `q2 render` in this directory; compare with
+`quarto render --output-dir _site-q1`.
+
+A Lua filter attaches an HTML dependency that declares a version, the
+way real extensions do:
+
+```lua
+quarto.doc.add_html_dependency({
+  name = 'versioned-dep',
+  version = '1.0.0',
+  scripts = { 'versioned-dep.js' }
+})
+```
+
+## Expected (Quarto 1)
+
+No diagnostic. The version becomes part of the asset directory name, so
+a site can carry two versions of the same dependency without collision:
+
+```
+_site/site_libs/quarto-contrib/versioned-dep-1.0.0/versioned-dep.js
+```
+
+## Actual (q2 0.20.0)
+
+```
+Warning [Q-11-1]: add_html_dependency: field 'version' is not yet supported and will be ignored
+```
+
+…and the assets land in an unversioned directory:
+
+```
+_site/site_libs/libs/versioned-dep/versioned-dep.js
+```
+
+The warning is truthful and self-documenting. Two things about it are
+worth separating:
+
+1. **The field is unimplemented.** For most extensions this is
+   cosmetic — one dependency, one version, nothing to collide with.
+2. **The warning is emitted per call, not per distinct dependency.**
+   `add_html_dependency` de-duplicates by name, so extensions are
+   written to call it unconditionally for every matching element; the
+   documentation of the API encourages exactly that. This repro's
+   filter runs on two paragraphs and produces two identical warnings.
+
+Point 2 is what makes it noisy in practice rather than cosmetic. See
+the Connect docs impact below.
+
+## Connect docs impact
+
+The `mermaid-zoom` extension calls `add_html_dependency` once per
+mermaid diagram, with a `version`. Across the 33 diagrams on 14 pages
+that is **33 warnings per full render** for one field on one line —
+enough to take the site's render from one distinct diagnostic to two.
+
+Worked around in `docs-quarto-2/_quarto.yml` with the `diagnostics:`
+suppression added in q2 0.20.0, so the extension source can stay
+byte-identical to the upstream Quarto 1 copy:
+
+```yaml
+diagnostics:
+  Q-11-1:
+    level: off
+    reason: "add_html_dependency version: field is not yet supported by q2"
+```
+
+That is the suppression mechanism working as designed, and it is worth
+recording as the first real use of it in this project.

claude-notes/plans/add-html-dependency-version-investigation/repro/_extensions/test/versioned-dep/_extension.yml

@@ -0,0 +1,6 @@
+title: versioned-dep
+author: repro
+version: 1.0.0
+contributes:
+  filters:
+    - versioned-dep.lua

claude-notes/plans/add-html-dependency-version-investigation/repro/_extensions/test/versioned-dep/versioned-dep.js

@@ -0,0 +1 @@
+console.log('versioned-dep loaded');

claude-notes/plans/add-html-dependency-version-investigation/repro/_extensions/test/versioned-dep/versioned-dep.lua

@@ -0,0 +1,11 @@
+-- Attach an HTML dependency that declares a version, the way a real
+-- extension does. Called once per paragraph to show that the warning is
+-- emitted per call rather than per distinct dependency.
+function Para(el)
+  quarto.doc.add_html_dependency({
+    name = 'versioned-dep',
+    version = '1.0.0',
+    scripts = { 'versioned-dep.js' }
+  })
+  return nil
+end

claude-notes/plans/add-html-dependency-version-investigation/repro/_quarto.yml

@@ -0,0 +1,6 @@
+project:
+  type: website
+website:
+  title: "add_html_dependency version"
+filters:
+  - versioned-dep

claude-notes/plans/add-html-dependency-version-investigation/repro/index.qmd

@@ -0,0 +1,8 @@
+---
+title: "Dependency with a version"
+---
+
+Two paragraphs, so the filter's Para handler fires twice and the
+per-call nature of the warning is visible.
+
+The second paragraph.