- ts-ignore/ts-nocheck detector now only flags real suppression directives (token immediately after the // or /* comment opener), not prose mentions - outdated-dep detector now parses pnpm's Unicode box-drawing table, skipping header/separator rows; surfaces real outdated deps instead of one garbage row
425 lines
16 KiB
JavaScript
425 lines
16 KiB
JavaScript
#!/usr/bin/env node
|
|
// gc-scan.mjs — deterministic garbage detection for the GC bot
|
|
// Zero npm dependencies. Emits gc-findings.json consumed by the garbage-collector agent.
|
|
//
|
|
// Usage: node scripts/gc-scan.mjs [--out <path>] [--days-branch=90] [--days-comment=180]
|
|
|
|
import { execSync } from 'node:child_process';
|
|
import { writeFileSync, readFileSync, existsSync } from 'node:fs';
|
|
import { join, resolve, relative } from 'node:path';
|
|
|
|
const ROOT = process.cwd();
|
|
|
|
// Parse CLI args: --out <path>, --days-branch=N, --days-comment=N
|
|
const ARGS = Object.fromEntries(
|
|
process.argv.slice(2).flatMap(a => {
|
|
const m = a.match(/^--([\w-]+)=(.+)$/);
|
|
return m ? [[m[1], m[2]]] : [];
|
|
})
|
|
);
|
|
const outIdx = process.argv.indexOf('--out');
|
|
const OUT = outIdx !== -1 ? process.argv[outIdx + 1] : (ARGS['out'] ?? 'gc-findings.json');
|
|
const STALE_BRANCH_DAYS = Number(ARGS['days-branch'] ?? 90);
|
|
const STALE_COMMENT_DAYS = Number(ARGS['days-comment'] ?? 180);
|
|
|
|
/** @type {Array<Record<string, unknown>>} */
|
|
const findings = [];
|
|
|
|
function run(cmd) {
|
|
try {
|
|
return execSync(cmd, { encoding: 'utf8', cwd: ROOT, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
|
|
} catch {
|
|
return '';
|
|
}
|
|
}
|
|
|
|
function add(finding) {
|
|
findings.push(finding);
|
|
}
|
|
|
|
function daysAgo(isoDate) {
|
|
if (!isoDate) return Infinity;
|
|
return (Date.now() - new Date(isoDate).getTime()) / 86_400_000;
|
|
}
|
|
|
|
// ─── Detector 1: Stale branches ──────────────────────────────────────────────
|
|
function detectStaleBranches() {
|
|
const out = run(
|
|
'git for-each-ref --sort=committerdate refs/remotes/origin ' +
|
|
'--format=%(refname:short)|%(committerdate:iso8601)|%(authorname)|%(subject)'
|
|
);
|
|
for (const line of out.split('\n').filter(Boolean)) {
|
|
const [ref, date, author, subject] = line.split('|');
|
|
const branch = ref.replace('origin/', '');
|
|
if (['HEAD', 'main', 'master', 'develop'].includes(branch)) continue;
|
|
const age = daysAgo(date);
|
|
if (age < STALE_BRANCH_DAYS) continue;
|
|
const mergeBase = run(`git merge-base origin/main "${ref}" 2>/dev/null`);
|
|
const branchHead = run(`git rev-parse "${ref}"`);
|
|
const isMerged = mergeBase === branchHead;
|
|
add({
|
|
type: 'stale-branch',
|
|
tier: 'B',
|
|
branch,
|
|
author,
|
|
lastCommitDate: date?.trim(),
|
|
ageDays: Math.floor(age),
|
|
isMerged,
|
|
lastSubject: subject,
|
|
description: `Branch '${branch}' is ${Math.floor(age)} days old${isMerged ? ' and fully merged into main — safe to delete' : ' with no recent activity'}`,
|
|
});
|
|
}
|
|
}
|
|
|
|
// ─── Detector 2: Stale TODO/FIXME/HACK comments ──────────────────────────────
|
|
function detectStaleTodos() {
|
|
const raw = run(
|
|
'git grep -rn --fixed-strings -e "TODO" -e "FIXME" -e "HACK" -e "XXX" ' +
|
|
'-- "*.ts" "*.tsx" "*.mjs" "*.js"'
|
|
);
|
|
if (!raw) return;
|
|
|
|
// Cap at 40 matches to keep git blame calls fast on large repos
|
|
const lines = raw.split('\n').filter(Boolean).slice(0, 40);
|
|
|
|
for (const line of lines) {
|
|
const firstColon = line.indexOf(':');
|
|
if (firstColon === -1) continue;
|
|
const afterFile = line.slice(firstColon + 1);
|
|
const secondColon = afterFile.indexOf(':');
|
|
if (secondColon === -1) continue;
|
|
|
|
const file = line.slice(0, firstColon);
|
|
const lineNum = afterFile.slice(0, secondColon);
|
|
const content = afterFile.slice(secondColon + 1).trim();
|
|
|
|
if (file.startsWith('node_modules/') || file.includes('public/cesium')) continue;
|
|
|
|
const blameOut = run(`git blame -L ${lineNum},${lineNum} --porcelain "${file}"`);
|
|
const timeMatch = blameOut.match(/^author-time (\d+)/m);
|
|
if (!timeMatch) continue;
|
|
|
|
const ageInDays = (Date.now() - parseInt(timeMatch[1], 10) * 1000) / 86_400_000;
|
|
if (ageInDays < STALE_COMMENT_DAYS) continue;
|
|
|
|
const issueMatch = content.match(/#(\d+)/);
|
|
let issueClosed = false;
|
|
if (issueMatch) {
|
|
const state = run(`gh issue view ${issueMatch[1]} --json state -q .state 2>/dev/null`);
|
|
issueClosed = state.toUpperCase() === 'CLOSED';
|
|
}
|
|
|
|
add({
|
|
type: 'stale-todo',
|
|
tier: 'A',
|
|
file,
|
|
line: parseInt(lineNum, 10),
|
|
content: content.slice(0, 200),
|
|
ageInDays: Math.round(ageInDays),
|
|
issueClosed,
|
|
linkedIssue: issueMatch ? issueMatch[1] : null,
|
|
description: issueClosed
|
|
? `TODO references closed issue #${issueMatch[1]} (${Math.round(ageInDays)}d old) — safe to delete`
|
|
: `TODO/comment is ${Math.round(ageInDays)} days old — review and resolve or delete`,
|
|
});
|
|
}
|
|
}
|
|
|
|
// ─── Detector 3: Known anti-patterns ─────────────────────────────────────────
|
|
const ANTI_PATTERNS = [
|
|
{
|
|
id: 'mdc-ref',
|
|
tier: 'A',
|
|
globs: ['*.ts', '*.tsx'],
|
|
pattern: '[\'"].*\\.mdc[\'"]',
|
|
excludePrefix: 'scripts/',
|
|
desc: '.mdc file reference — must be .md (project invariant: never .mdc files)',
|
|
},
|
|
{
|
|
id: 'console-log',
|
|
tier: 'A',
|
|
globs: ['*.ts', '*.tsx'],
|
|
pattern: 'console\\.log(',
|
|
excludePrefix: 'scripts/',
|
|
desc: 'stray console.log — remove or replace with structured logging',
|
|
},
|
|
{
|
|
id: 'ts-ignore',
|
|
tier: 'A',
|
|
globs: ['*.ts', '*.tsx'],
|
|
pattern: '@ts-ignore',
|
|
// Only flag the actual suppression directive form (// @ts-ignore or /* @ts-ignore),
|
|
// not the token appearing in JSDoc prose (e.g. "No @ts-ignore used here").
|
|
directiveOnly: true,
|
|
desc: '@ts-ignore suppresses real type errors — remove and fix the underlying type',
|
|
},
|
|
{
|
|
id: 'ts-nocheck',
|
|
tier: 'A',
|
|
globs: ['*.ts', '*.tsx'],
|
|
pattern: '@ts-nocheck',
|
|
directiveOnly: true,
|
|
desc: '@ts-nocheck disables all type checking for the file — remove and fix types',
|
|
},
|
|
{
|
|
id: 'hardcoded-url',
|
|
tier: 'B',
|
|
globs: ['*.ts', '*.tsx'],
|
|
pattern: 'localhost:500',
|
|
excludePrefix: 'scripts/',
|
|
desc: 'hardcoded engine URL (localhost:5001/5000) — use env var or plugin streamUrl instead',
|
|
},
|
|
{
|
|
id: 'deprecated',
|
|
tier: 'B',
|
|
globs: ['*.ts', '*.tsx'],
|
|
pattern: '@deprecated',
|
|
desc: '@deprecated JSDoc on a symbol — audit whether all callers have migrated',
|
|
},
|
|
];
|
|
|
|
function detectAntiPatterns() {
|
|
for (const { id, tier, globs, pattern, desc, excludePrefix, directiveOnly } of ANTI_PATTERNS) {
|
|
const globArgs = globs.map(g => `"${g}"`).join(' ');
|
|
const raw = run(`git grep -En "${pattern}" -- ${globArgs}`);
|
|
if (!raw) continue;
|
|
|
|
const hits = raw
|
|
.split('\n')
|
|
.filter(l => l && !(excludePrefix && l.startsWith(excludePrefix)))
|
|
.slice(0, 15);
|
|
|
|
for (const line of hits) {
|
|
const m = line.match(/^([^:]+):(\d+):(.*)/);
|
|
if (!m) continue;
|
|
if (m[1].startsWith('node_modules/') || m[1].includes('public/cesium')) continue;
|
|
const content = m[3].trim();
|
|
// For directive-only patterns (e.g. @ts-ignore), skip lines where the token
|
|
// appears in prose rather than as a comment suppression directive.
|
|
// A real directive has @ts-ignore/@ts-nocheck immediately after the // or /*
|
|
// comment opener — not buried mid-sentence in a comment that mentions it.
|
|
if (directiveOnly && !/^\s*\/[/*]\s*@ts-(ignore|nocheck)/.test(m[3])) continue;
|
|
add({
|
|
type: 'anti-pattern',
|
|
patternId: id,
|
|
tier,
|
|
file: m[1],
|
|
line: parseInt(m[2], 10),
|
|
content: content.slice(0, 200),
|
|
description: desc,
|
|
});
|
|
}
|
|
}
|
|
}
|
|
|
|
// ─── Detector 4: Oversized source files ──────────────────────────────────────
|
|
function detectOversizedFiles() {
|
|
const fileList = run('git ls-files "*.ts" "*.tsx"').split('\n').filter(Boolean);
|
|
for (const file of fileList) {
|
|
if (file.startsWith('node_modules/') || file.includes('public/cesium') || file.includes('.next/')) continue;
|
|
const fullPath = join(ROOT, file);
|
|
if (!existsSync(fullPath)) continue;
|
|
const lineCount = readFileSync(fullPath, 'utf8').split('\n').length;
|
|
if (lineCount > 350) {
|
|
add({
|
|
type: 'oversized-file',
|
|
tier: 'B',
|
|
file,
|
|
lines: lineCount,
|
|
description: `${lineCount} lines exceeds ~300-line convention — extract helpers, split component, or use hooks`,
|
|
});
|
|
}
|
|
}
|
|
}
|
|
|
|
// ─── Detector 5: Orphaned rule file references ───────────────────────────────
|
|
function detectOrphanedRuleRefs() {
|
|
const ruleFiles = run('git ls-files ".agents/rules/"').split('\n').filter(f => f.endsWith('.md'));
|
|
for (const ruleFile of ruleFiles) {
|
|
const fullPath = join(ROOT, ruleFile);
|
|
if (!existsSync(fullPath)) continue;
|
|
const content = readFileSync(fullPath, 'utf8');
|
|
const seen = new Set();
|
|
for (const [, ref] of content.matchAll(
|
|
/`((?:src|packages|local-plugins|local-seeders|\.agents)\/[^`\s]+)`/g
|
|
)) {
|
|
const base = ref.replace(/\/\*\*.*/, '').replace(/\/\*.*/, '').replace(/\{[^}]+\}.*/, '');
|
|
if (!base || seen.has(base)) continue;
|
|
seen.add(base);
|
|
const tracked = run(`git ls-files "${base}" "${base}/" 2>/dev/null`);
|
|
if (!tracked && !existsSync(join(ROOT, base))) {
|
|
add({
|
|
type: 'orphaned-rule-ref',
|
|
tier: 'B',
|
|
file: ruleFile,
|
|
ref: base,
|
|
description: `Rule file references '${base}' which no longer exists — update or remove`,
|
|
});
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
// ─── Detector 6: Orphaned workspace packages ─────────────────────────────────
|
|
function detectOrphanedPackages() {
|
|
try {
|
|
const wsInfo = run('pnpm list --recursive --depth=0 --json 2>/dev/null');
|
|
if (!wsInfo) return;
|
|
const pkgs = JSON.parse(wsInfo);
|
|
const allNames = new Set(pkgs.map(p => p.name).filter(Boolean));
|
|
const reverseDepCount = Object.fromEntries([...allNames].map(n => [n, 0]));
|
|
for (const pkg of pkgs) {
|
|
for (const dep of Object.keys({ ...pkg.dependencies, ...pkg.devDependencies })) {
|
|
if (reverseDepCount[dep] !== undefined) reverseDepCount[dep]++;
|
|
}
|
|
}
|
|
for (const [name, count] of Object.entries(reverseDepCount)) {
|
|
const pkg = pkgs.find(p => p.name === name);
|
|
if (!pkg?.path?.includes('/packages/')) continue;
|
|
if (count === 0) {
|
|
add({
|
|
type: 'orphaned-package',
|
|
tier: 'B',
|
|
name,
|
|
path: relative(ROOT, pkg.path),
|
|
description: `Workspace package '${name}' has no reverse dependencies inside the monorepo — consider removing`,
|
|
});
|
|
}
|
|
}
|
|
} catch { /* skip if pnpm unavailable */ }
|
|
}
|
|
|
|
// ─── Detector 7: Old Prisma migrations ───────────────────────────────────────
|
|
function detectOldMigrations() {
|
|
const migrationsDir = resolve(ROOT, 'prisma/migrations');
|
|
if (!existsSync(migrationsDir)) return;
|
|
const dirs = run(`ls -1 "${migrationsDir}"`).split('\n').filter(Boolean);
|
|
for (const dir of dirs) {
|
|
const sqlFile = `prisma/migrations/${dir}/migration.sql`;
|
|
const lastTouch = run(`git log -1 --format=%ci -- "${sqlFile}"`);
|
|
if (!lastTouch) continue;
|
|
const age = daysAgo(lastTouch);
|
|
if (age < 365) continue;
|
|
add({
|
|
type: 'old-migration',
|
|
tier: 'B',
|
|
migration: dir,
|
|
ageDays: Math.floor(age),
|
|
lastTouched: lastTouch.trim(),
|
|
description: `Migration '${dir}' is ${Math.floor(age)} days old — verify it is still actively needed`,
|
|
});
|
|
}
|
|
}
|
|
|
|
// ─── Detector 8: Outdated dependencies ───────────────────────────────────────
|
|
function detectOutdatedDeps() {
|
|
if (!existsSync(join(ROOT, 'package.json'))) return;
|
|
const raw = run('pnpm outdated --no-color 2>/dev/null || true');
|
|
if (!raw) return;
|
|
// pnpm outdated renders a Unicode box-drawing table. Data rows start with │ and
|
|
// contain pipe-separated columns; separator/border rows contain ─ or ┼ characters.
|
|
// We extract data rows by splitting on │ and discarding header/separator lines.
|
|
const SEPARATOR_CHARS = /[┌┐└┘├┤─]/;
|
|
const tableDataRows = raw
|
|
.split('\n')
|
|
.filter(l => l.startsWith('│') && !SEPARATOR_CHARS.test(l));
|
|
// Fall back to plain whitespace-separated output (older pnpm / --no-color plain format)
|
|
const plainDataLines = !tableDataRows.length
|
|
? raw.split('\n').filter(l => l.trim() && !l.startsWith('Package') && !l.startsWith('Legend') && !l.startsWith(' '))
|
|
: [];
|
|
|
|
const dataLines = tableDataRows.length ? tableDataRows : plainDataLines;
|
|
|
|
for (const line of dataLines.slice(0, 12)) {
|
|
let pkg, current, latest;
|
|
if (tableDataRows.length) {
|
|
// Parse │ col1 │ col2 │ col3 │ format
|
|
const cols = line.split('│').map(c => c.trim()).filter(Boolean);
|
|
if (cols.length < 3) continue;
|
|
// Header row: first column is literally "Package"
|
|
if (cols[0] === 'Package') continue;
|
|
[pkg, current, latest] = cols;
|
|
// current may be "1.2.3 (wanted 1.2.4)" — extract just the installed version
|
|
current = current.split(' ')[0];
|
|
} else {
|
|
const cols = line.trim().split(/\s+/);
|
|
if (cols.length < 3) continue;
|
|
[pkg, current, latest] = cols;
|
|
}
|
|
if (!pkg || !current || !latest || current === latest) continue;
|
|
const isMajor = current.replace(/^[^0-9]*/, '').split('.')[0] !== latest.replace(/^[^0-9]*/, '').split('.')[0];
|
|
add({
|
|
type: 'outdated-dep',
|
|
tier: 'B',
|
|
package: pkg,
|
|
current,
|
|
latest,
|
|
isMajor,
|
|
description: `${pkg}: ${current} → ${latest}${isMajor ? ' ⚠ MAJOR bump — review breaking changes before upgrading' : ''}`,
|
|
});
|
|
}
|
|
}
|
|
|
|
// ─── Run all detectors ────────────────────────────────────────────────────────
|
|
console.log('WorldWideView GC Scan');
|
|
console.log(`Repo: ${run('git remote get-url origin') || ROOT}`);
|
|
console.log(`Commit: ${run('git rev-parse --short HEAD') || 'unknown'}`);
|
|
console.log(`Thresholds: branch=${STALE_BRANCH_DAYS}d comment=${STALE_COMMENT_DAYS}d`);
|
|
console.log('');
|
|
|
|
detectStaleBranches();
|
|
console.log(` stale-branch ${findings.filter(f => f.type === 'stale-branch').length}`);
|
|
|
|
detectStaleTodos();
|
|
console.log(` stale-todo ${findings.filter(f => f.type === 'stale-todo').length}`);
|
|
|
|
detectAntiPatterns();
|
|
console.log(` anti-pattern ${findings.filter(f => f.type === 'anti-pattern').length}`);
|
|
|
|
detectOversizedFiles();
|
|
console.log(` oversized-file ${findings.filter(f => f.type === 'oversized-file').length}`);
|
|
|
|
detectOrphanedRuleRefs();
|
|
console.log(` orphaned-rule-ref ${findings.filter(f => f.type === 'orphaned-rule-ref').length}`);
|
|
|
|
detectOrphanedPackages();
|
|
console.log(` orphaned-package ${findings.filter(f => f.type === 'orphaned-package').length}`);
|
|
|
|
detectOldMigrations();
|
|
console.log(` old-migration ${findings.filter(f => f.type === 'old-migration').length}`);
|
|
|
|
detectOutdatedDeps();
|
|
console.log(` outdated-dep ${findings.filter(f => f.type === 'outdated-dep').length}`);
|
|
|
|
// Deduplicate
|
|
const seen = new Set();
|
|
const deduped = findings.filter(f => {
|
|
const key = [
|
|
f.type,
|
|
f.file ?? f.package ?? f.name ?? f.migration ?? f.branch ?? '',
|
|
f.line ?? f.ref ?? '',
|
|
f.patternId ?? '',
|
|
].join(':');
|
|
if (seen.has(key)) return false;
|
|
seen.add(key);
|
|
return true;
|
|
});
|
|
|
|
const output = {
|
|
scanDate: new Date().toISOString(),
|
|
thresholds: { STALE_BRANCH_DAYS, STALE_COMMENT_DAYS },
|
|
repo: run('git remote get-url origin') || ROOT,
|
|
commit: run('git rev-parse --short HEAD') || 'unknown',
|
|
summary: {
|
|
total: deduped.length,
|
|
tierA: deduped.filter(f => f.tier === 'A').length,
|
|
tierB: deduped.filter(f => f.tier === 'B').length,
|
|
},
|
|
findings: deduped,
|
|
};
|
|
|
|
writeFileSync(OUT, JSON.stringify(output, null, 2));
|
|
console.log('');
|
|
console.log(`Total: ${deduped.length} (Tier A: ${output.summary.tierA}, Tier B: ${output.summary.tierB})`);
|
|
console.log(`Output: ${OUT}`);
|