light-plan 0.0.0-stage → 0.1.0

package/dist/shared/cohesion.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The single definition of "which container is already under way?", so the
+ * engine and the browser cannot disagree about which of two unrelated features
+ * a queue should stay inside.
+ *
+ * A queue that ranks two ready stories only by priority, column and id will
+ * happily hand out one story from every feature on the board in turn: nothing
+ * in that order knows that somebody already finished two stories in the first
+ * feature and started a third. That is not a neutral order — it is the board
+ * telling a team to context-switch, and it leaves half-built features open all
+ * over the plan. So work whose container is already moving is offered before
+ * work whose container has not been touched.
+ *
+ * The rule is about *containers*, and it is asked from the root down: two
+ * candidates are compared by the first ancestor they do not share, which is the
+ * one level where they are genuinely alternatives. Stories in the same feature
+ * are never separated by it, and a story in an ongoing epic is preferred to one
+ * in an untouched epic before their features are ever consulted.
+ *
+ * Import-free by design: core adapts a `LoadedBoard` to `CohesionLookup` and
+ * the browser adapts its working copy, exactly as they both do for
+ * `work-unit.ts` and `blocking.ts`.
+ */
+/** The minimal shape the progress walk needs from a board. */
+export interface CohesionLookup {
+    parentOf(id: string): string | null;
+    childIdsOf(id: string): string[];
+    /** Whether the board offers this id as one piece of work. */
+    isWorkUnit(id: string): boolean;
+    isTerminal(id: string): boolean;
+    isActive(id: string): boolean;
+}
+/**
+ * How far the work inside one container has got.
+ *
+ * Counted over the **work units** underneath it at any depth — the things the
+ * board would actually hand somebody — and never over the containers in
+ * between, whose status is derived from those same units and would be counted
+ * twice. What is inside an atomic unit is that unit's checklist, not work of
+ * its own, so the walk stops there.
+ */
+export interface ContainerProgress {
+    /** Work units inside, at any depth. Zero for a leaf. */
+    total: number;
+    /** Of those, the ones in a terminal status. */
+    done: number;
+    /** Of those, the ones in an active status — work in flight right now. */
+    active: number;
+}
+/** @see ContainerProgress */
+export declare function containerProgress(id: string, lookup: CohesionLookup): ContainerProgress;
+/**
+ * Which of two containers a queue should stay inside, most ongoing first.
+ *
+ * Work in flight wins outright: the strongest reason not to open a third
+ * feature is that somebody is inside the second one right now. Failing that,
+ * the container closest to finished wins, measured as a *share* rather than a
+ * count so a large container does not outrank a small one merely by holding
+ * more work. An untouched container has neither and loses to both.
+ */
+export declare function compareProgress(a: ContainerProgress, b: ContainerProgress): number;
+/**
+ * Order two issues by how far along the part of the plan they sit in is.
+ *
+ * Built once per sort, because it caches the progress of every container it
+ * looks at and a board's statuses move underneath it between sorts (that is
+ * exactly what `simulateQueue` does, one step at a time).
+ *
+ * The comparison walks both lineages from the root and stops at the first
+ * ancestor the two do not share — the level at which the two issues really are
+ * alternatives. Two issues on the same chain (nothing to choose between) and
+ * two issues whose containers are equally under way both come back 0, leaving
+ * the caller's remaining tiebreaks to decide.
+ */
+export declare function progressComparator(lookup: CohesionLookup): (a: string, b: string) => number;

package/dist/shared/cohesion.js

