throughline 4.6.2__tar.gz → 4.7.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. {throughline-4.6.2/src/throughline.egg-info → throughline-4.7.0}/PKG-INFO +3 -3
  2. {throughline-4.6.2 → throughline-4.7.0}/README.md +2 -2
  3. {throughline-4.6.2 → throughline-4.7.0}/pyproject.toml +1 -1
  4. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/cli.py +81 -1
  5. throughline-4.7.0/src/throughline/discovery.py +145 -0
  6. throughline-4.7.0/src/throughline/migrate_beneath.py +96 -0
  7. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/parser.py +8 -0
  8. {throughline-4.6.2 → throughline-4.7.0/src/throughline.egg-info}/PKG-INFO +3 -3
  9. {throughline-4.6.2 → throughline-4.7.0}/src/throughline.egg-info/SOURCES.txt +3 -0
  10. throughline-4.7.0/tests/test_migrate_beneath.py +208 -0
  11. {throughline-4.6.2 → throughline-4.7.0}/LICENSE +0 -0
  12. {throughline-4.6.2 → throughline-4.7.0}/NOTICE +0 -0
  13. {throughline-4.6.2 → throughline-4.7.0}/setup.cfg +0 -0
  14. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/__init__.py +0 -0
  15. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/apply.py +0 -0
  16. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/brief.py +0 -0
  17. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/collision.py +0 -0
  18. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/composition.py +0 -0
  19. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/declared.py +0 -0
  20. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/diagrams.py +0 -0
  21. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/dump.py +0 -0
  22. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/filters.py +0 -0
  23. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/fingerprint.py +0 -0
  24. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/graph.py +0 -0
  25. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/grounding.py +0 -0
  26. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/identity.py +0 -0
  27. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/inherit.py +0 -0
  28. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/inject.py +0 -0
  29. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/items.py +0 -0
  30. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/links.py +0 -0
  31. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/model.py +0 -0
  32. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/ratification.py +0 -0
  33. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/resolvers.py +0 -0
  34. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/schema.py +0 -0
  35. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/schema_ops.py +0 -0
  36. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/seam.py +0 -0
  37. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/signatures.py +0 -0
  38. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/signed_links.py +0 -0
  39. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/sources.py +0 -0
  40. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/storage.py +0 -0
  41. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/tomledit.py +0 -0
  42. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/uid.py +0 -0
  43. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/union.py +0 -0
  44. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/validate.py +0 -0
  45. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/version.py +0 -0
  46. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/views.py +0 -0
  47. {throughline-4.6.2 → throughline-4.7.0}/src/throughline/worklist.py +0 -0
  48. {throughline-4.6.2 → throughline-4.7.0}/src/throughline.egg-info/dependency_links.txt +0 -0
  49. {throughline-4.6.2 → throughline-4.7.0}/src/throughline.egg-info/entry_points.txt +0 -0
  50. {throughline-4.6.2 → throughline-4.7.0}/src/throughline.egg-info/requires.txt +0 -0
  51. {throughline-4.6.2 → throughline-4.7.0}/src/throughline.egg-info/top_level.txt +0 -0
  52. {throughline-4.6.2 → throughline-4.7.0}/tests/test_amend.py +0 -0
  53. {throughline-4.6.2 → throughline-4.7.0}/tests/test_apply.py +0 -0
  54. {throughline-4.6.2 → throughline-4.7.0}/tests/test_apply_once.py +0 -0
  55. {throughline-4.6.2 → throughline-4.7.0}/tests/test_attribute_kinds.py +0 -0
  56. {throughline-4.6.2 → throughline-4.7.0}/tests/test_baseline.py +0 -0
  57. {throughline-4.6.2 → throughline-4.7.0}/tests/test_clarify.py +0 -0
  58. {throughline-4.6.2 → throughline-4.7.0}/tests/test_declared.py +0 -0
  59. {throughline-4.6.2 → throughline-4.7.0}/tests/test_deprecated_names.py +0 -0
  60. {throughline-4.6.2 → throughline-4.7.0}/tests/test_diagram_cli.py +0 -0
  61. {throughline-4.6.2 → throughline-4.7.0}/tests/test_doctor.py +0 -0
  62. {throughline-4.6.2 → throughline-4.7.0}/tests/test_engine.py +0 -0
  63. {throughline-4.6.2 → throughline-4.7.0}/tests/test_filters.py +0 -0
  64. {throughline-4.6.2 → throughline-4.7.0}/tests/test_flag.py +0 -0
  65. {throughline-4.6.2 → throughline-4.7.0}/tests/test_init_from_schema.py +0 -0
  66. {throughline-4.6.2 → throughline-4.7.0}/tests/test_library_api.py +0 -0
  67. {throughline-4.6.2 → throughline-4.7.0}/tests/test_link_guard.py +0 -0
  68. {throughline-4.6.2 → throughline-4.7.0}/tests/test_migrate_withdrawn.py +0 -0
  69. {throughline-4.6.2 → throughline-4.7.0}/tests/test_normative_by_type.py +0 -0
  70. {throughline-4.6.2 → throughline-4.7.0}/tests/test_own_tree.py +0 -0
  71. {throughline-4.6.2 → throughline-4.7.0}/tests/test_ratification_change.py +0 -0
  72. {throughline-4.6.2 → throughline-4.7.0}/tests/test_ratification_withdrawal.py +0 -0
  73. {throughline-4.6.2 → throughline-4.7.0}/tests/test_ratified_content.py +0 -0
  74. {throughline-4.6.2 → throughline-4.7.0}/tests/test_ratified_deletion.py +0 -0
  75. {throughline-4.6.2 → throughline-4.7.0}/tests/test_ratifier_correction.py +0 -0
  76. {throughline-4.6.2 → throughline-4.7.0}/tests/test_ratify_several.py +0 -0
  77. {throughline-4.6.2 → throughline-4.7.0}/tests/test_ratify_status.py +0 -0
  78. {throughline-4.6.2 → throughline-4.7.0}/tests/test_ratify_transition_refused_first.py +0 -0
  79. {throughline-4.6.2 → throughline-4.7.0}/tests/test_register_type.py +0 -0
  80. {throughline-4.6.2 → throughline-4.7.0}/tests/test_resolve_collision.py +0 -0
  81. {throughline-4.6.2 → throughline-4.7.0}/tests/test_resolve_cross_graph.py +0 -0
  82. {throughline-4.6.2 → throughline-4.7.0}/tests/test_schema_ops.py +0 -0
  83. {throughline-4.6.2 → throughline-4.7.0}/tests/test_schema_source.py +0 -0
  84. {throughline-4.6.2 → throughline-4.7.0}/tests/test_signatures.py +0 -0
  85. {throughline-4.6.2 → throughline-4.7.0}/tests/test_signed_links.py +0 -0
  86. {throughline-4.6.2 → throughline-4.7.0}/tests/test_spec_lists.py +0 -0
  87. {throughline-4.6.2 → throughline-4.7.0}/tests/test_tombstone_record.py +0 -0
  88. {throughline-4.6.2 → throughline-4.7.0}/tests/test_unset_attrs.py +0 -0
  89. {throughline-4.6.2 → throughline-4.7.0}/tests/test_worklist.py +0 -0
  90. {throughline-4.6.2 → throughline-4.7.0}/tests/test_yaml_loader.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: throughline
