Skip to content
Open
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
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
### Fixed

- **`eval check` and `repo run` refuse a `--cache-root` or a `--cache NAME=PATH` that is not a usable directory with exit 2 naming the flag and the path** — a regular file, a path below one, or a `--cache-root` holding a regular file named after a cache used to end in `✗ [Errno 17] File exists` or in `✗ [Errno 20] Not a directory`, and exit 1 after the image build; the paths are now checked before the export and the build. An existing read-only directory still passes.
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
### Fixed

- **`repo` commands refuse a `$DOKIMI_REPO_CACHE` that is not a usable directory with exit 2 and a message naming the variable and the path** — with no `--cache-dir`, a variable naming a regular file (or a path below one) used to end in `✗ [Errno 17] File exists` and exit 1 at the clone; it is now checked before any clone, as `--cache-dir` is. A `--cache-dir` that is given wins, and the variable is not looked at then. A bad variable next to a local-directory source is refused too, where it used to be ignored.
2 changes: 1 addition & 1 deletion dokimi/docs/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -265,7 +265,7 @@ failed check.

A command that validates its input and then runs exits 2 for the first and 1
for the second. Not every command follows this yet: `repo run` and
`eval check` exit 2 for a source that does not parse, a pinned local path inside a repository or a `--cache-dir` that is not a usable directory,
`eval check` exit 2 for a source that does not parse, a pinned local path inside a repository, a `--cache-dir` (or `$DOKIMI_REPO_CACHE`) that is not a usable directory or a `--cache-root` or `--cache NAME=PATH` that is not one,
but still exit 1 for other input refusals (a missing or malformed manifest, a bad arm; the `✗` lines;
a `--manifest` path that leaves the source tree as typed is exit 2, pinned or not, as a source refusal; a link in the tree that leads out of it is exit 1), and
`tools preference` exits 1 when every call failed and 3 when `--max-cost-usd`
Expand Down
8 changes: 5 additions & 3 deletions dokimi/docs/repo-evaluation-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -701,7 +701,7 @@ apart, neither failed nor missing. If the probe itself fails, a task with
cells is left unrun; a cell that already has a `result.json` keeps it.

Both commands exit 2, before any build, on a source that does not parse (a local path that is not a
directory, an unpinned remote), on a pinned local path inside a repository that is not its root and on a `--cache-dir` that is not a usable directory; a
directory, an unpinned remote), on a pinned local path inside a repository that is not its root, on a `--cache-dir` (or, without the flag, a `$DOKIMI_REPO_CACHE`) that is not a usable directory and on a `--cache-root` or `--cache NAME=PATH` that is not one; a
source that parses but cannot be opened (clone, fetch, revision) exits 1 with a `✗` line. A manifest that
is missing or malformed exits 1 too; a `--manifest` path that leaves the source tree is refused as a
source and exits 2, for an unpinned local directory and for a pinned source (`<repo>@<sha>`) alike; a link in the tree that leads out of it, the default
Expand Down Expand Up @@ -2268,8 +2268,10 @@ the `dokimi:typecheck` grader above.
eval tree to `<out>/_eval/content`, and build the image from the eval tree
without its tasks directory (tag `dokimi/<id>:<sha>`) unless
`--image` names one. Cache directories default to
`~/.cache/dokimi/caches/<id>/<name>`; `--cache NAME=PATH` points one
elsewhere. `{source_dir}` is the source's own git directory, or
`~/.cache/dokimi/caches/<id>/<name>`; `--cache-root` moves them all and
`--cache NAME=PATH` points one elsewhere. A `--cache-root` or `--cache NAME=PATH` that is a regular file or
below one, or a `--cache-root` that holds a regular file named after a cache, is refused before the image
build with exit 2, naming the flag and the path. `{source_dir}` is the source's own git directory, or
`--source-dir`.

Cloning and fetching a remote source (`url@rev`, in every `repo` command) is
Expand Down
16 changes: 9 additions & 7 deletions dokimi/dokimi/commands/cache_dir.py
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Copyright (C) 2026 Intel Corporation
# SPDX-License-Identifier: Apache-2.0

"""The up-front check of a ``--cache-dir`` value, shared by the novelty and repo commands (#701, #765)."""
"""The up-front check of a cache path from a flag or variable, shared by the novelty and repo commands (#701, #765, #826)."""

