xingbiao 0.9.0

星表 (Xingbiao) — Tianheng's shared declared-workspace-data substrate: reads `cargo metadata --no-deps` and looks up packages and their crate-root source files, the tabulated catalog every observation dimension references before it observes. serde_json-only, below all dimensions like 璇璣 — a single source of truth so the static and semantic dimensions read the workspace through one reader instead of two drifting twins.
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
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
//! 星表 (xīngbiǎo) — the single reader of truth for **what the workspace tree IS**.
//!
//! Reads `cargo metadata --no-deps` and looks up packages and their crate-root source files:
//! the tabulated catalog every observation dimension references before it observes. Spawns
//! `cargo` and parses its JSON (`serde_json` + std only, no `syn`).
//!
//! **The criterion, because this charter widens, and an enumeration of what it holds goes
//! stale.** A fact belongs here when every dimension must agree on it *before* observing, and it is a
//! fact about the tree rather than a reading of what the tree contains. Which packages exist and where
//! their roots are; whether two paths are one file; whether a path is there at all, and whether being
//! unable to tell is the same answer as its absence. Each of those is asked by 圭表, 渾儀 and 漏刻
//! alike, and a dimension answering it privately is how three readers came to disagree about one tree.
//!
//! **What the criterion refuses** is as load-bearing as what it admits: an interpretation of source is a
//! dimension's own observation, not a fact about the tree. `cargo metadata` says which file is a crate
//! root; what the tokens in that file mean is 圭表's or 渾儀's answer and belongs to whichever is
//! asking. The line is between *what is there* and *what it says*.
//!
//! The widenings are named rather than left to be inferred: the path-identity primitives
//! ([`canonicalize_or_fail`], [`try_visit`]) arrived for a module-graph cycle guard, and the
//! filesystem-answer policy ([`is_regular_file`], [`is_directory`] and the crate-private criterion behind
//! them) arrived after all three dimensions were measured collapsing *absent* into *unreadable* — each is
//! one notch finer than the last, on the same
//! question of what the tree holds.
//!
//! **Fixture infrastructure.** This widening is test-only: the hidden scratch-root helpers ([`claim_scratch`], [`scratch_base`], [`scratch_root`]) and `Unreadable`.
//! All of these are `#[doc(hidden)]` items that exist because integration and unit test trees across member
//! crates cannot share a `cfg(test)` helper, yet must enforce identical policies (atomic temporary
//! root reservation without adopting pre-existing symlinks, and permission-removal verification that
//! restores on drop and asserts under `TIANHENG_WORKSPACE_TESTS`). They ship hidden in the published
//! crate so all test suites agree on fixture safety and refusal semantics without hand-rolled copies.
//!
//! Sits beneath all three observation dimensions — static (圭表), semantic (渾儀) and runtime (漏刻,
//! through its CI-only `audit` face) — preventing twin-drift in what they take the tree to be.
#![forbid(unsafe_code)]
#![deny(missing_docs)]

use std::path::{Path, PathBuf};
use std::process::Command;

use serde_json::Value;

mod path_identity;

#[cfg(test)]
mod tests;

pub use path_identity::{canonicalize_or_fail, try_visit};

/// Target `kind` strings that denote a library crate root (library types + `proc-macro`).
const LIBRARY_KINDS: [&str; 6] = ["lib", "rlib", "dylib", "cdylib", "staticlib", "proc-macro"];

/// Run `cargo metadata --no-deps --format-version 1` for the workspace at `manifest_path`.
pub fn cargo_metadata(manifest_path: &Path) -> Result<Value, String> {
    let output = Command::new("cargo")
        .args([
            "metadata",
            "--no-deps",
            "--format-version",
            "1",
            "--manifest-path",
        ])
        .arg(manifest_path)
        .output()
        .map_err(|err| err.to_string())?;
    if !output.status.success() {
        let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
        return Err(if stderr.is_empty() {
            format!("cargo metadata failed: {}", output.status)
        } else {
            stderr
        });
    }
    serde_json::from_slice(&output.stdout).map_err(|err| err.to_string())
}

/// Find a workspace member package by name in parsed metadata.
pub fn find_package<'a>(metadata: &'a Value, package: &str) -> Option<&'a Value> {
    metadata["packages"]
        .as_array()?
        .iter()
        .find(|candidate| candidate["name"].as_str() == Some(package))
}

