template_press 3.2.0__tar.gz → 3.3.0__tar.gz

{template_press-3.2.0 → template_press-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: template_press
-Version: 3.2.0
+Version: 3.3.0
 Summary: Standalone rebrand utility — press a new identity onto an external target repo
 Author: Steve Morin
 Author-email: Steve Morin <steve.morin@gmail.com>

{template_press-3.2.0 → template_press-3.3.0}/pyproject.toml

@@ -20,7 +20,7 @@
 [project]
 name = "template_press"
 # ITM-070 — static version (ADR-06 cutover). release-please bumps this.
-version = "3.2.0"
+version = "3.3.0"
 description = "Standalone rebrand utility — press a new identity onto an external target repo"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -216,10 +216,12 @@ strict_markers = true
 [tool.codespell]
 skip = ".git,.venv,build,dist,node_modules,uv.lock,bun.lock,*.lock,docs/_build,*.svg,*.cast,.ruff_cache,.pytest_cache,.mypy_cache,.ty_cache,*.log"
 # *.log: raw run output, not prose.
-ignore-words-list = "ans,porjects"
+ignore-words-list = "ans,porjects,replcae"
 # ans: variable name used in prompt-handling code; codespell wants to "fix"
 # it to "and". Whitelist to keep the short variable name.
 # porjects: intentional typo — the did-you-mean example in cli/groups.py and
 # its test ("press porjects" must suggest "projects").
+# replcae: intentional typo — the unknown-root-key regression test/message
+# for `[[replcae]]` (rules.py F5a).
 check-filenames = true
 check-hidden = false

{template_press-3.2.0 → template_press-3.3.0}/src/template_press/rebrand/cli.py

@@ -27,9 +27,16 @@ from template_press.rebrand.engine import (
     ApplyReport,
     apply,
     build_plan,
+    rendered_replace_rules,
     stray_press_dirs,
 )
-from template_press.rebrand.identity import Identity, ValidationError, token_occurs
+from template_press.rebrand.identity import (
+    DISPLAY_FORM_NAMES,
+    Identity,
+    ValidationError,
+    display_forms,
+    token_occurs,
+)
 from template_press.rebrand.receipt import read_receipt, write_receipt
 from template_press.rebrand.rules import DEFAULT_RULES, Rules, load_rules
 from template_press.rebrand.safety import (
@@ -130,7 +137,31 @@ def _resolve_source(
     return source, write_pending
 
 
-def _collisions(source: Identity, dest: Identity) -> list[str]:
+def _expand_display_forms(values: dict[str, str]) -> dict[str, str]:
+    """Replace a raw ``display_name`` entry with its per-form expansions.
+
+    Mirrors ``replacement_pairs``' display-form handling (engine.py):
+    runtime pair tags are ``display_name_spaced/pascal/camel``, never bare
+    ``display_name``, so comparing raw dict values alone can miss a derived
+    form that embeds a changed source token. Uses the full
+    ``DISPLAY_FORM_NAMES`` set (not a rules-configured subset) — a subset
+    only narrows what gets REWRITTEN; this preflight stays conservative and
+    checks every form regardless.
+    """
+    if "display_name" not in values:
+        return values
+    expanded = {k: v for k, v in values.items() if k != "display_name"}
+    forms = display_forms(values["display_name"])
+    for form in DISPLAY_FORM_NAMES:
+        expanded[f"display_name_{form}"] = forms[form]
+    return expanded
+
+
+def _collisions(
+    source: Identity,
+    dest: Identity,
+    substring_fields: frozenset[str] = frozenset(),
+) -> list[str]:
     """Destination values that embed a CHANGED source token.
 
     Sequential substitution would re-rewrite such output (old app name
@@ -138,13 +169,34 @@ def _collisions(source: Identity, dest: Identity) -> list[str]:
     would flag correct output as a leak (press → press_two). Refusing up
     front with guidance beats either silent corruption or a permanent
     verification failure.
+
+    Both identities are expanded the same way ``replacement_pairs`` expands
+    them (Fix F3): a raw ``display_name`` entry is replaced by its exact
+    per-form values, so a destination display name whose DERIVED form (e.g.
+    the camel form of "Plbp" is "plbp") embeds a changed source token is
+    caught even though the raw display name never contains it verbatim.
+
+    ``substring_fields`` (Fix F4) — the target's ``[rules]
+    substring_rewrite_fields`` — mirrors what the engine will actually do to
+    a changed field opted into substring mode: it rewrites that field
+    SUBSTRING-wide, with no word-boundary guard, so a destination value that
+    embeds the source token WITHOUT a boundary (e.g. dest repo_name
+    "myfoo-tools" embedding source app_name "foo") is just as much a
+    collision as a boundary-guarded one — checked via plain ``in`` instead of
+    the boundary-guarded ``token_occurs``.
     """
     out: list[str] = []
-    src, dst = source.as_dict(), dest.as_dict()
-    changed = {f: v for f, v in src.items() if v != dst[f]}
+    src = _expand_display_forms(source.as_dict())
+    dst = _expand_display_forms(dest.as_dict())
+    changed = {f: v for f, v in src.items() if v != dst.get(f)}
     for dest_field, dest_value in dst.items():
         for src_field, src_value in changed.items():
-            if token_occurs(dest_value, src_field, src_value):
+            hit = (
+                src_value in dest_value
+                if src_field in substring_fields
+                else token_occurs(dest_value, src_field, src_value)
+            )
+            if hit:
                 out.append(
                     f"destination {dest_field}={dest_value!r} contains the "
                     f"source {src_field} token {src_value!r}"
@@ -152,6 +204,24 @@ def _collisions(source: Identity, dest: Identity) -> list[str]:
     return out
 
 
+def display_name_problem(source: Identity, dest: Identity) -> str | None:
+    """Half-specified display identity is refused (codesign sec-06).
+
+    The press knows what to erase but not what to write — proceeding would
+    ship a half-rebrand where every prose mention keeps the old product
+    name. The reverse direction is harmless: nothing to rewrite, and the
+    post-apply source-config write records the new display name.
+    """
+    if source.display_name is not None and dest.display_name is None:
+        return (
+            f"source-config declares display_name "
+            f"({source.display_name!r}) but the answers file does not — "
+            f"add display_name to [answers]; press cannot know the new "
+            f"display name"
+        )
+    return None
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="press rebrand", description=__doc__)
     parser.add_argument("--target", type=Path, required=True)
@@ -186,11 +256,23 @@ def main(argv: list[str] | None = None) -> int:
             return _fail("--config ANSWERS.toml is required")
         dest = load_answers(args.config)
 
+        display_problem = display_name_problem(source, dest)
+        if display_problem is not None:
+            return _fail(display_problem)
+
         if source == dest:
             return _fail(
                 "source and destination identities are identical — nothing to press"
             )
-        collisions = _collisions(source, dest)
+        # Loaded before the collision preflight (Fix F4): substring_rewrite_fields
+        # changes what counts as a collision (a boundary-free embedded token is
+        # only a problem for a field the engine will actually rewrite
+        # substring-wide) — pure reading, no side effect, so moving it earlier
+        # is safe.
+        rules = load_rules(target)
+        collisions = _collisions(
+            source, dest, substring_fields=rules.substring_rewrite_fields
+        )
         if collisions:
             print(
                 "error: destination identity embeds source tokens — a single "
@@ -202,7 +284,6 @@ def main(argv: list[str] | None = None) -> int:
                 print(f"  {c}", file=sys.stderr)
             return 2
 
-        rules = load_rules(target)
         plan = build_plan(target, source, dest, rules)
         print(plan.render())
         strays = stray_press_dirs(target)
@@ -322,7 +403,16 @@ def _press(
             regenerate=rules.regenerate,
             verify_ignore=rules.verify_ignore,
         )
-        leaks = find_leaks(target, source, doctor_rules, dest=dest)
+        leaks = find_leaks(
+            target,
+            source,
+            doctor_rules,
+            dest=dest,
+            display_form_names=rules.display_forms,
+            substring_fields=rules.substring_rewrite_fields,
+            rendered_rules=rendered_replace_rules(rules, source, dest),
+            renamed=report.renamed,
+        )
         if leaks:
             print(render_leak_report(leaks), file=sys.stderr)
             print(report.render(), file=sys.stderr)

{template_press-3.2.0 → template_press-3.3.0}/src/template_press/rebrand/config.py

@@ -12,7 +12,12 @@ import tomllib
 from pathlib import Path
 
 from template_press.rebrand.engine import ROOT_CONTROL
-from template_press.rebrand.identity import Identity, ValidationError
+from template_press.rebrand.identity import (
+    OPTIONAL_FIELDS,
+    REQUIRED_FIELDS,
+    Identity,
+    ValidationError,
+)
 from template_press.rebrand.safety import ContainmentError, assert_under_root
 
 SOURCE_CONFIG_REL = Path("press") / "press-source.toml"
@@ -64,6 +69,22 @@ def load_identity_toml(path: Path, table: str) -> Identity:
     section = data.get(table)
     if not isinstance(section, dict):
         raise ValidationError(f"{path}: missing [{table}] table")
+    # F3: an unknown key (typo'd optional field, e.g. `display_nam`) must
+    # fail loud — the dict-comprehension below silently drops any key it
+    # doesn't recognize, so a typo would otherwise pass through as if the
+    # field were simply absent, and press proceeds none the wiser.
+    known = frozenset(REQUIRED_FIELDS) | frozenset(OPTIONAL_FIELDS)
+    unknown = set(section) - known
+    if unknown:
+        raise ValidationError(
+            f"{path}: [{table}] unknown key(s): {', '.join(sorted(unknown))}"
+        )
+    for key in (*REQUIRED_FIELDS, *OPTIONAL_FIELDS):
+        if key in section and not isinstance(section[key], str):
+            raise ValidationError(
+                f"{path}: [{table}] {key} must be a string, got "
+                f"{type(section[key]).__name__}"
+            )
     identity = Identity.from_mapping(
         {k: v for k, v in section.items() if isinstance(v, str)}
     )

template_press-3.3.0/src/template_press/rebrand/doctor.py

@@ -0,0 +1,336 @@
+"""No-leak verification: the gate between apply() and the receipt (EMP-01).
+
+A rebrand that leaves ANY source-identity token behind — in file content or
+in a path name — is a failed rebrand. The CLI must exit non-zero and write
+no receipt. Port of init_doctor.check_no_identity_leftover, generalized to
+(target, identity, rules) and extended with path-name checking.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Collection
+from dataclasses import dataclass
+from pathlib import Path
+
+from template_press.rebrand.engine import (
+    ROOT_CONTROL,
+    _git_listed,
+    _gitlink_rels,
+    _is_excluded,
+    _is_root_press,
+    iter_target_files,
+    symlink_target_posix,
+)
+from template_press.rebrand.identity import (
+    DISPLAY_FORM_NAMES,
+    Identity,
+    display_forms,
+    occurs,
+)
+from template_press.rebrand.rules import ReplaceRule, Rules, rule_matches_path
+
+PATH_FIELDS: tuple[str, ...] = (
+    "package_name",
+    "repo_name",
+    "app_name",
+    "app_name_upper",
+)
+
+
+@dataclass(frozen=True)
+class Leak:
+    path: str
+    field: str
+    value: str
+    where: str  # "content" | "path" | "symlink" | "unverifiable"
+
+
+def _read_for_scan(path: Path) -> str | None:
+    """Content for scanning; None for binary/symlink; OSError propagates.
+
+    Unlike the engine's lenient reader, the doctor must NOT silently skip an
+    unreadable file — a file it cannot scan is a file it cannot certify.
+    """
+    if path.is_symlink():
+        return None  # content lives outside the target; the name is scanned
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return None  # binary: the rewrite pass cannot alter it either
+
+
+def _reverse_renamed_posix(posix: str, renamed: list[tuple[str, str]]) -> str:
+    """Undo every prefix rename recorded in ``renamed`` (new -> old), longest
+    new-prefix first, applied iteratively until no further substitution
+    fires (Fix F1).
+
+    A rename entry's NEW prefix substitutes back to its OLD prefix when
+    ``posix`` equals it exactly or starts with it plus ``"/"`` — mirroring
+    how ``_rename_pass_once``/``build_plan`` record ``(old_prefix,
+    new_prefix)`` collapsed to the shallowest differing ancestor per pass. A
+    path may have crossed several such ancestors across SEPARATE passes, so
+    this keeps substituting (bounded to ``len(renamed) + 1`` rounds — more
+    than enough for any chain of disjoint renames) rather than doing it once.
+    """
+    ordered = sorted(renamed, key=lambda pair: -len(pair[1]))
+    for _ in range(len(ordered) + 1):
+        for old, new in ordered:
+            if posix == new:
+                posix = old
+                break
+            if posix.startswith(new + "/"):
+                posix = old + posix[len(new) :]
+                break
+        else:
+            break
+    return posix
+
+
+def _rule_scope_hits(
+    rule: ReplaceRule, posix: str, renamed: list[tuple[str, str]]
+) -> bool:
+    """Rule-literal scope match against BOTH the CURRENT path and its
+    PRE-rename original (Fix F1).
+
+    A token-rename pass can move a file's ancestor out from under a
+    ``files`` scope written against the source layout before the SAME
+    [[replace]] rule ever gets a chance to re-evaluate against it (the
+    rewrite-side scope migration is a documented 0008 limitation, left
+    unfixed there) — so scoping the doctor's rule-literal scan against the
+    current path alone would silently certify the missed rename. Over-flags
+    rather than misses: a hit on EITHER path counts.
+    """
+    return rule_matches_path(rule, posix) or rule_matches_path(
+        rule, _reverse_renamed_posix(posix, renamed)
+    )
+
+
+def find_leaks(
+    target: Path,
+    source: Identity,
+    rules: Rules,
+    dest: Identity | None = None,
+    display_form_names: tuple[str, ...] = DISPLAY_FORM_NAMES,
+    substring_fields: Collection[str] = frozenset(),
+    rendered_rules: list[tuple[ReplaceRule, str, str]] | None = None,
+    renamed: list[tuple[str, str]] | None = None,
+) -> list[Leak]:
+    """Scan for surviving source-identity tokens.
+
+    When ``dest`` is given, only fields that actually CHANGED are scanned:
+    an unchanged field (same author across a rename) is not a leak — its
+    token legitimately remains everywhere. Without ``dest`` all fields are
+    scanned (full-rebrand semantics).
+
+    ``rendered_rules`` (rule, FROM, TO) triples from
+    ``engine.rendered_replace_rules`` — when a ``[[replace]]`` rule is the
+    ONLY matcher for a boundary-unmatched rendered form (e.g. an
+    underscore-glued ``_{app_name}_owned``), the ordinary field-based token
+    scan can miss a surviving FROM literal entirely (a containment-skipped
+    symlink retarget, or any other rewrite the engine could not perform).
+    Each rule is scanned scoped by what it was supposed to touch:
+    ``rule.content`` against file CONTENT (glob-scoped via
+    ``rule_matches_path`` against the file's own rel posix), and
+    ``rule.paths`` against PATH COMPONENTS (glob-scoped the same way,
+    mirroring ``_renamed_rel``) and SYMLINK text (scoped against the link
+    TARGET's normalized rel path, mirroring ``_retarget_symlinks``).
+
+    ``renamed`` (Fix F1) — ``ApplyReport.renamed`` (old_prefix, new_prefix)
+    pairs from every rename ``apply()`` actually executed — lets each
+    rule-literal scope check (``_rule_scope_hits``) recover a scanned
+    path/symlink-target's PRE-rename original before testing ``rule.files``:
+    a token-rename pass can move a rule-scoped path's ancestor out from under
+    its own ``files`` glob before that same rule ever gets to re-evaluate
+    against it, leaving a stale FROM literal that a current-path-only scope
+    check would miss entirely (a receipt/verify contradiction). Omitted
+    (``None``/empty), this degrades to the prior current-path-only behavior.
+
+    A third, GITLINK pass (Fix F2) scans every submodule index entry's PATH
+    COMPONENTS the same way — ``_gitlink_rels`` reads the index directly, so
+    an uninitialized/uncheckoutable submodule is still covered. Neither of
+    the two passes above ever reaches a gitlink: pass 1 filters on
+    ``Path.is_file()`` and pass 2 on ``Path.is_symlink()``, both False for a
+    submodule mount point with no working-tree materialization.
+    """
+    rendered_rules = rendered_rules or []
+    renamed = renamed or []
+    leaks: list[Leak] = []
+    fields = source.as_dict()
+    if "display_name" in fields:
+        # Expand into the exact per-form values so a surviving glued form
+        # (PyLaunchBlueprint) is a leak, not just the spaced original.
+        sf = display_forms(fields.pop("display_name"))
+        for form in display_form_names:
+            fields[f"display_name_{form}"] = sf[form]
+    if dest is not None:
+        dest_fields = dest.as_dict()
+        if "display_name" in dest_fields:
+            df = display_forms(dest_fields.pop("display_name"))
+            for form in display_form_names:
+                dest_fields[f"display_name_{form}"] = df[form]
+        fields = {k: v for k, v in fields.items() if dest_fields.get(k) != v}
+    # Path-component scans must cover display-form fields too (Fix 2): the
+    # doctor already expands display_name into its exact forms for the
+    # content/symlink scans above, but a leftover PyLaunchBlueprint/ dir
+    # would otherwise pass the path-component loops below, which iterated
+    # PATH_FIELDS only.
+    path_fields = (
+        *PATH_FIELDS,
+        *(f"display_name_{form}" for form in display_form_names),
+    )
+    covered_symlinks: set[str] = set()
+    for path in iter_target_files(target, rules):
+        rel = path.relative_to(target)
+        rel_posix = rel.as_posix()
+        try:
+            text = _read_for_scan(path)
+        except OSError:
+            leaks.append(Leak(rel_posix, "io", "unreadable", "unverifiable"))
+            text = None
+        if text is not None:
+            for field_name, value in fields.items():
+                if occurs(text, field_name, value, substring_fields):
+                    leaks.append(Leak(rel_posix, field_name, value, "content"))
+            for rule, frm, _to in rendered_rules:
+                if (
+                    rule.content
+                    and _rule_scope_hits(rule, rel_posix, renamed)
+                    and frm in text
+                ):
+                    leaks.append(Leak(rel_posix, "replace_rule", frm, "content"))
+        if path.is_symlink():
+            # A symlink's bytes are its target string, not file content — an
+            # identity token embedded there would dangle/leak in a pressed fork.
+            covered_symlinks.add(rel_posix)
+            link = os.readlink(path)
+            for field_name, value in fields.items():
+                if occurs(link, field_name, value, substring_fields):
+                    leaks.append(Leak(rel_posix, field_name, value, "symlink"))
+            # Rule scope for symlink text is the link's TARGET, normalized —
+            # mirroring _retarget_symlinks — never the link's own location.
+            link_target_posix = symlink_target_posix(rel, link)
+            for rule, frm, _to in rendered_rules:
+                if (
+                    rule.paths
+                    and _rule_scope_hits(rule, link_target_posix, renamed)
+                    and frm in link
+                ):
+                    leaks.append(Leak(rel_posix, "replace_rule", frm, "symlink"))
+        path_rules = [
+            (rule, frm)
+            for rule, frm, _to in rendered_rules
+            if rule.paths and _rule_scope_hits(rule, rel_posix, renamed)
+        ]
+        for i, component in enumerate(rel.parts):
+            if _is_root_press(rel, i):
+                continue
+            for field_name in path_fields:
+                value = fields.get(field_name)
+                if value is not None and occurs(
+                    component, field_name, value, substring_fields
+                ):
+                    leaks.append(Leak(rel_posix, field_name, value, "path"))
+            for _rule, frm in path_rules:
+                if frm in component:
+                    leaks.append(Leak(rel_posix, "replace_rule", frm, "path"))
+    # DIRECTORY and DANGLING symlinks never reach the loop above:
+    # `iter_target_files` keeps only `is_file()` paths, and `is_file()` FOLLOWS
+    # the link — so a symlink to a dir (or to nothing) is dropped, and a source
+    # token embedded in its link string would slip the gate. Scan every
+    # git-listed symlink's `readlink` STRING here (never the destination),
+    # deduping the symlink-to-file links the loop already covered.
+    for rel in _git_listed(target):
+        rel_posix = rel.as_posix()
+        if rel_posix in covered_symlinks:
+            continue
+        path = target / rel
+        if not path.is_symlink():
+            continue
+        # The NAME of a dir/dangling symlink is never scanned by the main loop
+        # (iter_target_files drops non-is_file paths), so scan its path
+        # components here exactly as Pass 1 does — a source token in the link's
+        # OWN name would otherwise slip the gate. (symlink-to-file names are
+        # already covered above via covered_symlinks.)
+        path_rules = [
+            (rule, frm)
+            for rule, frm, _to in rendered_rules
+            if rule.paths and _rule_scope_hits(rule, rel_posix, renamed)
+        ]
+        for i, component in enumerate(rel.parts):
+            if _is_root_press(rel, i):
+                continue
+            for field_name in path_fields:
+                value = fields.get(field_name)
+                if value is not None and occurs(
+                    component, field_name, value, substring_fields
+                ):
+                    leaks.append(Leak(rel_posix, field_name, value, "path"))
+            for _rule, frm in path_rules:
+                if frm in component:
+                    leaks.append(Leak(rel_posix, "replace_rule", frm, "path"))
+        try:
+            link = os.readlink(path)
+        except OSError:
+            leaks.append(Leak(rel_posix, "io", "unreadable", "unverifiable"))
+            continue
+        for field_name, value in fields.items():
+            if occurs(link, field_name, value, substring_fields):
+                leaks.append(Leak(rel_posix, field_name, value, "symlink"))
+        link_target_posix = symlink_target_posix(rel, link)
+        for rule, frm, _to in rendered_rules:
+            if (
+                rule.paths
+                and _rule_scope_hits(rule, link_target_posix, renamed)
+                and frm in link
+            ):
+                leaks.append(Leak(rel_posix, "replace_rule", frm, "symlink"))
+    # GITLINK (submodule) index entries reach NEITHER pass above (Fix F2):
+    # pass 1 filters on `is_file()` and pass 2 on `is_symlink()`, both False
+    # for a submodule mount point (no working-tree materialization needed —
+    # a gitlink is a pointer, not a checkout). Scan each gitlink's PATH
+    # COMPONENTS only — no content read, no readlink — exactly like the
+    # other two path-component loops, honoring the same exclusion posture
+    # pass 1 uses (`_is_excluded` + `ROOT_CONTROL`; pass 2's unfiltered gap
+    # is a known, separate limitation, not mirrored here).
+    for rel_posix in sorted(_gitlink_rels(target)):
+        rel = Path(rel_posix)
+        if _is_excluded(rel, rules) or rel_posix in ROOT_CONTROL:
+            continue
+        path_rules = [
+            (rule, frm)
+            for rule, frm, _to in rendered_rules
+            if rule.paths and _rule_scope_hits(rule, rel_posix, renamed)
+        ]
+        for i, component in enumerate(rel.parts):
+            if _is_root_press(rel, i):
+                continue
+            for field_name in path_fields:
+                value = fields.get(field_name)
+                if value is not None and occurs(
+                    component, field_name, value, substring_fields
+                ):
+                    leaks.append(Leak(rel_posix, field_name, value, "path"))
+            for _rule, frm in path_rules:
+                if frm in component:
+                    leaks.append(Leak(rel_posix, "replace_rule", frm, "path"))
+    return leaks
+
+
+def render_leak_report(leaks: list[Leak], limit: int = 20) -> str:
+    lines = [
+        f"error: {len(leaks)} source-identity leftover(s) — rebrand is "
+        f"INCOMPLETE; no receipt written."
+    ]
+    for leak in leaks[:limit]:
+        lines.append(f"  [{leak.where}] {leak.path}: {leak.field}={leak.value!r}")
+    if len(leaks) > limit:
+        lines.append(f"  … and {len(leaks) - limit} more")
+    lines.append(
+        "hint: restore the target (git -C <target> checkout . && git clean "
+        "-fd), fix the root cause (or, for content that is VALID to keep, "
+        "add its directory to BOTH extra_exclude_dirs and verify_ignore in "
+        "<target>/press/press-rules.toml — the first skips rewriting, the second skips "
+        "this scan), then press again."
+    )
+    return "\n".join(lines)