alef 0.72.0

Opinionated polyglot binding generator for Rust libraries
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
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
use super::*;
use crate::test_support::{git_add, git_init, write_file};
use tracing_test::traced_test;

fn config() -> ResolvedCrateConfig {
    ResolvedCrateConfig {
        name: "sample".to_string(),
        ..ResolvedCrateConfig::default()
    }
}

/// Regression for #178: a filtered `generate --lang python` must not return
/// any other language's directory, nor the unconditional wasm/typescript
/// roots. Sweeping them with a python-only keep set was deleting every other
/// binding's still-valid output.
#[test]
fn filtered_run_excludes_other_languages_and_ts_fallback_roots() {
    let base = Path::new("/base");
    let roots = generate_sweep_roots(&[Language::Python], true, &config(), base);

    assert!(
        roots.contains(&base.join("packages/python")),
        "must keep the requested language"
    );
    assert!(
        !roots.contains(&base.join("packages/ruby")),
        "must not touch an unrequested language"
    );
    assert!(
        !roots.contains(&base.join("packages/wasm")),
        "must not add the wasm fallback root on a filtered run"
    );
    assert!(
        !roots.contains(&base.join("packages/typescript")),
        "must not add the typescript fallback root on a filtered run"
    );
}

#[test]
fn unfiltered_run_includes_all_languages_and_ts_fallback_roots() {
    let base = Path::new("/base");
    let roots = generate_sweep_roots(&[Language::Python, Language::Ruby], false, &config(), base);

    assert!(roots.contains(&base.join("packages/python")));
    assert!(roots.contains(&base.join("packages/ruby")));
    assert!(
        roots.contains(&base.join("packages/wasm")),
        "unfiltered run keeps the wasm fallback root"
    );
    assert!(
        roots.contains(&base.join("packages/typescript")),
        "unfiltered run keeps the typescript fallback root"
    );
}

#[test]
fn manifest_sweep_removes_only_prior_managed_orphans_in_selected_root() {
    let dir = tempfile::tempdir().expect("tempdir");
    let selected = dir.path().join("python");
    let other = dir.path().join("ruby");
    std::fs::create_dir_all(&selected).expect("selected root");
    std::fs::create_dir_all(&other).expect("other root");
    let managed = selected.join("orphan.py");
    let handwritten = selected.join("notes.py");
    let unselected = other.join("orphan.rb");
    let header = crate::core::hash::header(crate::core::hash::CommentStyle::Hash);
    let hashed = crate::core::hash::inject_hash_line(&header, &"0".repeat(64));
    std::fs::write(&managed, &hashed).expect("managed");
    std::fs::write(&handwritten, "handwritten\n").expect("handwritten");
    std::fs::write(&unselected, &hashed).expect("unselected");

    let previous = vec![managed.clone(), handwritten.clone(), unselected.clone()];
    let removed =
        sweep_manifest_orphans(&previous, &std::collections::HashSet::new(), &[selected], &[]).expect("manifest sweep");

    assert_eq!(removed, 1);
    assert!(!managed.exists());
    assert!(handwritten.exists());
    assert!(unselected.exists());
}

#[test]
fn manifest_sweep_preserves_non_header_generator_manifests() {
    let dir = tempfile::tempdir().expect("tempdir");
    let selected = dir.path().join("swift");
    let manifest = selected.join("rust/Cargo.toml");
    std::fs::create_dir_all(manifest.parent().expect("manifest parent")).expect("selected root");
    let header = crate::core::hash::header(crate::core::hash::CommentStyle::Hash);
    let hashed = crate::core::hash::inject_hash_line(&header, &"0".repeat(64));
    std::fs::write(&manifest, hashed).expect("manifest");

    let previous = vec![manifest.clone()];
    let keep = std::collections::HashSet::from([manifest.clone()]);
    let removed = sweep_manifest_orphans(&previous, &keep, &[selected], &[]).expect("manifest sweep");

    assert_eq!(removed, 0);
    assert!(manifest.exists());
}

