doccoverage

Documentation coverage & quality analyzer — detects undocumented public functions, missing JSDoc/docstrings/godoc/Javadoc, incomplete parameter descriptions,...

Security Scan

DocCoverage's code, declared requirements, and runtime instructions are internally consistent with its stated purpose of a local, regex-based documentation coverage scanner that optionally installs git pre-commit hooks and validates an offline license key.

Purpose & Capability

Name/description (doc coverage across JS/TS, Python, Go, Java, Ruby) lines up with the included scripts (patterns.sh, analyzer.sh) and the provided commands. Required binaries (git, bash, python3, jq) are reasonable for file discovery, pattern matching, config parsing, and git-hook installation. The primary credential (DOCCOVERAGE_LICENSE_KEY) is appropriate for gating Pro/Team features.

Instruction Scope

SKILL.md and the scripts limit actions to local scanning, report generation, license validation, and modifying/creating lefthook.yml in a repository when installing hooks. The code reads ~/.openclaw/openclaw.json (declared in metadata) for optional configuration, and does not make network calls or transmit repository contents externally. Pre-commit hook behavior (sourcing patterns and analyzer then running hook_doccoverage_scan) is expected for a hooks-based scanner.

Install Mechanism

Install spec uses the well-known brew formula 'lefthook' to provide the lefthook binary used for git hooks. No arbitrary URL downloads or archive extraction are present; files included in the skill are the scanner implementation. This is proportionate for adding optional hook support.

Credentials

The declared primary env DOCCOVERAGE_LICENSE_KEY matches the code's license checks. The license module optionally uses CLAWHUB_JWT_SECRET to verify JWT signatures and may invoke node or openssl if present — these optional environment/command usages are not listed in requires.env but are only used when present (fallbacks). No other unrelated credentials are requested.

Persistence & Privilege

always is false and the skill does not request permanent system-wide privileges. The only persistent change is writing/modifying a repository's lefthook.yml when the user runs 'hooks install' (expected for a hook installer). The skill does not modify other skills' configs or agent-wide settings beyond reading the declared ~/.openclaw/openclaw.json.

Assessment

This skill appears to do what it claims: local, regex-based documentation scans and optional installation of lefthook pre-commit hooks. Before installing: 1) Understand that 'hooks install' will create or modify lefthook.yml in your repository root and will cause the hooks to run on every commit (it can block commits on critical findings). Back up any existing lefthook.yml if you have one. 2) Pro/Team features require DOCCOVERAGE_LICENSE_KEY (can be set as env var or placed into ~/.openclaw/openclaw.json); the license code stays local and performs offline JWT decoding. 3) The code may use node or openssl if present to assist license parsing/verification (these are optional fallbacks and not required). 4) If you rely on zero-telemetry/offline guarantees, review network calls in the environment where you run the skill — the included scripts do not perform outbound network requests. 5) If you want to be extra cautious, inspect the included scripts (patterns.sh, analyzer.sh, license.sh) yourself before running hooks install. Overall the skill is coherent with its stated purpose.

DocCoverage -- Documentation Coverage & Quality Analyzer

DocCoverage scans codebases for undocumented public functions, missing JSDoc/docstrings/godoc/Javadoc/YARD, incomplete parameter descriptions, outdated README sections, missing CHANGELOG entries, and documentation quality gaps. It uses regex-based pattern matching against 85+ documentation patterns across JS/TS, Python, Go, Java, and Ruby. Lefthook integration for git hooks, markdown coverage reports with doc quality scoring.

Commands

Free Tier (No license required)

doccoverage scan [file|directory]

One-shot documentation coverage scan of files or directories.

How to execute:

bash "<SKILL_DIR>/scripts/doccoverage.sh" scan [target]

What it does:

1. Accepts a file path or directory (defaults to current directory)
2. Auto-detects language from file extensions (JS/TS, Python, Go, Java, Ruby)
3. Finds all source files with public/exported functions, classes, and types
4. Runs 85+ documentation coverage patterns against each file
5. Calculates a documentation coverage score (0-100) per file and overall
6. Outputs findings with: file, line number, check ID, severity, description, recommendation
7. Exit code 0 if passing (score >= 70), exit code 1 if issues found
8. Free tier limited to 5 files per scan

Example usage scenarios:

• "Check my code for missing documentation" -> runs doccoverage scan .
• "Are my exported functions documented?" -> runs doccoverage scan src/
• "Scan this file for missing JSDoc" -> runs doccoverage scan src/utils.ts
• "Check documentation coverage of my Python module" -> runs doccoverage scan mymodule/

Pro Tier ($19/user/month -- requires DOCCOVERAGE_LICENSE_KEY)

doccoverage hooks install

Install git pre-commit hooks that scan staged files for documentation gaps before every commit.

How to execute:

bash "<SKILL_DIR>/scripts/doccoverage.sh" hooks install

What it does:

1. Validates Pro+ license
2. Copies lefthook config to project root
3. Installs lefthook pre-commit hook
4. On every commit: scans all staged files for missing documentation, blocks commit if critical/high findings, shows remediation advice

doccoverage hooks uninstall

Remove DocCoverage git hooks.

bash "<SKILL_DIR>/scripts/doccoverage.sh" hooks uninstall

doccoverage report [directory]