/// Whether a `cargo metadata` target's `kind` array contains `wanted` — the one-target shape
/// check shared by [`crate_root_file`] (picking one library/bin target) and [`crate_roots`]
/// (every library/bin target of one package), through which [`member_root_files`] reaches it for the
/// whole workspace.
fn target_has_kind(target: &Value, wanted: &str) -> bool {
    target["kind"]
        .as_array()
        .is_some_and(|kinds| kinds.iter().any(|k| k.as_str() == Some(wanted)))
}

/// Which of a package's crate roots are compiled, told apart from the two ways there can be none.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CrateRoots {
    /// The metadata reports no target — the shape synthetic metadata in a caller's own tests carries, for which a
    /// caller reads the conventional source directory.
    Unreported,
    /// It reports targets, none a library kind or a binary — an example, a test, a bench or a build script alone —
    /// so no compiled root reads the package's `src/`, and reading it would judge a directory nothing builds.
    NoneCompiled,
    /// At least one library-kind or binary root.
    Compiled(CompiledRoots),
}

/// A package's library-kind and binary roots, in Cargo's reported order, each once, and at least one — by
/// construction, since only [`crate_roots`] builds one, so an empty list cannot stand for either state that has
/// none.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CompiledRoots(Vec<PathBuf>);

impl CompiledRoots {
    /// The roots, in Cargo's reported order.
    pub fn as_slice(&self) -> &[PathBuf] {
        &self.0
    }
}

impl CrateRoots {
    /// The compiled roots, and none for either state that has none.
    pub fn compiled(&self) -> &[PathBuf] {
        match self {
            Self::Compiled(roots) => roots.as_slice(),
            Self::Unreported | Self::NoneCompiled => &[],
        }
    }
}

/// What ONE package's metadata says about its compiled crate roots: **every** one — each library-kind target
/// and each `bin` target, in Cargo's reported order, deduplicated.
///
/// The per-package counterpart of [`member_root_files`] (which spans the workspace) and the plural of
/// [`crate_root_file`] (which picks one). A package's roots are separate compilation units: they each
/// denote the module path `crate` and neither's declarations belong in the other's module graph, so a
/// dimension that governs a package governs each root as its own corpus. Returning them all is what lets
/// a violation written in a `bin` beside a library be observed at all.
///
/// The uniqueness is **total**, not adjacency-dependent, and that distinction is load-bearing here in a
/// way it is not in [`member_root_files`] (which sorts first, so `Vec::dedup` is total for it by
/// construction). Two targets may name the same `path` — Cargo accepts it and builds both — and Cargo
/// reports targets sorted by NAME, so the two reports are adjacent only if no third target's name sorts
/// between them. `Vec::dedup` alone therefore left `[x, y, x]` intact, and the root was scanned once per
/// report. Order is Cargo's own and is preserved, because a caller's sibling-root exclusion reads this
/// slice positionally against the root it is currently walking.
///
/// A target Cargo reports always carries its `src_path`, so a library or binary target without one is metadata
/// no Cargo wrote; it contributes no root, and where no other target does either the package reads as
/// [`CrateRoots::NoneCompiled`] — no root path was resolved, whatever the kinds claimed.
pub fn crate_roots(package: &Value) -> CrateRoots {
    let targets = match package["targets"].as_array() {
        Some(targets) if !targets.is_empty() => targets,
        _ => return CrateRoots::Unreported,
    };
    let mut seen = std::collections::HashSet::new();
    let roots: Vec<PathBuf> = targets
        .iter()
        .filter(|t| {
            LIBRARY_KINDS.iter().any(|k| target_has_kind(t, k)) || target_has_kind(t, "bin")
        })
        .filter_map(|t| t["src_path"].as_str().map(PathBuf::from))
        .filter(|root| seen.insert(root.clone()))
        .collect();
    if roots.is_empty() {
        CrateRoots::NoneCompiled
    } else {
        CrateRoots::Compiled(CompiledRoots(roots))
    }
}

