pkg-scaffold 2.2.0 → 2.4.0

package/src/refractor/ImpactAnalyzer.js

@@ -0,0 +1,92 @@
+import path from 'path';
+import fs from 'fs/promises';
+
+/**
+ * Cross-Reference Dependency Matrix & Breakage Risk Auditor
+ * Traces dynamic runtime usage patterns to prevent code pruning from breaking downstream systems.
+ */
+export class ImpactAnalyzer {
+  constructor(context) {
+    this.context = context;
+    this.safetyOverlays = [/\.json$/, /\.json5$/, /\.html$/, /\.yaml$/, /\.yml$/];
+  }
+
+  /**
+   * Scans non-code assets and dynamic lookups to check if an unused export is needed elsewhere.
+   * @param {string} originFile - Absolute path of component housing target symbol
+   * @param {string} symbolName - Literal identifier being evaluated for deletion
+   * @param {Map} projectGraph - Full project structural graph representation
+   */
+  async verifyRefactorSafety(originFile, symbolName, projectGraph) {
+    // Avoid dropping generic single letter tokens or framework primitives
+    if (symbolName === 'default' || symbolName.length <= 2) {
+      return { isSafeToPrune: false, blockReason: 'PROTECTED_SYSTEM_CONTRACT_KEYWORD' };
+    }
+
+    // Rule 1: Check across all code files for loose string-based token references
+    for (const [filePath, fileNode] of projectGraph.entries()) {
+      if (filePath === originFile) continue;
+
+      // If the symbol name is explicitly referenced in an element lookup or template slice, flag it as risky
+      if (fileNode.rawStringReferences && fileNode.rawStringReferences.has(symbolName)) {
+        return {
+          isSafeToPrune: false,
+          blockReason: `LOOSE_STRING_ACCESS_MATCH_FOUND_IN: ${path.relative(this.context.cwd, filePath)}`
+        };
+      }
+
+      // Check member property chain lookups: customer.profile.billingAddress
+      if (fileNode.propertyAccessChains) {
+        for (const chain of fileNode.propertyAccessChains) {
+          if (chain.endsWith(`.${symbolName}`) || chain.includes(`.${symbolName}.`)) {
+            return {
+              isSafeToPrune: false,
+              blockReason: `DYNAMIC_PROPERTY_ACCESS_CHAIN_HIT: ${chain}`
+            };
+          }
+        }
+      }
+    }
+
+    // Rule 2: Crawl through external static manifests (JSON metadata, HTML routing templates, workflow files)
+    const configurations = await this.gatherMetadataFiles(this.context.cwd);
+    
+    for (const confPath of configurations) {
+      try {
+        const payload = await fs.readFile(confPath, 'utf8');
+        
+        // Match string references inside configuration boundaries
+        if (payload.includes(`"${symbolName}"`) || payload.includes(`'${symbolName}'`) || payload.includes(`data-${symbolName}`)) {
+          return {
+            isSafeToPrune: false,
+            blockReason: `METADATA_MANIFEST_DEPENDENCY_FOUND_IN: ${path.relative(this.context.cwd, confPath)}`
+          };
+        }
+      } catch {
+        // Read step error; skip unreadable descriptors
+      }
+    }
+
+    return { isSafeToPrune: true, blockReason: null };
+  }
+
+  async gatherMetadataFiles(dir, collected = []) {
+    try {
+      const entities = await fs.readdir(dir, { withFileTypes: true });
+      for (const ent of entities) {
+        const resolutionPath = path.join(dir, ent.name);
+        
+        if (ent.isDirectory()) {
+          if (ent.name === 'node_modules' || ent.name === '.git' || ent.name === '.scaffold-cache' || ent.name === 'dist') continue;
+          await this.gatherMetadataFiles(resolutionPath, collected);
+        } else if (ent.isFile()) {
+          const actsAsMetaAsset = this.safetyOverlays.some(regex => regex.test(ent.name));
+          if (actsAsMetaAsset) {
+            collected.push(resolutionPath);
+          }
+        }
+      }
+    } catch {}
+    return collected;
+  }
+}

