pkg-scaffold 2.4.0 → 3.1.0

package/src/ast/ASTAnalyzer.js

@@ -1,313 +1,266 @@
 import ts from 'typescript';
 import fs from 'fs/promises';
-import crypto from 'crypto';
+import path from 'path';
 
 /**
  * Enterprise AST Syntax Walker & Feature Extractor
- * Utilizes the official TypeScript Compiler infrastructure to execute deeply nested
- * node classification without falling back to high-risk regular expression approximations.
+ * Upgraded to use full TypeScript Compiler API (ts.createProgram + TypeChecker)
+ * for type-aware cross-file analysis.
  */
+import { OxcAnalyzer } from './OxcAnalyzer.js';
+
 export class ASTAnalyzer {
   constructor(context) {
     this.context = context;
-    // Standard high-entropy baseline selectors for AST variable tracking
-    this.entropyThreshold = 4.3;
+    this.program = null;
+    this.checker = null;
+    this.oxc = new OxcAnalyzer(context);
   }
 
   /**
-   * Parses target file data into an isolated AST representation and populates metadata structures.
-   * @param {string} filePath - Absolute path to on-disk component
-   * @param {Object} fileNode - In-memory structural graph reference node
+   * Initializes the TypeScript program for the entire project.
+   * This is crucial for cross-file type resolution.
+   */
+  initProgram(filePaths, options = {}) {
+    const defaultOptions = {
+      target: ts.ScriptTarget.Latest,
+      module: ts.ModuleKind.CommonJS,
+      allowJs: true,
+      checkJs: true,
+      esModuleInterop: true,
+      skipLibCheck: true
+    };
+    
+    this.program = ts.createProgram(filePaths, { ...defaultOptions, ...options });
+    this.checker = this.program.getTypeChecker();
+  }
+
+  /**
+   * Processes a file using the initialized program and type checker.
    */
   async processFile(filePath, fileNode) {
-    try {
-      const sourceText = await fs.readFile(filePath, 'utf8');
-      
-      // Configure target extraction structures to parse TS, JSX, and modern TC39 specifications
-      const sourceFile = ts.createSourceFile(
-        filePath,
-        sourceText,
-        ts.ScriptTarget.Latest,
-        true, // Ensure parent pointers are bound to allow localized subtree walking
-        this.getScriptKind(filePath)
-      );
+    // Fast Path: Use OXC for rapid scanning if type checking is not strictly required for this file
+    if (this.context.fastMode) {
+      return await this.oxc.processFile(filePath, fileNode);
+    }
 
-      this.walkNode(sourceFile, sourceFile, fileNode);
-      this.extractTopLevelJSDocSuppreessions(sourceFile, fileNode);
-      
-      return true;
-    } catch (parseError) {
+    if (!this.program) {
+      throw new Error('ASTAnalyzer must be initialized with initProgram() before processing files.');
+    }
+
+    const sourceFile = this.program.getSourceFile(filePath);
+    if (!sourceFile) {
       if (this.context.verbose) {
-        console.error(`[AST Open Error] Failed compilation validation mapping on element: ${filePath}. Reason: ${parseError.message}`);
+        console.error(`[AST Error] Source file not found in program: ${filePath}`);
       }
       return false;
     }
+
+    this.extractTopLevelJSDocSuppreessions(sourceFile, fileNode);
+    this.walkNode(sourceFile, sourceFile, fileNode);
+    
+    return true;
   }
 
-  /**
-   * Primary node walker loop executing atomic switch classifications.
-   * Challenge #7: Resolves conditional/destructured references to prevent cascading breakages.
-   */
   walkNode(sourceFile, node, fileNode) {
     if (!node) return;
 
-    switch (node.kind) {
-      // Handle Explicit Named or Absolute Star Namespace Imports
-      case ts.SyntaxKind.ImportDeclaration: {
-        if (node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
-          const specifier = node.moduleSpecifier.text;
-          fileNode.explicitImports.add(specifier);
-
-          if (node.importClause) {
-            // Trace named bounds: import { activeToken } from 'module';
-            if (node.importClause.namedBindings) {
-              if (ts.isNamedImports(node.importClause.namedBindings)) {
-                node.importClause.namedBindings.elements.forEach(element => {
-                  const importedName = element.name.text;
-                  const propertyName = element.propertyName ? element.propertyName.text : importedName;
-                  fileNode.importedSymbols.add(`${specifier}:${propertyName}`);
-                });
-              } else if (ts.isNamespaceImport(node.importClause.namedBindings)) {
-                // Tracking total wildcard imports: import * as layout from 'module';
-                fileNode.importedSymbols.add(`${specifier}:*`);
-              }
-            }
-            // Trace default bounds: import React from 'react';
-            if (node.importClause.name) {
-              fileNode.importedSymbols.add(`${specifier}:default`);
-            }
+    // Use type checker to resolve symbols if needed
+    if (ts.isIdentifier(node) && !this.isNodeDeclarationName(node)) {
+      const symbol = this.checker.getSymbolAtLocation(node);
+      if (symbol) {
+        const declarations = symbol.getDeclarations();
+        if (declarations && declarations.length > 0) {
+          const declFile = declarations[0].getSourceFile().fileName;
+          const symbolName = symbol.getName();
+          
+          // Track sub-symbol usage (Property Access)
+          if (ts.isPropertyAccessExpression(node.parent) && node.parent.name === node) {
+             const parentType = this.checker.getTypeAtLocation(node.parent.expression);
+             const parentSymbol = parentType.getSymbol() || parentType.aliasSymbol;
+             if (parentSymbol) {
+               const parentDecl = parentSymbol.getDeclarations()?.[0];
+               if (parentDecl) {
+                 const parentFile = parentDecl.getSourceFile().fileName;
+                 fileNode.memberUsage = fileNode.memberUsage || new Set();
+                 fileNode.memberUsage.add(`${parentFile}:${parentSymbol.getName()}.${symbolName}`);
+               }
+             }
           }
-        }
-        break;
-      }
 
-      // Handle Explicit Namespace Requirements: import config = require('./config');
-      case ts.SyntaxKind.ImportEqualsDeclaration: {
-        if (node.moduleReference && ts.isExternalModuleReference(node.moduleReference)) {
-          if (node.moduleReference.expression && ts.isStringLiteral(node.moduleReference.expression)) {
-            fileNode.explicitImports.add(node.moduleReference.expression.text);
+          if (declFile !== sourceFile.fileName) {
+            fileNode.resolvedReferences = fileNode.resolvedReferences || new Set();
+            fileNode.resolvedReferences.add(`${declFile}:${symbolName}`);
           }
         }
-        break;
-      }
-
-      // Challenge #1: Tracking dynamic expressions e.g., import('./chunks/' + variant)
-      case ts.SyntaxKind.CallExpression: {
-        if (node.expression && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
-          const firstArgument = node.arguments[0];
-          if (firstArgument) {
-            if (ts.isStringLiteral(firstArgument)) {
-              fileNode.explicitImports.add(firstArgument.text);
-              fileNode.dynamicImports.add(firstArgument.text);
-            } else {
-              // Deeply trace runtime calculated variables within the import parameters call
-              const stringPatterns = [];
-              this.traceStringExpressions(firstArgument, stringPatterns);
-              fileNode.calculatedDynamicImports.push({
-                rawText: firstArgument.getText(sourceFile),
-                heuristics: stringPatterns,
-                position: node.getStart(sourceFile)
-              });
-            }
-          }
-        }
-        break;
       }
+    }
 
-      // Handle Variable Declaration Assignments & Challenge #11 (AST Secret Scanning)
-      case ts.SyntaxKind.VariableDeclaration: {
-        if (node.name && ts.isIdentifier(node.name)) {
-          this.auditAssignmentSafety(node.name.text, node.initializer, fileNode, sourceFile);
-        } else if (node.name && (ts.isObjectBindingPattern(node.name) || ts.isArrayBindingPattern(node.name))) {
-          // Flatten binding properties to map destructured usage accurately
-          node.name.elements.forEach(element => {
-            if (element.name && ts.isIdentifier(element.name)) {
-              this.auditAssignmentSafety(element.name.text, null, fileNode, sourceFile);
-            }
-          });
-        }
+    switch (node.kind) {
+      case ts.SyntaxKind.ImportDeclaration: {
+        this.handleImportDeclaration(node, fileNode);
         break;
       }
-
-      // Handle Named Function Node Exports Matrix Configurations
-      case ts.SyntaxKind.FunctionDeclaration: {
-        if (node.name && ts.isIdentifier(node.name)) {
-          const name = node.name.text;
-          if (this.hasExportModifier(node)) {
-            fileNode.internalExports.set(name, { type: 'function', start: node.getStart(sourceFile), end: node.getEnd() });
-          }
-        }
+      case ts.SyntaxKind.ExportDeclaration: {
+        this.handleExportDeclaration(node, fileNode, sourceFile);
         break;
       }
-
-      // Handle Structural Class Definitions and Class Export Signatures
-      case ts.SyntaxKind.ClassDeclaration: {
-        if (node.name && ts.isIdentifier(node.name)) {
-          const name = node.name.text;
-          if (this.hasExportModifier(node)) {
-            fileNode.internalExports.set(name, { type: 'class', start: node.getStart(sourceFile), end: node.getEnd() });
-          }
-        }
+      case ts.SyntaxKind.FunctionDeclaration:
+      case ts.SyntaxKind.ClassDeclaration:
+      case ts.SyntaxKind.InterfaceDeclaration:
+      case ts.SyntaxKind.TypeAliasDeclaration:
+      case ts.SyntaxKind.EnumDeclaration:
+      case ts.SyntaxKind.ModuleDeclaration: {
+        this.handleNamedDeclaration(node, fileNode, sourceFile);
         break;
       }
-
-      // Handle Interface Definitions (Crucial for Challenge #10: Type Integrity Mapping)
-      case ts.SyntaxKind.InterfaceDeclaration: {
-        if (node.name && ts.isIdentifier(node.name)) {
-          const name = node.name.text;
-          if (this.hasExportModifier(node)) {
-            fileNode.internalExports.set(name, { type: 'interface', start: node.getStart(sourceFile), end: node.getEnd() });
-          }
-        }
+      case ts.SyntaxKind.VariableStatement: {
+        this.handleVariableStatement(node, fileNode, sourceFile);
         break;
       }
-
-      // Handle Type Invocations and Declarations Aliases
-      case ts.SyntaxKind.TypeAliasDeclaration: {
-        if (node.name && ts.isIdentifier(node.name)) {
-          const name = node.name.text;
-          if (this.hasExportModifier(node)) {
-            fileNode.internalExports.set(name, { type: 'type-alias', start: node.getStart(sourceFile), end: node.getEnd() });
-          }
-        }
+      case ts.SyntaxKind.CallExpression: {
+        this.handleCallExpression(node, fileNode, sourceFile);
         break;
       }
+    }
 
-      // Handle Explicit Export Assignments: export default baselineConfiguration;
-      case ts.SyntaxKind.ExportAssignment: {
-        const name = node.expression ? node.expression.getText(sourceFile) : 'default';
-        fileNode.internalExports.set('default', { 
-          type: 'default-assignment', 
-          referencedSymbol: name,
-          start: node.getStart(sourceFile), 
-          end: node.getEnd() 
-        });
-        break;
-      }
+    ts.forEachChild(node, child => this.walkNode(sourceFile, child, fileNode));
+  }
 
-      // Handle Arbitrary String References to catch deep framework routing or dynamic keys
-      case ts.SyntaxKind.StringLiteral: {
-        const text = node.text;
-        if (text.length > 2 && text.length < 120) {
-          fileNode.rawStringReferences.add(text);
+  handleImportDeclaration(node, fileNode) {
+    if (node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+      const specifier = node.moduleSpecifier.text;
+      fileNode.explicitImports.add(specifier);
+      
+      if (node.importClause) {
+        if (node.importClause.namedBindings) {
+          if (ts.isNamedImports(node.importClause.namedBindings)) {
+            node.importClause.namedBindings.elements.forEach(element => {
+              const importedName = element.name.text;
+              const propertyName = element.propertyName ? element.propertyName.text : importedName;
+              fileNode.importedSymbols.add(`${specifier}:${propertyName}`);
+            });
+          } else if (ts.isNamespaceImport(node.importClause.namedBindings)) {
+            fileNode.importedSymbols.add(`${specifier}:*`);
+          }
         }
-        break;
-      }
-
-      // Track general identifiers to register references to mapped import keys
-      case ts.SyntaxKind.Identifier: {
-        const idText = node.text;
-        // Avoid adding declarations to usage logs to keep verification accurate
-        if (!this.isNodeDeclarationName(node)) {
-          fileNode.instantiatedIdentifiers.add(idText);
+        if (node.importClause.name) {
+          fileNode.importedSymbols.add(`${specifier}:default`);
         }
-        break;
       }
     }
-
-    // Traverse recursively down the Node structural tree
-    ts.forEachChild(node, child => this.walkNode(sourceFile, child, fileNode));
   }
 
-  /**
-   * Challenge #1: Evaluates math operations and template configurations inside dynamic imports.
-   */
-  traceStringExpressions(node, collector) {
-    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
-      this.traceStringExpressions(node.left, collector);
-      this.traceStringExpressions(node.right, collector);
-    } else if (ts.isStringLiteral(node)) {
-      collector.push({ type: 'literal', val: node.text });
-    } else if (ts.isTemplateExpression(node)) {
-      if (node.head) collector.push({ type: 'template-slice', val: node.head.text });
-      node.templateSpans.forEach(span => {
-        collector.push({ type: 'dynamic-var', val: span.expression.getText() });
-        if (span.literal) collector.push({ type: 'template-slice', val: span.literal.text });
-      });
-    } else {
-      collector.push({ type: 'computed-variable', val: node.getText() });
+  handleExportDeclaration(node, fileNode, sourceFile) {
+    // Handle re-exports: export { x } from './y'
+    if (node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+      const specifier = node.moduleSpecifier.text;
+      if (node.exportClause && ts.isNamedExports(node.exportClause)) {
+        node.exportClause.elements.forEach(element => {
+          const name = element.name.text;
+          fileNode.internalExports.set(name, { 
+            type: 're-export', 
+            source: specifier,
+            start: node.getStart(sourceFile), 
+            end: node.getEnd() 
+          });
+        });
+      } else {
+        // export * from './y'
+        fileNode.internalExports.set('*', { type: 're-export-all', source: specifier });
+      }
     }
   }
 
-  /**
-   * Challenge #11: AST Secret Scanning. Evaluates entropy and patterns directly via assignments.
-   */
-  auditAssignmentSafety(variableName, initializer, fileNode, sourceFile) {
-    // Process variable mapping target indicators first
-    if (this.hasExportModifier(variableName?.parent)) {
-      fileNode.internalExports.set(variableName, { type: 'variable', start: variableName.parent.getStart(sourceFile), end: variableName.parent.getEnd() });
-    }
-
-    if (!initializer || !ts.isStringLiteral(initializer)) return;
-    const value = initializer.text;
+  handleNamedDeclaration(node, fileNode, sourceFile) {
+    if (this.hasExportModifier(node)) {
+      const isDefault = node.modifiers?.some(m => m.kind === ts.SyntaxKind.DefaultKeyword);
+      const name = isDefault ? 'default' : (node.name?.text || 'anonymous');
+      
+      const exportInfo = {
+        type: ts.SyntaxKind[node.kind].toLowerCase().replace('declaration', ''),
+        start: node.getStart(sourceFile),
+        end: node.getEnd()
+      };
 
-    // Challenge #11 Heuristic validation parameters matching variable patterns or contents values
-    const isSuspiciousKeyName = /api_?key|secret|token|password|auth_?token|private_?key/i.test(variableName);
-    const entropy = this.calculateShannonEntropy(value);
+      fileNode.internalExports.set(name, exportInfo);
+      
+      // Phase 4: Drill down into members
+      if (ts.isEnumDeclaration(node)) {
+        exportInfo.members = node.members.map(m => m.name.getText(sourceFile));
+      } else if (ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node)) {
+        exportInfo.members = node.members
+          .filter(m => m.name)
+          .map(m => m.name.getText(sourceFile));
+      } else if (ts.isModuleDeclaration(node)) {
+        // Handle Namespaces
+        const members = [];
+        if (node.body && ts.isModuleBlock(node.body)) {
+          node.body.statements.forEach(stmt => {
+            if (this.hasExportModifier(stmt) && (ts.isVariableStatement(stmt) || ts.isFunctionDeclaration(stmt) || ts.isClassDeclaration(stmt))) {
+              if (ts.isVariableStatement(stmt)) {
+                stmt.declarationList.declarations.forEach(d => members.push(d.name.getText(sourceFile)));
+              } else if (stmt.name) {
+                members.push(stmt.name.getText(sourceFile));
+              }
+            }
+          });
+        }
+        exportInfo.members = members;
+      }
 
-    if ((isSuspiciousKeyName && value.length > 8) || (entropy > this.entropyThreshold && value.length > 16)) {
-      fileNode.securityThreats.push({
-        identifier: variableName,
-        entropy: parseFloat(entropy.toFixed(2)),
-        position: initializer.getStart(sourceFile),
-        riskCode: 'HIGH_RISK_SECRET_LEAK'
-      });
+      const loc = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+      fileNode.symbolSourceLocations.set(name, { line: loc.line + 1, column: loc.character + 1 });
     }
   }
 
-  calculateShannonEntropy(str) {
-    const map = {};
-    for (let i = 0; i < str.length; i++) {
-      const char = str[i];
-      map[char] = (map[char] || 0) + 1;
-    }
-    let entropy = 0;
-    for (const char in map) {
-      const p = map[char] / str.length;
-      entropy -= p * Math.log2(p);
+  handleVariableStatement(node, fileNode, sourceFile) {
+    if (this.hasExportModifier(node)) {
+      node.declarationList.declarations.forEach(decl => {
+        if (decl.name && ts.isIdentifier(decl.name)) {
+          const name = decl.name.text;
+          fileNode.internalExports.set(name, { 
+            type: 'variable', 
+            start: decl.getStart(sourceFile), 
+            end: decl.getEnd() 
+          });
+        }
+      });
     }
-    return entropy;
   }
 
-  /**
-   * Challenge #18 & #8: Parse JSDoc suppression blocks right out of code statements.
-   */
-  extractTopLevelJSDocSuppreessions(sourceFile, fileNode) {
-    const fullText = sourceFile.text;
-    const commentRanges = ts.getLeadingCommentRanges(fullText, 0) || [];
-    
-    for (const range of commentRanges) {
-      const comment = fullText.slice(range.pos, range.end);
-      const matches = comment.match(/@scaffold-suppress\s+([a-zA-Z0-9_\-*:]+)/g);
-      if (matches) {
-        matches.forEach(m => {
-          const directive = m.replace('@scaffold-suppress', '').trim();
-          fileNode.localSuppressedRules.add(directive);
-        });
+  handleCallExpression(node, fileNode, sourceFile) {
+    // Trace dynamic imports
+    if (node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+      const arg = node.arguments[0];
+      if (arg && ts.isStringLiteral(arg)) {
+        fileNode.explicitImports.add(arg.text);
+        fileNode.dynamicImports.add(arg.text);
       }
     }
   }
 
   hasExportModifier(node) {
-    if (!node || !node.modifiers) return false;
-    return node.modifiers.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword);
+    return node.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
   }
 
   isNodeDeclarationName(node) {
     const parent = node.parent;
     if (!parent) return false;
-    if (ts.isVariableDeclaration(parent) && parent.name === node) return true;
-    if (ts.isFunctionDeclaration(parent) && parent.name === node) return true;
-    if (ts.isClassDeclaration(parent) && parent.name === node) return true;
-    if (ts.isInterfaceDeclaration(parent) && parent.name === node) return true;
-    if (ts.isImportSpecifier(parent) && parent.name === node) return true;
-    return false;
+    return (ts.isVariableDeclaration(parent) || ts.isFunctionDeclaration(parent) || 
+            ts.isClassDeclaration(parent) || ts.isInterfaceDeclaration(parent) || 
+            ts.isEnumDeclaration(parent) || ts.isModuleDeclaration(parent)) && parent.name === node;
   }
 
-  getScriptKind(filePath) {
-    if (filePath.endsWith('.ts')) return ts.ScriptKind.TS;
-    if (filePath.endsWith('.tsx')) return ts.ScriptKind.TSX;
-    if (filePath.endsWith('.jsx')) return ts.ScriptKind.JSX;
-    return ts.ScriptKind.JS;
+  extractTopLevelJSDocSuppreessions(sourceFile, fileNode) {
+    const fullText = sourceFile.text;
+    const commentRegex = /\/\*\*?[\s\S]*?\*\/|\/\/.*/g;
+    let match;
+    while ((match = commentRegex.exec(fullText)) !== null) {
+      const suppressMatches = match[0].match(/@scaffold-suppress\s+([a-zA-Z0-9_\-*:]+)/g);
+      if (suppressMatches) {
+        suppressMatches.forEach(m => fileNode.localSuppressedRules.add(m.replace('@scaffold-suppress', '').trim()));
+      }
+    }
   }
 }

package/src/ast/BarrelParser.js

@@ -104,6 +104,18 @@ export class BarrelParser {
         }
         break;
       }
+
+      // Track default exports declared directly within the file boundary:
+      // Handles both `export default function foo()` and `export default expression`.
+      // The canonical symbol name stored is 'default' so that forwardedNamedExports
+      // entries whose sourceSymbol is 'default' can resolve correctly via Rule A.
+      case ts.SyntaxKind.ExportAssignment: {
+        // ExportAssignment covers `export default <expr>` (isExportEquals === false)
+        // as well as `export = <expr>` (isExportEquals === true, CommonJS style).
+        // We register 'default' for both to ensure the barrel tracer can settle here.
+        spec.declaredLocalExports.add('default');
+        break;
+      }
     }
 
     ts.forEachChild(node, child => this.harvestExportSignatures(child, spec));