Merge pull request #35 from wai-coding/dev

feat: richer analysis rules and export polish

Author: wai-coding

README.md

@@ -24,10 +24,14 @@ Manual code review is time-consuming and inconsistent. InspectoRepo provides det
 | Rule | Severity | Description |
 |------|----------|-------------|
 | `unused-imports` | warn | Detects unused import specifiers (default, namespace, named) and suggests removal with a safe proposed patch |
-| `complexity-hotspot` | warn | Flags functions with high cyclomatic-like complexity (≥ 12) and suggests refactoring strategies |
+| `complexity-hotspot` | warn | Flags functions with high cyclomatic-like complexity (≥ 12) with specific contributor breakdown (nested conditionals, loops, ternaries, logical chains) and tailored suggestions |
 | `optional-chaining` | info | Detects monotonic guard chains like `a && a.b && a.b.c` and suggests optional chaining (`a?.b?.c`) |
 | `boolean-simplification` | info | Simplifies `x === true`, `x === false`, `!!x`, and `x ? true : false` patterns |
 | `early-return` | info | Detects unnecessary block-style early returns and suggests single-line guard clauses |
+| `no-debugger` | warn | Detects `debugger` statements left in code — auto-fixable |
+| `no-empty-catch` | warn | Flags empty catch blocks that silently hide errors — report only |
+| `no-useless-return` | info | Detects redundant `return;` at the end of functions — auto-fixable |
+| `ts-diagnostics` | error | Reports high-confidence TypeScript compiler diagnostics (unreachable code, duplicate identifiers, missing names, type mismatches) — report only |
 
 ## Tech Stack
 
@@ -88,6 +92,8 @@ npm test
 | `npm test`            | Run Vitest tests             |
 | `npm run repopack`   | Generate repomix exports     |
 
+> **Export packs:** `npm run repopack` generates four versioned files under `ai/exports/`. Use `repo-pack-latest-vN.md` for a quick lightweight review — it includes project structure and core source without docs, screenshots, or scripts.
+
 ## Demo
 
 Try InspectoRepo locally in three steps:
@@ -140,7 +146,7 @@ Apply safe code fixes interactively:
 inspectorepo fix ./my-project
 ```
 
-The fix command runs analysis, finds issues with safe auto-fix suggestions, shows a preview of each proposed change, and asks for confirmation before applying. Only `optional-chaining`, `boolean-simplification`, and `unused-imports` rules support auto-fix. `complexity-hotspot` is never auto-applied.
+The fix command runs analysis, finds issues with safe auto-fix suggestions, shows a preview of each proposed change, and asks for confirmation before applying. Rules with auto-fix support: `optional-chaining`, `boolean-simplification`, `unused-imports`, `early-return`, `no-debugger`, and `no-useless-return`. Advisory rules like `complexity-hotspot`, `no-empty-catch`, and `ts-diagnostics` are never auto-applied.
 
 ### Fix Preview Mode
 
@@ -196,13 +202,17 @@ The CLI uses the same analysis engine as the web UI. Output is deterministic —
 
 ## Rules
 
-| Rule | Severity | Description |
-|------|----------|-------------|
-| `unused-imports` | warn | Detects unused import specifiers and suggests removal |
-| `complexity-hotspot` | warn | Flags high-complexity functions (≥ 12) with refactor suggestions |
-| `optional-chaining` | info | Suggests `?.` for monotonic guard chains |
-| `boolean-simplification` | info | Simplifies redundant boolean expressions |
-| `early-return` | info | Detects unnecessary block-style early returns |
+| Rule | Severity | Auto-fix | Description |
+|------|----------|----------|-------------|
+| `unused-imports` | warn | ✅ | Detects unused import specifiers and suggests removal |
+| `complexity-hotspot` | warn | ❌ | Flags high-complexity functions with specific contributor breakdown and tailored suggestions |
+| `optional-chaining` | info | ✅ | Suggests `?.` for monotonic guard chains |
+| `boolean-simplification` | info | ✅ | Simplifies redundant boolean expressions |
+| `early-return` | info | ✅ | Detects unnecessary block-style early returns |
+| `no-debugger` | warn | ✅ | Detects `debugger` statements left in code |
+| `no-empty-catch` | warn | ❌ | Flags empty catch blocks that silently hide errors |
+| `no-useless-return` | info | ✅ | Detects redundant `return;` at the end of functions |
+| `ts-diagnostics` | error | ❌ | Reports high-confidence TypeScript compiler diagnostics |
 
 ## Configuration
 
@@ -215,7 +225,11 @@ Create `.inspectorepo.json` in your project root to configure which rules run an
     "unused-imports": "warn",
     "complexity-hotspot": "off",
     "boolean-simplification": "warn",
-    "early-return": "warn"
+    "early-return": "warn",
+    "no-debugger": "warn",
+    "no-empty-catch": "warn",
+    "no-useless-return": "warn",
+    "ts-diagnostics": "off"
   }
 }
 ```