package/src/refractor/SourceRewriter.js

@@ -0,0 +1,86 @@
+import ts from 'typescript';
+import fs from 'fs/promises';
+
+/**
+ * Format-Preserving Abstract Syntax Tree Source Mutation Engine
+ * Executes targeted updates using token position logic while preserving trivia (comments/JSDoc).
+ */
+export class SourceRewriter {
+  constructor(context) {
+    this.context = context;
+  }
+
+  /**
+   * Removes a specific named export symbol declaration block from code text.
+   * @param {string} filePath - Absolute path to on-disk code component
+   * @param {string} symbolName - Target export key to prune
+   * @param {Object} exportMeta - Mapped token offset indices (start/end offsets)
+   */
+  async stripNamedExportSignature(filePath, symbolName, exportMeta) {
+    const rawSource = await fs.readFile(filePath, 'utf8');
+    
+    // Case A: Token is grouped inside a multi-export destructured statement block: export { a, b, c };
+    if (exportMeta.type === 'named') {
+      const updatedText = this.pruneFromSharedExportClause(rawSource, symbolName, exportMeta);
+      if (updatedText) return updatedText;
+    }
+
+    // Case B: Isolated node removal. Calculate indices from start to end while preserving comments.
+    const startOffset = exportMeta.start;
+    const endOffset = exportMeta.end;
+
+    // Split source without dropping trailing line structural punctuation or text formatting configurations
+    const prefix = rawSource.slice(0, startOffset);
+    let suffix = rawSource.slice(endOffset);
+
+    // Clean up trailing commas or semicolons to prevent syntax errors
+    if (suffix.startsWith(';') || suffix.startsWith(',')) {
+      suffix = suffix.slice(1);
+    }
+
+    return prefix + suffix;
+  }
+
+  /**
+   * Handles selective pruning of export elements within inline groupings like `export { x, y as z }`.
+   */
+  pruneFromSharedExportClause(sourceText, symbolName, meta) {
+    // Find the enclosing export declaration node using structural boundaries
+    const sourceFile = ts.createSourceFile(
+      'temp.ts',
+      sourceText,
+      ts.ScriptTarget.Latest,
+      true
+    );
+
+    let targetText = null;
+
+    const findAndPrune = (node) => {
+      if (ts.isExportDeclaration(node) && node.exportClause && ts.isNamedExports(node.exportClause)) {
+        const start = node.getStart(sourceFile);
+        const end = node.getEnd();
+
+        // Check if the target node spans the exact offset coordinates of the dead symbol
+        if (meta.start >= start && meta.end <= end) {
+          const activeElements = node.exportClause.elements;
+          const keptSymbols = activeElements
+            .filter(el => el.name.text !== symbolName)
+            .map(el => el.getText(sourceFile));
+
+          if (keptSymbols.length === 0) {
+            // Drop the entire declaration block if no active exports remain inside it
+            targetText = sourceText.slice(0, start) + sourceText.slice(end);
+          } else {
+            // Rewrite the export group inline, preserving formatting and comments
+            const reconstructedClause = `export { ${keptSymbols.join(', ')} };`;
+            targetText = sourceText.slice(0, start) + reconstructedClause + sourceText.slice(end);
+          }
+        }
+      }
+      ts.forEachChild(node, findAndPrune);
+    };
+
+    findAndPrune(sourceFile);
+    return targetText;
+  }
+}

package/src/refractor/TransactionManager.js

