@quadnix/octo 0.0.30 → 0.1.0

package/dist/functions/dependency/dependency.js

@@ -1,5 +1,11 @@
 import { DependencyError } from '../../errors/index.js';
+/**
+ * @internal
+ */
 class DependencyBehavior {
+    /**
+     * @internal
+     */
     constructor(onField, onAction, toField, forAction) {
         this.onField = onField;
         this.onAction = onAction;
@@ -8,6 +14,8 @@ class DependencyBehavior {
     }
 }
 /**
+ * How two nodes are related. A parent exists before its child, and outlives it.
+ *
  * @group Functions/Dependency
  */
 export var DependencyRelationship;
@@ -16,34 +24,82 @@ export var DependencyRelationship;
     DependencyRelationship["PARENT"] = "parent";
 })(DependencyRelationship || (DependencyRelationship = {}));
 /**
+ * The edge between two nodes in Octo's graph.
+ *
+ * A dependency is directed, and carries two things: an optional parent/child relationship, and a set
+ * of *behaviors*. A behavior states an ordering rule - "when this field of `from` is added, the
+ * matching action on `to` must have run first" - and it is those rules that let Octo order a
+ * transaction correctly instead of guessing.
+ *
+ * Models create dependencies through `addChild()` and `addRelationship()`; you rarely construct one.
+ *
  * @group Functions/Dependency
+ *
+ * @see Definition of [Dependencies](/docs/fundamentals/dependencies).
  */
 export class Dependency {
+    /**
+     * @param from The node this dependency points from.
+     * @param to The node this dependency points to.
+     */
     constructor(from, to) {
         this.behaviors = [];
         this.from = from;
         this.to = to;
     }
-    getBehaviorIndex(onField, onAction, toField, forAction) {
-        return this.behaviors.findIndex((b) => b.onField === onField && b.onAction === onAction && b.toField === toField && b.forAction === forAction);
+    /**
+     * @internal
+     */
+    static unSynth(from, to, dependency) {
+        const newDependency = new Dependency(from, to);
+        dependency.behaviors.forEach((b) => {
+            newDependency.addBehavior(b.onField, b.onAction, b.toField, b.forAction);
+        });
+        if (dependency.relationship) {
+            newDependency.relationship = { ...dependency.relationship };
+        }
+        return newDependency;
     }
+    /**
+     * To declare an ordering rule: when `onAction` happens to `onField` of `from`, then `forAction`
+     * on `toField` of `to` must have been applied first. Adding the same behavior twice is a no-op.
+     */
     addBehavior(onField, onAction, toField, forAction) {
         if (this.getBehaviorIndex(onField, onAction, toField, forAction) === -1) {
             this.behaviors.push(new DependencyBehavior(onField, onAction, toField, forAction));
         }
     }
+    /**
+     * To mark `to` as the child of `from`.
+     *
+     * @throws {@link DependencyError} If this dependency already has a relationship.
+     */
     addChildRelationship(onField, toField) {
         if (this.relationship) {
             throw new DependencyError('Dependency relationship already exists!', this);
         }
         this.relationship = { onField, toField, type: DependencyRelationship.CHILD };
     }
+    /**
+     * To mark `to` as the parent of `from`.
+     *
+     * @throws {@link DependencyError} If this dependency already has a relationship.
+     */
     addParentRelationship(onField, toField) {
         if (this.relationship) {
             throw new DependencyError('Dependency relationship already exists!', this);
         }
         this.relationship = { onField, toField, type: DependencyRelationship.PARENT };
     }
+    /**
+     * The relationship between the two nodes, if one was declared.
+     */
+    getRelationship() {
+        return this.relationship;
+    }
+    /**
+     * Whether any behavior matches every argument given. Arguments left out match anything.
+     */
     hasMatchingBehavior(onField, onAction, toField, forAction) {
         return this.behaviors.some((b) => {
             const onFieldCondition = onField ? b.onField === onField : true;
@@ -53,18 +109,29 @@ export class Dependency {
             return onFieldCondition && onActionCondition && toFieldCondition && forActionCondition;
         });
     }
+    /**
+     * Whether `to` is a child of `from`.
+     */
     isChildRelationship() {
         return this.relationship && this.relationship.type === DependencyRelationship.CHILD;
     }
+    /**
+     * Whether both dependencies connect the same two nodes, in the same direction.
+     */
     isEqual(dependency) {
         return (this.from.getContext() === dependency.from.getContext() && this.to.getContext() === dependency.to.getContext());
     }
+    /**
+     * Whether `to` is a parent of `from`.
+     */
     isParentRelationship() {
         return this.relationship && this.relationship.type === DependencyRelationship.PARENT;
     }
-    getRelationship() {
-        return this.relationship;
-    }
+    /**
+     * To drop an ordering rule.
+     *
+     * @throws {@link DependencyError} If no such behavior exists.
+     */
     removeBehavior(onField, onAction, toField, forAction) {
         const index = this.getBehaviorIndex(onField, onAction, toField, forAction);
         if (index === -1) {
@@ -72,6 +139,9 @@ export class Dependency {
         }
         this.behaviors.splice(index, 1);
     }
+    /**
+     * @internal
+     */
     synth() {
         const behaviors = [];
         this.behaviors.forEach((b) => {
@@ -95,15 +165,11 @@ export class Dependency {
             to: this.to.getContext(),
         };
     }
-    static unSynth(from, to, dependency) {
-        const newDependency = new Dependency(from, to);
-        dependency.behaviors.forEach((b) => {
-            newDependency.addBehavior(b.onField, b.onAction, b.toField, b.forAction);
-        });
-        if (dependency.relationship) {
-            newDependency.relationship = { ...dependency.relationship };
-        }
-        return newDependency;
+    /**
+     * The position of a matching behavior, or `-1`.
+     */
+    getBehaviorIndex(onField, onAction, toField, forAction) {
+        return this.behaviors.findIndex((b) => b.onField === onField && b.onAction === onAction && b.toField === toField && b.forAction === forAction);
     }
 }
 //# sourceMappingURL=dependency.js.map

package/dist/functions/dependency/dependency.js.map

@@ -1 +1 @@
-{"version":3,"file":"dependency.js","sourceRoot":"","sources":["../../../src/functions/dependency/dependency.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dependency.js","sourceRoot":"","sources":["../../../src/functions/dependency/dependency.ts"],"names":[],"mappings":"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"}

package/dist/functions/diff/aggregate-resource-actions.d.ts

@@ -0,0 +1,19 @@
+import type { DiffMetadata } from './diff-metadata.js';
+import { DiffAction } from './diff.js';
+/**
+ * One octo resource's diffs, collapsed to a single action.
+ */
+export interface AggregatedResourceAction {
+    action: DiffAction.ADD | DiffAction.DELETE | DiffAction.REPLACE | DiffAction.UPDATE;
+    reason?: string;
+    resourceId: string;
+}
+/**
+ * Collapses a resource's field-level diffs into one action per resource, keyed by resource context.
+ *
+ * Precedence: an add/delete of `resourceId` wins; a REPLACE beats an UPDATE; otherwise UPDATE.
+ * `reason` is taken from the winning diff.
+ *
+ * @internal
+ */
+export declare function aggregateResourceActions(diffs: DiffMetadata[]): Map<string, AggregatedResourceAction>;

package/dist/functions/diff/aggregate-resource-actions.js

@@ -0,0 +1,41 @@
+import { DiffAction } from './diff.js';
+/**
+ * Collapses a resource's field-level diffs into one action per resource, keyed by resource context.
+ *
+ * Precedence: an add/delete of `resourceId` wins; a REPLACE beats an UPDATE; otherwise UPDATE.
+ * `reason` is taken from the winning diff.
+ *
+ * @internal
+ */
+export function aggregateResourceActions(diffs) {
+    const aggregated = new Map();
+    for (const diff of diffs) {
+        const node = diff.node;
+        const context = node.getContext();
+        const reason = diff.diff.reason;
+        if (diff.action === DiffAction.DELETE && diff.field === 'resourceId') {
+            aggregated.set(context, { action: DiffAction.DELETE, reason, resourceId: node.resourceId });
+        }
+        else if (diff.action === DiffAction.ADD && diff.field === 'resourceId') {
+            aggregated.set(context, { action: DiffAction.ADD, reason, resourceId: node.resourceId });
+        }
+        else if (diff.action === DiffAction.REPLACE) {
+            const existing = aggregated.get(context);
+            if (!existing || existing.action === DiffAction.UPDATE) {
+                aggregated.set(context, { action: DiffAction.REPLACE, reason, resourceId: node.resourceId });
+            }
+        }
+        else if (!aggregated.has(context)) {
+            aggregated.set(context, { action: DiffAction.UPDATE, reason, resourceId: node.resourceId });
+        }
+        else {
+            // A later update may be the only one carrying a reason.
+            const existing = aggregated.get(context);
+            if (existing.action === DiffAction.UPDATE && existing.reason === undefined && reason !== undefined) {
+                existing.reason = reason;
+            }
+        }
+    }
+    return aggregated;
+}
+//# sourceMappingURL=aggregate-resource-actions.js.map

package/dist/functions/diff/aggregate-resource-actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate-resource-actions.js","sourceRoot":"","sources":["../../../src/functions/diff/aggregate-resource-actions.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAWvC;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAqB;IAC5D,MAAM,UAAU,GAAG,IAAI,GAAG,EAAoC,CAAC;IAE/D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAuB,CAAC;QAC1C,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QAEhC,IAAI,IAAI,CAAC,MAAM,KAAK,UAAU,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK,KAAK,YAAY,EAAE,CAAC;YACrE,UAAU,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QAC9F,CAAC;aAAM,IAAI,IAAI,CAAC,MAAM,KAAK,UAAU,CAAC,GAAG,IAAI,IAAI,CAAC,KAAK,KAAK,YAAY,EAAE,CAAC;YACzE,UAAU,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QAC3F,CAAC;aAAM,IAAI,IAAI,CAAC,MAAM,KAAK,UAAU,CAAC,OAAO,EAAE,CAAC;YAC9C,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACzC,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,UAAU,CAAC,MAAM,EAAE,CAAC;gBACvD,UAAU,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;YAC/F,CAAC;QACH,CAAC;aAAM,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACpC,UAAU,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QAC9F,CAAC;aAAM,CAAC;YACN,wDAAwD;YACxD,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,OAAO,CAAE,CAAC;YAC1C,IAAI,QAAQ,CAAC,MAAM,KAAK,UAAU,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACnG,QAAQ,CAAC,MAAM,GAAG,MAAM,CAAC;YAC3B,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/functions/diff/diff-metadata.d.ts

@@ -1,24 +1,42 @@
 import type { ActionInputs, ActionOutputs, IUnknownModelAction, IUnknownResourceAction, UnknownNode } from '../../app.type.js';
 import type { Diff, DiffAction } from './diff.js';
 /**
+ * A {@link Diff} paired with the actions that will apply it, and the order they run in.
+ *
+ * A transaction is a list of these, so this is the shape you read when inspecting what a run did -
+ * in an event payload, or in a test.
+ *
  * @group Functions/Diff
  */
 export declare class DiffMetadata {
+    readonly action: DiffAction;
     readonly actions: IUnknownModelAction[] | IUnknownResourceAction[];
     applied: boolean;
     applyOrder: number;
     readonly diff: Diff;
-    readonly action: DiffAction;
     readonly field: string;
-    readonly node: UnknownNode;
-    readonly value: unknown;
     readonly inputs: ActionInputs;
+    readonly node: UnknownNode;
     readonly outputs: ActionOutputs;
+    readonly value: unknown;
+    /**
+     * @param diff The change this metadata is about.
+     * @param actions The actions that will apply it.
+     * @throws {@link NoMatchingActionFoundTransactionError} If no action was given.
+     */
     constructor(diff: Diff, actions: IUnknownModelAction[] | IUnknownResourceAction[]);
     /**
      * Overrides JSON.serialize() to output a more succinct model of diff-metadata.
+     *
+     * @internal
      */
     toJSON(): ReturnType<Diff['toJSON']>;
+    /**
+     * @internal
+     */
     updateInputs(inputs: ActionInputs): void;
+    /**
+     * @internal
+     */
     updateOutputs(outputs: ActionOutputs): void;
 }

package/dist/functions/diff/diff-metadata.js

@@ -1,8 +1,18 @@
 import { NoMatchingActionFoundTransactionError } from '../../errors/index.js';
 /**
+ * A {@link Diff} paired with the actions that will apply it, and the order they run in.
+ *
+ * A transaction is a list of these, so this is the shape you read when inspecting what a run did -
+ * in an event payload, or in a test.
+ *
  * @group Functions/Diff
  */
 export class DiffMetadata {
+    /**
+     * @param diff The change this metadata is about.
+     * @param actions The actions that will apply it.
+     * @throws {@link NoMatchingActionFoundTransactionError} If no action was given.
+     */
     constructor(diff, actions) {
         this.inputs = { inputs: {}, metadata: {}, models: {}, overlays: {}, resources: {} };
         this.outputs = {};
@@ -20,13 +30,21 @@ export class DiffMetadata {
     }
     /**
      * Overrides JSON.serialize() to output a more succinct model of diff-metadata.
+     *
+     * @internal
      */
     toJSON() {
         return this.diff.toJSON();
     }
+    /**
+     * @internal
+     */
     updateInputs(inputs) {
         Object.assign(this.inputs, inputs);
     }
+    /**
+     * @internal
+     */
     updateOutputs(outputs) {
         Object.assign(this.outputs, outputs);
     }

package/dist/functions/diff/diff-metadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"diff-metadata.js","sourceRoot":"","sources":["../../../src/functions/diff/diff-metadata.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,qCAAqC,EAAE,MAAM,uBAAuB,CAAC;AAG9E;;GAEG;AACH,MAAM,OAAO,YAAY;IAcvB,YAAY,IAAU,EAAE,OAAyD;QAHxE,WAAM,GAAiB,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;QAC7F,YAAO,GAAkB,EAAE,CAAC;QAGnC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;YACrB,MAAM,IAAI,qCAAqC,CAAC,oCAAoC,EAAE,IAAI,CAAC,CAAC;QAC9F,CAAC;QAED,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC;QAErB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5B,CAAC;IAED,YAAY,CAAC,MAAoB;QAC/B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;IAED,aAAa,CAAC,OAAsB;QAClC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;CACF"}
+{"version":3,"file":"diff-metadata.js","sourceRoot":"","sources":["../../../src/functions/diff/diff-metadata.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,qCAAqC,EAAE,MAAM,uBAAuB,CAAC;AAG9E;;;;;;;GAOG;AACH,MAAM,OAAO,YAAY;IAcvB;;;;OAIG;IACH,YAAY,IAAU,EAAE,OAAyD;QAXxE,WAAM,GAAiB,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;QAG7F,YAAO,GAAkB,EAAE,CAAC;QASnC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;YACrB,MAAM,IAAI,qCAAqC,CAAC,oCAAoC,EAAE,IAAI,CAAC,CAAC;QAC9F,CAAC;QAED,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC;QAErB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAC1B,CAAC;IAED;;;;OAIG;IACH,MAAM;QACJ,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,MAAoB;QAC/B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,OAAsB;QAClC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;CACF"}

package/dist/functions/diff/diff.d.ts

@@ -1,30 +1,84 @@
 import type { UnknownNode } from '../../app.type.js';
 /**
+ * What a {@link Diff} says happened to a node.
+ *
+ * `REPLACE` is distinct from `UPDATE`: it means the change cannot be applied in place, and the
+ * infrastructure must be destroyed and re-created.
+ *
  * @group Functions/Diff
  */
 export declare enum DiffAction {
+    /**
+     * The node is in the new graph and not in the last committed one, so it has to be created.
+     */
     ADD = "add",
+    /**
+     * The node is in the last committed graph and not in the new one, so it has to be destroyed.
+     */
     DELETE = "delete",
+    /**
+     * A field changed that cannot be changed in place, so the infrastructure is destroyed and created
+     * again. A resource declares this itself, with a reason, which is what a report shows a reviewer
+     * in place of leaving them to work a recreate out of a terraform plan.
+     */
     REPLACE = "replace",
+    /**
+     * A field changed and can be changed in place.
+     */
     UPDATE = "update",
+    /**
+     * Nothing changed, and the node still wants an action to run over it.
+     */
     VALIDATE = "validate"
 }
 /**
+ * One change to one field of one node.
+ *
+ * Diffs are the currency of Octo: comparing the graph you just described against the last committed
+ * one produces a list of them, and every action is selected and driven by the diffs it accepts.
+ *
  * @group Functions/Diff
  */
 export declare class Diff<N extends UnknownNode = UnknownNode, V = unknown> {
+    /**
+     * What happened.
+     */
     readonly action: DiffAction;
+    /**
+     * The field of the node that changed, e.g. `resourceId`, `properties`, or `parent`.
+     */
     readonly field: string;
+    /**
+     * The node that changed.
+     */
     readonly node: N;
+    /**
+     * Why the change is being made, when the field alone does not explain it.
+     * It is carried into reports, so write it for whoever reads the plan.
+     */
+    readonly reason?: string;
+    /**
+     * The new value of the field. Its shape depends on the field.
+     */
     readonly value: V;
-    constructor(node: Diff<N, V>['node'], action: Diff['action'], field: Diff['field'], value: Diff<N, V>['value']);
+    /**
+     * @param node The node that changed.
+     * @param action What happened to it.
+     * @param field The field of the node that changed.
+     * @param value The new value of the field.
+     * @param reason Why the change is being made, carried into reports.
+     */
+    constructor(node: Diff<N, V>['node'], action: Diff['action'], field: Diff['field'], value: Diff<N, V>['value'], reason?: Diff['reason']);
     /**
      * Overrides JSON.serialize() to output a more succinct representation of diff.
+     *
+     * @internal
      */
     toJSON(): {
         action: string;
         field: string;
         node: string;
+        reason?: string;
         value: V | string;
     };
 }

package/dist/functions/diff/diff.js

@@ -1,26 +1,63 @@
 /**
+ * What a {@link Diff} says happened to a node.
+ *
+ * `REPLACE` is distinct from `UPDATE`: it means the change cannot be applied in place, and the
+ * infrastructure must be destroyed and re-created.
+ *
  * @group Functions/Diff
  */
 export var DiffAction;
 (function (DiffAction) {
+    /**
+     * The node is in the new graph and not in the last committed one, so it has to be created.
+     */
     DiffAction["ADD"] = "add";
+    /**
+     * The node is in the last committed graph and not in the new one, so it has to be destroyed.
+     */
     DiffAction["DELETE"] = "delete";
+    /**
+     * A field changed that cannot be changed in place, so the infrastructure is destroyed and created
+     * again. A resource declares this itself, with a reason, which is what a report shows a reviewer
+     * in place of leaving them to work a recreate out of a terraform plan.
+     */
     DiffAction["REPLACE"] = "replace";
+    /**
+     * A field changed and can be changed in place.
+     */
     DiffAction["UPDATE"] = "update";
+    /**
+     * Nothing changed, and the node still wants an action to run over it.
+     */
     DiffAction["VALIDATE"] = "validate";
 })(DiffAction || (DiffAction = {}));
 /**
+ * One change to one field of one node.
+ *
+ * Diffs are the currency of Octo: comparing the graph you just described against the last committed
+ * one produces a list of them, and every action is selected and driven by the diffs it accepts.
+ *
  * @group Functions/Diff
  */
 export class Diff {
-    constructor(node, action, field, value) {
+    /**
+     * @param node The node that changed.
+     * @param action What happened to it.
+     * @param field The field of the node that changed.
+     * @param value The new value of the field.
+     * @param reason Why the change is being made, carried into reports.
+     */
+    constructor(node, action, field, value, reason) {
         this.node = node;
         this.action = action;
         this.field = field;
         this.value = value;
+        this.reason = reason;
     }
     /**
      * Overrides JSON.serialize() to output a more succinct representation of diff.
+     *
+     * @internal
      */
     toJSON() {
         let value = this.value;
@@ -31,14 +68,18 @@ export class Diff {
             value = `anchorId=${value.anchorId}`;
         }
         else {
-            value = JSON.parse(JSON.stringify(value));
+            value = value === undefined ? undefined : JSON.parse(JSON.stringify(value));
         }
-        return {
+        const json = {
             action: this.action,
             field: this.field,
             node: this.node.getContext(),
             value,
         };
+        if (this.reason !== undefined) {
+            json.reason = this.reason;
+        }
+        return json;
     }
 }
 //# sourceMappingURL=diff.js.map

package/dist/functions/diff/diff.js.map

@@ -1 +1 @@
-{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../../src/functions/diff/diff.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,CAAN,IAAY,UAMX;AAND,WAAY,UAAU;IACpB,yBAAW,CAAA;IACX,+BAAiB,CAAA;IACjB,iCAAmB,CAAA;IACnB,+BAAiB,CAAA;IACjB,mCAAqB,CAAA;AACvB,CAAC,EANW,UAAU,KAAV,UAAU,QAMrB;AAED;;GAEG;AACH,MAAM,OAAO,IAAI;IASf,YAAY,IAAwB,EAAE,MAAsB,EAAE,KAAoB,EAAE,KAA0B;QAC5G,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,IAAI,KAAK,GAAe,IAAI,CAAC,KAAK,CAAC;QACnC,IAAK,KAAqB,CAAC,UAAU,EAAE,CAAC;YACtC,KAAK,GAAI,KAAqB,CAAC,UAAU,EAAE,CAAC;QAC9C,CAAC;aAAM,IAAK,KAAuB,CAAC,QAAQ,EAAE,CAAC;YAC7C,KAAK,GAAG,YAAa,KAAuB,CAAC,QAAQ,EAAE,CAAC;QAC1D,CAAC;aAAM,CAAC;YACN,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5C,CAAC;QAED,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE;YAC5B,KAAK;SACN,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../../src/functions/diff/diff.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,CAAN,IAAY,UA2BX;AA3BD,WAAY,UAAU;IACpB;;OAEG;IACH,yBAAW,CAAA;IAEX;;OAEG;IACH,+BAAiB,CAAA;IAEjB;;;;OAIG;IACH,iCAAmB,CAAA;IAEnB;;OAEG;IACH,+BAAiB,CAAA;IAEjB;;OAEG;IACH,mCAAqB,CAAA;AACvB,CAAC,EA3BW,UAAU,KAAV,UAAU,QA2BrB;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,IAAI;IA2Bf;;;;;;OAMG;IACH,YACE,IAAwB,EACxB,MAAsB,EACtB,KAAoB,EACpB,KAA0B,EAC1B,MAAuB;QAEvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,MAAM;QACJ,IAAI,KAAK,GAAe,IAAI,CAAC,KAAK,CAAC;QACnC,IAAK,KAAqB,CAAC,UAAU,EAAE,CAAC;YACtC,KAAK,GAAI,KAAqB,CAAC,UAAU,EAAE,CAAC;QAC9C,CAAC;aAAM,IAAK,KAAuB,CAAC,QAAQ,EAAE,CAAC;YAC7C,KAAK,GAAG,YAAa,KAAuB,CAAC,QAAQ,EAAE,CAAC;QAC1D,CAAC;aAAM,CAAC;YACN,KAAK,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9E,CAAC;QAED,MAAM,IAAI,GAAwF;YAChG,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE;YAC5B,KAAK;SACN,CAAC;QAEF,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC5B,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/functions/diff/diff.utility.d.ts

@@ -1,11 +1,14 @@
 import type { UnknownNode } from '../../app.type.js';
 import { Diff } from './diff.js';
 /**
+ * Helpers for producing {@link Diff}s between two versions of a node.
+ *
+ * Use them when overriding `diffProperties()` on a model or resource - each one compares a single
+ * field of the previous node against the latest, and returns the diffs that field's change implies.
+ *
  * @group Functions/Diff
  */
 export declare class DiffUtility {
-    private static generateDeleteDiff;
-    static isObjectDeepEquals(x: unknown, y: unknown, excludePaths?: string[], currentPath?: string[]): boolean;
     /**
      * Generate a deep diff of an array of basic types from the previous node vs the latest node.
      * @param a previous node.
@@ -43,4 +46,16 @@ export declare class DiffUtility {
      * @param field string representing the field parent uses to reference the object.
      */
     static diffObject(a: UnknownNode, b: UnknownNode, field: string): Diff[];
+    /**
+     * Whether two values are deeply equal.
+     *
+     * @param x The first value.
+     * @param y The second value.
+     * @param excludePaths Dot-separated paths to ignore, e.g. `tags`.
+     */
+    static isObjectDeepEquals(x: unknown, y: unknown, excludePaths?: string[], currentPath?: string[]): boolean;
+    /**
+     * The diffs that deleting a node implies - the node itself, and every child below it.
+     */
+    private static generateDeleteDiff;
 }