@@ -0,0 +1,132 @@
+/**
+ * The single definition of "which container is already under way?", so the
+ * engine and the browser cannot disagree about which of two unrelated features
+ * a queue should stay inside.
+ *
+ * A queue that ranks two ready stories only by priority, column and id will
+ * happily hand out one story from every feature on the board in turn: nothing
+ * in that order knows that somebody already finished two stories in the first
+ * feature and started a third. That is not a neutral order — it is the board
+ * telling a team to context-switch, and it leaves half-built features open all
+ * over the plan. So work whose container is already moving is offered before
+ * work whose container has not been touched.
+ *
+ * The rule is about *containers*, and it is asked from the root down: two
+ * candidates are compared by the first ancestor they do not share, which is the
+ * one level where they are genuinely alternatives. Stories in the same feature
+ * are never separated by it, and a story in an ongoing epic is preferred to one
+ * in an untouched epic before their features are ever consulted.
+ *
+ * Import-free by design: core adapts a `LoadedBoard` to `CohesionLookup` and
+ * the browser adapts its working copy, exactly as they both do for
+ * `work-unit.ts` and `blocking.ts`.
+ */
+/** @see ContainerProgress */
+export function containerProgress(id, lookup) {
+    const progress = { total: 0, done: 0, active: 0 };
+    const seen = new Set([id]);
+    const walk = (parentId) => {
+        for (const childId of lookup.childIdsOf(parentId)) {
+            // A hand-edited or merged board can name a parent that names it back;
+            // the walk terminates rather than hanging whoever asked.
+            if (seen.has(childId))
+                continue;
+            seen.add(childId);
+            if (lookup.isWorkUnit(childId)) {
+                progress.total += 1;
+                if (lookup.isTerminal(childId))
+                    progress.done += 1;
+                else if (lookup.isActive(childId))
+                    progress.active += 1;
+                continue;
+            }
+            walk(childId);
+        }
+    };
+    walk(id);
+    return progress;
+}
+/** The share of the work inside that is finished; zero for an empty container. */
+function completion(progress) {
+    return progress.total ? progress.done / progress.total : 0;
+}
+/**
+ * Which of two containers a queue should stay inside, most ongoing first.
+ *
+ * Work in flight wins outright: the strongest reason not to open a third
+ * feature is that somebody is inside the second one right now. Failing that,
+ * the container closest to finished wins, measured as a *share* rather than a
+ * count so a large container does not outrank a small one merely by holding
+ * more work. An untouched container has neither and loses to both.
+ */
+export function compareProgress(a, b) {
+    const inFlight = Number(b.active > 0) - Number(a.active > 0);
+    if (inFlight !== 0)
+        return inFlight;
+    const finished = completion(b) - completion(a);
+    if (finished !== 0)
+        return finished < 0 ? -1 : 1;
+    return 0;
+}
+/** A node's ancestors, outermost first, ending with the node itself. */
+function lineageOf(id, lookup) {
+    const chain = [id];
+    const seen = new Set([id]);
+    let parentId = lookup.parentOf(id);
+    while (parentId && !seen.has(parentId)) {
+        seen.add(parentId);
+        chain.unshift(parentId);
+        parentId = lookup.parentOf(parentId);
+    }
+    return chain;
+}
+/**
+ * Order two issues by how far along the part of the plan they sit in is.
+ *
+ * Built once per sort, because it caches the progress of every container it
+ * looks at and a board's statuses move underneath it between sorts (that is
+ * exactly what `simulateQueue` does, one step at a time).
+ *
+ * The comparison walks both lineages from the root and stops at the first
+ * ancestor the two do not share — the level at which the two issues really are
+ * alternatives. Two issues on the same chain (nothing to choose between) and
+ * two issues whose containers are equally under way both come back 0, leaving
+ * the caller's remaining tiebreaks to decide.
+ */
+export function progressComparator(lookup) {
+    const cache = new Map();
+    const progressOf = (id) => {
+        const known = cache.get(id);
+        if (known)
+            return known;
+        const computed = containerProgress(id, lookup);
+        cache.set(id, computed);
+        return computed;
+    };
+    const lineages = new Map();
+    const lineage = (id) => {
+        const known = lineages.get(id);
+        if (known)
+            return known;
+        const computed = lineageOf(id, lookup);
+        lineages.set(id, computed);
+        return computed;
+    };
+    return (a, b) => {
+        if (a === b)
+            return 0;
+        const left = lineage(a);
+        const right = lineage(b);
+        const depth = Math.min(left.length, right.length);
+        for (let index = 0; index < depth; index += 1) {
+            const here = left[index];
+            const there = right[index];
+            if (here === there)
+                continue;
+            return compareProgress(progressOf(here), progressOf(there));
+        }
+        // One is an ancestor of the other: they are not alternatives at any level.
+        return 0;
+    };
+}
+//# sourceMappingURL=cohesion.js.map

package/dist/shared/cohesion.js.map

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