@@ -0,0 +1,131 @@
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * Transactional File System Operations Supervisor
+ * Guarantees atomicity across multi-file transformations by tracking rolling backups.
+ */
+export class TransactionManager {
+  constructor(context) {
+    this.context = context;
+    this.backupDirectory = path.join(context.cacheDir, 'backups');
+    this.journal = [];
+    this.isLocked = false;
+  }
+
+  /**
+   * Begins a new transaction lifecycle loop, initializing isolation vectors.
+   */
+  async begin() {
+    if (this.isLocked) {
+      throw new Error('Transaction Manager concurrency fault: Another transaction is already staged.');
+    }
+    this.isLocked = true;
+    this.journal = [];
+    await fs.mkdir(this.backupDirectory, { recursive: true });
+  }
+
+  /**
+   * Stages a destructive file modification or creation sequence.
+   * @param {string} filePath - Absolute system file target location
+   * @param {string} nextContent - The completely rewritten proposed source structure
+   */
+  async stageWrite(filePath, nextContent) {
+    this.assertLock();
+    let originalContent = null;
+    let backupPath = null;
+    let operationType = 'UPDATE';
+
+    try {
+      await fs.access(filePath);
+      originalContent = await fs.readFile(filePath, 'utf8');
+      
+      const fileId = Buffer.from(filePath).toString('base64url');
+      backupPath = path.join(this.backupDirectory, `${fileId}.bak`);
+      await fs.writeFile(backupPath, originalContent, 'utf8');
+    } catch {
+      operationType = 'CREATE';
+    }
+
+    // Attempt target file mutation write directly to disk
+    await fs.writeFile(filePath, nextContent, 'utf8');
+
+    this.journal.push({
+      type: operationType,
+      targetFile: filePath,
+      backupLocation: backupPath
+    });
+  }
+
+  /**
+   * Stages an element deletion sequence safely.
+   * @param {string} filePath - Target component being evaluated as dead
+   */
+  async stageDeletion(filePath) {
+    this.assertLock();
+    
+    // Read previous state data for archiving before dropping linkage
+    const originalContent = await fs.readFile(filePath, 'utf8');
+    const fileId = Buffer.from(filePath).toString('base64url');
+    const backupPath = path.join(this.backupDirectory, `${fileId}.bak`);
+    
+    await fs.writeFile(backupPath, originalContent, 'utf8');
+    await fs.unlink(filePath);
+
+    this.journal.push({
+      type: 'DELETE',
+      targetFile: filePath,
+      backupLocation: backupPath
+    });
+  }
+
+  /**
+   * Finalizes the transaction sequence, cleaning up local transaction cache points.
+   */
+  async commit() {
+    this.assertLock();
+    try {
+      for (const record of this.journal) {
+        if (record.backupLocation) {
+          await fs.unlink(record.backupLocation).catch(() => {});
+        }
+      }
+    } finally {
+      this.releaseLock();
+    }
+  }
+
+  /**
+   * Reverts changes to their original states if any error or verification failure is flagged.
+   */
+  async rollback() {
+    this.assertLock();
+    try {
+      // Process journal logs in reverse execution order to preserve dependencies
+      for (let i = this.journal.length - 1; i >= 0; i--) {
+        const record = this.journal[i];
+        
+        if (record.type === 'CREATE') {
+          await fs.unlink(record.targetFile).catch(() => {});
+        } else if (record.type === 'UPDATE' || record.type === 'DELETE') {
+          const originalContent = await fs.readFile(record.backupLocation, 'utf8');
+          await fs.writeFile(record.targetFile, originalContent, 'utf8');
+          await fs.unlink(record.backupLocation).catch(() => {});
+        }
+      }
+    } finally {
+      this.releaseLock();
+    }
+  }
+
+  assertLock() {
+    if (!this.isLocked) {
+      throw new Error('Transaction Manager boundary violation: No active tracking block exists.');
+    }
+  }
+
+  releaseLock() {
+    this.isLocked = false;
+    this.journal = [];
+  }
+}

package/src/refractor/TypeIntegrity.js

@@ -0,0 +1,75 @@
+import ts from 'typescript';
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * Ambient Type Declaration (`.d.ts`) Alignment Supervisor
+ * Updates declaration mapping entries to keep compiler checks stable.
+ */
+export class TypeIntegrity {
+  constructor(context) {
+    this.context = context;
+  }
+
+  /**
+   * Re-evaluates ambient files to verify type alignment after optimization changes.
+   * @param {string} sourceFilePath - Absolute filename target context location
+   * @param {string} prunedSymbolName - Target variable token removed from active source graph
+   */
+  async synchronizeDeclarationFile(sourceFilePath, prunedSymbolName) {
+    const fileDirectory = path.dirname(sourceFilePath);
+    const baselineName = path.basename(sourceFilePath, path.extname(sourceFilePath));
+    
+    // Map standard ambient types build output combinations
+    const declarationTargets = [
+      path.join(fileDirectory, `${baselineName}.d.ts`),
+      path.join(this.context.cwd, 'dist', `${baselineName}.d.ts`),
+      path.join(this.context.cwd, 'types', `${baselineName}.d.ts`)
+    ];
+
+    for (const dtsPath of declarationTargets) {
+      try {
+        await fs.access(dtsPath);
+        const code = await fs.readFile(dtsPath, 'utf8');
+        
+        const sourceFile = ts.createSourceFile(
+          dtsPath,
+          code,
+          ts.ScriptTarget.Latest,
+          true,
+          ts.ScriptKind.TS
+        );
+
+        const replacementIntervals = [];
+        this.inspectDtsNodes(sourceFile, prunedSymbolName, replacementIntervals);
+
+        if (replacementIntervals.length > 0) {
+          let updatedDtsText = code;
+          // Apply substring text deletions from back to front to keep offset indexes accurate
+          replacementIntervals.sort((a, b) => b.start - a.start);
+          
+          for (const interval of replacementIntervals) {
+            updatedDtsText = updatedDtsText.slice(0, interval.start) + updatedDtsText.slice(interval.end);
+          }
+
+          await fs.writeFile(dtsPath, updatedDtsText, 'utf8');
+        }
+      } catch {
+        // Declaration file variation target absent; proceed to fallback check routes
+      }
+    }
+  }
+
+  inspectDtsNodes(node, matchSymbol, intervals) {
+    if (!node) return;
+
+    // Match type mutations inside ambient structural parameters
+    if (ts.isExportSpecifier(node) && node.name.text === matchSymbol) {
+      intervals.push({ start: node.getStart(), end: node.getEnd() });
+    } else if ((ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node) || ts.isClassDeclaration(node) || ts.isFunctionDeclaration(node)) && node.name && node.name.text === matchSymbol) {
+      intervals.push({ start: node.getStart(), end: node.getEnd() });
+    }
+
+    ts.forEachChild(node, child => this.inspectDtsNodes(child, matchSymbol, intervals));
+  }
+}

package/src/resolution/DepencyResolver.js

@@ -0,0 +1,120 @@
+import resolve from 'enhanced-resolve';
+import path from 'path';
+
+/**
+ * Industrial-Strength Module Resolution Supervisor
+ * Integrates path mapping and workspace topologies using enhanced-resolve.
+ */
+export class DependencyResolver {
+  constructor(context, pathMapper, workspaceGraph) {
+    this.context = context;
+    this.pathMapper = pathMapper;
+    this.workspaceGraph = workspaceGraph;
+    
+    // Instantiate production-grade enhanced-resolve workspace parameters
+    this.nativeResolver = resolve.create.sync({
+      conditionNames: ['import', 'module', 'require', 'node', 'types'],
+      extensions: ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.json', '.vue'],
+      mainFields: ['module', 'main', 'types'],
+      exportsFields: ['exports'],
+      symlinks: true
+    });
+  }
+
+  /**
+   * Resolves a raw import string from a source file into an absolute file path.
+   * @param {string} containingFile - Absolute path of the file containing the import declaration
+   * @param {string} importSpecifier - Raw import target string (e.g., '../components/Button' or '@utils/math')
+   * @returns {string|null} Resolved absolute file path location on disk, or null if external/third-party node_module
+   */
+  resolveModulePath(containingFile, importSpecifier) {
+    const containingDir = path.dirname(containingFile);
+
+    // Rule A: Intercept and resolve local monorepo workspace cross-links
+    if (this.workspaceGraph.isLocalWorkspaceSpecifier(importSpecifier)) {
+      const match = this.workspaceGraph.getWorkspacePackageMatch(importSpecifier);
+      if (match) {
+        if (importSpecifier === match.packageName) {
+          // Point directly to the target package's configured index entry file
+          return match.entryPoints[0] || null;
+        }
+        
+        // Handle deep sub-path monorepo target imports
+        const subPathOffset = importSpecifier.slice(match.packageName.length + 1);
+        try {
+          return this.nativeResolver(match.rootDirectory, `./${subPathOffset}`);
+        } catch {
+          // Fall back to scanning the package root directly if the sub-path lookup fails
+        }
+      }
+    }
+
+    // Rule B: Intercept and expand path mapping aliases (@/*)
+    const aliasedCandidates = this.pathMapper.resolveCandidatePaths(importSpecifier);
+    if (aliasedCandidates.length > 0) {
+      for (const candidate of aliasedCandidates) {
+        try {
+          const resolvedPath = this.nativeResolver(containingDir, candidate);
+          if (this.isAbsoluteInternalPath(resolvedPath)) {
+            return resolvedPath;
+          }
+        } catch {
+          // Candidate target path absent; try the next fallback pattern entry
+        }
+      }
+    }
+
+    // Rule C: Standard file system lookups for standard files or package assets
+    try {
+      const resolvedPath = this.nativeResolver(containingDir, importSpecifier);
+      if (this.isAbsoluteInternalPath(resolvedPath)) {
+        return resolvedPath;
+      }
+    } catch (err) {
+      if (this.context.verbose) {
+        // Output trace logs for unresolvable dependencies during deep code investigations
+        console.debug(`[Resolution Trace Skip] Specifier unresolvable from context: ${importSpecifier} inside ${containingFile}`);
+      }
+    }
+
+    return null; // Target is an external node_module dependency or an unresolvable asset
+  }
+
+  /**
+   * Ensures our tracking focus stays locked onto internal codebase components, bypassing third-party node_modules.
+   */
+  isAbsoluteInternalPath(resolvedPath) {
+    if (!resolvedPath) return false;
+    const normalized = resolvedPath.replace(/\\/g, '/');
+    
+    // Ignore external node_modules blocks, but preserve local monorepo packages that live inside symlinked node_modules
+    if (normalized.includes('/node_modules/')) {
+      for (const [name, meta] of this.workspaceGraph.packageManifests.entries()) {
+        if (normalized.startsWith(meta.rootDirectory.replace(/\\/g, '/'))) {
+          return true;
+        }
+      }
+      return false;
+    }
+    
+    return path.isAbsolute(resolvedPath);
+  }
+
+  /**
+   * Challenge #17 Intent Detection. Evaluates if an export serves as a consumer contract distribution node.
+   */
+  determineIntentProfile(filePath, declaredExportsManifest) {
+    const fileName = path.basename(filePath);
+    const isPublicContractFile = /(^index|^public\-api|^entry)\.(ts|js|tsx|jsx)$/i.test(fileName);
+    
+    // If the file is a primary bundle entry point, flag its exports as protected public contracts
+    if (isPublicContractFile) {
+      for (const [symbolKey, metadata] of declaredExportsManifest.entries()) {
+        metadata.isLibraryContract = true;
+      }
+      return 'LIBRARY_CONSUMPTION_TARGET';
+    }
+
+    return 'INTERNAL_CODEBASE_ELEMENT';
+  }
+}

package/src/resolution/PathMapper.js