/// A manifest alef wrote last run and does not write this run IS reclaimed,
/// even though `composer.json` never carries a marker or hash — this is the
/// core "previous-manifest provenance" case from orphan reports filed by two
/// independent consumer repos: a co-located/split layout toggle stops emitting
/// a `composer.json` copy, and the old copy must not linger forever.
#[test]
fn manifest_sweep_reclaims_unmarkable_manifest_absent_from_current_run() {
    let dir = tempfile::tempdir().expect("tempdir");
    let package_dir = dir.path().join("packages/php");
    std::fs::create_dir_all(&package_dir).expect("package dir");
    let composer_json = package_dir.join("composer.json");
    std::fs::write(&composer_json, "{\n  \"name\": \"acme/demo\"\n}\n").expect("composer.json");

    let previous = vec![composer_json.clone()];
    let removed = sweep_manifest_orphans(&previous, &std::collections::HashSet::new(), &[package_dir], &[])
        .expect("manifest sweep");

    assert_eq!(removed, 1, "unmarkable manifest absent from this run must be reclaimed");
    assert!(!composer_json.exists());
}

/// A manifest alef writes on both runs is NOT touched: it is present in
/// `keep` (this run's own output), so the `keep.contains(path)` guard must
/// short-circuit before `path_is_reclaimable` (and therefore before the
/// unmarkable-manifest allowlist) is ever consulted.
#[test]
fn manifest_sweep_preserves_unmarkable_manifest_still_written_this_run() {
    let dir = tempfile::tempdir().expect("tempdir");
    let package_dir = dir.path().join("packages/php");
    std::fs::create_dir_all(&package_dir).expect("package dir");
    let composer_json = package_dir.join("composer.json");
    std::fs::write(&composer_json, "{\n  \"name\": \"acme/demo\"\n}\n").expect("composer.json");

    let previous = vec![composer_json.clone()];
    let keep = std::collections::HashSet::from([composer_json.clone()]);
    let removed = sweep_manifest_orphans(&previous, &keep, &[package_dir], &[]).expect("manifest sweep");

    assert_eq!(removed, 0, "manifest still written this run must survive");
    assert!(composer_json.exists());
}

/// Reclaiming an orphaned `composer.json` cascades to its `composer.lock`
/// sibling in the same directory — the concrete instance seen in a consumer
/// repo: a lockfile whose manifest was removed long ago must not linger forever
/// either, even though alef never authored the lockfile itself.
#[test]
fn manifest_sweep_reclaims_lockfile_sibling_of_reclaimed_manifest() {
    let dir = tempfile::tempdir().expect("tempdir");
    let package_dir = dir.path().join("packages/php");
    std::fs::create_dir_all(&package_dir).expect("package dir");
    let composer_json = package_dir.join("composer.json");
    let composer_lock = package_dir.join("composer.lock");
    std::fs::write(&composer_json, "{\n  \"name\": \"acme/demo\"\n}\n").expect("composer.json");
    std::fs::write(&composer_lock, "{\n  \"_readme\": []\n}\n").expect("composer.lock");

    let previous = vec![composer_json.clone()];
    let removed = sweep_manifest_orphans(&previous, &std::collections::HashSet::new(), &[package_dir], &[])
        .expect("manifest sweep");

    assert_eq!(
        removed, 2,
        "both the manifest and its lockfile sibling must be reclaimed"
    );
    assert!(!composer_json.exists());
    assert!(
        !composer_lock.exists(),
        "orphaned lockfile must be reclaimed alongside its manifest"
    );
}

/// THE risk-bounding test: a hand-authored `composer.lock` at a path alef
/// has never emitted a `composer.json` for must survive `--clean`. This is
/// the case the design explicitly calls out as capable of real damage — a
/// predicate that was widened to "any lockfile in a package dir" (instead of
/// "a lockfile beside a manifest this call just reclaimed by provenance")
/// would delete it, because `previous_paths` is empty here: alef has no
/// record of ever writing anything in this directory.
#[test]
fn manifest_sweep_preserves_hand_authored_lockfile_alef_never_emitted() {
    let dir = tempfile::tempdir().expect("tempdir");
    let package_dir = dir.path().join("packages/php");
    std::fs::create_dir_all(&package_dir).expect("package dir");
    // No composer.json ever existed here — this project was never scaffolded
    // by alef, only a developer ran `composer install` by hand.
    let hand_authored_lock = package_dir.join("composer.lock");
    std::fs::write(&hand_authored_lock, "{\n  \"_readme\": [\"hand rolled\"]\n}\n").expect("hand-authored lock");

    let previous: Vec<PathBuf> = Vec::new();
    let removed = sweep_manifest_orphans(&previous, &std::collections::HashSet::new(), &[package_dir], &[])
        .expect("manifest sweep");

    assert_eq!(
        removed, 0,
        "a lockfile with no reclaimed manifest sibling must never be touched"
    );
    assert!(
        hand_authored_lock.exists(),
        "hand-authored lockfile alef never emitted must survive"
    );
}