/// A path as a **canonical identity label**: `/` as its only component separator, and every byte the
/// path carried preserved.
///
/// The one answer to "what is the label for an observed path", shared by every dimension that records
/// one — 圭表/渾儀's compilation unit ([`compilation_unit_label`]) and 漏刻's observed file. Written once
/// here because two sites answering separately is how they came to disagree.
///
/// **Separator.** Built on [`Path::components`], joined with `/`, and that is the whole reason it is
/// correct rather than an implementation detail: separator semantics are delegated to `std::path`
/// instead of re-implemented. Substituting characters would be wrong in both directions — on unix `\`
/// is a legal byte *within* a name, so replacing it would map the single file `a\b` and the file `b`
/// inside directory `a` onto one label, destroying the injectivity this exists for; on Windows both
/// `\` and `/` separate, so replacing one is incomplete. `components()` is the only thing that knows
/// which is which per platform. A component cannot contain `/` anywhere, so `/` in a label
/// unambiguously means a component boundary.
///
/// Canonical path separators ensure cross-platform baseline stability: without this, paths would
/// produce `src/lib.rs` on Linux and `src\lib.rs` on Windows, causing a baseline recorded on one
/// platform to match nothing on the other.
///
/// **Bytes.** Every byte that is not part of a valid UTF-8 sequence is percent-escaped, and a literal
/// `%` becomes `%25` so no escaped label can be spelled by an unescaped one. `Path::display()` is
/// **lossy** — it replaces each undecodable byte with U+FFFD — so two paths differing only in such
/// bytes would produce one label, one identity, and a baseline accepting the first would silently
/// suppress the second's never-accepted violation. This half is load-bearing for 漏刻, whose labels come
/// from filesystem walks where such a name is reachable; for 圭表/渾儀 it cannot trigger, since their
/// paths are built from `cargo metadata`'s JSON strings and Cargo refuses to operate under a non-UTF-8
/// path at all (`error: path contains invalid UTF-8 characters`). Holding one rule for both is what
/// keeps the dimension where it cannot trigger from drifting away from the one where it can.
///
/// `as_encoded_bytes`'s encoding is unspecified but self-consistent within a platform, which is all this
/// needs: a label is never decoded back, only compared with another label produced the same way. On
/// Windows that encoding is WTF-8, so an unpaired surrogate's bytes escape exactly as an invalid unix
/// byte does.
///
/// **Stated normalizations.** `Component::CurDir` contributes nothing and repeated separators collapse,
/// so `./a` and `a//b` label as `a` and `a/b`. Both name the same file, and neither form is reachable
/// from the inputs these labels are built from — a `cargo metadata` `src_path` or a walked path, both
/// already canonical — but the normalization is stated rather than left implicit. `Component::ParentDir`
/// is preserved as `..`, being unresolvable without touching the filesystem. A root-only path labels
/// as `/`: the separator is written before the NEXT component, and a lone `RootDir` has none.
pub fn path_label(path: &Path) -> String {
    fn push_escaped(out: &mut String, name: &std::ffi::OsStr) {
        fn push_text(out: &mut String, text: &str) {
            for ch in text.chars() {
                if ch == '%' {
                    out.push_str("%25");
                } else {
                    out.push(ch);
                }
            }
        }

        let mut rest = name.as_encoded_bytes();
        loop {
            match std::str::from_utf8(rest) {
                Ok(text) => {
                    push_text(out, text);
                    return;
                }
                Err(err) => {
                    let (valid, invalid) = rest.split_at(err.valid_up_to());
                    push_text(
                        out,
                        std::str::from_utf8(valid)
                            .expect("`valid_up_to()` bounds a checked-valid prefix"),
                    );
                    let skip = err.error_len().unwrap_or(invalid.len()).max(1);
                    for byte in &invalid[..skip.min(invalid.len())] {
                        out.push_str(&format!("%{byte:02X}"));
                    }
                    rest = &invalid[skip.min(invalid.len())..];
                }
            }
        }
    }

    let mut label = String::new();
    let mut first = true;
    for component in path.components() {
        match component {
            std::path::Component::RootDir => {
                label.push('/');
                first = true;
                continue;
            }
            std::path::Component::CurDir => continue,
            _ => {}
        }
        if !first {
            label.push('/');
        }
        first = false;
        match component {
            std::path::Component::Prefix(prefix) => push_escaped(&mut label, prefix.as_os_str()),
            std::path::Component::ParentDir => label.push_str(".."),
            std::path::Component::Normal(name) => push_escaped(&mut label, name),
            std::path::Component::RootDir | std::path::Component::CurDir => unreachable!(),
        }
    }
    label
}

