feat: fluent-gen type info extraction

[rafbcampos]

Part 1/2: TypeScript Type Extraction Engine for Fluent API Generation

Overview

This PR introduces @player-tools/fluent-gen, that will expose a code generation tool for @player-tools/fluent builders.

In this PR we bring type-info that contains a comprehensive TypeScript type analysis engine that extracts structured metadata from TypeScript interfaces, and part 2 will leverage that and add the gen where we'll expose the code generation and CLI.

Type Extraction System - Core Architecture

Type Analysis Strategies

• PrimitiveAnalyzer
• ArrayAnalyzer
• UnionAnalyzer
• IntersectionAnalyzer
• ObjectAnalyzer:
• ReferenceAnalyzer
• TupleAnalyzer

Resolution Strategies

• Local Declaration Strategy
• Import Resolution Strategy
• External Module Resolution

Utility Type Expanders

• PickExpander
• OmitExpander
• PartialExpander
• RequiredExpander
• RecordExpander
• NonNullableExpander

API Design

Primary API (Single Function)

import { extractTypescriptInterfaceInfo } from '@player-tools/fluent-gen';

const result = extractTypescriptInterfaceInfo({
  filePath: 'src/types/UserInterface.ts',
  interfaceName: 'EditableUser'
});

// Returns complete structural analysis:
interface ExtractResult {
  kind: 'non-terminal';
  type: 'object';
  name: string;                    // Interface name
  typeAsString: string;            // Complete interface text  
  properties: PropertyInfo[];      // Analyzed property tree
  filePath: string;               // Source location
  dependencies: Dependency[];      // External type dependencies
  documentation?: string;          // JSDoc comments
}

// Each property includes:
interface PropertyInfo {
  kind: 'terminal' | 'non-terminal';  // Expandability
  type: string;                       // Type category
  name: string;                       // Property name
  typeAsString: string;              // Original TypeScript
  isOptional?: boolean;              // Optional flag
  isArray?: boolean;                 // Array detection
  documentation?: string;            // JSDoc extraction
  properties?: PropertyInfo[];       // Nested properties
}

Extensibility

Strategy Registration (Plugin Architecture)

// Custom Type Analyzer
class GraphQLTypeAnalyzer implements TypeAnalysisStrategy {
  canHandle(typeNode: TypeNode): boolean {
    return this.isGraphQLType(typeNode);
  }

  analyze(args: AnalysisArgs): PropertyInfo | null {
    return this.extractGraphQLMetadata(args);
  }
}

// Custom Utility Type Expander
class MyCustomExpander extends UtilityTypeExpander {
   getTypeName(): string { return 'MyUtility'; }
   
  expand(args: ExpansionArgs): PropertyInfo | null {
    return this.processMyUtilityType(args);
  }
}

This PR establishes the foundation for next-generation Player-UI development with type-safe, auto-generated fluent APIs. The comprehensive architecture and extensive testing ensures this system will scale with our growing ecosystem.

[codecov]

Codecov Report

❌ Patch coverage is 87.53790% with 411 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (fluent@be58976). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
...luent-gen/src/type-info/analyzers/UnionAnalyzer.ts	48.92%	95 Missing ⚠️
...gen/src/type-info/utility-types/PartialExpander.ts	56.75%	48 Missing ⚠️
...en/src/type-info/utility-types/RequiredExpander.ts	56.75%	48 Missing ⚠️
...t-gen/src/type-info/analyzers/ReferenceAnalyzer.ts	79.65%	47 Missing ⚠️
...-info/analyzers/strategies/EnumAnalysisStrategy.ts	63.54%	35 Missing ⚠️
language/fluent-gen/src/type-info/index.ts	0.00%	32 Missing ⚠️
...en/src/type-info/resolvers/ExternalTypeResolver.ts	90.55%	17 Missing ⚠️
...o/resolvers/strategies/ImportResolutionStrategy.ts	90.00%	12 Missing ⚠️
...uent-gen/src/type-info/resolvers/SymbolResolver.ts	92.61%	11 Missing ⚠️
...-gen/src/type-info/resolvers/utils/TypeAnalyzer.ts	92.02%	10 Missing and 1 partial ⚠️
... and 13 more

Additional details and impacted files

@@            Coverage Diff            @@
##             fluent     #225   +/-   ##
=========================================
  Coverage          ?   74.89%           
=========================================
  Files             ?      163           
  Lines             ?    14621           
  Branches          ?     2136           
=========================================
  Hits              ?    10950           
  Misses            ?     3640           
  Partials          ?       31           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[rafbcampos]

#221