from __future__ import annotations

Expand All @@ -10,15 +10,17 @@

RETENTION_USE = "the retention verdicts can be stored in"
CLONE_USE = "the repository clones can be cached in"
CACHE_USE = "the build caches can be kept in"


def usable_cache_dir(raw: str | None, use: str = RETENTION_USE) -> Path | None:
"""``--cache-dir`` as a path a cache can store into, or ``None`` when unset.
def usable_cache_dir(raw: str | None, use: str = RETENTION_USE, *, label: str = "--cache-dir") -> Path | None:
"""``raw`` (the value of ``--cache-dir`` or another setting) as a path a cache can store into, or ``None`` when unset.

A directory that does not exist yet is fine (created on the first store) when an existing,
writable directory is above it; one that exists must be a readable directory, writable or
not (a fully cached run replays from it). Anything else raises ``InputError`` before a paid
call or a clone (#701, #765). ``use`` closes the message: "pass a directory <use>".
call or a clone (#701, #765). ``use`` closes the message: "pass a directory <use>"; ``label`` names the
setting at its start (``--cache-dir`` unless the caller says otherwise: #826).
"""
from dokimi.utils import InputError

Expand All @@ -32,14 +34,14 @@ def usable_cache_dir(raw: str | None, use: str = RETENTION_USE) -> Path | None:
is_dir = probe.is_dir()
except OSError as exc:
# An ancestor without search permission: exists()/is_dir() raise PermissionError (Python < 3.14).
raise InputError(f"--cache-dir {path}: cannot inspect {probe} ({exc.strerror or type(exc).__name__}); "
raise InputError(f"{label} {path}: cannot inspect {probe} ({exc.strerror or type(exc).__name__}); "
f"pass a directory {use}") from exc
if not is_dir:
where = "is not a directory" if probe == path else f"has {probe} above it, which is not a directory"
raise InputError(f"--cache-dir {path} {where}; pass a directory {use}")
raise InputError(f"{label} {path} {where}; pass a directory {use}")
# An existing directory only has to be readable: a fully cached run replays from a read-only
# directory and writes nothing. A missing one is created on the first store, so it needs to be writable.
needed, word = (os.R_OK | os.X_OK, "readable") if probe == path else (os.W_OK | os.X_OK, "writable")
if not os.access(probe, needed):
raise InputError(f"--cache-dir {path}: {probe} is not {word}; pass a directory {use}")
raise InputError(f"{label} {path}: {probe} is not {word}; pass a directory {use}")
return path
9 changes: 7 additions & 2 deletions dokimi/dokimi/commands/repo.py
Original file line number Diff line number Diff line change
Expand Up @@ -611,11 +611,16 @@ def _manifest_id(label: str) -> str:
def _cache_dir(args: argparse.Namespace) -> Path | None:
"""``--cache-dir`` as given, or ``None``; a value no clone can be cached in is a usage error (2) (#765).

An existing read-only directory passes on purpose: a populated one replays without writing. An empty one
is not told apart without the clone URL, so its clone fails later with exit 1.
Without the flag, a non-empty ``$DOKIMI_REPO_CACHE`` is checked and returned the same way (#827); the flag wins.
A read-only directory passes: a populated one replays without writing; an empty one fails later with exit 1.
"""
import os

from dokimi.commands.cache_dir import CLONE_USE, usable_cache_dir

env = os.environ.get("DOKIMI_REPO_CACHE")
if not args.cache_dir and env:
return usable_cache_dir(env, CLONE_USE, label="$DOKIMI_REPO_CACHE")
return usable_cache_dir(args.cache_dir, CLONE_USE)


Expand Down
26 changes: 25 additions & 1 deletion dokimi/dokimi/commands/repo_run.py
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,7 @@ def _context(args: argparse.Namespace, out: Path, source, pin: bool = False):
require_runnable(manifest)
if manifest.image is None:
raise ValueError(f"{manifest.path} declares no `image`; entry points and agents run in it")
_check_cache_paths(args, manifest) # before the export and the image build (#826)
git_dir = source_git_dir(source, tree, _cache_dir(args))
content = out / "_eval" / "content"
# a pinned batch keeps its content until the pin is checked
Expand Down Expand Up @@ -175,6 +176,25 @@ def _pair(text: str) -> tuple[str, str]:
return name, path


def _check_cache_paths(args: argparse.Namespace, manifest: RepoManifest) -> None:
"""Refuse a ``--cache-root`` or ``--cache NAME=PATH`` no cache directory can be made in (usage error, exit 2) (#826).

Checked before the image build: ``_context`` makes each cache directory after it. A ``--cache`` naming no
cache of the manifest is skipped here (``_context`` refuses it with its own message).
"""
from dokimi.commands.cache_dir import CACHE_USE, usable_cache_dir

overrides = dict(_pair(c) for c in args.cache or ())
names = [c.name for c in manifest.image.caches] if manifest.image is not None else []
if args.cache_root:
usable_cache_dir(str(Path(args.cache_root).resolve()), CACHE_USE, label="--cache-root")

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

bug · medium
Must-fix — Impact: unusable cache input can bypass the labeled usage-error handler, producing exit 1 or a traceback with exit 5 instead of exit 2. Trigger: on supported Python 3.11/3.12, create a self-referencing symlink (ln -s loop /tmp/loop) and pass --cache-root /tmp/loop or --cache build-cache=/tmp/loop; Path.resolve() raises RuntimeError. An inaccessible ancestor can also raise OSError during resolution. Evidence: all three new resolve() calls execute outside usable_cache_dir's exception handling; _errors() catches OSError as exit 1 but excludes RuntimeError, which reaches the CLI's traceback/exit-5 handler. Catch resolution failures (OSError and RuntimeError) and convert them to InputError naming the relevant flag and path, covering root, override and derived-child paths with regression tests. Workaround: supply an accessible, non-looping path. Severity justification: medium, because a concrete class of invalid user inputs violates the promised exit-code and diagnostic contract without data loss.

for name in names: # the resolved path, as `_context` makes it: `missing/..` must not hide a file
if name in overrides:
usable_cache_dir(str(Path(overrides[name]).resolve()), CACHE_USE, label=f"--cache {name}")
elif args.cache_root:
usable_cache_dir(str((Path(args.cache_root) / name).resolve()), CACHE_USE, label="--cache-root")


def _progress(line: str) -> None:
"""One progress line, flushed: under a pipe (CI) stdout is block-buffered and the per-task
lines would otherwise all appear when the command exits."""
Expand Down Expand Up @@ -212,6 +232,8 @@ def cmd_repo_tasks_check(args: argparse.Namespace) -> None:
print(f"{len(tasks)} task(s), image {ctx.image}{' (warm: with network)' if args.warm else ''}",
file=sys.stderr)
results = run_check(ctx, tasks, out / "check", warm=args.warm, jobs=args.jobs, log=_progress)
except InputError: # a ValueError: a bad cache path is a usage error (2), not a failed run (1) (#826)
raise
except _errors() as exc:
print(f"✗ {exc}", file=sys.stderr)
sys.exit(1)
Expand Down Expand Up @@ -363,6 +385,8 @@ def _run_locked(args: argparse.Namespace, arms: list[str], batch_dir: Path, lock
write_skill_pin(batch_dir, skill_pin)
summary = run_batch(ctx, tasks, arms, options, args.reps, batch_dir, jobs=args.jobs, force=args.force,
max_batch_usd=args.max_batch_usd, log=_progress)
except InputError: # see cmd_repo_tasks_check (#826)
raise
except _errors() as exc:
print(f"✗ {exc}", file=sys.stderr)
sys.exit(1)
Expand Down Expand Up @@ -486,7 +510,7 @@ def _common(p: argparse.ArgumentParser, source_help: str, cache_help: str, posit

_SOURCE_EXIT = (
"Exit 2 for a source that does not parse (a path that is not a directory, an unpinned remote), a "
"pinned local path inside a repository (give its root) or a --cache-dir that is not a usable directory; exit 1 for a source that cannot be opened "
"pinned local path inside a repository (give its root) or a --cache-dir that is not a usable directory (so is a $DOKIMI_REPO_CACHE, without the flag), or a --cache-root or --cache that is not one; exit 1 for a source that cannot be opened "
"(clone, fetch, revision) and "
)
CHECK_EXIT = _SOURCE_EXIT + "for a task that fails the check."
Expand Down
2 changes: 1 addition & 1 deletion dokimi/dokimi/commands/tasks_generate.py
Original file line number Diff line number Diff line change
Expand Up @@ -154,7 +154,7 @@ def add_parser(eval_tasks_sub, positive_int) -> None:
"threads file; --from prs writes one dokimi:hidden_tests task per merged pull request of a pull request "
"file (its description as the prompt, its test files hidden until grading, the rest of its diff as the "
"oracle). Exits 2 on a usage error, among them a malformed source, an unpinned remote, a local source "
"that is not a directory or a --cache-dir that is not a usable directory. With graph, also 2 on an index that does not read or matches no file "
"that is not a directory or a --cache-dir that is not a usable directory (so is a $DOKIMI_REPO_CACHE, without the flag). With graph, also 2 on an index that does not read or matches no file "
"of the source, and 1 when no target of the index gave a task, the tasks cannot be written or the source "
"cannot be resolved at the revision. With replay or prs, 1 when no pull request gave a task, a task cannot "
"be written, the source cannot be opened, or the threads or pull request file, the manifest or the prompt "
Expand Down
54 changes: 54 additions & 0 deletions dokimi/tests/test_cache_dir_label.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Copyright (C) 2026 Intel Corporation
# SPDX-License-Identifier: Apache-2.0

"""`usable_cache_dir` names the setting it was given in each of its messages (#826, #827)."""

from __future__ import annotations

import os

import pytest

from dokimi.commands.cache_dir import CACHE_USE, RETENTION_USE, usable_cache_dir
from dokimi.utils import InputError


def _message(raw, **kwargs) -> str:
with pytest.raises(InputError) as exc:
usable_cache_dir(raw, **kwargs)
return str(exc.value)


def test_the_default_label_is_cache_dir_in_a_file_and_a_file_above_it(tmp_path):
blocker = tmp_path / "file"
blocker.write_text("x", encoding="utf-8")
assert _message(str(blocker)) == f"--cache-dir {blocker} is not a directory; pass a directory {RETENTION_USE}"
child = blocker / "c"
assert _message(str(child)) == (f"--cache-dir {child} has {blocker} above it, which is not a directory; "
f"pass a directory {RETENTION_USE}")


@pytest.mark.skipif(os.name != "posix" or os.geteuid() == 0, reason="needs permission bits that bind the user")
def test_a_custom_label_replaces_the_flag_in_the_not_writable_message(tmp_path):
locked = tmp_path / "locked"
locked.mkdir()
locked.chmod(0o500)
try:
assert _message(str(locked / "new"), label="--cache-root", use=CACHE_USE) == (
f"--cache-root {locked / 'new'}: {locked} is not writable; pass a directory {CACHE_USE}")
finally:
locked.chmod(0o700)


def test_a_custom_label_replaces_the_flag_in_the_not_a_directory_messages(tmp_path):
blocker = tmp_path / "file"
blocker.write_text("x", encoding="utf-8")
assert _message(str(blocker), use=CACHE_USE, label="--cache build-cache") == (
f"--cache build-cache {blocker} is not a directory; pass a directory {CACHE_USE}")
assert "--cache-dir" not in _message(str(blocker / "c"), label="--cache-root")


def test_a_custom_label_does_not_change_what_passes(tmp_path):
assert usable_cache_dir(None, label="--cache-root") is None
assert usable_cache_dir("", label="--cache-root") is None
assert usable_cache_dir(str(tmp_path / "new"), label="--cache-root") == tmp_path / "new"
106 changes: 106 additions & 0 deletions dokimi/tests/test_repo_cache_env_usable.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
# Copyright (C) 2026 Intel Corporation
# SPDX-License-Identifier: Apache-2.0

"""`$DOKIMI_REPO_CACHE` is checked like `--cache-dir` before any clone (#827): a bad value exits 2 naming the variable."""

from __future__ import annotations

import argparse
import subprocess

import pytest

from dokimi import cli
from dokimi.commands.repo import _cache_dir
from tests.cli_refusal import refusal

CLOSING = "pass a directory the repository clones can be cached in"


def _argv(monkeypatch, *argv):
monkeypatch.setattr("sys.argv", ["dokimi", *argv])


def _source(tmp_path) -> str:
return f"file://{tmp_path}/nothere@HEAD"


def _commands(tmp_path):
return {
"fetch": ["repo", "fetch", _source(tmp_path)],
"scan": ["repo", "scan", _source(tmp_path)],
"reach": ["repo", "reach", _source(tmp_path), "--model", "m"],
"check": ["eval", "check", _source(tmp_path)],
}


def _file(tmp_path):
path = tmp_path / "cachefile"
path.write_text("x", encoding="utf-8")
return path


@pytest.mark.parametrize("command", ["fetch", "scan", "reach", "check"])
def test_repo_command_refuses_a_cache_variable_that_is_a_regular_file(command, tmp_path, monkeypatch, capsys):
"""#827: it was `✗ [Errno 17] File exists: '<file>'`, exit 1, with no mention of the variable."""
cache = _file(tmp_path)
monkeypatch.setenv("DOKIMI_REPO_CACHE", str(cache))
_argv(monkeypatch, *_commands(tmp_path)[command])
with refusal() as exc:
cli.main()
err = capsys.readouterr().err
assert exc.code == 2
assert f"$DOKIMI_REPO_CACHE {cache} is not a directory; {CLOSING}" in err
assert "File exists" not in err and cache.read_text(encoding="utf-8") == "x"


def test_repo_fetch_refuses_a_cache_variable_below_a_regular_file_and_makes_nothing(tmp_path, monkeypatch, capsys):
blocker = _file(tmp_path)
monkeypatch.setenv("DOKIMI_REPO_CACHE", str(blocker / "cache"))
_argv(monkeypatch, *_commands(tmp_path)["fetch"])
with refusal() as exc:
cli.main()
err = capsys.readouterr().err
assert exc.code == 2
assert f"$DOKIMI_REPO_CACHE {blocker / 'cache'} has {blocker} above it, which is not a directory; {CLOSING}" in err
assert sorted(p.name for p in tmp_path.iterdir()) == ["cachefile"]


def test_a_cache_dir_flag_wins_over_a_bad_variable(tmp_path, monkeypatch, capsys):
src = tmp_path / "src"
src.mkdir()
(src / "a.txt").write_text("a", encoding="utf-8")
git = ["git", "-C", str(src), "-c", "user.name=t", "-c", "user.email=t@example.com"]
subprocess.run([*git, "init", "-q"], check=True)
subprocess.run([*git, "add", "-A"], check=True)
subprocess.run([*git, "commit", "-qm", "init"], check=True)
sha = subprocess.run([*git, "rev-parse", "HEAD"], check=True, capture_output=True, text=True).stdout.strip()
cache = tmp_path / "cache"
cache.mkdir()
monkeypatch.setenv("DOKIMI_REPO_CACHE", str(_file(tmp_path)))
_argv(monkeypatch, "repo", "fetch", f"file://{src}@{sha}", "--cache-dir", str(cache))
cli.main()
assert capsys.readouterr().out.startswith(f"{sha}\t")
assert any(cache.iterdir()) # cloned into the flag's directory


def test_a_bad_cache_dir_flag_is_still_named_when_the_variable_is_set(tmp_path, monkeypatch, capsys):
bad = _file(tmp_path)
monkeypatch.setenv("DOKIMI_REPO_CACHE", str(tmp_path))
_argv(monkeypatch, *_commands(tmp_path)["fetch"], "--cache-dir", str(bad))
with refusal() as exc:
cli.main()
err = capsys.readouterr().err
assert exc.code == 2 and f"--cache-dir {bad} is not a directory" in err and "$DOKIMI_REPO_CACHE" not in err


def test_cache_dir_returns_a_good_variable_and_an_empty_one_counts_as_unset(tmp_path, monkeypatch):
args = argparse.Namespace(cache_dir=None)
monkeypatch.setenv("DOKIMI_REPO_CACHE", "")
assert _cache_dir(args) is None
monkeypatch.setenv("DOKIMI_REPO_CACHE", str(tmp_path))
assert _cache_dir(args) == tmp_path
assert _cache_dir(argparse.Namespace(cache_dir="")) == tmp_path
monkeypatch.setenv("DOKIMI_REPO_CACHE", str(tmp_path / "new" / "deeper"))
assert _cache_dir(args) == tmp_path / "new" / "deeper"
assert not (tmp_path / "new").exists()
Loading
Loading