ai/scripts/generate-repomix-exports.ts

@@ -207,9 +207,11 @@ const BANNED_BULLET_PATTERNS: RegExp[] = [
   /\bpatterns?\s+match/i,
   /\.ts[x]?[:\s]/i,
   /Checks? passed/i,
-  // Milestone-title-style bullets (e.g. "M19 Web UI improvements")
+  // Milestone-title-style bullets (e.g. "M19 Web UI improvements", "V3 Platform Milestone")
   /^M\d+\b/i,
   /\bM\d+\b.*\bM\d+\b/i,
+  /^V\d+\s/i,
+  /\bMilestone\b/i,
 ];
 
 function isBannedBullet(bullet: string): boolean {
@@ -521,15 +523,13 @@ const ROADMAP: RoadmapItem[] = [
   { label: 'Summary-only CLI mode for fast CI checks', implemented: true },
   { label: 'Lightweight repo-pack-latest export mode', implemented: true },
   { label: 'Web app onboarding About section and empty state', implemented: true },
+  { label: 'Richer complexity warnings with contributor breakdown', implemented: true },
+  { label: 'Conservative analysis rules (no-debugger, no-empty-catch, no-useless-return, ts-diagnostics)', implemented: true },
   { label: 'Deploy web app as a hosted service', implemented: false },
   { label: 'Rule dependency graph and cascade analysis', implemented: false },
   { label: 'Performance profiling for large codebases', implemented: false },
   { label: 'VS Code extension inline fix suggestions', implemented: false },
 ];
-  { label: 'Rule dependency graph and cascade analysis', implemented: false },
-  { label: 'Performance profiling for large codebases', implemented: false },
-  { label: 'VS Code extension inline fix suggestions', implemented: false },
-];
 
 function generateNextMilestoneSection(): string {
   const future = ROADMAP.filter(r => !r.implemented).map(r => r.label);
@@ -674,8 +674,8 @@ ${formatGroupedFiles(milestoneFiles)}
 \`\`\`
 
 ## Known Limitations
-- Auto-fix supports 4 rules (optional-chaining, boolean-simplification, unused-imports, early-return) — more planned
-- Complexity-hotspot is advisory only — no auto-fix support
+- Auto-fix supports 6 rules (optional-chaining, boolean-simplification, unused-imports, early-return, no-debugger, no-useless-return) — more planned
+- Complexity-hotspot, no-empty-catch, and ts-diagnostics are advisory only — no auto-fix support
 - Browser folder picker requires Chrome/Edge (File System Access API)
 
 ## Next Milestone
@@ -690,6 +690,7 @@ npm run repopack
 This scans \`ai/exports/\` for existing versioned files, increments the version, runs repomix, and writes:
 - \`ai/exports/repo-pack-full-vN.md\` — full repository pack
 - \`ai/exports/repo-pack-core-vN.md\` — core-only pack (no docs/screenshots/.github)
+- \`ai/exports/repo-pack-latest-vN.md\` — lightweight pack for quick review (no docs/screenshots/.github/scripts)
 - \`ai/exports/changes-summary-vN.md\` — this file
 `;
 

apps/web/src/components/MainPanel.tsx

@@ -158,6 +158,12 @@ export function MainPanel({ report, selectedIssue, onSelectIssue }: MainPanelPro
                       {issue.suggestion.summary}
                     </div>
                   )}
