Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 101 additions & 0 deletions crates/pons-cli/tests/contracts.rs
Original file line number Diff line number Diff line change
Expand Up @@ -378,3 +378,104 @@ fn ambiguous_legacy_paths_require_one_consistent_record_and_fingerprint() {
);
}
}

/// The writer keys a file by component (`Path::strip_prefix`), so a `.` next to
/// the scan root never reaches a key; the reader has to derive the same one.
/// The report here is this build's own output, not a hand-made document.
#[test]
fn a_component_equivalent_file_spelling_validates_with_the_writer_key() {
use pons_core::{
corroborate::fingerprint_of, engine::Engine, finding::EvidenceClass, lang::Lang,
source::DiscoveredFile,
};
fn rebase(value: &mut Value, root: &str, separator: &str) {
match value {
Value::String(text) => {
if let Some(suffix) = text.strip_prefix(root) {
*text = format!("repo{}", suffix.replace(['/', '\\'], separator));
}
}
Value::Array(values) => values
.iter_mut()
.for_each(|value| rebase(value, root, separator)),
Value::Object(values) => values
.values_mut()
.for_each(|value| rebase(value, root, separator)),
_ => (),
}
}
fn accepted(fixture: &Fixture, report: &Value, what: &str) {
for (version, document) in [("0.5.0", report.clone()), ("0.4.0", as_0_4_0(report))] {
let result = fixture.validate(&document);
assert!(
result.status.success(),
"{what} as {version}: {}",
String::from_utf8_lossy(&result.stderr)
);
}
}
let fixture = Fixture::new();
// The CLI makes its root absolute and walks it, so it never names a file
// through a `.` component. The public `scan_files` API can.
let spelled = fixture.src.join(".").join("sample.php");
let scanned = Engine::new(pons_rules::registry::RuleRegistry::all()).scan_files(
&fixture.src,
&[DiscoveredFile {
path: spelled.clone(),
lang: Lang::Php,
}],
);
let native: Value =
serde_json::from_str(&pons_core::report::json::render(&scanned).unwrap()).unwrap();
assert_eq!(
native["findings"][0]["location"]["file"],
json!(spelled.display().to_string()),
"the report must carry the spelling under test"
);
assert_eq!(
native["evidence_contract"]["records"][0]["path"],
"sample.php"
);
accepted(&fixture, &native, "the native report");

// The same report under a relative root label, in each separator style.
// No writer emits the lexical `./sample.php`: it is refused as a record
// path, as a fingerprint input, as both together, and in a frozen report.
let root = native["scanned"]["root"].as_str().unwrap().to_owned();
let lexical = "./sample.php";
for (separator, file) in [("/", "repo/./sample.php"), ("\\", r"repo\.\sample.php")] {
let mut relative = native.clone();
rebase(&mut relative, &root, separator);
assert_eq!(relative["scanned"]["root"], "repo");
assert_eq!(relative["findings"][0]["location"]["file"], file);
accepted(&fixture, &relative, file);

let evidence: EvidenceClass =
serde_json::from_value(relative["findings"][0]["evidence"].clone()).unwrap();
let line = relative["findings"][0]["location"]["line_start"]
.as_u64()
.unwrap() as usize;
for (record, fingerprint) in [(true, false), (false, true), (true, true)] {
let mut forged = relative.clone();
if record {
forged["evidence_contract"]["records"][0]["path"] = json!(lexical);
}
if fingerprint {
forged["findings"][0]["semantic_fingerprint"] =
json!(fingerprint_of(lexical, line, evidence));
}
assert_eq!(
fixture.validate(&forged).status.code(),
Some(2),
"{file}: lexical key accepted (record {record}, fingerprint {fingerprint})"
);
}
let mut frozen = as_0_4_0(&relative);
frozen["evidence_contract"]["records"][0]["path"] = json!(lexical);
assert_eq!(
fixture.validate(&frozen).status.code(),
Some(2),
"{file}: lexical key accepted in a frozen report"
);
}
}
195 changes: 177 additions & 18 deletions crates/pons-core/src/evidence.rs
Original file line number Diff line number Diff line change
Expand Up @@ -23,28 +23,53 @@ pub(crate) fn relative_path(file: &str, root: &str) -> String {
.replace('\\', "/")
}

/// The components `std::path` compares, each with its offset in `text`: the
/// root, then every name. Empty components are dropped, and so is every `.`
/// except a leading one; `..` is kept. Only the Windows reading tells a `//`
/// root from `/`. Drive and verbatim prefixes are ordinary names here, as
/// they were under the literal rule this replaces.
fn components(text: &str, windows: bool) -> Vec<(&str, usize)> {
let body = text.trim_start_matches('/');
let lead = text.len() - body.len();
let mut parts = Vec::new();
if lead > 0 {
parts.push((&text[..lead.min(1 + usize::from(windows))], 0));
}
let mut start = lead;
for name in body.split('/') {
if !name.is_empty() && (name != "." || start == 0) {
parts.push((name, start));
}
start += name.len() + 1;
}
parts
}

