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
26 changes: 24 additions & 2 deletions Main.lean
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,14 @@
line end. `path join` with no elements, or only empty ones, prints an
empty line. Wrong arguments exit with 2.

The Lean runtime decodes each argument as UTF-8 before `main` sees
it, and replaces ill-formed octets with U+FFFD. So `main` first reads
the raw arguments from /proc/self/cmdline, and refuses with exit 2 if
any of them is not UTF-8: Go would keep those octets, and the
replaced string would give an answer Go does not. Such a path can be
sent to `path serve` as hex. Where /proc is absent, the check is
skipped.

path serve

answers requests on standard input, one per line, for the
Expand All @@ -24,8 +32,9 @@
lower case, or octets that are not UTF-8. A request line may end in
LF or CR LF.

Every answer comes from the proved functions in `Path/`. The hex
coding and the request handling here are covered by the tests, not by
Every answer comes from the proved functions in `Path/`, applied to
the arguments as `main` receives them. The hex coding, the argument
check and the request handling here are covered by the tests, not by
a proof.
-/

Expand Down Expand Up @@ -96,7 +105,20 @@ def serve : IO Unit := do
def usage : String :=
"usage: path clean PATH\n path join ELEM...\n path serve"

/-- Whether every argument, as the process received it, is UTF-8.
/proc/self/cmdline holds argv[0] and then each argument, each ended
by a NUL. Without /proc, it answers `true`, as before this check. -/
def rawArgsUTF8 : IO Bool := do
try
let raw ← IO.FS.readBinFile "/proc/self/cmdline"
let parts := (raw.toList.splitOn 0).drop 1
pure (parts.all fun p => (String.fromUTF8? (ByteArray.mk p.toArray)).isSome)
catch _ => pure true

def main (args : List String) : IO UInt32 := do
unless (← rawArgsUTF8) do
IO.eprintln "path: an argument is not UTF-8; send it to `path serve` as hex"
return 2
match args with
| ["clean", p] => IO.println (Path.clean p); return 0
| "join" :: es => IO.println (Path.join es); return 0
Expand Down
9 changes: 5 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,22 +32,23 @@ The statements are in `Spec.lean`. The rules they use are in `Spec/Defs.lean`, w
|-------|---------|
| Whatever order Go's rules are applied in to the elements of a path, once none applies, the elements they leave are those of `clean p`. | `Spec.clean_rules` |
| The rules can always be applied until none applies, and they leave the elements of `clean p`. | `Spec.rules_end` |
| `clean p` names exactly one list of elements, as a path rooted exactly when `p` is; so in any order the rules end at the same elements. | `Spec.clean_names` |
| `clean p` names exactly one list of elements, as a path rooted exactly when `p` is; so, with `clean_rules`, whatever order the rules are applied in, once none applies they leave the same elements. | `Spec.clean_names` |
| The elements of `clean p` are some `..`, none if `p` is rooted, then names: no empty element and no `.`. | `Spec.clean_shape` |
| Cleaning a clean path changes nothing. | `Spec.clean_idem` |
| `join` leaves out empty elements, joins the rest with slashes and cleans them, and gives the empty string when nothing is left. | `Spec.join_eq` |
| A clean relative path with no `..`, joined to any path `b`, gives the elements of `clean b`, then its own. | `Spec.join_inside` |
| Any path cleaned as rooted, joined to a path `b` that is not empty, gives the elements of `clean b`, then elements with no `..`. | `Spec.join_root_inside` |
| Any path cleaned as rooted, joined to a path `b` that is not the empty string (`.` and `/` are covered), gives the elements of `clean b`, then elements with no `..`. | `Spec.join_root_inside` |
| Go's tests of Clean, `cleantests`: each path cleans to its result, and the result to itself. Go's tests of Join, `jointests`. | `Spec.go_clean_tests`, `Spec.go_join_tests` |

## What is not proved

