405 lines
15 KiB
Python
405 lines
15 KiB
Python
#!/usr/bin/env python3
|
|
"""Propagate a spec_lock.md value change to both the lock file and svg_output/*.svg.
|
|
|
|
Examples:
|
|
python3 update_spec.py <project_path> primary=#0066AA
|
|
python3 update_spec.py <project_path> colors.text=#111111
|
|
python3 update_spec.py <project_path> \\
|
|
typography.font_family='Arial, "Microsoft YaHei", sans-serif'
|
|
|
|
v2 scope:
|
|
- `colors.*` — HEX value replacement across svg_output/*.svg (case-insensitive match).
|
|
- `typography.font_family` — replaces the inner value of every `font-family="..."`
|
|
/ `font-family='...'` attribute in svg_output/*.svg. This is a global replace:
|
|
every text element becomes the new family, regardless of role, and every
|
|
existing `typography.*_family` lock row is updated to the same value.
|
|
|
|
Bare `key=value` (no dot) is treated as `colors.key=value` for backward compat.
|
|
|
|
Other keys as independent targets (typography sizes, per-role
|
|
`typography.*_family` overrides, icons, images, canvas, forbidden) are
|
|
intentionally NOT supported — they involve attribute-scoped or semantic
|
|
replacements whose risk/benefit does not warrant bulk propagation. For
|
|
per-role family changes, edit spec_lock.md and re-author the affected pages.
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
import argparse
|
|
import os
|
|
import re
|
|
import shutil
|
|
import sys
|
|
import tempfile
|
|
from pathlib import Path
|
|
|
|
from console_encoding import configure_utf8_stdio
|
|
from project_management.project_specs import parse_spec_lock as parse_lock
|
|
|
|
configure_utf8_stdio()
|
|
|
|
HEX_RE = re.compile(r"^#(?:[0-9A-Fa-f]{3,4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$")
|
|
FONT_FAMILY_RE = re.compile(r"""(font-family\s*=\s*)(["'])(.*?)\2""")
|
|
|
|
|
|
def plan_lock_values(
|
|
lock_path: Path, section: str, updates: dict[str, str]
|
|
) -> str:
|
|
"""Return a lock rewrite only after every target row validates."""
|
|
lines = lock_path.read_text(encoding="utf-8").splitlines(keepends=True)
|
|
in_section = False
|
|
found: set[str] = set()
|
|
for i, raw in enumerate(lines):
|
|
stripped = raw.rstrip("\r\n")
|
|
line_ending = raw[len(stripped) :]
|
|
if stripped.startswith("## "):
|
|
in_section = stripped[3:].strip() == section
|
|
continue
|
|
if not in_section:
|
|
continue
|
|
m = re.match(r"^(-\s+)([A-Za-z0-9_]+)(\s*:\s*)(.+?)(\s*)$", stripped)
|
|
if not m or m.group(2) not in updates:
|
|
continue
|
|
key = m.group(2)
|
|
if key in found:
|
|
raise ValueError(
|
|
f"duplicate key {key!r} under section {section!r} in {lock_path}"
|
|
)
|
|
found.add(key)
|
|
lines[i] = (
|
|
f"{m.group(1)}{key}{m.group(3)}{updates[key]}{m.group(5)}"
|
|
f"{line_ending}"
|
|
)
|
|
|
|
missing = set(updates) - found
|
|
if missing:
|
|
missing_list = ", ".join(sorted(missing))
|
|
raise KeyError(
|
|
f"key(s) {missing_list} not found under section {section!r} in {lock_path}"
|
|
)
|
|
return "".join(lines)
|
|
|
|
|
|
def _plan_color_updates(
|
|
svg_dir: Path,
|
|
old_hex: str,
|
|
new_hex: str,
|
|
) -> list[tuple[Path, str, int]]:
|
|
"""Return planned color rewrites without touching the SVG files."""
|
|
if not HEX_RE.match(old_hex) or not HEX_RE.match(new_hex):
|
|
raise ValueError(f"not a HEX color: old={old_hex!r} new={new_hex!r}")
|
|
pattern = re.compile(
|
|
rf"{re.escape(old_hex)}(?![0-9A-Fa-f])",
|
|
re.IGNORECASE,
|
|
)
|
|
planned: list[tuple[Path, str, int]] = []
|
|
for svg in sorted(svg_dir.glob("*.svg")):
|
|
text = svg.read_text(encoding="utf-8")
|
|
new_text, count = pattern.subn(new_hex, text)
|
|
if count > 0:
|
|
planned.append((svg, new_text, count))
|
|
return planned
|
|
|
|
|
|
def _plan_font_family_updates(
|
|
svg_dir: Path,
|
|
new_value: str,
|
|
) -> list[tuple[Path, str, int]]:
|
|
"""Return planned font-family rewrites without touching the SVG files."""
|
|
|
|
def replace_value(match: re.Match[str]) -> str:
|
|
prefix, quote, _inner = match.group(1), match.group(2), match.group(3)
|
|
outer = quote
|
|
if outer in new_value:
|
|
outer = "'" if quote == '"' else '"'
|
|
if outer in new_value:
|
|
raise ValueError(
|
|
f"new font_family value contains both ' and \" — cannot embed: "
|
|
f"{new_value!r}"
|
|
)
|
|
return f"{prefix}{outer}{new_value}{outer}"
|
|
|
|
planned: list[tuple[Path, str, int]] = []
|
|
for svg in sorted(svg_dir.glob("*.svg")):
|
|
text = svg.read_text(encoding="utf-8")
|
|
new_text, count = FONT_FAMILY_RE.subn(replace_value, text)
|
|
if count > 0 and new_text != text:
|
|
planned.append((svg, new_text, count))
|
|
return planned
|
|
|
|
|
|
def _publish_text_updates(updates: list[tuple[Path, str]]) -> None:
|
|
"""Publish existing text files as one rollback unit."""
|
|
if not updates:
|
|
return
|
|
targets = [path for path, _text in updates]
|
|
if len(targets) != len(set(targets)):
|
|
raise ValueError("transaction contains duplicate output paths")
|
|
for target in targets:
|
|
if not target.is_file() or target.is_symlink():
|
|
raise OSError(f"transaction target must be a regular file: {target}")
|
|
|
|
transaction_dir = Path(
|
|
tempfile.mkdtemp(
|
|
prefix=".update-spec-",
|
|
dir=targets[0].parent,
|
|
)
|
|
)
|
|
staged_dir = transaction_dir / "staged"
|
|
backup_dir = transaction_dir / "previous"
|
|
preserve_transaction = False
|
|
published: list[tuple[Path, Path]] = []
|
|
try:
|
|
staged_dir.mkdir()
|
|
backup_dir.mkdir()
|
|
staged: list[tuple[Path, Path, Path]] = []
|
|
transaction_device = transaction_dir.stat().st_dev
|
|
for index, (target, text) in enumerate(updates):
|
|
if target.parent.stat().st_dev != transaction_device:
|
|
raise OSError(
|
|
f"cannot atomically publish across filesystems: {target}"
|
|
)
|
|
staged_path = staged_dir / f"{index:06d}.new"
|
|
backup_path = backup_dir / f"{index:06d}.bak"
|
|
staged_path.write_text(text, encoding="utf-8")
|
|
shutil.copymode(target, staged_path)
|
|
shutil.copy2(target, backup_path, follow_symlinks=False)
|
|
staged.append((target, staged_path, backup_path))
|
|
|
|
try:
|
|
for target, staged_path, backup_path in staged:
|
|
os.replace(staged_path, target)
|
|
published.append((target, backup_path))
|
|
except BaseException as publish_error:
|
|
rollback_errors: list[str] = []
|
|
for target, backup_path in reversed(published):
|
|
try:
|
|
os.replace(backup_path, target)
|
|
except BaseException as rollback_error:
|
|
rollback_errors.append(
|
|
f"could not restore {target}: "
|
|
f"{type(rollback_error).__name__}: {rollback_error}"
|
|
)
|
|
if rollback_errors:
|
|
preserve_transaction = True
|
|
raise RuntimeError(
|
|
f"update_spec publish failed ({publish_error}); rollback was "
|
|
f"incomplete: {'; '.join(rollback_errors)}; recovery directory: "
|
|
f"{transaction_dir}"
|
|
) from publish_error
|
|
raise
|
|
finally:
|
|
if not preserve_transaction:
|
|
shutil.rmtree(transaction_dir, ignore_errors=True)
|
|
|
|
|
|
def replace_color_in_svgs(
|
|
svg_dir: Path, old_hex: str, new_hex: str, *, dry_run: bool = False
|
|
) -> list[tuple[Path, int]]:
|
|
"""Replace old_hex with new_hex in every .svg under svg_dir.
|
|
|
|
Returns a list of (path, replacement_count) for each changed file. The
|
|
count comes straight from re.subn so callers can spot anomalies —
|
|
e.g. one file with 50 hits when the rest have 4-8 is likely a stray
|
|
HEX literal inside <text> content rather than a styling attribute.
|
|
|
|
Two-phase: plan all file updates in memory, then publish them with rollback.
|
|
If planning or publishing fails, the original files are retained.
|
|
|
|
When dry_run=True, the planning phase still runs (so bad HEX still raises
|
|
and callers see which files would change), but no disk writes happen. The
|
|
returned list describes the would-change files.
|
|
"""
|
|
planned = _plan_color_updates(svg_dir, old_hex, new_hex)
|
|
if not dry_run:
|
|
_publish_text_updates([
|
|
(svg, new_text)
|
|
for svg, new_text, _count in planned
|
|
])
|
|
return [(path, count) for path, _text, count in planned]
|
|
|
|
|
|
def replace_font_family_in_svgs(
|
|
svg_dir: Path, new_value: str, *, dry_run: bool = False
|
|
) -> list[tuple[Path, int]]:
|
|
"""Replace the inner value of every `font-family="..."` / `font-family='...'`
|
|
attribute in every .svg under svg_dir.
|
|
|
|
Returns a list of (path, replacement_count) for each changed file.
|
|
|
|
Preserves the outer quote character when possible; if the new value contains
|
|
that same quote type, switches the outer quote to the other kind.
|
|
|
|
Two-phase: plan all file updates in memory, then publish them with rollback.
|
|
A conflicting quote style fails during planning, before files are touched.
|
|
|
|
When dry_run=True, the planning phase still runs (so the ValueError still
|
|
fires and callers see which files would change), but no disk writes happen.
|
|
The returned list describes the would-change files.
|
|
"""
|
|
planned = _plan_font_family_updates(svg_dir, new_value)
|
|
if not dry_run:
|
|
_publish_text_updates([
|
|
(svg, new_text)
|
|
for svg, new_text, _count in planned
|
|
])
|
|
return [(path, count) for path, _text, count in planned]
|
|
|
|
|
|
def main() -> int:
|
|
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
|
|
ap.add_argument("project_path", type=Path, help="project folder containing spec_lock.md and svg_output/")
|
|
ap.add_argument(
|
|
"assignment",
|
|
help=(
|
|
"section.key=value (e.g. colors.primary=#0066AA, "
|
|
"typography.font_family='Arial, \"Microsoft YaHei\", sans-serif'). "
|
|
"Bare key=value is treated as colors.key=value."
|
|
),
|
|
)
|
|
ap.add_argument(
|
|
"--dry-run",
|
|
"-n",
|
|
action="store_true",
|
|
help="preview which SVGs would change; do not write anything to disk.",
|
|
)
|
|
args = ap.parse_args()
|
|
|
|
project = args.project_path.resolve()
|
|
lock = project / "spec_lock.md"
|
|
svg_dir = project / "svg_output"
|
|
|
|
if not lock.exists():
|
|
print(f"error: spec_lock.md not found at {lock}", file=sys.stderr)
|
|
return 2
|
|
if not svg_dir.exists():
|
|
print(f"error: svg_output/ not found at {svg_dir}", file=sys.stderr)
|
|
return 2
|
|
|
|
if "=" not in args.assignment:
|
|
print("error: assignment must be [section.]key=value", file=sys.stderr)
|
|
return 2
|
|
lhs, new_value = args.assignment.split("=", 1)
|
|
lhs = lhs.strip()
|
|
new_value = new_value.strip()
|
|
if "." in lhs:
|
|
section, key = lhs.split(".", 1)
|
|
section = section.strip()
|
|
key = key.strip()
|
|
else:
|
|
section, key = "colors", lhs
|
|
|
|
sections = parse_lock(lock)
|
|
section_map = sections.get(section, {})
|
|
if key not in section_map:
|
|
known = {s: sorted(v) for s, v in sections.items()}
|
|
print(
|
|
f"error: {key!r} not found under `## {section}` in spec_lock.md.\n"
|
|
f"known keys: {known}",
|
|
file=sys.stderr,
|
|
)
|
|
return 2
|
|
|
|
old_value = section_map[key]
|
|
lock_changes: list[tuple[str, str, str]] = []
|
|
|
|
if section == "colors":
|
|
if not HEX_RE.match(new_value):
|
|
print(f"error: new value for colors.{key} must be a HEX color (got {new_value!r})", file=sys.stderr)
|
|
return 2
|
|
if old_value == new_value:
|
|
print(f"no change: colors.{key} already = {new_value}")
|
|
return 0
|
|
try:
|
|
planned_lock = plan_lock_values(lock, "colors", {key: new_value})
|
|
except (KeyError, ValueError) as exc:
|
|
print(f"error: {exc}", file=sys.stderr)
|
|
return 2
|
|
planned_svg = _plan_color_updates(svg_dir, old_value, new_value)
|
|
changed = [
|
|
(path, count)
|
|
for path, _text, count in planned_svg
|
|
]
|
|
lock_changes = [(key, old_value, new_value)]
|
|
if not args.dry_run:
|
|
try:
|
|
_publish_text_updates([
|
|
*(
|
|
(path, new_text)
|
|
for path, new_text, _count in planned_svg
|
|
),
|
|
(lock, planned_lock),
|
|
])
|
|
except (OSError, RuntimeError, ValueError) as exc:
|
|
print(f"error: update was not published: {exc}", file=sys.stderr)
|
|
return 2
|
|
elif section == "typography" and key == "font_family":
|
|
family_keys = [
|
|
name
|
|
for name in section_map
|
|
if name == "font_family" or name.endswith("_family")
|
|
]
|
|
lock_changes = [
|
|
(name, section_map[name], new_value)
|
|
for name in family_keys
|
|
if section_map[name] != new_value
|
|
]
|
|
if not lock_changes:
|
|
print(f"no change: all typography.*_family rows already = {new_value}")
|
|
return 0
|
|
try:
|
|
planned_lock = plan_lock_values(
|
|
lock,
|
|
"typography",
|
|
{name: new_value for name in family_keys},
|
|
)
|
|
planned_svg = _plan_font_family_updates(svg_dir, new_value)
|
|
changed = [
|
|
(path, count)
|
|
for path, _text, count in planned_svg
|
|
]
|
|
except (KeyError, ValueError) as e:
|
|
print(f"error: {e}", file=sys.stderr)
|
|
return 2
|
|
if not args.dry_run:
|
|
try:
|
|
_publish_text_updates([
|
|
*(
|
|
(path, new_text)
|
|
for path, new_text, _count in planned_svg
|
|
),
|
|
(lock, planned_lock),
|
|
])
|
|
except (OSError, RuntimeError, ValueError) as exc:
|
|
print(f"error: update was not published: {exc}", file=sys.stderr)
|
|
return 2
|
|
else:
|
|
print(
|
|
f"error: {section}.{key} is not supported by update_spec.py.\n"
|
|
f"v2 supports: colors.* (HEX), typography.font_family.\n"
|
|
f"Edit spec_lock.md and the affected SVGs by hand for other changes.",
|
|
file=sys.stderr,
|
|
)
|
|
return 2
|
|
|
|
if args.dry_run:
|
|
for lock_key, previous, replacement in lock_changes:
|
|
print(
|
|
f"[dry-run] spec_lock.md: "
|
|
f"{section}.{lock_key} {previous} → {replacement}"
|
|
)
|
|
print(f"[dry-run] svg_output/: {len(changed)} file(s) would be updated")
|
|
else:
|
|
for lock_key, previous, replacement in lock_changes:
|
|
print(
|
|
f"spec_lock.md: {section}.{lock_key} {previous} → {replacement}"
|
|
)
|
|
print(f"svg_output/: {len(changed)} file(s) updated")
|
|
for p, n in changed:
|
|
suffix = "replacement" if n == 1 else "replacements"
|
|
print(f" - {p.name} ({n} {suffix})")
|
|
return 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
sys.exit(main())
|