// One reading of `relative_path`: the same component comparison, and the same
// remainder, without `std::path` and therefore without the reader's host.
fn path_for_style(file: &str, root: &str, windows: bool) -> (String, bool) {
let file = if windows {
file.replace('\\', "/")
} else {
file.into()
};
let root = if windows {
root.replace('\\', "/")
let (file, root) = if windows {
(file.replace('\\', "/"), root.replace('\\', "/"))
} else {
root.into()
(file.to_owned(), root.to_owned())
};
let base = if file == root {
root.rsplit_once('/').map_or("", |(parent, _)| parent)
} else {
root.trim_end_matches('/')
};
let prefix = format!("{base}/");
let relative = if base.is_empty() && !file.starts_with('/') {
Some(file.as_str())
} else {
file.strip_prefix(&prefix)
let parts = components(&file, windows);
let base = components(&root, windows);
let same = |a: &[(&str, usize)], b: &[(&str, usize)]| {
a.iter().map(|part| part.0).eq(b.iter().map(|part| part.0))
};
// A file that is the root itself is keyed below the root's parent. A bare
// root has no parent.
let has_parent = base.last().is_some_and(|last| !last.0.starts_with('/'));
let depth = base.len() - usize::from(has_parent && same(&parts, &base));
let relative = (parts.len() >= depth && same(&parts[..depth], &base[..depth])).then(|| {
match (parts.get(depth), parts.last()) {
// As `Components::as_path`: from the next component to the end of
// the last one, spelled as the producer spelled it.
(Some(first), Some(last)) => &file[first.1..last.1 + last.0.len()],
_ => "",
}
});
(
relative.unwrap_or(&file).replace('\\', "/"),
relative.is_some(),
Expand Down Expand Up @@ -119,6 +144,140 @@ mod portable_paths {
.any(|(path, _)| path == expected));
}
}
// The writer strips by component (`Path::strip_prefix`), so `.` and
// repeated separators next to the root never reach a key. Each row gives
// the exact POSIX and Windows readings; the native writer is compared with
// the reading of the host that runs the test.
#[test]
fn component_equivalent_spellings_have_the_writer_key() {
let inside = |key: &str| (key.to_string(), true);
let outside = |key: &str| (key.to_string(), false);
for (file, root, posix, windows) in [
("repo/./a.php", "repo", inside("a.php"), inside("a.php")),
(
"repo/./sub/a.php",
"repo",
inside("sub/a.php"),
inside("sub/a.php"),
),
("repo//a.php", "repo", inside("a.php"), inside("a.php")),
("repo/a.php/.", "repo", inside("a.php"), inside("a.php")),
("repo/a.php", "repo/.", inside("a.php"), inside("a.php")),
("repo/a.php", "repo//", inside("a.php"), inside("a.php")),
// The same file named twice: the key is its name below the parent.
(
"repo/./a.php",
"repo/a.php",
inside("a.php"),
inside("a.php"),
),
("./a.php", ".", inside("a.php"), inside("a.php")),
(
"/tmp/repo/./a.php",
"/tmp/repo",
inside("a.php"),
inside("a.php"),
),
// Only the components next to the root are dropped. The remainder
// keeps its spelling, `..` is never resolved, and a leading `.` is
// a component of its own.
(
"repo/sub/./a.php",
"repo",
inside("sub/./a.php"),
inside("sub/./a.php"),
),
(
"repo/../repo/a.php",
"repo",
inside("../repo/a.php"),
inside("../repo/a.php"),
),
(
"./repo/a.php",
"repo",
outside("./repo/a.php"),
outside("./repo/a.php"),
),
// A backslash separates components only in the Windows reading.
(
r"repo\.\a.php",
"repo",
outside("repo/./a.php"),
inside("a.php"),
),
(
r"repo\.\sub\a.php",
r"repo\",
outside("repo/./sub/a.php"),
inside("sub/a.php"),
),
] {
let native = if cfg!(windows) { &windows } else { &posix };
assert_eq!(
super::relative_path(file, root),
native.0,
"writer: {file} in {root}"
);
let mut expected = vec![posix.clone()];
// An absolute POSIX root has one reading.
if windows != posix && !root.starts_with('/') {
expected.push(windows);
}
assert_eq!(
path_candidates(file, root),
expected,
"reader: {file} in {root}"
);
}
assert_eq!(
path_candidates(r"C:\repo\.\a.php", r"C:\repo"),
vec![inside("a.php")]
);
assert_eq!(
path_candidates(r"//server/share\.\a.php", "//server/share")[1],
inside("a.php")
);
}
// Every short path over a name, `.` and the host's separators: the reading
// for this host is the native writer, string for string. Windows prefixes
// need `:` or two leading separators; the reader does not model them, so
// they are not generated.
#[test]
fn the_host_reading_is_the_native_writer_on_every_short_path() {
let alphabet: &[char] = if cfg!(windows) {
&['a', '.', '/', '\\']
} else {
&['a', '.', '/']
};
let mut paths = vec![String::new()];
let mut from = 0;
for _ in 0..6 {
let until = paths.len();
for index in from..until {
for letter in alphabet {
paths.push(format!("{}{letter}", paths[index]));
}
}
from = until;
}
let prefixed = |path: &str| {
cfg!(windows) && path.len() > 1 && path[..2].chars().all(|c| matches!(c, '/' | '\\'))
};
paths.retain(|path| !prefixed(path));
let mut compared = 0usize;
for file in &paths {
for root in paths.iter().filter(|root| root.len() < 5) {
assert_eq!(
super::path_for_style(file, root, cfg!(windows)).0,
super::relative_path(file, root),
"{file:?} in {root:?}"
);
compared += 1;
}
}
assert!(compared > 100_000, "the comparison was vacuous: {compared}");
}
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
Expand Down
65 changes: 65 additions & 0 deletions docs/echo-362-verification.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -111,3 +111,68 @@ This establishes internal consistency, not a unique historical filesystem
identity. Tests cover both 0.4.0 and 0.5.0 legacy forms and reject mixed
interpretations; the Windows workspace suite passed 261 test executions,
with all-target Clippy and the eight CLI contract tests passing.

== Component-equivalent paths: 10 November 2026

The review of #73 left one finding open. The writer and the reader disagreed
on a file named through a component that `std::path` drops. For root `repo`
and file `repo/./a.php`, the writer (`Path::strip_prefix`) keys `a.php`. The
reader removed the literal prefix `repo/` and derived `./a.php`.

Reproduced at `612145d805c6ec519d60fc65e406e9c091462848` on x86_64 Linux with
rustc 1.97.1 (`8bab26f4f`), the `rust-toolchain.toml` pin:

* `Engine::scan_files` wrote record path `sample.php` for the file
`<root>/./sample.php`. `pons validate-report` rejected that report with
`semantic fingerprint mismatch` as 0.5.0, and with `record/finding mismatch`
as its frozen 0.4.0 projection.
* The same disagreement occurred for `repo/./sub/a.php`, `repo//a.php`,
`repo/a.php/.`, the root spelling `repo/.`, the absolute form
`/tmp/repo/./a.php`, and one file named twice (file `repo/./a.php`, root
`repo/a.php`).
* Not affected: the root spelling `repo//`, `./a.php` below `.`, and spelling
after the first kept component (`repo/sub/./a.php` is `sub/./a.php` on both
sides).
* The Windows spelling `repo\.\a.php` does not reproduce on a POSIX writer,
which keeps the string as one name. The reader's Windows reading had the
defect (`./a.php`). A Windows writer was not run locally.

The reader now derives each reading with the writer's rule. It compares
components (the root, then every name; empty components and every `.` except
a leading one are dropped; `..` is kept) and returns the producer's spelling
from the next component to the end of the last one. The writer, the
fingerprint, the validator rule that requires one reading, and both schemas
are unchanged, so current and frozen keys are unchanged. The lexical
`./a.php` is not an additional candidate.

Controls added:

* `component_equivalent_spellings_have_the_writer_key` gives the exact POSIX
and Windows reading for each case above. It compares the native writer with
the reading of the host that runs it.
* `the_host_reading_is_the_native_writer_on_every_short_path` compares the
native writer with the host reading for every path of up to six characters
over a name, `.` and the host separators, against every root of up to four:
132,253 pairs on Linux. Windows paths that need a prefix are not generated.
* `a_component_equivalent_file_spelling_validates_with_the_writer_key` drives
this build's own `scan_files` report through `pons validate-report`, as
0.5.0 and as 0.4.0, with its absolute root and with the relative label
`repo` in both separator styles. It rejects `./sample.php` as a record path,
as a fingerprint input, as both together, and in a frozen report.

Local results on the fix: `cargo fmt --check` and all-target Clippy with
warnings denied passed. `cargo test --workspace --no-fail-fast` as root gave
266 passed and 3 failed. The three are the POSIX permission fixtures, which
refuse to run as root; they fail identically at `612145d` (263 passed, 3
failed). The `pons-core` unit binary run as uid 1000 passed 146 of 146.
`tests/e2e.sh` on the release build gave 46 passed, 0 failed, 0 skipped, and
`tests/doc_drift.sh` passed. Three deliberate reader mutations (keep interior
`.`, drop the parent rule, keep trailing components) each failed both new
unit tests; the mutations are not committed.

Limits. Drive, UNC and verbatim prefixes remain ordinary names in the reader,
as at `612145d`: a drive-letter case difference, a bare `C:` root and `.`
below a `\\?\` root are not modelled, and nothing here tests them. No Windows
host ran these tests locally; the hosted Linux and Windows checks belong to
the pull request. Creusot with Pearlite contracts and Verus remain `OPEN`, not
run. The tests, including the exhaustive comparison, are tests and not proofs.
Loading