Parcel TypeScript Types Transformer

// This is a Parcel plugin - import and usage is handled by Parcel's plugin system
// Direct usage typically occurs through Parcel configuration or programmatic API
const TSTypesTransformer = require("@parcel/transformer-typescript-types");

import TSTypesTransformer from "@parcel/transformer-typescript-types";

// Parcel automatically loads and uses this transformer for TypeScript files
// when configured in .parcelrc or package.json

// Example .parcelrc configuration for declaration generation
{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.ts": ["@parcel/transformer-typescript-types"],
    "*.tsx": ["@parcel/transformer-typescript-types"]
  }
}

// Alternative package.json configuration
{
  "name": "my-package",
  "@parcel/transformer-typescript-types": {
    "validateTS": true,
    "isolatedModules": false
  },
  "targets": {
    "types": {
      "source": "src/index.ts",
      "distDir": "dist",
      "includeNodeModules": false
    }
  }
}

// Programmatic usage with Parcel API
import { Parcel } from '@parcel/core';

const bundler = new Parcel({
  entries: 'src/index.ts',
  defaultConfig: '@parcel/config-default',
  targets: {
    types: {
      distDir: 'types',
      includeNodeModules: false
    }
  }
});

const { bundleGraph } = await bundler.run();

/**
 * Main Parcel transformer instance for processing TypeScript files
 */
const TSTypesTransformer: {
  loadConfig(config: any, options: any): Promise<any>;
  transform(asset: any, config: any, options: any, logger: any): Promise<any[]>;
};

/**
 * Manages dependency graph between TypeScript modules
 */
class TSModuleGraph {
  constructor(mainModuleName: string);
  addModule(name: string, module: TSModule): void;
  getModule(name: string): TSModule | null;
  markUsed(module: TSModule, name: string, context: any): void;
  propagate(context: any): Map<string, TSModule>;
}

/**
 * Represents a single TypeScript module with imports, exports, and bindings
 */
class TSModule {
  constructor();
  addImport(local: string, specifier: string, imported: string): void;
  addExport(name: string, imported: string, specifier?: string): void;
  addLocal(name: string, node: any): void;
  getName(name: string): string;
  hasBinding(name: string): boolean;
}

/**
 * Collects module graph information from TypeScript AST
 */
function collect(
  moduleGraph: TSModuleGraph,
  context: any,
  sourceFile: any
): any;

/**
 * Performs tree-shaking and symbol renaming on TypeScript AST
 */
function shake(
  moduleGraph: TSModuleGraph,
  context: any,
  sourceFile: any
): any;

/**
 * Cross-version wrapper for creating import clauses
 */
function createImportClause(
  factory: any,
  isTypeOnly: boolean,
  name: any,
  namedBindings: any
): any;

/**
 * Cross-version wrapper for creating import declarations
 */
function createImportDeclaration(
  factory: any,
  modifiers: any,
  importClause: any,
  moduleSpecifier: any,
  assertClause: any
): any;

/**
 * Represents an import statement in a TypeScript module
 */
type Import = {
  specifier: string;  // Module path (e.g., './components', 'react')
  imported: string;   // Imported symbol name ('default', '*', or named export)
};

/**
 * Represents an export statement in a TypeScript module
 * Either a named export (possibly re-exported) or a wildcard export
 */
type Export = 
  | { 
      name: string;           // Export name in current module
      imported: string;       // Symbol name being exported
      specifier?: string;     // Re-export source module (optional)
    }
  | { 
      specifier: string;      // Wildcard export source (export * from 'module')
    };

/**
 * TypeScript transform context provided by the compiler
 * Contains factory methods and compilation state
 */
interface TransformContext {
  factory?: any;                              // TypeScript node factory (TS 4.0+)
  suspendLexicalEnvironment?(): void;         // Suspend lexical tracking
  resumeLexicalEnvironment?(): void;          // Resume lexical tracking
  getCompilerOptions(): any;                  // Get compiler configuration
  [key: string]: any;                         // Additional context properties
}

/**
 * TypeScript AST node types commonly used by the transformer
 */
interface TypeScriptASTNodes {
  SourceFile: any;                           // Root AST node for a TypeScript file
  ImportDeclaration: any;                    // import statement
  ExportDeclaration: any;                    // export statement
  ImportClause: any;                         // import clause with bindings
  ImportSpecifier: any;                      // named import specifier
  ModuleDeclaration: any;                    // module or namespace declaration
  FunctionDeclaration: any;                  // function declaration
  ClassDeclaration: any;                     // class declaration
  InterfaceDeclaration: any;                 // interface declaration
  TypeAliasDeclaration: any;                 // type alias declaration
  EnumDeclaration: any;                      // enum declaration
  VariableStatement: any;                    // variable statement (const, let, var)
  ImportTypeNode: any;                       // import() type node
  QualifiedName: any;                        // qualified name (namespace.Type)
  Identifier: any;                           // identifier node
}

/**
 * Diagnostic information for TypeScript compilation errors
 */
interface TypeScriptDiagnostic {
  messageText: string | any;                 // Error message or message chain
  file?: any;                                // Source file with error
  start?: number;                            // Error start position
  length?: number;                           // Error length
  source?: string;                           // Source code text
}