@aiready/hygiene-audit 0.6.0

package/.turbo/turbo-build.log

@@ -0,0 +1,19 @@
+
+
+> @aiready/hygiene-audit@0.6.0 build /Users/pengcao/projects/aiready/packages/hygiene-audit
+> tsup src/index.ts src/cli.ts --format cjs,esm --dts
+
+CLI Building entry: src/index.ts
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.1
+CLI Target: es2020
+CJS Build start
+ESM Build start
+ESM dist/index.mjs 6.58 KB
+ESM ⚡️ Build success in 59ms
+CJS dist/index.js 8.35 KB
+CJS ⚡️ Build success in 60ms
+DTS Build start
+DTS ⚡️ Build success in 691ms
+DTS dist/index.d.ts  429.00 B
+DTS dist/index.d.mts 429.00 B

package/.turbo/turbo-test.log

@@ -0,0 +1,33 @@
+
+
+> @aiready/hygiene-audit@0.6.0 test /Users/pengcao/projects/aiready/packages/hygiene-audit
+> vitest run
+
+[?25l
+ RUN  v4.1.4 /Users/pengcao/projects/aiready/packages/hygiene-audit
+
+[?2026h
+ ❯ src/__tests__/hygiene.test.ts [queued]
+
+ Test Files 0 passed (1)
+      Tests 0 passed (0)
+   Start at 09:12:55
+   Duration 101ms
+[?2026l[?2026h
+ ❯ src/__tests__/hygiene.test.ts 0/2
+
+ Test Files 0 passed (1)
+      Tests 0 passed (2)
+   Start at 09:12:55
+   Duration 525ms
+[?2026l ✓ src/__tests__/hygiene.test.ts (2 tests) 2ms
+   ✓ HygieneAuditProvider (2)
+     ✓ should be registered in ToolRegistry 1ms
+     ✓ should have correct aliases 0ms
+
+ Test Files  1 passed (1)
+      Tests  2 passed (2)
+   Start at  09:12:55
+   Duration  536ms (transform 125ms, setup 0ms, import 394ms, tests 2ms, environment 0ms)
+
+[?25h

package/dist/index.d.mts

@@ -0,0 +1,11 @@
+import { ToolProvider, ToolName, ScanOptions, SpokeOutput, ToolScoringOutput } from '@aiready/core';
+
+declare class HygieneAuditProvider implements ToolProvider {
+    readonly id = ToolName.HygieneAudit;
+    readonly alias: string[];
+    analyze(options: ScanOptions): Promise<SpokeOutput>;
+    score(output: SpokeOutput, _options: ScanOptions): ToolScoringOutput;
+    private calculateScore;
+}
+
+export { HygieneAuditProvider };

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { ToolProvider, ToolName, ScanOptions, SpokeOutput, ToolScoringOutput } from '@aiready/core';
+
+declare class HygieneAuditProvider implements ToolProvider {
+    readonly id = ToolName.HygieneAudit;
+    readonly alias: string[];
+    analyze(options: ScanOptions): Promise<SpokeOutput>;
+    score(output: SpokeOutput, _options: ScanOptions): ToolScoringOutput;
+    private calculateScore;
+}
+
+export { HygieneAuditProvider };

package/dist/index.js

@@ -0,0 +1,241 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  HygieneAuditProvider: () => HygieneAuditProvider
+});
+module.exports = __toCommonJS(index_exports);
+var import_core = require("@aiready/core");
+var import_child_process = require("child_process");
+var import_util = require("util");
+var import_ripgrep = require("@vscode/ripgrep");
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var execFileAsync = (0, import_util.promisify)(import_child_process.execFile);
+var HygieneAuditProvider = class {
+  constructor() {
+    this.id = import_core.ToolName.HygieneAudit;
+    this.alias = ["hygiene", "codebase-hygiene", "metabolism"];
+  }
+  async analyze(options) {
+    const { rootDir } = options;
+    const rawIssues = [];
+    let filesAnalyzed = 0;
+    let debtMarkers = 0;
+    try {
+      const { stdout } = await execFileAsync(import_ripgrep.rgPath, [
+        "--count-matches",
+        "--fixed-strings",
+        "-e",
+        "TODO",
+        "-e",
+        "FIXME",
+        "--glob",
+        "!**/node_modules/**",
+        "--glob",
+        "!**/.git/**",
+        "--glob",
+        "!**/dist/**",
+        rootDir
+      ]);
+      const lines = stdout.split("\n").filter(Boolean);
+      for (const line of lines) {
+        const parts = line.split(":");
+        const count = parseInt(parts[parts.length - 1], 10);
+        if (!isNaN(count)) {
+          debtMarkers += count;
+          filesAnalyzed++;
+        }
+      }
+    } catch (error) {
+      if (error.code !== 1)
+        console.error("[Hygiene] Error counting markers:", error);
+    }
+    if (debtMarkers > 0) {
+      rawIssues.push({
+        type: import_core.IssueType.ArchitectureInconsistency,
+        severity: debtMarkers > 20 ? import_core.Severity.Major : import_core.Severity.Minor,
+        location: { file: "codebase", line: 0 },
+        message: `Codebase Hygiene: Found ${debtMarkers} TODO/FIXME markers.`,
+        recommendation: "Address or resolve old TODO markers to maintain codebase health."
+      });
+    }
+    const emptyDirs = [];
+    const scanEmpty = (dir) => {
+      if (!fs.existsSync(dir)) return;
+      const files = fs.readdirSync(dir);
+      if (files.length === 0) {
+        emptyDirs.push(path.relative(rootDir, dir));
+        return;
+      }
+      for (const file of files) {
+        const fullPath = path.join(dir, file);
+        if (fs.statSync(fullPath).isDirectory()) {
+          if ([
+            "node_modules",
+            ".git",
+            "dist",
+            ".sst",
+            ".turbo",
+            ".next"
+          ].includes(file))
+            continue;
+          scanEmpty(fullPath);
+        }
+      }
+    };
+    if (fs.existsSync(rootDir)) scanEmpty(rootDir);
+    if (emptyDirs.length > 0) {
+      rawIssues.push({
+        type: import_core.IssueType.DeadCode,
+        severity: import_core.Severity.Minor,
+        location: { file: "structure", line: 0 },
+        message: `Empty directories: Found ${emptyDirs.length} empty folders.`,
+        recommendation: `Prune empty directories to keep project structure clean: ${emptyDirs.slice(0, 3).join(", ")}`
+      });
+    }
+    const orphanedFiles = [];
+    const allFiles = [];
+    const collectFiles = (dir) => {
+      if (!fs.existsSync(dir)) return;
+      const files = fs.readdirSync(dir);
+      for (const file of files) {
+        const fullPath = path.join(dir, file);
+        if (fs.statSync(fullPath).isDirectory()) {
+          if ([
+            "node_modules",
+            ".git",
+            "dist",
+            ".sst",
+            ".turbo",
+            ".next"
+          ].includes(file))
+            continue;
+          collectFiles(fullPath);
+        } else if (file.endsWith(".ts") || file.endsWith(".js") || file.endsWith(".tsx") || file.endsWith(".jsx")) {
+          allFiles.push(fullPath);
+        }
+      }
+    };
+    if (fs.existsSync(rootDir)) collectFiles(rootDir);
+    for (const file of allFiles) {
+      const base = path.basename(file, path.extname(file));
+      if (base === "index" || base.endsWith(".test") || base.endsWith(".spec"))
+        continue;
+      let referenced = false;
+      try {
+        const { status } = await execFileAsync(import_ripgrep.rgPath, [
+          "--quiet",
+          "--fixed-strings",
+          "--word-regexp",
+          "--glob",
+          `!${path.relative(rootDir, file)}`,
+          "--glob",
+          "!**/node_modules/**",
+          base,
+          rootDir
+        ]);
+        if (status === 0) referenced = true;
+      } catch (e) {
+        if (e.code === 0) referenced = true;
+      }
+      if (!referenced) orphanedFiles.push(path.relative(rootDir, file));
+    }
+    if (orphanedFiles.length > 0) {
+      rawIssues.push({
+        type: import_core.IssueType.DeadCode,
+        severity: import_core.Severity.Major,
+        location: { file: "codebase", line: 0 },
+        message: `Orphaned files: Found ${orphanedFiles.length} potentially unused files.`,
+        recommendation: `Audit and remove orphaned files to reduce cognitive load: ${orphanedFiles.slice(0, 3).join(", ")}`
+      });
+    }
+    const results = (0, import_core.groupIssuesByFile)(rawIssues);
+    const score = this.calculateScore(
+      debtMarkers,
+      emptyDirs.length,
+      orphanedFiles.length
+    );
+    const summary = {
+      score,
+      criticalIssues: rawIssues.filter((i) => i.severity === import_core.Severity.Critical).length,
+      majorIssues: rawIssues.filter((i) => i.severity === import_core.Severity.Major).length,
+      minorIssues: rawIssues.filter((i) => i.severity === import_core.Severity.Minor).length,
+      totalIssues: rawIssues.length,
+      totalFiles: filesAnalyzed,
+      recommendations: rawIssues.map((i) => i.recommendation)
+    };
+    return (0, import_core.buildSpokeOutput)(this.id, "0.1.0", summary, results, {
+      debtMarkers,
+      emptyDirs,
+      orphanedFiles
+    });
+  }
+  score(output, _options) {
+    const score = typeof output.summary.score === "number" ? output.summary.score : 0;
+    const debtCount = output.metadata?.debtMarkers || 0;
+    const orphanCount = (output.metadata?.orphanedFiles || []).length;
+    return {
+      toolName: this.id,
+      score,
+      rawMetrics: output.metadata,
+      factors: [
+        {
+          name: "Technical Debt",
+          impact: debtCount > 0 ? -Math.min(20, debtCount) : 5,
+          description: `Found ${debtCount} TODO/FIXME markers.`
+        },
+        {
+          name: "File Orphans",
+          impact: orphanCount > 0 ? -Math.min(30, orphanCount * 5) : 10,
+          description: `Found ${orphanCount} potentially unused files.`
+        }
+      ],
+      recommendations: output.summary.recommendations.map((action) => ({
+        action,
+        estimatedImpact: 5,
+        priority: import_core.RecommendationPriority.Medium
+      }))
+    };
+  }
+  calculateScore(debt, empty, orphans) {
+    let score = 100;
+    score -= debt * 1;
+    score -= empty * 2;
+    score -= orphans * 5;
+    return Math.max(0, Math.min(100, score));
+  }
+};
+import_core.ToolRegistry.register(new HygieneAuditProvider());
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HygieneAuditProvider
+});

package/dist/index.mjs

@@ -0,0 +1,214 @@
+// src/index.ts
+import {
+  ToolRegistry,
+  ToolName,
+  Severity,
+  IssueType,
+  RecommendationPriority,
+  buildSpokeOutput,
+  groupIssuesByFile
+} from "@aiready/core";
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { rgPath } from "@vscode/ripgrep";
+import * as fs from "fs";
+import * as path from "path";
+var execFileAsync = promisify(execFile);
+var HygieneAuditProvider = class {
+  constructor() {
+    this.id = ToolName.HygieneAudit;
+    this.alias = ["hygiene", "codebase-hygiene", "metabolism"];
+  }
+  async analyze(options) {
+    const { rootDir } = options;
+    const rawIssues = [];
+    let filesAnalyzed = 0;
+    let debtMarkers = 0;
+    try {
+      const { stdout } = await execFileAsync(rgPath, [
+        "--count-matches",
+        "--fixed-strings",
+        "-e",
+        "TODO",
+        "-e",
+        "FIXME",
+        "--glob",
+        "!**/node_modules/**",
+        "--glob",
+        "!**/.git/**",
+        "--glob",
+        "!**/dist/**",
+        rootDir
+      ]);
+      const lines = stdout.split("\n").filter(Boolean);
+      for (const line of lines) {
+        const parts = line.split(":");
+        const count = parseInt(parts[parts.length - 1], 10);
+        if (!isNaN(count)) {
+          debtMarkers += count;
+          filesAnalyzed++;
+        }
+      }
+    } catch (error) {
+      if (error.code !== 1)
+        console.error("[Hygiene] Error counting markers:", error);
+    }
+    if (debtMarkers > 0) {
+      rawIssues.push({
+        type: IssueType.ArchitectureInconsistency,
+        severity: debtMarkers > 20 ? Severity.Major : Severity.Minor,
+        location: { file: "codebase", line: 0 },
+        message: `Codebase Hygiene: Found ${debtMarkers} TODO/FIXME markers.`,
+        recommendation: "Address or resolve old TODO markers to maintain codebase health."
+      });
+    }
+    const emptyDirs = [];
+    const scanEmpty = (dir) => {
+      if (!fs.existsSync(dir)) return;
+      const files = fs.readdirSync(dir);
+      if (files.length === 0) {
+        emptyDirs.push(path.relative(rootDir, dir));
+        return;
+      }
+      for (const file of files) {
+        const fullPath = path.join(dir, file);
+        if (fs.statSync(fullPath).isDirectory()) {
+          if ([
+            "node_modules",
+            ".git",
+            "dist",
+            ".sst",
+            ".turbo",
+            ".next"
+          ].includes(file))
+            continue;
+          scanEmpty(fullPath);
+        }
+      }
+    };
+    if (fs.existsSync(rootDir)) scanEmpty(rootDir);
+    if (emptyDirs.length > 0) {
+      rawIssues.push({
+        type: IssueType.DeadCode,
+        severity: Severity.Minor,
+        location: { file: "structure", line: 0 },
+        message: `Empty directories: Found ${emptyDirs.length} empty folders.`,
+        recommendation: `Prune empty directories to keep project structure clean: ${emptyDirs.slice(0, 3).join(", ")}`
+      });
+    }
+    const orphanedFiles = [];
+    const allFiles = [];
+    const collectFiles = (dir) => {
+      if (!fs.existsSync(dir)) return;
+      const files = fs.readdirSync(dir);
+      for (const file of files) {
+        const fullPath = path.join(dir, file);
+        if (fs.statSync(fullPath).isDirectory()) {
+          if ([
+            "node_modules",
+            ".git",
+            "dist",
+            ".sst",
+            ".turbo",
+            ".next"
+          ].includes(file))
+            continue;
+          collectFiles(fullPath);
+        } else if (file.endsWith(".ts") || file.endsWith(".js") || file.endsWith(".tsx") || file.endsWith(".jsx")) {
+          allFiles.push(fullPath);
+        }
+      }
+    };
+    if (fs.existsSync(rootDir)) collectFiles(rootDir);
+    for (const file of allFiles) {
+      const base = path.basename(file, path.extname(file));
+      if (base === "index" || base.endsWith(".test") || base.endsWith(".spec"))
+        continue;
+      let referenced = false;
+      try {
+        const { status } = await execFileAsync(rgPath, [
+          "--quiet",
+          "--fixed-strings",
+          "--word-regexp",
+          "--glob",
+          `!${path.relative(rootDir, file)}`,
+          "--glob",
+          "!**/node_modules/**",
+          base,
+          rootDir
+        ]);
+        if (status === 0) referenced = true;
+      } catch (e) {
+        if (e.code === 0) referenced = true;
+      }
+      if (!referenced) orphanedFiles.push(path.relative(rootDir, file));
+    }
+    if (orphanedFiles.length > 0) {
+      rawIssues.push({
+        type: IssueType.DeadCode,
+        severity: Severity.Major,
+        location: { file: "codebase", line: 0 },
+        message: `Orphaned files: Found ${orphanedFiles.length} potentially unused files.`,
+        recommendation: `Audit and remove orphaned files to reduce cognitive load: ${orphanedFiles.slice(0, 3).join(", ")}`
+      });
+    }
+    const results = groupIssuesByFile(rawIssues);
+    const score = this.calculateScore(
+      debtMarkers,
+      emptyDirs.length,
+      orphanedFiles.length
+    );
+    const summary = {
+      score,
+      criticalIssues: rawIssues.filter((i) => i.severity === Severity.Critical).length,
+      majorIssues: rawIssues.filter((i) => i.severity === Severity.Major).length,
+      minorIssues: rawIssues.filter((i) => i.severity === Severity.Minor).length,
+      totalIssues: rawIssues.length,
+      totalFiles: filesAnalyzed,
+      recommendations: rawIssues.map((i) => i.recommendation)
+    };
+    return buildSpokeOutput(this.id, "0.1.0", summary, results, {
+      debtMarkers,
+      emptyDirs,
+      orphanedFiles
+    });
+  }
+  score(output, _options) {
+    const score = typeof output.summary.score === "number" ? output.summary.score : 0;
+    const debtCount = output.metadata?.debtMarkers || 0;
+    const orphanCount = (output.metadata?.orphanedFiles || []).length;
+    return {
+      toolName: this.id,
+      score,
+      rawMetrics: output.metadata,
+      factors: [
+        {
+          name: "Technical Debt",
+          impact: debtCount > 0 ? -Math.min(20, debtCount) : 5,
+          description: `Found ${debtCount} TODO/FIXME markers.`
+        },
+        {
+          name: "File Orphans",
+          impact: orphanCount > 0 ? -Math.min(30, orphanCount * 5) : 10,
+          description: `Found ${orphanCount} potentially unused files.`
+        }
+      ],
+      recommendations: output.summary.recommendations.map((action) => ({
+        action,
+        estimatedImpact: 5,
+        priority: RecommendationPriority.Medium
+      }))
+    };
+  }
+  calculateScore(debt, empty, orphans) {
+    let score = 100;
+    score -= debt * 1;
+    score -= empty * 2;
+    score -= orphans * 5;
+    return Math.max(0, Math.min(100, score));
+  }
+};
+ToolRegistry.register(new HygieneAuditProvider());
+export {
+  HygieneAuditProvider
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@aiready/hygiene-audit",
+  "version": "0.6.0",
+  "description": "Codebase-level metabolic health and technical debt audit for AI-readiness",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "aiready-hygiene": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "keywords": [
+    "aiready",
+    "tech-debt",
+    "code-health",
+    "metabolism",
+    "ai-code",
+    "refactoring"
+  ],
+  "author": "AIReady Team",
+  "license": "MIT",
+  "dependencies": {
+    "@vscode/ripgrep": "^1.15.9",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "@aiready/core": "0.28.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.2",
+    "eslint": "^10.2.0",
+    "tsup": "^8.5.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts src/cli.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "type-check": "tsc --noEmit",
+    "format-check": "prettier --check . --ignore-path ../../.prettierignore"
+  }
+}

package/src/__tests__/hygiene.test.ts

@@ -0,0 +1,17 @@
+import { describe, it, expect } from 'vitest';
+import { ToolRegistry, ToolName } from '@aiready/core';
+import '../index';
+
+describe('HygieneAuditProvider', () => {
+  it('should be registered in ToolRegistry', () => {
+    const provider = ToolRegistry.get(ToolName.HygieneAudit);
+    expect(provider).toBeDefined();
+    expect(provider?.id).toBe(ToolName.HygieneAudit);
+  });
+
+  it('should have correct aliases', () => {
+    const provider = ToolRegistry.get(ToolName.HygieneAudit);
+    expect(provider?.alias).toContain('hygiene');
+    expect(provider?.alias).toContain('metabolism');
+  });
+});

package/src/index.ts

@@ -0,0 +1,251 @@
+import {
+  ToolProvider,
+  ToolRegistry,
+  ToolName,
+  Severity,
+  IssueType,
+  ScanOptions,
+  SpokeOutput,
+  ToolScoringOutput,
+  RecommendationPriority,
+  buildSpokeOutput,
+  groupIssuesByFile,
+} from '@aiready/core';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { rgPath } from '@vscode/ripgrep';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const execFileAsync = promisify(execFile);
+
+export class HygieneAuditProvider implements ToolProvider {
+  public readonly id = ToolName.HygieneAudit;
+  public readonly alias = ['hygiene', 'codebase-hygiene', 'metabolism'];
+
+  public async analyze(options: ScanOptions): Promise<SpokeOutput> {
+    const { rootDir } = options;
+    const rawIssues = [];
+    let filesAnalyzed = 0;
+
+    // 1. Count Debt Markers (TODO/FIXME)
+    let debtMarkers = 0;
+    try {
+      const { stdout } = await execFileAsync(rgPath, [
+        '--count-matches',
+        '--fixed-strings',
+        '-e',
+        'TODO',
+        '-e',
+        'FIXME',
+        '--glob',
+        '!**/node_modules/**',
+        '--glob',
+        '!**/.git/**',
+        '--glob',
+        '!**/dist/**',
+        rootDir,
+      ]);
+
+      const lines = stdout.split('\n').filter(Boolean);
+      for (const line of lines) {
+        const parts = line.split(':');
+        const count = parseInt(parts[parts.length - 1], 10);
+        if (!isNaN(count)) {
+          debtMarkers += count;
+          filesAnalyzed++;
+        }
+      }
+    } catch (error: any) {
+      if (error.code !== 1)
+        console.error('[Hygiene] Error counting markers:', error);
+    }
+
+    if (debtMarkers > 0) {
+      rawIssues.push({
+        type: IssueType.ArchitectureInconsistency,
+        severity: debtMarkers > 20 ? Severity.Major : Severity.Minor,
+        location: { file: 'codebase', line: 0 },
+        message: `Codebase Hygiene: Found ${debtMarkers} TODO/FIXME markers.`,
+        recommendation:
+          'Address or resolve old TODO markers to maintain codebase health.',
+      });
+    }
+
+    // 2. Identify Empty Directories (Structure waste)
+    const emptyDirs: string[] = [];
+    const scanEmpty = (dir: string) => {
+      if (!fs.existsSync(dir)) return;
+      const files = fs.readdirSync(dir);
+      if (files.length === 0) {
+        emptyDirs.push(path.relative(rootDir, dir));
+        return;
+      }
+      for (const file of files) {
+        const fullPath = path.join(dir, file);
+        if (fs.statSync(fullPath).isDirectory()) {
+          if (
+            [
+              'node_modules',
+              '.git',
+              'dist',
+              '.sst',
+              '.turbo',
+              '.next',
+            ].includes(file)
+          )
+            continue;
+          scanEmpty(fullPath);
+        }
+      }
+    };
+    if (fs.existsSync(rootDir)) scanEmpty(rootDir);
+
+    if (emptyDirs.length > 0) {
+      rawIssues.push({
+        type: IssueType.DeadCode,
+        severity: Severity.Minor,
+        location: { file: 'structure', line: 0 },
+        message: `Empty directories: Found ${emptyDirs.length} empty folders.`,
+        recommendation: `Prune empty directories to keep project structure clean: ${emptyDirs.slice(0, 3).join(', ')}`,
+      });
+    }
+
+    // 3. Orphaned Files (Redundant logic)
+    const orphanedFiles: string[] = [];
+    const allFiles: string[] = [];
+    const collectFiles = (dir: string) => {
+      if (!fs.existsSync(dir)) return;
+      const files = fs.readdirSync(dir);
+      for (const file of files) {
+        const fullPath = path.join(dir, file);
+        if (fs.statSync(fullPath).isDirectory()) {
+          if (
+            [
+              'node_modules',
+              '.git',
+              'dist',
+              '.sst',
+              '.turbo',
+              '.next',
+            ].includes(file)
+          )
+            continue;
+          collectFiles(fullPath);
+        } else if (
+          file.endsWith('.ts') ||
+          file.endsWith('.js') ||
+          file.endsWith('.tsx') ||
+          file.endsWith('.jsx')
+        ) {
+          allFiles.push(fullPath);
+        }
+      }
+    };
+    if (fs.existsSync(rootDir)) collectFiles(rootDir);
+
+    for (const file of allFiles) {
+      const base = path.basename(file, path.extname(file));
+      if (base === 'index' || base.endsWith('.test') || base.endsWith('.spec'))
+        continue;
+
+      let referenced = false;
+      try {
+        const { status } = (await execFileAsync(rgPath, [
+          '--quiet',
+          '--fixed-strings',
+          '--word-regexp',
+          '--glob',
+          `!${path.relative(rootDir, file)}`,
+          '--glob',
+          '!**/node_modules/**',
+          base,
+          rootDir,
+        ])) as any;
+        if (status === 0) referenced = true;
+      } catch (e: any) {
+        if (e.code === 0) referenced = true;
+      }
+
+      if (!referenced) orphanedFiles.push(path.relative(rootDir, file));
+    }
+
+    if (orphanedFiles.length > 0) {
+      rawIssues.push({
+        type: IssueType.DeadCode,
+        severity: Severity.Major,
+        location: { file: 'codebase', line: 0 },
+        message: `Orphaned files: Found ${orphanedFiles.length} potentially unused files.`,
+        recommendation: `Audit and remove orphaned files to reduce cognitive load: ${orphanedFiles.slice(0, 3).join(', ')}`,
+      });
+    }
+
+    const results = groupIssuesByFile(rawIssues);
+    const score = this.calculateScore(
+      debtMarkers,
+      emptyDirs.length,
+      orphanedFiles.length
+    );
+
+    const summary = {
+      score,
+      criticalIssues: rawIssues.filter((i) => i.severity === Severity.Critical)
+        .length,
+      majorIssues: rawIssues.filter((i) => i.severity === Severity.Major)
+        .length,
+      minorIssues: rawIssues.filter((i) => i.severity === Severity.Minor)
+        .length,
+      totalIssues: rawIssues.length,
+      totalFiles: filesAnalyzed,
+      recommendations: rawIssues.map((i) => i.recommendation),
+    };
+
+    return buildSpokeOutput(this.id, '0.1.0', summary, results, {
+      debtMarkers,
+      emptyDirs,
+      orphanedFiles,
+    });
+  }
+
+  public score(output: SpokeOutput, _options: ScanOptions): ToolScoringOutput {
+    const score =
+      typeof output.summary.score === 'number' ? output.summary.score : 0;
+    const debtCount = (output.metadata?.debtMarkers as number) || 0;
+    const orphanCount = ((output.metadata?.orphanedFiles as any[]) || [])
+      .length;
+
+    return {
+      toolName: this.id,
+      score,
+      rawMetrics: output.metadata as any,
+      factors: [
+        {
+          name: 'Technical Debt',
+          impact: debtCount > 0 ? -Math.min(20, debtCount) : 5,
+          description: `Found ${debtCount} TODO/FIXME markers.`,
+        },
+        {
+          name: 'File Orphans',
+          impact: orphanCount > 0 ? -Math.min(30, orphanCount * 5) : 10,
+          description: `Found ${orphanCount} potentially unused files.`,
+        },
+      ],
+      recommendations: output.summary.recommendations.map((action: string) => ({
+        action,
+        estimatedImpact: 5,
+        priority: RecommendationPriority.Medium,
+      })),
+    };
+  }
+
+  private calculateScore(debt: number, empty: number, orphans: number): number {
+    let score = 100;
+    score -= debt * 1;
+    score -= empty * 2;
+    score -= orphans * 5;
+    return Math.max(0, Math.min(100, score));
+  }
+}
+
+// Register with the global registry
+ToolRegistry.register(new HygieneAuditProvider());

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}