3
- Version: 4.6.2
3
+ Version: 4.7.0
4
4
  Summary: A Git-native requirements management tool with a scope-avalanche grounding layer: permanent UIDs, one file per item, typed links, suspect detection, and a CI-gating check.
5
5
  Author-email: Henry J Grech-Cini <henry.grechcini@gmail.com>
6
6
  License-Expression: Apache-2.0
@@ -36,10 +36,10 @@ version control; a `check` command validates the whole graph and gates CI.
36
36
 
37
37
  **Dogfooded:** throughline's own spec is itself a throughline project —
38
38
  <!-- tl:count type == 'system_requirement' -->
39
- 263
39
+ 268
40
40
  <!-- tl:end --> system requirements,
41
41
  <!-- tl:count type == 'user_requirement' -->
42
- 41
42
+ 42
43
43
  <!-- tl:end --> user requirements, and
44
44
  <!-- tl:count type == 'nfr' -->
45
45
  21
@@ -8,10 +8,10 @@ version control; a `check` command validates the whole graph and gates CI.
8
8
 
9
9
  **Dogfooded:** throughline's own spec is itself a throughline project —
10
10
  <!-- tl:count type == 'system_requirement' -->
11
- 263
11
+ 268
12
12
  <!-- tl:end --> system requirements,
13
13
  <!-- tl:count type == 'user_requirement' -->
14
- 41
14
+ 42
15
15
  <!-- tl:end --> user requirements, and
16
16
  <!-- tl:count type == 'nfr' -->
17
17
  21
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "throughline"
7
- version = "4.6.2"
7
+ version = "4.7.0"
8
8
  description = "A Git-native requirements management tool with a scope-avalanche grounding layer: permanent UIDs, one file per item, typed links, suspect detection, and a CI-gating check."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -121,6 +121,7 @@ from .sources import SourceError, parse_sources
121
121
  from .union import ComposeError, build_union, translate_finding
