promptmigrate-cli 0.1.0__py3-none-any.whl
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.
- promptmigrate/__init__.py +21 -0
- promptmigrate/__main__.py +3 -0
- promptmigrate/apply.py +116 -0
- promptmigrate/cli.py +123 -0
- promptmigrate/commands/__init__.py +5 -0
- promptmigrate/commands/check.py +65 -0
- promptmigrate/commands/current.py +25 -0
- promptmigrate/commands/diff.py +19 -0
- promptmigrate/commands/downgrade.py +36 -0
- promptmigrate/commands/env.py +35 -0
- promptmigrate/commands/get.py +48 -0
- promptmigrate/commands/history.py +41 -0
- promptmigrate/commands/init.py +43 -0
- promptmigrate/commands/plan.py +51 -0
- promptmigrate/commands/restamp.py +47 -0
- promptmigrate/commands/revision.py +97 -0
- promptmigrate/commands/upgrade.py +36 -0
- promptmigrate/commands/validate.py +96 -0
- promptmigrate/core.py +30 -0
- promptmigrate/draftdiff.py +41 -0
- promptmigrate/errors.py +91 -0
- promptmigrate/output.py +122 -0
- promptmigrate/plan.py +112 -0
- promptmigrate/project.py +160 -0
- promptmigrate/protocol/__init__.py +9 -0
- promptmigrate/protocol/equality.py +15 -0
- promptmigrate/protocol/jsonloader.py +92 -0
- promptmigrate/protocol/limits.py +9 -0
- promptmigrate/protocol/rules.py +80 -0
- promptmigrate/revisions.py +181 -0
- promptmigrate/secretscan.py +195 -0
- promptmigrate/store/__init__.py +13 -0
- promptmigrate/store/environments.py +181 -0
- promptmigrate/store/events.py +70 -0
- promptmigrate/store/lock.py +66 -0
- promptmigrate/store/sqlite.py +147 -0
- promptmigrate_cli-0.1.0.dist-info/METADATA +247 -0
- promptmigrate_cli-0.1.0.dist-info/RECORD +42 -0
- promptmigrate_cli-0.1.0.dist-info/WHEEL +5 -0
- promptmigrate_cli-0.1.0.dist-info/entry_points.txt +2 -0
- promptmigrate_cli-0.1.0.dist-info/licenses/LICENSE +21 -0
- promptmigrate_cli-0.1.0.dist-info/top_level.txt +1 -0
promptmigrate/project.py
ADDED
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
"""The .promptmigrate/ project directory: layout, drafts and the reviewed secret allowlist."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import errno
|
|
6
|
+
import json
|
|
7
|
+
import os
|
|
8
|
+
import secrets
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
from typing import Any
|
|
11
|
+
|
|
12
|
+
from . import protocol, secretscan
|
|
13
|
+
from .errors import InitializationError, SchemaError, StorageError
|
|
14
|
+
|
|
15
|
+
ALLOWLIST_FILE = "secret-allowlist.json"
|
|
16
|
+
# os.link failures that mean "this filesystem has no hard links" (e.g. FAT/exFAT), not "the publish failed".
|
|
17
|
+
_NO_LINKS = {errno.EPERM, errno.ENOTSUP, errno.EOPNOTSUPP}
|
|
18
|
+
# CreateHardLink's own "not supported" codes (FAT/exFAT, many SMB shares); CPython maps these failures to errno
|
|
19
|
+
# EINVAL, which isn't in _NO_LINKS above, so the winerror has to be checked too on Windows.
|
|
20
|
+
_NO_LINKS_WINERROR = {1, 50} # ERROR_INVALID_FUNCTION, ERROR_NOT_SUPPORTED
|
|
21
|
+
# Exclusive create in binary mode. Mode 0o666 lets the OS apply the umask (and any default ACL) at creation, so the
|
|
22
|
+
# process never has to read the umask: os.umask is process-wide and reading it means setting it.
|
|
23
|
+
_NEW_FILE_FLAGS = os.O_CREAT | os.O_EXCL | os.O_WRONLY | getattr(os, "O_BINARY", 0)
|
|
24
|
+
_NEW_FILE_MODE = 0o666
|
|
25
|
+
_TEMP_ATTEMPTS = 100
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def pretty(obj: Any) -> str:
|
|
29
|
+
return json.dumps(obj, sort_keys=True, ensure_ascii=False, indent=2) + "\n"
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def _write_all(fd: int, data: bytes) -> None:
|
|
33
|
+
view = memoryview(data)
|
|
34
|
+
while view:
|
|
35
|
+
view = view[os.write(fd, view):]
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def _create_temp(directory: Path) -> tuple[int, Path]:
|
|
39
|
+
"""Create a new hidden `.<hex>.tmp` file in `directory`; the `*.json` glob in load_revisions never sees it.
|
|
40
|
+
|
|
41
|
+
Not tempfile.mkstemp: it always creates mode 0600, and a hard link shares that mode, so the published file would
|
|
42
|
+
be unreadable to others; fixing it afterwards needs the umask.
|
|
43
|
+
"""
|
|
44
|
+
for _ in range(_TEMP_ATTEMPTS):
|
|
45
|
+
temp = directory / f".{secrets.token_hex(8)}.tmp"
|
|
46
|
+
try:
|
|
47
|
+
return os.open(temp, _NEW_FILE_FLAGS, _NEW_FILE_MODE), temp
|
|
48
|
+
except FileExistsError:
|
|
49
|
+
continue # someone else's temp file: never touch it, try another name
|
|
50
|
+
raise StorageError(f"Cannot create a temporary file in {directory.name}: every name tried exists")
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def _fsync_dir(directory: Path) -> None:
|
|
54
|
+
if os.name != "nt": # Windows cannot open a directory for fsync; NTFS journals the new entry itself
|
|
55
|
+
fd = os.open(directory, os.O_RDONLY)
|
|
56
|
+
try:
|
|
57
|
+
os.fsync(fd)
|
|
58
|
+
finally:
|
|
59
|
+
os.close(fd)
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def _link_unsupported(exc: OSError) -> bool:
|
|
63
|
+
"""Whether `exc` means "this filesystem has no hard links", on POSIX or on Windows."""
|
|
64
|
+
if exc.errno in _NO_LINKS:
|
|
65
|
+
return True
|
|
66
|
+
return os.name == "nt" and getattr(exc, "winerror", None) in _NO_LINKS_WINERROR
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _write_exclusive(path: Path, data: bytes) -> None:
|
|
70
|
+
"""No-clobber fallback without hard links: still never overwrites, but a crash can leave a partial file."""
|
|
71
|
+
fd = os.open(path, _NEW_FILE_FLAGS, _NEW_FILE_MODE)
|
|
72
|
+
try:
|
|
73
|
+
try:
|
|
74
|
+
_write_all(fd, data)
|
|
75
|
+
os.fsync(fd)
|
|
76
|
+
finally:
|
|
77
|
+
os.close(fd)
|
|
78
|
+
except BaseException:
|
|
79
|
+
path.unlink(missing_ok=True) # we created it (O_EXCL), so removing it removes only our partial bytes
|
|
80
|
+
raise
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def write_new_file(path: Path, text: str) -> None:
|
|
84
|
+
"""Publish `text` as UTF-8 at `path` (a new file) atomically, never overwriting an existing one.
|
|
85
|
+
|
|
86
|
+
Raises FileExistsError if `path` exists; any other OSError becomes StorageError. No temp file survives.
|
|
87
|
+
"""
|
|
88
|
+
data = text.encode("utf-8")
|
|
89
|
+
try:
|
|
90
|
+
fd, temp = _create_temp(path.parent)
|
|
91
|
+
try:
|
|
92
|
+
try:
|
|
93
|
+
_write_all(fd, data)
|
|
94
|
+
os.fsync(fd)
|
|
95
|
+
finally:
|
|
96
|
+
os.close(fd)
|
|
97
|
+
try:
|
|
98
|
+
os.link(temp, path)
|
|
99
|
+
except FileExistsError:
|
|
100
|
+
raise
|
|
101
|
+
except OSError as exc:
|
|
102
|
+
if not _link_unsupported(exc):
|
|
103
|
+
raise
|
|
104
|
+
_write_exclusive(path, data)
|
|
105
|
+
finally:
|
|
106
|
+
# Best-effort: once published, a leftover/failed-to-remove temp file must not turn success into
|
|
107
|
+
# StorageError, nor replace an in-flight exception (e.g. the FileExistsError above) with its own.
|
|
108
|
+
try:
|
|
109
|
+
temp.unlink(missing_ok=True)
|
|
110
|
+
except OSError:
|
|
111
|
+
pass
|
|
112
|
+
except FileExistsError:
|
|
113
|
+
raise
|
|
114
|
+
except OSError as exc:
|
|
115
|
+
raise StorageError(f"Cannot write {path.name}: {exc}") from exc
|
|
116
|
+
try:
|
|
117
|
+
_fsync_dir(path.parent) # the file is already visible; directory durability beyond this is best effort
|
|
118
|
+
except OSError:
|
|
119
|
+
pass
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def root_dir(project_dir: Path) -> Path:
|
|
123
|
+
return Path(project_dir).resolve() / ".promptmigrate"
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
def require_init(project_dir: Path) -> Path:
|
|
127
|
+
"""Return the .promptmigrate directory, or raise InitializationError if the project is not initialized."""
|
|
128
|
+
root = root_dir(project_dir)
|
|
129
|
+
if not (root / "versions").is_dir() or not (root / "drafts").is_dir():
|
|
130
|
+
raise InitializationError("Not initialized. Run: promptmigrate init")
|
|
131
|
+
return root
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def read_drafts(project_dir: Path) -> dict[str, dict[str, Any]]:
|
|
135
|
+
root = require_init(project_dir)
|
|
136
|
+
drafts = {}
|
|
137
|
+
for path in sorted((root / "drafts").iterdir()):
|
|
138
|
+
if path.is_dir() or path.suffix != ".json":
|
|
139
|
+
continue
|
|
140
|
+
name = path.stem
|
|
141
|
+
value, _raw, _rules = protocol.load_json(path, kind="draft", root=root)
|
|
142
|
+
protocol.validate_config(name, value)
|
|
143
|
+
found = protocol.config_violations(name, value)
|
|
144
|
+
if found:
|
|
145
|
+
raise SchemaError(f"Invalid draft {path.name}: {', '.join(found)}")
|
|
146
|
+
drafts[name] = value
|
|
147
|
+
collisions = protocol.case_collisions(drafts)
|
|
148
|
+
if collisions:
|
|
149
|
+
raise SchemaError(f"Invalid drafts: case-collision {collisions[0]}")
|
|
150
|
+
return drafts
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
def load_allowlist(project_dir: Path) -> list[secretscan.AllowEntry]:
|
|
154
|
+
"""The reviewed secret allowlist (.promptmigrate/secret-allowlist.json); empty when the file is absent."""
|
|
155
|
+
root = require_init(project_dir)
|
|
156
|
+
path = root / ALLOWLIST_FILE
|
|
157
|
+
if not path.exists() and not path.is_symlink():
|
|
158
|
+
return []
|
|
159
|
+
value, _raw, _rules = protocol.load_json(path, kind="allowlist", root=root)
|
|
160
|
+
return secretscan.parse_allowlist(value, path.name)
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
"""Source-file protocol: strict JSON loading, limits, canonical equality and config validation.
|
|
2
|
+
|
|
3
|
+
Names are defined in the submodules and re-exported here. Patch a limit on `protocol.limits`, not on this package.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from .equality import canonical, same
|
|
7
|
+
from .jsonloader import _PREFIX, _StrictJSONError, _finite_float, _reject_constant, _unique_pairs, load_json
|
|
8
|
+
from .limits import MAX_CONFIG_DEPTH, MAX_CONTROL_FILE_BYTES, MAX_DRAFT_BYTES, MAX_REVISION_BYTES
|
|
9
|
+
from .rules import _NAME, RESERVED_TYPES, case_collisions, config_depth, config_violations, validate_config
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
"""Canonical JSON text and equality by it."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def canonical(obj: Any) -> str:
|
|
10
|
+
return json.dumps(obj, sort_keys=True, ensure_ascii=False, separators=(",", ":"))
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def same(a: Any, b: Any) -> bool:
|
|
14
|
+
"""Equality by canonical JSON, so 1, 1.0 and true are pairwise distinct (Python's == conflates them)."""
|
|
15
|
+
return canonical(a) == canonical(b)
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
"""Strict JSON loading of source files: duplicate keys, non-finite numbers, size limits, symlinks."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
import math
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
from typing import Any
|
|
9
|
+
|
|
10
|
+
from ..errors import SchemaError
|
|
11
|
+
from . import limits
|
|
12
|
+
|
|
13
|
+
_PREFIX = {
|
|
14
|
+
"draft": "Invalid JSON draft",
|
|
15
|
+
"revision": "Unreadable migration",
|
|
16
|
+
"allowlist": "Invalid secret allowlist",
|
|
17
|
+
"environments": "Invalid environments file",
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class _StrictJSONError(ValueError):
|
|
22
|
+
pass
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def _unique_pairs(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
|
|
26
|
+
obj: dict[str, Any] = {}
|
|
27
|
+
for key, value in pairs:
|
|
28
|
+
if key in obj:
|
|
29
|
+
raise _StrictJSONError(f"duplicate key {key!r}")
|
|
30
|
+
obj[key] = value
|
|
31
|
+
return obj
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def _reject_constant(name: str) -> Any:
|
|
35
|
+
raise _StrictJSONError(f"non-finite number {name} is not allowed")
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def _finite_float(text: str) -> float:
|
|
39
|
+
value = float(text)
|
|
40
|
+
if not math.isfinite(value):
|
|
41
|
+
raise _StrictJSONError("number out of range")
|
|
42
|
+
return value
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def load_json(path: Path, *, kind: str, root: Path) -> tuple[Any, bytes, list[str]]:
|
|
46
|
+
"""Strictly read one source file under root (.promptmigrate/).
|
|
47
|
+
|
|
48
|
+
Returns (value, raw bytes, tier-B file rules). Tier-A problems always raise SchemaError. Drafts, the allowlist,
|
|
49
|
+
and the environment manifest raise on symlinks and size; an existing revision returns those rules so that the
|
|
50
|
+
caller can warn.
|
|
51
|
+
"""
|
|
52
|
+
prefix = _PREFIX[kind]
|
|
53
|
+
rules: list[str] = []
|
|
54
|
+
try:
|
|
55
|
+
if not path.resolve().is_relative_to(root.resolve()):
|
|
56
|
+
raise SchemaError(f"{prefix} {path.name}: resolves outside .promptmigrate/")
|
|
57
|
+
if path.is_symlink():
|
|
58
|
+
if kind == "draft":
|
|
59
|
+
raise SchemaError(f"{prefix} {path.name}: drafts must not be symlinks")
|
|
60
|
+
if kind in {"allowlist", "environments"}:
|
|
61
|
+
raise SchemaError(f"{prefix} {path.name}: must not be a symlink")
|
|
62
|
+
rules.append("symlink")
|
|
63
|
+
size = path.stat().st_size
|
|
64
|
+
limit = {
|
|
65
|
+
"draft": limits.MAX_DRAFT_BYTES,
|
|
66
|
+
"allowlist": limits.MAX_CONTROL_FILE_BYTES,
|
|
67
|
+
"environments": limits.MAX_CONTROL_FILE_BYTES,
|
|
68
|
+
}.get(kind)
|
|
69
|
+
if limit is not None and size > limit:
|
|
70
|
+
raise SchemaError(f"{prefix} {path.name}: {size} bytes exceeds the {limit}-byte limit")
|
|
71
|
+
raw = path.read_bytes()
|
|
72
|
+
except SchemaError:
|
|
73
|
+
raise
|
|
74
|
+
except RuntimeError as exc:
|
|
75
|
+
# Path.resolve() raises an untyped RuntimeError for a symlink loop on Python 3.10-3.12.
|
|
76
|
+
raise SchemaError(f"{prefix} {path.name}: symlink loop") from exc
|
|
77
|
+
except OSError as exc:
|
|
78
|
+
raise SchemaError(f"{prefix} {path.name}: {exc}") from exc
|
|
79
|
+
if kind == "revision" and len(raw) > limits.MAX_REVISION_BYTES:
|
|
80
|
+
rules.append("revision-size")
|
|
81
|
+
try:
|
|
82
|
+
# Drafts and control files are decoded as UTF-8 text, so a BOM is rejected; revisions are parsed from bytes,
|
|
83
|
+
# so a BOM is accepted. Both are unchanged from the starter (spec §3). A UnicodeDecodeError is a ValueError.
|
|
84
|
+
document = raw if kind == "revision" else raw.decode("utf-8")
|
|
85
|
+
value = json.loads(
|
|
86
|
+
document, object_pairs_hook=_unique_pairs, parse_constant=_reject_constant, parse_float=_finite_float
|
|
87
|
+
)
|
|
88
|
+
except RecursionError as exc:
|
|
89
|
+
raise SchemaError(f"{prefix} {path.name}: nested too deep to parse") from exc
|
|
90
|
+
except ValueError as exc:
|
|
91
|
+
raise SchemaError(f"{prefix} {path.name}: {exc}") from exc
|
|
92
|
+
return value, raw, rules
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
"""Size and depth limits for source files and configs.
|
|
2
|
+
|
|
3
|
+
Module globals, read at call time (as `limits.NAME`) so tests can patch them here.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
MAX_DRAFT_BYTES = 1 << 20 # 1 MiB per draft file
|
|
7
|
+
MAX_REVISION_BYTES = 16 << 20 # 16 MiB per revision file
|
|
8
|
+
MAX_CONFIG_DEPTH = 64 # nesting depth of one config: a draft's root, or one before/after value
|
|
9
|
+
MAX_CONTROL_FILE_BYTES = 1 << 20 # 1 MiB for secret-allowlist.json and environments.json
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
"""Config validation: tier-A rules enforced everywhere, tier-B rules enforced on new content."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import re
|
|
6
|
+
from collections.abc import Iterable
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
from ..errors import SchemaError
|
|
10
|
+
from . import limits
|
|
11
|
+
|
|
12
|
+
RESERVED_TYPES: dict[str, tuple[type, ...]] = {
|
|
13
|
+
"model": (str,),
|
|
14
|
+
"parameters": (dict,),
|
|
15
|
+
"tools": (list,),
|
|
16
|
+
"response_schema": (dict, type(None)),
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
_NAME = re.compile(r"[a-zA-Z][a-zA-Z0-9_-]{0,127}")
|
|
20
|
+
_ENV_NAME = re.compile(r"[A-Za-z][A-Za-z0-9_-]{0,63}")
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def validate_config(name: str, value: Any) -> None:
|
|
24
|
+
"""Tier-A config rules, enforced everywhere."""
|
|
25
|
+
if not _NAME.fullmatch(name):
|
|
26
|
+
raise SchemaError(f"Invalid prompt name: {name!r}")
|
|
27
|
+
if not isinstance(value, dict):
|
|
28
|
+
raise SchemaError(f"Prompt {name!r} must contain a JSON object")
|
|
29
|
+
# Minimal structural validation; intentionally no framework-specific constraints.
|
|
30
|
+
if "messages" in value:
|
|
31
|
+
msgs = value["messages"]
|
|
32
|
+
if not isinstance(msgs, list) or any(
|
|
33
|
+
not isinstance(msg, dict)
|
|
34
|
+
or not isinstance(msg.get("role"), str)
|
|
35
|
+
or not isinstance(msg.get("content"), str)
|
|
36
|
+
for msg in msgs
|
|
37
|
+
):
|
|
38
|
+
raise SchemaError(f"Prompt {name!r} has invalid messages")
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def config_depth(value: Any) -> int:
|
|
42
|
+
"""Nesting depth of JSON containers: a scalar is 0, {} or [] is 1. Iterative, so deep input can't overflow."""
|
|
43
|
+
deepest, stack = 0, [(value, 1)]
|
|
44
|
+
while stack:
|
|
45
|
+
item, depth = stack.pop()
|
|
46
|
+
if isinstance(item, dict):
|
|
47
|
+
children = list(item.values())
|
|
48
|
+
elif isinstance(item, list):
|
|
49
|
+
children = item
|
|
50
|
+
else:
|
|
51
|
+
continue
|
|
52
|
+
deepest = max(deepest, depth)
|
|
53
|
+
stack.extend((child, depth + 1) for child in children)
|
|
54
|
+
return deepest
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def config_violations(name: str, value: dict[str, Any]) -> list[str]:
|
|
58
|
+
"""Tier-B rules for one config, as rule ids plus subject. Enforced on new content, warned about in history."""
|
|
59
|
+
found = []
|
|
60
|
+
if config_depth(value) > limits.MAX_CONFIG_DEPTH:
|
|
61
|
+
found.append(f"config-depth {name}")
|
|
62
|
+
for field, types in RESERVED_TYPES.items():
|
|
63
|
+
if field in value and not isinstance(value[field], types):
|
|
64
|
+
found.append(f"reserved-field-type {name}.{field}")
|
|
65
|
+
return found
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def case_collisions(names: Iterable[str]) -> list[str]:
|
|
69
|
+
"""Each group of names that are equal case-insensitively, as 'A/a'."""
|
|
70
|
+
groups: dict[str, list[str]] = {}
|
|
71
|
+
for name in names:
|
|
72
|
+
groups.setdefault(name.lower(), []).append(name)
|
|
73
|
+
return sorted("/".join(sorted(group)) for group in groups.values() if len(group) > 1)
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def validate_environment_name(name: str) -> None:
|
|
77
|
+
if not isinstance(name, str) or not _ENV_NAME.fullmatch(name):
|
|
78
|
+
raise SchemaError("Environment must be alphanumeric, starting with a letter")
|
|
79
|
+
if re.fullmatch(r"(?i:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])", name):
|
|
80
|
+
raise SchemaError("Environment name is reserved on Windows")
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
"""Source history: revision files, the linear revision graph, and replay of changes from the empty state."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import hashlib
|
|
6
|
+
import json
|
|
7
|
+
import re
|
|
8
|
+
import warnings
|
|
9
|
+
from dataclasses import dataclass
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
from typing import Any
|
|
12
|
+
|
|
13
|
+
from . import project, protocol
|
|
14
|
+
from .errors import LegacyRevisionWarning, MigrationConflictError, RevisionGraphError, SchemaError
|
|
15
|
+
|
|
16
|
+
_V0_KEYS = ("revision", "down_revision", "message", "created_at", "changes")
|
|
17
|
+
_V1_KEYS = frozenset({"format_version", *_V0_KEYS})
|
|
18
|
+
_LEGACY = "revision {rid}: {rule} (accepted for compatibility; create a new revision to fix)"
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
@dataclass(frozen=True)
|
|
22
|
+
class Revision:
|
|
23
|
+
revision: str
|
|
24
|
+
down_revision: str | None
|
|
25
|
+
message: str
|
|
26
|
+
created_at: str
|
|
27
|
+
changes: dict[str, dict[str, Any]]
|
|
28
|
+
checksum: str
|
|
29
|
+
path: Path
|
|
30
|
+
format_version: int = 0
|
|
31
|
+
line_ending_checksums: frozenset[str] = frozenset() # v0 only: raw-byte digests of the LF and CRLF re-saves
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def _hash(data: bytes) -> str:
|
|
35
|
+
return hashlib.sha256(data).hexdigest()
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def line_ending_variants(raw: bytes) -> set[str]:
|
|
39
|
+
"""Raw-byte digests of `raw` re-saved with LF and with CRLF line endings (ADR-027). The v0 checksum is unchanged."""
|
|
40
|
+
lf = raw.replace(b"\r\n", b"\n")
|
|
41
|
+
return {_hash(lf), _hash(lf.replace(b"\n", b"\r\n"))}
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def _v1_checksum(item: dict[str, Any]) -> str:
|
|
45
|
+
"""Protocol v1 (ADR-026): SHA-256 of the canonical JSON of the whole parsed file, tagged so it never equals v0."""
|
|
46
|
+
return "v1:" + _hash(protocol.canonical(item).encode("utf-8"))
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def _format_version(item: dict[str, Any], name: str) -> int:
|
|
50
|
+
"""0 for a file without `format_version` (frozen, ADR-025), 1 for the JSON integer 1; anything else is tier A."""
|
|
51
|
+
if "format_version" not in item:
|
|
52
|
+
return 0
|
|
53
|
+
if type(item["format_version"]) is not int or item["format_version"] != 1:
|
|
54
|
+
raise SchemaError(f"Unsupported format_version in {name}")
|
|
55
|
+
unknown = sorted(set(item) - _V1_KEYS)
|
|
56
|
+
if unknown:
|
|
57
|
+
raise SchemaError(f"Unknown top-level key in {name}: {', '.join(unknown)}")
|
|
58
|
+
return 1
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def load_revisions(project_dir: Path) -> list[Revision]:
|
|
62
|
+
root = project.require_init(project_dir)
|
|
63
|
+
unsorted: dict[str, Revision] = {}
|
|
64
|
+
violations: dict[str, list[str]] = {}
|
|
65
|
+
for path in sorted((root / "versions").glob("*.json")):
|
|
66
|
+
item, raw, file_rules = protocol.load_json(path, kind="revision", root=root)
|
|
67
|
+
if not isinstance(item, dict):
|
|
68
|
+
raise SchemaError(f"Invalid migration format: {path.name}")
|
|
69
|
+
version = _format_version(item, path.name)
|
|
70
|
+
if not all(k in item for k in _V0_KEYS):
|
|
71
|
+
raise SchemaError(f"Invalid migration format: {path.name}")
|
|
72
|
+
rid, parent, changes = item["revision"], item["down_revision"], item["changes"]
|
|
73
|
+
if not isinstance(rid, str) or not re.fullmatch(r"[a-f0-9]{12}", rid):
|
|
74
|
+
raise SchemaError(f"Invalid revision id in {path.name}")
|
|
75
|
+
if parent is not None and (not isinstance(parent, str) or not re.fullmatch(r"[a-f0-9]{12}", parent)):
|
|
76
|
+
raise SchemaError(f"Invalid down_revision in {path.name}")
|
|
77
|
+
if not isinstance(item["message"], str) or not isinstance(item["created_at"], str):
|
|
78
|
+
raise SchemaError(f"Invalid metadata in {path.name}")
|
|
79
|
+
if not isinstance(changes, dict) or not changes:
|
|
80
|
+
raise SchemaError(f"Migration must contain nonempty changes: {path.name}")
|
|
81
|
+
for name, change in changes.items():
|
|
82
|
+
if not isinstance(change, dict) or set(change) != {"before", "after"}:
|
|
83
|
+
raise SchemaError(f"Invalid change operation in {path.name}: {name}")
|
|
84
|
+
for field in ("before", "after"):
|
|
85
|
+
if change[field] is not None:
|
|
86
|
+
protocol.validate_config(name, change[field])
|
|
87
|
+
if rid in unsorted:
|
|
88
|
+
raise RevisionGraphError(f"Duplicate revision id: {rid}")
|
|
89
|
+
found = list(file_rules)
|
|
90
|
+
for name, change in changes.items():
|
|
91
|
+
if protocol.same(change["before"], change["after"]):
|
|
92
|
+
found.append(f"no-op-change {name}")
|
|
93
|
+
# Only after values: replay makes every before equal an earlier after, so each violation shows once.
|
|
94
|
+
if change["after"] is not None:
|
|
95
|
+
found.extend(protocol.config_violations(name, change["after"]))
|
|
96
|
+
violations[rid] = found
|
|
97
|
+
variants: frozenset[str] = frozenset()
|
|
98
|
+
if version == 0:
|
|
99
|
+
checksum = _hash(raw)
|
|
100
|
+
# CR/LF bytes (b"\r\n") are only ever whitespace in UTF-8 JSON. `json.loads` also auto-detects and
|
|
101
|
+
# accepts UTF-16/32, where a single code unit such as U+0D0A encodes as the same two bytes as a byte-
|
|
102
|
+
# level CR LF; replacing it would treat a real value change as a line-ending-only edit (Finding 1,
|
|
103
|
+
# 2026-11-13 final review). `raw.decode("utf-8")` alone is not a reliable test here: a mostly-ASCII
|
|
104
|
+
# UTF-16 file is full of null bytes, which are themselves valid (if meaningless) UTF-8, so it can
|
|
105
|
+
# decode without error even though `json.loads` did not read it as UTF-8. Ask the same question
|
|
106
|
+
# `json.loads` asks of these bytes (`json.detect_encoding`, the encoding-sniffing it uses for bytes
|
|
107
|
+
# input) instead, so "UTF-8" here means what it means to the loader, with or without a BOM.
|
|
108
|
+
if json.detect_encoding(raw) in ("utf-8", "utf-8-sig"):
|
|
109
|
+
variants = frozenset(line_ending_variants(raw))
|
|
110
|
+
else:
|
|
111
|
+
try:
|
|
112
|
+
checksum = _v1_checksum(item)
|
|
113
|
+
except UnicodeEncodeError as exc:
|
|
114
|
+
raise SchemaError(f"Invalid string in {path.name}: unpaired surrogate") from exc
|
|
115
|
+
unsorted[rid] = Revision(
|
|
116
|
+
rid, parent, item["message"], item["created_at"], changes, checksum, path, version, variants
|
|
117
|
+
)
|
|
118
|
+
|
|
119
|
+
if not unsorted:
|
|
120
|
+
return []
|
|
121
|
+
roots = [r for r in unsorted.values() if r.down_revision is None]
|
|
122
|
+
if len(roots) != 1:
|
|
123
|
+
raise RevisionGraphError("MVP requires exactly one root revision (linear history)")
|
|
124
|
+
children: dict[str, list[Revision]] = {}
|
|
125
|
+
for r in unsorted.values():
|
|
126
|
+
if r.down_revision is not None:
|
|
127
|
+
if r.down_revision not in unsorted:
|
|
128
|
+
raise RevisionGraphError(f"Missing parent of revision {r.revision}: {r.down_revision}")
|
|
129
|
+
children.setdefault(r.down_revision, []).append(r)
|
|
130
|
+
if any(len(kids) > 1 for kids in children.values()):
|
|
131
|
+
raise RevisionGraphError("Branching detected. MVP only supports one linear head; resolve in Git before deploying")
|
|
132
|
+
result: list[Revision] = []
|
|
133
|
+
current: Revision | None = roots[0]
|
|
134
|
+
while current is not None and current.revision not in {r.revision for r in result}:
|
|
135
|
+
result.append(current)
|
|
136
|
+
current = children.get(current.revision, [None])[0]
|
|
137
|
+
if len(result) != len(unsorted):
|
|
138
|
+
raise RevisionGraphError("Disconnected or cyclic migration history")
|
|
139
|
+
# Validate declarative preconditions across all revisions, independently of environments.
|
|
140
|
+
replay_revisions(result)
|
|
141
|
+
names: set[str] = set()
|
|
142
|
+
for r in result:
|
|
143
|
+
for name, change in r.changes.items():
|
|
144
|
+
if change["after"] is None:
|
|
145
|
+
names.discard(name)
|
|
146
|
+
else:
|
|
147
|
+
names.add(name)
|
|
148
|
+
found = violations[r.revision]
|
|
149
|
+
found.extend(f"case-collision {group}" for group in protocol.case_collisions(names)
|
|
150
|
+
if any(member in r.changes for member in group.split("/")))
|
|
151
|
+
for rule in found:
|
|
152
|
+
warnings.warn(_LEGACY.format(rid=r.revision, rule=rule), LegacyRevisionWarning, stacklevel=2)
|
|
153
|
+
return result
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
def _apply_changes(
|
|
157
|
+
state: dict[str, dict[str, Any]],
|
|
158
|
+
revision: Revision,
|
|
159
|
+
*,
|
|
160
|
+
backward: bool = False,
|
|
161
|
+
) -> None:
|
|
162
|
+
for name, change in revision.changes.items():
|
|
163
|
+
expected = change["after"] if backward else change["before"]
|
|
164
|
+
replacement = change["before"] if backward else change["after"]
|
|
165
|
+
if not protocol.same(state.get(name), expected):
|
|
166
|
+
direction = "downgrade" if backward else "upgrade"
|
|
167
|
+
raise MigrationConflictError(
|
|
168
|
+
f"{direction} {revision.revision}: unexpected current value for {name!r}; "
|
|
169
|
+
"possible drift or invalid revision dependency"
|
|
170
|
+
)
|
|
171
|
+
if replacement is None:
|
|
172
|
+
state.pop(name, None)
|
|
173
|
+
else:
|
|
174
|
+
state[name] = replacement
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
def replay_revisions(revisions: list[Revision]) -> dict[str, dict[str, Any]]:
|
|
178
|
+
state: dict[str, dict[str, Any]] = {}
|
|
179
|
+
for r in revisions:
|
|
180
|
+
_apply_changes(state, r)
|
|
181
|
+
return state
|