@codifycli/plugin-core 1.0.0-beta1

package/src/plan/change-set.ts

@@ -0,0 +1,236 @@
+import { ParameterOperation, ResourceOperation, StringIndexedObject } from 'codify-schemas';
+
+import { ParsedParameterSetting } from '../resource/parsed-resource-settings.js';
+import { ResourceSettings } from '../resource/resource-settings.js';
+
+/**
+ * A parameter change describes a parameter level change to a resource.
+ */
+export interface ParameterChange<T extends StringIndexedObject> {
+  /**
+   * The name of the parameter
+   */
+  name: keyof T & string;
+
+  /**
+   * The operation to be performed on the parameter.
+   */
+  operation: ParameterOperation;
+
+  /**
+   * The previous value of the resource (the current value on the system)
+   */
+  previousValue: any | null;
+
+  /**
+   * The new value of the resource (the desired value)
+   */
+  newValue: any | null;
+
+  /**
+   * Whether the parameter is sensitive
+   */
+  isSensitive: boolean;
+}
+
+// Change set will coerce undefined values to null because undefined is not valid JSON
+export class ChangeSet<T extends StringIndexedObject> {
+  operation: ResourceOperation
+  parameterChanges: Array<ParameterChange<T>>
+
+  constructor(
+    operation: ResourceOperation,
+    parameterChanges: Array<ParameterChange<T>>
+  ) {
+    this.operation = operation;
+    this.parameterChanges = parameterChanges;
+  }
+
+  get desiredParameters(): T {
+    return this.parameterChanges
+      .reduce((obj, pc) => ({
+        ...obj,
+        [pc.name]: pc.newValue,
+      }), {}) as T;
+  }
+
+  get currentParameters(): T {
+    return this.parameterChanges
+      .reduce((obj, pc) => ({
+        ...obj,
+        [pc.name]: pc.previousValue,
+      }), {}) as T;
+  }
+
+  static empty<T extends StringIndexedObject>(): ChangeSet<T> {
+    return new ChangeSet<T>(ResourceOperation.NOOP, []);
+  }
+
+  static create<T extends StringIndexedObject>(desired: Partial<T>, settings?: ResourceSettings<T>): ChangeSet<T> {
+    const parameterChanges = Object.entries(desired)
+      .map(([k, v]) => ({
+        name: k,
+        operation: ParameterOperation.ADD,
+        previousValue: null,
+        newValue: v ?? null,
+        isSensitive: settings?.parameterSettings?.[k]?.isSensitive ?? false,
+      }))
+
+    return new ChangeSet(ResourceOperation.CREATE, parameterChanges);
+  }
+
+  static noop<T extends StringIndexedObject>(parameters: Partial<T>, settings?: ResourceSettings<T>): ChangeSet<T> {
+    const parameterChanges = Object.entries(parameters)
+      .map(([k, v]) => ({
+        name: k,
+        operation: ParameterOperation.NOOP,
+        previousValue: v ?? null,
+        newValue: v ?? null,
+        isSensitive: settings?.parameterSettings?.[k]?.isSensitive ?? false,
+      }))
+
+    return new ChangeSet(ResourceOperation.NOOP, parameterChanges);
+  }
+
+  static destroy<T extends StringIndexedObject>(current: Partial<T>, settings?: ResourceSettings<T>): ChangeSet<T> {
+    const parameterChanges = Object.entries(current)
+      .map(([k, v]) => ({
+        name: k,
+        operation: ParameterOperation.REMOVE,
+        previousValue: v ?? null,
+        newValue: null,
+        isSensitive: settings?.parameterSettings?.[k]?.isSensitive ?? false,
+      }))
+
+    return new ChangeSet(ResourceOperation.DESTROY, parameterChanges);
+  }
+
+  static calculateModification<T extends StringIndexedObject>(
+    desired: Partial<T>,
+    current: Partial<T>,
+    parameterSettings: Partial<Record<keyof T, ParsedParameterSetting>> = {},
+  ): ChangeSet<T> {
+    const pc = ChangeSet.calculateParameterChanges(desired, current, parameterSettings);
+
+    const statefulParameterKeys = new Set(
+      Object.entries(parameterSettings)
+        .filter(([, v]) => v?.type === 'stateful')
+        .map(([k]) => k)
+    )
+
+    const resourceOperation = pc
+      .filter((change) => change.operation !== ParameterOperation.NOOP)
+      .reduce((operation: ResourceOperation, curr: ParameterChange<T>) => {
+        let newOperation: ResourceOperation;
+        if (statefulParameterKeys.has(curr.name)) {
+          newOperation = ResourceOperation.MODIFY // All stateful parameters are modify only
+        } else if (parameterSettings[curr.name]?.canModify) {
+          newOperation = ResourceOperation.MODIFY
+        } else {
+          newOperation = ResourceOperation.RECREATE; // Default to Re-create. Should handle the majority of use cases
+        }
+
+        return ChangeSet.combineResourceOperations(operation, newOperation);
+      }, ResourceOperation.NOOP);
+
+    return new ChangeSet<T>(resourceOperation, pc);
+  }
+
+  /**
+   * Calculates the differences between the desired and current parameters,
+   * and returns a list of parameter changes that describe what needs to be added,
+   * removed, or modified to match the desired state.
+   *
+   * @param {Partial<T>} desiredParameters - The desired target state of the parameters.
+   * @param {Partial<T>} currentParameters - The current state of the parameters.
+   * @param {Partial<Record<keyof T, ParameterSetting>>} [parameterOptions] - Optional settings used when comparing parameters.
+   * @return {ParameterChange<T>[]} A list of changes required to transition from the current state to the desired state.
+   */
+  private static calculateParameterChanges<T extends StringIndexedObject>(
+    desiredParameters: Partial<T>,
+    currentParameters: Partial<T>,
+    parameterOptions?: Partial<Record<keyof T, ParsedParameterSetting>>,
+  ): ParameterChange<T>[] {
+    const parameterChangeSet = new Array<ParameterChange<T>>();
+
+    // Filter out null and undefined values or else the diff below will not work
+    const desired = Object.fromEntries(
+      Object.entries(desiredParameters).filter(([, v]) => v !== null && v !== undefined)
+    ) as Partial<T>
+
+    const current = Object.fromEntries(
+      Object.entries(currentParameters).filter(([, v]) => v !== null && v !== undefined)
+    ) as Partial<T>
+
+    for (const k of new Set([...Object.keys(current), ...Object.keys(desired)])) {
+      if (ChangeSet.isSame(desired[k], current[k], parameterOptions?.[k])) {
+        parameterChangeSet.push({
+          name: k,
+          previousValue: current[k] ?? null,
+          newValue: desired[k] ?? null,
+          operation: ParameterOperation.NOOP,
+          isSensitive: parameterOptions?.[k]?.isSensitive ?? false,
+        })
+
+        continue;
+      }
+
+      if ((desired?.[k] === null || desired?.[k] === undefined) && (current?.[k] !== null && current?.[k] !== undefined)) {
+        parameterChangeSet.push({
+          name: k,
+          previousValue: current[k] ?? null,
+          newValue: null,
+          operation: ParameterOperation.REMOVE,
+          isSensitive: parameterOptions?.[k]?.isSensitive ?? false,
+        })
+
+        continue;
+      }
+
+      if ((current?.[k] === null || current?.[k] === undefined) && (desired?.[k] !== null && desired?.[k] !== undefined)) {
+        parameterChangeSet.push({
+          name: k,
+          previousValue: null,
+          newValue: desired[k] ?? null,
+          operation: ParameterOperation.ADD,
+          isSensitive: parameterOptions?.[k]?.isSensitive ?? false,
+        })
+
+        continue;
+      }
+
+      parameterChangeSet.push({
+        name: k,
+        previousValue: current[k] ?? null,
+        newValue: desired[k] ?? null,
+        operation: ParameterOperation.MODIFY,
+        isSensitive: parameterOptions?.[k]?.isSensitive ?? false,
+      })
+    }
+
+    return parameterChangeSet;
+  }
+
+  private static combineResourceOperations(prev: ResourceOperation, next: ResourceOperation) {
+    const orderOfOperations = [
+      ResourceOperation.NOOP,
+      ResourceOperation.MODIFY,
+      ResourceOperation.RECREATE,
+      ResourceOperation.CREATE,
+      ResourceOperation.DESTROY,
+    ]
+
+    const indexPrev = orderOfOperations.indexOf(prev);
+    const indexNext = orderOfOperations.indexOf(next);
+
+    return orderOfOperations[Math.max(indexPrev, indexNext)];
+  }
+
+  private static isSame(
+    desired: unknown,
+    current: unknown,
+    setting?: ParsedParameterSetting,
+  ): boolean {
+    return (setting?.isEqual ?? ((a: unknown, b: unknown) => a === b))(desired, current)
+  }
+}

