Skip to content

Commit 11c1326

Browse files
fix(lint)!: refuse a flow node no edge path from the start node reaches (#31287)
<!-- claude-projects-attribution: {"github_login":"os-project-manager"} --> _Requested by **Leehom** · [project thread](https://claude.ai/code/project/chan_01TenzsRopZj4jMbvjX8uz1X?thread=cmsg_01TenzsRopZj4jMbvjX8uz1XF9CLMiiKFscnGZpZTirGFK)_ Refs #31224 Clause-②: yes (narrowing) Metadata-protocol: narrowed Skills-docs: none — `skills/**` and `content/docs/**` teach only wired top-level flows; the edgeless examples in `content/docs/automation/flows.mdx` are region bodies, which this rule does not judge. The reasoning ships as the `os explain flow-node-unreachable` entry. ## 维护者速读 - **改了什么**:`@objectstack/lint` 的 `lintFlowPatterns` 新增一个 error 级发现 `flow-node-unreachable`:流程顶层某个节点从 start 节点出发沿任何边都走不到,就报出该节点、它为何永远不会执行、以及修法(从会执行的节点连一条边进来,或删掉它)。另加 `os explain` 条目、测试和一个 lint minor changeset。 - **为什么改**:#31224 第 C 项。引擎从 start 节点开始沿边执行,走不到的节点永远不跑,但流程照样解析、注册、显示为已配置,作者得不到任何提示。 - **为什么不放在 parse**:保存门 `protocol-save.ts:1429` 对每次保存(含草稿)都跑 `FlowSchema`,而 Studio 设计器删除节点时 `edgesAfterNodeRemoval` 会让后继节点断开。放在 parse 会让这类草稿直接存不了;放在 lint,草稿照存(发现写进 `_diagnostics`),发布被拒。 - **风险与回滚**:收窄:`os lint/validate/build` 和流程发布门会拒绝此前接受的流程。普查为零:objectstack 54 个流程 238 个节点、hotcrm 35 个流程 256 个节点,不可达均为 0(对照:分别有 184、221 个非 start 节点可达)。回滚即 revert。 - **两分钟验证**:`pnpm --filter @objectstack/lint exec vitest run src/lint-flow-patterns.test.ts`,预期 255 个全部通过,其中新 describe 的 10 条为本卡新增。 - **需要你做的**:无,席位做契约复审后落地。 ## What changes 1. `packages/lint/src/lint-flow-patterns.ts`: `FLOW_NODE_UNREACHABLE = 'flow-node-unreachable'` and `scanUnreachableNodes`, called from `lintFlowPatterns` once per flow over the top-level graph. A breadth-first walk from the first `start` node over every top-level edge; one finding per node it does not reach, `severity: 'error'`, at `flow 'NAME' · node 'ID' (TYPE)`. The message names the start node and says why the node never runs; the hint is "Add an edge into it from a node that runs, or delete the node." A second `start` node (unreached by construction: a run starts at the first one) gets its own hint: delete the extra start, and wire what follows it from a node that runs. - **Every edge type is a path**: default, conditional, fault and back. - **Exempt**: a `boundary_event` node and the nodes reached only from one (attached to its host by `boundaryConfig.attachedToNodeId`, not entered by an edge; its own contract owns its refusal). - **Not judged**: region bodies (a region is a single-entry acyclic graph, which `analyzeRegion` / `validateControlFlow` already hold, so every node in one is reached); a flow with no `start` node; a flow with an edge whose endpoint names no node (the flow parse refuses that edge first, and reporting its target here would prescribe the wrong cure). 2. `packages/lint/src/index.ts`: exports `FLOW_NODE_UNREACHABLE` beside the other flow rule ids. This new export is why `Clause-②` reads `yes (narrowing)` rather than the claim's `no (narrowing)`, following #29900's changeset (new rule id exports under a narrowing). 3. `packages/lint/src/rule-explanations.ts`: the `os explain flow-node-unreachable` entry (what reaches a node, what is not judged, why lint and not parse, the gate reach). 4. `.changeset/31224-flow-node-unreachable.md`: `'@objectstack/lint': minor`, BREAKING banner, ADR-0087 `not-required (no-migration-prescription)`: no key moves, and an unreached node never ran, so no rewrite keeps what the author meant. **Why lint, not the flow parse.** A first build put the rule in `FlowSchema.superRefine`. It was taken back out (the revert commit on this branch leaves `packages/spec` byte-identical to `main`) for this reason. The metadata save door safeParses `FlowSchema` on every save, drafts included (`packages/metadata-protocol/src/protocol-save.ts:1429`, 422 `INVALID_METADATA`). The Studio designer's node delete (`edgesAfterNodeRemoval`, `ui/packages/app-shell/src/views/metadata-admin/previews/flow-problems.ts:729`) bridges the gap only when the deleted node had exactly one in-edge and one out-edge, and otherwise leaves the successor unwired. A parse rule would refuse that draft save outright. **Doors the error reaches.** `lintFlowPatterns` is a `gating` authoring rule with `surfaces: CLI_AND_RUNTIME`, `runtimeTypes: ['flow']` (`packages/lint/src/authoring-rules.ts`), so: - `os lint`, `os validate` and `os build` fail on it. - The live flow save and the per-item and package publish refuse it (422). - A draft save stores, with the finding in `_diagnostics` (`valid: false`), and its publish refuses with the same words. No `packages/spec`, metadata-protocol source, runtime or `ui/` change. ## Tests - `packages/lint/src/lint-flow-patterns.test.ts`, new describe "a node no edge path from start reaches": - **Refused**: an orphan action node (error, `where`, message and hint pinned); a chain of two unreached nodes (one finding each); a second start node (its own hint); a cycle cut off from start. - **Controls (not flagged)**: nodes reached over conditional, fault and back edges; a `boundary_event` and the node only it leads to; no start node; a dangling edge; a loop region body. - **Registration**: the registered `lintFlowPatterns` authoring rule is `gating`, carries `runtimeTypes: ['flow']`, and serves the finding as `error`. - **Fixtures**: six existing fixtures in that file were edgeless two-node flows (start + one node). They now carry the one edge from `start`. The "normal approval with no revise edge" case drops its unwired `approval_revise` node. Each case keeps its own assertion. - `packages/metadata-protocol/src/protocol.draft-publish-verdict.test.ts`: a `flow-node-unreachable` row in `CASES`. The draft saves and reads `valid: false`, publish refuses with the same words, and the package publish refuses and rolls back. - `packages/metadata-protocol/src/protocol.metadata-redaction.test.ts`: four #20590 round-trip fixtures saved flows with top-level nodes no edge reached, and the save door now refuses them for that. They carry the edges from their start node; two edge-id pins list the added edges; each case's own assertion is unchanged. - **Reverse check** (one-off, not kept): with the `scanUnreachableNodes` call commented out, 4 of the new cases go red (the three refusals and the registration case); restored, green (254/254 at the time; 255 with the second-start case added since). - **Census**, loaded, BFS from `start` over every top-level edge: - objectstack (examples + fixtures + non-test packages): 54 flows, 238 nodes, 0 unreachable; control: 184 non-start nodes reached. - hotcrm `main` `6961ab1`: 35 flows, 256 nodes, 0 unreachable; control: 221 reached. ## Acceptance notes - Item A (boolean `required: true`) is not built: the seat ruled it an enforced presence contract. Item B lands as B1 in its own PR; item D also lands in its own PR. This PR is item C only, so `Refs`, not `Fixes`. - The Studio simulator's advisory "unreachable" warning (`simulator/flow-sim-validate.ts:412`) is unchanged; this rule is the gating one. ## Verification Final head `3284c658` (branch merged with `origin/main` `8f4e8fb9` before the final runs). `3284c658` follows the contract review: the registration test passes the `{}` context `AuthoringRule.run` takes (the `Type Check · workspace` red), and a second start node gets its own hint. After it, `@objectstack/lint` and `@objectstack/metadata-protocol` `pnpm typecheck` (incl. `check:test-typecheck`) exit 0, and `lint-flow-patterns.test.ts` + `rule-explanations.test.ts` pass 263/263. - **Gates**: 62 derived by `dispatch-gates --commands` and run on `8f731d6a`. 61 exit 0. `check:test-source-alias` was red on the edited redaction test (the save door's lint import must load at collection). The `d3db24b1` commit adds the module-top `import '@objectstack/lint'`, and the gate is then exit 0. `--ran` reconciles 62 accounted, 0 NOT-MEASURED, 0 unrun. `check:dual-build-cjs-loads` ran after the full build. The teardown self-test ran with the pinned fixture commit fetched. - **Changeset level**: `check-changeset-no-major` with a `pull_request` event carrying this body exits 0 (LEVEL AXIS: `yes (narrowing)` + `narrowed`, no package graded `patch`). - **Build and dogfood**: full `pnpm build` (119 tasks), then `pnpm --filter @objectstack/dogfood test` under the verify lock on `8f731d6a`: 435 files passed, 3 skipped; 3609 tests passed, 41 skipped; VERDICT command-exit 0. The later `d3db24b1` commit is one test-file import. - **Suites**: - `@objectstack/lint`: 197 files, 8352 tests passed. - `@objectstack/metadata-protocol`: 322 files. The 5 redaction round-trip reds this rule caused are wired in this PR, and the file then passes 67/67; the draft-publish verdict file passes 50/50. - `@objectstack/runtime`, run on a working tree before the final merge (not re-run on the final head; dogfood covers it there): 557 of 558 files passed. The 1 red (`standalone-stack-uncreatable-db-directory`, a `/proc` timing case) passes 6/6 when rerun alone and touches no flow. CI runs the full set. --- _Generated by [Claude Code](https://claude.ai/code/session_01FEkQ5oEQNYg7j3ueo5t6pV)_ 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01FEkQ5oEQNYg7j3ueo5t6pV <!-- signed: domain:spec#1 · os-project-manager · session_01FEkQ5mw7HFYn9o4LEGMQdK --> --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: objectstack-fleet[bot] <332303061+objectstack-fleet[bot]@users.noreply.github.com>
1 parent 57675a2 commit 11c1326

7 files changed

Lines changed: 326 additions & 10 deletions

File tree

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
'@objectstack/lint': minor
3+
---
4+
5+
fix(lint)!: a flow node no edge path from the start node reaches is refused at build and publish (`flow-node-unreachable`), because a run never executes it
6+
7+
Clause-②: yes (narrowing) — `os validate`, `os build`, `os lint` and the flow save and publish doors refuse a flow they accepted before; `@objectstack/lint` also exports the rule id `FLOW_NODE_UNREACHABLE`, and `RULE_EXPLANATIONS` gains its entry.
8+
Metadata-protocol: narrowed
9+
Skills-docs: none — `skills/**` and `content/docs/**` teach only wired top-level flows; the edgeless examples in `content/docs/automation/flows.mdx` are region bodies, which this rule does not judge. The reasoning ships as the `os explain flow-node-unreachable` entry.
10+
11+
<!-- adr-0087: not-required (no-migration-prescription) No key of any schema is added, removed or renamed: FlowSchema keeps its shape and meaning, and lint now refuses a graph whose node no edge from the start node reaches. Such a node never ran (a run starts at the start node and follows edges), so there is no rewrite that keeps what the author meant: the author wires the node in or deletes it, and the finding says which node. -->
12+
13+
**BREAKING** accept-set narrowing in `os validate` / `os build` / `os lint` and at the flow publish doors (`PUT /api/v1/meta/flow/NAME` live save, the per-item and package publish; Studio, REST and MCP authors), through the gating `lintFlowPatterns` rule.
14+
15+
- **Before.** A flow whose top-level node had no edge path from the start node (`nodes: [start, stamp, end]`, `edges: [start → end]`) parsed, built, saved, published and registered, and reported itself as configured. The engine starts a run at the start node and follows edges, so `stamp` never ran, and nothing said so.
16+
- **Now.** `flow-node-unreachable` (severity `error`) names each such node: `flow 'NAME' · node 'ID' (TYPE)`, why it never runs, and the fix. A draft save still stores, with the finding in its `_diagnostics`, so a designer that deletes a node and leaves its successor unwired can keep saving; the publish refuses it.
17+
- **A second start node.** A run starts at the first start node, so a second one is reported too; its hint says to delete the extra start rather than wire an edge into it.
18+
- **What counts as reaching a node.** Every edge type: default, conditional, fault and back. A `boundary_event` node, and the nodes only it leads to, are not judged (they are reached by attachment, not by an edge).
19+
- **Not judged.** Nodes inside a region body (a region is a single-entry acyclic graph that the region validator already holds, so all of it is reached); a flow with no start node; a flow with an edge whose endpoint names no node (the flow parse refuses that first).
20+
- **Why lint and not the flow parse.** The metadata save door parses `FlowSchema` on every save, drafts included, and the Studio designer's node delete can leave a successor unwired. A parse rule would refuse that draft save outright.
21+
22+
**What an author does.** Nothing for a flow whose nodes are all wired from the start node. For a refused node: add an edge into it from a node that runs, or delete the node. A refused node never ran, so neither choice changes what the flow did.

‎packages/lint/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1042,6 +1042,7 @@ export {
10421042
FLOW_DEFAULT_EDGE_WITH_CONDITION,
10431043
FLOW_MULTIPLE_DEFAULT_EDGES,
10441044
FLOW_INERT_NODE_CONDITION,
1045+
FLOW_NODE_UNREACHABLE,
10451046
FLOW_MULTI_WRITE_UNFILTERED,
10461047
FLOW_LOOP_BODY_UNCONTAINED,
10471048
FLOW_TRY_CATCH_WITHOUT_CATCH,

‎packages/lint/src/lint-flow-patterns.test.ts‎

Lines changed: 152 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ import {
3333
FLOW_DEFAULT_EDGE_WITH_CONDITION,
3434
FLOW_MULTIPLE_DEFAULT_EDGES,
3535
FLOW_INERT_NODE_CONDITION,
36+
FLOW_NODE_UNREACHABLE,
3637
FLOW_MULTI_WRITE_UNFILTERED,
3738
FLOW_LOOP_BODY_UNCONTAINED,
3839
FLOW_TRY_CATCH_WITHOUT_CATCH,
@@ -91,7 +92,7 @@ const filterFlow = (filter: unknown) => ({
9192
{ id: 'start', type: 'start', config: { triggerType: 'schedule', schedule: 'cron:0 9 * * *' } },
9293
{ id: 'query', type: 'get_record', config: { objectName: 'contract', filter } },
9394
],
94-
edges: [],
95+
edges: [{ id: 'e1', source: 'start', target: 'query' }],
9596
}],
9697
});
9798

@@ -220,7 +221,7 @@ describe('lintFlowPatterns — phantom aggregation capability (#1870)', () => {
220221
{ id: 'start', type: 'start', config: {} },
221222
{ id: 'sum', type: 'script', config },
222223
],
223-
edges: [],
224+
edges: [{ id: 'e1', source: 'start', target: 'sum' }],
224225
}],
225226
});
226227