/// Second half of the risk-bounding guarantee: even when a real
/// `composer.json` exists beside the lockfile, the lockfile survives if the
/// manifest is still being written this run (`keep`) — the cascade must only
/// fire when the manifest itself was actually reclaimed, never merely
/// because a lockfile happens to sit beside *some* manifest.
#[test]
fn manifest_sweep_preserves_lockfile_when_its_manifest_is_still_kept() {
    let dir = tempfile::tempdir().expect("tempdir");
    let package_dir = dir.path().join("packages/php");
    std::fs::create_dir_all(&package_dir).expect("package dir");
    let composer_json = package_dir.join("composer.json");
    let composer_lock = package_dir.join("composer.lock");
    std::fs::write(&composer_json, "{\n  \"name\": \"acme/demo\"\n}\n").expect("composer.json");
    std::fs::write(&composer_lock, "{\n  \"_readme\": []\n}\n").expect("composer.lock");

    let previous = vec![composer_json.clone()];
    let keep = std::collections::HashSet::from([composer_json.clone()]);
    let removed = sweep_manifest_orphans(&previous, &keep, &[package_dir], &[]).expect("manifest sweep");

    assert_eq!(removed, 0);
    assert!(composer_json.exists());
    assert!(
        composer_lock.exists(),
        "lockfile must survive when its manifest is still written this run"
    );
}

/// Documents the chosen behavior for the genuinely contentious case: a user
/// hand-edits an unmarkable manifest (`composer.json`) at a path alef
/// previously wrote and has now decided to stop writing. The unmarkable-
/// manifest route does not inspect content (see `path_is_reclaimable`'s
/// doc), so the hand-edited file is reclaimed exactly like an untouched one
/// — deletion wins over preserving the edit, because alef's current-run
/// intent ("this path is not mine") is unambiguous and the file is already
/// orphaned relative to that intent.
#[test]
fn manifest_sweep_reclaims_user_modified_unmarkable_manifest_at_disowned_path() {
    let dir = tempfile::tempdir().expect("tempdir");
    let package_dir = dir.path().join("packages/php");
    std::fs::create_dir_all(&package_dir).expect("package dir");
    let composer_json = package_dir.join("composer.json");
    std::fs::write(
        &composer_json,
        "{\n  \"name\": \"acme/demo\",\n  \"require\": {\n    \"hand-added/package\": \"^9.9\"\n  }\n}\n",
    )
    .expect("hand-edited composer.json");

    let previous = vec![composer_json.clone()];
    let removed = sweep_manifest_orphans(&previous, &std::collections::HashSet::new(), &[package_dir], &[])
        .expect("manifest sweep");

    assert_eq!(
        removed, 1,
        "hand-edited content at a disowned path is reclaimed, not preserved"
    );
    assert!(!composer_json.exists());
}

/// The unmarkable-manifest allowlist is narrow by construction: a filename
/// outside [`UNMARKABLE_ALEF_MANIFESTS`] (e.g. `pubspec.yaml`, which opts
/// out of a marker for unrelated reasons) still requires the original
/// content-based marker check. This guards against the allowlist silently
/// growing to swallow every `generated_header: false` scaffold file.
#[test]
fn manifest_sweep_does_not_widen_provenance_route_beyond_the_allowlist() {
    let dir = tempfile::tempdir().expect("tempdir");
    let package_dir = dir.path().join("packages/dart");
    std::fs::create_dir_all(&package_dir).expect("package dir");
    let pubspec = package_dir.join("pubspec.yaml");
    std::fs::write(&pubspec, "name: demo\nversion: 1.0.0\n").expect("pubspec.yaml");

    let previous = vec![pubspec.clone()];
    let removed = sweep_manifest_orphans(&previous, &std::collections::HashSet::new(), &[package_dir], &[])
        .expect("manifest sweep");

    assert_eq!(
        removed, 0,
        "a filename outside the allowlist must still require the marker check"
    );
    assert!(pubspec.exists());
}

