stale-comment-guard

A pre-commit hook that blocks commits when code under a leading comment changes but the comment itself does not.

Keeps your comments honest — if the code they describe has changed, the comment must be updated or explicitly approved before the commit goes through.

The problem

// Validates user input and returns true if valid
function processPayment(amount, cardNumber) {  // ← this changed, comment didn't
  ...
}

This commit would be blocked. Either update the comment or run approve to acknowledge the change.

Installation

npm install --save-dev @farisabujolban/stale-comment-guard

Setup

With Husky

npm install --save-dev husky
npx husky init
echo "npx stale-comment-guard check" > .husky/pre-commit

Manual

Add to .git/hooks/pre-commit:

#!/bin/sh
npx stale-comment-guard check

Commands

stale-comment-guard check

Scans staged diffs for stale comments. Exits with code 1 if any are found, blocking the commit.

STALE COMMENT: src/auth.ts:12
  Comment: "// Validates user input and returns true if valid"
  Code changed at line(s) 14–18 but comment was not updated.
  → Run: stale-comment-guard approve src/auth.ts 12

stale-comment-guard approve <file> <line>

Records that you've reviewed the comment and acknowledged the code change. The approval is stored in .commentguard/approvals.json and is invalidated automatically if the comment or its owned code changes again.

stale-comment-guard approve src/auth.ts 12

Configuration

Create .commentguard.json in your project root:

{
  "maxOwnershipDistance": 3,
  "exclude": ["dist/**", "*.generated.ts"]
}

| Option | Default | Description | |--------|---------|-------------| | maxOwnershipDistance | 3 | Max blank lines between a comment and the code it owns | | exclude | [] | Glob patterns for files to skip |

How it works

• Only checks .js, .jsx, .ts, .tsx files
• Supports //, /* */, and /** */ comment styles
• A comment "owns" the code block immediately following it
• Approvals are tied to a hash of the comment text and the owned code — any change invalidates them

GitHub Actions

Add as a CI check to catch commits that bypassed the local hook:

name: stale-comment-guard
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - run: npx stale-comment-guard check

Commit approvals to git?

Yes — commit .commentguard/approvals.json so your team shares the same approval state.

Add to .gitignore only if you want each developer to manage approvals independently.