package/dist/shared/dependency-rollup.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The single definition of "which containers does a dependency between two
+ * pieces of work put in order?", so the engine
+ * (`core/board/dependency-rollup.ts`) and the browser
+ * (`web/src/lib/board/selectors.ts`) cannot disagree about it.
+ *
+ * A dependency is written between the two documents that actually have the
+ * relationship — a story waits on a story — and that is the right place for it:
+ * it is what the queue reads, and writing it any higher would block work that
+ * is not waiting on anything. But it is not where the relationship is *read*.
+ * Somebody looking at a feature, an epic or a whole increment asks "what does
+ * this wait on", and until now the answer at every level above the story was
+ * "nothing", which is not true and is exactly what makes a large plan hard to
+ * trust. So the edge is reflected upward: the two features the two stories sit
+ * in stand in the same order, the two epics above them do, and so on until the
+ * container they share, inside which there is nothing left to order.
+ *
+ * Four rules, and the reflection is wrong without any of them:
+ *
+ *   - **It stops at the common parent.** Two stories in one feature order
+ *     nothing above them: the feature waits on itself, which is not a fact
+ *     anybody can act on. Everything strictly below the lowest common ancestor
+ *     is reflected, and nothing at or above it is.
+ *   - **The two chains are paired from the common parent downward**, not from
+ *     the stories upward. The chains are rarely the same length — a story can
+ *     wait on a whole feature — and pairing from the top is what keeps the
+ *     outermost pair (the two epics) aligned, which is the pair a reader
+ *     starting from the top of the board sees first. When one chain runs out,
+ *     its last member stands for the rest of it, so the deeper side still
+ *     reports what it waits on at every level it has.
+ *   - **Nothing is written to a document.** This is a reading of the graph, the
+ *     way `board.dependents` is, and it is deliberately *not* a `depends_on`
+ *     edge on the container. Two reasons, either of them decisive. A stored
+ *     edge would be inherited by everything inside the container, so one story
+ *     waiting on one story would stop every other story in the feature — the
+ *     board would say a dozen things are blocked that are not. And the
+ *     reflection is not acyclic: two features that each contain a story
+ *     waiting on the other are an ordinary plan, and rolling that up produces
+ *     a loop the cycle check would have to refuse, which would mean refusing
+ *     the second story link. Reflected edges are read, never gated, so a loop
+ *     among them is a fact about the plan and not a stall.
+ *   - **An edge somebody wrote is never reported as a reflection of another
+ *     one.** If the two features already declare the dependency, that is the
+ *     document's own word and the surfaces show it as such; repeating it as
+ *     derived would say the same thing twice with two different meanings.
+ *
+ * Imports nothing, so it compiles for Node and for the browser alike.
+ */
+/** Everything the walk needs about the issue tree, asked by id. */
+export interface HierarchyLookup {
+    /** The issue this one sits under, or null at the top of the collection. */
+    parentOf(id: string): string | null;
+}
+/** A dependency as it is written down: `from` waits on `to`. */
+export interface DependencyEdge {
+    from: string;
+    to: string;
+}
+/** A dependency two containers are in because of work inside them. */
+export interface RolledUpDependency extends DependencyEdge {
+    /** The written dependency this reflects — `source` waits on `target`. */
+    source: string;
+    target: string;
+    /**
+     * How deep below the common parent this pair sits: 0 is the pair directly
+     * inside it, 1 the pair inside that. Reported nearest the written edge
+     * first, so the highest `level` comes first.
+     */
+    level: number;
+}
+/**
+ * The containers one written dependency puts in order, nearest the written
+ * edge first.
+ *
+ * Empty when there is nothing above the edge to order: the two ends sit in the
+ * same container, or one of them is inside the other — an issue cannot be made
+ * to wait on the container it is part of.
+ */
+export declare function rollUpDependency(edge: DependencyEdge, lookup: HierarchyLookup): RolledUpDependency[];
+/**
+ * Every dependency the containers on a board are in because of the work inside
+ * them, each pair reported once.
+ *
+ * `edges` is every dependency written on the board. Both ends of each one are
+ * expected to exist — a dangling id is a problem for `check` to report, and
+ * reflecting one would put a container in order behind nothing.
+ *
+ * A pair that is already written down is left out: it is that document's own
+ * dependency, and the surfaces show it as one.
+ */
+export declare function rollUpDependencies(edges: readonly DependencyEdge[], lookup: HierarchyLookup): RolledUpDependency[];