package/src/plan/plan-types.ts

@@ -0,0 +1,27 @@
+import { StringIndexedObject } from 'codify-schemas';
+
+import { Plan } from './plan.js';
+
+/**
+ * A narrower type for plans for CREATE operations. Only desiredConfig is not null.
+ */
+export interface CreatePlan<T extends StringIndexedObject> extends Plan<T> {
+  desiredConfig: T;
+  currentConfig: null;
+}
+
+/**
+ * A narrower type for plans for DESTROY operations. Only currentConfig is not null.
+ */
+export interface DestroyPlan<T extends StringIndexedObject> extends Plan<T> {
+  desiredConfig: null;
+  currentConfig: T;
+}
+
+/**
+ * A narrower type for plans for MODIFY and RE-CREATE operations.
+ */
+export interface ModifyPlan<T extends StringIndexedObject> extends Plan<T> {
+  desiredConfig: T;
+  currentConfig: T;
+}

package/src/plan/plan.test.ts

@@ -0,0 +1,413 @@
+import { describe, expect, it } from 'vitest';
+import { Plan } from './plan.js';
+import { OS, ParameterOperation, ResourceOperation } from 'codify-schemas';
+import { TestConfig, TestResource } from '../utils/test-utils.test.js';
+import { ResourceController } from '../resource/resource-controller.js';
+import { ParsedResourceSettings } from '../resource/parsed-resource-settings.js';
+import { ResourceSettings } from '../resource/resource-settings.js';
+
+describe('Plan entity tests', () => {
+  it('Adds default values properly when plan is parsed from request (Create)', () => {
+    const resource = createTestResource()
+    const controller = new ResourceController(resource);
+
+    const plan = Plan.fromResponse({
+      operation: ResourceOperation.CREATE,
+      resourceType: 'type',
+      parameters: [{
+        name: 'propB',
+        operation: ParameterOperation.ADD,
+        previousValue: null,
+        newValue: 'propBValue'
+      }],
+      isStateful: false,
+    }, controller.parsedSettings.defaultValues);
+
+    expect(plan.currentConfig).to.be.null;
+
+    expect(plan.desiredConfig).toMatchObject({
+      propA: 'defaultA',
+      propB: 'propBValue',
+    })
+
+    expect(plan.changeSet.parameterChanges
+      .every((pc) => pc.operation === ParameterOperation.ADD)
+    ).to.be.true;
+  })
+
+  it('Adds default values properly when plan is parsed from request (Destroy)', () => {
+    const resource = createTestResource()
+    const controller = new ResourceController(resource);
+
+    const plan = Plan.fromResponse({
+      operation: ResourceOperation.DESTROY,
+      resourceType: 'type',
+      parameters: [{
+        name: 'propB',
+        operation: ParameterOperation.REMOVE,
+        previousValue: 'propBValue',
+        newValue: null,
+      }],
+      isStateful: false,
+    }, controller.parsedSettings.defaultValues);
+
+    expect(plan.currentConfig).toMatchObject({
+      propA: 'defaultA',
+      propB: 'propBValue',
+    })
+
+    expect(plan.desiredConfig).to.be.null;
+
+    expect(plan.changeSet.parameterChanges
+      .every((pc) => pc.operation === ParameterOperation.REMOVE)
+    ).to.be.true;
+  })
+
+  it('Adds default values properly when plan is parsed from request (No-op)', () => {
+    const resource = createTestResource()
+    const controller = new ResourceController(resource);
+
+    const plan = Plan.fromResponse({
+      operation: ResourceOperation.NOOP,
+      resourceType: 'type',
+      parameters: [{
+        name: 'propB',
+        operation: ParameterOperation.NOOP,
+        previousValue: 'propBValue',
+        newValue: 'propBValue',
+      }],
+      isStateful: false,
+    }, controller.parsedSettings.defaultValues);
+
+    expect(plan.currentConfig).toMatchObject({
+      propA: 'defaultA',
+      propB: 'propBValue',
+    })
+
+    expect(plan.desiredConfig).toMatchObject({
+      propA: 'defaultA',
+      propB: 'propBValue',
+    })
+
+    expect(plan.changeSet.parameterChanges
+      .every((pc) => pc.operation === ParameterOperation.NOOP)
+    ).to.be.true;
+  })
+
+  it('Does not add default value if a value has already been specified', () => {
+    const resource = createTestResource()
+    const controller = new ResourceController(resource);
+
+    const plan = Plan.fromResponse({
+      operation: ResourceOperation.CREATE,
+      resourceType: 'type',
+      parameters: [{
+        name: 'propB',
+        operation: ParameterOperation.ADD,
+        previousValue: null,
+        newValue: 'propBValue',
+      }, {
+        name: 'propA',
+        operation: ParameterOperation.ADD,
+        previousValue: null,
+        newValue: 'propAValue',
+      }],
+      isStateful: false,
+    }, controller.parsedSettings.defaultValues);
+
+    expect(plan.currentConfig).to.be.null
+
+    expect(plan.desiredConfig).toMatchObject({
+      propA: 'propAValue',
+      propB: 'propBValue',
+    })
+
+    expect(plan.changeSet.parameterChanges
+      .every((pc) => pc.operation === ParameterOperation.ADD)
+    ).to.be.true;
+  })
+
+  it('Returns the original resource names', () => {
+    const plan = Plan.calculate<TestConfig>({
+      desired: { propA: 'propA' },
+      currentArray: [{ propA: 'propA2' }],
+      state: null,
+      core: {
+        type: 'type',
+        name: 'name1'
+      },
+      settings: new ParsedResourceSettings<TestConfig>({ id: 'type' }),
+      isStateful: false,
+    });
+
+    expect(plan.toResponse()).toMatchObject({
+      resourceType: 'type',
+      resourceName: 'name1',
+      operation: ResourceOperation.RECREATE
+    })
+  })
+
+  it('Filters array parameters in stateless mode (by default)', async () => {
+    const resource = new class extends TestResource {
+      getSettings(): ResourceSettings<any> {
+        return {
+          id: 'type',
+          operatingSystems: [OS.Darwin],
+          parameterSettings: {
+            propZ: { type: 'array', isElementEqual: (a, b) => b.includes(a) }
+          }
+        }
+      }
+
+      async refresh(): Promise<Partial<any> | null> {
+        return {
+          propZ: [
+            '20.15.0',
+            '20.15.1'
+          ]
+        }
+      }
+    }
+
+    const controller = new ResourceController(resource);
+    const plan = await controller.plan(
+      { type: 'type' },
+      { propZ: ['20.15'], } as any,
+      null,
+      false
+    )
+
+    expect(plan.changeSet.operation).to.eq(ResourceOperation.NOOP);
+  })
+
+  it('Filters array parameters in delete mode (when desired is null)', async () => {
+    const resource = new class extends TestResource {
+      getSettings(): ResourceSettings<any> {
+        return {
+          id: 'type',
+          operatingSystems: [OS.Darwin],
+          parameterSettings: {
+            propZ: { type: 'array', isElementEqual: (a, b) => b.includes(a) }
+          }
+        }
+      }
+
+      async refresh(): Promise<Partial<any> | null> {
+        return {
+          propZ: [
+            '20.15.0',
+            '20.15.1'
+          ]
+        }
+      }
+    }
+
+    const controller = new ResourceController(resource);
+    const plan = await controller.plan(
+      { type: 'type' },
+      null,
+      { propZ: ['20.15.0'], } as any,
+      true
+    )
+
+    console.log(JSON.stringify(plan, null, 2));
+    expect(plan).toMatchObject({
+      id: expect.any(String),
+      changeSet: expect.objectContaining({
+        operation: ResourceOperation.DESTROY,
+        parameterChanges: [
+          expect.objectContaining({ operation: 'remove', name: 'propZ', previousValue: ['20.15.0'], newValue: null }),
+        ],
+      }),
+      coreParameters: expect.objectContaining({
+        type: 'type',
+      }),
+      isStateful: true,
+    })
+  })
+
+  it('Doesn\'t filters array parameters if filtering is disabled', async () => {
+    const resource = new class extends TestResource {
+      getSettings(): ResourceSettings<any> {
+        return {
+          id: 'type',
+          operatingSystems: [OS.Darwin],
+          parameterSettings: {
+            propZ: {
+              type: 'array',
+              canModify: true,
+              isElementEqual: (a, b) => b.includes(a),
+              filterInStatelessMode: false
+            }
+          }
+        }
+      }
+
+      async refresh(): Promise<Partial<any> | null> {
+        return {
+          propZ: [
+            '20.15.0',
+            '20.15.1'
+          ]
+        }
+      }
+    }
+
+    const controller = new ResourceController(resource);
+    const plan = await controller.plan(
+      { type: 'type' },
+      { propZ: ['20.15'], } as any,
+      null,
+      false
+    )
+
+    expect(plan.changeSet).toMatchObject({
+      operation: ResourceOperation.MODIFY,
+      parameterChanges: expect.arrayContaining([
+        expect.objectContaining({
+          name: 'propZ',
+          previousValue: expect.arrayContaining([
+            '20.15.0',
+            '20.15.1'
+          ]),
+          newValue: expect.arrayContaining([
+            '20.15'
+          ]),
+          operation: 'modify'
+        })
+      ])
+    })
+  })
+
+  it('Can use the requiredParameters to match the correct resources together', async () => {
+    const resource1 = new class extends TestResource {
+      getSettings(): ResourceSettings<TestConfig> {
+        return {
+          id: 'type',
+          operatingSystems: [OS.Darwin],
+          parameterSettings: {
+            propA: { type: 'string' },
+            propB: { type: 'string', canModify: true },
+          },
+          allowMultiple: {
+            identifyingParameters: ['propA']
+          }
+        }
+      }
+
+      async refresh(): Promise<Partial<any> | null> {
+        return [{
+          propA: 'same',
+          propB: 'old',
+        }, {
+          propA: 'different',
+          propB: 'different',
+        }]
+      }
+    }
+
+    const controller = new ResourceController(resource1);
+    const plan = await controller.plan(
+      { type: 'type' },
+      { propA: 'same', propB: 'new' },
+      null,
+      false
+    )
+
+    expect(plan.changeSet).toMatchObject({
+      operation: ResourceOperation.MODIFY,
+      parameterChanges: expect.arrayContaining([
+        expect.objectContaining({
+          name: 'propA',
+          previousValue: 'same',
+          newValue: 'same',
+          operation: 'noop'
+        }),
+        expect.objectContaining({
+          name: 'propB',
+          previousValue: 'old',
+          newValue: 'new',
+          operation: 'modify'
+        })
+      ])
+    })
+  })
+
+  it('Can use the schema to determine required parameters for multiple allowed', async () => {
+    const resource1 = new class extends TestResource {
+      getSettings(): ResourceSettings<TestConfig> {
+        return {
+          id: 'type',
+          operatingSystems: [OS.Darwin],
+          parameterSettings: {
+            propA: { type: 'string' },
+            propB: { type: 'string', canModify: true },
+          },
+          allowMultiple: true,
+          schema: {
+            '$schema': 'http://json-schema.org/draft-07/schema',
+            '$id': 'https://www.codifycli.com/type.json',
+            'type': 'object',
+            'properties': {
+              propA: { type: 'string' },
+              propB: { type: 'string' }
+            },
+            required: ['propA']
+          }
+        }
+      }
+
+      async refresh(): Promise<Partial<any> | null> {
+        return [{
+          propA: 'same',
+          propB: 'old',
+        }, {
+          propA: 'different',
+          propB: 'different',
+        }]
+      }
+    }
+
+    const controller = new ResourceController(resource1);
+    const plan = await controller.plan(
+      { type: 'type' },
+      { propA: 'same', propB: 'new' },
+      null,
+      false
+    )
+
+    expect(plan.changeSet).toMatchObject({
+      operation: ResourceOperation.MODIFY,
+      parameterChanges: expect.arrayContaining([
+        expect.objectContaining({
+          name: 'propA',
+          previousValue: 'same',
+          newValue: 'same',
+          operation: 'noop'
+        }),
+        expect.objectContaining({
+          name: 'propB',
+          previousValue: 'old',
+          newValue: 'new',
+          operation: 'modify'
+        })
+      ])
+    })
+  })
+})
+
+function createTestResource() {
+  return new class extends TestResource {
+    getSettings(): ResourceSettings<TestConfig> {
+      return {
+        id: 'type',
+        operatingSystems: [OS.Darwin],
+        parameterSettings: {
+          propA: {
+            default: 'defaultA'
+          }
+        }
+      }
+    }
+  };
+}