@sqaoss/flowy 1.8.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqaoss/flowy",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Agentic persistent planning",
   "type": "module",
   "bin": {

package/server/src/contract.test.ts

@@ -281,11 +281,44 @@ describe('CLI/local-server contract (P1-1)', () => {
     })
     expect(exportDescendants.descendants.length).toBeGreaterThan(0)
 
-    const subtree = await ok<{ subtree: Array<{ id: string }> }>(
-      LOCAL_CONTRACT_OPERATIONS.SUBTREE,
-      { nodeId: project.id, maxDepth: 10 },
-    )
-    expect(subtree.subtree.length).toBeGreaterThan(0)
+    // SUBTREE follows one relation (default part_of) and annotates each node
+    // with parentId/depth/relation. From the project, the part_of view is:
+    //   project -> feature (depth 1) -> {task, blocker, imported} (depth 2),
+    // all reached via part_of edges. The blocker -> task `blocks` edge must NOT
+    // change anyone's parent/relation: every returned node carries
+    // relation 'part_of' and its part_of parent, never the blocks linkage.
+    const subtree = await ok<{
+      subtree: Array<{
+        id: string
+        parentId: string
+        depth: number
+        relation: string
+      }>
+    }>(LOCAL_CONTRACT_OPERATIONS.SUBTREE, {
+      nodeId: project.id,
+      relation: 'part_of',
+      maxDepth: 10,
+    })
+    const subtreeById = new Map(subtree.subtree.map((n) => [n.id, n]))
+    expect(subtreeById.get(feature.id)).toMatchObject({
+      parentId: project.id,
+      depth: 1,
+      relation: 'part_of',
+    })
+    expect(subtreeById.get(task.id)).toMatchObject({
+      parentId: feature.id,
+      depth: 2,
+      relation: 'part_of',
+    })
+    // the blocker is reached via its part_of edge to the feature (depth 2),
+    // NOT via the blocks edge that points at the task — proving blocks edges
+    // do not leak into the hierarchy view.
+    expect(subtreeById.get(blocker.id)).toMatchObject({
+      parentId: feature.id,
+      depth: 2,
+      relation: 'part_of',
+    })
+    expect(subtree.subtree.every((n) => n.relation === 'part_of')).toBe(true)
 
     // task is blocked by an unfinished blocker, so readyTasks excludes it.
     const ready = await ok<{ readyTasks: Array<{ id: string }> }>(

package/server/src/resolvers.test.ts

@@ -580,7 +580,7 @@ describe('createResolvers', () => {
   })
 
   describe('Query.subtree', () => {
-    it('returns full tree traversal across all edge types', () => {
+    it('returns the part_of hierarchy by default', () => {
       const project = resolvers.Mutation.createNode(null, {
         type: 'project',
         title: 'Root',
@@ -608,6 +608,125 @@ describe('createResolvers', () => {
       expect(tree).toHaveLength(2)
     })
 
+    it('returns parentId, depth and relation for each node (default part_of)', () => {
+      const project = resolvers.Mutation.createNode(null, {
+        type: 'project',
+        title: 'Root',
+      })
+      const feature = resolvers.Mutation.createNode(null, {
+        type: 'feature',
+        title: 'F1',
+      })
+      const task = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'T1',
+      })
+      resolvers.Mutation.createEdge(null, {
+        sourceId: feature.id,
+        targetId: project.id,
+        relation: 'part_of',
+      })
+      resolvers.Mutation.createEdge(null, {
+        sourceId: task.id,
+        targetId: feature.id,
+        relation: 'part_of',
+      })
+
+      const tree = resolvers.Query.subtree(null, { nodeId: project.id })
+      const byId = new Map(tree.map((n) => [n.id, n]))
+
+      const featNode = byId.get(feature.id)
+      expect(featNode).toBeDefined()
+      expect(featNode?.depth).toBe(1)
+      expect(featNode?.parentId).toBe(project.id)
+      expect(featNode?.relation).toBe('part_of')
+
+      const taskNode = byId.get(task.id)
+      expect(taskNode).toBeDefined()
+      expect(taskNode?.depth).toBe(2)
+      expect(taskNode?.parentId).toBe(feature.id)
+      expect(taskNode?.relation).toBe('part_of')
+    })
+
+    it('excludes blocks edges from the default part_of view', () => {
+      const project = resolvers.Mutation.createNode(null, {
+        type: 'project',
+        title: 'Root',
+      })
+      const feature = resolvers.Mutation.createNode(null, {
+        type: 'feature',
+        title: 'F1',
+      })
+      const task = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'T1',
+      })
+      const blocker = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'Blocker',
+      })
+      resolvers.Mutation.createEdge(null, {
+        sourceId: feature.id,
+        targetId: project.id,
+        relation: 'part_of',
+      })
+      resolvers.Mutation.createEdge(null, {
+        sourceId: task.id,
+        targetId: feature.id,
+        relation: 'part_of',
+      })
+      // blocker blocks task: source=blocker, target=task. A blocks edge must NOT
+      // pull the blocker into the project's part_of hierarchy view.
+      resolvers.Mutation.createEdge(null, {
+        sourceId: blocker.id,
+        targetId: task.id,
+        relation: 'blocks',
+      })
+
+      const tree = resolvers.Query.subtree(null, { nodeId: project.id })
+      const ids = tree.map((n) => n.id)
+      expect(ids).toContain(feature.id)
+      expect(ids).toContain(task.id)
+      expect(ids).not.toContain(blocker.id)
+      expect(tree.every((n) => n.relation === 'part_of')).toBe(true)
+    })
+
+    it('follows only the requested relation when overridden', () => {
+      const task = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'Target',
+      })
+      const blocker = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'Blocker',
+      })
+      const child = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'Part of target',
+      })
+      // blocker blocks task (source=blocker, target=task)
+      resolvers.Mutation.createEdge(null, {
+        sourceId: blocker.id,
+        targetId: task.id,
+        relation: 'blocks',
+      })
+      // child is part_of task (source=child, target=task)
+      resolvers.Mutation.createEdge(null, {
+        sourceId: child.id,
+        targetId: task.id,
+        relation: 'part_of',
+      })
+
+      const blocks = resolvers.Query.subtree(null, {
+        nodeId: task.id,
+        relation: 'blocks',
+      })
+      expect(blocks.map((n) => n.id)).toEqual([blocker.id])
+      expect(blocks[0].relation).toBe('blocks')
+      expect(blocks[0].depth).toBe(1)
+      expect(blocks[0].parentId).toBe(task.id)
+    })
+
     it('respects maxDepth', () => {
       const project = resolvers.Mutation.createNode(null, {
         type: 'project',
@@ -638,6 +757,7 @@ describe('createResolvers', () => {
       })
       expect(shallow).toHaveLength(1)
       expect(shallow[0].id).toBe(feature.id)
+      expect(shallow[0].depth).toBe(1)
     })
   })
 

