Merge branch 'main' into main

Author: matzehuels

.github/workflows/ci.yml

@@ -4,7 +4,6 @@ on:
   push:
     branches: [main]
   pull_request:
-    branches: [main]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}

README.md

@@ -2,7 +2,6 @@
 
 Inspired by [XKCD #2347](https://xkcd.com/2347/), StackTower renders dependency graphs as **physical towers** where blocks rest on what they depend on. Your application sits at the top, supported by libraries below—all the way down to that one critical package maintained by *some dude in Nebraska*.
 
-Traditional node-link diagrams are technically correct but don't *feel* like anything. Tower visualizations tap into intuition: width shows importance, depth reveals foundation, and the structure makes hidden dependencies visible at a glance.
 
 📖 **[Read the full story at stacktower.io](https://www.stacktower.io)**
 
@@ -38,6 +37,9 @@ stacktower parse rust serde -o serde.json
 
 # JavaScript (npm)
 stacktower parse javascript yup -o yup.json
+
+# PHP (Packagist/Composer)
+stacktower parse php monolog/monolog -o monolog.json
 ```
 
 Add `--enrich` with a `GITHUB_TOKEN` to pull repository metadata (stars, maintainers, last commit) for richer visualizations.
@@ -63,14 +65,20 @@ The repository ships with pre-parsed graphs so you can experiment immediately:
 # Real packages with full metadata
 stacktower render examples/real/flask.json -t tower --style handdrawn --merge -o flask.svg
 stacktower render examples/real/serde.json -t tower --popups -o serde.svg
-stacktower render examples/real/express.json -t tower --ordering barycenter -o express.svg
+stacktower render examples/real/express.json -t tower --ordering barycentric -o express.svg
 
 # Synthetic test cases
 stacktower render examples/test/diamond.json -t tower -o diamond.svg
 ```
 
 ## Options Reference
 
+### Global Options
+
+| Flag | Description |
+|------|-------------|
+| `-v`, `--verbose` | Enable debug logging (search space info, timing details) |
+
 ### Parse Options
 
 | Flag | Description |
@@ -99,6 +107,59 @@ stacktower render examples/test/diamond.json -t tower -o diamond.svg
 |------|-------------|
 | `--detailed` | Show node metadata in labels |
 
+## JSON Format
+
+The render layer accepts a simple JSON format, making it easy to visualize **any** directed graph—not just package dependencies. You can hand-craft graphs for component diagrams, callgraphs, or pipe output from other tools.
+
+### Minimal Example
+
+```json
+{
+  "nodes": [
+    { "id": "app" },
+    { "id": "lib-a" },
+    { "id": "lib-b" }
+  ],
+  "edges": [
+    { "from": "app", "to": "lib-a" },
+    { "from": "lib-a", "to": "lib-b" }
+  ]
+}
+```
+
+### Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `nodes[].id` | string | Unique node identifier (displayed as label) |
+| `edges[].from` | string | Source node ID |
+| `edges[].to` | string | Target node ID |
+
+### Optional Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `nodes[].row` | int | Pre-assigned layer (computed automatically if omitted) |
+| `nodes[].kind` | string | Internal use: `"subdivider"` or `"auxiliary"` |
+| `nodes[].meta` | object | Freeform metadata for display features |
+
+### Recognized `meta` Keys
+
+These keys are read by specific render flags. All are optional—missing keys simply disable the corresponding feature.
+
+| Key | Type | Used By |
+|-----|------|---------|
+| `repo_url` | string | Clickable blocks, `--popups`, `--nebraska` |
+| `repo_stars` | int | `--popups` |
+| `repo_owner` | string | `--nebraska` |
+| `repo_maintainers` | []string | `--nebraska`, `--popups` |
+| `repo_last_commit` | string (date) | `--popups`, brittle detection |
+| `repo_last_release` | string (date) | `--popups` |
+| `repo_archived` | bool | `--popups`, brittle detection |
+| `summary` | string | `--popups` (fallback: `description`) |
+
+The `--detailed` flag (node-link only) displays **all** meta keys in the node label.
+
 ## How It Works
 
 1. **Parse** — Fetch package metadata from registries (PyPI, crates.io, npm)
@@ -121,11 +182,27 @@ The ordering step is where the magic happens. StackTower uses an optimal search
 
 HTTP responses are cached in `~/.cache/stacktower/` with a 24-hour TTL. Use `--refresh` to bypass.
 
+## Adding New Languages
+
+To add support for a new package manager (e.g., Ruby/RubyGems):
+
+1. **Create a registry client** in `pkg/integrations/rubygems/client.go` — parse the registry API, extract dependencies, use `integrations.BaseClient` for HTTP + caching
+
+2. **Create a source parser** in `pkg/source/ruby/ruby.go` — implement the `source.PackageInfo` interface (`GetName`, `GetVersion`, `GetDependencies`, `ToMetadata`, `ToRepoInfo`)
+
+3. **Wire into CLI** in `internal/cli/parse.go`:
+   ```go
+   cmd.AddCommand(newParserCmd("ruby <gem>", "Parse Ruby dependencies",
+       func() (source.Parser, error) { return ruby.NewParser(source.DefaultCacheTTL) }, &opts))
+   ```
+
+The generic `source.Parse()` handles concurrent fetching, depth limits, and graph construction automatically.
+
 ## Learn More
 
 - 📖 **[stacktower.io](https://www.stacktower.io)** — Interactive examples and the full story behind tower visualizations
 - 🐛 **[Issues](https://github.com/matzehuels/stacktower/issues)** — Bug reports and feature requests
 
 ## License
 
-MIT
+Apache-2.0

internal/cli/parse.go

@@ -12,6 +12,7 @@ import (
 	"github.com/matzehuels/stacktower/pkg/source"
 	"github.com/matzehuels/stacktower/pkg/source/javascript"
 	"github.com/matzehuels/stacktower/pkg/source/metadata"
+	"github.com/matzehuels/stacktower/pkg/source/php"
 	"github.com/matzehuels/stacktower/pkg/source/python"
 	"github.com/matzehuels/stacktower/pkg/source/rust"
 	"github.com/matzehuels/stacktower/pkg/source/ruby"
@@ -50,6 +51,8 @@ func newParseCmd() *cobra.Command {
 		func() (source.Parser, error) { return javascript.NewParser(source.DefaultCacheTTL) }, &opts))
 	cmd.AddCommand(newParserCmd("ruby <gem>", "Parse Ruby gem dependencies from RubyGems",
 		func() (source.Parser, error) { return ruby.NewParser(source.DefaultCacheTTL) }, &opts))
+	cmd.AddCommand(newParserCmd("php <package>", "Parse PHP (Composer) package dependencies from Packagist",
+		func() (source.Parser, error) { return php.NewParser(source.DefaultCacheTTL) }, &opts))
 
 	return cmd
 }

internal/cli/render.go

@@ -256,7 +256,12 @@ func buildLayoutOpts(ctx context.Context, opts *renderOpts) ([]tower.Option, err
 
 func withOptimalSearchProgress(ctx context.Context, timeoutSec int) ordering.Orderer {
 	logger := loggerFromContext(ctx)
-	o := &optimalSearchOrderer{prog: newProgress(logger), logger: logger, lastBest: -1}
+	o := &optimalSearchOrderer{
+		prog:     newProgress(logger),
+		logger:   logger,
+		lastBest: -1,
+		start:    time.Now(),
+	}
 
 	o.OptimalSearch = ordering.OptimalSearch{
 		Timeout: time.Duration(timeoutSec) * time.Second,
@@ -269,11 +274,34 @@ func withOptimalSearchProgress(ctx context.Context, timeoutSec int) ordering.Ord
 			switch {
 			case o.lastBest < 0:
 				logger.Infof("Initial: %d crossings (explored: %d, pruned: %d)", bestScore, explored, pruned)
+				o.lastLog = time.Now()
 			case bestScore < o.lastBest:
 				logger.Infof("Improved: %d crossings (↓%d)", bestScore, o.lastBest-bestScore)
+				o.lastLog = time.Now()
+			default:
+				if time.Since(o.lastLog) >= 10*time.Second {
+					elapsed := time.Since(o.start).Truncate(time.Second)
+					logger.Infof("Searching... %v/%ds elapsed, %d crossings (pruned: %d)", elapsed, timeoutSec, bestScore, pruned)
+					o.lastLog = time.Now()
+				}
 			}
 			o.lastBest = bestScore
 		},
+		Debug: func(info ordering.DebugInfo) {
+			logger.Debugf("Search space: %d rows, max depth reached: %d/%d", info.TotalRows, info.MaxDepth, info.TotalRows)
+
+			bottlenecks := 0
+			for _, r := range info.Rows {
+				if r.Candidates > 100 {
+					logger.Debugf("  Row %d: %d nodes, %d candidates", r.Row, r.NodeCount, r.Candidates)
+					bottlenecks++
+				}
+			}
+
+			if info.MaxDepth < info.TotalRows && bottlenecks > 0 {
+				logger.Debugf("Search incomplete: %d rows have >100 candidates, causing combinatorial explosion", bottlenecks)
+			}
+		},
 	}
 	return o
 }
@@ -284,6 +312,7 @@ type optimalSearchOrderer struct {
 	logger                   *log.Logger
 	lastExplored, lastPruned int
 	lastBest                 int
+	start, lastLog           time.Time
 }
 
 func (o *optimalSearchOrderer) OrderRows(g *dag.DAG) map[int][]string {
@@ -294,6 +323,9 @@ func (o *optimalSearchOrderer) OrderRows(g *dag.DAG) map[int][]string {
 		o.logger.Infof("Best: %d crossings (explored: %d, pruned: %d)",
 			crossings, o.lastExplored, o.lastPruned)
 	}
+	if crossings > 0 {
+		o.logger.Warn("Layout has edge crossings; try increasing the timeout (--ordering-timeout)")
+	}
 	return result
 }
 

pkg/dag/perm/pqtree.go

@@ -358,77 +358,90 @@ func (t *PQTree) Enumerate(limit int) [][]int {
 	}
 
 	var results [][]int
-	t.enumerate(t.root, nil, limit, &results)
+	t.enumerateLazy(t.root, nil, func(perm []int) bool {
+		results = append(results, perm)
+		return limit <= 0 || len(results) < limit
+	})
 	return results
 }
 
-func (t *PQTree) enumerate(node *pqNode, prefix []int, limit int, results *[][]int) bool {
-	if limit > 0 && len(*results) >= limit {
-		return false
-	}
-
+// enumerateLazy generates permutations one at a time via callback.
+// Returns false if callback signaled stop, true otherwise.
+func (t *PQTree) enumerateLazy(node *pqNode, prefix []int, emit func([]int) bool) bool {
 	if node.kind == leafNode {
-		*results = append(*results, append(slices.Clone(prefix), node.value))
-		return true
+		return emit(append(slices.Clone(prefix), node.value))
 	}
 
-	perms := t.childPermutations(node)
-	for _, perm := range perms {
-		if limit > 0 && len(*results) >= limit {
+	return t.forEachChildPerm(node, func(children []*pqNode) bool {
+		return t.enumerateChildrenLazy(children, prefix, emit)
+	})
+}
+
+// For Q-nodes: yields forward and reverse only.
+// For P-nodes: generates permutations one at a time without storing them all.
+func (t *PQTree) forEachChildPerm(node *pqNode, fn func([]*pqNode) bool) bool {
+	if node.kind == qNode {
+		if !fn(node.children) {
 			return false
 		}
-		if !t.enumerateChildren(perm, prefix, limit, results) {
-			return false
+		if len(node.children) <= 1 {
+			return true
 		}
+		rev := slices.Clone(node.children)
+		slices.Reverse(rev)
+		return fn(rev)
 	}
 
-	return true
-}
+	// P-node: Generate permutations lazily
+	n := len(node.children)
+	if n == 0 {
+		return fn(nil)
+	}
+	if n == 1 {
+		return fn(node.children)
+	}
 
-func (t *PQTree) childPermutations(node *pqNode) [][]*pqNode {
-	if node.kind == qNode {
-		fwd := slices.Clone(node.children)
-		rev := slices.Clone(node.children)
-		slices.Reverse(rev)
-		return [][]*pqNode{fwd, rev}
+	perm := slices.Clone(node.children)
+	state := make([]int, n)
+
+	// Emit first permutation (identity)
+	if !fn(slices.Clone(perm)) {
+		return false
 	}
 
-	indexPerms := Generate(len(node.children), -1)
-	result := make([][]*pqNode, len(indexPerms))
-	for i, perm := range indexPerms {
-		ordered := make([]*pqNode, len(perm))
-		for j, idx := range perm {
-			ordered[j] = node.children[idx]
+	// iteratively generate remaining permutations
+	for i := 0; i < n; {
+		if state[i] < i {
+			if i&1 == 0 {
+				perm[0], perm[i] = perm[i], perm[0]
+			} else {
+				perm[state[i]], perm[i] = perm[i], perm[state[i]]
+			}
+			if !fn(slices.Clone(perm)) {
+				return false
+			}
+			state[i]++
+			i = 0
+		} else {
+			state[i] = 0
+			i++
 		}
-		result[i] = ordered
 	}
-	return result
+	return true
 }
 
-func (t *PQTree) enumerateChildren(children []*pqNode, prefix []int, limit int, results *[][]int) bool {
+func (t *PQTree) enumerateChildrenLazy(children []*pqNode, prefix []int, emit func([]int) bool) bool {
 	if len(children) == 0 {
-		*results = append(*results, slices.Clone(prefix))
-		return true
+		return emit(slices.Clone(prefix))
 	}
 
 	first := children[0]
 	rest := children[1:]
 
-	var firstPerms [][]int
-	t.enumerate(first, nil, 0, &firstPerms)
-
-	for _, fp := range firstPerms {
-		if limit > 0 && len(*results) >= limit {
-			return false
-		}
-
-		newPrefix := append(slices.Clone(prefix), fp...)
-		if !t.enumerateChildren(rest, newPrefix, limit, results) {
-			return false
-		}
-	}
-
-	return true
+	return t.enumerateLazy(first, nil, func(firstPerm []int) bool {
+		newPrefix := append(slices.Clone(prefix), firstPerm...)
+		return t.enumerateChildrenLazy(rest, newPrefix, emit)
+	})
 }
 
 func (t *PQTree) ValidCount() int {