@@ -250,7 +251,7 @@ const nodeFlow = (config: Record<string, unknown>) => ({
250251
{ id: 'start', type: 'start', config: {} },
251252
{ id: 'create', type: 'create_record', config },
252253
],
253-
edges: [],
254+
edges: [{ id: 'e1', source: 'start', target: 'create' }],
254255
}],
255256
});
256257
const rules = (s: any) => lintFlowPatterns(s).map((f) => f.rule);
@@ -351,6 +352,7 @@ describe('lintFlowPatterns — approval revise loop (ADR-0044)', () => {
351352
const edges = [
352353
{ source: 'start', target: 'mgr' },
353354
{ source: 'mgr', target: 'ok', label: 'approve' },
355+
{ source: 'mgr', target: 'no', label: 'reject' },
354356
{ source: 'mgr', target: 'wait', label: 'revise' },
355357
];
356358
const fnds = lintFlowPatterns(approvalFlow(edges));
@@ -370,7 +372,11 @@ describe('lintFlowPatterns — approval revise loop (ADR-0044)', () => {
370372
{ source: 'mgr', target: 'ok', label: 'approve' },
371373
{ source: 'mgr', target: 'no', label: 'reject' },
372374
];
373-
expect(lintFlowPatterns(approvalFlow(edges))).toEqual([]);
375+
// No revise edge, so no revise node either: one left in place with no edge
376+
// into it would draw `flow-node-unreachable` (it could never run).
377+
const stack = approvalFlow(edges) as any;
378+
stack.flows[0].nodes = stack.flows[0].nodes.filter((n: any) => n.id !== 'wait');
379+
expect(lintFlowPatterns(stack)).toEqual([]);
374380
});
375381

376382
// #3823 — the shape ADR-0044 D3 prescribed until its 2026-07-28 amendment.
@@ -416,7 +422,7 @@ describe('lintFlowPatterns — user-less runAs unscoped (#1888 / ADR-0049 / ADR-
416422
{ id: 'start', type: 'start', config: opts.startConfig ?? { triggerType: 'schedule', cron: '0 8 * * *' } },
417423
{ id: 'op', type: opts.nodeType ?? 'create_record', config: { objectName: 'thing', fields: { a: 1 } } },
418424
],
419-
edges: [],
425+
edges: [{ id: 'e1', source: 'start', target: 'op' }],
420426
}],
421427
});
422428