+                  {issue.suggestion.details && (
+                    <div className="issue-expanded-suggestion">
+                      <span className="issue-expanded-suggestion-label">Details:</span>{' '}
+                      {issue.suggestion.details}
+                    </div>
+                  )}
                 </div>
               )}
             </div>

docs/agent-worklog.md

@@ -4,6 +4,42 @@ Development log for InspectoRepo. Each entry describes what was implemented, why
 
 ---
 
+## 2026-03-11 — Richer Analysis Rules and Export Polish
+
+### What was implemented
+
+- **Enriched complexity-hotspot warnings** — each complexity issue now includes function name, complexity score, contributor breakdown (if statements, loops, ternaries, logical chains, switch cases, nesting depth), and specific tailored suggestions instead of generic messages.
+- **New rule: `no-debugger`** — detects `debugger` statements left in code. Auto-fixable by removing the statement.
+- **New rule: `no-empty-catch`** — flags empty catch blocks that silently swallow errors. Report-only (no auto-fix).
+- **New rule: `no-useless-return`** — detects redundant `return;` at the end of function bodies. Auto-fixable.
+- **New rule: `ts-diagnostics`** — reports high-confidence TypeScript compiler diagnostics (unreachable code, duplicate identifiers, missing names, type mismatches). Report-only.
+- **Extended auto-fix support** — `no-debugger` and `no-useless-return` now supported in the fix engine (preview + apply modes).
+- **Export workflow polish** — human summary generation now bans milestone-title bullets and raw commit prefixes more strictly. Regenerate section lists all 4 export files. repo-pack-latest documented as the preferred lightweight pack.
+- **Web UI details panel** — expanded issue view now shows both suggestion summary and details for richer context (e.g. complexity contributors).
+- **Preset updates** — all four presets (`recommended`, `strict`, `cleanup`, `react`) updated to include the new rules with conservative defaults.
+
+### Why
+
+The previous complexity warnings were too generic — every function got the same message regardless of what was actually making it complex. The new rules (`no-debugger`, `no-empty-catch`, `no-useless-return`, `ts-diagnostics`) are all syntax-exact or diagnostics-backed, making them highly reliable with zero false positives for their defined scope.
+
+### How to verify
+
+```bash
+npm run lint
+npm run typecheck
+npm run build
+npm test
+```
+
+### Design decisions
+
+- **Complexity breakdown is tracked per-function** — a `ComplexityBreakdown` struct accumulates counts for each contributor type during the recursive walk. This makes the output deterministic and the rule predictable.
+- **New rules are conservative** — `no-debugger` and `no-empty-catch` are exact syntax matches with no ambiguity. `no-useless-return` only flags bare `return;` as the last statement. `ts-diagnostics` uses a curated subset of TS error codes.
+- **Auto-fix only for safe removals** — `no-debugger` (remove statement) and `no-useless-return` (remove redundant return) are trivially safe. `no-empty-catch` and `ts-diagnostics` are never auto-fixed.
+- **ts-diagnostics off by default** — in `recommended` and `cleanup` presets, because in-memory ts-morph projects may not resolve all external types. Enabled in `strict` preset.
+
+---
+
 ## 2026-03-11 — V3 Platform Milestone
 
 ### What was implemented

docs/code-walkthrough.md

@@ -246,7 +246,25 @@ Skips side-effect imports (`import './polyfill'`).
 
 ### `src/rules/complexity-hotspot.ts`
 