122
122
  from .storage import (
123
123
  CONFIG_NAME,
124
+ FORMAT_VERSION,
124
125
  MANIFEST_NAME,
125
126
  ProjectError,
126
127
  baseline_note,
@@ -146,6 +147,7 @@ from .validate import (
146
147
  validate,
147
148
  )
148
149
  from .version import distribution_version
150
+ from . import migrate_beneath
149
151
 
150
152
  OK, FINDINGS, USAGE = 0, 1, 2
151
153
 
@@ -293,6 +295,11 @@ def cmd_init(args) -> int:
293
295
 
294
296
 
295
297
  def cmd_migrate(args) -> int:
298
+ if getattr(args, "beneath", None):
299
+ return _migrate_beneath(args)
300
+ if getattr(args, "apply", False):
301
+ return _err("--apply migrates the graphs found by --beneath; name at least "
302
+ "one --beneath PATH (SR-0301)")
296
303
  try:
297
304
  result = migrate_project(args.path)
298
305
  except ProjectError as e:
@@ -2173,6 +2180,77 @@ def _composed_ratify(args) -> int:
2173
2180
  return OK
2174
2181
 
2175
2182
 
2183
+ def _migrate_beneath(args) -> int:
2184
+ """Every graph beneath the given paths: listed (SR-0301), or migrated where it
2185
+ is safe to rewrite (SR-0302..SR-0304). Nothing is ever committed."""
2186
+ found = migrate_beneath.survey(args.beneath)
2187
+ behind = [f for f in found if f.behind]
2188
+ if not args.apply:
2189
+ _print_behind(behind)
2190
+ _print_unmigratable(found)
2191
+ current = sum(1 for f in found if f.declared == FORMAT_VERSION)
2192
+ print(f"{current} graph(s) already at format version {FORMAT_VERSION}")
2193
+ if not args.apply:
2194
+ if behind:
2195
+ print("nothing was written — run again with --apply to migrate those "
2196
+ "with no uncommitted changes and not in a linked worktree")
2197
+ return OK
2198
+
2199
+ outcomes = migrate_beneath.apply(behind)
2200
+ skipped = [o for o in outcomes if o.skipped]
2201
+ failed = [o for o in outcomes if o.failed]
2202
+ if skipped:
2203
+ print(f"skipped {len(skipped)} graph(s):")
2204
+ for o in skipped:
2205
+ print(f" {o.found.root} — {o.skipped}")
2206
+ if failed:
2207
+ print(f"failed to migrate {len(failed)} graph(s):")
2208
+ for o in failed:
2209
+ print(f" {o.found.root} — {o.failed}")
2210
+ by_repo: dict[Path, int] = {}
2211
+ for o in outcomes:
2212
+ if o.migrated:
2213
+ by_repo[o.found.repository] = by_repo.get(o.found.repository, 0) + 1
2214
+ for repo, n in by_repo.items():
2215
+ print(f"migrated {n} graph(s) in {repo} to format version {FORMAT_VERSION} "
2216
+ "— review with `git diff` and commit them there")
2217
+ if not by_repo:
2218
+ print("migrated nothing")
2219
+ return FINDINGS if failed else OK
2220
+
2221
+
2222
+ def _print_behind(behind) -> None:
2223
+ if not behind:
2224
+ print(f"no graph is below format version {FORMAT_VERSION}")
2225
+ return
2226
+ print(f"{len(behind)} graph(s) below format version {FORMAT_VERSION}:")
2227
+ groups: dict[Path | None, list] = {}
2228
+ for f in behind:
2229
+ groups.setdefault(f.repository, []).append(f)
2230
+ # By repository, so each owner's graphs read together; those outside any last.
2231
+ for repo, graphs in sorted(groups.items(),
2232
+ key=lambda g: (g[0] is None, str(g[0]))):
2233
+ print(f" {repo if repo is not None else '(not in a git repository)'}")
2234
+ for f in graphs:
2235
+ # Forward slashes, so a listing reads the same on every platform.
2236
+ where = f.root if repo is None else f.root.relative_to(repo).as_posix()
2237
+ print(f" {where} format {f.declared}")
2238
+
2239
+
2240
+ def _print_unmigratable(found) -> None:
2241
+ unread = [f for f in found if f.error is not None]
2242
+ ahead = [f for f in found if f.ahead]
2243
+ if unread:
2244
+ print(f"{len(unread)} graph(s) whose configuration cannot be read:")
2245
+ for f in unread:
2246
+ print(f" {f.root} — {f.error}")
2247
+ if ahead:
2248
+ print(f"{len(ahead)} graph(s) newer than this tl's format version "
2249
+ f"{FORMAT_VERSION} — upgrade tl to open them:")
2250
+ for f in ahead:
2251
+ print(f" {f.root} format {f.declared}")
2252
+
2253
+
2176
2254
  def _composed_migrate(args) -> int:
2177
2255
  """Migrate the consumer, judging its ratification records over the union
2178
2256
  (SR-0153).
@@ -2185,7 +2263,9 @@ def _composed_migrate(args) -> int:
2185
2263
  bound record carries a fingerprint and never matches again, so the union pass
2186
2264
  can only add."""
2187
2265
  rc = cmd_migrate(args)
2188
- if rc != OK:
2266
+ if rc != OK or getattr(args, "beneath", None):
2267
+ # Over many graphs each is migrated alone (SR-0304): the -C project's
2268
+ # sources have nothing to say about them.
2189
2269
  return rc
2190
2270
 
2191
2271
  # The project is loadable from here — the repair has upgraded it if it needed it.
@@ -0,0 +1,145 @@
1
+ # Copyright (c) 2026 Henry J Grech-Cini
2
+ # SPDX-License-Identifier: Apache-2.0
3
+ """Finding the graphs beneath a directory, and the git facts about where each
4
+ one lives (SR-0300).
5
+
6
+ Part of the library rather than of one command, so every tool that has to find a
7
+ reviewer's graphs — ``tl migrate --beneath`` and tl-ratify's picker among them —
8
+ finds the same ones, instead of each keeping its own copy of the rules.
9
+ """
10
+ from __future__ import annotations
11
+
12
+ import subprocess
13
+ import tomllib
14
+ from pathlib import Path
15
+ from types import SimpleNamespace
16
+
17
+ from .sources import SourceError, parse_sources
18
+ from .storage import CONFIG_NAME
19
+
20
+ # How far beneath a given path the search reaches. Deep enough for the layouts in
21
+ # use (``idd/`` at a repository root, ``packages/<name>/idd`` in a monorepo, a
22
+ # folder of repositories above either).
23
+ MAX_SEARCH_DEPTH = 5
24
+
25
+
26
+ def graphs_beneath(path: str | Path, *more: str | Path) -> list[Path]:
27
+ """The root of every graph at or beneath ``path``, and beneath each of
28
+ ``more``, in the order the walk met them (SR-0300).
29
+
30
+ Breadth-first to :data:`MAX_SEARCH_DEPTH`, pruning as the walk descends, so an
31
+ excluded directory costs nothing to skip. A graph reached from two of the
32
+ paths is returned once, and a graph another found graph encloses and declares
33
+ as a local path source is left out: it is part of that graph's composition,
34
+ not a peer of it.
35
+ """
36
+ roots: list[Path] = []
37
+ for base in (_base_of(p) for p in (path, *more)):
38
+ roots.extend(r for r in _walk(base) if r not in roots)
39
+ return _drop_borrowed(roots)
40
+
41
+
42
+ def _base_of(path: str | Path) -> Path:
43
+ base = Path(path).resolve()
44
+ return base if base.is_dir() else base.parent
45
+
46
+
47
+ def _walk(base: Path) -> list[Path]:
48
+ roots = [base] if (base / CONFIG_NAME).exists() else []
49
+ level = [base]
50
+ for _ in range(MAX_SEARCH_DEPTH):
51
+ children: list[Path] = []
52
+ for parent in level:
53
+ try:
54
+ children.extend(c for c in sorted(parent.iterdir())
55
+ if c.is_dir() and not _is_excluded(c))
56
+ except OSError:
57
+ continue
58
+ if not children:
59
+ break
60
+ ignored = _git_ignored(base, children)
61
+ # Both sides resolved: git echoes a path in its own spelling, which on
62
+ # Windows differs from the walk's.
63
+ children = [c for c in children if c.resolve() not in ignored]
64
+ roots.extend(c for c in children if (c / CONFIG_NAME).exists())
65
+ level = children
66
+ return roots
67
+
68
+
69
+ def _is_excluded(d: Path) -> bool:
70
+ """A directory that cannot hold a graph anyone owns: a dot-directory (which
71
+ covers ``.git`` and ``.venv``), a symbolic link, or a virtualenv not named
72
+ like one."""
73
+ return d.name.startswith(".") or d.is_symlink() or (d / "pyvenv.cfg").exists()
74
+
75
+
76
+ def _git_ignored(base: Path, dirs: list[Path]) -> set[Path]:
77
+ """Which of ``dirs`` git ignores. Outside a repository, or with no git, none
78
+ are: the walk then relies on its other exclusions."""
79
+ try:
80
+ # NUL-separated both ways, so text-mode newline translation and git's
81
+ # quoting of unusual names cannot corrupt a path.
82
+ proc = subprocess.run(
83
+ ["git", "-C", str(base), "check-ignore", "--stdin", "-z"],
84
+ input="".join(f"{d}\0" for d in dirs),
85
+ capture_output=True, text=True, timeout=10, check=False)
86
+ except (OSError, subprocess.SubprocessError):
87
+ return set()
88
+ return {Path(e).resolve() for e in proc.stdout.split("\0") if e.strip()}
89
+
90
+
91
+ def _drop_borrowed(roots: list[Path]) -> list[Path]:
92
+ borrowed: set[Path] = set()
93
+ for root in roots:
94
+ borrowed |= {src for src in _path_sources(root)
95
+ if src != root and root in src.parents}
96
+ return [r for r in roots if r not in borrowed]
97
+
98
+
99
+ def _path_sources(root: Path) -> set[Path]:
100
+ """The local directories a graph declares as sources, read from its
101
+ configuration alone. A graph at an older format may still carry the withdrawn
102
+ ``reexport`` key, so it is ignored here rather than refused."""
103
+ try:
104
+ config = tomllib.loads((root / CONFIG_NAME).read_text(encoding="utf-8"))
105
+ declared = parse_sources(SimpleNamespace(config=config), withdrawn="ignore")
106
+ except (OSError, ValueError, SourceError):
107
+ return set()
108
+ return {(root / s.path).resolve() for s in declared if not s.is_remote and s.path}
109
+
110
+
111
+ # --------------------------------------------------------------- where it lives
112
+
113
+ def _git(root: Path, *args: str) -> str | None:
114
+ """git's answer, run in ``root``, or None where there is no repository (or no
115
+ git) to ask."""
116
+ try:
117
+ proc = subprocess.run(["git", "-C", str(root), *args],
118
+ capture_output=True, text=True, timeout=30, check=False)
119
+ except (OSError, subprocess.SubprocessError):
120
+ return None
121
+ return proc.stdout if proc.returncode == 0 else None
122
+
123
+
124
+ def repository_of(root: Path) -> Path | None:
125
+ """The top of the git working tree holding ``root``, or None outside one."""
126
+ top = _git(root, "rev-parse", "--show-toplevel")
127
+ return Path(top.strip()).resolve() if top and top.strip() else None
128
+
129
+
130
+ def in_linked_worktree(root: Path) -> bool:
131
+ """Whether ``root`` lies in a linked worktree — one whose git directory is not
132
+ the repository's common directory (SR-0303)."""
133
+ out = _git(root, "rev-parse", "--path-format=absolute",
134
+ "--git-dir", "--git-common-dir")
135
+ if out is None:
136
+ return False
137
+ lines = out.split("\n")
138
+ return len(lines) >= 2 and Path(lines[0]).resolve() != Path(lines[1]).resolve()
139
+
140
+
141
+ def has_uncommitted_changes(root: Path) -> bool:
142
+ """Whether anything under ``root`` differs from its last commit, tracked or
143
+ untracked, ignored files aside (SR-0302)."""
144
+ out = _git(root, "status", "--porcelain", "--untracked-files=all", "--", ".")
145
+ return out is None or bool(out.strip())
@@ -0,0 +1,96 @@
1
+ # Copyright (c) 2026 Henry J Grech-Cini
2
+ # SPDX-License-Identifier: Apache-2.0
3
+ """``tl migrate --beneath``: every graph beneath some paths brought to the current
4
+ format (UR-0045).
5
+
6
+ Surveying writes nothing (SR-0301). Applying migrates only the graphs it is safe
7
+ to rewrite — not one with uncommitted work (SR-0302), not one in another branch's
8
+ linked worktree (SR-0303) — and commits nothing (SR-0304).
9
+ """
10
+ from __future__ import annotations
11
+
12
+ import tomllib
13
+ from dataclasses import dataclass
14
+ from pathlib import Path
15
+
16
+ from . import discovery
17
+ from .storage import (CONFIG_NAME, FORMAT_VERSION, ProjectError,
18
+ _read_format_version, migrate_project)
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class Found:
23
+ """A graph the search found, and what its configuration says."""
24
+
25
+ root: Path
26
+ repository: Path | None # the git working tree holding it, if any
27
+ declared: int | None # its format version, when it could be read
28
+ error: str | None = None # why it could not be, when it could not
29
+
30
+ @property
31
+ def behind(self) -> bool:
32
+ return self.declared is not None and self.declared < FORMAT_VERSION
33
+
34
+ @property
35
+ def ahead(self) -> bool:
36
+ return self.declared is not None and self.declared > FORMAT_VERSION
37
+
38
+
39
+ def survey(paths: list[str | Path]) -> list[Found]:
40
+ """Every graph beneath ``paths``, with its declared format (SR-0300, SR-0301).
41
+ Reads configurations only; never writes."""
42
+ return [_found(root) for root in discovery.graphs_beneath(*paths)]
43
+
44
+
45
+ def _found(root: Path) -> Found:
46
+ repository = discovery.repository_of(root)
47
+ try:
48
+ config = tomllib.loads((root / CONFIG_NAME).read_text(encoding="utf-8"))
49
+ return Found(root, repository, _read_format_version(config, root))
50
+ except (OSError, ValueError, ProjectError) as e:
51
+ return Found(root, repository, None, str(e).splitlines()[0])
52
+
53
+
54
+ def skip_reason(found: Found) -> str | None:
55
+ """Why ``--apply`` must leave this graph alone, or None to migrate it."""
56
+ if found.repository is None:
57
+ # Nothing would show its owner what the migration changed (SR-0302).
58
+ return "not in a git repository — migrate it with `tl -C <path> migrate`"
59
+ if discovery.in_linked_worktree(found.root):
60
+ return "in a linked git worktree — another branch's to migrate"
61
+ if discovery.has_uncommitted_changes(found.root):
62
+ return "has uncommitted changes — commit or discard them first"
63
+ return None
64
+
65
+
66
+ @dataclass(frozen=True)
67
+ class Outcome:
68
+ found: Found
69
+ skipped: str | None = None # why it was left alone
70
+ failed: str | None = None # why its migration failed
71
+
72
+ @property
73
+ def migrated(self) -> bool:
74
+ return self.skipped is None and self.failed is None
75
+
76
+
77
+ def apply(graphs: list[Found]) -> list[Outcome]:
78
+ """Migrate each graph behind the current format that is safe to rewrite,
79
+ carrying on past any that fails (SR-0304). Sources are not resolved: the
80
+ migration is the one a graph gets alone, which is lossless and offline."""
81
+ outcomes: list[Outcome] = []
82
+ for found in graphs:
83
+ if not found.behind:
84
+ continue
85
+ reason = skip_reason(found)
86
+ if reason is not None:
87
+ outcomes.append(Outcome(found, skipped=reason))
88
+ continue
89
+ try:
90
+ migrate_project(found.root)
91
+ except Exception as e: # noqa: BLE001 - one graph's failure must not stop the rest
92
+ outcomes.append(Outcome(found, failed=(str(e).splitlines() or
93
+ [type(e).__name__])[0]))
94
+ continue
95
+ outcomes.append(Outcome(found))
96
+ return outcomes
@@ -252,6 +252,14 @@ def build_parser(handlers=None) -> argparse.ArgumentParser:
252
252
 
253
253
  s = sub.add_parser("migrate",
254
254
  help="upgrade an older project's on-disk format to this tl")
255
+ s.add_argument("--beneath", metavar="PATH", action="append",
256
+ help="every graph beneath PATH instead of the -C project "
257
+ "(repeatable); lists what is behind unless --apply "
258
+ "(SR-0300, SR-0301)")
259
+ s.add_argument("--apply", action="store_true",
260
+ help="with --beneath: migrate each graph that is behind, has no "
261
+ "uncommitted changes and is not in a linked worktree; "
262
+ "commits nothing (SR-0302..SR-0304)")
255
263
  s.set_defaults(func=handlers.get("cmd_migrate"))
256
264
 
257
265
  s = sub.add_parser("register", help="register (prefix-owning collection) operations")
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: throughline
3
- Version: 4.6.2
3
+ Version: 4.7.0
4
4
  Summary: A Git-native requirements management tool with a scope-avalanche grounding layer: permanent UIDs, one file per item, typed links, suspect detection, and a CI-gating check.
5
5
  Author-email: Henry J Grech-Cini <henry.grechcini@gmail.com>
6
6
  License-Expression: Apache-2.0
@@ -36,10 +36,10 @@ version control; a `check` command validates the whole graph and gates CI.
36
36
 
37
37
  **Dogfooded:** throughline's own spec is itself a throughline project —
38
38
  <!-- tl:count type == 'system_requirement' -->
39
- 263
39
+ 268
40
40
  <!-- tl:end --> system requirements,
41
41
  <!-- tl:count type == 'user_requirement' -->
42
- 41
42
+ 42
43
43
  <!-- tl:end --> user requirements, and
44
44
  <!-- tl:count type == 'nfr' -->
45
45
  21
@@ -10,6 +10,7 @@ src/throughline/collision.py
10
10
  src/throughline/composition.py
11
11
  src/throughline/declared.py
12
12
  src/throughline/diagrams.py
13
+ src/throughline/discovery.py
13
14
  src/throughline/dump.py
14
15
  src/throughline/filters.py
15
16
  src/throughline/fingerprint.py
@@ -20,6 +21,7 @@ src/throughline/inherit.py
20
21
  src/throughline/inject.py
21
22
  src/throughline/items.py
22
23
  src/throughline/links.py
24
+ src/throughline/migrate_beneath.py
23
25
  src/throughline/model.py
24
26
  src/throughline/parser.py
25
27
  src/throughline/ratification.py
@@ -60,6 +62,7 @@ tests/test_flag.py
60
62
  tests/test_init_from_schema.py
61
63
  tests/test_library_api.py
62
64
  tests/test_link_guard.py
65
+ tests/test_migrate_beneath.py
63
66
  tests/test_migrate_withdrawn.py
64
67
  tests/test_normative_by_type.py
65
68
  tests/test_own_tree.py
@@ -0,0 +1,208 @@
1
+ # Copyright (c) 2026 Henry J Grech-Cini
2
+ # SPDX-License-Identifier: Apache-2.0
3
+ """`tl migrate --beneath` finds every graph beneath some paths, lists the ones
4
+ behind the current format, and with --apply migrates those safe to rewrite
5
+ (UR-0045, SR-0300..SR-0304).
6
+
7
+ Asked on 1 November 2026, when tl-ratify found 268 of 430 graphs unreadable
8
+ because they were still at format 3, many of them in other sessions' worktrees.
9
+ """
10
+ from __future__ import annotations
11
+
12
+ import os
13
+ import re
14
+ import shutil
15
+ import subprocess
16
+ from pathlib import Path
17
+
18
+ import pytest
19
+
20
+ from throughline.cli import main as cli_main
21
+ from throughline.discovery import graphs_beneath
22
+ from throughline.storage import FORMAT_VERSION
23
+
24
+
25
+ def _cli(argv) -> int:
26
+ return cli_main([str(a) for a in argv])
27
+
28
+
29
+ def _git(root: Path, *args: str) -> str:
30
+ return subprocess.run(["git", "-C", str(root), *args], capture_output=True,
31
+ text=True, check=True).stdout
32
+
33
+
34
+ def _repo(root: Path) -> Path:
35
+ root.mkdir(parents=True, exist_ok=True)
36
+ _git(root, "init", "-q")
37
+ _git(root, "config", "user.email", "grace@example.com")
38
+ _git(root, "config", "user.name", "Grace")
39
+ return root
40
+
41
+
42
+ def _commit(root: Path) -> None:
43
+ _git(root, "add", ".")
44
+ _git(root, "commit", "-qm", "baseline")
45
+
46
+
47
+ def _graph(root: Path, version: int = 3) -> Path:
48
+ """A graph declaring ``version`` — made at the current format and relabelled,
49
+ which is all the 3-to-4 step needs to find in front of it."""
50
+ assert _cli(["-C", root, "init", "--no-demo"]) == 0
51
+ cfg = root / "throughline.toml"
52
+ cfg.write_text(re.sub(r"format_version = \d+", f"format_version = {version}",
53
+ cfg.read_text(encoding="utf-8")), encoding="utf-8")
54
+ return root
55
+
56
+
57
+ def _declared(root: Path) -> int:
58
+ m = re.search(r"format_version = (\d+)",
59
+ (root / "throughline.toml").read_text(encoding="utf-8"))
60
+ return int(m.group(1))
61
+
62
+
63
+ # ----------------------------------------------------------------- SR-0300
64
+
65
+ def test_discovery_finds_nested_graphs_and_skips_what_no_one_owns(tmp_path):
66
+ repo = _repo(tmp_path / "repo")
67
+ found = [_graph(repo / "idd"), _graph(repo / "packages" / "a" / "idd")]
68
+ _graph(repo / ".hidden" / "idd")
69
+ _graph(repo / "venv" / "idd")
70
+ (repo / "venv" / "pyvenv.cfg").write_text("home = /usr\n", encoding="utf-8")
71
+ _graph(repo / "build" / "idd")
72
+ (repo / ".gitignore").write_text("build/\n", encoding="utf-8")
73
+ os.symlink(repo / "idd", repo / "linked")
74
+ _graph(repo / "a" / "b" / "c" / "d" / "e" / "too-deep")
75
+
76
+ assert graphs_beneath(repo) == found
77
+
78
+
79
+ def test_discovery_leaves_out_a_graph_an_enclosing_graph_borrows(tmp_path):
80
+ outer = _graph(tmp_path / "outer")
81
+ # Made apart and moved in, because init refuses to nest one graph in another.
82
+ shutil.move(_graph(tmp_path / "made-apart"), outer / "baseline")
83
+ cfg = outer / "throughline.toml"
84
+ cfg.write_text(cfg.read_text(encoding="utf-8")
85
+ + '\n[[sources]]\nnamespace = "baseline"\npath = "baseline"\n',
86
+ encoding="utf-8")
87
+ assert graphs_beneath(tmp_path) == [outer]
88
+
89
+
90
+ def test_discovery_lists_a_graph_two_paths_reach_once(tmp_path):
91
+ g = _graph(tmp_path / "x" / "idd")
92
+ assert graphs_beneath(tmp_path, tmp_path / "x") == [g]
93
+
94
+
95
+ # ----------------------------------------------------------------- SR-0301
96
+
97
+ def test_without_apply_it_lists_by_repository_and_writes_nothing(tmp_path, capsys):
98
+ one = _repo(tmp_path / "one")
99
+ _graph(one / "idd")
100
+ _graph(one / "docs" / "idd")
101
+ two = _repo(tmp_path / "two")
102
+ _graph(two / "idd", version=FORMAT_VERSION)
103
+ _commit(one)
104
+ before = (one / "idd" / "throughline.toml").read_text(encoding="utf-8")
105
+
106
+ assert _cli(["migrate", "--beneath", tmp_path]) == 0
107
+ out = capsys.readouterr().out
108
+ assert "2 graph(s) below format version" in out
109
+ assert f" {one.resolve()}\n idd format 3\n docs/idd format 3\n" in out
110
+ assert f"1 graph(s) already at format version {FORMAT_VERSION}" in out
111
+ assert "nothing was written" in out
112
+ assert (one / "idd" / "throughline.toml").read_text(encoding="utf-8") == before
113
+ assert _git(one, "status", "--porcelain") == ""
114
+
115
+
116
+ def test_without_apply_it_names_graphs_it_cannot_read_or_that_are_newer(tmp_path,
117
+ capsys):
118
+ (tmp_path / "broken").mkdir()
119
+ (tmp_path / "broken" / "throughline.toml").write_text("[project\n",
120
+ encoding="utf-8")
121
+ _graph(tmp_path / "future", version=FORMAT_VERSION + 1)
122
+ assert _cli(["migrate", "--beneath", tmp_path]) == 0
123
+ out = capsys.readouterr().out
124
+ assert "1 graph(s) whose configuration cannot be read" in out
125
+ assert str((tmp_path / "broken").resolve()) in out
126
+ assert "newer than this tl" in out
127
+ assert f"format {FORMAT_VERSION + 1}" in out
128
+
129
+
130
+ def test_apply_without_beneath_is_a_usage_error(tmp_path, capsys):
131
+ _graph(tmp_path)
132
+ assert _cli(["-C", tmp_path, "migrate", "--apply"]) == 2
133
+ assert "--beneath" in capsys.readouterr().err
134
+ assert _declared(tmp_path) == 3
135
+
136
+
137
+ # ----------------------------------------------------------------- SR-0302
138
+
139
+ @pytest.mark.parametrize("change", ["tracked", "untracked"])
140
+ def test_apply_skips_a_graph_with_uncommitted_changes(tmp_path, capsys, change):
141
+ repo = _repo(tmp_path / "repo")
142
+ g = _graph(repo / "idd")
143
+ _commit(repo)
144
+ if change == "tracked":
145
+ (g / "throughline.toml").write_text(
146
+ (g / "throughline.toml").read_text(encoding="utf-8") + "# edit\n",
147
+ encoding="utf-8")
148
+ else:
149
+ (g / "notes.txt").write_text("wip\n", encoding="utf-8")
150
+
151
+ assert _cli(["migrate", "--beneath", repo, "--apply"]) == 0
152
+ out = capsys.readouterr().out
153
+ assert f"{g.resolve()} — has uncommitted changes" in out
154
+ assert "migrated nothing" in out
155
+ assert _declared(g) == 3
156
+
157
+
158
+ def test_apply_skips_a_graph_outside_any_repository(tmp_path, capsys):
159
+ g = _graph(tmp_path / "loose")
160
+ assert _cli(["migrate", "--beneath", tmp_path, "--apply"]) == 0
161
+ assert f"{g.resolve()} — not in a git repository" in capsys.readouterr().out
162
+ assert _declared(g) == 3
163
+
164
+
165
+ # ----------------------------------------------------------------- SR-0303
166
+
167
+ def test_apply_skips_a_graph_in_a_linked_worktree(tmp_path, capsys):
168
+ repo = _repo(tmp_path / "repo")
169
+ _graph(repo / "idd")
170
+ _commit(repo)
171
+ linked = tmp_path / "repo-worktrees" / "feature"
172
+ _git(repo, "worktree", "add", "-q", "-b", "feature", str(linked))
173
+
174
+ assert _cli(["migrate", "--beneath", tmp_path / "repo-worktrees", "--apply"]) == 0
175
+ out = capsys.readouterr().out
176
+ assert f"{(linked / 'idd').resolve()} — in a linked git worktree" in out
177
+ assert _declared(linked / "idd") == 3
178
+
179
+
180
+ # ----------------------------------------------------------------- SR-0304
181
+
182
+ def test_apply_migrates_the_rest_commits_nothing_and_carries_on(tmp_path, capsys):
183
+ repo = _repo(tmp_path / "repo")
184
+ a = _graph(repo / "a")
185
+ b = _graph(repo / "b")
186
+ bad = _graph(repo / "c", version=0) # no migration path from format 0
187
+ _commit(repo)
188
+ head = _git(repo, "rev-parse", "HEAD")
189
+
190
+ assert _cli(["migrate", "--beneath", repo, "--apply"]) == 1
191
+ out = capsys.readouterr().out
192
+ assert _declared(a) == _declared(b) == FORMAT_VERSION
193
+ assert f"{bad.resolve()} — no migration path from format version 0" in out
194
+ assert (f"migrated 2 graph(s) in {repo.resolve()} to format version "
195
+ f"{FORMAT_VERSION}") in out
196
+ assert _git(repo, "rev-parse", "HEAD") == head
197
+ assert _git(repo, "status", "--porcelain") != ""
198
+
199
+
200
+ def test_apply_reports_one_line_per_repository(tmp_path, capsys):
201
+ for name in ("one", "two"):
202
+ repo = _repo(tmp_path / name)
203
+ _graph(repo / "idd")
204
+ _commit(repo)
205
+ assert _cli(["migrate", "--beneath", tmp_path, "--apply"]) == 0
206
+ lines = [ln for ln in capsys.readouterr().out.splitlines()
207
+ if ln.startswith("migrated 1 graph(s) in ")]
208
+ assert len(lines) == 2
File without changes
File without changes
File without changes