DocShield – The Documentation Guardian That Never Ships

DocShield is a CLI tool designed to run in your CI pipeline (GitHub Actions, CircleCI, etc.) that automatically checks the health of your project's documentation. It parses code comments (JSDoc, TSDoc) and Markdown files, then performs a set of customizable rules to ensure completeness, correctness, and freshness. For example, it flags exported functions missing @param or @returns tags, detects when a parameter name changes but the doc doesn't follow, and checks that examples in your README are syntactically valid.

The tool outputs a structured JSON report and a human-readable summary with a “doc debt” score. It can upload this report to a lightweight cloud backend (free Vercel serverless + MongoDB Atlas) to track trends over time. A companion React dashboard displays the history, allows drill-down into specific files, and generates a badge for your project’s README.

Unlike existing doc generators or linters, DocShield is opinionated – it expects a minimum standard (e.g., all exported symbols documented) by default, but is fully configurable via a docshield.config.js file. The entire stack runs on free tiers: npm package, GitHub Actions, Netlify (frontend), Vercel (API), and MongoDB Atlas (500MB). No paid service required.

Documentation is often neglected because there’s no immediate feedback. Code coverage has tools like Codecov that enforce a minimum threshold, but documentation coverage is rarely measured. Existing tools like JSDoc only generate static HTML without checking if docs are up-to-date. Teams end up with stale comments, missing parameter descriptions, and READMEs that don't reflect the current API. DocShield fills this gap by treating docs as a first-class citizen in CI, giving developers instant, actionable feedback on PRs.

• Provide a CLI that outputs a JSON report and human-readable summary of documentation health.
• Integrate with GitHub Actions to comment on PRs with a diff of doc changes and a health score change.
• Generate a dynamic badge for the project’s README showing the current doc coverage score.
• Support JSDoc, TSDoc, and basic Markdown linting out of the box.
• Allow extensible custom rules via a plugin API.
• Keep the entire system free to run using open-source components and free cloud tiers.

• Not a documentation generator (existing tools like JSDoc/TSDoc already do that).
• Not a natural language understanding tool – only syntactic and structural checks.
• Not a replacement for human code review or documentation writing.
• Not a paid SaaS – no paid tiers, no monetisation.
• Not a full-featured documentation site builder.

• Runtime: Node.js (v16+), npm package.
• CLI framework: Commander.js.
• Parsing: TypeScript Compiler API (ts.createProgram) for JavaScript/TypeScript; jsdoc-parser for JSDoc; markdown-it + remark for Markdown.
• CI: GitHub Actions (free tier) for integration and badge generation.
• Backend: Vercel Serverless Functions (free tier) with Mongoose and MongoDB Atlas (512MB free).
• Frontend: React + Vite, deployed on Netlify (free tier).
• Badges: Shields.io JSON endpoint.
• All open-source: the core will be MIT licensed.

The system has four components:

1. CLI (Node.js package): Installed via npm install docshield. Runs as a CLI step in CI. Accepts a configuration file or zero-config defaults. It traverses the project's source directory, parses all relevant files (.js, .ts, .jsx, .tsx, .md), extracts comments and structure, then runs each rule (e.g., 'exported-functions-have-returns') against the extracted data. Outputs a JSON report to stdout (or saves to file). Optionally, it can POST the report to the cloud backend.

2. GitHub Action: A Docker-based action that wraps the CLI and adds behavior: parses the PR diff to only check changed files’ docs, posts a comment with the score change, and manages the badge. The action is published to the GitHub Marketplace as a free action.

3. Cloud Backend (Vercel + MongoDB): Receives reports via a REST API. Stores per-project snapshots (using repo name as key). Provides endpoints to fetch history and aggregate scores. Built with Next.js API routes or plain Express on Vercel, using Mongoose to talk to a free MongoDB Atlas cluster.

4. Dashboard (React on Netlify): A single-page app that uses the backend API to display project trends, drill into snapshots, and show file-level results. It also exposes a badge endpoint that returns Shields.io-compatible JSON.

• Adoption inertia: Developers may resist adding another CI step. Mitigated by showing clear value and making it zero-config.
• Performance on large monorepos: Parsing many files could be slow. Add incremental parsing (only changed files) and caching.
• Evolving JS/TS syntax: TypeScript compiler API changes frequently. We pin a supported TS version and update rules accordingly.
• Low PR comment engagement: Comments may be ignored. Use a ‘doc debt’ threshold to fail the build if it drops too low.
• Free tier limits: MongoDB Atlas free tier is 512MB; Vercel free tier has execution limits. For huge projects, we may hit limits; plan accordingly with batching and data retention.

• Should we support zero-config (no file required) or force a configuration file?
• How to handle private repos that don’t want to send data to a public backend? Offline mode or self-hosted backend?
• Which comment styles to support in v1? Definitely JSDoc, TSDoc, maybe JavaDoc?
• Should we also lint code examples in Markdown (e.g., ensure they compile)? That adds complexity but high value.
• Do we need a separate badge endpoint or can Shields.io fetch directly from the API?

We started this in a weekend hackathon and got a working prototype with core parsing and a few rules. But then real jobs, family, and the sheer effort of building a full plugin system and dashboard drained momentum. It sits in a GitHub repo with a handful of stars and a 'coming soon' banner. The idea is solid, but execution never crossed the finish line.

The prototype used only GitHub Actions free tier and a MongoDB Atlas free cluster. The dashboard was a minimal React app on Netlify. At peak, we had about 20 rules implemented and a working badge. The hardest part was incremental parsing in CI to avoid re-scanning unchanged files, which we solved with git diff parsing.