rea/src/application/JavaScriptSemanticGraphChildProcessProjection.ts

import { createJavaScriptSemanticGraphUnknown } from "../domain/javascriptSemanticGraph.js";
import type { JavaScriptSemanticGraphNode } from "../domain/javascriptSemanticGraph.js";
import type {
  JavaScriptSemanticChildProcessInteraction,
  JavaScriptSemanticChildProcessSpawn,
} from "../domain/javascriptSemanticIr.js";
import {
  addSemanticGraphNode,
  addSemanticGraphRelation,
  addSemanticGraphUnknown,
  constructSemanticGraphNode,
} from "./JavaScriptSemanticGraphConstruction.js";
import { unknownSemanticEvidence } from "./JavaScriptSemanticGraphEvidence.js";
import {
  semanticCallSiteAt,
  type SemanticFlowProjectionContext,
} from "./JavaScriptSemanticGraphFlowProjection.js";

interface ChildUnknownInput {
  readonly context: SemanticFlowProjectionContext;
  readonly node: JavaScriptSemanticGraphNode | null;
  readonly location: JavaScriptSemanticChildProcessSpawn["location"];
  readonly relationKinds: readonly (
    | "spawns"
    | "forwards-signal"
    | "listens-exit"
    | "listens-error"
  )[];
  readonly detail: string;
  readonly candidateNodeIds: readonly string[];
}

/** Project child creation, argv/env/stdio, listeners, and signals. */
export const projectSemanticChildProcesses = (
  context: SemanticFlowProjectionContext,
): void => {
  const processNodes = new Map(
    context.ir.childProcessSpawns.flatMap((spawn) => {
      const node = addChildProcessNode(context, spawn);
      return node === null ? [] : [[spawn.processId, node] as const];
    }),
  );
  for (const spawn of context.ir.childProcessSpawns) {
    const child = processNodes.get(spawn.processId);
    if (child === undefined) continue;
    projectSpawn(context, spawn, child);
  }
  for (const interaction of context.ir.childProcessInteractions)
    projectInteraction(context, interaction, processNodes);
};

const addChildProcessNode = (
  context: SemanticFlowProjectionContext,
  spawn: JavaScriptSemanticChildProcessSpawn,
): JavaScriptSemanticGraphNode | null =>
  addSemanticGraphNode(
    context.state,
    constructSemanticGraphNode(
      context.file,
      {
        kind: "child-process",
        roleKey: spawn.processId,
        location: spawn.location,
        label: spawn.command ?? spawn.method,
        functionNodeId:
          spawn.ownerCallableId === null
            ? null
            : (context.callableNodes.get(spawn.ownerCallableId)?.node_id ??
              null),
        properties: {
          argv_count: spawn.argvCount,
          command: spawn.command,
          environment_supplied: spawn.environmentSupplied,
          method: spawn.method,
          stdio_mode: spawn.stdioMode,
        },
      },
      context.state,
    ),
  );

const projectSpawn = (
  context: SemanticFlowProjectionContext,
  spawn: JavaScriptSemanticChildProcessSpawn,
  child: JavaScriptSemanticGraphNode,
): void => {
  const callSite = semanticCallSiteAt(context, spawn.location);
  addSemanticGraphRelation(context.state, {
    source: callSite,
    target: child,
    relation: "spawns",
    resolution: spawn.resolution === "complete" ? "resolved" : "candidate",
  });
  for (const projected of spawn.projectedResultBindings)
    addSemanticGraphRelation(context.state, {
      source: child,
      target: context.bindingNodes.get(projected.bindingId),
      relation: "destructures",
      resolution:
        projected.resolution === "complete" ? "resolved" : "candidate",
      properties: {
        projection_path: [...projected.projectionPath],
        projection_resolution: projected.resolution,
      },
    });
  if (spawn.argvCount !== null)
    addSemanticGraphRelation(context.state, {
      source: callSite,
      target: child,
      relation: "supplies-argv",
      resolution: "resolved",
      properties: { argument_count: spawn.argvCount },
    });
  if (spawn.environmentSupplied)
    addSemanticGraphRelation(context.state, {
      source: callSite,
      target: child,
      relation: "supplies-env",
      resolution: "resolved",
    });
  const stdio = addStdioNode(context, spawn, child);
  addSemanticGraphRelation(context.state, {
    source: child,
    target: stdio,
    relation: "connects-stdio",
    resolution: spawn.stdioMode === "dynamic" ? "candidate" : "resolved",
  });
  if (spawn.resolution !== "complete")
    addChildUnknown({
      context,
      node: child,
      location: spawn.location,
      relationKinds: ["spawns"],
      detail: `Static ${spawn.method} command remains unresolved.`,
      candidateNodeIds: [],
    });
};