/// A compilation unit's stable identity label: its root source path **relative to the package's own
/// manifest directory** (`src/lib.rs`, `src/main.rs`, `tools/x.rs`).
///
/// `None` when the root does not lie under that directory. A caller SHALL treat that as **cannot
/// judge** (a constitution error), not as a reason to fall back to the path as given: that path is the
/// clone's own location, so keeping it would make the identity checkout-dependent — the same commit in
/// two clones yielding two identities, and a baseline recorded in one matching nothing in the other.
///
/// This is deliberately NOT the rule 漏刻 applies to a file reached through an absolute `#[path]`
/// literal, and the difference is the whole reason this returns `None` rather than the raw path: that
/// literal is **committed text**, identical in every checkout, so keeping it verbatim is exactly what
/// makes it stable. A root path outside the manifest directory is the checkout's own location, so
/// keeping it verbatim is what makes it unstable. Same shape, opposite consequence.
///
/// When the metadata carries no `manifest_path` — the shape synthetic metadata in a caller's own tests
/// has; real `cargo metadata` always carries it — the root's file name is used, which is stable and
/// sufficient because such metadata declares a single root.
///
/// The relative path is rendered by [`path_label`], so the label is the platform-independent one: a
/// Windows checkout labels `src\lib.rs` as `src/lib.rs`, matching what Linux CI recorded, instead of
/// re-firing every baseline entry as new. Because that rendering is total, `None` has exactly **one**
/// possible cause — `strip_prefix` failing — so the `out_of_package_root_error` a caller raises from it
/// is true whenever it fires, by construction rather than by wording.
pub fn compilation_unit_label(package: &Value, root_file: &Path) -> Option<String> {
    match package["manifest_path"]
        .as_str()
        .map(Path::new)
        .and_then(Path::parent)
    {
        Some(dir) => root_file.strip_prefix(dir).ok().map(path_label),
        None => root_file
            .file_name()
            .map(|name| path_label(Path::new(name))),
    }
}

/// Resolve a crate's root source file from `cargo metadata` (library target else `bin` target).
pub fn crate_root_file(package: &Value) -> Option<PathBuf> {
    let targets = package["targets"].as_array()?;
    let pick = targets
        .iter()
        .find(|t| LIBRARY_KINDS.iter().any(|k| target_has_kind(t, k)))
        .or_else(|| targets.iter().find(|t| target_has_kind(t, "bin")))?;
    pick["src_path"].as_str().map(PathBuf::from)
}

/// The workspace root directory Cargo resolved for this metadata read — the directory holding the
/// workspace manifest, whichever member manifest `--manifest-path` happened to name (Cargo resolves
/// upward to the same root either way).
///
/// Read for its **stability**, not for locating anything: it is the one directory that does not move
/// when a workspace gains, loses, or relocates a member, which is what makes it the right thing to
/// label an observed file *relative to* when that label is baseline identity (see 漏刻's
/// `audit_probe_coverage` anchor). A path derived from the observed member set instead — their
/// longest common prefix, say — is checkout-independent yet shifts the moment the set does, silently
/// restating every recorded label.
///
/// `None` when the field is absent, which real `cargo metadata` output always carries; a caller
/// holding synthetic metadata is expected to supply its own anchor rather than receive a guess.
pub fn workspace_root(metadata: &Value) -> Option<PathBuf> {
    metadata["workspace_root"].as_str().map(PathBuf::from)
}

/// Workspace member source-root directories (deduplicated and sorted).
pub fn member_src_dirs(metadata: &Value) -> Vec<PathBuf> {
    let mut dirs: Vec<PathBuf> = metadata["packages"]
        .as_array()
        .map(|packages| {
            packages
                .iter()
                .filter_map(crate_root_file)
                .filter_map(|root| root.parent().map(Path::to_path_buf))
                .collect()
        })
        .unwrap_or_default();
    dirs.sort();
    dirs.dedup();
    dirs
}

