@fjall/generator 0.88.4

package/dist/src/ast/astInfrastructureParser.d.ts

@@ -0,0 +1,357 @@
+import * as ts from "typescript";
+import { type ApplicationResourcePlan, type StatementType, type CustomCodeBlock, type ExtraProperty } from "../schemas/resourceSchemas.js";
+/** Special marker for identifier references in parsed AST */
+export interface IdentifierRef {
+    __identifier: string;
+}
+/** Special marker for property access expressions in parsed AST */
+export interface ExpressionRef {
+    __expression: string;
+}
+/** Special marker for function call expressions in parsed AST */
+export interface CallRef {
+    __call: string;
+}
+/** Special marker for unknown/unsupported expressions in parsed AST */
+interface UnknownRef {
+    __unknown: string;
+}
+/** Union of all possible values that can be parsed from AST expressions */
+export type ParsedValue = string | number | boolean | null | undefined | IdentifierRef | ExpressionRef | CallRef | UnknownRef | ParsedValue[] | ParsedObject;
+/** Object with string keys and parsed values */
+export type ParsedObject = {
+    [key: string]: ParsedValue;
+};
+/** Base check for non-null, non-array objects */
+export declare function isPlainObject(value: ParsedValue): value is Record<string, ParsedValue>;
+/** Type guard for identifier references */
+export declare function isIdentifierRef(value: ParsedValue): value is IdentifierRef;
+/** Type guard for expression references */
+export declare function isExpressionRef(value: ParsedValue): value is ExpressionRef;
+/** Type guard for parsed objects */
+export declare function isParsedObject(value: ParsedValue): value is ParsedObject;
+/** Safely extract a string from ParsedValue */
+export declare function asString(value: ParsedValue): string | undefined;
+/** Safely extract a number from ParsedValue */
+export declare function asNumber(value: ParsedValue): number | undefined;
+/** Safely extract a boolean from ParsedValue */
+export declare function asBoolean(value: ParsedValue): boolean | undefined;
+/** Safely extract a string array from ParsedValue */
+export declare function asStringArray(value: ParsedValue): string[] | undefined;
+/** Narrow a string to a union member, returning undefined if not a valid member */
+export declare function asStringUnion<T extends readonly string[]>(value: ParsedValue | undefined, validValues: T): T[number] | undefined;
+/** Type guard for call references */
+export declare function isCallRef(value: ParsedValue): value is CallRef;
+/** Capture properties from a parsed config that are NOT in the known keys set */
+export declare function captureExtraProperties(config: ParsedObject, knownKeys: Set<string>): ExtraProperty[];
+/** Parsed network configuration from App.getApp() options */
+interface ParsedNetworkConfig {
+    maxAzs?: number;
+    natGateways?: {
+        count?: number;
+    } | false;
+    flowLogs?: {
+        destination?: string;
+        retentionDays?: number;
+    } | false;
+    vpcEndpoints?: ParsedObject;
+}
+declare const DYNAMODB_KEY_TYPES: readonly ["S", "N", "B"];
+type DynamoDBKeyType = (typeof DYNAMODB_KEY_TYPES)[number];
+interface DynamoDBKey {
+    name: string;
+    type: DynamoDBKeyType;
+}
+/** Parsed DynamoDB table resource from app.addDatabase(DatabaseFactory.build("...", { type: "DynamoDB" })) */
+export interface ParsedDynamoDBResource {
+    variableName?: string;
+    resourceName: string;
+    partitionKey: DynamoDBKey;
+    sortKey?: DynamoDBKey;
+    globalSecondaryIndexes?: Array<{
+        indexName: string;
+        partitionKey: DynamoDBKey;
+        sortKey?: DynamoDBKey;
+    }>;
+    ttlAttribute?: string;
+    stream?: boolean;
+    extraProperties?: ExtraProperty[];
+    node: ts.Node;
+}
+export interface ParsedInfrastructure {
+    sourceFile: ts.SourceFile;
+    imports: ImportInfo[];
+    appVariableName: string;
+    appName: string;
+    vpcId?: string;
+    network?: ParsedNetworkConfig;
+    backup?: {
+        tier: string;
+    } | false;
+    tunnel?: {
+        instanceType?: string;
+    } | boolean;
+    networkResources: ParsedNetworkResource[];
+    databaseResources: ParsedDatabaseResource[];
+    dynamodbResources: ParsedDynamoDBResource[];
+    sqsResources: ParsedSQSResource[];
+    cdnResource?: ParsedCDNResource;
+    s3Resources: ParsedS3Resource[];
+    computeResources: ParsedComputeResource[];
+    patternResources: ParsedPatternResource[];
+    tags: Record<string, string>;
+    /** Custom code blocks (user-written code) to preserve during regeneration */
+    customCodeBlocks?: CustomCodeBlock[];
+    /** All statements classified as managed or custom */
+    classifiedStatements?: ClassifiedStatement[];
+}
+/** Parsed Lambda function configuration */
+export interface ParsedLambdaConfig {
+    memorySize?: number;
+    timeout?: number;
+    ephemeralStorageSize?: number;
+}
+/** Parsed pattern resource from app.addPattern(PatternFactory.build(...)) */
+export interface ParsedPatternResource {
+    variableName?: string;
+    constructId: string;
+    type: "payload" | "nextjs";
+    config: {
+        name: string;
+        domain?: string;
+        database?: {
+            type?: "Instance" | "Aurora";
+            databaseName?: string;
+            databaseEngine?: "postgresql" | "mysql";
+            deletionProtection?: boolean;
+            backupRetention?: number;
+            port?: number;
+            publiclyAccessible?: boolean;
+            allowedIpCidr?: string;
+            instanceType?: string;
+            allocatedStorage?: number;
+            multiAz?: boolean;
+            allowVpcAccess?: boolean;
+            monitoringInterval?: number;
+            preferredMaintenanceWindow?: string;
+            snapshotIdentifier?: string;
+            snapshotUsername?: string;
+            readReplica?: object | false;
+            writer?: object;
+            readers?: object | false;
+            databaseInsights?: object | false;
+            proxy?: object | false;
+            credentials?: object;
+            encryption?: object;
+        };
+        compute?: {
+            server?: ParsedLambdaConfig;
+            imageOptimisation?: ParsedLambdaConfig;
+            revalidation?: ParsedLambdaConfig;
+        };
+        storage?: {
+            assets?: {
+                versioned?: boolean;
+            };
+            cache?: {
+                versioned?: boolean;
+            };
+            media?: {
+                versioned?: boolean;
+            };
+        };
+        messaging?: {
+            revalidationQueue?: {
+                visibilityTimeout?: number;
+                messageRetentionPeriod?: number;
+                maxMessageSize?: number;
+                deadLetterQueue?: {
+                    enabled?: boolean;
+                    maxReceiveCount?: number;
+                } | false;
+            };
+        };
+        cdn?: {
+            domainNames?: string[];
+            certificateArn?: string;
+        };
+        environment?: Record<string, string>;
+    };
+    node: ts.Node;
+}
+export interface ImportInfo {
+    moduleSpecifier: string;
+    namedImports: string[];
+    defaultImport?: string;
+}
+interface ParsedProxyConfig {
+    maxConnections?: number;
+    maxIdleConnections?: number;
+    connectionBorrowTimeout?: number;
+    requireTLS?: boolean;
+}
+interface ParsedReadReplicaConfig {
+    instanceType?: string;
+    availabilityZone?: string;
+}
+interface ParsedCredentialsConfig {
+    username?: string;
+    secretRotation?: {
+        automaticallyAfterDays?: number;
+    };
+}
+interface ParsedDatabaseInsightsConfig {
+    mode?: "standard" | "advanced";
+    encryptionKey?: {
+        awsManaged: true;
+    };
+}
+interface ParsedEncryptionConfig {
+    storageKey?: {
+        awsManaged: true;
+    };
+}
+interface ParsedAuroraWriterConfig {
+    enableDatabaseInsights?: boolean;
+    identifierSuffix?: string;
+    availabilityZone?: string;
+}
+interface ParsedAuroraReadersConfig {
+    count?: number;
+    defaultEnableDatabaseInsights?: boolean;
+}
+export interface ParsedDatabaseResource {
+    variableName?: string;
+    resourceName: string;
+    type: string;
+    databaseName: string;
+    databaseEngine?: "postgresql" | "mysql";
+    engineExpression?: string;
+    port?: number;
+    deletionProtection?: boolean;
+    instanceType?: string;
+    multiAz?: boolean;
+    publiclyAccessible?: boolean;
+    enableSecretRotation?: boolean;
+    encryption?: ParsedEncryptionConfig;
+    databaseInsights?: ParsedDatabaseInsightsConfig | false;
+    proxy?: ParsedProxyConfig | false;
+    readReplica?: ParsedReadReplicaConfig | false;
+    credentials?: ParsedCredentialsConfig;
+    writer?: ParsedAuroraWriterConfig;
+    readers?: ParsedAuroraReadersConfig | false;
+    backupRetention?: number;
+    preferredMaintenanceWindow?: string;
+    primaryRegion?: string;
+    secondaryRegions?: string[];
+    globalClusterIdentifier?: string;
+    enableGlobalWriteForwarding?: boolean;
+    snapshotIdentifier?: string;
+    snapshotUsername?: string;
+    extraProperties?: ExtraProperty[];
+    node: ts.Node;
+}
+export interface ParsedS3Resource {
+    variableName: string;
+    resourceName: string;
+    bucketClass: string;
+    config: ParsedObject;
+    node: ts.Node;
+}
+export interface ParsedComputeResource {
+    variableName?: string;
+    resourceName: string;
+    type: string;
+    config: ParsedObject;
+    node: ts.Node;
+}
+/** Parsed SQS queue resource from app.addMessaging(MessagingFactory.build(...)) */
+export interface ParsedSQSResource {
+    variableName?: string;
+    resourceName: string;
+    queueType: string;
+    visibilityTimeout?: number;
+    retentionPeriod?: number;
+    contentBasedDeduplication?: boolean;
+    extraProperties?: ExtraProperty[];
+    node: ts.Node;
+}
+/** Parsed CDN resource from app.addCdn(CdnFactory.build(...)) */
+export interface ParsedCDNResource {
+    resourceName: string;
+    config: ParsedObject;
+    node: ts.Node;
+}
+/** Parsed additional network resource from app.addNetwork() */
+export interface ParsedNetworkResource {
+    variableName?: string;
+    name: string;
+    config: {
+        maxAzs?: number;
+        natGateways?: {
+            count?: number;
+        } | false;
+        flowLogs?: {
+            destination?: string;
+            retentionDays?: number;
+        } | false;
+        vpcEndpoints?: ParsedObject;
+    };
+    node: ts.Node;
+}
+export declare function parseInfrastructure(content: string, options?: {
+    extractCustomCode?: boolean;
+}): ParsedInfrastructure;
+export declare function convertToResourcePlan(parsed: ParsedInfrastructure, appName: string, options?: {
+    skipValidation?: boolean;
+}): ApplicationResourcePlan;
+/** Re-export for downstream consumers (e.g. astSurgicalModification) */
+export type { StatementType } from "../schemas/resourceSchemas.js";
+/**
+ * A classified statement with its type and metadata.
+ */
+export interface ClassifiedStatement {
+    /** The statement type */
+    type: StatementType;
+    /** The AST node */
+    node: ts.Statement;
+    /** For managed resources, the resource name (e.g., "MyDatabase") */
+    resourceName?: string;
+    /** Start position in source text */
+    startPos: number;
+    /** End position in source text */
+    endPos: number;
+    /** Whether the statement is classified as managed by Fjall */
+    isManaged: boolean;
+}
+/** Re-export for downstream consumers (e.g. astSurgicalModification) */
+export type { CustomCodeBlock } from "../schemas/resourceSchemas.js";
+/**
+ * Classify all top-level statements in an infrastructure file.
+ * This identifies which statements are managed by Fjall vs custom user code.
+ */
+export declare function classifyStatements(sourceFile: ts.SourceFile): ClassifiedStatement[];
+/**
+ * Extract custom code blocks from an infrastructure file.
+ * Returns an array of custom code blocks with their positions relative to managed resources.
+ */
+export declare function extractCustomCodeBlocks(sourceFile: ts.SourceFile, precomputedClassifications?: ClassifiedStatement[]): CustomCodeBlock[];
+/**
+ * Find the position information for a specific managed resource.
+ * Useful for surgical updates.
+ */
+export declare function findManagedResourcePosition(sourceFile: ts.SourceFile, resourceType: StatementType, resourceName: string, precomputedClassifications?: ClassifiedStatement[]): {
+    startPos: number;
+    endPos: number;
+    node: ts.Statement;
+} | null;
+/**
+ * Get the last managed statement of a specific type.
+ * Used to determine insertion points for new resources.
+ */
+export declare function getLastManagedStatementOfType(sourceFile: ts.SourceFile, type: StatementType, precomputedClassifications?: ClassifiedStatement[]): ClassifiedStatement | null;
+/**
+ * Get all managed resources grouped by type.
+ * Useful for understanding the structure of an infrastructure file.
+ */
+export declare function getManagedResourcesByType(sourceFile: ts.SourceFile, precomputedClassifications?: ClassifiedStatement[]): Record<StatementType, ClassifiedStatement[]>;