const addStdioNode = (
  context: SemanticFlowProjectionContext,
  spawn: JavaScriptSemanticChildProcessSpawn,
  child: JavaScriptSemanticGraphNode,
): JavaScriptSemanticGraphNode | null =>
  addSemanticGraphNode(
    context.state,
    constructSemanticGraphNode(
      context.file,
      {
        kind: "stdio",
        roleKey: `stdio:${spawn.processId}`,
        location: spawn.location,
        label: spawn.stdioMode,
        functionNodeId: child.function_node_id,
        properties: { mode: spawn.stdioMode },
      },
      context.state,
    ),
  );

const projectInteraction = (
  context: SemanticFlowProjectionContext,
  interaction: JavaScriptSemanticChildProcessInteraction,
  processNodes: ReadonlyMap<string, JavaScriptSemanticGraphNode>,
): void => {
  const children = interaction.linkedProcessIds.flatMap((identifier) => {
    const child = processNodes.get(identifier);
    return child === undefined ? [] : [child];
  });
  const effect =
    interaction.kind === "listener"
      ? addChildListenerNode(context, interaction)
      : addSignalNode(context, interaction);
  for (const child of children)
    addSemanticGraphRelation(context.state, {
      source: interaction.kind === "listener" ? child : effect,
      target: interaction.kind === "listener" ? effect : child,
      relation:
        interaction.kind === "signal"
          ? "forwards-signal"
          : interaction.eventName === "exit"
            ? "listens-exit"
            : "listens-error",
      resolution:
        interaction.resolution === "complete" ? "resolved" : "candidate",
    });
  if (interaction.resolution !== "complete")
    addChildUnknown({
      context,
      node: effect,
      location: interaction.location,
      relationKinds: [
        interaction.kind === "signal"
          ? "forwards-signal"
          : interaction.eventName === "exit"
            ? "listens-exit"
            : "listens-error",
      ],
      detail: `Static child ${interaction.method} ownership is ambiguous.`,
      candidateNodeIds: children.map(({ node_id: identifier }) => identifier),
    });
};

const addChildListenerNode = (
  context: SemanticFlowProjectionContext,
  interaction: JavaScriptSemanticChildProcessInteraction,
): JavaScriptSemanticGraphNode | null =>
  addSemanticGraphNode(
    context.state,
    constructSemanticGraphNode(
      context.file,
      {
        kind: "listener",
        roleKey: interaction.interactionId,
        location: interaction.listenerLocation ?? interaction.location,
        label: interaction.eventName,
        functionNodeId:
          interaction.ownerCallableId === null
            ? null
            : (context.callableNodes.get(interaction.ownerCallableId)
                ?.node_id ?? null),
        properties: {
          event_name: interaction.eventName,
          method: interaction.method,
        },
      },
      context.state,
    ),
  );

const addSignalNode = (
  context: SemanticFlowProjectionContext,
  interaction: JavaScriptSemanticChildProcessInteraction,
): JavaScriptSemanticGraphNode | null =>
  addSemanticGraphNode(
    context.state,
    constructSemanticGraphNode(
      context.file,
      {
        kind: "signal",
        roleKey: interaction.interactionId,
        location: interaction.location,
        label: interaction.signalName,
        functionNodeId:
          interaction.ownerCallableId === null
            ? null
            : (context.callableNodes.get(interaction.ownerCallableId)
                ?.node_id ?? null),
        properties: { signal_name: interaction.signalName },
      },
      context.state,
    ),
  );

const addChildUnknown = (input: ChildUnknownInput): void => {
  const { context, node, location, relationKinds, detail, candidateNodeIds } =
    input;
  addSemanticGraphUnknown(
    context.state,
    createJavaScriptSemanticGraphUnknown({
      node_id: node?.node_id ?? null,
      family: "child-process",
      relation_kinds: relationKinds,
      reason: "ambiguous-target",
      detail,
      candidate_node_ids: candidateNodeIds,
      evidence: unknownSemanticEvidence(context.file, location),
    }),
  );
};