- **Go's code.** The proofs are against Go's documentation, written down in `Spec/Defs.lean`. That `clean` and `join` give what go1.24.7's `path.Clean` and `path.Join` give is tested (`tests/TEST-RESULTS.md`), not proved; only Go's own test tables are proved.
- **The file system.** The rules are lexical. If `b/x` is a symbolic link, `b/x/..` on the file system need not be `b`, and a link inside a folder can point outside it.
- **Two slashes at the start.** POSIX lets a system give `//` at the start of a path a meaning of its own. Go, and this library, read it as `/`; Python keeps it. That is a choice, recorded in `SPEC.md`.
- **The empty folder.** `join ["", u]` leaves the empty element out, so `join ["", clean ("/" ++ u)]` is rooted. `join_root_inside` needs a folder that is not empty.
- **That every order of the rules ends.** Each rule drops one element or two, as `Spec.Step` shows. This is read off the definition, not a statement, since bar item 3 asks every statement to mention code under proof (`Path.clean` or `Path.join`), and a statement about the rules alone mentions neither.
- **The empty string as the folder.** `join` leaves an empty element out, so `join ["", clean ("/" ++ u)]` is `clean ("/" ++ u)` itself (`join_eq`, `clean_idem`): a path from the root that `u` chooses, such as `/etc/passwd` for `u` = `../../etc/passwd`. `join_root_inside` needs `b ≠ ""`; pass `.` for the current folder, as Go's `http.Dir` does.
- **Other path functions** of Go: `Split`, `Base`, `Dir`, `Ext`, `IsAbs` and `Match`. Windows paths are not covered.
- **Strings that are not UTF-8.** Lean strings are Unicode text, so a Go string holding other octets cannot be passed to the library. On the command line, the Lean runtime replaces each run of such octets in an argument with U+FFFD before `path clean` and `path join` see it, so for such an argument the tool prints a path Go would not. `path serve` refuses them.
- **Strings that are not UTF-8.** Lean strings are Unicode text, so a Go string holding other octets cannot be passed to the library. On the command line, `path clean` and `path join` refuse an argument that is not UTF-8 with exit 2, since the Lean runtime would otherwise replace its ill-formed octets with U+FFFD and the tool would print a path Go would not; send such a path to `path serve` as hex, which answers `error` for it. The check reads the raw arguments from /proc/self/cmdline and is skipped where /proc is absent.
- **Time and memory.** No proof bounds them. `clean` reads the path once, as Go's loop does, and removes each character it writes at most once; the tests clean paths of a million characters.
- **Reading requests and printing answers in `Main.lean`.** The differential tests cover them.

Expand Down
8 changes: 4 additions & 4 deletions SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ It adds: "The returned path ends in a slash only if it is the root `/`", and "If
- **Rule 3** drops a `..` element and the element before it, when that is a name: not empty, not `.` and not `..`. An empty element or a `.` before the `..` is dropped first, by rule 1 or 2. Go's words are "the non-`..` element that precedes it"; read literally, with an empty element or a `.` allowed there, the rules would end in more than one place. `abc/./../def` could end as `abc/def` or as `def`, and Go's own tests give `def`.
- **Rule 4** drops a `..` at the start of a rooted path.

`Spec.Steps` is the rules applied any number of times, in any order. `Spec.Normal` says that no rule applies. `Spec.render` writes elements back as a path: a slash first when it is rooted, a slash between each two elements, and `.` for no elements in a path that is not rooted. So the result ends in a slash only when it is the root `/`.
`Spec.Steps` is the rules applied any number of times, in any order. `Spec.Normal` says that no rule applies. `Spec.render` writes elements back as a path: a slash first when it is rooted, a slash between each two elements, and `.` for no elements in a path that is not rooted. So, when no element is empty, as for the elements of `clean p` (`clean_shape`), the result ends in a slash only when it is the root `/`.