package/dist/shared/dependency-rollup.js

@@ -0,0 +1,132 @@
+/**
+ * The single definition of "which containers does a dependency between two
+ * pieces of work put in order?", so the engine
+ * (`core/board/dependency-rollup.ts`) and the browser
+ * (`web/src/lib/board/selectors.ts`) cannot disagree about it.
+ *
+ * A dependency is written between the two documents that actually have the
+ * relationship — a story waits on a story — and that is the right place for it:
+ * it is what the queue reads, and writing it any higher would block work that
+ * is not waiting on anything. But it is not where the relationship is *read*.
+ * Somebody looking at a feature, an epic or a whole increment asks "what does
+ * this wait on", and until now the answer at every level above the story was
+ * "nothing", which is not true and is exactly what makes a large plan hard to
+ * trust. So the edge is reflected upward: the two features the two stories sit
+ * in stand in the same order, the two epics above them do, and so on until the
+ * container they share, inside which there is nothing left to order.
+ *
+ * Four rules, and the reflection is wrong without any of them:
+ *
+ *   - **It stops at the common parent.** Two stories in one feature order
+ *     nothing above them: the feature waits on itself, which is not a fact
+ *     anybody can act on. Everything strictly below the lowest common ancestor
+ *     is reflected, and nothing at or above it is.
+ *   - **The two chains are paired from the common parent downward**, not from
+ *     the stories upward. The chains are rarely the same length — a story can
+ *     wait on a whole feature — and pairing from the top is what keeps the
+ *     outermost pair (the two epics) aligned, which is the pair a reader
+ *     starting from the top of the board sees first. When one chain runs out,
+ *     its last member stands for the rest of it, so the deeper side still
+ *     reports what it waits on at every level it has.
+ *   - **Nothing is written to a document.** This is a reading of the graph, the
+ *     way `board.dependents` is, and it is deliberately *not* a `depends_on`
+ *     edge on the container. Two reasons, either of them decisive. A stored
+ *     edge would be inherited by everything inside the container, so one story
+ *     waiting on one story would stop every other story in the feature — the
+ *     board would say a dozen things are blocked that are not. And the
+ *     reflection is not acyclic: two features that each contain a story
+ *     waiting on the other are an ordinary plan, and rolling that up produces
+ *     a loop the cycle check would have to refuse, which would mean refusing
+ *     the second story link. Reflected edges are read, never gated, so a loop
+ *     among them is a fact about the plan and not a stall.
+ *   - **An edge somebody wrote is never reported as a reflection of another
+ *     one.** If the two features already declare the dependency, that is the
+ *     document's own word and the surfaces show it as such; repeating it as
+ *     derived would say the same thing twice with two different meanings.
+ *
+ * Imports nothing, so it compiles for Node and for the browser alike.
+ */
+/** An issue and everything above it, nearest first. Cycle-safe. */
+function lineageOf(id, lookup) {
+    const chain = [];
+    const seen = new Set();
+    let current = id;
+    while (current && !seen.has(current)) {
+        seen.add(current);
+        chain.push(current);
+        current = lookup.parentOf(current);
+    }
+    return chain;
+}
+/**
+ * The containers one written dependency puts in order, nearest the written
+ * edge first.
+ *
+ * Empty when there is nothing above the edge to order: the two ends sit in the
+ * same container, or one of them is inside the other — an issue cannot be made
+ * to wait on the container it is part of.
+ */
+export function rollUpDependency(edge, lookup) {
+    if (edge.from === edge.to)
+        return [];
+    const waiting = lineageOf(edge.from, lookup);
+    const blocking = lineageOf(edge.to, lookup);
+    const blockingAt = new Map(blocking.map((id, index) => [id, index]));
+    // The lowest common ancestor: the first id above the waiting end that also
+    // stands above (or is) the blocking end. Either chain being empty afterwards
+    // means one end contains the other, and there is nothing to reflect.
+    let waitingCut = waiting.length;
+    let blockingCut = blocking.length;
+    for (const [index, id] of waiting.entries()) {
+        const found = blockingAt.get(id);
+        if (found === undefined)
+            continue;
+        waitingCut = index;
+        blockingCut = found;
+        break;
+    }
+    const above = waiting.slice(0, waitingCut).reverse();
+    const under = blocking.slice(0, blockingCut).reverse();
+    if (!above.length || !under.length)
+        return [];
+    const out = [];
+    const levels = Math.max(above.length, under.length);
+    for (let level = 0; level < levels; level += 1) {
+        const from = above[Math.min(level, above.length - 1)];
+        const to = under[Math.min(level, under.length - 1)];
+        // The last pair is the written edge itself on boards where both chains run
+        // to the bottom; it is the fact being reflected, not a reflection of it.
+        if (from === edge.from && to === edge.to)
+            continue;
+        out.push({ from, to, source: edge.from, target: edge.to, level });
+    }
+    return out.reverse();
+}
+/**
+ * Every dependency the containers on a board are in because of the work inside
+ * them, each pair reported once.
+ *
+ * `edges` is every dependency written on the board. Both ends of each one are
+ * expected to exist — a dangling id is a problem for `check` to report, and
+ * reflecting one would put a container in order behind nothing.
+ *
+ * A pair that is already written down is left out: it is that document's own
+ * dependency, and the surfaces show it as one.
+ */
+export function rollUpDependencies(edges, lookup) {
+    const key = (from, to) => `${from}->${to}`;
+    const written = new Set(edges.map((edge) => key(edge.from, edge.to)));
+    const seen = new Set();
+    const out = [];
+    for (const edge of edges) {
+        for (const rolled of rollUpDependency(edge, lookup)) {
+            const id = key(rolled.from, rolled.to);
+            if (written.has(id) || seen.has(id))
+                continue;
+            seen.add(id);
+            out.push(rolled);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=dependency-rollup.js.map

package/dist/shared/dependency-rollup.js.map

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

package/dist/shared/errors.d.ts

@@ -0,0 +1,23 @@
+/** The body of every non-2xx API response. */
+export interface ApiErrorBody {
+    error: string;
+    /** The `details` of a BoardError: hints about how to fix it. */
+    details?: string[];
+}
+/** One failed change in a push, reported alongside the ones that succeeded. */
+export interface PushFailure {
+    /** Id of the change that failed, temporary ids included. */
+    id: string;
+    error: string;
+    details?: string[];
+}
+/**
+ * The distinct reasons a push was rejected, in the order they were hit.
+ *
+ * One bad change holds up every change that referenced it: a sprint the board
+ * refuses takes down the eighty issues scheduled into it, and a list of eighty-
+ * one lines buries the one thing that actually went wrong under eighty copies
+ * of its consequence. Grouping by message puts the cause on the first line and
+ * says how much rode on it.
+ */
+export declare function summarizePushFailures(failures: PushFailure[], limit?: number): string[];

package/dist/shared/errors.js

@@ -0,0 +1,24 @@
+/**
+ * The distinct reasons a push was rejected, in the order they were hit.
+ *
+ * One bad change holds up every change that referenced it: a sprint the board
+ * refuses takes down the eighty issues scheduled into it, and a list of eighty-
+ * one lines buries the one thing that actually went wrong under eighty copies
+ * of its consequence. Grouping by message puts the cause on the first line and
+ * says how much rode on it.
+ */
+export function summarizePushFailures(failures, limit = 6) {
+    const grouped = new Map();
+    for (const failure of failures) {
+        const ids = grouped.get(failure.error);
+        if (ids)
+            ids.push(failure.id);
+        else
+            grouped.set(failure.error, [failure.id]);
+    }
+    const lines = [...grouped].map(([error, ids]) => ids.length === 1 ? `${ids[0]}: ${error}` : `${ids.length} changes — ${error}`);
+    return lines.length > limit
+        ? [...lines.slice(0, limit), `…and ${lines.length - limit} more`]
+        : lines;
+}
+//# sourceMappingURL=errors.js.map

package/dist/shared/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAeA;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAuB,EAAE,KAAK,GAAG,CAAC;IACtE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC5C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,GAAG;YAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;;YACzB,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;IAChD,CAAC;IACD,MAAM,KAAK,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,EAAE,CAC9C,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,cAAc,KAAK,EAAE,CAC9E,CAAC;IACF,OAAO,KAAK,CAAC,MAAM,GAAG,KAAK;QACzB,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,QAAQ,KAAK,CAAC,MAAM,GAAG,KAAK,OAAO,CAAC;QACjE,CAAC,CAAC,KAAK,CAAC;AACZ,CAAC"}

package/dist/shared/flag-rollup.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The single definition of "does a container stand in front of stopped work?",
+ * so the engine (`core/board/flag-rollup.ts`), `lpm check` and the browser
+ * cannot disagree about which parents are showing red.
+ *
+ * A flag says work has stopped and needs a person. Whoever is running the plan
+ * reads the board from the top, and a story flagged four levels down was
+ * invisible from there: the epic looked like every other epic, and the only way
+ * to find the stall was to open everything. So a flag carries upward, the way a
+ * closed story closes its feature — `src/shared/rollup.ts` is the same idea
+ * applied to status, and this file is deliberately shaped like it.
+ *
+ * Four rules, and the roll-up is wrong without any of them:
+ *
+ *   - **A derived flag is a different word from a raised one.** `DERIVED_FLAG`
+ *     is the only value this writes and the only value it clears. A person
+ *     cannot raise it (`flagIssue` refuses it) and the roll-up never touches
+ *     `blocked`, `paused` or `help`, so "somebody stopped this" and "something
+ *     inside this stopped" stay two facts and the canvas can draw them
+ *     differently. Without that there is no way to clear a derived flag safely:
+ *     a feature nobody flagged and a feature somebody paused look identical.
+ *   - **A flag of the container's own outranks the derived one.** A feature
+ *     already flagged `paused` says something more specific than "work inside
+ *     stopped", and overwriting it would lose it. It is left exactly as it is.
+ *   - **Clearing follows the last flag out.** When nothing inside is flagged any
+ *     more, the derived flag goes — that is the whole of "if all the children
+ *     are not flagged, its flag should also be cleared", and it is what stops
+ *     the board silting up with red nobody can act on.
+ *   - **A leaf answers for itself.** A node with nothing inside it is never
+ *     touched by the roll-up, in either direction.
+ *
+ * Imports nothing, so it compiles for Node and for the browser alike.
+ */
+/**
+ * The flag a container carries because something inside it has stopped.
+ *
+ * Its own word rather than the child's, because the reason belongs to the issue
+ * that has it: a story flagged `help` needs a person, and the epic above it does
+ * not — what the epic has is stopped work somewhere underneath.
+ */
+export declare const DERIVED_FLAG = "inside";
+/** True for the flag the roll-up writes, as opposed to one somebody raised. */
+export declare function isDerivedFlag(flag: string | null | undefined): boolean;
+/** Everything the walk needs about the issue tree, asked by id. */
+export interface FlagLookup {
+    /** The issue this one sits under, or null at the top of the collection. */
+    parentOf(id: string): string | null;
+    /** The issues directly inside this one. */
+    childIdsOf(id: string): readonly string[];
+    /** The flag this issue carries, or null. */
+    flagOf(id: string): string | null;
+}
+/** A flag a parent should gain or lose, because of what is inside it. */
+export interface FlagRollup {
+    id: string;
+    from: string | null;
+    to: string | null;
+}
+/**
+ * The flag a parent holding these children should have, or null when the one it
+ * has already says the truth.
+ *
+ * `children` are the flags of the issues directly inside it — `null` for each
+ * one that is not flagged. A parent with nothing inside it answers for itself
+ * and is never touched.
+ */
+export declare function rolledUpFlag(current: string | null, children: readonly (string | null)[]): FlagRollup['to'] | undefined;
+/**
+ * Walk up from an issue whose flag just changed and report every ancestor that
+ * has to change with it, nearest first.
+ *
+ * `lookup.flagOf` must already answer with the *new* flag of everything that
+ * moved; each roll-up this returns is folded into the walk, so clearing the last
+ * flag in a feature clears the epic above it too.
+ *
+ * Stops at the first ancestor that does not change: nothing above it saw its
+ * contents change either.
+ */
+export declare function flagRollupsUpward(from: string, lookup: FlagLookup): FlagRollup[];
+/**
+ * Every parent on a board whose flag disagrees with what is inside it, in an
+ * order that can be applied as it stands.
+ *
+ * `ids` must be ordered deepest-first, so a feature is decided before the epic
+ * above it and one pass carries a flagged story all the way up. This is what
+ * `lpm check` reports and what `--fix` writes.
+ */
+export declare function flagRollupsAcross(ids: readonly string[], lookup: FlagLookup): FlagRollup[];