@ibgib/core-gib 0.1.38 → 0.1.40

package/src/test-helpers.mts

@@ -8,6 +8,7 @@
 
 import { extractErrorMsg, getUUID } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { IbGib_V1, IbGibRel8ns_V1, IbGibData_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
 
 import { GLOBAL_LOG_A_LOT } from './core-constants.mjs';
 import { KeystoneService_V1 } from './keystone/keystone-service-v1.mjs';
@@ -16,7 +17,7 @@ import { Factory_V1 } from '@ibgib/ts-gib/dist/V1/factory.mjs';
 import { createTimeline, mut8Timeline, appendToTimeline } from './timeline/timeline-api.mjs';
 import { persistTransformResult, registerNewIbGib } from './witness/space/space-helper.mjs';
 import { MetaspaceService } from './witness/space/metaspace/metaspace-types.mjs';
-import { TransformResult } from '@ibgib/ts-gib/dist/types.mjs';
+import { Ib, TransformResult } from '@ibgib/ts-gib/dist/types.mjs';
 import { TestMut8Info, TestRel8Info, TestStepInfo, TestRound } from './test-types.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT;
@@ -86,16 +87,6 @@ export async function createTimelineRootTestHelper<TData extends IbGibData_V1 =
     try {
         if (logalot) { console.log(`${lc} starting... (I: 8f50a8cf0268742048f7c188feb5a825)`); }
 
-        // const resTimeline = await createTimeline({
-        //     ib,
-        //     data,
-        //     rel8ns: undefined,
-        //     metaspace, space
-        // });
-        // const timeline = resTimeline.newIbGib;
-
-        // return timeline;
-
         // Determine the parent to fork based on the provided options.
         const atom = ib.split(' ').at(0)!;
         const parentIbGib = Factory_V1.primitive({ ib: atom });
@@ -159,6 +150,140 @@ export async function getTestKeystoneServiceHelper(): Promise<KeystoneService_V1
     return new MockKeystoneService() as unknown as KeystoneService_V1;
 }
 
+export interface TestIbGibIb {
+    /**
+     * @example alpha, beta, gamma, etc.
+     */
+    atom: string;
+    /**
+     * concatenated r0 mut8 history
+     * @example r0, r0r1, r0r1r2
+     */
+    rounds: string
+    /**
+     * @example 0 for r0, 1 for r0r1, 2 for r0r1r2, etc.
+     */
+    roundNumber: number
+    /**
+     * concatenated v0 mut8 history
+     * @example v0, v0v1, v0v1v2
+     */
+    versions: string
+    /**
+     * @example 0 for v0, 1 for v0v1, 2 for v0v1v2, etc.
+     */
+    versionNumber: number
+    /**
+     * optional comments sans spaces, e.g., "thisIsAComment_thisIsAnother_heckWhyNotAThird"
+     */
+    comments_snake_plus_CamelCase: string | undefined;
+}
+
+/**
+ * r0, r0r1, r0r1r2
+ */
+const TEST_IB_ROUNDS_REGEXP = /^(r\d)+$/;
+/**
+ * v0, v0v1, v0v1v2
+ */
+const TEST_IB_VERSIONS_REGEXP = /^(v\d)+$/;
+
+/**
+ * Parses ib to extract base, rounds, and version.
+ * Schema: [base] [r1r2...] [v0v1...] (space-delimited)
+ * Example: "alpha r0r1 v0v1v2" → { base: "alpha", rounds: "r1", version: 2 }
+ */
+export function parseTestIb(ib: string): TestIbGibIb {
+    const lc = `[${parseTestIb.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 87b6d85567f2e2a4b84a4278fb1bc826)`); }
+
+        const parts = ib.split(' ');
+
+        if (parts.length === 1) {
+            // Initial ib, no rounds or versions yet
+            throw new Error(`(UNEXPECTED) does this ever hit? (E: 584978e0c644aec1e86f7e964a547526)`);
+            // return {
+            //     atom: parts[0],
+            //     rounds: '',
+            //     roundNumber: -1,
+            //     versions: '',
+            //     versionNumber: -1,
+            //     comments_snake_plus_CamelCase: undefined,
+            // };
+        }
+
+        const [
+            atom, // alpha, beta, etc.
+            rounds,
+            versions,
+            comments_snake_plus_CamelCase,
+        ] = parts;
+
+        // ignoring possibility of later erroneous parts for now
+
+        // Find round and version parts
+        if (!rounds) { throw new Error(`invalid ib. rounds falsy (E: b706c8005e7f619e0386b6981d835826)`); }
+        if (!TEST_IB_ROUNDS_REGEXP.test(rounds)) { throw new Error(`invalid ib. rounds (${rounds}) does not match TEST_IB_ROUNDS_REGEXP: ${TEST_IB_ROUNDS_REGEXP.source} (E: 5498b89c25321a97a8728be82b1f7b26)`); }
+        const roundNumber = Number.parseInt(rounds.split('r').at(-1)!);
+        if (!versions) { throw new Error(`invalid ib. versions falsy (E: 79aa180471b434c685ea27987b50e726)`); }
+        if (!TEST_IB_VERSIONS_REGEXP.test(versions)) { throw new Error(`invalid ib. versions (${versions}) does not match TEST_IB_VERSIONS_REGEXP: ${TEST_IB_VERSIONS_REGEXP.source} (E: 5498b89c25321a97a8728be82b1f7b26)`); }
+        const versionNumber = Number.parseInt(versions.split('v').at(-1)!);
+
+        return {
+            atom,
+            rounds,
+            roundNumber,
+            versions,
+            versionNumber,
+            comments_snake_plus_CamelCase,
+        }
+
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+function getNewTestIb({
+    atom,
+    comments_snake_plus_CamelCase,
+}: {
+    /**
+     * should be 'alpha', 'beta', 'gamma', etc.
+     */
+    atom: string,
+    /**
+     * @default undefined
+     */
+    comments_snake_plus_CamelCase?: string,
+}): Ib {
+    const lc = `[${getNewTestIb.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 60aebdb828f72bbfbcbf401e7af09826)`); }
+        if (!atom) throw new Error(`atom required (E: dc041852cdd88d692a8c2168ae4c7626)`);
+
+        let ib = [
+            atom,
+            'r1',
+            'v0',
+        ].join(' ');
+
+        if (comments_snake_plus_CamelCase) {
+            ib += ' ' + comments_snake_plus_CamelCase;
+        }
+
+        return ib;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
 /**
  * Stateful transformer for test operations.
  * Manages counters, rounds, and execution history.
@@ -169,40 +294,45 @@ export async function getTestKeystoneServiceHelper(): Promise<KeystoneService_V1
  * const r1 = transformer.newRound({ name: 'r1_common_history' });
  *
  * const step = await transformer.mut8({
- *   ibGib: alpha, space: sourceSpace, metaspace,
- *   name: 'r1_alpha_v1_source'
- * });
+ * Test transformer class that provides fluent method chaining for timeline testing.
+ * Automatically tracks rounds, steps, provides test data snapshots, and auto-versions ibs.
  *
- * // Later verify
- * r1.steps.forEach(step => {
- *   const mut8Info = step.infos[0] as TestMut8Info;
- *   // verify step.ibGib.data[mut8Info.key] === mut8Info.value
- * });
- * ```
+ * Ib versioning schema: `[base] [r1r2...] [v0v1v2]` (space-delimited)
+ * Example: `alpha r1 v0` → `alpha r1 v1` → `alpha r1r2 v0`
  */
 export class TestTransformer {
+    private lc = `[${TestTransformer.name}]`;
+    private metaspace: MetaspaceService;
+    private sourceSpace: IbGibSpaceAny;
+    private destSpace: IbGibSpaceAny;
     private mut8Counter = 0;
     private rel8Counter = 0;
     private rounds: TestRound[] = [];
-    private currentRound?: TestRound;
+    private get currentRound(): TestRound | undefined {
+        return this.rounds && this.rounds.length > 0 ?
+            this.rounds.at(-1)! :
+            undefined;
+    };
+
+    constructor(
+        metaspace: MetaspaceService,
+        sourceSpace: IbGibSpaceAny,
+        destSpace: IbGibSpaceAny
+    ) {
+        this.metaspace = metaspace;
+        this.sourceSpace = sourceSpace;
+        this.destSpace = destSpace;
+    }
 
     /**
-     * Start a new round of test operations.
+     * Start a new round of testing operations.
      */
     newRound({ name, description }: { name: string, description?: string }): TestRound {
         const round: TestRound = { name, description, steps: [] };
         this.rounds.push(round);
-        this.currentRound = round;
         return round;
     }
 
-    /**
-     * Get the current active round.
-     */
-    getCurrentRound(): TestRound | undefined {
-        return this.currentRound;
-    }
-
     /**
      * Get all steps across all rounds.
      */
@@ -224,172 +354,319 @@ export class TestTransformer {
         this.mut8Counter = 0;
         this.rel8Counter = 0;
         this.rounds = [];
-        this.currentRound = undefined;
     }
 
-    private getNextMut8Key(prefix?: string): string {
-        this.mut8Counter++;
-        const baseKey = prefix ?? 'testField';
-        return `${baseKey}_${this.mut8Counter}`;
+    /**
+     * Get space by location.
+     */
+    private getSpace(location: 'source' | 'dest'): IbGibSpaceAny {
+        return location === 'source' ? this.sourceSpace : this.destSpace;
     }
 
-    private getNextMut8Value(): string {
-        return `value_${this.mut8Counter}`;
-    }
 
-    private getNextRel8nName(prefix?: string): string {
-        this.rel8Counter++;
-        const baseName = prefix ?? 'testrel8n';
-        return `${baseName}_${this.rel8Counter}`;
+    /**
+     * Generates next ib based on current ib and round context.
+     * Increments version and appends round if needed.
+     */
+    private generateNextIb({
+        currentIb,
+        comments_snake_plus_CamelCase,
+    }: {
+        currentIb: Ib,
+        comments_snake_plus_CamelCase?: string,
+    }): string {
+        const lc = `${this.lc}[${this.generateNextIb.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 9291a8f3c6b168e53856c61ba9d5c826)`); }
+
+            const { atom, rounds, roundNumber, versions, versionNumber } = parseTestIb(currentIb);
+
+            if (!this.currentRound) { throw new Error(`(UNEXPECTED) this.currentRound falsy? (E: 4594188ef0a859759daaa4b8ea1a7926)`); }
+
+            const currentRoundNumber = this.rounds.length;
+            const needsNewRounds = roundNumber !== currentRoundNumber;
+
+            /**
+             * the next rounds is only different if we are in a different round.
+             */
+            const nextRounds = needsNewRounds ?
+                `${rounds}r${roundNumber + 1}` :
+                rounds;
+            /**
+             * always increment the version
+             */
+            const nextVersions = `${versions}v${versionNumber + 1}`;
+
+            if (comments_snake_plus_CamelCase && comments_snake_plus_CamelCase.includes(' ')) {
+                throw new Error(`comments_snake_plus_CamelCase contains spaces. must be underscore-delimited camelCase comments (E: de725d4090de648bf221cbaf4e041826)`);
+            }
+
+            let nextIb = `${atom} ${nextRounds} ${nextVersions}`;
+            if (comments_snake_plus_CamelCase) {
+                nextIb += ' ' + comments_snake_plus_CamelCase;
+            }
+
+            return nextIb;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
     }
 
     /**
-     * Perform a mutation with auto-generated field/value.
-     * Automatically adds step to current round if one exists.
+     * Create a timeline root with auto-tracking to current round.
      *
      * @example
-     * // Start new step
-     * let step = await transformer.mut8({ ibGib: alpha, space, metaspace });
+     * const transformer = new TestTransformer(metaspace, sourceSpace, destSpace);
+     * transformer.newRound({ name: 'r1_setup' });
+     * const step = await transformer.create({
+     *   ib: 'alpha',
+     *   data: { type: 'alpha' },
+     *   in: 'source',
+     * });
+     */
+    async create<TData extends IbGibData_V1 = any>({
+        atom,
+        data,
+        in: location,
+        name,
+        comments_snake_plus_CamelCase,
+    }: {
+        atom: string;
+        data?: TData;
+        in: 'source' | 'dest';
+        name?: string;
+        comments_snake_plus_CamelCase?: string,
+    }): Promise<TestStepInfo> {
+        const lc = `${this.lc}[create]`;
+
+        if (!this.currentRound) {
+            throw new Error(`${lc} No active round. Call newRound() first.`);
+        }
+
+        const space = this.getSpace(location);
+
+        const timeline = await createTimelineRootTestHelper<TData>({
+            ib: getNewTestIb({ atom, comments_snake_plus_CamelCase }),
+            data,
+            space,
+        });
+
+        const result: TestStepInfo = {
+            ibGib: timeline,
+            addr: getIbGibAddr({ ibGib: timeline }),
+            space,
+            metaspace: this.metaspace,
+            infos: [],
+            name: name || `${this.currentRound.name}_${atom}_create`,
+        };
+
+        this.currentRound.steps.push(result);
+
+        return result;
+    }
+
+    /**
+     * Perform a mutation with optional field mutation and auto-versioning.
      *
-     * // Continue chaining
-     * step = await transformer.mut8({ stepInfo: step, fieldPrefix: 'count' });
+     * @example
+     * // With field and auto value
+     * const step = await transformer.mut8({
+     *   stepInfo: prevStep,
+     *   strField: 'commonField',
+     * });
+     * // Creates: alpha r1 v0, sets commonField: 'value_1'
      *
      * @example
-     * // With naming convention
+     * // With field and custom value
      * const step = await transformer.mut8({
-     *   ibGib: alpha, space, metaspace,
-     *   name: 'r1_alpha_v2_source'
+     *   stepInfo: prevStep,
+     *   strField: { name: 'count', value: '42' },
      * });
+     *
+     * @example
+     * // Ib-only mutation (no field)
+     * const step = await transformer.mut8({ stepInfo: prevStep });
      */
-    async mut8({
+    async mut8<TData extends IbGibData_V1 = any>({
         ibGib,
-        space,
-        metaspace,
-        fieldPrefix,
         stepInfo,
+        in: location,
+        strField,
         name,
+        comments_snake_plus_CamelCase,
     }: {
-        ibGib?: IbGib_V1;
-        space?: IbGibSpaceAny;
-        metaspace: MetaspaceService; // Required for mut8Timeline
-        fieldPrefix?: string;
+        ibGib?: IbGib_V1<TData>;
         stepInfo?: TestStepInfo;
+        in?: 'source' | 'dest';
+        strField?: string | { name: string; value: string };
         name?: string;
+        comments_snake_plus_CamelCase?: string,
     }): Promise<TestStepInfo> {
-        const lc = `[${TestTransformer.name}.${this.mut8.name}]`;
-        try {
-            const currentIbGib = stepInfo?.ibGib ?? ibGib;
-            const currentSpace = stepInfo?.space ?? space;
-            const currentMetaspace = stepInfo?.metaspace ?? metaspace;
-            const currentName = name ?? stepInfo?.name;
-
-            if (!currentIbGib) throw new Error(`ibGib required (E: 8c4a5e1f2b3d4e5f6a7b8c9d0e1f2a3b)`);
-            if (!currentSpace) throw new Error(`space required (E: 9d5b6f2c3e4a5d6f7b8c9d0e1f2a3b4c)`);
-
-            const key = this.getNextMut8Key(fieldPrefix);
-            const value = this.getNextMut8Value();
-            const mut8Ib = `${currentIbGib.ib} x_${value}`;
-
-            const mutated = await mut8Timeline({
-                timeline: currentIbGib,
-                mut8Opts: {
-                    mut8Ib,
-                    dataToAddOrPatch: { [key]: value }
-                },
-                metaspace: currentMetaspace,
-                space: currentSpace,
-            });
+        const lc = `${this.lc}[mut8]`;
 
-            const mut8Info: TestMut8Info = { key, value };
-            const result: TestStepInfo = {
-                ibGib: mutated,
-                space: currentSpace,
-                metaspace: currentMetaspace,
-                infos: [...(stepInfo?.infos ?? []), mut8Info],
-                name: currentName,
-            };
+        if (!this.currentRound) {
+            throw new Error(`${lc} No active round. Call newRound() first.`);
+        }
 
-            // Add to current round if exists
-            this.currentRound?.steps.push(result);
+        // Extract context
+        let targetIbGib: IbGib_V1<TData>;
+        let space: IbGibSpaceAny;
+
+        if (stepInfo) {
+            targetIbGib = stepInfo.ibGib as IbGib_V1<TData>;
+            space = stepInfo.space;
+        } else if (ibGib && location) {
+            targetIbGib = ibGib;
+            space = this.getSpace(location);
+        } else {
+            throw new Error(`${lc} Must provide either stepInfo or (ibGib + in)`);
+        }
 
-            return result;
-        } catch (error) {
-            console.error(`${lc} ${extractErrorMsg(error)}`);
-            throw error;
+        // Generate next ib with auto-versioning
+        const nextIb = this.generateNextIb({
+            currentIb: targetIbGib.ib,
+            comments_snake_plus_CamelCase,
+        });
+
+        // Build data to add/patch
+        const dataToAddOrPatch: Partial<TData> = {};
+
+        if (strField) {
+            let fieldName: string;
+            let fieldValue: string;
+
+            if (typeof strField === 'string') {
+                // Field name only, generate random value
+                fieldName = strField;
+                fieldValue = `value_${++this.mut8Counter}`;
+            } else {
+                // Field name and value provided
+                fieldName = strField.name;
+                fieldValue = strField.value;
+                this.mut8Counter++; // Still increment counter
+            }
+
+            (dataToAddOrPatch as any)[fieldName] = fieldValue;
         }
+
+        // Perform mutation
+        const mutatedIbGib = await mut8Timeline({
+            timeline: targetIbGib,
+            mut8Opts: {
+                mut8Ib: nextIb,
+                dataToAddOrPatch,
+            },
+            metaspace: this.metaspace,
+            space,
+        });
+
+        const mut8Info: TestMut8Info = {
+            type: 'mut8',
+            ib: nextIb,
+            key: strField ? (typeof strField === 'string' ? strField : strField.name) : undefined,
+            value: strField ? (typeof strField === 'string' ? `value_${this.mut8Counter}` : strField.value) : undefined,
+        };
+
+        const result: TestStepInfo = {
+            ibGib: mutatedIbGib,
+            addr: getIbGibAddr({ ibGib: mutatedIbGib }),
+            space,
+            metaspace: this.metaspace,
+            infos: [mut8Info],
+            name: name || `${this.currentRound.name}_${nextIb}`,
+        };
+
+        this.currentRound.steps.push(result);
+
+        return result;
     }
 
     /**
-     * Perform a relation with auto-generated rel8n name.
-     * Automatically adds step to current round if one exists.
+     * Perform a relation with auto-generated rel8n name and auto-versioning.
      *
      * @example
-     * // Start new step
-     * let step = await transformer.rel8({
-     *   ibGib: alpha, targetIbGibs: [beta],
-     *   space, metaspace
+     * const step = await transformer.rel8({
+     *   stepInfo: prevStep,
+     *   targetIbGibs: [beta, gamma],
+     *   rel8nName: 'depends_on',
      * });
-     *
-     * // Continue chaining
-     * step = await transformer.rel8({ stepInfo: step, targetIbGibs: [gamma] });
      */
     async rel8({
+        stepInfo,
         ibGib,
+        in: location,
         targetIbGibs,
-        space,
-        metaspace,
-        rel8nPrefix,
-        stepInfo,
+        rel8nName,
         name,
+        // comments_snake_plus_CamelCase,
     }: {
-        ibGib?: IbGib_V1;
-        targetIbGibs: IbGib_V1 | IbGib_V1[];
-        space?: IbGibSpaceAny;
-        metaspace?: MetaspaceService;
-        rel8nPrefix?: string;
         stepInfo?: TestStepInfo;
+        ibGib?: IbGib_V1;
+        in: 'source' | 'dest';
+        targetIbGibs: IbGib_V1[];
+        rel8nName: string;
         name?: string;
+        // comments_snake_plus_CamelCase?: string,
     }): Promise<TestStepInfo> {
-        const lc = `[${TestTransformer.name}.${this.rel8.name}]`;
-        try {
-            const currentIbGib = stepInfo?.ibGib ?? ibGib;
-            const currentSpace = stepInfo?.space ?? space;
-            const currentMetaspace = stepInfo?.metaspace ?? metaspace;
-            const currentName = name ?? stepInfo?.name;
-
-            if (!currentIbGib) throw new Error(`ibGib required (E: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6)`);
-            if (!currentSpace) throw new Error(`space required (E: b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7)`);
-            if (!currentMetaspace) throw new Error(`metaspace required (E: c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8)`);
-
-            const rel8nName = this.getNextRel8nName(rel8nPrefix);
-            const targets = Array.isArray(targetIbGibs) ? targetIbGibs : [targetIbGibs];
-
-            const related = await appendToTimeline({
-                timeline: currentIbGib,
-                metaspace: currentMetaspace,
-                space: currentSpace,
-                rel8nInfos: [{
-                    rel8nName,
-                    ibGibs: targets
-                }],
-            });
-
-            const rel8Info: TestRel8Info = { rel8nName, targetIbGibs: targets };
-            const result: TestStepInfo = {
-                ibGib: related,
-                space: currentSpace,
-                metaspace: currentMetaspace,
-                infos: [...(stepInfo?.infos ?? []), rel8Info],
-                name: currentName,
-            };
+        const lc = `${this.lc}[rel8]`;
 
-            // Add to current round if exists
-            this.currentRound?.steps.push(result);
+        if (!this.currentRound) {
+            throw new Error(`${lc} No active round. Call newRound() first.`);
+        }
 
-            return result;
-        } catch (error) {
-            console.error(`${lc} ${extractErrorMsg(error)}`);
-            throw error;
+        // Extract context
+        let sourceIbGib: IbGib_V1;
+        let space: IbGibSpaceAny;
+
+        if (stepInfo) {
+            sourceIbGib = stepInfo.ibGib;
+            space = stepInfo.space;
+        } else if (ibGib && location) {
+            sourceIbGib = ibGib;
+            space = this.getSpace(location);
+        } else {
+            throw new Error(`${lc} Must provide either stepInfo or (ibGib + in)`);
         }
+
+        // Generate next ib with auto-versioning
+        // we can't do this right now because the rel8 transform cannot itself
+        // change the ib. this only currently is available through the mut8
+        // call.
+        // const nextIb = this.generateNextIb({currentIb: sourceIbGib.ib, comments_snake_plus_CamelCase});
+
+        // Perform relation
+        const relatedIbGib = await appendToTimeline({
+            timeline: sourceIbGib,
+            rel8nInfos: [{
+                rel8nName,
+                ibGibs: targetIbGibs
+            }],
+            metaspace: this.metaspace,
+            space,
+        });
+
+        const rel8Info: TestRel8Info = {
+            type: 'rel8',
+            ib: sourceIbGib.ib,
+            rel8nName,
+            targetAddrs: targetIbGibs.map(x => getIbGibAddr({ ibGib: x })),
+        };
+
+        const result: TestStepInfo = {
+            ibGib: relatedIbGib,
+            addr: getIbGibAddr({ ibGib: relatedIbGib }),
+            space,
+            metaspace: this.metaspace,
+            infos: [rel8Info],
+            name: name || `${this.currentRound.name}_autoname_${sourceIbGib.ib}`,
+        };
+
+        this.currentRound.steps.push(result);
+
+        return result;
     }
 }
+