**Clean** is the path `render` writes for the elements the rules leave, in whatever order they are applied (`clean_rules`), and the rules can always be applied until none applies (`rules_end`). `Spec.Names s r es` says that `s` is the path `render r` writes for `es`, that no rule applies to `es`, and that no element of `es` holds a slash; `clean p` names exactly one such list (`clean_names`). So every order of the rules ends at the same elements. Each rule drops one element or two, as `Spec.Step` shows, so the rules always come to an end.

Expand All @@ -40,7 +40,7 @@ The elements of `clean p` are some `..`, none if `p` is rooted, and then names (

Go's documentation: "Join joins any number of path elements into a single path, separating them with slashes. Empty elements are ignored. The result is Cleaned. However, if the argument list is empty or all its elements are empty, Join returns an empty string." `join_eq` states this.

**Joined paths stay inside.** A clean relative path `q` with no `..`, joined to any path `b`, gives the elements of `clean b` and then those of `q` (`join_inside`). Any path `u`, cleaned as a rooted path (`clean ("/" ++ u)`) and joined to a path `b` that is not empty, gives the elements of `clean b` and then elements with no `..` (`join_root_inside`). If `b` is empty, `join` leaves it out, and the result is rooted: `join ["", "/etc"]` is `/etc`.
**Joined paths stay inside.** A clean relative path `q` with no `..`, joined to any path `b`, gives the elements of `clean b` and then those of `q` (`join_inside`). Any path `u`, cleaned as a rooted path (`clean ("/" ++ u)`) and joined to a path `b` that is not the empty string (`.` and `/` are covered), gives the elements of `clean b` and then elements with no `..` (`join_root_inside`). If `b` is the empty string, `join` leaves it out, and the result is rooted: `join ["", "/etc"]` is `/etc`.

"Inside" is lexical: it says what the strings are, not where a file system resolves them. A symbolic link inside `b` can point anywhere.

Expand All @@ -57,7 +57,7 @@ Each property is a theorem in `Spec.lean`, under the name given.
| Cleaning a clean path changes nothing. | `Spec.clean_idem` |
| `join` is what Go's documentation says. | `Spec.join_eq` |
| A clean relative path with no `..`, joined to `b`, adds its elements to those of `clean b`. | `Spec.join_inside` |
| Any path cleaned as rooted, joined to a `b` that is not empty, adds elements with no `..` to those of `clean b`. | `Spec.join_root_inside` |
| Any path cleaned as rooted, joined to a `b` that is not the empty string (`.` and `/` are covered), adds elements with no `..` to those of `clean b`. | `Spec.join_root_inside` |
| Go's tests of Clean, each path and each result. | `Spec.go_clean_tests` |
| Go's tests of Join, and an empty first element joined to a rooted path. | `Spec.go_join_tests` |

Expand All @@ -73,4 +73,4 @@ The functions take and give Lean strings, which are Unicode text in UTF-8. Go's
- `path join ELEM...` prints the elements joined and cleaned, and an empty line for no elements or only empty ones.
- `path serve` answers requests from the differential tests, one per line. The header comment of `Main.lean` gives the protocol.

Wrong arguments exit with 2. Every answer comes from the functions above. The Lean runtime reads the arguments of `clean` and `join` as UTF-8 and replaces each run of octets that are not UTF-8 with U+FFFD, so for such an argument the tool prints a path Go would not; `path serve` answers `error` for them.
Wrong arguments exit with 2. Every answer comes from the functions above. An argument of `clean` or `join` that is not UTF-8 is refused with exit 2: the Lean runtime would replace its ill-formed octets with U+FFFD, and the tool would print a path Go would not. Such a path can be sent to `path serve` as hex, which answers `error` for it. The tool reads the raw arguments from /proc/self/cmdline for this check, and skips it where /proc is absent.
9 changes: 5 additions & 4 deletions Spec.lean
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,8 @@ theorem rules_end (p : String) :
sorry

/-- `clean p` names exactly one list of elements, as a path rooted when
`p` is. With `clean_rules`, every order of the rules ends at the
same elements. -/
`p` is. With `clean_rules`, whatever order the rules are applied in,
once none applies, the elements left are the same. -/
theorem clean_names (p : String) :
∃ es, Names (Path.clean p) (Rooted p.toList) es ∧
∀ es', Names (Path.clean p) (Rooted p.toList) es' → es' = es := by
Expand Down Expand Up @@ -69,8 +69,9 @@ theorem join_inside (b q : String) (eq : List Element) (hq : Names q false eq)
sorry

/-- Any path `u`, cleaned as a rooted path and joined to a path `b`
that is not empty, stays inside `b`. If `b` is empty, `join` leaves
it out, and the result is rooted (see `go_join_tests`). -/
that is not the empty string (`.` and `/` are covered), stays inside
`b`. If `b` is the empty string, `join` leaves it out, and the
result is `clean ("/" ++ u)` itself (see `go_join_tests`). -/
theorem join_root_inside (b u : String) (hb : b ≠ "") :
∃ eb ext, dotdot ∉ ext ∧ Names (Path.clean b) (Rooted b.toList) eb ∧
Names (Path.join [b, Path.clean ("/" ++ u)]) (Rooted b.toList) (eb ++ ext) := by
Expand Down
8 changes: 5 additions & 3 deletions Spec/Defs.lean
Original file line number Diff line number Diff line change
Expand Up @@ -85,9 +85,11 @@ inductive Steps (rooted : Bool) : List Element → List Element → Prop
def Normal (rooted : Bool) (es : List Element) : Prop :=
∀ es', ¬ Step rooted es es'

/-- The path with these elements: a slash first when it is rooted, and
a slash between each two elements. So it ends in a slash only when
it is the root `/`. An empty path that is not rooted is `.`. -/
/-- The path with these elements: a slash first when it is rooted, a
slash between each two elements, and `.` for no elements in a path
that is not rooted. When no element is empty or holds a slash, as
for a list that `Names` gives, it ends in a slash only when it is
the root `/`. -/
def render (rooted : Bool) (es : List Element) : List Char :=
if rooted then '/' :: List.intercalate ['/'] es
else if es = [] then dot
Expand Down
8 changes: 4 additions & 4 deletions tests/PLANTED-BUGS.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,12 @@ Written by `tests/plant_bugs.py`. Each bug is a change of one line, or of two, t
| a `..` that cannot backtrack is kept in a rooted path, not in one that is not | 6537 |
| `dotdot` does not move past a `..` that is kept | 289 |
| a kept `..` gets a slash before it even at the start | 4426 |
| a `.` at the end is kept | 10538 |
| a `.` at the end is kept | 10537 |
| a `..` at the end is dropped | 3410 |
| a `.` before a slash is copied as a name | 29229 |
| in a rooted path, the first name gets a slash after the root | 32251 |
| a name runs on past the slash after it | 68611 |
| the length is not counted while a name is copied | 3348 |
| a name runs on past the slash after it | 68609 |
| the length is not counted while a name is copied | 3347 |
| the root's `dotdot` is 0, so a `..` can remove the root | 1653 |
| the root alone is not rooted | 15 |
| an empty result is the empty string, not `.` | 2320 |
Expand All @@ -25,7 +25,7 @@ Written by `tests/plant_bugs.py`. Each bug is a change of one line, or of two, t
| Main.lean: `-` is read as the path `-` | 357 |
| Main.lean: `clean` takes more than one field | 2 |
| Main.lean: a CR before the LF is kept | 15536 |
| Main.lean: `path clean` prints the path as given | 6 |
| Main.lean: `path clean` prints the path as given | 4 |
| Main.lean: wrong arguments exit with 0 | 6 |

Bugs caught: 22 of 22
4 changes: 2 additions & 2 deletions tests/TEST-RESULTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,13 @@ Written by `tests/run_tests.py`. Rerun it to check these numbers.
- The model on Go's `cleantests` and `jointests`: 47 of 47
- The model's two parts, the rules applied in a random order and the stack, agree on 147239 of 147239 paths
- Answers that differ from the model: 0
- Long inputs: 12, 12296441 characters in all, answered in 2.8 s by one `path serve`
- Long inputs: 12, 12296441 characters in all, answered in 5.6 s by one `path serve`
- Agreement with each oracle over the requests it answers: Go 167263 of 167263, Python 138020 of 147250, Node 117446 of 167263
- Requests each oracle answers, by operation: Go: clean 147250, join 20013; Python: clean 147250; Node: clean 147250, join 20013
- Malformed requests answered `error`: 31 of 31
- Requests ending in CR LF: every seventh, 23893
- Last lines sent alone, with no LF, with CR LF, or with a lone CR, answered right: 4 of 4
- Command-line modes (`clean`, `join`, and wrong arguments), printing and exiting as the model says: 21 of 21
- Command-line modes (`clean`, `join`, and wrong arguments), printing and exiting as the model says: 25 of 25
- Failures: 0

## Where the oracles differ
Expand Down
21 changes: 13 additions & 8 deletions tests/run_tests.py
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,8 @@
src/path/path_test.go). Every answer of the tool must equal the
model's.

