polen 0.10.0-next.11 → 0.10.0-next.12

package/build/lib/graphql-document/schema-integration-example.js

@@ -0,0 +1,297 @@
+/**
+ * Example usage of Schema Integration (Layer 2)
+ *
+ * Demonstrates how the schema integration layer resolves GraphQL identifiers
+ * against actual schemas, extracts documentation, and generates reference URLs.
+ */
+import { buildSchema } from 'graphql';
+import { analyzeWithSchema, createPolenSchemaResolver } from "./schema-integration.js";
+// Example schema - typical GraphQL API
+const pokemonSchema = buildSchema(`
+  """
+  A Pokémon character
+  """
+  type Pokemon {
+    """
+    The Pokémon's unique identifier
+    """
+    id: ID!
+    
+    """
+    The Pokémon's name
+    """
+    name: String!
+    
+    """
+    The Pokémon's type (e.g., Electric, Fire, Water)
+    """
+    type: String!
+    
+    """
+    The Pokémon's abilities
+    """
+    abilities(
+      """
+      Maximum number of abilities to return
+      """
+      first: Int = 5
+    ): [Ability!]!
+    
+    """
+    @deprecated Use evolutionChain instead
+    """
+    evolutions: [Pokemon!] @deprecated(reason: "Use evolutionChain instead")
+  }
+
+  """
+  A special ability that Pokémon can have
+  """
+  type Ability {
+    id: ID!
+    name: String!
+    description: String
+    isHidden: Boolean!
+  }
+
+  type Query {
+    """
+    Get a Pokémon by ID
+    """
+    pokemon(id: ID!): Pokemon
+    
+    """
+    Search for Pokémon by name
+    """
+    searchPokemon(query: String!): [Pokemon!]!
+  }
+`);
+// Example GraphQL query with various constructs
+const exampleQuery = `
+  query GetPokemonDetails($pokemonId: ID!, $abilityLimit: Int = 3) {
+    pokemon(id: $pokemonId) {
+      id
+      name
+      type
+      abilities(first: $abilityLimit) {
+        name
+        description
+        isHidden
+      }
+      evolutions  # This field is deprecated
+      invalidField  # This field doesn't exist
+    }
+  }
+`;
+/**
+ * Demonstrate basic schema resolution
+ */
+export const demonstrateSchemaResolution = () => {
+    console.log('🔗 Schema Integration Demo\n');
+    const resolver = createPolenSchemaResolver(pokemonSchema);
+    // Example identifiers (normally extracted from AST)
+    const testIdentifiers = [
+        {
+            name: 'Pokemon',
+            kind: 'Type',
+            position: { start: 50, end: 57, line: 3, column: 5 },
+            schemaPath: ['Pokemon'],
+            context: { selectionPath: [] },
+        },
+        {
+            name: 'name',
+            kind: 'Field',
+            position: { start: 75, end: 79, line: 4, column: 7 },
+            parentType: 'Pokemon',
+            schemaPath: ['Pokemon', 'name'],
+            context: { selectionPath: ['pokemon', 'name'] },
+        },
+        {
+            name: 'evolutions',
+            kind: 'Field',
+            position: { start: 150, end: 160, line: 9, column: 7 },
+            parentType: 'Pokemon',
+            schemaPath: ['Pokemon', 'evolutions'],
+            context: { selectionPath: ['pokemon', 'evolutions'] },
+        },
+        {
+            name: 'first',
+            kind: 'Argument',
+            position: { start: 120, end: 125, line: 6, column: 20 },
+            parentType: 'Pokemon',
+            schemaPath: ['Pokemon', 'abilities', 'first'],
+            context: { selectionPath: ['pokemon', 'abilities'] },
+        },
+    ];
+    console.log('📋 Identifier Resolutions:\n');
+    for (const identifier of testIdentifiers) {
+        const resolution = resolver.resolveIdentifier(identifier);
+        if (!resolution)
+            continue;
+        console.log(`🏷️  ${identifier.kind}: ${identifier.name}`);
+        console.log(`   ✅ Exists: ${resolution.exists}`);
+        console.log(`   🔗 URL: ${resolution.referenceUrl}`);
+        if (resolution.documentation) {
+            console.log(`   📝 Type: ${resolution.documentation.typeInfo}`);
+            if (resolution.documentation.description) {
+                console.log(`   💬 Description: ${resolution.documentation.description}`);
+            }
+            if (resolution.documentation.defaultValue) {
+                console.log(`   🎯 Default: ${resolution.documentation.defaultValue}`);
+            }
+        }
+        if (resolution.deprecated) {
+            console.log(`   ⚠️  DEPRECATED: ${resolution.deprecated.reason}`);
+        }
+        console.log();
+    }
+};
+/**
+ * Demonstrate full schema-aware analysis
+ */
+export const demonstrateSchemaAwareAnalysis = () => {
+    console.log('🔍 Schema-Aware Analysis\n');
+    const result = analyzeWithSchema(exampleQuery, pokemonSchema);
+    console.log(`📊 Analysis Summary:`);
+    console.log(`   • Valid GraphQL: ${result.analysis.isValid}`);
+    console.log(`   • Total identifiers: ${result.analysis.identifiers.all.length}`);
+    console.log(`   • Schema resolutions: ${result.resolutions.size}`);
+    console.log(`   • Schema errors: ${result.schemaErrors.length}\n`);
+    // Show validation errors
+    if (result.schemaErrors.length > 0) {
+        console.log('🚨 Schema Validation Issues:\n');
+        for (const error of result.schemaErrors) {
+            const emoji = error.severity === 'error' ? '❌' : '⚠️';
+            const pos = `${error.identifier.position.line}:${error.identifier.position.column}`;
+            console.log(`   ${emoji} ${error.message} @ ${pos}`);
+        }
+        console.log();
+    }
+    // Show successful resolutions with hyperlink potential
+    console.log('🔗 Generated Hyperlinks:\n');
+    let linkCount = 0;
+    for (const [key, resolution] of result.resolutions) {
+        if (resolution.exists && linkCount < 8) { // Show first 8 successful resolutions
+            const identifier = result.analysis.identifiers.all.find(id => key.startsWith(`${id.position.start}-${id.name}-${id.kind}`));
+            if (identifier) {
+                const pos = `${identifier.position.line}:${identifier.position.column}`;
+                console.log(`   📍 ${identifier.name} (${identifier.kind}) → ${resolution.referenceUrl}`);
+                if (resolution.documentation?.description) {
+                    const shortDesc = resolution.documentation.description.length > 50
+                        ? resolution.documentation.description.substring(0, 50) + '...'
+                        : resolution.documentation.description;
+                    console.log(`      💬 "${shortDesc}"`);
+                }
+                linkCount++;
+            }
+        }
+    }
+};
+/**
+ * Demonstrate tooltip data extraction
+ */
+export const demonstrateTooltipData = () => {
+    console.log('\n💬 Tooltip Data Extraction\n');
+    const resolver = createPolenSchemaResolver(pokemonSchema);
+    // Simulate tooltip hover scenarios
+    const tooltipExamples = [
+        ['Pokemon'],
+        ['Pokemon', 'name'],
+        ['Pokemon', 'abilities'],
+        ['Pokemon', 'abilities', 'first'],
+        ['Ability', 'isHidden'],
+    ];
+    for (const schemaPath of tooltipExamples) {
+        const docs = resolver.getDocumentation(schemaPath);
+        if (docs) {
+            const pathStr = schemaPath.join(' → ');
+            console.log(`🏷️  ${pathStr}`);
+            console.log(`   📋 Type: ${docs.typeInfo}`);
+            if (docs.description) {
+                console.log(`   💬 Description: ${docs.description}`);
+            }
+            if (docs.defaultValue) {
+                console.log(`   🎯 Default: ${docs.defaultValue}`);
+            }
+            if (docs.deprecated) {
+                console.log(`   ⚠️  DEPRECATED: ${docs.deprecated.reason}`);
+            }
+            console.log();
+        }
+    }
+};
+/**
+ * Demonstrate URL generation customization
+ */
+export const demonstrateCustomURLGeneration = () => {
+    console.log('🛠️  Custom URL Generation\n');
+    // Different resolver configurations
+    const configurations = [
+        { name: 'Default', config: {} },
+        { name: 'Custom Base Path', config: { basePath: '/docs/api' } },
+        { name: 'No Fragments', config: { includeFragments: false } },
+        { name: 'Custom + No Fragments', config: { basePath: '/schema', includeFragments: false } },
+    ];
+    const testPaths = [
+        ['Pokemon'],
+        ['Pokemon', 'name'],
+        ['Pokemon', 'abilities', 'first'],
+    ];
+    for (const { name, config } of configurations) {
+        console.log(`📋 ${name}:`);
+        const resolver = createPolenSchemaResolver(pokemonSchema, config);
+        for (const path of testPaths) {
+            const url = resolver.generateReferenceLink(path);
+            console.log(`   ${path.join(' → ')} → ${url}`);
+        }
+        console.log();
+    }
+};
+/**
+ * Show integration with Polen's reference system
+ */
+export const demonstratePolenIntegration = () => {
+    console.log('🏗️  Polen Integration Preview\n');
+    // This demonstrates how the schema integration connects with Polen's existing systems
+    const result = analyzeWithSchema(exampleQuery, pokemonSchema, {
+        basePath: '/reference', // Polen's reference page base
+        includeFragments: true, // Enable field anchors
+    });
+    console.log('🔄 How this integrates with Polen:\n');
+    console.log('1. 📋 Schema Loading:');
+    console.log("   • Uses PROJECT_DATA.schema from Polen's build system");
+    console.log('   • Leverages existing schema processing pipeline');
+    console.log();
+    console.log('2. 🔗 Reference Links:');
+    console.log("   • Generates URLs matching Polen's /reference/* structure");
+    console.log('   • Works with existing TypeIndex and sidebar system');
+    console.log();
+    console.log('3. 💬 Documentation:');
+    console.log('   • Extracts descriptions for hover tooltips');
+    console.log('   • Provides type signatures for context');
+    console.log('   • Detects deprecation warnings');
+    console.log();
+    console.log('4. ✅ Validation:');
+    console.log('   • Build-time validation against actual schema');
+    console.log('   • Catches typos and invalid references');
+    console.log('   • Reports deprecation usage');
+    console.log();
+    // Show some example integrations
+    const validFields = Array.from(result.resolutions.values())
+        .filter(r => r.exists)
+        .slice(0, 3);
+    if (validFields.length > 0) {
+        console.log('📋 Example Reference Links:');
+        for (const resolution of validFields) {
+            console.log(`   • ${resolution.referenceUrl}`);
+        }
+    }
+};
+// Run examples if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    demonstrateSchemaResolution();
+    demonstrateSchemaAwareAnalysis();
+    demonstrateTooltipData();
+    demonstrateCustomURLGeneration();
+    demonstratePolenIntegration();
+}
+//# sourceMappingURL=schema-integration-example.js.map

