pkg-scaffold 2.3.0 → 3.0.0

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,131 @@
+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) {
+    // Challenge #16: Ignore built-in Node.js modules (fs, path, etc.)
+    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);
+
+    // 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;
+  }
+}

package/src/resolution/WorkSpaceGraph.js

@@ -0,0 +1,171 @@
+import fs from 'fs/promises';
+import path from 'path';
+// Native sub-directory crawling removed as it's not in fs/promises in older node, but we use readdir anyway.
+
+/**
+ * Monorepo Cross-Linking Topology Manager
+ * Maps sub-package structural boundaries across pnpm, Yarn, or npm workspaces.
+ */
+export class WorkspaceGraph {
+  constructor(context) {
+    this.context = context;
+    this.packageManifests = new Map(); // Package Name -> { manifestPath, rootDirectory, entryPoints[] }
+    this.workspacePackageNames = new Set();
+  }
+
+  /**
+   * Checks the environment layout to discover and map local workspace packages.
+   */
+  async initializeWorkspaceMesh() {
+    const rootPackageJsonPath = path.join(this.context.cwd, 'package.json');
+    const pnpmWorkspacePath = path.join(this.context.cwd, 'pnpm-workspace.yaml');
+    
+    let workspaceGlobs = [];
+
+    // Protocol A: Check for pnpm workspace configurations
+    try {
+      const yaml = await fs.readFile(pnpmWorkspacePath, 'utf8');
+      const lines = yaml.split('\n');
+      let insidePackagesBlock = false;
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('packages:')) {
+          insidePackagesBlock = true;
+          continue;
+        }
+        if (insidePackagesBlock && trimmed.startsWith('-')) {
+          const pattern = trimmed.replace(/^-|['"]/g, '').trim();
+          workspaceGlobs.push(pattern);
+        }
+      }
+    } catch {
+      // pnpm structure absent; check package.json workspace array paths instead
+    }
+
+    // Protocol B: Check for Yarn/npm workspaces array inside the root package.json
+    if (workspaceGlobs.length === 0) {
+      try {
+        const pkgText = await fs.readFile(rootPackageJsonPath, 'utf8');
+        const pkg = JSON.parse(pkgText);
+        if (pkg.workspaces) {
+          workspaceGlobs = Array.isArray(pkg.workspaces) ? pkg.workspaces : (pkg.workspaces.packages || []);
+        }
+      } catch {
+        return; // Workspace mesh maps skipped for single-package targets
+      }
+    }
+
+    // Crawl target glob configurations to locate workspace packages
+    for (const pattern of workspaceGlobs) {
+      await this.locatePackagesViaPattern(pattern);
+    }
+  }
+
+  async locatePackagesViaPattern(globPattern) {
+    // Normalizes wildcards down into base query directories
+    const standardizedPattern = globPattern.replace(/\\/g, '/');
+    const baseDir = standardizedPattern.split('/*')[0];
+    const absoluteSearchPath = path.resolve(this.context.cwd, baseDir);
+
+    try {
+      const contents = await fs.readdir(absoluteSearchPath, { withFileTypes: true });
+      
+      for (const entity of contents) {
+        if (!entity.isDirectory()) continue;
+        
+        const subPackageDir = path.join(absoluteSearchPath, entity.name);
+        const manifestFile = path.join(subPackageDir, 'package.json');
+        
+        try {
+          const data = await fs.readFile(manifestFile, 'utf8');
+          const pkg = JSON.parse(data);
+          
+          if (pkg.name) {
+            const entryPoints = this.calculatePackageExportsEntries(pkg, subPackageDir);
+            
+            this.packageManifests.set(pkg.name, {
+              packageName: pkg.name,
+              rootDirectory: subPackageDir,
+              manifestPath: manifestFile,
+              entryPoints
+            });
+
+            this.workspacePackageNames.add(pkg.name);
+          }
+        } catch {
+          // package.json parsing failed; ignore invalid directory roots
+        }
+      }
+    } catch {
+      // Unreadable target directories; pass tracking
+    }
+  }
+
+  /**
+   * Tracks package entry points by evaluating standard fields and main/exports configurations.
+   */
+  calculatePackageExportsEntries(pkg, pkgDir) {
+    const entries = new Set();
+
+    // Trace traditional entry fields
+    if (pkg.main) entries.add(path.resolve(pkgDir, pkg.main));
+    if (pkg.module) entries.add(path.resolve(pkgDir, pkg.module));
+    if (pkg.browser) entries.add(path.resolve(pkgDir, pkg.browser));
+    if (pkg.types) entries.add(path.resolve(pkgDir, pkg.types));
+
+    // Handle deep nested conditional exports matrices block parameters
+    if (pkg.exports) {
+      this.recursivelyUnwindExports(pkg.exports, pkgDir, entries);
+    }
+
+    // Default file index fallback configurations
+    if (entries.size === 0) {
+      entries.add(path.resolve(pkgDir, 'index.js'));
+      entries.add(path.resolve(pkgDir, 'index.ts'));
+    }
+
+    return Array.from(entries);
+  }
+
+  recursivelyUnwindExports(exportsValue, pkgDir, collected) {
+    if (typeof exportsValue === 'string') {
+      if (exportsValue.startsWith('.')) {
+        collected.add(path.resolve(pkgDir, exportsValue));
+      }
+    } else if (typeof exportsValue === 'object' && exportsValue !== null) {
+      for (const val of Object.values(exportsValue)) {
+        this.recursivelyUnwindExports(val, pkgDir, collected);
+      }
+    }
+  }
+
+  /**
+   * Checks if an import specifier matches a package registered in our workspace mesh.
+   */
+  isLocalWorkspaceSpecifier(specifier) {
+    if (this.workspacePackageNames.has(specifier)) return true;
+    
+    // Catch sub-path imports from monorepos (e.g., '@workspace/shared/utils')
+    for (const registeredPkgName of this.workspacePackageNames) {
+      if (specifier.startsWith(`${registeredPkgName}/`)) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Maps a workspace package specifier to its local absolute package root location on disk.
+   */
+  getWorkspacePackageMatch(specifier) {
+    if (this.packageManifests.has(specifier)) {
+      return this.packageManifests.get(specifier);
+    }
+
+    for (const [name, metadata] of this.packageManifests.entries()) {
+      if (specifier.startsWith(`${name}/`)) {
+        return metadata;
+      }
+    }
+    return null;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ESNext"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "./dist",
+    "rootDir": "./",
+    "allowJs": true,
+    "checkJs": false,
+    "declaration": true,
+    "emitDeclarationOnly": false
+  },
+  "include": [
+    "bin/**/*",
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    ".scaffold-cache"
+  ]
+}