You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 11c1326
Browse filesBrowse the repository at this point in the historyBrowse 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>
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.
0 commit comments