Conversation
…mp-club#161) Following #1218 shipping `swamp extension quality`, authors now see locally that the scorer strips the tarball's `deno.json` and writes a controlled one with no imports map — so bare `"zod"` imports fail with `deno doc --json failed: Import "zod" not a dependency`. Three files teach authors the pattern that was silently breaking their scores. - `swamp-extension-quality/references/templates.md` — switch the JSDoc entrypoint skeleton from bare `"zod"` to `"npm:zod@4"` and add a rationale bullet. - `swamp-extension-publish/references/publishing.md` — rewrite the contradictory Import Rules (one bullet said inline was "always required", another said bare was fine with an import map). Single coherent paragraph now carries both the hermeticity and zod-externalization signals. - `swamp-extension-quality/SKILL.md` — add a gotcha block under "Essential mechanics authors get wrong" covering the bare-specifier failure mode, the Deno `no-import-prefix` default catch-22 when a `deno.json` with `imports` is present, and concrete mitigations (global `lint.rules.exclude` or per-import `// deno-lint-ignore`). Cross-link from the new "Self-check your score locally" section to the gotcha. Add a symptom→fix row to "Common patterns". Verified via executable round-trip in /tmp: bare `"zod"` fails the quality command with the documented error; `"npm:zod@4"` plus the lint exclusion scores 11/12. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
There was a problem hiding this comment.
Code Review
Blocking Issues
None.
Suggestions
-
In
SKILL.md, the sentence "The deadlock goes away entirely once the scorer honours the tarball'sfiles/deno.json" is forward-looking — consider adding a tracking reference (e.g. a follow-up issue number) so it can be cleaned up when the server-side fix lands. Minor, and the PR body already calls this out as a follow-up. -
The
publishing.mdrewrite is thorough but the section is now notably longer than the other Import Rules it sits alongside. Not a problem for correctness, but if it ever feels heavy, the hermeticity explanation could move to areferences/file with a one-line pointer. Fine as-is given the complexity of the trap being documented.
Overall: well-structured fix that resolves a real contradiction in the import rules docs and documents a non-obvious failure mode with concrete mitigations. The template fix ("zod" → "npm:zod@4") is the highest-value change — authors who copy the skeleton literally now produce extensions that score.
Summary
Closes swamp-club#161. Following #1218 shipping
swamp extension quality, authors now discover locally that the scorer strips the tarball'sdeno.jsonand writes a controlled one with no imports map — so bare"zod"imports fail withdeno doc --json failed: Import "zod" not a dependencybefore factor scoring even begins. This PR teaches that pattern to authors through the two skills that previously led them into the trap.Three files, +50/-7 lines:
swamp-extension-quality/references/templates.md— the JSDoc entrypoint skeleton was showing bare"zod"; switched to"npm:zod@4"with a rationale bullet explaining hermeticity. An author who copies the template literally now produces an extension that scores.swamp-extension-publish/references/publishing.md— the Import Rules had two contradictory bullets ("npm:zod@4"is "always required" vs. bare specifiers "can be used" withdeno.json). Rewritten into one coherent paragraph that carries both load-bearing signals: hermeticity at score time AND zod-specific externalization (why zod in particular is called out, not merely a consequence of hermeticity).swamp-extension-quality/SKILL.md— added a gotcha block under "Essential mechanics authors get wrong" that names the failure mode explicitly, calls out the Denono-import-prefixdefault that activates when adeno.jsonwithimportsis present (which is every swamp repo's default state, creating a catch-22), and gives concrete mitigations: either global"lint": { "rules": { "exclude": ["no-import-prefix"] } }indeno.json, or per-import// deno-lint-ignore no-import-prefix. Also added a one-sentence cross-link from the new "Self-check your score locally" section and a symptom→fix row to "Common patterns" so a reader landing anywhere in the skill finds the fix.Test Plan
Three-layer verification:
deno fmt --checkclean on all three filesdeno checkcleandeno lintclean (1088 files)deno run test— 4803 passed, 0 failed/tmp/swamp-issue-161-verify:"zod"import →swamp extension qualitythrows the exact error documented in the gotcha (deno doc --json failed: Warning Import "zod" not a dependency)"npm:zod@4"→ scorer runs and reports 11/12 (91%) factor resultsno-import-prefixdefault rule firing as predicted, and the documented mitigation (lint.rules.exclude) unblocked the round-trip — confirming both halves of the gotcha match the tool's actual behaviour.Follow-up (not in this PR)
The deadlock between the scorer (strips
deno.json) and Deno's default lint rules (forbidnpm:prefix when animportsmap is present) is ultimately a swamp-club server-side concern. A future follow-up issue could make the analyzer honour the tarball'sfiles/deno.jsonwith appropriate hardening — the README/LICENSE promotion logic already does similar. Until then, the gotcha documents the author-side workaround.🤖 Generated with Claude Code