package/build/lib/graphql-document/schema-integration-example.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-integration-example.js","sourceRoot":"","sources":["../../../src/lib/graphql-document/schema-integration-example.ts"],"names":[],"mappings":"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"}

package/build/lib/graphql-document/schema-integration.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Layer 2: Schema Integration
+ *
+ * Bridge between GraphQL analysis and Polen's schema system.
+ * Resolves identifiers against the actual schema, extracts documentation,
+ * and generates reference URLs for navigation.
+ */
+import { type GraphQLSchema, type GraphQLType } from 'graphql';
+import type { Identifier } from './types.ts';
+/**
+ * Documentation extracted from GraphQL schema
+ */
+export interface Documentation {
+    /** Description from schema SDL or introspection */
+    description?: string;
+    /** Type signature (e.g., "String!", "[User!]!") */
+    typeInfo: string;
+    /** Whether this field/type is deprecated */
+    deprecated?: {
+        reason: string;
+        replacement?: string;
+    };
+    /** Default value for arguments */
+    defaultValue?: string;
+}
+/**
+ * Result of resolving an identifier against the schema
+ */
+export interface SchemaResolution {
+    /** Whether the identifier exists in the schema */
+    exists: boolean;
+    /** Documentation extracted from schema */
+    documentation?: Documentation;
+    /** URL to the reference page for this identifier */
+    referenceUrl: string;
+    /** Whether this identifier is deprecated */
+    deprecated?: {
+        reason: string;
+        replacement?: string;
+    };
+    /** The GraphQL type if this is a type identifier */
+    graphqlType?: GraphQLType;
+}
+/**
+ * Interface for resolving GraphQL identifiers against a schema
+ */
+export interface SchemaResolver {
+    /**
+     * Resolve an identifier against the schema
+     */
+    resolveIdentifier(identifier: Identifier): SchemaResolution | null;
+    /**
+     * Get documentation for a schema path
+     */
+    getDocumentation(schemaPath: string[]): Documentation | null;
+    /**
+     * Generate a reference URL for a schema path
+     */
+    generateReferenceLink(schemaPath: string[]): string;
+    /**
+     * Check if a type exists in the schema
+     */
+    typeExists(typeName: string): boolean;
+    /**
+     * Get all available types for validation
+     */
+    getAllTypes(): string[];
+}
+/**
+ * Configuration for URL generation
+ */
+export interface RouteConfig {
+    /** Base path for reference pages (default: "/reference") */
+    basePath?: string;
+    /** Whether to include fragments in URLs (default: true) */
+    includeFragments?: boolean;
+}
+/**
+ * Polen's implementation of SchemaResolver
+ */
+export declare class PolenSchemaResolver implements SchemaResolver {
+    private schema;
+    private routeConfig;
+    constructor(schema: GraphQLSchema, routeConfig?: RouteConfig);
+    /**
+     * Resolve an identifier against the schema
+     */
+    resolveIdentifier(identifier: Identifier): SchemaResolution | null;
+    /**
+     * Get documentation for a schema path
+     */
+    getDocumentation(schemaPath: string[]): Documentation | null;
+    /**
+     * Generate a reference URL for a schema path
+     */
+    generateReferenceLink(schemaPath: string[]): string;
+    /**
+     * Check if a type exists in the schema
+     */
+    typeExists(typeName: string): boolean;
+    /**
+     * Get all available types for validation
+     */
+    getAllTypes(): string[];
+    private resolveType;
+    private resolveField;
+    private resolveArgument;
+    private resolveDirective;
+    private getFieldFromType;
+    private getTypeSignature;
+}
+/**
+ * Create a schema resolver for Polen
+ */
+export declare const createPolenSchemaResolver: (schema: GraphQLSchema, routeConfig?: RouteConfig) => SchemaResolver;
+/**
+ * Enhanced analysis result with schema resolution
+ */
+export interface SchemaAwareAnalysisResult {
+    /** Original analysis result */
+    analysis: import('./types.ts').AnalysisResult;
+    /** Schema resolutions for all identifiers */
+    resolutions: Map<string, SchemaResolution>;
+    /** Validation errors from schema checking */
+    schemaErrors: Array<{
+        identifier: Identifier;
+        message: string;
+        severity: 'error' | 'warning';
+    }>;
+}
+/**
+ * Perform schema-aware analysis of a GraphQL document
+ */
+export declare const analyzeWithSchema: (source: string, schema: GraphQLSchema, routeConfig?: RouteConfig) => SchemaAwareAnalysisResult;
+//# sourceMappingURL=schema-integration.d.ts.map

package/build/lib/graphql-document/schema-integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-integration.d.ts","sourceRoot":"","sources":["../../../src/lib/graphql-document/schema-integration.ts"],"names":[],"mappings":"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"}