2. Against three oracles, on every request each can answer:
2. Against three oracles. Each oracle must answer every request, except
that Python is not asked `join`; any other `n/a` is a failure:

- Go: `path.Clean` and `path.Join` of the Go standard library, the
installed toolchain, through tests/oracles/go/main.go;
Expand Down Expand Up @@ -76,7 +77,7 @@
- malformed requests, which the tool must answer with `error`, among
them hex that is not UTF-8;
- the command-line modes `clean` and `join`, among them arguments that
are not UTF-8, which the Lean runtime replaces with U+FFFD, and wrong
are not UTF-8, which the tool must refuse with exit 2, and wrong
arguments: what each run prints on standard output and its exit
status.

Expand Down Expand Up @@ -497,12 +498,13 @@ def cli_cases():
cases.append((["clean", p], model_clean(p), 0))
for es in [[], [""], ["a", "b"], ["", "/etc"], ["/", "..", "x/"], ["a", "", "", "b"]]:
cases.append((["join"] + es, model_join(es), 0))
# Arguments that are not UTF-8: the Lean runtime replaces each run of
# such octets with U+FFFD before `main` sees them, as Python's
# "replace" does for these.
for raw in [b"\xc3/x/.", b"a\xff/../b\xff"]:
cases.append((["clean", raw], model_clean(raw.decode("utf-8", "replace")), 0))
cases.append((["join", b"\xff", "b"], model_join(["\ufffd", "b"]), 0))
# Arguments that are not UTF-8 are refused with exit 2: Go would
# keep the octets, and the Lean runtime would have replaced them with
# U+FFFD. A real U+FFFD is UTF-8, and is cleaned as any character is.
for raw in [b"\xc3/x/.", b"a\xff/../b\xff", b"a/\xff", b"\xff", b"\xc3"]:
cases.append((["clean", raw], "", 2))
cases.append((["join", b"\xff", "b"], "", 2))
cases.append((["clean", "a/\ufffd"], model_clean("a/\ufffd"), 0))
for args in [[], ["bogus"], ["clean"], ["clean", "a", "b"], ["serve", "x"], ["Clean", "a"]]:
cases.append((args, "", 2))
return cases
Expand Down Expand Up @@ -709,6 +711,9 @@ def ask(o):
for o in names:
theirs = oracle_out[o][i]
if theirs == "n/a":
# Only Python may refuse, and only `join` (see above).
if not (o == "Python" and op == "join"):
failures.append((f"{o}: {short(request(op, a))}", short(want, 160), "n/a"))
continue
asked[o] += 1
by_op[o][op] = by_op[o].get(op, 0) + 1
Expand Down