taskgraph_ts/tasks/implementation/graph/queries.md at 131e3e929b50de5749c864fbd04c4e5e3ffda52d

Files

glm-5.1 131e3e929b Decompose architecture into 28 atomic implementation tasks

Break the @alkdev/taskgraph architecture specs into dependency-ordered
implementation tasks across 8 component directories: setup, schema,
error, graph, analysis, cost-benefit, frontmatter, api, and review.
Each task has clear acceptance criteria referencing specific architecture
docs. Three review tasks serve as quality gates at critical junction
points (schemas-and-errors, graph-complete, complete-library). The
dependency graph is validated acyclic with 9 topological levels enabling
significant parallelism across independent work streams.

2026-04-27 08:30:05 +00:00

2.6 KiB

Raw Blame History

id, name, status, depends_on, scope, risk, impact, level

name

status

depends_on

scope

risk

impact

level

graph/queries

Implement TaskGraph query methods (hasCycles, findCycles, topologicalOrder, dependencies, dependents, taskCount, getTask)

pending

graph/taskgraph-class

moderate

medium

component

implementation

Description

Implement query methods in src/graph/queries.ts and integrate on TaskGraph. The findCycles implementation requires a custom 3-color DFS since graphology-components only gives SCCs, not cycle paths.

Per errors-validation.md:

hasCycles() returns boolean (uses graphology-dag or graphology-components for fast check)
findCycles() returns string[][] — each inner array is an ordered cycle path
topologicalOrder() throws CircularDependencyError with cycles populated when graph is cyclic (per ADR-003)

Acceptance Criteria

hasCycles(): boolean — uses graphology-dag.hasCycle() or graphology-components SCC check as fast pre-check
findCycles(): string[][]:
- Uses stronglyConnectedComponents() as pre-check: if zero multi-node SCCs and no self-loops, skip DFS
- Custom 3-color DFS (WHITE/GREY/BLACK) to extract cycle paths
- Returns one representative cycle per back edge, not exhaustive enumeration
- Each inner array is an ordered node sequence where last node has edge back to first
topologicalOrder(): string[]:
- Uses graphology-dag.topologicalSort() for the actual sort
- Throws CircularDependencyError (with cycles from findCycles()) when graph is cyclic
- Returns string[] of task IDs in prerequisite→dependent order
dependencies(taskId: string): string[] — returns prerequisite task IDs (inNeighbors). Throws TaskNotFoundError if ID doesn't exist.
dependents(taskId: string): string[] — returns dependent task IDs (outNeighbors). Throws TaskNotFoundError if ID doesn't exist.
taskCount(): number — returns number of nodes
getTask(taskId: string): TaskGraphNodeAttributes | undefined — returns node attributes or undefined
Unit tests: cycle detection on known cyclic/acyclic graphs, topologicalOrder on DAG, topologicalOrder throws on cyclic graph, dependency/dependent queries

References

docs/architecture/api-surface.md — query methods
docs/architecture/errors-validation.md — cycle handling, CircularDependencyError
docs/architecture/cost-benefit.md — findCycles algorithm description
docs/architecture/decisions/003-topo-order-throws-on-cycle.md — ADR-003

Notes

To be filled by implementation agent

Summary

To be filled on completion

2.6 KiB Raw Blame History