/// Every workspace member library, proc-macro, and binary crate-root source file reported by Cargo.
///
/// Which target kinds have a governable crate root is [`crate_roots`]'s filter; what is this
/// function's own is the scope — every package rather than one — and the ordering: it sorts and
/// dedups across packages, so the corpus is deterministic whatever order Cargo lists members in.
pub fn member_root_files(metadata: &Value) -> Vec<PathBuf> {
    let mut roots: Vec<PathBuf> = metadata["packages"]
        .as_array()
        .map(|packages| {
            packages
                .iter()
                .flat_map(|package| crate_roots(package).compiled().to_vec())
                .collect()
        })
        .unwrap_or_default();
    roots.sort();
    roots.dedup();
    roots
}

/// The runtime audit's corpus and label anchor for the workspace at `manifest_path`, in one read.
///
/// The corpus is every member's crate-root file; the anchor is Cargo's own resolved `workspace_root`, made
/// absolute. The anchor matters more than it looks: the audit labels every observed file relative to it and that
/// label is **baseline identity**, so it must be the one directory that moves neither with the checkout location
/// nor with the workspace's member set. It is the same directory whichever member manifest `--manifest-path`
/// named.
///
/// The fallback to the given manifest's own directory exists for metadata carrying no `workspace_root` field — a
/// synthetic value in a unit test; a real `cargo metadata` read always carries it. `absolute` is used rather than
/// canonicalization so the cargo-reported root is never rewritten, and it refuses only an empty path, hence the
/// working-directory last resort for a bare `Cargo.toml` whose parent is empty.
///
/// This lives here, in the single reader of truth, because two dimensions derived it separately once: the shell
/// computed it for the runtime audit while a runtime observer would have had to compute it again, and a
/// twin derivation of a baseline-identity anchor is the drift this crate exists to prevent.
pub fn audit_corpus_and_anchor(manifest_path: &Path) -> Result<(Vec<PathBuf>, PathBuf), String> {
    let metadata = cargo_metadata(manifest_path)?;
    let roots = member_root_files(&metadata);
    let anchor = match workspace_root(&metadata) {
        Some(root) => root,
        None => {
            let manifest_dir = manifest_path.parent().unwrap_or(Path::new(""));
            std::path::absolute(manifest_dir).or_else(|_| std::env::current_dir()).map_err(|err| {
                format!(
                    "no anchor: {manifest_path:?} names no absolute directory and the working directory \
                     cannot be read ({err}). Every observed file is labelled relative to the anchor, so \
                     inventing one would mislabel a whole baseline rather than fail"
                )
            })?
        }
    };
    Ok((roots, anchor))
}

/// Whether a `metadata` failure means the target IS NOT THERE, as against this reader not finding out.
///
/// **`Path::is_file` answers `false` for both, and the three dimensions each collapsed them.** A
/// `#[cfg]`-gated or `cfg_attr`-remapped declaration is allowed to have an absent target — that is the
/// tolerance a cfg-blind walker owes a conditional module — so a target this reader merely could not stat
/// was swallowed by that tolerance, with whatever the subtree holds going unobserved. That is the false
/// negative the Core Contract forbids, and it stood in 圭表, 渾儀 and 漏刻 alike.
///
/// **The criterion, so a later error kind is placed rather than guessed.** An error saying *this path
/// cannot name anything* is an absence; one saying *this reader could not find out* is not. Measured as
/// uid 1000: a directory at mode `000` holding `mod.rs` gives `is_file` false with kind `PermissionDenied`
/// — this reader could not find out. With a plain file where a module directory would be, the kind is
/// `NotADirectory` — a component that is not a directory cannot have children, so the target cannot exist.
///
/// `FilesystemLoop` is deliberately NOT an absence: a cycle is a thing this reader could not resolve, and
/// a walker that tolerates it silently would drop whatever the cycle hides. Kinds beyond the two measured
/// are left on the loud side rather than sorted on a guess.
///
/// It lives here because all three dimensions ask it and none may ask another: the substrate is where a
/// question they share is answered once, the way `canonicalize_or_fail` already is. They ask it **through**
/// [`is_regular_file`] and [`is_directory`], which are its only callers, so the criterion itself is
/// crate-private — a published name is a promise this crate would have to keep, and nothing outside asks
/// for it. A dimension that later needs to place a new error kind changes the criterion here, which is the
/// point of it living here at all.
pub(crate) fn is_absence(kind: std::io::ErrorKind) -> bool {
    matches!(
        kind,
        std::io::ErrorKind::NotFound | std::io::ErrorKind::NotADirectory
    )
}