#[test]
fn recursive_sweep_and_collection_ignore_hash_only_files() {
    let dir = tempfile::tempdir().expect("tempdir");
    let generated_root = dir.path().join("java");
    std::fs::create_dir_all(&generated_root).expect("generated root");
    let legacy_scaffold = generated_root.join("settings.gradle.kts");
    std::fs::write(
        &legacy_scaffold,
        format!("// alef:hash:{}\nrootProject.name = \"sample\"\n", "0".repeat(64)),
    )
    .expect("legacy scaffold");

    let removed = sweep_orphans(std::slice::from_ref(&generated_root), &std::collections::HashSet::new())
        .expect("recursive sweep");
    let collected = collect_alef_headered_paths(&generated_root);

    assert_eq!(removed, 0);
    assert!(legacy_scaffold.exists());
    assert!(!collected.contains(&legacy_scaffold));
}

/// The core case this whole route exists for: a file dropped from every manifest still on
/// disk (simulated here by a `previous_paths`/`keep` that never mention it at all) is
/// unreachable by the `previous_paths` route no matter how correct today's bookkeeping is --
/// only the marker on disk, under a root the caller has vouched for, can find it.
/// The disk-scan route REPORTS and never deletes. This test previously asserted the opposite
/// and is inverted deliberately: the same five-clause gate it encoded would have deleted a
/// consumer's Java public API class and a class a live test depended on, both of which passed
/// every clause. Absence from a run's output does not prove a file is an orphan. If this test
/// is ever "fixed" back to asserting deletion, read `report_disk_scan_candidates`' doc first. ~keep
#[test]
fn manifest_sweep_disk_scan_reports_but_never_deletes_a_marked_file_absent_from_keep() {
    let dir = tempfile::tempdir().expect("tempdir");
    let package_dir = dir.path().join("packages/kotlin_android");
    std::fs::create_dir_all(&package_dir).expect("package dir");
    git_init(&package_dir);

    let kept = package_dir.join("Bridge.kt");
    let orphan = package_dir.join("Language.kt");
    let header = crate::core::hash::header(crate::core::hash::CommentStyle::DoubleSlash);
    let hashed = crate::core::hash::inject_hash_line(&header, &"0".repeat(64));
    std::fs::write(&kept, &hashed).expect("kept file");
    std::fs::write(&orphan, &hashed).expect("orphan file");
    git_add(&package_dir, &["Bridge.kt"]);
    git_add(&package_dir, &["Language.kt"]);

    let previous = vec![kept.clone()];
    let keep = std::collections::HashSet::from([kept.clone()]);

    let removed = sweep_manifest_orphans(
        &previous,
        &keep,
        std::slice::from_ref(&package_dir),
        std::slice::from_ref(&package_dir),
    )
    .expect("manifest sweep");

    assert_eq!(removed, 0, "the disk-scan route must never delete");
    assert!(
        orphan.exists(),
        "a marked, tracked file absent from keep must be REPORTED, not removed -- it may be a \
         create-once seed or a file the emitter failed to emit this run"
    );
    assert!(kept.exists(), "the file still recorded in keep must survive");
}

#[test]
fn manifest_sweep_disk_scan_preserves_unmarked_tracked_file_absent_from_keep() {
    let dir = tempfile::tempdir().expect("tempdir");
    let package_dir = dir.path().join("packages/kotlin_android");
    std::fs::create_dir_all(&package_dir).expect("package dir");
    git_init(&package_dir);

    let kept = package_dir.join("Bridge.kt");
    let handwritten = package_dir.join("Extensions.kt");
    let header = crate::core::hash::header(crate::core::hash::CommentStyle::DoubleSlash);
    let hashed = crate::core::hash::inject_hash_line(&header, &"0".repeat(64));
    std::fs::write(&kept, &hashed).expect("kept file");
    std::fs::write(&handwritten, "fun extra() {}\n").expect("handwritten file");
    git_add(&package_dir, &["Bridge.kt"]);
    git_add(&package_dir, &["Extensions.kt"]);

    let previous = vec![kept.clone()];
    let keep = std::collections::HashSet::from([kept.clone()]);

    let removed = sweep_manifest_orphans(
        &previous,
        &keep,
        std::slice::from_ref(&package_dir),
        std::slice::from_ref(&package_dir),
    )
    .expect("manifest sweep");

    assert_eq!(
        removed, 0,
        "a file with no alef marker must never be deleted by the disk-scan route"
    );
    assert!(handwritten.exists());
}