-Counts control-flow complexity per function: if/else, switch cases, ternaries, logical operators, loops, try/catch, plus nesting depth bonus. Flags functions scoring ≥ 12.
+Counts control-flow complexity per function: if/else, switch cases, ternaries, logical operators, loops, try/catch, plus nesting depth bonus. Each function gets a `ComplexityBreakdown` struct tracking counts for each contributor type (ifStatements, loops, ternaries, logicalChains, switchCases, catchClauses, maxNestingDepth). Flags functions scoring ≥ 12.
+
+Messages are specific: `Function "renderDashboard" has high complexity (22) driven by nested conditionals and ternaries.` Details include contributor counts (e.g. "4 if statements, 3 ternaries, nesting depth 3"). Suggestions are tailored to what was actually found (e.g. "replace nested conditionals with early returns" when if-statements dominate).
+
+### `src/rules/no-debugger.ts`
+
+Detects `debugger` statements via `SyntaxKind.DebuggerStatement`. Auto-fixable by removing the statement line. Severity: warn.
+
+### `src/rules/no-empty-catch.ts`
+
+Detects catch blocks with no statements inside via `SyntaxKind.CatchClause` → `getBlock().getStatements().length === 0`. Report-only (no auto-fix). Severity: warn.
+
+### `src/rules/no-useless-return.ts`
+
+Detects bare `return;` as the final statement of a function body. Only flags when the return text is exactly `"return;"` — does not flag returns with values. Auto-fixable by removing the redundant line. Severity: info.
+
+### `src/rules/ts-diagnostics.ts`
+
+Reports selected high-confidence TypeScript diagnostics from the analyzed file using `sourceFile.getPreEmitDiagnostics()`. Only maps a conservative subset of diagnostic codes: TS7027 (unreachable code), TS2300 (duplicate identifier), TS2304 (cannot find name), TS2339 (property does not exist), TS2554 (argument count mismatch), TS2322 (type assignment mismatch). Off by default in recommended/cleanup presets; enabled in strict preset.
 
 ### `src/rules/optional-chaining.ts`
 
@@ -284,7 +302,7 @@ Rule preset system:
 - `isValidPreset(name)` — type guard checking if a string is a valid `PresetName`
 - `getPresetNames()` — returns the list of available preset names
 
-Presets: `recommended` (all warn), `strict` (unused-imports + complexity at error), `cleanup` (complexity off, style rules on), `react` (unused-imports at error for TS+React projects).
+Presets: `recommended` (all warn, ts-diagnostics off), `strict` (unused-imports + complexity + no-debugger + no-empty-catch at error, ts-diagnostics on), `cleanup` (complexity off, ts-diagnostics off, style/cleanup rules on), `react` (unused-imports at error for TS+React projects, ts-diagnostics off).
 
 ### `src/config.ts`
 

packages/cli/src/fixer.test.ts

@@ -47,6 +47,21 @@ describe('isAutoFixable', () => {
     expect(isAutoFixable(issue)).toBe(false);
   });
 
