process-graph 1.0.5 → 1.1.0

package/dist/index-CCfe0csl.d.ts

@@ -0,0 +1,353 @@
+import { G as IdSpace, a as Overlay, g as Model } from "./index-CmZOswkx.js";
+import { JsonValue, Resolution } from "trilean";
+//#region ../../core/graph/domain/dist/status.d.ts
+/** The derived states of an element, in the order the derivation considers them. */
+declare const statuses: readonly ["done", "unknown", "skipped", "ready", "blocked"];
+/**
+ * Where an element stands in a run, derived from the model, the run overlay and the facts, never stored.
+ *
+ * - `done`: finished, as reported by the overlay or, for a pure control element, derived.
+ * - `unknown`: cannot be told apart, because the overlay says so, a need is unknown, or a condition on an incoming transition is indeterminate.
+ * - `skipped`: every incoming path is cut, so the element will not run.
+ * - `ready`: not done, with every live need done and every consumed artefact produced or provided.
+ * - `blocked`: not done and still waiting.
+ */
+type Status = (typeof statuses)[number];
+/**
+ * What a transition's `condition` evaluates to: `taken`, `not-taken`, or `indeterminate` when facts the condition reads are missing, so both outcomes stay possible. A transition without a condition is always `taken`.
+ */
+type Branch = "taken" | "not-taken" | "indeterminate";
+//#endregion
+//#region ../../core/graph/domain/dist/facts.d.ts
+/**
+ * The injected source of facts a condition reads: an opaque, JSON-valued key in, a found or not-found value out (trilean's `Resolution`). A key the port cannot answer is `{ found: false }`, which makes any condition that depends on it indeterminate, never false.
+ *
+ * Keys of the reserved shape built by `elementStatusKey` are answered by this package from the overlay and never reach the port. The port is asked keys of the shape built by `artefactKey` to learn which input artefacts are provided; it should answer every other key it does not know with `{ found: false }`.
+ */
+type Facts = (key: JsonValue) => Resolution;
+/**
+ * Builds the reserved key that reads another element's run state inside a condition. It resolves to the text `"done"` or `"open"`, and is not found (so the condition is indeterminate) when the overlay says `"unknown"` or the id is not an element of the model.
+ *
+ * The value is the overlay's own state, not the derived status: a condition therefore never depends on the derivation that evaluates it, and cannot form a cycle.
+ * @param id - The element whose state is read.
+ * @returns A key to put in a trilean `reference` node.
+ */
+declare const elementStatusKey: (id: string) => JsonValue;
+/**
+ * Builds the key the package asks the facts port when it needs to know whether an artefact has been provided from outside the process. An artefact is provided exactly when the port answers `{ found: true }` with the boolean `true`; a not-found or `false` answer means it is not.
+ *
+ * A provided artefact satisfies every consumer, whether or not an activity also produces it.
+ * @param id - The artefact.
+ * @returns The key the port is asked.
+ */
+declare const artefactKey: (id: string) => JsonValue;
+/**
+ * Thrown when a condition uses a node whose evaluation needs a table or a collection from the facts port, which answers single keys only.
+ */
+declare class UnsupportedConditionError extends Error {
+  /** The kind of reference the condition used. */
+  readonly reference: "lookup" | "collection";
+  /**
+   * @param reference - The unsupported kind of reference.
+   */
+  constructor(reference: "lookup" | "collection");
+}
+/**
+ * Evaluates every transition's condition.
+ *
+ * A definite true is `taken`, a definite false is `not-taken` and an indeterminate result is `indeterminate`. A transition without a condition is `taken`. Conditions are evaluated for every transition regardless of the state of its source.
+ * @param model - The model whose transitions are evaluated.
+ * @param overlay - Run state, read by `elementStatusKey` references.
+ * @param facts - The injected source of facts.
+ * @returns The outcome of every transition, in transition order.
+ * @throws UnsupportedConditionError when a condition contains a `lookup`, `some`, `every` or fold node.
+ */
+declare const evaluateBranches: <I extends IdSpace>(model: Model<I>, overlay: Readonly<Overlay<I>>, facts: Facts) => ReadonlyMap<I["transition"], Branch>;
+//#endregion
+//#region ../../core/graph/dag/dist/dag.d.ts
+/**
+ * The identifier of a node. Restricted to primitives so that two ids denote the same node exactly when they are strictly equal.
+ */
+type NodeId = string | number;
+/**
+ * A `needs` target that is not a node of the graph, reported as data instead of being absorbed.
+ */
+interface UnknownReference<Id extends NodeId> {
+  /** The node whose `needs` named the missing target. */
+  readonly from: Id;
+  /** The target that is not a node. */
+  readonly missing: Id;
+}
+/**
+ * An immutable snapshot of a dependency graph: every node, the direct `needs` of each, the inverse relation, and the references that pointed outside the node set.
+ *
+ * The type does not promise acyclicity: a graph built from arbitrary input may contain cycles, which `findCycles` reports and the operations that need acyclicity document how they treat. Nothing here may be mutated by a caller.
+ */
+interface Dag<Id extends NodeId> {
+  /** Every node once, in the order the input first produced it. All other orderings in this package derive from this one. */
+  readonly nodes: readonly Id[];
+  /** For every node, the nodes it directly needs, without duplicates, in the order `needs` produced them, restricted to nodes of the graph. */
+  readonly needs: ReadonlyMap<Id, readonly Id[]>;
+  /** For every node, the nodes that directly need it, in node order. The inverse of `needs`. */
+  readonly dependents: ReadonlyMap<Id, readonly Id[]>;
+  /** Every `needs` target that is not a node, once per `{ from, missing }` pair, in node order and then `needs` order. These are not edges of the graph. */
+  readonly unknownReferences: readonly UnknownReference<Id>[];
+}
+/**
+ * Builds a graph once from a node set and a `needs` accessor.
+ *
+ * `nodes` is iterated once and duplicates are dropped, keeping the first occurrence. `needs` is called exactly once per distinct node, in node order, and its result is iterated once. A target that is not a node is recorded in `unknownReferences` and is not an edge. A node may need itself; that is a cycle of one, reported by `findCycles`.
+ *
+ * Never throws for malformed structure: cycles and unknown references are data on the result and in the analyses.
+ * @param nodes - Every node of the graph.
+ * @param needs - The direct needs of a node: the nodes that must come before it.
+ */
+declare function buildDag<Id extends NodeId>(nodes: Readonly<Iterable<Id>>, needs: (id: Id) => Iterable<Id>): Dag<Id>;
+//#endregion
+//#region ../../core/graph/dag/dist/critical-path.d.ts
+/**
+ * The most expensive chain through a graph.
+ */
+interface CriticalPath<Id extends NodeId> {
+  /** The chain in dependency order: each node needs the one before it. Empty only for a graph with no nodes. */
+  readonly path: readonly Id[];
+  /** The sum of the weights of the nodes on `path`. */
+  readonly weight: number;
+}
+/**
+ * The longest weighted chain along `needs`, where a chain's weight is the sum of its nodes' weights.
+ *
+ * `weight` is called exactly once per node, in node order, and must return a finite number that is not negative. The returned path always runs back to a node with no needs and ends at the node whose chain is heaviest.
+ *
+ * Ties are broken deterministically, and the rule is part of the contract. Where several needs of a node give an equally heavy chain, the one that comes first in node order is followed. Where several nodes end an equally heavy chain, the one that comes first in node order ends it. A zero-weight node therefore never shortens the path back to the start, and a zero-weight dependent never extends the path past an earlier node of equal total.
+ *
+ * Defined for acyclic graphs. An empty graph returns `{ path: [], weight: 0 }`. Unknown references are not edges.
+ * @throws CycleError when the graph contains a cycle: a chain through a cycle has no greatest weight.
+ * @throws RangeError when `weight` returns a negative or non-finite number.
+ */
+declare function criticalPath$1<Id extends NodeId>(dag: Dag<Id>, weight: (id: Id) => number): CriticalPath<Id>;
+//#endregion
+//#region ../../core/graph/domain/dist/control.d.ts
+/**
+ * The transitions that re-enter earlier work: a transition leaving a `decision` element whose target can reach its source (or is its source), so that it closes a cycle through the decision.
+ *
+ * Reachability is over the whole graph, transitions and artefact dependencies alike. Only a decision's own outgoing transitions are candidates: a cycle that contains no decision has no loop edge and is illegal.
+ * @param model - The model to read.
+ * @returns The loop transitions, in transition order.
+ * @throws UnknownNodeError when such a transition's target is not an element of the model.
+ */
+declare const loopTransitions: <I extends IdSpace>(model: Model<I>) => readonly I["transition"][];
+/**
+ * The control graph the whole analysis is computed on, with the loop edges removed.
+ *
+ * Its nodes are the element ids. A node needs the source of every incoming transition that is not a loop edge (see `loopTransitions`) and, for an activity, the producer of every artefact in `consumes`. Excluding loop edges makes a legal retry or review loop acyclic here, so readiness, layers and the critical path are well defined: a loop edge is a way back to earlier work, never a prerequisite of it. A node whose only incoming transitions are loop edges therefore has no needs.
+ *
+ * The graph is not guaranteed acyclic: cycles that no decision closes remain and are reported by `illegalCycles`. A transition whose source is not an element appears in `unknownReferences`.
+ * @param model - The model to read.
+ * @returns The graph over element ids, as a `graph-dag` `Dag`.
+ * @throws UnknownNodeError when a decision's transition targets something that is not an element.
+ */
+declare const controlDag: <I extends IdSpace>(model: Model<I>) => Dag<I["element"]>;
+/**
+ * The cycles of the control graph: every cycle that is not a legal decision loop.
+ *
+ * A cycle that passes through a `decision` element is a legal loop and is not reported; the loop edge that closes it is left out of `controlDag`. Any cycle that remains has no decision in it, so it can never make progress, and is reported with its path.
+ *
+ * A path follows `graph-dag`'s convention: each element needs the next one and the last needs the first, which is repeated at the end. `["a", "b", "a"]` means a needs b and b needs a. One path is reported per strongly connected component; break it and call again for the rest.
+ * @param model - The model to read.
+ * @returns The illegal cycles, empty exactly when every cycle is a legal decision loop.
+ * @throws UnknownNodeError when a decision's transition targets something that is not an element.
+ */
+declare const illegalCycles: <I extends IdSpace>(model: Model<I>) => readonly (readonly I["element"][])[];
+//#endregion
+//#region ../../core/graph/domain/dist/derive.d.ts
+/** Which of the derivation's rules decided an element's status, in the order the rules are applied. */
+declare const statusRules: readonly ["overlay-done", "overlay-unknown", "unknown-need", "all-cut", "needs-met", "waiting"];
+/**
+ * Which rule decided a status.
+ *
+ * - `overlay-done`: the overlay says `done`.
+ * - `overlay-unknown`: the overlay says `unknown`.
+ * - `unknown-need`: a live transition's condition is indeterminate or its source is `unknown`, or a consumed artefact that is not provided and has no done producer has an `unknown` producer.
+ * - `all-cut`: the element has incoming transitions and every one is cut, so it is `skipped`.
+ * - `needs-met`: every live need is done and every consumed artefact is satisfied, so it is `ready`, or `done` for a decision or pseudo-state.
+ * - `waiting`: anything else, so it is `blocked`.
+ */
+type StatusRule = (typeof statusRules)[number];
+/** An incoming transition of an element, as the derivation saw it. Loop edges are not incoming transitions. */
+interface IncomingBasis<I extends IdSpace> {
+  readonly transition: I["transition"];
+  readonly source: I["element"];
+  /** What the transition's condition evaluated to. */
+  readonly branch: Branch;
+  /** The derived status of the source. */
+  readonly sourceStatus: Status;
+  /** Whether the transition is cut: its condition is definitely false or its source is skipped. A cut transition is not a need. */
+  readonly cut: boolean;
+}
+/** A producer of a consumed artefact and its derived status. */
+interface ProducerBasis<I extends IdSpace> {
+  readonly element: I["element"];
+  readonly status: Status;
+}
+/** A consumed artefact of an activity, as the derivation saw it. */
+interface ArtefactBasis<I extends IdSpace> {
+  readonly artefact: I["artefact"];
+  /** Whether the facts port reports it provided from outside the process. */
+  readonly provided: boolean;
+  /** The activities that produce it, in model order. Empty when none does. */
+  readonly producers: readonly ProducerBasis<I>[];
+  /** Whether it is provided or a producer is done. */
+  readonly satisfied: boolean;
+}
+/** What one element's status was derived from. */
+interface StatusBasis<I extends IdSpace> {
+  readonly rule: StatusRule;
+  /** The element's incoming transitions other than loop edges, in model order. */
+  readonly transitions: readonly IncomingBasis<I>[];
+  /** The artefacts the element consumes, in the order it lists them; empty for anything but an activity. */
+  readonly artefacts: readonly ArtefactBasis<I>[];
+}
+/**
+ * The derived status of every element. See `analyse` for the rules; the semantics are documented in the package README.
+ * @param model - The model to read.
+ * @param overlay - Run state by element id.
+ * @param facts - The injected source of facts conditions read, and of which input artefacts are provided (see `artefactKey`).
+ * @returns A status for every element, in model order.
+ * @throws CycleError when the control graph contains an illegal cycle (see `illegalCycles`), since status is undefined on it.
+ * @throws UnknownNodeError when a transition refers to an element the model does not declare.
+ * @throws UnsupportedConditionError when a condition needs a table or collection from the facts port.
+ */
+declare const deriveStatuses: <I extends IdSpace>(model: Model<I>, overlay: Readonly<Overlay<I>>, facts: Facts) => ReadonlyMap<I["element"], Status>;
+//#endregion
+//#region ../../core/graph/domain/dist/explain.d.ts
+/** One element of a blocked-by chain and the unfinished needs it still waits on. */
+interface ChainLink<I extends IdSpace> {
+  readonly element: I["element"];
+  readonly status: Status;
+  /** The element's live needs that are not done, in model order. Empty for the open work at the end of the chain. */
+  readonly waitingOn: readonly I["element"][];
+}
+/** Why an element has the status it has. */
+interface StatusExplanation<I extends IdSpace> {
+  readonly element: I["element"];
+  readonly status: Status;
+  /** The rule that decided the status. */
+  readonly rule: StatusRule;
+  /** The element's incoming transitions other than loop edges, each with its branch, its source's status and whether it is cut, in model order. */
+  readonly transitions: readonly IncomingBasis<I>[];
+  /** The artefacts the element consumes, each with whether it is provided and its producers' statuses. */
+  readonly artefacts: readonly ArtefactBasis<I>[];
+  /**
+   * The blocked-by chain: the element, then every unfinished need reached from it by following unfinished needs, in model order. The links after the first that wait on nothing are the elements `blockedBy` returns. A done or skipped element waits on nothing, so its chain is the element alone.
+   */
+  readonly chain: readonly ChainLink<I>[];
+}
+/**
+ * Explains an element's status: the rule that decided it, the transitions and artefacts it was decided from, and the chain of unfinished work behind it. The explanation is the derivation's own record, so it always agrees with `deriveStatuses` and `blockedBy`.
+ * @param model - The model to read.
+ * @param overlay - Run state by element id.
+ * @param facts - The injected source of facts conditions read, and of which input artefacts are provided.
+ * @param id - The element asked about.
+ * @returns The explanation.
+ * @throws UnknownNodeError when `id` is not an element.
+ * @throws CycleError when the control graph has an illegal cycle.
+ */
+declare const explainStatus: <I extends IdSpace>(model: Model<I>, overlay: Readonly<Overlay<I>>, facts: Facts, id: I["element"]) => StatusExplanation<I>;
+//#endregion
+//#region ../../core/graph/domain/dist/queries.d.ts
+/**
+ * The elements that can be worked on now: every element whose status is `ready`, in model order. Pure control elements (decisions and pseudo-states) are derived `done` and never appear.
+ * @param model - The model to read.
+ * @param overlay - Run state by element id.
+ * @param facts - The injected source of facts conditions read, and of which input artefacts are provided.
+ * @returns The ready elements.
+ * @throws CycleError when the control graph has an illegal cycle.
+ */
+declare const readySet: <I extends IdSpace>(model: Model<I>, overlay: Readonly<Overlay<I>>, facts: Facts) => readonly I["element"][];
+/**
+ * What is holding an element back: the minimal set of open elements to finish first.
+ *
+ * Starting from the element's unfinished needs, follows each one's own unfinished needs until it reaches elements that wait on nothing further, and returns exactly those leaves, in model order. Cut transitions (a branch not taken, a skipped source) and provided artefacts are not needs. A leaf is open work that is `ready`, or an element whose own state or condition is `unknown`. An element that is `done`, `skipped` or `ready` is blocked by nothing, and neither is one whose only obstacle is its own unknown state.
+ * @param model - The model to read.
+ * @param overlay - Run state by element id.
+ * @param facts - The injected source of facts conditions read, and of which input artefacts are provided.
+ * @param id - The element asked about.
+ * @returns The leaves of the unfinished-needs closure, in model order.
+ * @throws UnknownNodeError when `id` is not an element.
+ * @throws CycleError when the control graph has an illegal cycle.
+ */
+declare const blockedBy: <I extends IdSpace>(model: Model<I>, overlay: Readonly<Overlay<I>>, facts: Facts, id: I["element"]) => readonly I["element"][];
+/**
+ * What finishing, delaying or dropping an element affects: the elements that transitively depend on it through paths that are still live.
+ *
+ * Traversal follows each dependent's live needs (see `Analysis.liveNeeds`), so a transition cut by a branch not taken, a skipped element and a loop edge carry no impact, and an element already `done` is neither affected nor traversed through. The element itself is not included.
+ * @param model - The model to read.
+ * @param overlay - Run state by element id.
+ * @param facts - The injected source of facts conditions read, and of which input artefacts are provided.
+ * @param id - The element asked about.
+ * @returns The affected elements, in model order.
+ * @throws UnknownNodeError when `id` is not an element.
+ * @throws CycleError when the control graph has an illegal cycle.
+ */
+declare const impact: <I extends IdSpace>(model: Model<I>, overlay: Readonly<Overlay<I>>, facts: Facts, id: I["element"]) => readonly I["element"][];
+/** A status that changed. */
+interface StatusChange<I extends IdSpace> {
+  readonly id: I["element"];
+  readonly before: Status;
+  readonly after: Status;
+}
+/** The effect of finishing one element. */
+interface WhatIf<I extends IdSpace> {
+  /** Elements that were not ready and become ready, in model order. */
+  readonly becomesReady: readonly I["element"][];
+  /** Every element whose status changes, in model order. Includes the finished element itself unless it was done already. */
+  readonly changes: readonly StatusChange<I>[];
+}
+/**
+ * Derives the run again with an element marked `done` in the overlay and reports what changes. Nothing is mutated.
+ * @param model - The model to read.
+ * @param overlay - Run state by element id.
+ * @param facts - The injected source of facts conditions read, and of which input artefacts are provided.
+ * @param id - The element to finish.
+ * @returns The elements that become ready and every status change.
+ * @throws UnknownNodeError when `id` is not an element.
+ * @throws CycleError when the control graph has an illegal cycle.
+ */
+declare const whatIfDone: <I extends IdSpace>(model: Model<I>, overlay: Readonly<Overlay<I>>, facts: Facts, id: I["element"]) => WhatIf<I>;
+/**
+ * The heaviest chain through the work that is still ahead: the live elements, those that are neither `done` nor `skipped`, ordered by the live needs that are themselves live.
+ *
+ * A finished or skipped element contributes nothing and does not appear. The chain is computed with `graph-dag`'s `criticalPath`, so its tie-breaking rule holds (the earliest element in model order wins).
+ * @param model - The model to read.
+ * @param overlay - Run state by element id.
+ * @param facts - The injected source of facts conditions read, and of which input artefacts are provided.
+ * @param weight - The cost of an element: finite and not negative.
+ * @returns The path in dependency order and its total weight; empty when nothing is live.
+ * @throws RangeError when `weight` returns a negative or non-finite number.
+ * @throws CycleError when the control graph has an illegal cycle.
+ */
+declare const criticalPath: <I extends IdSpace>(model: Model<I>, overlay: Readonly<Overlay<I>>, facts: Facts, weight: (id: I["element"]) => number) => CriticalPath<I["element"]>;
+/** A deliverable artefact that has not been produced yet and what it still takes. */
+interface UnmetOutput<I extends IdSpace> {
+  readonly artefact: I["artefact"];
+  /** The activities that declare they produce it. Empty when none does, so it can never be produced. */
+  readonly producers: readonly I["element"][];
+  /** The open elements still needed to produce it: its unfinished producers and, transitively, every unfinished live need of those, in model order. */
+  readonly needed: readonly I["element"][];
+  /** The artefacts among those needs that nothing produces and the run has not provided, in declaration order. */
+  readonly missingInputs: readonly I["artefact"][];
+}
+/**
+ * Every deliverable artefact that is still to be produced, with what is needed to produce it.
+ *
+ * A deliverable is met when it is provided or one of its producers is `done`. An unmet one lists its producers, the unfinished elements that must finish (its unfinished producers and everything those transitively wait on, skipped elements excluded) and the inputs that no one produces and nobody has provided, so a deliverable that can only ever be reached through an unproduced input shows exactly which input is missing.
+ * @param model - The model to read.
+ * @param overlay - Run state by element id.
+ * @param facts - The injected source of facts conditions read, and of which input artefacts are provided.
+ * @returns One entry per unmet deliverable, in declaration order.
+ * @throws CycleError when the control graph has an illegal cycle.
+ */
+declare const unmetOutputs: <I extends IdSpace>(model: Model<I>, overlay: Readonly<Overlay<I>>, facts: Facts) => readonly UnmetOutput<I>[];
+//#endregion
+export { UnsupportedConditionError as A, CriticalPath as C, UnknownReference as D, NodeId as E, Status as F, statuses as I, elementStatusKey as M, evaluateBranches as N, buildDag as O, Branch as P, loopTransitions as S, Dag as T, StatusRule as _, criticalPath as a, controlDag as b, unmetOutputs as c, StatusExplanation as d, explainStatus as f, StatusBasis as g, ProducerBasis as h, blockedBy as i, artefactKey as j, Facts as k, whatIfDone as l, IncomingBasis as m, UnmetOutput as n, impact as o, ArtefactBasis as p, WhatIf as r, readySet as s, StatusChange as t, ChainLink as u, deriveStatuses as v, criticalPath$1 as w, illegalCycles as x, statusRules as y };