slopcop API

The slopcop version that built the current endpoints and module, and the number of rules it ships. Compare it with slopcop --version to see whether your CLI matches the site.

$ curl https://slopcop.me/api/v1/version.json

{
  "version": "0.4.0",
  "rule_count": 46
}

Every rule as an array, ordered by ID. This is the catalog behind slopcop rules and slopcop explain, and the SARIF rule descriptors.

$ curl -s https://slopcop.me/api/v1/rules.json | jq -r '.[] | "\(.id) \(.description)"'

[
  {
    "id": "DEAD001",
    "module": "deadweight",
    "description": "Empty exception handler",
    "default_severity": "error",
    "default_confidence": "high",
    "message": "Exception is swallowed without logging, rethrowing, or handling.",
    "suggestion": "Handle the failure, rethrow it, or document a narrow and intentional exception.",
    "rationale": "Silent exception handling hides failures and turns debugging evidence into an unexplained fallback.",
    "examples": ["except NetworkError:\n    pass", "catch (error) {}"],
    "false_positives": "A deliberately ignored exception with an explanatory body comment, …"
  },
  …
]

One rule, with the same fields as an entry of rules.json. An unknown ID returns 404.

$ curl https://slopcop.me/api/v1/rules/VIBE013.json

{
  "id": "VIBE013",
  "module": "vibecheck",
  "description": "…",
  …
}

A JSON Schema (draft 2020-12) for the report that slopcop --format json prints and that scanFiles and scanRepository return. The site build checks a real report against it, so the schema and the linter cannot drift apart.

$ slopcop . --format json > report.json
$ check-jsonschema --schemafile https://slopcop.me/api/v1/report.schema.json report.json

An ES module that loads the linter's WebAssembly build (about 1 MB) on first use. Import it from a module script or a module Worker in the browser, or from Deno with --allow-net --allow-import. Node cannot import modules from URLs; use the CLI there.

The linter runs synchronously once the files are in memory. Large repositories keep the thread busy for a moment, so call the module from a Worker if your page has to stay responsive.

import { scanFiles, scanRepository, rules, version } from "https://slopcop.me/api/v1/slopcop.js";

$ deno run --allow-net --allow-import scan.js

Scans files you already have in memory and resolves to a report. Paths are repository-relative, and they choose each file's language and whether it is scanned at all, just as in a checkout.

A .gitattributes among the files excludes the paths it marks linguist-vendored or linguist-generated. Binary files, unsupported types, oversized files, dependency directories such as node_modules, and ignored paths count toward summary.skipped_files.

const report = await scanFiles({
  "src/app.py": "try:\n    run()\nexcept Exception:\n    pass\n",
  "README.md": await (await fetch("/README.md")).text(),
});
for (const finding of report.findings) {
  console.log(`${finding.path}:${finding.location.line} ${finding.rule_id} ${finding.message}`);
}

Fetches a public repository from GitHub, GitLab, or Codeberg and scans it, as the demo does. The repository's own .slopcop.toml and .gitattributes files apply.

const scan = await scanRepository("https://codeberg.org/dnkl/foot", {
  onProgress: ({ stage, done, total }) => console.log(stage, total ? `${done}/${total}` : ""),
});
console.log(scan.sha, scan.report.summary);
console.log(scan.notices.join("\n"));

The same data as version.json and rules.json, read from the WebAssembly build the module loaded. They always agree with the linter that scans your files.

const catalog = new Map((await rules()).map((rule) => [rule.id, rule]));
console.log(await version(), catalog.get("DEAD001").rationale);

The JSON endpoints return 404 for unknown paths. The module's functions reject with an Error whose code property names the cause; other errors, such as network failures, have no code.

The JSON endpoints are static files on GitHub Pages with no rate limit of their own. scanRepository downloads every file from the repository host, so the host's limits apply to the network it runs from, and it caps each scan to stay within them. Run the CLI on a clone for anything larger.

Every scan also stops at 60 MB of downloads, and files over the configured max-file-size (1 MB by default) are skipped before download where the host lists sizes. When GitLab or Codeberg throttles a scan, every request to that host pauses for the time the host asks, or a minute, and onProgress reports the wait.