@quadnix/octo 0.0.30 → 0.2.0

package/dist/utilities/test-helpers/test-modes.d.ts

@@ -0,0 +1,315 @@
+import { type ModelSerializedOutput, NodeType, type ResourceSerializedOutput, type TerraformFolderOutput, type TerraformResourceOutput, type UnknownResource } from '../../app.type.js';
+import { Diff } from '../../functions/diff/diff.js';
+import type { Octo } from '../../main.js';
+import type { App } from '../../models/app/app.model.js';
+import type { TerraformPlan } from '../../modes/validate.mode.js';
+import { ResourceDataRepository } from '../../resources/resource-data.repository.js';
+import { AResource } from '../../resources/resource.abstract.js';
+import type { BaseResourceSchema } from '../../resources/resource.schema.js';
+import { ATerraformResource } from '../../resources/terraform-resource.abstract.js';
+import { StateManagementService } from '../../services/state-management/state-management.service.js';
+import { type TerraformModuleScope } from '../../services/terraform/terraform.service.js';
+/**
+ * An external resource: lifecycle runs outside terraform via a resource action.
+ *
+ * @internal
+ */
+export declare class ExternalIgwResource extends AResource<BaseResourceSchema, ExternalIgwResource> {
+    static readonly NODE_NAME: string;
+    static readonly NODE_PACKAGE: string;
+    static readonly NODE_SCHEMA: {};
+    static readonly NODE_TYPE: NodeType;
+    /**
+     * @internal
+     */
+    constructor(resourceId: string, properties?: BaseResourceSchema['properties'], parents?: UnknownResource[]);
+}
+/**
+ * A native terraform resource that references an (external) parent via `getRef`.
+ *
+ * @internal
+ */
+export declare class TfSgResource extends ATerraformResource<BaseResourceSchema, TfSgResource> {
+    static readonly NODE_NAME: string;
+    static readonly NODE_PACKAGE: string;
+    static readonly NODE_SCHEMA: {};
+    static readonly NODE_TYPE: NodeType;
+    /**
+     * @internal
+     */
+    constructor(resourceId: string, properties?: BaseResourceSchema['properties'], parents?: UnknownResource[]);
+    /**
+     * @internal
+     */
+    toHCL(terraform: TerraformModuleScope): Promise<void>;
+}
+/**
+ * A native terraform resource that contributes an `aws_vpc` block and publishes its id.
+ *
+ * @internal
+ */
+export declare class TfVpcResource extends ATerraformResource<BaseResourceSchema, TfVpcResource> {
+    static readonly NODE_NAME: string;
+    static readonly NODE_PACKAGE: string;
+    static readonly NODE_SCHEMA: {};
+    static readonly NODE_TYPE: NodeType;
+    /**
+     * @internal
+     */
+    constructor(resourceId: string, properties?: BaseResourceSchema['properties'], parents?: UnknownResource[]);
+    /**
+     * @internal
+     */
+    toHCL(terraform: TerraformModuleScope): Promise<void>;
+}
+/**
+ * A native terraform resource whose author declares that any property change recreates it: its
+ * `diffProperties` emits a single `REPLACE` instead of a granular update. Used to exercise the
+ * first-class REPLACE action and the validate replacement cascade.
+ *
+ * @internal
+ */
+export declare class ReplacingTfVpcResource extends ATerraformResource<BaseResourceSchema, ReplacingTfVpcResource> {
+    static readonly NODE_NAME: string;
+    static readonly NODE_PACKAGE: string;
+    static readonly NODE_SCHEMA: {};
+    static readonly NODE_TYPE: NodeType;
+    /**
+     * @internal
+     */
+    constructor(resourceId: string, properties?: BaseResourceSchema['properties'], parents?: UnknownResource[]);
+    /**
+     * @internal
+     */
+    diffProperties(previous: ReplacingTfVpcResource): Promise<Diff[]>;
+    /**
+     * @internal
+     */
+    toHCL(terraform: TerraformModuleScope): Promise<void>;
+}
+/**
+ * A native terraform resource whose author refuses any property update by throwing in
+ * `diffProperties`. Used to prove that an author refusal in a `diff*` method aborts generation
+ * before any HCL is built. Its `toHCL` records every invocation in {@link toHCLInvocations}, so a
+ * test can assert it was never reached when the diff threw.
+ *
+ * @internal
+ */
+export declare class RefusingTfResource extends ATerraformResource<BaseResourceSchema, RefusingTfResource> {
+    static readonly NODE_NAME: string;
+    static readonly NODE_PACKAGE: string;
+    static readonly NODE_SCHEMA: {};
+    static readonly NODE_TYPE: NodeType;
+    static readonly toHCLInvocations: string[];
+    /**
+     * @internal
+     */
+    constructor(resourceId: string, properties?: BaseResourceSchema['properties'], parents?: UnknownResource[]);
+    /**
+     * @internal
+     */
+    diffProperties(previous: RefusingTfResource): Promise<Diff[]>;
+    /**
+     * @internal
+     */
+    toHCL(terraform: TerraformModuleScope): Promise<void>;
+}
+/**
+ * Test harness for the `Octo` mode functions. {@link create} bootstraps an isolated container (via
+ * {@link TestContainer}) with real test terraform + transaction services and an external igw
+ * resource action, mirroring the wiring an `Octo` boot performs; the mode functions under test
+ * resolve those services from the container themselves. The instance exposes the standard
+ * vpc → igw → sg graph across two module folders plus helpers to fabricate terraform plan/state
+ * fixtures.
+ *
+ * @internal
+ */
+export declare class TestModes {
+    private readonly octo;
+    readonly outputDir: string;
+    readonly resourceDataRepository: ResourceDataRepository;
+    readonly stateManagementService: StateManagementService;
+    private readonly terraformService;
+    private readonly testModuleContainer;
+    readonly igwActionHandledDiffs: Diff[];
+    /**
+     * Replaces what the igw resource action does. Set it to throw, and a spec can exercise how a
+     * caller behaves when a resource action fails - the delete that commit drives, in particular.
+     */
+    igwActionHandler?: (diff: Diff) => Promise<BaseResourceSchema['response']>;
+    /**
+     * The response the igw resource action returns. Mutable, and deliberately looser than
+     * `BaseResourceSchema['response']`, so a spec can hand back what a real SDK action can return at
+     * runtime but the schema type forbids - a number, a boolean, a null.
+     */
+    igwResponse: Record<string, unknown>;
+    readonly outputs: Map<string, Record<string, {
+        value: unknown;
+    }>>;
+    readonly plans: Map<string, TerraformPlan>;
+    private readonly terraformConfigs;
+    private readonly terraformProviders;
+    /**
+     * @internal
+     */
+    private constructor();
+    /**
+     * @internal
+     */
+    static create(): Promise<TestModes>;
+    /**
+     * Registers an additional resource into an existing module folder, the way a model action would
+     * contribute a new resource on a re-run. Use after {@link createResourceGraph} to exercise an add
+     * of a brand-new resource (module-attributed, so it lands in the named folder rather than the
+     * provider-less `default` folder).
+     */
+    addResource(moduleId: string, resource: UnknownResource): Promise<void>;
+    /**
+     * Simulates deleting every terraform config/provider declaration from `octo.yml`: the next
+     * simulated fresh process boots without them, the way a real process would after the edit.
+     */
+    clearTerraformRegistrations(): void;
+    /**
+     * Takes the app lock the CLI would have taken, unless the caller supplied one, and releases it
+     * afterwards however the commit turned out, so a test never leaves one behind.
+     *
+     * @internal
+     */
+    commit(app: Parameters<Octo['commit']>[0], options: Omit<Parameters<Octo['commit']>[1], 'lockId'> & {
+        lockId?: string;
+    }, transaction?: Parameters<Octo['commit']>[2]): ReturnType<Octo['commit']>;
+    /**
+     * The same two folders as {@link createResourceGraph}, with the security group reading
+     * the vpc across the folder boundary instead of the (external) internet gateway. That is the one
+     * shape the standard graph cannot make: a terraform resource whose dependency output terragrunt
+     * can mock.
+     *
+     * @internal
+     */
+    createCrossModuleResourceGraph(options?: {
+        save?: boolean;
+    }): Promise<{
+        app: App;
+        sg: TfSgResource;
+        vpc: TfVpcResource;
+    }>;
+    /**
+     * @internal
+     */
+    createProviderBoundResourceGraph(provider: {
+        accountId: string;
+        regionId?: string;
+    }): Promise<{
+        app: App;
+        vpc: TfVpcResource;
+    }>;
+    /**
+     * Stages a single {@link RefusingTfResource} in `region-module`. With `save: true`, commits it so a
+     * later re-stage with changed properties drives an update that the resource refuses. Used to prove
+     * that an author refusal in `diff*` aborts generation before HCL is built.
+     */
+    createRefusingResourceGraph(options?: {
+        save?: boolean;
+    }): Promise<{
+        app: App;
+        refusing: RefusingTfResource;
+    }>;
+    /**
+     * Same `vpc → igw → sg` shape as {@link createResourceGraph}, but the vpc is a
+     * {@link ReplacingTfVpcResource}, so changing its properties later yields a REPLACE that cascades
+     * (in terraform) onto igw and sg. Used to exercise the validate replacement cascade.
+     */
+    createReplaceableResourceGraph(options?: {
+        save?: boolean;
+    }): Promise<{
+        app: App;
+        igw: ExternalIgwResource;
+        sg: TfSgResource;
+        vpc: ReplacingTfVpcResource;
+    }>;
+    /**
+     * @internal
+     */
+    createResourceGraph(options?: {
+        save?: boolean;
+    }): Promise<{
+        app: App;
+        igw: ExternalIgwResource;
+        sg: TfSgResource;
+        vpc: TfVpcResource;
+    }>;
+    /**
+     * @internal
+     */
+    generate(...args: Parameters<Octo['generate']>): ReturnType<Octo['generate']>;
+    /**
+     * @internal
+     */
+    getCommittedTerraformState(): Promise<{
+        terraformFolders: TerraformFolderOutput[];
+        terraformResources: TerraformResourceOutput[];
+    }>;
+    /**
+     * @internal
+     */
+    getModelState(): Promise<ModelSerializedOutput>;
+    /**
+     * @internal
+     */
+    getResourceState(fileName?: string): Promise<ResourceSerializedOutput>;
+    /**
+     * @internal
+     */
+    getTerraformFolderRecords(): Promise<TerraformFolderOutput[]>;
+    /**
+     * What the igw resource action matches. Mutable so a spec can narrow it and exercise a diff that
+     * no registered action handles.
+     */
+    igwActionFilter: (diff: Diff) => boolean;
+    /**
+     * @internal
+     */
+    registerTerraformConfig(...args: Parameters<Octo['registerTerraformConfig']>): void;
+    /**
+     * @internal
+     */
+    registerTerraformProvider(...args: Parameters<Octo['registerTerraformProvider']>): void;
+    /**
+     * @internal
+     */
+    runAction(...args: Parameters<Octo['runAction']>): ReturnType<Octo['runAction']>;
+    /**
+     * Plants a terraform folder record into `models.json`, as if a past generate had written those
+     * folders.
+     */
+    seedModelTerraformFolders(records: TerraformFolderOutput[]): Promise<void>;
+    /**
+     * Simulates the boot of a fresh octo process: fully reset the terraform service, then replay the
+     * recorded config/provider registrations (config before providers, as boot order requires).
+     */
+    simulateFreshProcess(): Promise<void>;
+    /**
+     * @internal
+     */
+    teardown(): Promise<void>;
+    /**
+     * @internal
+     */
+    validate(...args: Parameters<Octo['validate']>): ReturnType<Octo['validate']>;
+    /**
+     * @internal
+     */
+    writePlan(moduleId: string, resourceChanges: {
+        actions: string[];
+        address: string;
+        after?: Record<string, unknown>;
+        afterSensitive?: unknown;
+        afterUnknown?: unknown;
+        before?: Record<string, unknown>;
+        beforeSensitive?: unknown;
+    }[]): void;
+    /**
+     * @internal
+     */
+    writeTfState(moduleId: string, outputs: Record<string, unknown>): void;
+}