/// Whether `path` is a regular file, or why this reader could not tell — the criterion is
/// `is_absence`, crate-private beside these two, which are its only callers.
pub fn is_regular_file(path: &Path) -> Result<bool, String> {
    match std::fs::metadata(path) {
        Ok(found) => Ok(found.is_file()),
        Err(err) if is_absence(err.kind()) => Ok(false),
        Err(err) => Err(format!(
            "cannot read '{}' to decide whether it backs a module — {err}; an unreadable target is not \
             an absent one, and tolerating it would leave whatever it holds unobserved",
            path.display()
        )),
    }
}

/// Whether `path` is a directory, or why this reader could not tell — [`is_regular_file`]'s sibling.
pub fn is_directory(path: &Path) -> Result<bool, String> {
    match std::fs::metadata(path) {
        Ok(found) => Ok(found.is_dir()),
        Err(err) if is_absence(err.kind()) => Ok(false),
        Err(err) => Err(format!(
            "cannot read '{}' to decide whether it holds a module's children — {err}; an unreadable \
             directory is not an absent one",
            path.display()
        )),
    }
}

/// Claim `path` as a directory this process created, refusing to adopt one that already exists.
///
/// **Fixture infrastructure, deliberately withheld from the API contract.** It is `pub` because test targets
/// in other crates need it across crate boundaries, and `#[doc(hidden)]` because 星表's domain is
/// declared workspace data — a scratch-directory claim is not in it. It lives here for a dependency-graph
/// reason (the lightest crate already reachable from every dimension), and a dependency-graph reason is not
/// a domain fit.
///
/// The distinction is not cosmetic at `0.5.0`, which is the release that first publishes it: a documented
/// item is a promise an adopter may build on and this family cannot then withdraw, while a hidden one keeps
/// every present caller compiling and commits to nothing. Zero call sites outside a test target or a
/// `#[cfg(test)]` module were measured before hiding it.
///
/// **`create_dir_all` accepts a pre-existing symlink to a directory.** Measured: `create_dir_all` on such a
/// link returns `Ok(())` and every subsequent write lands in the link's *target*, while `create_dir` cannot
/// follow a symlink and returns `AlreadyExists` — the narrow call is what makes the refusal possible at all.
///
/// A fixture scratch root has a predictable name (a process id, a counter), so it is guessable by anyone who
/// can write the directory it sits in. [`scratch_root`] places it where only the user can, and the ordinary
/// `remove_dir_all` then `create_dir_all` idiom would still leave a window between the two calls in which a
/// planted symlink is silently adopted, with everything the fixture writes afterward landing wherever that link
/// points. `create_dir` closes the window rather than narrowing it: the root is claimed only if this call is
/// the one that created it, and `remove_dir_all` itself removes a symlink at the path rather than following
/// it, so an attacker must win a race rather than leave something lying around in advance.
///
/// **This is about the root only.** Every directory beneath a root this call already claimed is safe to build
/// with the ordinary `create_dir_all`, because nothing outside the fixture's own control could have planted
/// anything there first.
#[doc(hidden)]
pub fn claim_scratch(path: &Path) -> std::io::Result<()> {
    std::fs::create_dir(path)
}

/// The directory every fixture root lives under: `tmp/` beside the profile directory of the running test
/// binary, created if absent.
///
/// **Fixture infrastructure, withheld from the API contract** for the reason [`claim_scratch`] gives, and for a
/// second one: the layout it reads is cargo's test layout, which this family has no business promising.
///
/// A test binary sits at `<target>/[<triple>/]<profile>/deps/<bin>`; the base is the `tmp` directory next to
/// that profile directory. It is found at **run time** from [`std::env::current_exe`] and never from a
/// compile-time path, which a worktree sharing one target directory would bake in. It does not read `TMPDIR`:
/// a root under a target directory the user owns is not claimable by anyone else, survives a system temporary
/// directory that is unwritable, and is removed by `cargo clean`.
///
/// The path is canonical, because a consumer comparing it with a working directory's real path (git's ceiling
/// directories do) would otherwise miss when the target directory is reached through a symlink.
///
/// **A layout it cannot recognise panics, naming the executable's path.** It never falls back to the system
/// temporary directory, because a fallback is a second behaviour that depends on the environment.
///
/// **Fixture code takes a root from [`scratch_root`] and does not name a path under this.** A name composed
/// from a label alone is unique only while no two callers choose one label; [`scratch_root`] appends a
/// per-process counter. A repository check holds every file outside this crate to that, apart from a declared
/// set that says why.
#[doc(hidden)]
pub fn scratch_base() -> PathBuf {
    let exe = std::env::current_exe().unwrap_or_else(|err| {
        panic!("scratch_base: cannot read the running executable's path: {err}")
    });
    let base = scratch_base_for(&exe).unwrap_or_else(|why| panic!("{why}"));
    std::fs::create_dir_all(&base)
        .unwrap_or_else(|err| panic!("scratch_base: cannot create '{}': {err}", base.display()));
    base.canonicalize()
        .unwrap_or_else(|err| panic!("scratch_base: cannot resolve '{}': {err}", base.display()))
}