+  it('returns true for no-debugger with diff', () => {
+    const issue = makeIssue('no-debugger', '- debugger;');
+    expect(isAutoFixable(issue)).toBe(true);
+  });
+
+  it('returns true for no-useless-return with diff', () => {
+    const issue = makeIssue('no-useless-return', '- return;');
+    expect(isAutoFixable(issue)).toBe(true);
+  });
+
+  it('returns false for no-empty-catch (no auto-fix)', () => {
+    const issue = makeIssue('no-empty-catch');
+    expect(isAutoFixable(issue)).toBe(false);
+  });
+
   it('returns false when no diff is provided', () => {
     const issue = makeIssue('optional-chaining');
     expect(isAutoFixable(issue)).toBe(false);

packages/cli/src/fixer.ts

@@ -8,6 +8,8 @@ const SAFE_RULE_IDS = new Set([
   'boolean-simplification',
   'unused-imports',
   'early-return',
+  'no-debugger',
+  'no-useless-return',
 ]);
 
 export function isAutoFixable(issue: Issue): boolean {

packages/core/src/analyzer.test.ts

@@ -218,7 +218,7 @@ describe('unused-imports rule', () => {
 });
 
 describe('complexity-hotspot rule', () => {
-  it('flags functions above threshold', () => {
+  it('flags functions above threshold with function name and score', () => {
     // Build a function with many branches to exceed threshold of 12
     const code = [
       'export function complex(a: number, b: number, c: boolean) {',
@@ -252,8 +252,52 @@ describe('complexity-hotspot rule', () => {
       options: { rules: [complexityHotspotRule] },
     });
     expect(report.issues.length).toBe(1);
-    expect(report.issues[0].ruleId).toBe('complexity-hotspot');
-    expect(report.issues[0].severity).toBe('warn');
+    const issue = report.issues[0];
+    expect(issue.ruleId).toBe('complexity-hotspot');
+    expect(issue.severity).toBe('warn');
+    // Function name and score must appear in message
+    expect(issue.message).toContain('"complex"');
+    expect(issue.message).toMatch(/\(\d+\)/);
+    // Contributors must appear in details
+    expect(issue.suggestion.details).toMatch(/if statement/);
+    expect(issue.suggestion.details).toMatch(/Complexity score: \d+/);
+    // Suggestion should be specific, not generic
+    expect(issue.suggestion.summary).toMatch(/Consider:/);
+  });
+
+  it('includes contributor counts in details', () => {
+    const code = [
+      'export function branchy(x: number) {',
+      '  if (x > 0) {',
+      '    if (x > 1) {',
+      '      if (x > 2) {',
+      '        for (let i = 0; i < x; i++) {',
+      '          while (i > 0) {',
+      '            if (i % 2 === 0) {',
+      '              console.log(i);',
+      '            }',
+      '          }',
+      '        }',
+      '      }',
+      '    }',
+      '  }',
+      '  const a = x > 0 ? 1 : 0;',
+      '  const b = x > 1 ? 1 : 0;',
+      '  return a || b;',
+      '}',
+    ].join('\n');
+
+    const files = [{ path: 'src/test.ts', content: code }];
+    const report = analyzeCodebase({
+      files,
+      selectedDirectories: ['src'],
+      options: { rules: [complexityHotspotRule] },
+    });
+    expect(report.issues.length).toBe(1);
+    const details = report.issues[0].suggestion.details;
+    expect(details).toContain('if statement');
+    expect(details).toContain('loop');
+    expect(details).toContain('ternary');
   });
 
   it('does not flag simple functions', () => {

packages/core/src/index.ts

@@ -9,6 +9,10 @@ export {
   optionalChainingRule,
   booleanSimplificationRule,
   earlyReturnRule,
+  noDebuggerRule,
+  noEmptyCatchRule,
+  noUselessReturnRule,
+  tsDiagnosticsRule,
 } from './rules/index.js';
 export {
   isExcludedDir,

packages/core/src/presets.ts

@@ -9,27 +9,43 @@ const PRESETS: Record<PresetName, RuleConfig> = {
     'optional-chaining': 'warn',
     'boolean-simplification': 'warn',
     'early-return': 'warn',
+    'no-debugger': 'warn',
+    'no-empty-catch': 'warn',
+    'no-useless-return': 'warn',
+    'ts-diagnostics': 'off',
   },
   strict: {
     'unused-imports': 'error',
     'complexity-hotspot': 'error',
     'optional-chaining': 'warn',
     'boolean-simplification': 'warn',
     'early-return': 'warn',
+    'no-debugger': 'error',
+    'no-empty-catch': 'error',
+    'no-useless-return': 'warn',
+    'ts-diagnostics': 'error',
   },
   cleanup: {
     'unused-imports': 'warn',
     'complexity-hotspot': 'off',
     'optional-chaining': 'warn',
     'boolean-simplification': 'warn',
     'early-return': 'warn',
+    'no-debugger': 'warn',
+    'no-empty-catch': 'warn',
+    'no-useless-return': 'warn',
+    'ts-diagnostics': 'off',
   },
   react: {
     'unused-imports': 'error',
     'complexity-hotspot': 'warn',
     'optional-chaining': 'warn',
     'boolean-simplification': 'warn',
     'early-return': 'warn',
+    'no-debugger': 'warn',
+    'no-empty-catch': 'warn',
+    'no-useless-return': 'warn',
+    'ts-diagnostics': 'off',
   },
 };