#[test]
fn manifest_sweep_disk_scan_preserves_tracked_marked_file_present_in_keep() {
    let dir = tempfile::tempdir().expect("tempdir");
    let package_dir = dir.path().join("packages/kotlin_android");
    std::fs::create_dir_all(&package_dir).expect("package dir");
    git_init(&package_dir);

    let kept = package_dir.join("Bridge.kt");
    let header = crate::core::hash::header(crate::core::hash::CommentStyle::DoubleSlash);
    let hashed = crate::core::hash::inject_hash_line(&header, &"0".repeat(64));
    std::fs::write(&kept, &hashed).expect("kept file");
    git_add(&package_dir, &["Bridge.kt"]);

    let previous = vec![kept.clone()];
    let keep = std::collections::HashSet::from([kept.clone()]);

    let removed = sweep_manifest_orphans(
        &previous,
        &keep,
        std::slice::from_ref(&package_dir),
        std::slice::from_ref(&package_dir),
    )
    .expect("manifest sweep");

    assert_eq!(removed, 0);
    assert!(kept.exists());
}

/// The concrete failure mode this gate exists for: a backend whose manifest bookkeeping
/// records only its Rust crate source path, and never a single path under its own
/// language-output root (measured on a real tree, for several backends), is indistinguishable
/// from a healthy root with nothing to reclaim if the only signal consulted is "does this
/// path individually appear in keep". The gate must refuse to scan a root it cannot vouch for
/// at all, even though the caller explicitly names it as a `disk_scan_roots` candidate. ~keep
#[test]
fn manifest_sweep_disk_scan_skips_root_with_degenerate_manifest_baseline() {
    let dir = tempfile::tempdir().expect("tempdir");
    let package_dir = dir.path().join("packages/elixir");
    std::fs::create_dir_all(&package_dir).expect("package dir");
    git_init(&package_dir);

    let orphan = package_dir.join("dropped.ex");
    let header = crate::core::hash::header(crate::core::hash::CommentStyle::Hash);
    let hashed = crate::core::hash::inject_hash_line(&header, &"0".repeat(64));
    std::fs::write(&orphan, &hashed).expect("orphan file");
    git_add(&package_dir, &["dropped.ex"]);

    // The manifest baseline records only an unrelated Rust source path, never anything under
    // `package_dir` -- the exact signature measured for several real backends. ~keep
    let rust_source = dir.path().join("native/sample/src/lib.rs");
    let previous = vec![rust_source.clone()];
    let keep = std::collections::HashSet::from([rust_source]);

    let removed = sweep_manifest_orphans(
        &previous,
        &keep,
        std::slice::from_ref(&package_dir),
        std::slice::from_ref(&package_dir),
    )
    .expect("manifest sweep");

    assert_eq!(
        removed, 0,
        "a root with zero manifest/keep entries recorded under it must be skipped, not scanned"
    );
    assert!(orphan.exists());
}

/// A build tool can stage a copy of a real generated file at a mirrored path under the same
/// owned root (a gem packaging stage directory is the concrete case this guards against); the
/// copy inherits the marker verbatim, so content alone cannot distinguish it from the
/// original. Only the original is git-tracked -- the staged copy is disposable build output.
#[test]
fn manifest_sweep_disk_scan_preserves_untracked_marked_file_absent_from_keep() {
    let dir = tempfile::tempdir().expect("tempdir");
    let package_dir = dir.path().join("packages/ruby");
    std::fs::create_dir_all(&package_dir).expect("package dir");
    git_init(&package_dir);

    let kept = package_dir.join("client.rb");
    let header = crate::core::hash::header(crate::core::hash::CommentStyle::Hash);
    let hashed = crate::core::hash::inject_hash_line(&header, &"0".repeat(64));
    std::fs::write(&kept, &hashed).expect("kept file");
    git_add(&package_dir, &["client.rb"]);

    let staged_dir = package_dir.join("tmp/ruby/stage/lib");
    std::fs::create_dir_all(&staged_dir).expect("staged dir");
    let staged_copy = staged_dir.join("client.rb");
    std::fs::write(&staged_copy, &hashed).expect("staged copy");

    let previous = vec![kept.clone()];
    let keep = std::collections::HashSet::from([kept.clone()]);

    let removed = sweep_manifest_orphans(
        &previous,
        &keep,
        std::slice::from_ref(&package_dir),
        std::slice::from_ref(&package_dir),
    )
    .expect("manifest sweep");

    assert_eq!(
        removed, 0,
        "an untracked staged copy that merely inherits the marker must never be deleted"
    );
    assert!(staged_copy.exists());
    assert!(kept.exists());
}

