feat(core): implement flow-step-not-surfaced diagnostic (#105)

Author: mahyarmlk

.changeset/fresh-jokes-flow.md

@@ -0,0 +1,5 @@
+---
+"@intent-framework/core": minor
+---
+
+Add `flow-step-not-surfaced` diagnostic to `inspectScreen` for flow steps missing from surfaces.

packages/core/src/core.test.ts

@@ -831,6 +831,155 @@ describe("graph diagnostics", () => {
       expect(diags[0]?.semanticNodeId).toBe("action:hidden")
     })
   })
+
+  describe("flow-step-not-surfaced diagnostic", () => {
+    it("does not emit flow-step-not-surfaced when all flow steps are surfaced", () => {
+      const screenDef = screen("AllStepsSurfaced", $ => {
+        const email = $.state.text("email")
+        const emailAsk = $.ask("Email", email).private()
+        const login = $.act("Log in")
+        $.surface("main").contains(emailAsk, login)
+        $.flow("login").startsWith(emailAsk).then(login)
+      })
+      const inspected = inspectScreen(screenDef)
+      const diags = inspected.diagnostics.filter(d => d.code === "flow-step-not-surfaced")
+      expect(diags).toHaveLength(0)
+    })
+
+    it("emits flow-step-not-surfaced for unsurfaced ask step in flow", () => {
+      const screenDef = screen("UnsurfacedAskInFlow", $ => {
+        const email = $.state.text("email")
+        const emailAsk = $.ask("Email", email).private()
+        const login = $.act("Log in")
+        $.surface("main").contains(login)
+        $.flow("login").startsWith(emailAsk).then(login)
+      })
+      const inspected = inspectScreen(screenDef)
+      const diags = inspected.diagnostics.filter(d => d.code === "flow-step-not-surfaced")
+      expect(diags).toHaveLength(1)
+      expect(diags[0]?.severity).toBe("warning")
+      expect(diags[0]?.nodeId).toBe("ask_email")
+    })
+
+    it("emits flow-step-not-surfaced for unsurfaced action step in flow", () => {
+      const screenDef = screen("UnsurfacedActInFlow", $ => {
+        const email = $.state.text("email")
+        const emailAsk = $.ask("Email", email).private()
+        const login = $.act("Log in")
+        $.surface("main").contains(emailAsk)
+        $.flow("login").startsWith(emailAsk).then(login)
+      })
+      const inspected = inspectScreen(screenDef)
+      const diags = inspected.diagnostics.filter(d => d.code === "flow-step-not-surfaced")
+      expect(diags).toHaveLength(1)
+      expect(diags[0]?.severity).toBe("warning")
+      expect(diags[0]?.nodeId).toBe("act_log_in")
+    })
+
+    it("only reports unsurfaced steps when some are surfaced and some are not", () => {
+      const screenDef = screen("MixedSurfaced", $ => {
+        const email = $.state.text("email")
+        const pwd = $.state.text("password")
+        const emailAsk = $.ask("Email", email).private()
+        const pwdAsk = $.ask("Password", pwd).private()
+        const login = $.act("Log in")
+        $.surface("main").contains(emailAsk, login)
+        $.flow("login").startsWith(emailAsk).then(pwdAsk).then(login)
+      })
+      const inspected = inspectScreen(screenDef)
+      const diags = inspected.diagnostics.filter(d => d.code === "flow-step-not-surfaced")
+      expect(diags).toHaveLength(1)
+      expect(diags[0]?.nodeId).toBe("ask_password")
+    })
+
+    it("does not emit flow-step-not-surfaced when there are no flows", () => {
+      const screenDef = screen("NoFlowsAtAll", $ => {
+        const email = $.state.text("email")
+        const emailAsk = $.ask("Email", email).private()
+        const login = $.act("Log in")
+        $.surface("main").contains(emailAsk, login)
+      })
+      const inspected = inspectScreen(screenDef)
+      const diags = inspected.diagnostics.filter(d => d.code === "flow-step-not-surfaced")
+      expect(diags).toHaveLength(0)
+    })
+
+    it("emits deterministic flow-step-not-surfaced diagnostics across multiple flows", () => {
+      const screenDef = screen("MultipleFlowsDet", $ => {
+        const email = $.state.text("email")
+        const pwd = $.state.text("password")
+        const emailAsk = $.ask("Email", email).private()
+        const pwdAsk = $.ask("Password", pwd).private()
+        const login = $.act("Log in")
+        const signup = $.act("Sign up")
+        $.surface("main").contains(emailAsk, login, signup)
+        $.flow("login").startsWith(emailAsk).then(pwdAsk).then(login)
+        $.flow("register").startsWith(pwdAsk).then(signup)
+      })
+      const inspected = inspectScreen(screenDef)
+      const diags = inspected.diagnostics.filter(d => d.code === "flow-step-not-surfaced")
+      expect(diags).toHaveLength(2)
+      expect(diags[0]?.nodeId).toBe("ask_password")
+      expect(diags[0]?.flow?.flowNodeId).toBe("flow_login")
+      expect(diags[1]?.nodeId).toBe("ask_password")
+      expect(diags[1]?.flow?.flowNodeId).toBe("flow_register")
+    })
+
+    it("includes nodeId and semanticNodeId for the unsurfaced step", () => {
+      const screenDef = screen("WithSemanticStep", $ => {
+        const email = $.state.text("email")
+        const emailAsk = $.ask("Email", email).private()
+        const login = $.act("Log in")
+        $.surface("main").contains(login)
+        $.flow("login").startsWith(emailAsk).then(login)
+      })
+      const inspected = inspectScreen(screenDef)
+      const diags = inspected.diagnostics.filter(d => d.code === "flow-step-not-surfaced")
+      expect(diags).toHaveLength(1)
+      expect(diags[0]?.nodeId).toBe("ask_email")
+      expect(diags[0]?.semanticNodeId).toBe("ask:email")
+    })
+
+    it("includes nested flow.flowNodeId and flow.flowSemanticNodeId", () => {
+      const screenDef = screen("NestedFlowMeta", $ => {
+        const email = $.state.text("email")
+        const emailAsk = $.ask("Email", email).private()
+        const login = $.act("Log in")
+        $.surface("main").contains(login)
+        $.flow("login").startsWith(emailAsk).then(login)
+      })
+      const inspected = inspectScreen(screenDef)
+      const diags = inspected.diagnostics.filter(d => d.code === "flow-step-not-surfaced")
+      expect(diags).toHaveLength(1)
+      expect(diags[0]?.flow?.flowNodeId).toBe("flow_login")
+      expect(diags[0]?.flow?.flowSemanticNodeId).toBe("flow:login")
+    })
+
+    it("coexists with surfaced-node-not-in-any-flow without breaking determinism", () => {
+      const screenDef = screen("CoexistFlow", $ => {
+        const email = $.state.text("email")
+        const pwd = $.state.text("password")
+        const emailAsk = $.ask("Email", email).private()
+        const pwdAsk = $.ask("Password", pwd).private()
+        const login = $.act("Log in").primary()
+        const signup = $.act("Sign up").primary()
+        $.surface("main").contains(emailAsk, login, signup)
+        $.flow("login").startsWith(emailAsk).then(pwdAsk).then(login)
+      })
+      const first = inspectScreen(screenDef)
+      const second = inspectScreen(screenDef)
+      expect(first.diagnostics.map(d => d.code)).toEqual(second.diagnostics.map(d => d.code))
+      const codes = first.diagnostics.map(d => d.code)
+      expect(codes).toContain("flow-step-not-surfaced")
+      expect(codes).toContain("surfaced-node-not-in-any-flow")
+      const flowDiags = first.diagnostics.filter(d => d.code === "flow-step-not-surfaced")
+      expect(flowDiags).toHaveLength(1)
+      expect(flowDiags[0]?.nodeId).toBe("ask_password")
+      const reachDiags = first.diagnostics.filter(d => d.code === "surfaced-node-not-in-any-flow")
+      expect(reachDiags).toHaveLength(1)
+      expect(reachDiags[0]?.nodeId).toBe("act_sign_up")
+    })
+  })
 })
 
 describe("resource", () => {

packages/core/src/graph.ts

@@ -172,6 +172,23 @@ function computeDiagnostics<TServices extends object = DefaultScreenServices>(
       }
     }
 
+    // flow-step-not-surfaced: step referenced in a flow but not in any surface
+    for (const flow of screenDef.flows) {
+      for (const step of flow.steps) {
+        if (!surfacedNodeIds.has(step.node.id)) {
+          diagnostics.push({
+            severity: "warning",
+            code: "flow-step-not-surfaced",
+            message: `"${step.node.label}" is a flow step but not included in any surface.`,
+            nodeId: step.node.id,
+            flow: {
+              flowNodeId: flow.id,
+            },
+          })
+        }
+      }
+    }
+
     for (const ask of screenDef.asks) {
       if (surfacedNodeIds.has(ask.id) && !flowNodeIds.has(ask.id)) {
         diagnostics.push({
@@ -218,9 +235,17 @@ export function inspectScreen<TServices extends object = DefaultScreenServices>(
     idToSemantic.set(a.id, actIds(a.label))
   }
 
+  const idToFlowSemantic = new Map<string, string>()
+  for (const f of screenDef.flows) {
+    idToFlowSemantic.set(f.id, flowIds(f.name))
+  }
+
   const augmentedDiagnostics: GraphDiagnostic[] = diagnostics.map(d => ({
     ...d,
     semanticNodeId: d.nodeId ? idToSemantic.get(d.nodeId) : undefined,
+    flow: d.flow
+      ? { ...d.flow, flowSemanticNodeId: idToFlowSemantic.get(d.flow.flowNodeId) }
+      : undefined,
   }))
 
   return {
@@ -249,7 +274,7 @@ export function inspectScreen<TServices extends object = DefaultScreenServices>(
     })),
     flows: screenDef.flows.map(f => ({
       id: f.id,
-      semanticId: flowIds(f.name),
+      semanticId: idToFlowSemantic.get(f.id)!,
       name: f.name,
       stepCount: f.steps.length,
     })),