android2harmony 0.1.7 → 0.1.8

package/skills/a2h-app-req-gen/scripts/reqgen/src/analysis/graph/callback-flow.js

@@ -0,0 +1,277 @@
+import { conditionsAreCompatible } from "../../graph/paths.js";
+import {
+  advanceCallSiteStack,
+  executionFlowsForward,
+  isCallSiteArgumentStep,
+} from "../callback-call-sites.js";
+export const DEFAULT_MAX_CALL_DEPTH = 32;
+export const DEFAULT_MAX_CALLBACK_ITERATIONS = 50_000;
+export const CALL_DEPTH_BUDGET_EXHAUSTED = "CALL_DEPTH_BUDGET_EXHAUSTED";
+export const CALLBACK_ITERATION_BUDGET_EXHAUSTED =
+  "CALLBACK_ITERATION_BUDGET_EXHAUSTED";
+export class CallDepthBudgetExceededError extends Error {
+  code = CALL_DEPTH_BUDGET_EXHAUSTED;
+  stage = "graph";
+  maxCallDepth;
+  depthReached;
+  attemptedDepth;
+  bindingRef;
+  callbackRef;
+  constructor(input) {
+    super(
+      `Callback propagation exceeded the ${input.maxCallDepth}-edge call-depth budget.`,
+    );
+    this.name = "CallDepthBudgetExceededError";
+    this.maxCallDepth = input.maxCallDepth;
+    this.depthReached = input.depthReached;
+    this.attemptedDepth = input.depthReached + 1;
+    this.bindingRef = input.bindingRef;
+    this.callbackRef = input.callbackRef;
+  }
+}
+export class CallbackIterationBudgetExceededError extends Error {
+  code = CALLBACK_ITERATION_BUDGET_EXHAUSTED;
+  stage = "graph";
+  maxCallbackIterations;
+  iterationsUsed;
+  attemptedIteration;
+  bindingRef;
+  callbackRef;
+  constructor(input) {
+    super(
+      `Callback propagation exceeded the global ${input.maxCallbackIterations}-iteration budget.`,
+    );
+    this.name = "CallbackIterationBudgetExceededError";
+    this.maxCallbackIterations = input.maxCallbackIterations;
+    this.iterationsUsed = input.iterationsUsed;
+    this.attemptedIteration = input.iterationsUsed + 1;
+    this.bindingRef = input.bindingRef;
+    this.callbackRef = input.callbackRef;
+  }
+}
+function canonicalJson(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalJson).join(",")}]`;
+  }
+  if (value !== null && typeof value === "object") {
+    return `{${Object.entries(value)
+      .sort(([left], [right]) => left.localeCompare(right, "en"))
+      .map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function eventContextKey(context) {
+  if (!context) return "";
+  return [
+    context.eventChannelKey ?? "",
+    context.eventType ?? "",
+    context.eventPayload === undefined
+      ? ""
+      : canonicalJson(context.eventPayload),
+  ].join("\u0000");
+}
+function positiveSafeInteger(value, option) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new RangeError(
+      `${option} must be a positive safe integer, got ${value}.`,
+    );
+  }
+  return value;
+}
+function compareStep(left, right) {
+  return (
+    left.callbackKey.localeCompare(right.callbackKey, "en") ||
+    left.flowFactRef.localeCompare(right.flowFactRef, "en") ||
+    left.conditionRefs
+      .join("\u0000")
+      .localeCompare(right.conditionRefs.join("\u0000"), "en")
+  );
+}
+function traversalStateKey(
+  callbackKey,
+  conditionRefs,
+  eventContext,
+  callSiteStack,
+) {
+  return [
+    callbackKey,
+    [...new Set(conditionRefs)]
+      .sort((left, right) => left.localeCompare(right, "en"))
+      .join("\u0000"),
+    eventContextKey(eventContext),
+    callSiteStack.join("\u0000"),
+  ].join("\u0001");
+}
+/**
+ * Resolves the callbacks that execute for one UI interaction.
+ *
+ * Argument, method-reference, stored-value and return facts describe value
+ * flow from an implementation into a callback slot. Execution lookup therefore
+ * traverses them from the slot back to the implementation. Listener invocation
+ * direct call, and asynchronous event-channel facts already describe
+ * execution from producer/caller to consumer/callee, so they are traversed in
+ * their declared direction.
+ */
+export class CallbackFlowTraversal {
+  maxCallDepth;
+  maxCallbackIterations;
+  byExecutionSource = new Map();
+  conditionExpressions;
+  iterationsUsed = 0;
+  constructor(facts, options = {}) {
+    this.maxCallDepth = positiveSafeInteger(
+      options.maxCallDepth ?? DEFAULT_MAX_CALL_DEPTH,
+      "maxCallDepth",
+    );
+    this.maxCallbackIterations = positiveSafeInteger(
+      options.maxCallbackIterations ?? DEFAULT_MAX_CALLBACK_ITERATIONS,
+      "maxCallbackIterations",
+    );
+    this.conditionExpressions = new Map(
+      (options.conditionFacts ?? []).map((condition) => [
+        condition.id,
+        condition.data.expressionAnchor,
+      ]),
+    );
+    for (const fact of [...facts].sort((left, right) =>
+      left.id.localeCompare(right.id, "en"),
+    )) {
+      const forward = executionFlowsForward(fact.data.flowKind);
+      const source = forward
+        ? fact.data.fromCallbackKey
+        : fact.data.toCallbackKey;
+      const target = forward
+        ? fact.data.toCallbackKey
+        : fact.data.fromCallbackKey;
+      const steps = this.byExecutionSource.get(source) ?? [];
+      steps.push({
+        callbackKey: target,
+        flowFactRef: fact.id,
+        flowKind: fact.data.flowKind,
+        ...(fact.data.parameterName
+          ? { parameterName: fact.data.parameterName }
+          : {}),
+        ...(fact.data.callSiteKey
+          ? { callSiteKey: fact.data.callSiteKey }
+          : {}),
+        conditionRefs: fact.data.conditionKeys ?? [],
+        ...(fact.data.eventChannelKey
+          ? { eventChannelKey: fact.data.eventChannelKey }
+          : {}),
+        ...(fact.data.eventType ? { eventType: fact.data.eventType } : {}),
+        ...(fact.data.eventPayload
+          ? { eventPayload: fact.data.eventPayload }
+          : {}),
+      });
+      this.byExecutionSource.set(source, steps);
+    }
+    for (const steps of this.byExecutionSource.values()) {
+      steps.sort(compareStep);
+    }
+  }
+  isCompatibleWithConditions(reachable, conditionRefs) {
+    return conditionsAreCompatible(
+      [...reachable.conditionRefs, ...conditionRefs],
+      this.conditionExpressions,
+    );
+  }
+  retainIteration(bindingRef, callbackRef) {
+    if (this.iterationsUsed >= this.maxCallbackIterations) {
+      throw new CallbackIterationBudgetExceededError({
+        maxCallbackIterations: this.maxCallbackIterations,
+        iterationsUsed: this.iterationsUsed,
+        bindingRef,
+        callbackRef,
+      });
+    }
+    this.iterationsUsed += 1;
+  }
+  resolve(bindingRef, rootCallbackKey) {
+    this.retainIteration(bindingRef, rootCallbackKey);
+    const queue = [
+      {
+        callbackKey: rootCallbackKey,
+        depth: 0,
+        callbackPath: [rootCallbackKey],
+        flowFactRefs: [],
+        conditionRefs: [],
+        callSiteStack: [],
+      },
+    ];
+    /*
+     * A callback is an execution state together with the guards accumulated
+     * on the way to it. Treating the callback key alone as visited silently
+     * discarded a second valid path such as `if (A) helper()` /
+     * `if (B) helper()`. Path-local callback membership prevents cycles,
+     * while this state key preserves distinct A-or-B alternatives.
+     */
+    const visited = new Set([
+      traversalStateKey(rootCallbackKey, [], undefined, []),
+    ]);
+    let cursor = 0;
+    while (cursor < queue.length) {
+      const current = queue[cursor++];
+      const steps = this.byExecutionSource.get(current.callbackKey) ?? [];
+      const reverseArgumentCandidateCount = new Set(
+        steps.filter(isCallSiteArgumentStep).map((step) => step.callbackKey),
+      ).size;
+      for (const step of steps) {
+        const transition = advanceCallSiteStack(
+          current.callSiteStack,
+          step,
+          reverseArgumentCandidateCount,
+        );
+        if (!transition.accepted) continue;
+        if (current.callbackPath.includes(step.callbackKey)) continue;
+        const conditionRefs = [
+          ...new Set([...current.conditionRefs, ...step.conditionRefs]),
+        ].sort((left, right) => left.localeCompare(right, "en"));
+        if (!conditionsAreCompatible(conditionRefs, this.conditionExpressions))
+          continue;
+        const nextDepth = current.depth + 1;
+        if (nextDepth > this.maxCallDepth) {
+          throw new CallDepthBudgetExceededError({
+            maxCallDepth: this.maxCallDepth,
+            depthReached: current.depth,
+            bindingRef,
+            callbackRef: step.callbackKey,
+          });
+        }
+        const eventContext =
+          step.flowKind === "event-channel"
+            ? {
+                ...(step.eventChannelKey
+                  ? { eventChannelKey: step.eventChannelKey }
+                  : {}),
+                ...(step.eventType ? { eventType: step.eventType } : {}),
+                ...(step.eventPayload
+                  ? { eventPayload: step.eventPayload }
+                  : {}),
+              }
+            : current.eventContext;
+        const stateKey = traversalStateKey(
+          step.callbackKey,
+          conditionRefs,
+          eventContext,
+          transition.callSiteStack,
+        );
+        if (visited.has(stateKey)) continue;
+        this.retainIteration(bindingRef, step.callbackKey);
+        visited.add(stateKey);
+        queue.push({
+          callbackKey: step.callbackKey,
+          depth: nextDepth,
+          callbackPath: [...current.callbackPath, step.callbackKey],
+          flowFactRefs: [...current.flowFactRefs, step.flowFactRef],
+          conditionRefs,
+          callSiteStack: transition.callSiteStack,
+          ...(eventContext ? { eventContext } : {}),
+        });
+      }
+    }
+    return queue.map(
+      ({ callSiteStack: _callSiteStack, ...reachable }) => reachable,
+    );
+  }
+}