/// The base for the executable at `exe`, or why its path is not a cargo test layout.
fn scratch_base_for(exe: &Path) -> Result<PathBuf, String> {
    let deps = exe
        .parent()
        .filter(|dir| dir.file_name().is_some_and(|name| name == "deps"));
    deps.and_then(Path::parent)
        .and_then(Path::parent)
        .map(|above_profile| above_profile.join("tmp"))
        .ok_or_else(|| {
            format!(
                "scratch_base: '{}' is not at <target>/[<triple>/]<profile>/deps/<bin>, so there is no build \
                 directory to place a fixture root in",
                exe.display()
            )
        })
}

/// A fixture root under [`scratch_base`], removed on drop.
///
/// **Fixture infrastructure, withheld from the API contract** for the reason [`scratch_base`] gives. The root is
/// `<label>-<pid>-<counter>`, unique per call within a process, claimed with [`claim_scratch`] so this call is
/// the one that created it. A root a previous process left behind under a recycled process id is removed first,
/// and the removal is of the path itself rather than anything a symlink there points at.
#[doc(hidden)]
#[derive(Debug)]
pub struct ScratchRoot {
    path: PathBuf,
}

/// A fixture root named for `label`, empty and owned by the caller until the returned guard drops.
///
/// **A label that does not leave the name it is built into one ordinary path component is a refusal naming the
/// label, never a root outside the base.** The question is asked of the name, which is what [`Path::join`]
/// reads: a label carrying a separator, a leading `..` or a root leaves a name for a directory the base does
/// not contain — and that directory is removed, recursively, before the root is claimed and again when the
/// guard drops. A bare `.` or `..` leaves one ordinary component, the process id and counter standing after it,
/// and is contained. Asking it of the name is what makes the containment this function's own rather than every
/// caller's.
#[doc(hidden)]
pub fn scratch_root(label: &str) -> ScratchRoot {
    static NEXT: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);
    let base = scratch_base();
    let name = format!(
        "{label}-{}-{}",
        std::process::id(),
        NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed)
    );
    if !is_one_component(&name) {
        panic!(
            "scratch_root: '{name}', built from label '{label}', is not one ordinary path component, so it \
             does not name a directory under '{}'",
            base.display()
        );
    }
    let path = base.join(name);
    settle_cleanup(
        "scratch_root: removing the root a previous process left at",
        &path,
        remove_if_present(&path),
    );
    claim_scratch(&path)
        .unwrap_or_else(|err| panic!("scratch_root: cannot claim '{}': {err}", path.display()));
    ScratchRoot { path }
}

/// Whether `name` is one ordinary path component, which is what makes [`Path::join`] append it rather than
/// name anything above the directory joined to.
///
/// **Read through [`std::path::Components`], not by searching for separators**: which bytes separate is the
/// platform's answer, and a `.`, a `..` and a root are component kinds rather than characters. The equality is
/// what makes it total — a name yielding one `Normal` that spells less than the whole of it carried something
/// `join` would read.
fn is_one_component(name: &str) -> bool {
    let mut components = Path::new(name).components();
    matches!(
        (components.next(), components.next()),
        (Some(std::path::Component::Normal(only)), None) if only == std::ffi::OsStr::new(name)
    )
}

