Skip to main content

EXTENSION SCORECARD RUBRIC

The scorecard is a weighted rubric applied to every published extension. Each factor contributes a fixed number of points. The total is divided by the sum of all weights and expressed as a percentage and letter grade.

Factors

The current rubric defines ten active factors. The divisor is 12.

# Factor ID Label Points Earned when
1 has-readme Has README or module doc 2 The tarball contains a README file (README.md, README.MD, readme.md, or Readme.md) at the extension root or under files/.
2 readme-example README has a code example 1 The README contains at least one fenced code block.
3 rich-readme README is substantive 1 The README is at least 500 characters and contains at least two fenced code blocks.
4 symbols-docs Most symbols documented 1 At least 80% of exported symbols across all entry points carry a JSDoc comment.
5 fast-check No slow types 1 deno doc --lint emits no slow-type diagnostics (missing return types on exports, private-type references on public exports, and similar).
6 description Has description 1 The extension's description field is a non-empty string.
7 platforms-one At least one platform tag (or universal) 1 The platforms array has one or more entries, or is empty. An empty array declares "supports all platforms".
8 platforms-two Two or more platform tags (or universal) 1 The platforms array has two or more entries, or is empty.
9 has-license License declared 1 The license field is set on the extension, or a license file (LICENSE, LICENSE.md, LICENSE.txt, COPYING, and common variants) is present at the tarball root or under files/.
10 repository-verified Verified public repository 2 The repository URL is set and points to a publicly accessible repository on an allowlisted host, confirmed via the host's public API.

The maximum score is 12/12 = 100% (Grade A). Every factor above is earnable by any publisher.

Verified by Swamp badge

The Verified by Swamp badge is displayed as a shield pill next to the score ring on the extension detail page. It is awarded when either of the following is true:

  • The extension is published under the first-party @swamp namespace.
  • The latest version meta has verifiedBySwamp: true, set by a System Initiative admin. The admin curation endpoint is planned and not yet available.

The badge does not contribute points to the score. An extension can score 100% without the badge, and an extension can carry the badge at any score. See About the Extension Scorecard for why verification is a badge rather than a scored factor.

Grade thresholds

Grade Minimum score
A 90%
B 75%
C 60%
D 40%
F < 40%

Repository verification

The repository-verified factor is earned only for repositories hosted on one of the following allowlisted hosts:

Host API endpoint
github.com GET https://api.github.com/repos/:owner/:repo
gitlab.com GET https://gitlab.com/api/v4/projects/:url-encoded-path
codeberg.org GET https://codeberg.org/api/v1/repos/:owner/:repo
bitbucket.org GET https://api.bitbucket.org/2.0/repositories/:workspace/:repo

Verification calls the host's public API with the owner and repository path — the owner-supplied URL is not fetched directly. A 200 response from the host API with the repository marked public counts as verified. Any other outcome (404, private repository, rate limit, network error, malformed URL) counts as not verified. The result is cached either way; see the caching rules below for when a negative result is re-checked.

GitLab verification supports nested group paths by URL-encoding the full project path. The gitlab.com public SaaS instance is the only GitLab host recognised — self-hosted GitLab instances cannot be verified.

Verification results are cached on the extension record for 7 days. The cache is cleared and re-checked when the owner changes the repository URL. The cache is also re-checked if a scoring event fires (a new version is published or the owner triggers a manual rescore) and the stored result is more than 7 days old. The score worker does not re-verify on its own schedule — if no scoring event fires, a stale cache stays as-is until the next publish or rescore.

Extensions hosted on self-hosted Git instances (GitHub Enterprise, self-hosted GitLab, private Gitea) still display the repository URL on the detail page, but do not earn the repository-verified factor.

Factor data sources

Factors are evaluated against two kinds of data:

Data scope Stored on Updated by
Per-version Version meta record Tarball analyzer at publish time; re-run on the owner's "Rescore" action.
Per-package Extension record Read live from the extension's metadata. Edits to description, platforms, repository, homepage, and license update the score instantly.
Verification Extension record Repository verifier. Cached for 7 days; re-checked on URL change, publish, or worker tick.

Per-version factors: has-readme, readme-example, rich-readme, symbols-docs, fast-check.

Per-package factors: description, platforms-one, platforms-two, has-license.

Verification factor: repository-verified.

The Verified by Swamp badge is not a factor and does not appear in the breakdown. It is evaluated from the extension's namespace and the admin-set verifiedBySwamp flag on the latest version meta.

Rubric stability

Extensions published under an older rubric version are not re-analysed. Their stored per-version meta is composed against the current rubric on each page load. If weights or factor definitions change, existing per-version data continues to contribute to the new score without requiring a republish.

Factors not currently counted

A provenance factor is defined in the codebase but does not contribute to the score at this time. It is gated behind a feature flag and will be enabled when the swamp CLI ships Sigstore signing support. When enabled, the divisor will move from 12 to 13.

← PreviousDatastore ConfigurationNext →Notifications