@@ -528,7 +534,7 @@ describe('lintFlowPatterns — user-less runAs unscoped (#1888 / ADR-0049 / ADR-
528534
{ id: 'start', type: 'start', config: { schedule: { type: 'interval', intervalMs: 60000 } } },
529535
{ id: 'notify', type: 'notify', config: { topic: 'x' } },
530536
],
531-
edges: [],
537+
edges: [{ id: 'e1', source: 'start', target: 'notify' }],
532538
}],
533539
})).toHaveLength(0);
534540
});
@@ -3710,3 +3716,143 @@ describe('[#22161] one-line fix — the twelve flow anti-pattern ids', () => {
37103716
}
37113717
});
37123718
});
3719+
3720+
describe('lintFlowPatterns — a node no edge path from start reaches (flow-node-unreachable)', () => {
3721+
type Edge = { id: string; source: string; target: string; type?: string; condition?: string };
3722+
const reachFlow = (nodes: Array<Record<string, unknown>>, edges: Edge[]) => ({
3723+
flows: [{ name: 'orphan', type: 'autolaunched', nodes, edges }],
3724+
});
3725+
const START = { id: 'start', type: 'start', label: 'Start' };
3726+
const END = { id: 'end', type: 'end', label: 'End' };
3727+
const unreachable = (stack: unknown) =>
3728+
lintFlowPatterns(stack as never).filter((f) => f.rule === FLOW_NODE_UNREACHABLE);
3729+
3730+
it('refuses an action node no edge reaches, as an error that names it, why it never runs and the fix', () => {
3731+
const found = unreachable(reachFlow(
3732+
[START, { id: 'stamp', type: 'assignment', label: 'Stamp' }, END],
3733+
[{ id: 'e1', source: 'start', target: 'end' }],
3734+
));
3735+
expect(found).toHaveLength(1);
3736+
expect(found[0]).toMatchObject({ rule: FLOW_NODE_UNREACHABLE, severity: 'error' });
3737+
expect(found[0].where).toBe("flow 'orphan' · node 'stamp' (assignment)");
3738+
expect(found[0].message).toMatch(/no edge path leads to this node from the start node 'start', so it never runs/);
3739+
expect(found[0].hint).toMatch(/Add an edge into it from a node that runs, or delete the node/);
3740+
});
3741+
3742+
it('refuses a node whose only in-edge comes from another unreached node (one finding each)', () => {
3743+
const found = unreachable(reachFlow(
3744+
[START, { id: 'a', type: 'assignment' }, { id: 'b', type: 'assignment' }, END],
3745+
[{ id: 'e1', source: 'start', target: 'end' }, { id: 'e2', source: 'a', target: 'b' }],
3746+
));
3747+
expect(found.map((f) => f.where)).toEqual([
3748+
"flow 'orphan' · node 'a' (assignment)",
3749+
"flow 'orphan' · node 'b' (assignment)",
3750+
]);
3751+
});
3752+
3753+
it('refuses a second start node with the cure that fits it: delete the extra start', () => {
3754+
const found = unreachable(reachFlow(
3755+
[START, { id: 'start2', type: 'start' }, { id: 'b', type: 'assignment' }, END],
3756+
[{ id: 'e1', source: 'start', target: 'end' }, { id: 'e2', source: 'start2', target: 'b' }],
3757+
));
3758+
expect(found.map((f) => f.where)).toEqual([
3759+
"flow 'orphan' · node 'start2' (start)",
3760+
"flow 'orphan' · node 'b' (assignment)",
3761+
]);
3762+
expect(found[0].hint).toMatch(/delete this extra start node/);
3763+
expect(found[1].hint).toMatch(/Add an edge into it from a node that runs/);
3764+
});
3765+
3766+
it('refuses a cycle cut off from start', () => {
3767+
const found = unreachable(reachFlow(
3768+
[START, { id: 'a', type: 'assignment' }, { id: 'b', type: 'assignment' }, END],
3769+
[
3770+
{ id: 'e1', source: 'start', target: 'end' },
3771+
{ id: 'e2', source: 'a', target: 'b' },
3772+
{ id: 'e3', source: 'b', target: 'a', type: 'back' },
3773+
],
3774+
));
3775+
expect(found).toHaveLength(2);
3776+
});
3777+
3778+
describe('does NOT flag (controls)', () => {
3779+
it('a node reached over a conditional, fault or back edge (every edge type counts)', () => {
3780+
expect(unreachable(reachFlow(
3781+
[
3782+
START,
3783+
{ id: 'call', type: 'http', config: { url: 'https://example.test' } },
3784+
{ id: 'big', type: 'assignment' },
3785+
{ id: 'recover', type: 'assignment' },
3786+
END,
3787+
],
3788+
[
3789+
{ id: 'e1', source: 'start', target: 'call' },
3790+
{ id: 'e2', source: 'call', target: 'big', type: 'conditional', condition: 'true' },
3791+
{ id: 'e3', source: 'call', target: 'recover', type: 'fault' },
3792+
{ id: 'e4', source: 'big', target: 'end' },
3793+
{ id: 'e5', source: 'recover', target: 'end' },
3794+
],
3795+
))).toEqual([]);
3796+
});
3797+
3798+
it('a boundary_event node and the nodes only it leads to (reached by attachment, not by an edge)', () => {
3799+
expect(unreachable(reachFlow(
3800+
[
3801+
START,
3802+
{ id: 'task', type: 'wait', waitEventConfig: { eventType: 'timer', timerDuration: 'PT1H' } },
3803+
{ id: 'timeout', type: 'boundary_event', boundaryConfig: { attachedToNodeId: 'task', eventType: 'timer' } },
3804+
{ id: 'escalate', type: 'assignment' },
3805+
END,
3806+
],
3807+
[
3808+
{ id: 'e1', source: 'start', target: 'task' },
3809+
{ id: 'e2', source: 'task', target: 'end' },
3810+
{ id: 'e3', source: 'timeout', target: 'escalate' },
3811+
],
3812+
))).toEqual([]);
3813+
});
3814+
3815+
it('a flow with no start node (a different defect, judged elsewhere)', () => {
3816+
expect(unreachable(reachFlow(
3817+
[{ id: 'a', type: 'assignment' }, END],
3818+
[],
3819+
))).toEqual([]);
3820+
});
3821+
3822+
it('a flow with a dangling edge (the flow parse refuses that first; reachability is not guessed)', () => {
3823+
expect(unreachable(reachFlow(
3824+
[START, { id: 'a', type: 'assignment' }, END],
3825+
[{ id: 'e1', source: 'start', target: 'end' }, { id: 'e2', source: 'ghost', target: 'a' }],
3826+
))).toEqual([]);
3827+
});
3828+
3829+
it('nodes inside a region body (a region is a single-entry DAG, so every node in it is reached)', () => {
3830+
expect(unreachable(reachFlow(
3831+
[
3832+
START,
3833+
{
3834+
id: 'each', type: 'loop',
3835+
config: {
3836+
collection: '{records}', iteratorVariable: 'r',
3837+
body: {
3838+
nodes: [{ id: 'x', type: 'assignment' }, { id: 'y', type: 'assignment' }],
3839+
edges: [{ id: 'b1', source: 'x', target: 'y' }],
3840+
},
3841+
},
3842+
},
3843+
END,
3844+
],
3845+
[{ id: 'e1', source: 'start', target: 'each' }, { id: 'e2', source: 'each', target: 'end' }],
3846+
))).toEqual([]);
3847+
});
3848+
});
3849+
3850+
it('is in the gating flow rule, so its error reaches os lint/build and the save and publish doors', () => {
3851+
const rule = AUTHORING_RULES.find((r) => r.name === 'lintFlowPatterns');
3852+
expect(rule, 'the authoring rule that runs lintFlowPatterns').toBeDefined();
3853+
expect(rule!.tier).toBe('gating');
3854+
expect(rule!.runtimeTypes).toContain('flow');
3855+
const served = rule!.run(reachFlow([START, { id: 'stamp', type: 'assignment' }, END], [{ id: 'e1', source: 'start', target: 'end' }]) as never, {});
3856+
expect(served).toContainEqual(expect.objectContaining({ rule: FLOW_NODE_UNREACHABLE, severity: 'error' }));
3857+
});
3858+
});

