contribpath

contribpath

A CONTRIBUTING guide can read beautifully and still leave a new contributor stranded, because the document and the repository's real requirements drift apart: the guide never mentions the DCO sign-off the CI enforces, or the changeset the release bot demands. contribpath measures that drift. You supply the document text and the gates the repository actually has — each with an id, the label as it would appear in the document, and any alternative phrases that also count — and it reports which gates are documented, which are missing, how much coverage that adds up to, and a verdict.

Matching is deliberately simple and auditable. Everything is lowercased, and a gate counts as documented when the document contains its label or at least one of its non-empty keywords as a substring. Empty keywords are ignored on purpose: an empty string is a substring of every document, so counting it would mark every gate as covered and hide exactly the gaps this tool exists to find. Either signal is enough on its own — a gate whose label never appears can still be covered by a keyword, and a gate with no keywords at all is covered by its label alone.

Coverage is Math.round(100 * documented / gate_count), so two of three gates is 67, not 66. A coverage of 100 reads as complete, 60 and up as partial, and anything below 60 as sparse. The documented and missing lists carry gate ids in the order the gates were supplied, so the report lines up with the caller's own gate list.

If the caller also extracted topics from the document, they can be passed as documented_topics to find the ones that correspond to no gate at all. A topic matches a gate when it is exactly that gate's id, or when it equals the gate's label ignoring case; topics matching nothing come back verbatim, in input order, as extra_topics. When no topics are supplied, extra_topics is empty.

Duplicate gate ids are an error naming the id — a gate set with two entries for the same gate would make the coverage number meaningless. Malformed input — a missing or non-string document, a missing or empty gates array, a gate with a missing, empty, or non-string id or label, a keywords value that is not an array of strings, or a documented_topics entry that is not a non-empty string — is a validation error naming the offending path, with no partial result. Unknown extra fields are ignored, including inside gate items. The computation is pure and local: no network, no configuration, and no repository is read or touched. contribpath compares what you give it; extracting the gates from a repository in the first place is a separate job.

CLI

npx @reneturcios/contribpath check --input args.json
npx @reneturcios/contribpath --version

args.json contains the full arguments object:

{
  "document": "Please sign off your commits (DCO) and add a changeset.",
  "gates": [
    { "id": "dco", "label": "Developer Certificate of Origin", "keywords": ["dco", "sign off"] },
    { "id": "changeset", "label": "Changeset" },
    { "id": "cla", "label": "Contributor License Agreement", "keywords": ["cla"] }
  ],
  "documented_topics": ["dco", "Changeset", "Code of Conduct"]
}

The result is printed as JSON:

{
  "documented": ["dco", "changeset"],
  "missing": ["cla"],
  "extra_topics": ["Code of Conduct"],
  "coverage_percent": 67,
  "verdict": "partial",
  "gate_count": 3
}

An empty document string is valid input: every gate is missing and the verdict is sparse. Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid input file, or invalid input), 2 on a usage error.

MCP server

npx -y @reneturcios/contribpath mcp

MCP client config:

{
  "mcpServers": {
    "contribpath": {
      "command": "npx",
      "args": ["-y", "@reneturcios/contribpath", "mcp"]
    }
  }
}

Tools

• check_contributing_coverage — Check a CONTRIBUTING document against the repository's actual contribution gates.

  • document (string, required, may be empty) — the contributing document text to check
  • gates (array, required, at least 1 item) — the repository's actual contribution gates; each item is an object with:
    • id (string, required, non-empty) — gate identifier
    • label (string, required, non-empty) — gate label as it would appear in the document
    • keywords (array of strings, optional) — alternative phrases that also count as documenting the gate
  • documented_topics (array of strings, optional) — topics the caller extracted from the document, checked against the gate set

  Returns {documented, missing, extra_topics, coverage_percent, verdict, gate_count}.

Docker

docker run -i ghcr.io/cloudcorprecords/contribpath
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/contribpath check --input /w/args.json

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios