entkapp 4.1.0

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,138 @@
+import fs from 'fs/promises';
+import path from 'path';
+import crypto from 'crypto';
+
+/**
+ * Transactional File System Operations Supervisor
+ * Guarantees atomicity across multi-file transformations by tracking rolling backups.
+ */
+export class TransactionManager {
+  constructor(context) {
+    this.context = context;
+    // FIX: Ensure context.cwd is always defined, fallback to process.cwd()
+    const cwd = context?.cwd || process.cwd();
+    this.backupDirectory = path.join(cwd, '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 = crypto.createHash('sha256').update(filePath).digest('hex');
+      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 = crypto.createHash('sha256').update(filePath).digest('hex');
+    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') {
+          try {
+            const originalContent = await fs.readFile(record.backupLocation, 'utf8');
+            await fs.writeFile(record.targetFile, originalContent, 'utf8');
+            await fs.unlink(record.backupLocation).catch(() => {});
+          } catch (e) {
+            console.warn(`[Transaction] Rollback failed for ${record.targetFile}: ${e.message}`);
+          }
+        }
+      }
+    } 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/CircularDetector.js

@@ -0,0 +1,91 @@
+export class CircularDetector {
+  constructor(context) {
+    this.context = context;
+    this.cycles = [];
+  }
+
+  detectCycles(graph, context = null) {
+    if (context) this.context = context;
+    this.cwd = context?.cwd || this.context?.cwd || process.cwd();
+    this.cycles = [];
+    
+    let index = 0;
+    const stack = [];
+    const indices = new Map();
+    const lowlink = new Map();
+    const onStack = new Set();
+
+    const strongconnect = (v) => {
+      indices.set(v, index);
+      lowlink.set(v, index);
+      index++;
+      stack.push(v);
+      onStack.add(v);
+
+      const node = graph.get(v);
+      if (node && node.outgoingEdges) {
+        for (const w of node.outgoingEdges) {
+          if (!indices.has(w)) {
+            strongconnect(w);
+            lowlink.set(v, Math.min(lowlink.get(v), lowlink.get(w)));
+          } else if (onStack.has(w)) {
+            lowlink.set(v, Math.min(lowlink.get(v), indices.get(w)));
+          }
+        }
+      }
+
+      if (lowlink.get(v) === indices.get(v)) {
+        const component = [];
+        let w;
+        do {
+          w = stack.pop();
+          onStack.delete(w);
+          component.push(w);
+        } while (w !== v);
+
+        if (component.length > 1) {
+          this.cycles.push(component.reverse());
+        } else {
+          const node = graph.get(v);
+          if (node && node.outgoingEdges && node.outgoingEdges.has(v)) {
+            this.cycles.push([v]);
+          }
+        }
+      }
+    };
+
+    for (const v of graph.keys()) {
+      if (!indices.has(v)) {
+        strongconnect(v);
+      }
+    }
+
+    return this.cycles;
+  }
+
+  formatCycles() {
+    return this.cycles.map(cycle => {
+      const paths = cycle.map(p => {
+        let rel = p.replace(this.context.cwd, '').replace(/^\//, '');
+        if (rel.includes(':\\')) rel = rel.split(':\\')[1] || rel;
+        return rel;
+      });
+      if (cycle.length === 1) return `${paths[0]} -> (self-loop)`;
+      return paths.join(' -> ') + ' -> ' + paths[0];
+    });
+  }
+
+  getCycleDetails() {
+    return this.cycles.map((cycle, idx) => ({
+      cycleId: idx + 1,
+      files: cycle.map(p => {
+        let rel = p.replace(this.context.cwd, '').replace(/^\//, '');
+        if (rel.includes(':\\')) rel = rel.split(':\\')[1] || rel;
+        return rel;
+      }),
+      length: cycle.length,
+      isSelfLoop: cycle.length === 1
+    }));
+  }
+}
+export default CircularDetector;

package/src/resolution/ConfigLoader.js

@@ -0,0 +1,87 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { pathToFileURL } from 'url';
+
+/**
+ * Loads and parses entkapp configuration files.
+ * Supports scaffold.config.js, .scaffoldrc.json, and .scaffoldrc.
+ */
+export class ConfigLoader {
+  constructor(context) {
+    this.context = context;
+  }
+
+  async loadConfig(projectRoot) {
+    const searchPaths = [
+      'entkapp.json',
+      'entkapp.jsonc',
+      '.entkapp.json',
+      '.entkapp.jsonc',
+      'entkapp.js',
+      'entkapp.ts',
+      'entkapp/config.json',
+      'scaffold.config.js',
+      'scaffold.config.mjs',
+      '.scaffoldrc.json',
+      '.scaffoldrc'
+    ];
+
+    let config = this.getDefaultConfig();
+
+    // Try package.json first
+    try {
+      const pkgPath = path.join(projectRoot, 'package.json');
+      const pkgContent = await fs.readFile(pkgPath, 'utf8');
+      const pkg = JSON.parse(pkgContent);
+      if (pkg['entkapp']) {
+        Object.assign(config, pkg['entkapp']);
+      }
+    } catch (e) {
+      // ignore
+    }
+
+    for (const fileName of searchPaths) {
+      const fullPath = path.join(projectRoot, fileName);
+      try {
+        await fs.access(fullPath);
+        
+        if (fileName.endsWith('.js') || fileName.endsWith('.mjs') || fileName.endsWith('.ts')) {
+          const module = await import(pathToFileURL(fullPath).href);
+          Object.assign(config, module.default || module);
+          break;
+        } else {
+          const content = await fs.readFile(fullPath, 'utf8');
+          // Very basic JSONC parsing (strip comments)
+          const stripped = content.replace(/\/\*[\s\S]*?\*\/|\/\/.*/g, '');
+          Object.assign(config, JSON.parse(stripped));
+          break;
+        }
+      } catch (e) {
+        continue;
+      }
+    }
+
+    return config;
+  }
+
+  getDefaultConfig() {
+    return {
+      entryPoints: ['src/index.ts', 'index.js', 'src/index.js', 'src/main.ts', 'src/main.js'],
+      exclude: [
+        'node_modules/**',
+        'dist/**',
+        'build/**',
+        '**/*.test.ts',
+        '**/*.spec.ts',
+        '**/*.test.js',
+        '**/*.spec.js'
+      ],
+      plugins: [],
+      rules: {
+        'no-unused-exports': 'error',
+        'no-unused-vars': 'warn',
+        'no-dead-code': 'error'
+      }
+    };
+  }
+}

package/src/resolution/DepencyResolver.js

@@ -0,0 +1,133 @@
+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 prioritized: TS then JS
+      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.
+   * Handles the "trap" where .ts files import .js files that should resolve to .ts.
+   */
+  resolveModulePath(containingFile, importSpecifier) {
+    if (importSpecifier.startsWith('node:') || [
+      'assert', 'async_hooks', 'buffer', 'child_process', 'cluster', 'console', 'constants',
+      'crypto', 'dgram', 'dns', 'domain', 'events', 'fs', 'fs/promises', 'http', 'http2',
+      'https', 'inspector', 'module', 'net', 'os', 'path', 'perf_hooks', 'process',
+      'punycode', 'querystring', 'readline', 'repl', 'stream', 'string_decoder',
+      'timers', 'tls', 'trace_events', 'tty', 'url', 'util', 'v8', 'vm', 'worker_threads', 'zlib'
+    ].includes(importSpecifier)) {
+      return null;
+    }
+
+    const containingDir = path.dirname(containingFile);
+
+    // --- NEW: Fix for JS-in-TS import trap ---
+    // If we are in a TS file and importing something ending in .js, 
+    // we should try to resolve the .ts version first.
+    let effectiveSpecifier = importSpecifier;
+    const isTsFile = /\.(ts|tsx|mts|cts)$/.test(containingFile);
+    if (isTsFile && importSpecifier.endsWith('.js')) {
+        // Try replacing .js with .ts
+        const tsSpecifier = importSpecifier.replace(/\.js$/, '.ts');
+        try {
+            const resolvedTs = this.nativeResolver(containingDir, tsSpecifier);
+            if (this.isAbsoluteInternalPath(resolvedTs)) return resolvedTs;
+        } catch (e) {
+            // Fall back to original specifier if .ts version doesn't exist
+        }
+    }
+    // -----------------------------------------
+
+    // Rule A: Intercept and resolve local monorepo workspace cross-links
+    if (this.workspaceGraph.isLocalWorkspaceSpecifier(effectiveSpecifier)) {
+      const match = this.workspaceGraph.getWorkspacePackageMatch(effectiveSpecifier);
+      if (match) {
+        if (effectiveSpecifier === match.packageName) {
+          return match.entryPoints[0] || null;
+        }
+        
+        const subPathOffset = effectiveSpecifier.slice(match.packageName.length + 1);
+        try {
+          return this.nativeResolver(match.rootDirectory, `./${subPathOffset}`);
+        } catch {
+        }
+      }
+    }
+
+    // Rule B: Intercept and expand path mapping aliases (@/*)
+    const aliasedCandidates = this.pathMapper.resolveCandidatePaths(effectiveSpecifier);
+    if (aliasedCandidates.length > 0) {
+      for (const candidate of aliasedCandidates) {
+        try {
+          const resolvedPath = this.nativeResolver(containingDir, candidate);
+          if (this.isAbsoluteInternalPath(resolvedPath)) {
+            return resolvedPath;
+          }
+        } catch {
+        }
+      }
+    }
+
+    // Rule C: Standard file system lookups
+    try {
+      const resolvedPath = this.nativeResolver(containingDir, effectiveSpecifier);
+      if (this.isAbsoluteInternalPath(resolvedPath)) {
+        return resolvedPath;
+      }
+    } catch (err) {
+      if (this.context.verbose) {
+        console.debug(`[Resolution Trace Skip] Specifier unresolvable: ${effectiveSpecifier} inside ${containingFile}`);
+      }
+    }
+
+    return null;
+  }
+
+  isAbsoluteInternalPath(resolvedPath) {
+    if (!resolvedPath) return false;
+    const normalized = resolvedPath.replace(/\\/g, '/');
+    
+    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);
+  }
+
+  determineIntentProfile(filePath, declaredExportsManifest) {
+    const fileName = path.basename(filePath);
+    const isPublicContractFile = /(^index|^public\-api|^entry)\.(ts|js|tsx|jsx)$/i.test(fileName);
+    
+    if (isPublicContractFile) {
+      for (const [symbolKey, metadata] of declaredExportsManifest.entries()) {
+        metadata.isLibraryContract = true;
+      }
+      return 'LIBRARY_CONSUMPTION_TARGET';
+    }
+
+    return 'INTERNAL_CODEBASE_ELEMENT';
+  }
+}