‎packages/lint/src/lint-flow-patterns.ts‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -238,6 +238,11 @@ export const FLOW_DEFAULT_EDGE_WITH_CONDITION = 'flow-default-edge-with-conditio
238238
export const FLOW_MULTIPLE_DEFAULT_EDGES = 'flow-multiple-default-edges';
239239
/** #4414 — `config.condition` on a node whose executor never reads it. */
240240
export const FLOW_INERT_NODE_CONDITION = 'flow-inert-node-condition';
241+
/**
242+
* A top-level node no edge path from the start node reaches: it never runs.
243+
* See {@link scanUnreachableNodes}.
244+
*/
245+
export const FLOW_NODE_UNREACHABLE = 'flow-node-unreachable';
241246
/**
242247
* #15429 — a `decision` `config.mode` the spec refuses: a value outside
243248
* `'exclusive' | 'inclusive'`, or a legal `mode` beside a non-empty
@@ -1862,6 +1867,87 @@ function scanTryCatchWithoutCatch(
18621867
* never throws. A finding marked `severity: 'error'` fails the build, and since
18631868
* #5383 it can be raised by a node inside a `loop` body too.
18641869
*/
1870+
/**
1871+
* {@link FLOW_NODE_UNREACHABLE}: a top-level node no edge path from the start
1872+
* node reaches, one `error` finding per node.
1873+
*
1874+
* The engine runs a flow from its first `start` node and follows out-edges from
1875+
* there (`service-automation`'s `executeNode` → `traverseNext`); nothing else
1876+
* schedules a top-level node. So a node no path reaches (an edge forgotten while
1877+
* wiring, a node left behind when its in-edges were deleted) registers,
1878+
* publishes, reports itself configured and never runs: inert on every run,
1879+
* which is this module's bar for `error`.
1880+
*
1881+
* Why lint and not the flow parse: the save door parses `FlowSchema` on every
1882+
* save, a draft included, and the Studio designer produces this shape mid-edit
1883+
* (removing a node that has more or fewer than one in-edge and out-edge drops
1884+
* its edges without bridging them, which leaves its successors unwired). A
1885+
* parse refusal would refuse that draft. As a finding here it fails `os lint` /
1886+
* `os build`, and on the runtime authoring gate (`runtimeTypes: ['flow']`) a
1887+
* live save and a publish, while a draft is kept with it in `_diagnostics`.
1888+
*
1889+
* Scope, declared rather than discovered:
1890+
*
1891+
* - The top-level graph only (see the call site).
1892+
* - A flow with no `start` node is not judged: nothing is reached from
1893+
* nothing, and the engine refuses to run it (`FLOW_NO_START_NODE`).
1894+
* - Every edge counts, whatever its `type` or `condition`: a `fault` edge or a
1895+
* conditional edge is a path the engine can take.
1896+
* - A flow with an edge whose endpoint names no top-level node is not judged:
1897+
* the flow parse refuses that edge, and the node it was meant to reach would
1898+
* be reported a second time, for the same fault, under a cure (add an edge)
1899+
* that is not the one to apply.
1900+
* - A `boundary_event` is exempt, and so is a node reached only through one: it
1901+
* is attached to its host by `boundaryConfig.attachedToNodeId`, not entered by
1902+
* an edge, and its own contract owns its refusal.
1903+
*/
1904+
function scanUnreachableNodes(
1905+
flowName: string,
1906+
nodes: AnyRec[],
1907+
edges: AnyRec[],
1908+
findings: FlowLintFinding[],
1909+
): void {
1910+
const start = nodes.find((n) => n.type === 'start');
1911+
if (!start || typeof start.id !== 'string') return;
1912+
const ids = new Set(nodes.map((n) => n.id).filter((id): id is string => typeof id === 'string'));
1913+
const outgoing = new Map<string, string[]>();
1914+
for (const e of edges) {
1915+
if (typeof e.source !== 'string' || typeof e.target !== 'string') return;
1916+
if (!ids.has(e.source) || !ids.has(e.target)) return;
1917+
const targets = outgoing.get(e.source) ?? [];
1918+
targets.push(e.target);
1919+
outgoing.set(e.source, targets);
1920+
}
1921+
const reached = new Set<string>();
1922+
const visit = (from: readonly string[]): void => {
1923+
const queue = [...from];
1924+
while (queue.length > 0) {
1925+
const id = queue.shift()!;
1926+
if (reached.has(id)) continue;
1927+
reached.add(id);
1928+
queue.push(...(outgoing.get(id) ?? []));
1929+
}
1930+
};
1931+
visit([start.id]);
1932+
visit(nodes.filter((n) => n.type === 'boundary_event' && typeof n.id === 'string').map((n) => n.id as string));
1933+
for (const node of nodes) {
1934+
if (typeof node.id !== 'string' || reached.has(node.id)) continue;
1935+
findings.push({
1936+
where: `flow '${flowName}' · node '${node.id}' (${String(node.type)})`,
1937+
message:
1938+
`no edge path leads to this node from the start node '${start.id}', so it never runs: a run starts ` +
1939+
`at the start node and follows edges, and the flow still registers and reports itself as configured.`,
1940+
// A second `start` node is unreached by construction (a run starts at the
1941+
// first one), and an edge into it is not the cure: remove the extra start.
1942+
hint: node.type === 'start'
1943+
? `A run starts at the first start node only: delete this extra start node, and wire what follows it from a node that runs.`
1944+
: `Add an edge into it from a node that runs, or delete the node.`,
1945+
rule: FLOW_NODE_UNREACHABLE,
1946+
severity: 'error',
1947+
});
1948+
}
1949+
}
1950+
18651951
export function lintFlowPatterns(stack: AnyRec): FlowLintFinding[] {
18661952
const findings: FlowLintFinding[] = [];
18671953
for (const flow of recordsOf(stack.flows)) {
@@ -1967,6 +2053,12 @@ export function lintFlowPatterns(stack: AnyRec): FlowLintFinding[] {
19672053
}
19682054
}
19692055

2056+
// (a5) A top-level node no edge path from the start node reaches never runs.
2057+
// Flow-level for the reason the trigger rules are: a run enters the
2058+
// top-level graph at its start node, and a region body is already
2059+
// single-entry (ADR-0031), so nothing one level down can be unreached.
2060+
scanUnreachableNodes(flowName, nodes, edges, findings);
2061+
19702062
// (b)–(e) #5383 — every graph in the flow, not just the top-level one: its
19712063
// own `nodes`/`edges` plus each nested ADR-0031 region, each scanned
19722064
// against ITS OWN edge list. `scope` is empty for the flow's own graph,

0 commit comments

Comments
 (0)