pkg-scaffold 2.3.0 → 3.0.0

package/.scaffold-ignore

@@ -0,0 +1,22 @@
+# ============================================================================
+# ⚙️ pkg-scaffold Rule Suppression & Intent Profiles
+# ============================================================================
+# Define exact symbols, file patterns, or dependency keys that must remain 
+# preserved during dead-code scanning and transactional refactoring pruning.
+
+# Framework & Meta Entrypoints (Implicitly Alive)
+pages/api/*
+app/routes/*
+src/entry-point.js
+
+# Intent Suppression: Library Code / Consumer Consumption Contracts
+export:publicApiMethod
+export:initializePlugin
+export:onConfigLoaded
+
+# Globally Ignored Module Specifiers
+@types/node
+tslib
+
+# Secret Heuristic Exemptions (Explicit False Positive Control)
+exempt_token_pattern

package/README.md

@@ -1,107 +1,94 @@
-# 🚀 pkg-scaffold
-
-**Advanced Dependency Intelligence & Zero-Config Workspace Initializer**
-
-`pkg-scaffold` is a high-performance CLI tool designed to audit, clean, and initialize your JavaScript/TypeScript workspaces. It goes far beyond simple scaffolding by analyzing your source code's Abstract Syntax Tree (AST) to find critical issues like undeclared dependencies, orphaned packages, and security leaks.
-
-
-[![npm version](https://img.shields.io/npm/v/pkg-scaffold.svg?style=flat&color=CB3837)](https://www.npmjs.com/package/pkg-scaffold)
-[![npm downloads](https://img.shields.io/npm/dm/pkg-scaffold.svg?style=flat&color=34ADFF)](https://www.npmjs.com/package/pkg-scaffold)
-[![License](https://img.shields.io/badge/license-MIT-orange.svg?style=flat)](LICENSE)
-[![GitHub stars](https://img.shields.io/github/stars/DreamLongYT/pkg-scaffold.svg?style=flat&color=gold)](https://github.com/DreamLongYT/pkg-scaffold/stargazers)
-
----
-
-## ✨ Why pkg-scaffold?
-
-Most tools just create a `package.json`. `pkg-scaffold` **understands** your code. It bridges the gap between your source files and your configuration.
-
-### 🔍 Deep Intelligence Features
-
-*   **🚨 Ghost Dependency Detection**: Finds packages you `import` in your code but forgot to add to `package.json`. These are critical errors that will break your CI/CD or production builds.
-*   **🗑️ Orphaned Package Identification**: Finds packages listed in your `package.json` that are never actually used in your code. Perfect for reducing bundle size and "dependency bloat".
-*   **⚡ Unused Import Auditor**: Pinpoints specific files and line numbers where a package is imported but its identifier is never referenced.
-*   **🔐 Security Compliance**: Automatically scans for hardcoded secrets (API keys, tokens, passwords) and offers to move them safely into `.env` files.
-*   **📛 Deprecation Guard**: Live-checks your dependencies against the npm registry to warn you about deprecated or non-existent packages.
-*   **🏗️ Intelligent Scaffolding**: Detects your framework (React, Vue, Svelte, Next.js, etc.) and automatically generates optimized `tsconfig.json`, `eslint.config.js`, `.prettierrc`, and `.gitignore`.
-*   **📦 Monorepo Ready**: Automatically detects sub-workspaces and offers to set up `pnpm-workspace.yaml` or npm/yarn workspaces.
-
----
-
-## 🚀 Quick Start
-
-You don't even need to install it to try it out:
-
-```bash
-npx pkg-scaffold
-```
-
-Or install it globally:
-
-```bash
-npm install -g pkg-scaffold
-# then run
-pkg-scaffold
-```
-
----
-
-## 🛠️ How it works
-
-### 1. The Scan
-`pkg-scaffold` crawls your workspace, ignoring `node_modules` and build artifacts. It parses every `.js`, `.ts`, `.jsx`, and `.tsx` file using a high-performance AST engine.
-
-### 2. The Analysis
-It maps your imports against your `package.json`. It knows about:
-*   **Aliases**: Understands that `lodash` is often imported as `_`.
-*   **Binaries**: Knows that `tsc` comes from `typescript` and `vite` from `vite`.
-*   **Type-only imports**: Correctly handles TypeScript `import type` without flagging them as unused.
-*   **Side-effects**: Detects `import 'css-file'` or polyfills correctly.
-
-### 3. The Fix
-The tool is interactive. It will ask you before:
-*   Adding missing (ghost) dependencies.
-*   Pruning unused (orphaned) packages.
-*   Injecting `dotenv` initialization.
-*   Moving secrets to `.env`.
-
----
-
-## 📊 Summary Report
-At the end of every run, you get a clear intelligence summary:
-
-```text
-═══════════════════════════════════════════════════════════════════
-📊 DEPENDENCY INTELLIGENCE SUMMARY
-═══════════════════════════════════════════════════════════════════
-   📁 Files scanned:           42
-   📦 Packages imported:        18
-   🚨 Ghost deps (missing):     2 — CRITICAL
-   🗑️  Orphaned deps (unused):   3
-   ⚡ Unused imports:           5
-   📛 Deprecated packages:      1
-   🔐 Hardcoded secrets:        1 — SECURITY RISK
-═══════════════════════════════════════════════════════════════════
-```
-
----
-
-## 🤝 Contributing
-
-Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
-
-1. Fork the Project
-2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
-3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
-4. Push to the Branch (`git push origin feature/AmazingFeature`)
-5. Open a Pull Request
-
----
-
-## 📄 License
-
-Distributed under the MIT License. See `LICENSE` for more information.
-
----
-
-**Built with ❤️ by [DreamLongYT](https://github.com/DreamLongYT)**
+# 📦 pkg-scaffold v3.0.0
+
+**Enterprise-Grade AST Syntax Refactoring & Self-Healing Engine**
+
+[![npm version](https://img.shields.io/npm/v/pkg-scaffold.svg?style=flat&color=CB3837)](https://www.npmjs.com/package/pkg-scaffold)
+[![npm downloads](https://img.shields.io/npm/dm/pkg-scaffold.svg?style=flat&color=34ADFF)](https://www.npmjs.com/package/pkg-scaffold)
+[![License](https://img.shields.io/badge/license-MIT-orange.svg?style=flat)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/DreamLongYT/pkg-scaffold.svg?style=flat&color=gold)](https://github.com/DreamLongYT/pkg-scaffold)
+
+`pkg-scaffold` is an advanced, AST-driven tool designed to prune dead code, orphaned files, and unused exports from your JavaScript and TypeScript codebases with unprecedented safety. Unlike traditional linters, `pkg-scaffold` doesn't just report issues—it fixes them within a secure, transactional sandbox.
+
+---
+
+## 🚀 Key Features
+
+- **AST-Based Deep Tracing**: Leverages the official TypeScript compiler to trace dependencies through complex barrel files, re-exports, and default export chains.
+- **Automated Self-Healing**: Automatically runs your project's test suite after refactoring. If a regression is detected (non-zero exit code), it triggers an immediate rollback.
+- **Transactional Safety**: All modifications occur in a Git-isolated sandbox with a backup journaling system. Your original state is always recoverable.
+- **Interactive Optimization Plan**: Generates a detailed "dry-run" plan for user confirmation before any file is touched.
+- **Suppression Engine**: Fine-grained control using `@scaffold-suppress` directives to protect specific files or exports from being pruned.
+
+---
+
+## ⚔️ Competitive Analysis: Why pkg-scaffold?
+
+While tools like [Knip](https://knip.dev/) or [Depcheck](https://github.com/depcheck/depcheck) are excellent for reporting, `pkg-scaffold` is built for **automated architectural cleanup**.
+
+| Feature | **pkg-scaffold** | Knip.dev | Depcheck | ts-prune |
+| :--- | :---: | :---: | :---: | :---: |
+| **Dead Code Detection** | ✅ AST-Deep | ✅ Comprehensive | ⚠️ Regex/Loose | ✅ Basic |
+| **Automated Pruning** | ✅ Native | ⚠️ Experimental | ❌ No | ❌ No |
+| **Self-Healing (Auto-Rollback)** | ✅ **Yes** | ❌ No | ❌ No | ❌ No |
+| **Transaction Sandbox** | ✅ **Git + Journal** | ❌ No | ❌ No | ❌ No |
+| **Interactive Approval** | ✅ **Yes** | ❌ No | ❌ No | ❌ No |
+| **Barrel File Tracing** | ✅ High-Fidelity | ✅ Good | ❌ No | ⚠️ Limited |
+| **Status** | 🚀 Active | 🚀 Active | 🛠️ Maintenance | 🛠️ Maintenance |
+
+> **The Verdict:** `pkg-scaffold` wins when you need a **safe, automated workflow** that guarantees your project stays functional after cleaning up technical debt.
+
+---
+
+## 🛠️ Installation & Usage
+
+### Installation
+```bash
+npm install -g pkg-scaffold
+```
+
+### Basic Usage (Dry-Run)
+Analyze your project without making any changes:
+```bash
+pkg-scaffold --cwd ./my-project --no-fix
+```
+
+### Active Refactoring (Self-Healing)
+Analyze, prune, and validate with automatic rollback on test failure:
+```bash
+pkg-scaffold --cwd ./my-project --fix --test-command "npm test"
+```
+
+### Options
+| Flag | Description | Default |
+| :--- | :--- | :--- |
+| `--cwd <path>` | Execution context root directory | `process.cwd()` |
+| `--fix` | Enable atomic code updates and pruning | `true` |
+| `--test-command` | Script to run for self-healing validation | `npm test` |
+| `--yes` | Skip confirmation prompts | `false` |
+| `--verbose` | Toggle expanded debug telemetry | `false` |
+
+---
+
+## 🛡️ Suppression
+
+Protect a file or a specific export from being removed:
+
+```javascript
+/**
+ * @scaffold-suppress legacyFunction
+ */
+export const legacyFunction = () => {
+  // This export is safe even if unused
+};
+
+/**
+ * @scaffold-suppress
+ */
+// This entire file is protected from being flagged as orphaned
+```
+
+---
+
+## 📜 License
+
+MIT © DreamLongYT

package/bin/cli.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+/**
+ * ============================================================================
+ * 🏁 pkg-scaffold CLI Entry Point
+ * ============================================================================
+ * Handles option compilation, environment orchestration, option validation,
+ * and initiates the primary operational pipeline loop.
+ */
+
+import { Command } from 'commander';
+import ansis from 'ansis';
+import path from 'path';
+import fs from 'fs/promises';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const program = new Command();
+
+async function bootstrap() {
+  try {
+    const packageJsonPath = path.resolve(__dirname, '../package.json');
+    const packageJsonContent = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+
+    program
+      .name('pkg-scaffold')
+      .description(ansis.cyan('Enterprise-Grade AST Syntax Refactoring & Self-Healing Engine'))
+      .version(packageJsonContent.version || '3.0.0');
+
+    program
+      .option('-c, --cwd <path>', 'Specify the execution context root directory', process.cwd())
+      .option('--fix', 'Enable atomic code updates, structural file pruning, and active type sanitization', true)
+      .option('--no-fix', 'Disable direct file manipulation modifications (dry-run reporting mode)')
+      .option('--tsconfig <filename>', 'Specify path to custom layout configurations', 'tsconfig.json')
+      .option('--test-command <command>', 'Integrated continuous safety test validation script execution path', 'npm test')
+      .option('--workspace', 'Enable high-density workspace workspace/monorepo cluster mesh evaluation parsing', false)
+      .option('--verbose', 'Toggle expanded trace telemetry for debug operational diagnostics', false)
+      .option('-y, --yes', 'Skip confirmation prompts and execute planned structural modifications automatically', false);
+
+    program.parse(process.argv);
+    const options = program.opts();
+
+    console.log(ansis.bold.green(`\n📦 pkg-scaffold v${packageJsonContent.version || '3.0.0'} Engine Activation`));
+    console.log(ansis.dim('------------------------------------------------------------'));
+    console.log(`${ansis.bold('Target Workspace Root :')} ${ansis.blue(path.resolve(options.cwd))}`);
+    console.log(`${ansis.bold('Refactoring Mode     :')} ${options.fix ? ansis.yellow('Active Fixing & Self-Healing Enabled') : ansis.gray('Dry-Run Reporting Only')}`);
+    console.log(`${ansis.bold('Validation Sandbox   :')} ${ansis.magenta(options.testCommand)}`);
+    console.log(ansis.dim('------------------------------------------------------------\n'));
+
+    const engineModulePath = path.resolve(__dirname, '../src/EngineContext.js');
+    
+    try {
+      await fs.access(engineModulePath);
+    } catch {
+      console.error(ansis.red(`🚨 Execution Fault: Core engine architecture files missing. Ensure src/ directory layout is fully generated.`));
+      process.exit(1);
+    }
+
+    // Lazy load execution context wrapper to align with domain initialization
+    const { RefactoringEngine } = await import('../src/index.js');
+
+    if (!RefactoringEngine) {
+      console.error(ansis.red('🚨 Architecture Boundary Error: RefactoringEngine could not be resolved from code topology channels.'));
+      process.exit(1);
+    }
+
+    // Ensure cwd is always an absolute path regardless of how it was passed (e.g., '--cwd .')
+    const engine = new RefactoringEngine({
+      cwd: path.resolve(options.cwd),
+      autoFix: options.fix,
+      tsconfig: options.tsconfig,
+      testCommand: options.testCommand,
+      workspace: options.workspace,
+      verbose: options.verbose,
+      skipConfirm: options.yes
+    });
+
+    await engine.run();
+
+    console.log(ansis.bold.green('\n✨ Core cycle execution completed successfully. Structural layout is clean.'));
+    process.exit(0);
+
+  } catch (criticalBootError) {
+    console.error(ansis.bold.red(`\n🚨 Critical Lifecycle Boot Instability: ${criticalBootError.message}`));
+    if (criticalBootError.stack) {
+      console.error(ansis.dim(criticalBootError.stack));
+    }
+    process.exit(1);
+  }
+}
+
+bootstrap();

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "pkg-scaffold",
-  "version": "2.3.0",
-  "description": "Zero-config workspace initializer with advanced dependency intelligence: detects ghost dependencies (used but undeclared), orphaned packages (declared but unused), unused imports with file locations, deprecated packages, hardcoded secrets, and more.",
+  "version": "3.0.0",
+  "description": "An advanced, AST-driven dependency resolution, refactoring, and self-healing engine.",
   "type": "module",
   "main": "index.js",
   "bin": {
-    "pkg-scaffold": "./index.js"
+    "pkg-scaffold": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js",
+    "test": "echo \"Error: no test specified\" && exit 0",
+    "test:stability": "npm run test"
   },
   "keywords": [
     "scaffold",
@@ -35,8 +40,15 @@
   },
   "homepage": "https://github.com/DreamLongYT/pkg-scaffold#readme",
   "dependencies": {
-    "enhanced-resolve": "^5.24.0",
-    "npm-deprecated-check": "^1.4.0",
-    "typescript": "^6.0.3"
+    "ansis": "^3.0.0",
+    "commander": "^12.0.0",
+    "enhanced-resolve": "^5.16.0",
+    "execa": "^8.0.1",
+    "ramda": "^0.29.1",
+    "typescript": "^5.4.5",
+    "yocto-spinner": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
   }
 }

package/src/EngineContext.js

@@ -0,0 +1,287 @@
+/**
+ * ============================================================================
+ * 📦 pkg-scaffold v3.0.0: Enterprise In-Memory Codebase State Manifest
+ * ============================================================================
+ * Implements a high-density, centralized graph database context for tracking
+ * software engineering debt, dependencies, types, and vulnerabilities.
+ */
+
+import path from 'path';
+import fs from 'fs/promises';
+
+/**
+ * High-Fidelity Graph Element Node representing a single file asset boundary.
+ * @scaffold-suppress GraphNode
+ */
+export class GraphNode {
+  constructor(filePath) {
+    this.filePath = path.normalize(filePath);
+    this.contentHash = '';
+    this.isLibraryEntry = false;
+    this.isFrameworkContract = false;
+    this.scriptKind = 0; // Ambient enum mapping
+
+    // Explicit and Computed Dynamic Syntax Boundaries
+    this.explicitImports = new Set();
+    this.dynamicImports = new Set();
+    this.importedSymbols = new Set(); // Format: 'specifier:symbol' or 'specifier:*'
+    
+    // Internal API Exposed Interfaces (Symbol Name -> ExportMetadata)
+    this.internalExports = new Map();
+    this.typeOnlyExports = new Set();
+    
+    // Semantic Reference Verification Registries
+    this.instantiatedIdentifiers = new Set();
+    this.rawStringReferences = new Set();
+    this.propertyAccessChains = new Set();
+    
+    // Dependency Mesh Connection Maps
+    this.incomingEdges = new Set(); // Set of absolute filePaths depending on this component
+    this.outgoingEdges = new Set(); // Set of absolute internal filePaths this component calls
+    
+    // Security & Compliance Anomaly Matrices
+    this.securityThreats = [];
+    this.calculatedDynamicImports = [];
+    this.localSuppressedRules = new Set();
+    
+    // Detailed AST Location Diagnostics (Symbol -> Structural Location Mapping)
+    this.symbolSourceLocations = new Map(); // Symbol -> { line: number, column: number, length: number }
+  }
+
+  /**
+   * Evaluates if a specific exposed symbol token is utilized by any incoming edges.
+   * Leverages precise syntax identity collections.
+   */
+  isSymbolReferencedExternally(symbolName, projectGraph) {
+    if (this.isLibraryEntry) return true;
+    
+    for (const parentPath of this.incomingEdges) {
+      const parentNode = projectGraph.get(parentPath);
+      if (!parentNode) continue;
+
+      // Direct identity reference check
+      if (parentNode.instantiatedIdentifiers.has(symbolName)) return true;
+      
+      // Property lookup reference checks (e.g., config.databaseUrl)
+      for (const accessChain of parentNode.propertyAccessChains) {
+        if (accessChain.endsWith(`.${symbolName}`) || accessChain.includes(`.${symbolName}.`)) {
+          return true;
+        }
+      }
+
+      // Safe fallback lookup inside string reference caches (e.g., obj['databaseUrl'])
+      if (parentNode.rawStringReferences.has(symbolName)) return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Compiles complete localized diagnostic telemetry tracking metrics for this node instance.
+   */
+  compileNodeTelemetry() {
+    return {
+      path: this.filePath,
+      totalExplicitImportsCount: this.explicitImports.size,
+      totalExposedExportsCount: this.internalExports.size,
+      incomingDependenciesCount: this.incomingEdges.size,
+      outgoingDependenciesCount: this.outgoingEdges.size,
+      isDanglingOrphan: this.incomingEdges.size === 0 && !this.isLibraryEntry,
+      trackedThreatsCount: this.securityThreats.length
+    };
+  }
+}
+
+/**
+ * Enterprise Engine Run State Registry & Suppression Context Matrix
+ */
+export class EngineContext {
+  constructor(options = {}) {
+    this.cwd = path.normalize(options.cwd || process.cwd());
+    this.cacheDir = path.join(this.cwd, '.scaffold-cache');
+    this.ignoreFilePath = path.join(this.cwd, '.scaffold-ignore');
+    this.tsconfigFilename = options.tsconfig || 'tsconfig.json';
+    this.testCommand = options.testCommand || 'npm test';
+    
+    this.allowAutoFix = options.autoFix ?? true;
+    this.isWorkspaceEnabled = options.workspace ?? false;
+    this.verbose = options.verbose ?? false;
+    this.skipConfirm = options.skipConfirm ?? false;
+
+    // Core Memory Repositories
+    this.graph = new Map(); // Absolute File Path -> GraphNode
+    this.registryHashes = new Map(); // Package Name -> Secure Lockfile Signature String
+    this.globallyIgnoredSymbols = new Set();
+    this.globallyIgnoredPaths = [];
+    this.monorepoPackageRoots = new Set();
+    
+    // Structural Heuristic Verification Metrics Tracker
+    this.metrics = {
+      startTime: 0,
+      endTime: 0,
+      totalFilesScanned: 0,
+      cacheHits: 0,
+      cacheMisses: 0,
+      prunedFilesCount: 0,
+      prunedExportsCount: 0,
+      totalSymbolsAnalyzed: 0,
+      securityVulnerabilitiesMitigated: 0
+    };
+  }
+
+  /**
+   * Initializes baseline context options, directory footprints, and suppression maps.
+   */
+  async initialize() {
+    this.metrics.startTime = Date.now();
+    await fs.mkdir(this.cacheDir, { recursive: true });
+    await this.compileIgnoreConfigurations();
+  }
+
+  /**
+   * Parses .scaffold-ignore layers using precise token segment matching
+   * instead of high-risk loose regex blocks.
+   */
+  async compileIgnoreConfigurations() {
+    try {
+      const content = await fs.readFile(this.ignoreFilePath, 'utf8');
+      const lines = content.split('\n');
+
+      for (let line of lines) {
+        line = line.trim();
+        if (!line || line.startsWith('#')) continue;
+
+        if (line.startsWith('export:')) {
+          const symbolToken = line.replace('export:', '').trim();
+          this.globallyIgnoredSymbols.add(symbolToken);
+        } else if (line.startsWith('path:')) {
+          const pathToken = line.replace('path:', '').trim();
+          this.globallyIgnoredPaths.push(path.normalize(pathToken));
+        } else {
+          // Standard structural path rule fallback
+          this.globallyIgnoredPaths.push(path.normalize(line));
+        }
+      }
+    } catch {
+      // Configuration optionally omitted; proceed with default execution flags
+    }
+  }
+
+  /**
+   * Allocates or resolves a unified GraphNode reference inside our memory map index.
+   */
+  createNode(absoluteFilePath) {
+    const normalizedPath = path.normalize(absoluteFilePath);
+    if (this.graph.has(normalizedPath)) {
+      return this.graph.get(normalizedPath);
+    }
+    const node = new GraphNode(normalizedPath);
+    this.graph.set(normalizedPath, node);
+    return node;
+  }
+
+  /**
+   * Checks if an absolute file token path matches configuration ignore directives.
+   * Evaluates sub-path sequences exactly to prevent regular expression parsing drops.
+   */
+  isPathIgnored(absoluteFilePath) {
+    const relativeText = path.relative(this.cwd, absoluteFilePath);
+    
+    for (const ignoredTarget of this.globallyIgnoredPaths) {
+      if (relativeText === ignoredTarget || relativeText.startsWith(path.join(ignoredTarget, path.sep))) {
+        return true;
+      }
+      // Handle explicit wildcard terminal indicators
+      if (ignoredTarget.endsWith('*')) {
+        const baseSegment = ignoredTarget.slice(0, -1);
+        if (relativeText.startsWith(baseSegment)) return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Processes the entire active dependency map to compile structural issue indices.
+   * Evaluates orphaned components, dead exports, and supply-chain threats.
+   */
+  generateSummaryReport() {
+    this.metrics.endTime = Date.now();
+    const durationSeconds = ((this.metrics.endTime - this.metrics.startTime) / 1000).toFixed(2);
+    
+    const summary = {
+      executionDuration: `${durationSeconds}s`,
+      totalFilesProcessed: this.metrics.totalFilesScanned,
+      graphCacheOptimization: {
+        hits: this.metrics.cacheHits,
+        misses: this.metrics.cacheMisses,
+        ratio: this.metrics.totalFilesScanned > 0 
+          ? `${((this.metrics.cacheHits / this.metrics.totalFilesScanned) * 100).toFixed(1)}%`
+          : '0%'
+      },
+      structuralIssuesDetected: {
+        deadFiles: [],
+        deadExports: [],
+        securityThreats: []
+      },
+      modificationsExecuted: {
+        filesUnlinked: this.metrics.prunedFilesCount,
+        exportsStripped: this.metrics.prunedExportsCount
+      }
+    };
+
+    for (const [filePath, node] of this.graph.entries()) {
+      // Skip package control files from standard structural dead-code checks
+      if (filePath.endsWith('package.json')) continue;
+      if (this.isPathIgnored(filePath)) continue;
+
+      const relativePath = path.relative(this.cwd, filePath);
+
+      // Category A: Completely orphaned components (no references, not library/framework entries)
+      // A file with ANY @scaffold-suppress directive is considered intentionally retained and must
+      // never be flagged as orphaned, even if no other file imports it directly.
+      const fileHasSuppressDirective = node.localSuppressedRules.size > 0;
+      if (node.incomingEdges.size === 0 && !node.isLibraryEntry && !node.isFrameworkContract && !fileHasSuppressDirective) {
+        summary.structuralIssuesDetected.deadFiles.push(relativePath);
+        continue; // An orphaned file implies all internal sub-exports are dead; skip sub-checks
+      }
+
+      // Category B: Dead Named Exports inside active files
+      for (const [exportName, meta] of node.internalExports.entries()) {
+        this.metrics.totalSymbolsAnalyzed++;
+        
+        // Skip entry configurations, global suppresses, and type-suppressed symbols
+        if (exportName === 'default' || 
+            this.globallyIgnoredSymbols.has(exportName) || 
+            node.localSuppressedRules.has(exportName)) {
+          continue;
+        }
+        
+        if (!node.isSymbolReferencedExternally(exportName, this.graph)) {
+          const diagnosticLocation = node.symbolSourceLocations.get(exportName) || { line: 1, column: 1 };
+          summary.structuralIssuesDetected.deadExports.push({
+            file: relativePath,
+            symbol: exportName,
+            type: meta.type || 'named',
+            line: diagnosticLocation.line,
+            column: diagnosticLocation.column
+          });
+        }
+      }
+
+      // Category C: High-Entropy Password / Key Hardcode Vulnerabilities
+      if (node.securityThreats && node.securityThreats.length > 0) {
+        node.securityThreats.forEach(threat => {
+          summary.structuralIssuesDetected.securityThreats.push({
+            file: relativePath,
+            identifier: threat.variableKey,
+            riskCode: threat.riskCode || 'HIGH_RISK_SECRET_LEAK',
+            entropy: threat.entropyValue,
+            line: threat.line || 1
+          });
+        });
+      }
+    }
+
+    return summary;
+  }
+}