#3631 Docs: extension dependency trust pages — import-map auditing, bare-import rewrite and scoring, and the clarified warning/error plan

One docs pass for the extension dependency trust work. Merged 2026-10-20 (Seth): this issue now includes swamp-club#3664 and the plan clarifications decided that day. Land it after swamp-club#3637 ships. If #3677 and #3354 have shipped by then, include their output too; otherwise leave their wording for a follow-up.

1. Import-map dependencies are audited (original scope, after #3611)

Push's dependency trust audit also audits bare imports mapped through the extension's deno.json import map (exact, trailing-slash and package-subpath keys). It audits them at the version that ships, with the same blocking. Findings for such a dependency end with a suffix naming the bare import (imported as NAME via deno.json), and extension quality --json audited entries carry an optional importedAs field.

• content/manual/reference/extensions/publishing.md, Dependency-trust errors paragraph: it currently says "any npm: import", which reads as inline-only.
• content/manual/explanation/extension-trust.md: the paragraph on checking every npm: import against OSV.dev, and on jsr: imports.

2. Bare imports are rewritten on push and scored (was #3664, after #3637)

Push rewrites each bare import that the deno.json import map resolves to an npm:, jsr:, node: or http(s) specifier. It uses that specifier, as the map writes it, in the shipped source. The registry scorer and audit then resolve those imports, and the extension is scored. Only these bare imports still ship as written and raise the bare-specifiers finding, with quality exiting non-zero and registryScorable: false:

• bare imports with no import-map entry
• any bare import in package.json mode
• one reached only through an importMap file reference or scopes

The last case changes once swamp-club#3612 lands.

• manifest.md: the Scoring limitation callout says bare specifiers can't resolve at score time.
• publishing.md: the quality section and the Output (bare specifiers) example say any bare specifier leaves the extension unscored.
• scorecard-rubric.md: it names bare zod as an import that doesn't resolve; it now does when the map has an entry.
• Also note that no deno.json or deno.lock ships in the archive, and that zod mapped to any 4.x range (for example npm:zod@^4) is still shared with the host.

3. Clarified plan (Seth, 2026-10-20)

• publishing.md § Shipped-version warnings now says "A future release makes deprecated-version and jsr-yanked errors that block the push." That's no longer the plan. Nothing becomes an error: deprecated-version, jsr-yanked and loose-specifier all stay warnings that --yes accepts. They cost score points instead (#3354).
• Say why yanked is only a warning. A version pinned exactly, or held in a lockfile, still installs. Range resolution skips yanked versions.
• Scoring (#3354, shipped; #3682 registry): a loose specifier costs one of the two dependency-trust points. A yanked JSR version, a deprecated pin, an unaudited dependency or any error costs both. Update scorecard-rubric.md § At push and the registry section to match, once #3354 ships.
• #3677 output: the reworded yanked warning, with a suggested version, and dependency warnings listed under Unresolved warnings with fix lines. Update the example output in Shipped-version warnings when #3677 ships.

4. #3677 output (was #3687, merged 2026-10-20)

swamp-club#3677 (PR https://github.com/swamp-club/swamp/pull/3238) changes what 'extension push', its dry run and 'extension quality' print and return for dependency-trust warnings. content/manual/reference/extensions/publishing.md needs to catch up:

• The jsr-yanked warning now reads 'version X was withdrawn (yanked) by its author on JSR. Newest version that isn't yanked: Y.' (or 'No other version is available.').
• Dependency-trust findings with a cause (jsr-yanked, deprecated-version, loose-specifier, not-audited) carry an optional 'remediation', and jsr-yanked and deprecated-version findings carry an optional 'suggestedVersion', in warnings.dependencyTrust, acceptedWarnings.dependencyTrust and quality's dependencyTrust.warnings (additive).
• Those findings now appear under 'Unresolved warnings' (log and JSON unresolvedWarnings) with ruleId = the cause, file = '(dependency)' and a fix line. The not-audited fix depends on why the audit could not run.
• Severity is unchanged: still a warning that --yes accepts.

Sections to check: the dependencyTrust JSON row (~line 221), the unaudited dependencies section (~line 305), the warnings table (~line 688) and the dependency trust notes (~lines 1005 and 1130).

5. Stale bare-specifiers and quality messages (was #3689, merged 2026-10-20)

The swamp-club manual's extension reference quotes swamp CLI output that has changed twice since it was written:

• content/manual/reference/extensions/publishing.md (around lines 127-217) and content/manual/reference/extensions/manifest.md (around line 926) say an extension with bare specifiers would publish unscored. Since swamp-club#3370 the registry publishes a scorecard with the documentation factors at 0, and since swamp-club#3669 the CLI says so: the bare-specifiers message reads 'Extension has bare imports that ship as written, which the registry's scorer cannot resolve, so it would score the documentation factors 0: "zod". Push rewrites a bare import only when the deno.json import map resolves it to an npm:, jsr:, node: or URL specifier; add such an entry for each, or write the specifier in its place.'
• The sample quality output (bare-specifiers line, the 'The registry cannot score this extension' error line, and the 'Extension quality failed: the registry cannot score this extension' line) predates swamp-club#3637 and swamp-club#3669. Current lines: 'The registry cannot resolve this extension's bare imports: they ship as written, so it would score the documentation factors 0. Push rewrites only the bare imports the deno.json import map resolves.' and 'Extension quality failed: the registry cannot resolve its bare imports, which ship as written, so it would score the documentation factors 0.'
• The quality --json field table should add docAnalysisError: why deno doc could not analyse the source (null when it ran); quality scores the documentation factors 0, as the registry does, and fails. The status row should list a deno doc failure as a failing reason.

Source of truth: swamp's .claude/skills/swamp/references/extension-publish/references/publishing.md, updated in swamp PR 3241.