code_passenger 0.2.0

Language-pack + header-plan driven code annotator: scans usage + auto-generates feature gates and doc headers.
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
143
144
145
146
147
148
149
150
151
152
153

###
---

### code_passenger 0.2.0 — scans a workspace with klepto, then does the writing klepto never does:
### feature gates, cargo edits, headers, reports.

###
---

### the feature-gating loop (new in 0.2.0)

write a spec that says what you want the feature model to look like:

```toml
# klepto.toml — move `beta` behind a feature `b` in package `app`
[app]
optional = ["beta"]
default = []

[app.features]
b = ["dep:beta"]
```

then:

```bash
# what would change (plan + diff), nothing written
code-passenger --root . gate --spec klepto.toml

# CI: exit 1 while there is gating left to do
code-passenger --root . gate --spec klepto.toml --check

# prove it with real `cargo check` on a scratch copy, then write it
code-passenger --root . gate --spec klepto.toml --write
```

what happens:

1. klepto plans the gates: every use of `beta` that is not already behind
   `feature = "b"` gets a `#[cfg(feature = "b")]` on its carrier, and
   everything that depends on those carriers gets one too (the cascade).
2. the cargo oracle copies the tree to a scratch dir (minus `target`,
   `.git`, `.passenger`), applies the plan there, and runs `cargo check`
   for every feature combination that matters. errors the plan missed come
   back as forced gates; it goes again until everything compiles.
3. only then, and only with `--write`, the real files change: `#[cfg]`
   lines above the items (an existing `#[cfg(unix)]` becomes
   `#[cfg(all(unix, feature = "b"))]`, never two attributes stacked) and
   `Cargo.toml` edits through `toml_edit` so your formatting survives.

exit codes: `0` nothing to do or converged, `1` `--check` found work or
the oracle gave up, `2` something a person has to decide (the plan lists
it under `unknown` / `human`). nothing is written on 1 or 2.

###
---

### review before you gate

```bash
code-passenger --root . feature-map                          # crates, features, deps, use-site counts
code-passenger --root . feature-sites beta                   # every use site of a dep (or of a feature's deps), by file, with cfg
code-passenger --root . feature-probe beta --spec klepto.toml   # what is ungated, what would be gated, what gets lost; never writes
```

`--json` on any of them prints the structure instead of the text.

###
---

### the rest of klepto, on the command line

```bash
code-passenger --root . receipt --out receipt.json --kg kg/   # the versioned receipt + knowledge-graph ndjson
code-passenger --root . lint [--policy policy.toml]           # klepto's analyses under a policy; exit code = verdict
code-passenger --root . patterns --top 20                     # repeated code: extract / parameterize / generic / trait / macro candidates
```

the default lint policy denies ungated dependency uses (KLEP010) and
cfg-edge violations (KLEP011) and allows the noisy info rules. a policy
file looks like:

```toml
[levels]
KLEP013 = "deny"     # unreferenced private items fail the build
KLEP001 = "allow"

[max]
KLEP002 = 0          # no unwrap in public API
```

###
---

### the original job: headers

### check out report.json, it was made by doing this:
```bash
cargo run -- --root ../classified --src src --json scan
```

### if you wanna see the crate it was made from, go check out:

```txt
https://github.com/jameshuntt/classified
```

### it is designed to make file headers and documentations that explains itself
### it is intended to be a templating engine for max flexibility

# intended to produce things like this on command:

```txt
//! ----------------------------------------------
//! DOCUMENT DETAILS -----------------------------
//! 
//! filename:thread_pool_manager.rs
//! description:
//! usages:none in crate yet
//! 
//! ----------------------------------------------
//! FEATURE NOTES --------------------------------
//! 
//! feature_name:async
//! deps:[tokio][async_trait]
//! scope:[impl ThreadPoolManager]
//! corpus:true
//! 
//! feature_name:std
//! deps:[std]
//! scope:[impl ThreadPoolManager]
//! corpus:false
//! 
//! ----------------------------------------------
//! CORPUS FEATURES ------------------------------
//! 
#![cfg(feature = "async")]
#![cfg(feature = "std")]
```

`scan`, `annotate`, `scaffold` and `passenger` (the checkpoint store) are
unchanged in 0.2.0.

###
---

### notes

- klepto is a path dependency until klepto 0.2.0 is on crates.io.
- the oracle runs `cargo` offline; path dependencies only, nothing is
  downloaded and nothing outside the scratch copy is touched.
- the rules every command follows, with the fixture and tests that pin
  them, are in `the gate rules (cited in the source)` and `tests/gate.rs`.