package/server/src/resolvers.ts

@@ -40,6 +40,23 @@ export interface NodeGql {
   updatedAt: string
 }
 
+/**
+ * A node returned from a subtree traversal, annotated with the edge that pulled
+ * it in: `parentId` (the node it descends from), `depth` (1 for the root's
+ * direct children), and `relation` (the relation of the linking edge).
+ */
+export interface SubtreeNodeGql extends NodeGql {
+  parentId: string
+  depth: number
+  relation: string
+}
+
+interface SubtreeRow extends NodeRow {
+  parent_id: string
+  depth: number
+  edge_relation: string
+}
+
 const NODE_COLS =
   'id, type, title, description, status, metadata, created_at, updated_at'
 
@@ -177,21 +194,39 @@ export function createResolvers(db: Db) {
         return selectNodes(rows)
       },
 
-      subtree: (_: unknown, args: { nodeId: string; maxDepth?: number }) => {
+      // Walk the part_of hierarchy (or another `relation`, default 'part_of')
+      // downward from `nodeId`, returning each reachable node annotated with the
+      // edge that pulled it in: parentId, depth (root's direct children = 1) and
+      // relation. Following a single relation keeps the hierarchy view clean —
+      // `blocks` dependency edges no longer leak into the part_of tree.
+      subtree: (
+        _: unknown,
+        args: { nodeId: string; relation?: string; maxDepth?: number },
+      ): SubtreeNodeGql[] => {
+        const relation = args.relation ?? 'part_of'
         const maxDepth = args.maxDepth ?? 100
         if (maxDepth === 0) return []
         const rows = db.raw
           .query(
-            `WITH RECURSIVE tree(id, depth) AS (
-              SELECT source_id, 1 FROM edges WHERE target_id = ?1
+            `WITH RECURSIVE tree(id, parent_id, depth) AS (
+              SELECT source_id, target_id, 1 FROM edges
+                WHERE target_id = ?1 AND relation = ?3
               UNION ALL
-              SELECT e.source_id, t.depth + 1 FROM edges e
-              JOIN tree t ON e.target_id = t.id WHERE t.depth < ?2
+              SELECT e.source_id, e.target_id, t.depth + 1 FROM edges e
+                JOIN tree t ON e.target_id = t.id
+                WHERE t.depth < ?2 AND e.relation = ?3
             )
-            SELECT DISTINCT ${prefixedCols()} FROM nodes n JOIN tree t ON n.id = t.id`,
+            SELECT ${prefixedCols()}, t.parent_id AS parent_id, t.depth AS depth, ?3 AS edge_relation
+            FROM nodes n JOIN tree t ON n.id = t.id
+            ORDER BY t.depth`,
           )
-          .all(args.nodeId, maxDepth) as NodeRow[]
-        return selectNodes(rows)
+          .all(args.nodeId, maxDepth, relation) as SubtreeRow[]
+        return rows.map((row) => ({
+          ...rowToNode(row),
+          parentId: row.parent_id,
+          depth: row.depth,
+          relation: row.edge_relation,
+        }))
       },
 
       // Nodes connected to `nodeId` by `relation`, following edges in the given

package/server/src/schema.ts

@@ -19,11 +19,29 @@ export const typeDefs = /* GraphQL */ `
     createdAt: String!
   }
 
+  # A node returned from a subtree traversal, annotated with how it was reached:
+  # the parent it descends from (parentId), how many edges down the root it sits
+  # (depth, root's direct children are depth 1), and the relation of the edge
+  # that links it to its parent.
+  type SubtreeNode {
+    id: String!
+    type: String!
+    title: String!
+    description: String
+    status: String!
+    metadata: String
+    createdAt: String!
+    updatedAt: String!
+    parentId: String!
+    depth: Int!
+    relation: String!
+  }
+
   type Query {
     node(id: String!): Node
     nodes(type: String): [Node!]!
     descendants(nodeId: String!, relation: String, maxDepth: Int): [Node!]!
-    subtree(nodeId: String!, maxDepth: Int): [Node!]!
+    subtree(nodeId: String!, relation: String, maxDepth: Int): [SubtreeNode!]!
     edges(nodeId: String!, relation: String!, direction: String): [Node!]!
     readyTasks(projectId: String): [Node!]!
     search(query: String!, type: String, status: String, limit: Int): [Node!]!

package/src/commands/tree.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from 'vitest'
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
 
 describe('tree command', () => {
   test('exports a flat command with id argument and depth option', async () => {
@@ -6,4 +6,92 @@ describe('tree command', () => {
     expect(treeCommand.name()).toBe('tree')
     expect(treeCommand.commands).toHaveLength(0)
   })
+
+  test('exposes a --relation option defaulting to part_of', async () => {
+    const { treeCommand } = await import('./tree.ts')
+    const relationOpt = treeCommand.options.find((o) => o.long === '--relation')
+    expect(relationOpt).toBeDefined()
+    expect(relationOpt?.defaultValue).toBe('part_of')
+  })
+
+  describe('action', () => {
+    beforeEach(() => {
+      vi.resetModules()
+    })
+
+    afterEach(() => {
+      vi.restoreAllMocks()
+      vi.unstubAllEnvs()
+    })
+
+    test('sends the SUBTREE op with the relation filter and renders depth/relation', async () => {
+      const calls: Array<{ query: string; variables: unknown }> = []
+      vi.doMock('../util/client.ts', () => ({
+        graphql: vi.fn(async (query: string, variables: unknown) => {
+          calls.push({ query, variables })
+          return {
+            subtree: [
+              {
+                id: 'feat_1',
+                type: 'feature',
+                title: 'F1',
+                status: 'draft',
+                parentId: 'proj_1',
+                depth: 1,
+                relation: 'part_of',
+              },
+            ],
+          }
+        }),
+      }))
+      const outputs: unknown[] = []
+      vi.doMock('../util/format.ts', () => ({
+        output: vi.fn((data: unknown) => outputs.push(data)),
+        outputError: vi.fn(),
+      }))
+
+      const { SUBTREE } = await import('../util/operations.ts')
+      const { treeCommand } = await import('./tree.ts')
+      await treeCommand.parseAsync(['proj_1'], { from: 'user' })
+
+      expect(calls).toHaveLength(1)
+      expect(calls[0]!.query).toBe(SUBTREE)
+      expect(calls[0]!.variables).toMatchObject({
+        nodeId: 'proj_1',
+        relation: 'part_of',
+      })
+
+      const rendered = outputs[0] as Array<Record<string, unknown>>
+      expect(rendered[0]).toMatchObject({
+        id: 'feat_1',
+        parentId: 'proj_1',
+        depth: 1,
+        relation: 'part_of',
+      })
+    })
+
+    test('passes an overridden relation through to the op', async () => {
+      const calls: Array<{ variables: unknown }> = []
+      vi.doMock('../util/client.ts', () => ({
+        graphql: vi.fn(async (_query: string, variables: unknown) => {
+          calls.push({ variables })
+          return { subtree: [] }
+        }),
+      }))
+      vi.doMock('../util/format.ts', () => ({
+        output: vi.fn(),
+        outputError: vi.fn(),
+      }))
+
+      const { treeCommand } = await import('./tree.ts')
+      await treeCommand.parseAsync(['task_1', '--relation', 'blocks'], {
+        from: 'user',
+      })
+
+      expect(calls[0]!.variables).toMatchObject({
+        nodeId: 'task_1',
+        relation: 'blocks',
+      })
+    })
+  })
 })

package/src/commands/tree.ts

@@ -7,10 +7,16 @@ export const treeCommand = new Command('tree')
   .description('Show subtree from any entity')
   .argument('<id>', 'Root node ID')
   .option('--depth <n>', 'Max depth', '10')
+  .option(
+    '--relation <relation>',
+    'Edge relation to follow (e.g. part_of, blocks)',
+    'part_of',
+  )
   .action(async (id: string, opts) => {
     try {
       const data = await graphql<{ subtree: unknown[] }>(SUBTREE, {
         nodeId: id,
+        relation: opts.relation,
         maxDepth: Number.parseInt(opts.depth, 10),
       })
       output(data.subtree)

package/src/util/operations.ts

@@ -76,10 +76,11 @@ export const LIST_TASKS = `query ListTasks($nodeId: String!, $relation: String!,
   }
 }`
 
-/** tree.ts — full subtree from any root. */
-export const SUBTREE = `query Subtree($nodeId: String!, $maxDepth: Int) {
-  subtree(nodeId: $nodeId, maxDepth: $maxDepth) {
-    id type title status
+/** tree.ts — subtree from any root, filtered to one relation (default part_of),
+ *  each node annotated with parentId/depth/relation. */
+export const SUBTREE = `query Subtree($nodeId: String!, $relation: String, $maxDepth: Int) {
+  subtree(nodeId: $nodeId, relation: $relation, maxDepth: $maxDepth) {
+    id type title status parentId depth relation
   }
 }`