Use \/\-prefixed shorthand for out-of-dvc-dir deps (vs \../../\ chains)

When a .dvc file's dep lives outside the .dvc file's directory, write
it as \`/repo-root-relative\` instead of \`../../../foo/bar\`. Reads
already accept both forms (since the relative-paths spec landed), so
this is purely a write-path change.

Benefits:
- Easier to scan deeply-nested .dvc files
- /-prefixed paths are stable: moving a .dvc file doesn't break them
- Visually distinct from same-dir deps (foo/bar vs /foo/bar)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ryan-williams

specs/done/dep-path-shorthand.md

@@ -0,0 +1,107 @@
+# Repo-root-absolute dep path shorthand on write
+
+## Problem
+
+When a `.dvc` file depends on artifacts outside its own directory, DVX writes
+the dep path via `os.path.relpath()`, producing `../`-laden strings:
+
+```yaml
+# www/public/njsp/csvs.dvc
+deps:
+  ../../../njsp/data/crashes.parquet: e9799868d9114846a7052100454cde51
+```
+
+These `../../../` prefixes are hard to scan at a glance, change meaning based
+on which `.dvc` file they live in, and get noisier the deeper the `.dvc` file
+is nested.
+
+A shorter form is already supported on **read** (`src/dvx/run/dvc_files.py`
+lines 108-126): a leading `/` in a dep path is treated as repo-root-absolute,
+so the above is equivalent to:
+
+```yaml
+deps:
+  /njsp/data/crashes.parquet: e9799868d9114846a7052100454cde51
+```
+
+But `_relativize_dep_paths` (same file, L129-153) is purely `os.path.relpath`
+based, so DVX writes back the `../` form and hand-edited `/`-shorthand paths
+revert on the next `dvx run` that rewrites the file.
+
+## Proposal
+
+In `_relativize_dep_paths`, prefer the repo-root-absolute shorthand for any
+dep whose relpath from `dvc_dir` would contain `..`.
+
+### Write rule
+
+For each `(dep_path, hash)`:
+
+- If `dep_path` is inside `dvc_dir` (i.e. `relpath(dep_path, dvc_dir)` has no
+  `..`): write as-is relative (current behavior).
+  - e.g. `njsp/data/refresh.dvc` with dep `njsp/data/FAUQStats2024.xml`
+    → writes as `FAUQStats2024.xml` (dvc-dir-relative, no `/` prefix).
+- If `dep_path` is outside `dvc_dir` (relpath would start with `../`): write
+  as `/<dep_path>` (repo-root-absolute).
+  - e.g. `www/public/njsp/csvs.dvc` with dep `njsp/data/crashes.parquet`
+    → writes as `/njsp/data/crashes.parquet` (not `../../../njsp/data/...`).
+
+### Rationale
+
+- Humans scanning `.dvc` files in deeply-nested directories don't have to
+  count `../` segments to locate the dep.
+- Moving a `.dvc` file doesn't invalidate dep paths that point outside its
+  directory — `/path` is stable, `../../path` is not.
+- No migration needed for older files: reads continue to accept both forms.
+- The `/` prefix is visually distinct from the bare `foo/bar` form used for
+  same-directory deps, making it easy to tell at a glance whether a dep
+  lives inside or outside the stage's own dir.
+
+### Edge cases
+
+- `dvc_dir == "."` (stage file is at repo root): paths are already
+  repo-root-relative; don't add `/` prefix. Leave as-is.
+- `dvc_dir` absolute (unusual; current code preserves this): don't modify.
+- Windows: `os.path.relpath` may raise `ValueError` across drives; current
+  code preserves the raw path in that case. The new rule doesn't apply
+  there (no meaningful "repo root").
+
+## Opt-out
+
+Add a `run.path_style` config key in `.dvx/config.yml` (or `dvx.yml`):
+
+```yaml
+run:
+  path_style: repo_root  # default: prefer / shorthand for out-of-dir deps
+  # path_style: relative   # old behavior: always os.path.relpath
+```
+
+Only needed if there's demand for the old behavior (e.g. to minimize diff
+churn on initial rollout). Probably unnecessary.
+
+## Migration
+
+No forced migration. Over time, as DVX rewrites each `.dvc` file in a given
+repo, deps get normalized to the new shorthand. Downstream projects that
+prefer an immediate bulk conversion can do it with a short script (find
+every `.dvc` file, re-resolve each dep to repo-root-relative via the existing
+`_resolve_dep_paths`, then write back via the new `_relativize_dep_paths`).
+
+## Test plan
+
+- New `test_dvc_files` cases covering:
+  - Dep inside `dvc_dir`: writes dvc-dir-relative (no leading `/`).
+  - Dep outside `dvc_dir`: writes `/repo-root-relative`.
+  - `dvc_dir == "."`: writes repo-root-relative (no leading `/`).
+  - Roundtrip: resolve(relativize(deps)) == resolve(original_deps) for any
+    supported write form.
+- Existing tests in `tests/test_run_dvc_files.py` for the read path should
+  keep passing unchanged.
+
+## Out of scope
+
+- Changing the resolve (read) path. The leading-`/` form is already accepted
+  and that doesn't need to change.
+- Converting `outs` paths — those live within `dvc_dir` by convention.
+- Source project: `hccs/crashes` will adopt this shorthand via its own spec
+  (see `specs/dvx-dep-path-shorthand.md` there) once the DVX change lands.

src/dvx/run/dvc_files.py

@@ -127,10 +127,15 @@ def _resolve_dep_paths(deps: dict[str, str], dvc_dir: Path) -> dict[str, str]:
 
 
 def _relativize_dep_paths(deps: dict[str, str], dvc_dir: Path) -> dict[str, str]:
-    """Convert repo-root-relative dep paths to .dvc-dir-relative.
+    """Convert repo-root-relative dep paths to .dvc-file-relative form.
 
-    Inverse of ``_resolve_dep_paths``. If dvc_dir is "." (repo root),
-    paths are returned unchanged.
+    Two output forms:
+    - Deps inside ``dvc_dir``: written .dvc-dir-relative (no leading ``/``).
+    - Deps outside ``dvc_dir``: written ``/repo-root-relative`` shorthand,
+      which avoids ``../../../`` clutter for deeply-nested .dvc files.
+
+    Inverse of ``_resolve_dep_paths`` (which accepts both forms).
+    Returns paths unchanged if dvc_dir is "." or absolute.
     """
     dvc_dir_str = str(dvc_dir)
     # Only relativize if dvc_dir is a relative subdirectory (not "." or absolute)
@@ -143,13 +148,9 @@ def _relativize_dep_paths(deps: dict[str, str], dvc_dir: Path) -> dict[str, str]
             # Strip dvc_dir prefix to make relative
             result[dep_path[len(dvc_dir_str) + 1:]] = dep_hash
         else:
-            # Outside dvc_dir — use os.path.relpath
-            try:
-                rel = os.path.relpath(dep_path, dvc_dir_str)
-                result[rel] = dep_hash
-            except ValueError:
-                # Different drives on Windows, keep absolute
-                result[dep_path] = dep_hash
+            # Outside dvc_dir — use /-prefixed repo-root-absolute shorthand
+            # instead of ../../../ chains
+            result["/" + dep_path] = dep_hash
     return result
 
 

tests/test_run_dvc_files.py

@@ -1065,18 +1065,38 @@ def test_resolve_dep_paths_repo_root():
 
 
 def test_relativize_dep_paths():
-    """Repo-root-relative paths are converted to .dvc-dir-relative."""
+    """Deps inside dvc_dir → relative; outside → /-prefixed shorthand."""
     from dvx.run.dvc_files import _relativize_dep_paths
 
     deps = {"njsp/data/crashes.parquet": "abc123", "www/index.html": "def456"}
     rel = _relativize_dep_paths(deps, Path("njsp/data"))
 
     assert rel == {
         "crashes.parquet": "abc123",
-        "../../www/index.html": "def456",
+        "/www/index.html": "def456",
     }
 
 
+def test_relativize_dep_paths_repo_root():
+    """When dvc_dir is '.', paths are unchanged (no /-prefix added)."""
+    from dvx.run.dvc_files import _relativize_dep_paths
+
+    deps = {"data.txt": "abc", "subdir/file.txt": "def"}
+    rel = _relativize_dep_paths(deps, Path("."))
+    assert rel == deps
+
+
+def test_relativize_dep_paths_deeply_nested():
+    """Deep .dvc files use /-prefix instead of long ../../../ chains."""
+    from dvx.run.dvc_files import _relativize_dep_paths
+
+    deps = {"njsp/data/crashes.parquet": "abc"}
+    rel = _relativize_dep_paths(deps, Path("www/public/njsp"))
+
+    # Should be /-prefixed, not ../../../njsp/data/crashes.parquet
+    assert rel == {"/njsp/data/crashes.parquet": "abc"}
+
+
 def test_relative_paths_roundtrip():
     """Write then read with subdirectory .dvc preserves dep paths."""
     from dvx.run.dvc_files import _relativize_dep_paths, _resolve_dep_paths