@farisabujolban/codeanchor 0.1.0

package/README.md

@@ -0,0 +1,249 @@
+# codeanchor
+
+`codeanchor` catches the class of bugs that ESLint, Prettier, and type checkers cannot: broken references between your repo's moving parts. Docs that reference deleted scripts. CI workflows that call scripts that don't exist. Dockerfiles that COPY paths that were renamed. Comments that silently lie about the code beneath them.
+
+It does not replace any existing tool. It runs alongside them.
+
+---
+
+## The problem it solves
+
+You rename `scripts/build.js` to `scripts/bundle.js`. Your README still says `npm run build`, your CI workflow still calls it, and your Dockerfile still tries to COPY the old path. Nothing fails until you deploy or onboard a new engineer. `codeanchor` catches this before the commit lands.
+
+---
+
+## Rules
+
+| ID | Description | Mode | Default Severity | Languages |
+|---|---|---|---|---|
+| CA-CD001 | Leading comment not updated after code changed | `staged` | error | JS, TS, Java, C, C++, C#, Go, Python |
+| CA-DOCS001 | README/docs reference an npm script missing from `package.json` | `repo`, `pr` | error | Markdown |
+| CA-DOCS002 | README/docs have a broken local Markdown link | `repo`, `pr` | error | Markdown |
+| CA-DOCS003 | README/docs mention a backtick-enclosed local path that doesn't exist | `repo`, `pr` | warn | Markdown |
+| CA-CI001 | GitHub Actions workflow references a missing npm script | `repo`, `pr` | error | YAML |
+| CA-CI003 | GitHub Actions workflow references a local path that doesn't exist | `repo`, `pr` | error | YAML |
+| CA-DOCKER001 | Dockerfile `COPY`/`ADD` references a path that doesn't exist | `repo`, `pr` | warn | Dockerfile |
+| CA-DOCKER002 | Dockerfile `RUN`/`CMD`/`ENTRYPOINT` references a missing script or file | `repo`, `pr` | warn | Dockerfile |
+| CA-PKG001 | `package.json` script references a local file that doesn't exist | `repo`, `pr` | error | JSON |
+| CA-PKG002 | `package.json` entrypoint field (`main`, `exports`, etc.) references a missing file | `repo`, `pr` | error | JSON |
+| CA-LOCK001 | Dependency fields changed in `package.json` but no lockfile was updated | `staged`, `pr` | error | JSON |
+| CA-TEST001 | Frequently changed file has no associated test | `history` | warn | All |
+| CA-TEST002 | Source changed much more often than its test — test may be stale | `history` | warn | All |
+| CA-OWN001 | Frequently changed file has no CODEOWNERS entry | `history` | warn | All |
+| CA-TODO003 | TODO/FIXME/HACK older than 90 days with no issue link | `history` | warn | All |
+
+---
+
+## Installation
+
+```bash
+npm install -g codeanchor
+```
+
+Or use without installing:
+
+```bash
+npx codeanchor scan --repo
+```
+
+---
+
+## Quick start
+
+**Pre-commit (staged files only):**
+```bash
+codeanchor scan --staged
+```
+
+**Full repo scan:**
+```bash
+codeanchor scan --repo
+```
+
+**PR diff (e.g. in CI):**
+```bash
+codeanchor scan --base origin/main --head HEAD
+```
+
+**History report (run weekly, never blocks commits):**
+```bash
+codeanchor scan --history --since 90d
+```
+
+**JSON output:**
+```bash
+codeanchor scan --repo --json report.json
+```
+
+**Markdown report:**
+```bash
+codeanchor scan --history --since 90d --markdown maintenance-report.md
+```
+
+**List all rules:**
+```bash
+codeanchor rules
+```
+
+---
+
+## Pre-commit setup
+
+### Husky
+
+```bash
+npm install --save-dev husky
+npx husky init
+echo "npx codeanchor scan --staged" > .husky/pre-commit
+```
+
+### pre-commit (Python ecosystem)
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: codeanchor
+        name: codeanchor
+        language: node
+        entry: npx codeanchor scan --staged
+        pass_filenames: false
+```
+
+---
+
+## GitHub Actions setup
+
+```yaml
+# .github/workflows/codeanchor.yml
+name: codeanchor
+on:
+  pull_request:
+  push:
+    branches: [main]
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npx codeanchor scan --base origin/main --head HEAD
+```
+
+---
+
+## Config reference
+
+Place `codeanchor.config.json` in your repo root. All fields are optional.
+
+```json
+{
+  "exclude": ["dist/**", "*.generated.ts", "vendor/**"],
+  "rules": {
+    "CA-CD001":     { "severity": "error", "maxOwnershipDistance": 20 },
+    "CA-DOCS001":   { "severity": "error" },
+    "CA-DOCS002":   { "severity": "error" },
+    "CA-CI001":     { "severity": "error" },
+    "CA-DOCKER001": { "severity": "warn" },
+    "CA-PKG001":    { "severity": "error" },
+    "CA-TEST001":   { "severity": "warn" },
+    "CA-TEST002":   { "severity": "warn" },
+    "CA-OWN001":    { "severity": "warn" },
+    "CA-TODO003":   { "severity": "warn" }
+  }
+}
+```
+
+Disable a rule entirely:
+
+```json
+{ "rules": { "CA-DOCKER001": false } }
+```
+
+### `maxOwnershipDistance` (CA-CD001)
+
+How many lines of code below a comment it owns. Default: 20. Increase for files with dense comment blocks; decrease for tighter enforcement.
+
+---
+
+## Approving intentional stale comments (CA-CD001)
+
+If a comment intentionally describes behavior that differs from the current code:
+
+```bash
+codeanchor approve src/api.ts 12
+codeanchor approve src/utils.py 8
+codeanchor approve src/Auth.java 22
+```
+
+Approvals are stored in `.commentguard/approvals.json` and are invalidated automatically if either the comment or the code beneath it changes.
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | No error-severity findings |
+| 1 | One or more error-severity findings |
+| 2 | Config or usage error |
+
+Use `--fail-on-warn` to exit 1 on warnings too.
+
+---
+
+## Supported languages (CA-CD001)
+
+| Language | Extensions | Comment syntax |
+|---|---|---|
+| JavaScript / TypeScript | `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs` | `//`, `/* */`, `/** */` |
+| Java | `.java` | `//`, `/* */`, `/** */` |
+| C / C++ | `.c`, `.h`, `.cpp`, `.hpp`, `.cc` | `//`, `/* */` |
+| C# | `.cs` | `//`, `/* */` |
+| Go | `.go` | `//`, `/* */` |
+| Python | `.py` | `#`, `"""docstrings"""` |
+
+---
+
+## Migrating from stale-comment-guard
+
+`codeanchor` is a drop-in superset. Your existing `.commentguard/approvals.json` is read without migration.
+
+| Old command | New command |
+|---|---|
+| `stale-comment-guard check` | `codeanchor scan --staged` |
+| `stale-comment-guard approve <file> <line>` | `codeanchor approve <file> <line>` |
+
+The config format changes from `.commentguard.json` to `codeanchor.config.json` under the `rules.CA-CD001` key. The old config is not read automatically — copy your settings across if needed.
+
+---
+
+## Demo
+
+The `demo/` directory is an intentionally broken repo. Run:
+
+```bash
+cd demo
+codeanchor scan --repo
+```
+
+Expected output will show violations for all Phase 1+2 rules.
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/your-username/codeanchor
+cd codeanchor
+npm install
+npm test
+npm run build
+```
+
+Tests use `vitest`. Phase 1–2 tests use temporary file fixtures; Phase 3 tests create real temporary git repos.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,177 @@
+import { Command } from 'commander';
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadConfig } from './config.js';
+import { getStagedDiff, getPrDiff, parseDiff } from './git/diff.js';
+import { runEngine } from './engine.js';
+import { printResult, renderMarkdown } from './reporter.js';
+import { getDriver } from './util/languages.js';
+import { findCommentAtLine } from './util/comment-parser.js';
+import { getOwnedRegion } from './util/ownership.js';
+import { loadApprovals, buildApproval, upsertApproval, saveApprovals } from './util/approvals.js';
+import { allRules } from './rules/index.js';
+const program = new Command();
+program
+    .name('codeanchor')
+    .description('Deterministic tech-debt and workflow-drift CLI')
+    .version('0.1.0');
+program
+    .command('scan')
+    .description('Scan for repo drift issues')
+    .option('--staged', 'Check only staged changes (pre-commit mode)')
+    .option('--repo', 'Check current repo state')
+    .option('--base <ref>', 'Base ref for PR diff')
+    .option('--head <ref>', 'Head ref for PR diff')
+    .option('--history', 'Enable history-based rules')
+    .option('--since <duration>', 'Window for history mode (e.g. 90d, 6m)')
+    .option('--rules <ids>', 'Comma-separated rule IDs to run')
+    .option('--json [path]', 'Write JSON output (stdout if no path given)')
+    .option('--markdown [path]', 'Write Markdown report (stdout if no path given)')
+    .option('--fail-on-warn', 'Exit 1 even for warnings')
+    .option('--no-color', 'Disable color output')
+    .action(async (opts) => {
+    const cwd = process.cwd();
+    const config = loadConfig(cwd);
+    let ruleIds;
+    if (opts.rules) {
+        ruleIds = opts.rules.split(',').map((s) => s.trim()).filter(Boolean);
+        const unknown = ruleIds.filter(id => !allRules.some(r => r.id === id));
+        if (unknown.length > 0) {
+            console.error(`Unknown rule IDs: ${unknown.join(', ')}`);
+            console.error(`Valid IDs: ${allRules.map(r => r.id).join(', ')}`);
+            process.exit(2);
+        }
+    }
+    let mode = 'repo';
+    let stagedDiffs = undefined;
+    if (opts.staged) {
+        mode = 'staged';
+        const rawDiff = getStagedDiff();
+        if (!rawDiff.trim()) {
+            console.log('No staged changes.');
+            process.exit(0);
+        }
+        stagedDiffs = parseDiff(rawDiff);
+    }
+    else if (opts.base && opts.head) {
+        mode = 'pr';
+        const rawDiff = getPrDiff(opts.base, opts.head);
+        if (rawDiff.trim()) {
+            stagedDiffs = parseDiff(rawDiff);
+        }
+    }
+    else if (opts.history) {
+        mode = 'history';
+    }
+    const result = await runEngine({
+        mode,
+        repoRoot: cwd,
+        config,
+        stagedDiffs,
+        since: opts.since,
+        ruleIds,
+    });
+    const shouldFail = result.errorCount > 0 || (opts.failOnWarn && result.warnCount > 0);
+    if (opts.json !== undefined) {
+        const ruleBreakdown = {};
+        for (const f of result.findings) {
+            ruleBreakdown[f.ruleId] = (ruleBreakdown[f.ruleId] ?? 0) + 1;
+        }
+        const jsonOutput = {
+            version: '1',
+            mode: result.mode,
+            timestamp: result.timestamp,
+            repoRoot: result.repoRoot,
+            summary: {
+                errorCount: result.errorCount,
+                warnCount: result.warnCount,
+                ruleBreakdown,
+            },
+            findings: result.findings,
+        };
+        const json = JSON.stringify(jsonOutput, null, 2) + '\n';
+        if (typeof opts.json === 'string') {
+            fs.writeFileSync(opts.json, json, 'utf-8');
+        }
+        else {
+            process.stdout.write(json);
+        }
+        if (shouldFail)
+            process.exit(1);
+        return;
+    }
+    if (opts.markdown !== undefined) {
+        const md = renderMarkdown(result);
+        if (typeof opts.markdown === 'string') {
+            fs.writeFileSync(opts.markdown, md, 'utf-8');
+        }
+        else {
+            process.stdout.write(md);
+        }
+        if (shouldFail)
+            process.exit(1);
+        return;
+    }
+    printResult(result);
+    if (shouldFail) {
+        process.exit(1);
+    }
+});
+program
+    .command('approve <file> <line>')
+    .description('Mark a stale comment as intentionally reviewed')
+    .action((file, lineStr) => {
+    const cwd = process.cwd();
+    const line = parseInt(lineStr, 10);
+    if (isNaN(line)) {
+        console.error(`Invalid line number: ${lineStr}`);
+        process.exit(2);
+    }
+    const driver = getDriver(file);
+    if (!driver) {
+        console.error(`Unsupported file type: ${file}`);
+        process.exit(2);
+    }
+    const absPath = path.resolve(cwd, file);
+    let content;
+    try {
+        content = fs.readFileSync(absPath, 'utf-8');
+    }
+    catch {
+        console.error(`Cannot read file: ${file}`);
+        process.exit(2);
+    }
+    const comment = findCommentAtLine(content, line, driver);
+    if (!comment) {
+        console.error(`No leading comment found at line ${line} in ${file}`);
+        process.exit(2);
+    }
+    const config = loadConfig(cwd);
+    const ruleCfg = config.rules['CA-CD001'];
+    const maxDist = typeof ruleCfg === 'object' && ruleCfg?.maxOwnershipDistance
+        ? ruleCfg.maxOwnershipDistance
+        : 20;
+    const lines = content.split('\n');
+    const region = getOwnedRegion(comment, lines, maxDist, driver);
+    if (!region) {
+        console.error(`Could not determine owned region for comment at ${file}:${line}`);
+        process.exit(2);
+    }
+    const store = loadApprovals(cwd);
+    const approval = buildApproval(file, comment, lines, region, cwd);
+    upsertApproval(store, approval);
+    saveApprovals(store, cwd);
+    console.log(`Approved ${file}:${line}`);
+});
+program
+    .command('rules')
+    .description('List all rules with ID, description, mode, and default severity')
+    .action(() => {
+    console.log('\nAvailable rules:\n');
+    for (const rule of allRules) {
+        const modes = rule.applicableModes.join(', ');
+        console.log(`  ${rule.id}  [${rule.defaultSeverity}]  modes: ${modes}`);
+        console.log(`  ${rule.description}\n`);
+    }
+});
+program.parse();

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+export interface RuleConfig {
+    severity?: 'error' | 'warn' | 'info';
+    maxOwnershipDistance?: number;
+}
+export interface CodeAnchorConfig {
+    exclude: string[];
+    rules: Record<string, RuleConfig | false | undefined>;
+}
+export declare function loadConfig(cwd?: string): CodeAnchorConfig;

package/dist/config.js

@@ -0,0 +1,37 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const DEFAULTS = {
+    exclude: [],
+    rules: {
+        'CA-CD001': { severity: 'error', maxOwnershipDistance: 20 },
+        'CA-DOCS001': { severity: 'error' },
+        'CA-DOCS002': { severity: 'error' },
+        'CA-DOCS003': { severity: 'warn' },
+        'CA-CI001': { severity: 'error' },
+        'CA-CI003': { severity: 'error' },
+        'CA-DOCKER001': { severity: 'warn' },
+        'CA-DOCKER002': { severity: 'warn' },
+        'CA-PKG001': { severity: 'error' },
+        'CA-PKG002': { severity: 'error' },
+        'CA-LOCK001': { severity: 'error' },
+        'CA-TEST001': { severity: 'warn' },
+        'CA-TEST002': { severity: 'warn' },
+        'CA-OWN001': { severity: 'warn' },
+        'CA-TODO003': { severity: 'warn' },
+    },
+};
+export function loadConfig(cwd = process.cwd()) {
+    const configPath = path.join(cwd, 'codeanchor.config.json');
+    if (!fs.existsSync(configPath))
+        return DEFAULTS;
+    try {
+        const user = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        return {
+            exclude: user.exclude ?? DEFAULTS.exclude,
+            rules: { ...DEFAULTS.rules, ...user.rules },
+        };
+    }
+    catch {
+        return DEFAULTS;
+    }
+}

package/dist/engine.d.ts

@@ -0,0 +1,18 @@
+import type { Finding, ScanResult, ScanMode, FileDiff } from './types.js';
+import type { CodeAnchorConfig } from './config.js';
+export interface RuleContext {
+    mode: ScanMode;
+    repoRoot: string;
+    config: CodeAnchorConfig;
+    stagedDiffs?: FileDiff[];
+    since?: string;
+    ruleIds?: string[];
+}
+export interface Rule {
+    id: string;
+    description: string;
+    defaultSeverity: 'error' | 'warn' | 'info';
+    applicableModes: ScanMode[];
+    run(ctx: RuleContext): Promise<Finding[]>;
+}
+export declare function runEngine(ctx: RuleContext): Promise<ScanResult>;

package/dist/engine.js

@@ -0,0 +1,30 @@
+import { allRules } from './rules/index.js';
+export async function runEngine(ctx) {
+    const applicableRules = allRules.filter(rule => {
+        if (ctx.ruleIds && !ctx.ruleIds.includes(rule.id))
+            return false;
+        const ruleCfg = ctx.config.rules[rule.id];
+        if (ruleCfg === false)
+            return false;
+        return rule.applicableModes.includes(ctx.mode);
+    });
+    const allFindings = [];
+    for (const rule of applicableRules) {
+        const findings = await rule.run(ctx);
+        const ruleCfg = ctx.config.rules[rule.id];
+        if (typeof ruleCfg === 'object' && ruleCfg?.severity) {
+            for (const f of findings) {
+                f.severity = ruleCfg.severity;
+            }
+        }
+        allFindings.push(...findings);
+    }
+    return {
+        mode: ctx.mode,
+        timestamp: new Date().toISOString(),
+        repoRoot: ctx.repoRoot,
+        findings: allFindings,
+        errorCount: allFindings.filter(f => f.severity === 'error').length,
+        warnCount: allFindings.filter(f => f.severity === 'warn').length,
+    };
+}

package/dist/git/blame.d.ts

@@ -0,0 +1,8 @@
+export interface BlameLine {
+    lineNumber: number;
+    commitHash: string;
+    authorTime: number;
+    content: string;
+}
+export declare function getBlameLines(repoRoot: string, filePath: string): BlameLine[];
+export declare function getBlameAge(repoRoot: string, filePath: string): Map<number, number>;

package/dist/git/blame.js

@@ -0,0 +1,57 @@
+import { execFileSync } from 'node:child_process';
+export function getBlameLines(repoRoot, filePath) {
+    let raw;
+    try {
+        raw = execFileSync('git', ['blame', '--porcelain', '--', filePath], {
+            encoding: 'utf-8',
+            cwd: repoRoot,
+        });
+    }
+    catch {
+        return [];
+    }
+    const lines = [];
+    // commitTimes caches author-time per commit hash — porcelain omits it for repeated commits
+    const commitTimes = new Map();
+    const parts = raw.split('\n');
+    let i = 0;
+    while (i < parts.length) {
+        const line = parts[i];
+        if (!line) {
+            i++;
+            continue;
+        }
+        const headerMatch = line.match(/^([0-9a-f]{40}) \d+ (\d+)(?: \d+)?$/);
+        if (!headerMatch) {
+            i++;
+            continue;
+        }
+        const hash = headerMatch[1];
+        const finalLine = parseInt(headerMatch[2], 10);
+        i++;
+        let authorTime = commitTimes.get(hash) ?? 0;
+        // Parse header fields until we hit the tab-prefixed content line
+        while (i < parts.length && !parts[i].startsWith('\t')) {
+            const field = parts[i];
+            if (field.startsWith('author-time ')) {
+                authorTime = parseInt(field.slice(12), 10);
+                commitTimes.set(hash, authorTime);
+            }
+            i++;
+        }
+        const content = parts[i]?.startsWith('\t') ? parts[i].slice(1) : '';
+        lines.push({ lineNumber: finalLine, commitHash: hash, authorTime, content });
+        i++;
+    }
+    return lines;
+}
+// Returns a map from 1-indexed line number → age in seconds
+export function getBlameAge(repoRoot, filePath) {
+    const blameLines = getBlameLines(repoRoot, filePath);
+    const now = Date.now() / 1000;
+    const ageMap = new Map();
+    for (const bl of blameLines) {
+        ageMap.set(bl.lineNumber, now - bl.authorTime);
+    }
+    return ageMap;
+}

package/dist/git/diff.d.ts

@@ -0,0 +1,5 @@
+import type { FileDiff } from '../types.js';
+export declare function getStagedDiff(): string;
+export declare function getPrDiff(base: string, head: string): string;
+export declare function parseDiff(raw: string): FileDiff[];
+export declare function diffTouchesRange(fileDiff: FileDiff, startLine: number, endLine: number): boolean;

package/dist/git/diff.js

@@ -0,0 +1,75 @@
+import { execFileSync } from 'node:child_process';
+export function getStagedDiff() {
+    try {
+        return execFileSync('git', ['diff', '--staged'], { encoding: 'utf-8' });
+    }
+    catch {
+        return '';
+    }
+}
+export function getPrDiff(base, head) {
+    try {
+        return execFileSync('git', ['diff', `${base}...${head}`], { encoding: 'utf-8' });
+    }
+    catch {
+        return '';
+    }
+}
+export function parseDiff(raw) {
+    const results = [];
+    const fileBlocks = raw.split(/^diff --git /m).slice(1);
+    for (const block of fileBlocks) {
+        const lines = block.split('\n');
+        let path = '';
+        let status = 'modified';
+        const changedLines = new Set();
+        for (const line of lines) {
+            if (line.startsWith('--- /dev/null')) {
+                status = 'added';
+            }
+            else if (line.startsWith('+++ /dev/null')) {
+                status = 'deleted';
+            }
+            else if (line.startsWith('+++ b/')) {
+                path = line.slice(6).trim();
+            }
+            else if (line.startsWith('rename to ')) {
+                status = 'renamed';
+                path = line.slice(10).trim();
+            }
+        }
+        if (!path)
+            continue;
+        let newLineNum = 0;
+        let inHunk = false;
+        for (const line of lines) {
+            const hunkMatch = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+            if (hunkMatch) {
+                newLineNum = parseInt(hunkMatch[1], 10);
+                inHunk = true;
+                continue;
+            }
+            if (!inHunk)
+                continue;
+            if (line.startsWith('+') && !line.startsWith('+++')) {
+                changedLines.add(newLineNum);
+                newLineNum++;
+            }
+            else if (line.startsWith('-') && !line.startsWith('---')) {
+                // removed line — doesn't advance new-file counter
+            }
+            else if (!line.startsWith('\\')) {
+                newLineNum++;
+            }
+        }
+        results.push({ path, status, changedLines });
+    }
+    return results;
+}
+export function diffTouchesRange(fileDiff, startLine, endLine) {
+    for (let i = startLine; i <= endLine; i++) {
+        if (fileDiff.changedLines.has(i))
+            return true;
+    }
+    return false;
+}

package/dist/git/history.d.ts

@@ -0,0 +1,7 @@
+export interface HotFile {
+    path: string;
+    commitCount: number;
+}
+export declare function parseSinceDuration(since: string): string;
+export declare function getHotFiles(repoRoot: string, since: string, minCommits?: number): HotFile[];
+export declare function getFileCommitCount(repoRoot: string, filePath: string, since: string): number;