dependency_graph.ts

Declarations
#

Dependency graph data structure and algorithms for multi-repo publishing.
Provides DependencyGraph class with topological sort and cycle detection. For validation workflow and publishing order computation, see graph_validation.ts.

7 declarations

view source

DEPENDENCY_TYPE
#

dependency_graph.ts view source

{ readonly PROD: "prod"; readonly PEER: "peer"; readonly DEV: "dev"; }

DependencyGraph
#

dependency_graph.ts view source

`nodes`

type Map<string, DependencyNode>

`edges`

type Map<string, Set<string>>

`constructor`

type new (): DependencyGraph

`init_from_repos`

type (repos: LocalRepo[]): void

public

`repos`

type LocalRepo[]

returns void

`get_node`

type (name: string): DependencyNode | undefined

`name`

type string

returns DependencyNode | undefined

`get_dependents`

type (name: string): Set<string>

`name`

type string

returns Set<string>

`get_dependencies`

type (name: string): Map<string, DependencySpec>

`name`

type string

returns Map<string, DependencySpec>

`topological_sort`

Computes topological sort order for dependency graph.

Uses Kahn's algorithm with alphabetical ordering within tiers for deterministic results. Throws if cycles detected.

type (exclude_dev?: boolean): string[]

`exclude_dev`

if true, excludes dev dependencies to break cycles. Publishing uses exclude_dev=true to handle circular dev deps.

type boolean

default false

returns string[]

array of package names in dependency order (dependencies before dependents)

throws

if - circular dependencies detected in included dependency types

`detect_cycles`

type (): string[][]

returns string[][]

`detect_cycles_by_type`

Detects circular dependencies, categorized by severity.

Production/peer cycles prevent publishing (impossible to order packages). Dev cycles are normal (test utils, shared configs) and safely ignored.

Uses DFS traversal with recursion stack to identify back edges. Deduplicates cycles using sorted cycle keys.

type (): { production_cycles: string[][]; dev_cycles: string[][]; }

returns { production_cycles: string[][]; dev_cycles: string[][]; }

object with production_cycles (errors) and dev_cycles (info)

`toJSON`

type (): DependencyGraphJson

returns DependencyGraphJson

DependencyGraphBuilder
#

dependency_graph.ts view source

Builder for creating and analyzing dependency graphs.

`build_from_repos`

Constructs dependency graph from local repos.

Two-pass algorithm: first creates nodes, then builds edges (dependents). Prioritizes prod/peer deps over dev deps when same package appears in multiple dependency types (stronger constraint wins).

type (repos: LocalRepo[]): DependencyGraph

`repos`

type LocalRepo[]

returns DependencyGraph

fully initialized dependency graph with all nodes and edges

`compute_publishing_order`

Computes publishing order using topological sort with dev deps excluded.

Excludes dev dependencies to break circular dev dependency cycles while preserving production/peer dependency ordering. This allows patterns like shared test utilities that depend on each other for development.

type (graph: DependencyGraph): string[]

`graph`

type DependencyGraph

returns string[]

package names in safe publishing order (dependencies before dependents)

throws

if - production/peer cycles detected (cannot be resolved by exclusion)

`analyze`

type (graph: DependencyGraph): { production_cycles: string[][]; dev_cycles: string[][]; wildcard_deps: { pkg: string; dep: string; version: string; }[]; missing_peers: { pkg: string; dep: string; }[]; }

`graph`

type DependencyGraph

returns

{ production_cycles: string[][]; dev_cycles: string[][]; wildcard_deps: { pkg: string; dep: string; version: string; }[]; missing_peers: { pkg: string; dep: string; }[]; }

DependencyGraphJson
#

dependency_graph.ts view source

DependencyGraphJson

`nodes`

type

Array<{
		name: string;
		version: string;
		dependencies: Array<{name: string; spec: DependencySpec}>;
		dependents: Array<string>;
		publishable: boolean;
	}>