descendit 0.0.2

Deterministic structural metrics and loss scoring for Rust code
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

# descendit

**Where we're going, we don't need code**

Train code like we train models. `descendit` scores your Rust codebase with deterministic structural loss functions, then your agent iteratively refactors until convergence — score, fix, re-score, repeat.

To get started, have your agent run:

```bash
descendit agent guide
```

It will get back everything it needs to run the loop end-to-end. You'll get something like:

| Epoch | Composite loss | Delta | Action |
|-------|---------------|-------|--------|
| 0 | 0.142 | — | baseline |
| 1 | 0.098 | -0.044 | split bloated function |
| 2 | 0.071 | -0.027 | extract duplicated logic |
| 3 | 0.065 | -0.006 | reduce state cardinality |
| 4 | 0.063 | -0.002 | diminishing returns, stop |

Read the [introductory blog post](https://www.pikach.us/blog/newsletter-2026-03/) for the full motivation.

## Install

```bash
cargo install descendit
```

Requires Rust 1.85+ (edition 2024).

---

## Details

### The refactoring loop

`descendit` is designed for iterative, measurable improvement — like gradient
descent. Use `watch` to keep a persistent rust-analyzer session so repeated
analysis avoids cold starts:

```bash
# Start analysis server
descendit watch --sock /tmp/descendit.sock src/

# Epoch 0: baseline
descendit analyze src/ --sock /tmp/descendit.sock > epoch0.json

# Inspect what to fix first
descendit heatmap src/ --sock /tmp/descendit.sock --top 10

# ... refactor the top hotspot ...

# Epoch 1: measure improvement
descendit analyze src/ --sock /tmp/descendit.sock > epoch1.json
descendit diff epoch0.json epoch1.json --compliance

# Repeat until convergence (|delta| < 0.005 between epochs)

# Shut down the server when done
descendit reap --sock /tmp/descendit.sock
```

Most improvement lands in epochs 1-2. By epoch 4+, you're in diminishing returns.

### Interactive explorer

An interactive TUI flamegraph for drilling into loss attribution with
syntax-highlighted source preview:

```bash
descendit explore src/
```

![Interactive flamegraph explorer](loss_explore.gif)

[Watch the full recording on asciinema](https://asciinema.org/a/vlyBU5qMA3BkxYVb)

### Loss dimensions

Each dimension produces a score in [0, 1] where 1.0 = perfect.

| Dimension | Scope | What it measures |
|-----------|-------|-----------------|
| `duplication` | global | Fraction of functions in structural duplicate groups |
| `state_cardinality` | per-type, per-function | Geometric mean of log2 field cardinality |
| `bloat` | per-function | Function length beyond threshold (35 lines) |
| `code_economy` | global | Overhead ratio (non-test functions / public functions) |
| `coupling_density` | per-module | Cross-module call edges (via rust-analyzer) |

**Composite loss** = `1 - geometric_mean(dimension_scores)`. Range [0, 1], where 0.0 is perfect.

| Composite loss | Quality |
|---------------|---------|
| < 0.05 | Excellent |
| 0.05 - 0.15 | Good |
| 0.15 - 0.30 | Room for improvement |
| 0.30+ | Significant structural issues |

### CLI

```
$ descendit --help
Deterministic structural loss functions for Rust code

Usage: descendit [OPTIONS] <COMMAND>

Commands:
  analyze  Scan source code and produce a raw metrics snapshot
  diff     Compare two analysis snapshots and show what changed
  list     List all available loss dimensions and their descriptions
  watch    Watch paths for changes and serve analysis over a Unix socket
  reap     Shut down a running watch server
  heatmap  Drill down into which functions and types contribute most to loss
  explore  Interactive flamegraph explorer for loss drill-down
  agent    Agent-oriented utilities
  policy   Dump the default compliance policy as JSON
  help     Print this message or the help of the given subcommand(s)

Options:
      --sock <SOCK>  Connect to a running analysis server via this Unix socket path
  -h, --help         Print help
  -V, --version      Print version
```

Run `descendit <command> --help` for detailed flags, or `descendit agent guide` for
the full reference.

### Policy customization

Scoring thresholds and aggregation strategies are configurable via JSON:

```bash
descendit policy --dump-default > my-policy.json
# edit thresholds...
descendit heatmap src/ --policy my-policy.json
```

## License

Apache-2.0