@@ -0,0 +1,115 @@
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * Advanced TSConfig / JSConfig Compilation Path Alias Mapper
+ * Resolves deeply nested route mappings, wildcards, and base URL overrides.
+ */
+export class PathMapper {
+  constructor(context) {
+    this.context = context;
+    this.baseUrl = '.';
+    this.absoluteBaseUrl = context.cwd;
+    this.mappings = []; // Collection of { prefix, suffix, targets[] }
+  }
+
+  /**
+   * Reads, cleans, and indexes custom alias entries from tsconfig.json files.
+   * @param {string} tsconfigFilename - Target designator (typically tsconfig.json)
+   */
+  async loadMappings(tsconfigFilename = 'tsconfig.json') {
+    const configPath = path.resolve(this.context.cwd, tsconfigFilename);
+    
+    try {
+      await fs.access(configPath);
+      const rawText = await fs.readFile(configPath, 'utf8');
+      
+      // Strip inline single-line and block comments before parsing
+      const jsonCleanText = rawText.replace(/\/\*[\s\S]*?\*\/|([^\\:]|^)\/\/.*$/gm, '$1');
+      const tsconfig = JSON.parse(jsonCleanText);
+
+      if (!tsconfig.compilerOptions) return;
+
+      const opts = tsconfig.compilerOptions;
+      if (opts.baseUrl) {
+        this.baseUrl = opts.baseUrl;
+        this.absoluteBaseUrl = path.resolve(this.context.cwd, this.baseUrl);
+      }
+
+      if (opts.paths) {
+        for (const [aliasPattern, targetArrays] of Object.entries(opts.paths)) {
+          this.registerPatternRule(aliasPattern, targetArrays);
+        }
+      }
+    } catch (error) {
+      if (this.context.verbose) {
+        console.warn(`⚠️ [PathMapper Override] Proceeding without custom path configurations. Source: ${error.message}`);
+      }
+    }
+  }
+
+  /**
+   * Registers structural lookup parameters for alias strings.
+   */
+  registerPatternRule(pattern, targets) {
+    const wildcardIndex = pattern.indexOf('*');
+
+    if (wildcardIndex === -1) {
+      this.mappings.push({
+        isExact: true,
+        pattern,
+        targets: targets.map(t => path.normalize(t))
+      });
+      return;
+    }
+
+    const prefix = pattern.slice(0, wildcardIndex);
+    const suffix = pattern.slice(wildcardIndex + 1);
+
+    this.mappings.push({
+      isExact: false,
+      prefix,
+      suffix,
+      targets: targets.map(t => path.normalize(t))
+    });
+  }
+
+  /**
+   * Resolves a raw import specifier against mapped path patterns.
+   * @param {string} specifier - Raw text from import declaration (e.g., '@ui/button')
+   * @returns {Array<string>} Candidates of absolute filesystem paths to try resolving
+   */
+  resolveCandidatePaths(specifier) {
+    const matchingCandidates = [];
+
+    for (const rule of this.mappings) {
+      if (rule.isExact) {
+        if (specifier === rule.pattern) {
+          rule.targets.forEach(target => {
+            matchingCandidates.push(path.resolve(this.absoluteBaseUrl, target));
+          });
+        }
+      } else {
+        // Evaluate wildcard pattern matches
+        if (specifier.startsWith(rule.prefix) && specifier.endsWith(rule.suffix)) {
+          const extractedWildcardContent = specifier.slice(
+            rule.prefix.length,
+            specifier.length - rule.suffix.length
+          );
+
+          rule.targets.forEach(targetTemplate => {
+            const interpolatedTarget = targetTemplate.replace('*', extractedWildcardContent);
+            matchingCandidates.push(path.resolve(this.absoluteBaseUrl, interpolatedTarget));
+          });
+        }
+      }
+    }
+
+    // Fall back to direct lookup relative to the base URL
+    if (!specifier.startsWith('.') && !path.isAbsolute(specifier)) {
+      matchingCandidates.push(path.resolve(this.absoluteBaseUrl, specifier));
+    }
+
+    return matchingCandidates;
+  }
+}