Generate a markdown documentation coverage report with findings, severity breakdown, and remediation steps.

bash "<SKILL_DIR>/scripts/doccoverage.sh" report [directory]

What it does:

1. Validates Pro+ license
2. Runs full scan of the directory
3. Generates a formatted markdown report from template
4. Includes per-file breakdowns, coverage scores, language-specific guidance
5. Output suitable for documentation reviews and team standards audits

doccoverage coverage [directory]

Calculate documentation coverage percentage across the codebase.

bash "<SKILL_DIR>/scripts/doccoverage.sh" coverage [directory]

What it does:

1. Validates Pro+ license
2. Identifies all public/exported functions, classes, types, and interfaces
3. Checks each for presence of documentation (JSDoc, docstring, godoc, etc.)
4. Calculates per-file and overall documentation coverage percentages
5. Reports coverage by language, by category, and overall

Team Tier ($39/user/month -- requires DOCCOVERAGE_LICENSE_KEY with team tier)

doccoverage policy [directory]

Enforce organization-specific documentation policies on codebases.

bash "<SKILL_DIR>/scripts/doccoverage.sh" policy [directory]

What it does:

1. Validates Team+ license
2. Loads custom policies from ~/.openclaw/openclaw.json (doccoverage.config.customPolicies)
3. Enforces organization-specific rules (e.g., all public APIs must have @example, all @param must include type)
4. Combines custom policies with built-in patterns for comprehensive scanning
5. Outputs SARIF-compatible results

doccoverage sarif [directory]

Generate SARIF JSON output for CI/CD integration.

bash "<SKILL_DIR>/scripts/doccoverage.sh" sarif [directory]

What it does:

1. Validates Team+ license
2. Runs full scan of the directory
3. Outputs findings in SARIF 2.1.0 JSON format
4. Compatible with GitHub Code Scanning, Azure DevOps, and other SARIF consumers

doccoverage changelog [directory]

Verify CHANGELOG completeness and consistency.

bash "<SKILL_DIR>/scripts/doccoverage.sh" changelog [directory]

What it does:

1. Validates Team+ license
2. Scans CHANGELOG.md or HISTORY.md for completeness
3. Checks for missing version entries, empty sections, broken date formats
4. Verifies recent git tags have corresponding changelog entries
5. Reports changelog health with specific remediation suggestions

doccoverage status

Show license and configuration information.

bash "<SKILL_DIR>/scripts/doccoverage.sh" status

Detected Documentation Gaps

DocCoverage detects 85+ documentation quality patterns across 6 categories:

Category	Examples	Severity
Missing Function/Method Docs	Exported functions without JSDoc, public methods without docstrings, Go exported functions without godoc, Java public methods without Javadoc, Ruby public methods without YARD	Critical/High
Incomplete Documentation	JSDoc missing @param tags, docstrings missing Args section, @deprecated without replacement, missing @returns, generic placeholder docs	High/Medium
README & Project Docs	Missing README.md, README without installation section, missing CONTRIBUTING.md, missing LICENSE, outdated badges, empty README sections	High/Medium
API Documentation	REST endpoints without docs, GraphQL types without descriptions, OpenAPI missing descriptions, missing error response docs	High/Medium
Type & Interface Docs	Exported TypeScript interfaces without docs, enum values without descriptions, generic type parameters without docs	Medium/Low
Comment Quality	Obvious/redundant comments, commented-out code blocks, outdated comments, TODO without ticket reference, FIXME older than threshold	Medium/Low

Configuration

Users can configure DocCoverage in ~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "doccoverage": {
        "enabled": true,
        "apiKey": "YOUR_LICENSE_KEY_HERE",
        "config": {
          "severityThreshold": "high",
          "customPolicies": [],
          "excludePatterns": ["**/test/**", "**/examples/**", "**/vendor/**"],
          "reportFormat": "markdown"
        }
      }
    }
  }
}

Important Notes

• Free tier works immediately with no configuration
• All scanning happens locally -- no code is sent to external servers
• License validation is offline -- no phone-home or network calls
• Pattern matching only -- no AST parsing, no external dependencies
• Supports scanning multiple languages in a single pass
• Git hooks use lefthook which must be installed (see install metadata above)
• Exit codes: 0 = passing (score >= 70), 1 = issues found (for CI/CD integration)
• Scoring: critical=25, high=15, medium=8, low=3 point deductions from 100

Error Handling

• If lefthook is not installed and user tries hooks install, prompt to install it
• If license key is invalid or expired, show clear message with link to https://doccoverage.pages.dev/renew
• If a file is binary, skip it automatically with no warning
• If no scannable files found in target, report clean scan with info message
• If language cannot be determined from extension, skip the file gracefully

When to Use DocCoverage

The user might say things like:

• "Check my code for missing documentation"
• "Are my public functions documented?"
• "Scan for missing JSDoc comments"
• "What is the documentation coverage of my project?"
• "Check if my Python docstrings are complete"
• "Scan for undocumented exported functions"
• "Generate a documentation coverage report"
• "Set up pre-commit hooks for doc coverage"
• "Check my README for missing sections"
• "Verify my CHANGELOG is up to date"
• "Are there any TODO comments without ticket references?"
• "Find commented-out code in my project"
• "Check TypeScript interfaces for missing docs"