lint-debt

name	lint-debt
description	Track, audit, and create GitHub issues for lint suppression comments across your codebase. Ensures every lint bypass has a corresponding tracking issue.

Lint Debt Tracker — Suppression Audit & GitHub Issue Sync

Track, audit, and create GitHub issues for lint suppression comments across your codebase. Ensures every lint bypass (# lint-allow:, # noqa:, // eslint-disable, etc.) has a corresponding tracking issue.

Arguments

• scan — subcommand: scan, sync, report

Configuration

These variables are set in cognitive-core.conf (auto-populated by language packs):

Variable	Default	Purpose
CC_LINT_SUPPRESS_PATTERN	(from language pack)	ERE pattern matching lint suppressions
CC_LINT_DEBT_AUTO_ISSUE	true	Enable auto-issue reminders in post-edit hook
CC_LINT_DEBT_LABEL	technical-debt	GitHub label for debt tracking issues
CC_ORG	(project config)	GitHub owner for gh commands
CC_PROJECT_NAME	(project config)	GitHub repo name
CC_SRC_ROOT	src	Source directory to scan
CC_TEST_ROOT	tests	Test directory to scan

Commands

scan (default) — Find All Suppressions

Grep for CC_LINT_SUPPRESS_PATTERN across source and test directories. Parse each match into: file, line number, rule name, reason.

Steps:

1. Read CC_LINT_SUPPRESS_PATTERN from config. If empty, detect from CC_LANGUAGE:

   • perl: # lint-allow:
   • python: # noqa:|# type: ignore|# pylint: disable=
   • node: // eslint-disable|// @ts-ignore|// @ts-expect-error
   • go: //nolint:
   • java: @SuppressWarnings|//CHECKSTYLE:OFF
   • rust: #\[allow\(|#!\[allow\(
   • csharp: #pragma warning disable|// ReSharper disable

2. Use Grep tool to search across CC_SRC_ROOT and CC_TEST_ROOT:

   Grep pattern=<CC_LINT_SUPPRESS_PATTERN> path=<CC_SRC_ROOT> output_mode=content
   Grep pattern=<CC_LINT_SUPPRESS_PATTERN> path=<CC_TEST_ROOT> output_mode=content
   

3. Parse each match to extract:

   • file: relative path
   • line: line number
   • rule: extracted from the suppression comment (e.g., die_statement from # lint-allow: die_statement)
   • reason: text after the rule separator (e.g., - Infrastructure code from # lint-allow: die_statement - Infrastructure code)

4. Output grouped by rule:

## Lint Suppression Scan

| Rule | Count | Files |
|------|-------|-------|
| die_statement | 66 | 48 files |
| HashRefInflator | 4 | 4 files |
| direct_schema | 1 | 1 file |

**Total**: 71 suppressions across 52 files

### die_statement (66 occurrences)
| File | Line | Reason |
|------|------|--------|
| lib/TIMS/dao/UnifiedGenericDAO.pm | 28 | Infrastructure/framework code, system-level errors |
| ... | ... | ... |

sync — Create Missing GitHub Issues

Cross-reference suppressions with GitHub issues to create tracking issues for untracked debt.

Steps:

1. Run scan logic to get all current suppressions grouped by rule.

2. Search GitHub for existing tracking issues:

   gh issue list --repo <CC_ORG>/<CC_PROJECT_NAME> --label <CC_LINT_DEBT_LABEL> --state all --json number,title,state,body --limit 100
   

3. Match issues to suppression rules. Convention: issue title contains [lint-debt:<rule>] tag. Example: [lint-debt:die_statement] Replace die with structured error handling

4. For each untracked rule group, create a GitHub issue:

   gh issue create --repo <CC_ORG>/<CC_PROJECT_NAME> \
     --title "[lint-debt:<rule>] <remediation summary>" \
     --label "<CC_LINT_DEBT_LABEL>" \
     --body "<issue body>"
   

   Issue body template:

   ## Lint Debt: <rule>
   
   **Suppression count**: N occurrences across M files
   **Pattern**: `<suppression pattern used>`
   
   ### Affected Files
   
   | File | Line | Reason |
   |------|------|--------|
   | `path/to/file.pm` | 28 | Infrastructure code |
   | ... | ... | ... |
   
   ### Remediation
   
   <guidance based on rule type>
   
   ---
   *Auto-generated by `/lint-debt sync`. Updated: YYYY-MM-DD*
   

5. For tracked but stale issues (issue closed, suppressions remain): reopen or create new issue.

6. For tracked but resolved (issue open, no more suppressions): comment suggesting closure.

7. Report results:

   ## Lint Debt Sync Results
   
   | Rule | Status | Issue |
   |------|--------|-------|
   | die_statement | Already tracked | #56 (open) |
   | HashRefInflator | Created | #XX (new) |
   | direct_schema | Created | #YY (new) |
   
   **Created**: 2 | **Already tracked**: 1 | **Stale**: 0
   

report — Dashboard Summary

Cross-reference suppressions with GitHub issues and show a comprehensive dashboard.

Steps:

1. Run scan logic.
2. Fetch issues with CC_LINT_DEBT_LABEL.
3. Use git blame on each suppression line to determine when it was added.
4. Generate report:

## Lint Debt Report

### Overview
| Metric | Value |
|--------|-------|
| Total suppressions | 71 |
| Unique rules | 3 |
| Tracked (has issue) | 1 |
| Untracked | 2 |
| Files affected | 52 |

### By Rule
| Rule | Count | Issue | Status | Oldest |
|------|-------|-------|--------|--------|
| die_statement | 66 | #56 | open | 2025-03-15 |
| HashRefInflator | 4 | — | untracked | 2025-11-01 |
| direct_schema | 1 | — | untracked | 2026-02-18 |

### Recommendations
- Run `/lint-debt sync` to create 2 missing tracking issues
- Consider prioritizing die_statement (66 occurrences, oldest debt)

Language Pattern Reference

Language	Suppression Pattern (ERE)	Rule Extraction
perl	# lint-allow:	After : , before -
python	# noqa:|# type: ignore|# pylint: disable=	After noqa: / disable=
node	// eslint-disable|// @ts-ignore|// @ts-expect-error	After disable-next-line
go	//nolint:	After nolint:
java	@SuppressWarnings|//CHECKSTYLE:OFF	Inside ("...")
rust	#\[allow\(|#!\[allow\(	Inside allow(...)
csharp	#pragma warning disable|// ReSharper disable	After disable

Integration

• Post-edit hook: post-edit-lint.sh detects NEW suppressions via git diff and reminds to run /lint-debt sync
• CI/CD: Can be invoked in pipeline to fail builds with untracked suppressions
• Sprint planning: Use /lint-debt report during sprint planning to prioritize debt reduction