/// Remove `path` and everything under it, taking an already-absent `path` as removed.
///
/// **One answer for both removals a fixture root makes** — the one before it is claimed, which clears what a
/// previous process left under a recycled process id, and the one in `Drop`. Every error but absence names a
/// directory still standing where the caller is about to claim one, which is the thing it has to hear.
fn remove_if_present(path: &Path) -> std::io::Result<()> {
    match std::fs::remove_dir_all(path) {
        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(()),
        other => other,
    }
}

impl ScratchRoot {
    /// The root's path.
    pub fn path(&self) -> &Path {
        &self.path
    }
}

impl std::ops::Deref for ScratchRoot {
    type Target = Path;
    fn deref(&self) -> &Path {
        &self.path
    }
}

impl AsRef<Path> for ScratchRoot {
    fn as_ref(&self) -> &Path {
        &self.path
    }
}

impl Drop for ScratchRoot {
    fn drop(&mut self) {
        settle_cleanup(
            "ScratchRoot: removing",
            &self.path,
            remove_if_present(&self.path),
        );
    }
}

/// A fixture's cleanup, settled inside a `Drop`: said on stderr while a failure is already unwinding, so the first
/// failure stays the one reported, and a failure of its own otherwise, so a run that passed does not leave its
/// fixture behind in silence.
///
/// **Fixture infrastructure, withheld from the API contract** for the reason [`claim_scratch`] gives: the guards
/// that call it restore or remove something on drop and settle the result one way, and they live in test targets
/// across crates.
#[doc(hidden)]
pub fn settle_cleanup(what: &str, path: &Path, result: std::io::Result<()>) {
    if let Err(err) = result {
        if std::thread::panicking() {
            eprintln!("{what} '{}' failed during unwind: {err}", path.display());
        } else {
            panic!("{what} '{}' failed: {err}", path.display());
        }
    }
}

/// An RAII guard that restricts a file or directory to mode 000 during test execution
/// and restores its original permissions on drop.
///
/// **Fixture infrastructure, deliberately withheld from the API contract.**
/// Like [`claim_scratch`], it is `pub` because test targets across crates need it across crate
/// boundaries, and `#[doc(hidden)]` because 星表's domain is declared workspace data.
///
/// Under a privileged user (such as root in a container), mode 000 does not restrict access.
/// Outside `TIANHENG_WORKSPACE_TESTS`, it restores permissions and returns `None` so the calling
/// test can skip gracefully. Inside `TIANHENG_WORKSPACE_TESTS`, a silent skip is forbidden and
/// asserts.
#[cfg(unix)]
#[doc(hidden)]
pub struct Unreadable<'a> {
    path: &'a Path,
    original: std::fs::Permissions,
}

#[cfg(unix)]
impl<'a> Unreadable<'a> {
    /// Restrict `path` to mode 000, returning `None` if mode 000 does not bite (e.g. running as root).
    ///
    /// Outside `TIANHENG_WORKSPACE_TESTS` that skip is allowed and said on stderr, so a run that did not judge an
    /// unreadable input does not read as one that did.
    pub fn try_new(path: &'a Path) -> Option<Self> {
        use std::os::unix::fs::PermissionsExt;
        let original = std::fs::metadata(path)
            .unwrap_or_else(|err| {
                panic!(
                    "Unreadable: cannot read the permissions of '{}': {err}",
                    path.display()
                )
            })
            .permissions();
        std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o000)).unwrap_or_else(
            |err| {
                panic!(
                    "Unreadable: cannot restrict '{}' to mode 000: {err}",
                    path.display()
                )
            },
        );
        let accessible = if path.is_dir() {
            std::fs::read_dir(path).is_ok()
        } else {
            std::fs::read(path).is_ok()
        };
        if accessible {
            std::fs::set_permissions(path, original)
                .expect("restore permissions when mode 000 did not bite");
            assert!(
                std::env::var_os("TIANHENG_WORKSPACE_TESTS").is_none(),
                "mode 000 did not restrict the path — running as root would make this direction vacuous"
            );
            eprintln!(
                "Unreadable: mode 000 does not restrict '{}' for this process, so the direction using it is \
                 skipped",
                path.display()
            );
            return None;
        }
        Some(Self { path, original })
    }
}

#[cfg(unix)]
impl Drop for Unreadable<'_> {
    fn drop(&mut self) {
        settle_cleanup(
            "Unreadable: restoring the permissions of",
            self.path,
            std::fs::set_permissions(self.path, self.original.clone()),
        );
    }
}