/// The collection route must refuse a git-ignored staging copy, and must keep returning the
/// tracked original and an untracked-but-not-ignored file.
///
/// All three assertions are load-bearing together. Refusing the staged copy alone is
/// satisfiable by a walker that returns nothing, and the untracked case is what forces the
/// gate to be *ignored-ness* rather than tracked-ness: this set feeds
/// `finalize_hashes_sweeping`, which must still re-stamp a file `alef generate` wrote moments
/// ago and the consumer has not committed yet. ~keep
#[test]
fn collect_alef_headered_paths_refuses_git_ignored_copies_and_keeps_uncommitted_output() {
    let dir = tempfile::tempdir().expect("tempdir");
    let package_dir = dir.path().join("packages/ruby");
    std::fs::create_dir_all(&package_dir).expect("package dir");
    git_init(&package_dir);

    let header = crate::core::hash::header(crate::core::hash::CommentStyle::Hash);
    let marked = crate::core::hash::inject_hash_line(&header, &"0".repeat(64));

    write_file(&package_dir, ".gitignore", "tmp/\n");
    let tracked = write_file(&package_dir, "lib/client.rb", &marked);
    git_add(&package_dir, &[".gitignore", "lib/client.rb"]);
    let uncommitted = write_file(&package_dir, "lib/fresh.rb", &marked);
    let staged_copy = write_file(&package_dir, "tmp/ruby/stage/lib/client.rb", &marked);

    let collected = collect_alef_headered_paths(&package_dir);

    assert!(
        !collected.contains(&staged_copy),
        "a gitignored gem-staging copy carries the same marker verbatim and must not be \
         collected: {collected:?}"
    );
    assert!(
        collected.contains(&tracked),
        "the tracked original must still be collected, or this test passes by collecting \
         nothing: {collected:?}"
    );
    assert!(
        collected.contains(&uncommitted),
        "generated output the consumer has not committed yet must still be collected, so the \
         re-stamp pass can reach it: {collected:?}"
    );
}

/// alef#479: a caller that opts out of the disk-scan reclaim route for a root (passing `&[]` for
/// `disk_scan_roots` -- scaffold, README/docs, and e2e/test_apps sweeps all do, see their call
/// sites) must still learn that the root's bookkeeping is broken: this run recorded kept output
/// under the root, but the previous-run manifest recorded nothing under it at all. Before this
/// diagnostic, that condition produced no signal whatsoever for any of those callers -- only the
/// disk-scan loop's own skip check warned, and only for roots a caller opted into scanning. ~keep
#[traced_test]
#[test]
fn root_with_keep_entries_and_no_manifest_entries_warns_even_without_disk_scan() {
    let dir = tempfile::tempdir().expect("tempdir");
    let package_dir = dir.path().join("packages/java");
    std::fs::create_dir_all(&package_dir).expect("package dir");
    let kept = package_dir.join("Bridge.java");
    std::fs::write(&kept, "class Bridge {}\n").expect("kept file");

    let previous: Vec<PathBuf> = Vec::new();
    let keep = std::collections::HashSet::from([kept.clone()]);

    let removed =
        sweep_manifest_orphans(&previous, &keep, std::slice::from_ref(&package_dir), &[]).expect("manifest sweep");

    assert_eq!(
        removed, 0,
        "disk-scan reclaim is opted out of for this root, so nothing is ever removed here"
    );
    assert!(
        logs_contain("orphan-reclaim bookkeeping gap"),
        "expected a warning naming the manifest/keep mismatch for a root outside disk_scan_roots"
    );
    assert!(kept.exists());
}

/// Negative control: a root with BOTH manifest and keep entries recorded stays quiet -- proves
/// the warning fires on the manifest/keep mismatch, not merely on a root passing through
/// `sweep_manifest_orphans` at all. ~keep
#[traced_test]
#[test]
fn root_with_both_manifest_and_keep_entries_stays_quiet() {
    let dir = tempfile::tempdir().expect("tempdir");
    let package_dir = dir.path().join("packages/java");
    std::fs::create_dir_all(&package_dir).expect("package dir");
    let kept = package_dir.join("Bridge.java");
    std::fs::write(&kept, "class Bridge {}\n").expect("kept file");

    let previous = vec![kept.clone()];
    let keep = std::collections::HashSet::from([kept.clone()]);

    let removed =
        sweep_manifest_orphans(&previous, &keep, std::slice::from_ref(&package_dir), &[]).expect("manifest sweep");

    assert_eq!(removed, 0);
    assert!(
        !logs_contain("orphan-reclaim bookkeeping gap"),
        "a root with both manifest and keep entries recorded must not warn"
    );
    assert!(kept.exists());
}