treestamp 0.1.2__tar.gz → 0.2.0__tar.gz

{treestamp-0.1.2 → treestamp-0.2.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.2.0](https://github.com/reponomics/treestamp/compare/v0.1.2...v0.2.0) (2026-10-29)
+
+
+### ⚠ BREAKING CHANGES
+
+* Documents with path-only special_paths registrations must be regenerated; documents without special registrations remain supported.
+
+
+### Bug Fixes
+
+* Replace special-path identity backtracking with direct row-number-plus-path registrations.
+  
+* fix potential DoS threat and improve docs ([#15](https://github.com/reponomics/treestamp/issues/15)) ([f3c77eb](https://github.com/reponomics/treestamp/commit/f3c77eb03a45d22fa47c9fcd7a8fe02339587dd6))
+
 ## [0.1.2](https://github.com/reponomics/treestamp/compare/v0.1.1...v0.1.2) (2026-10-28)
 
 

{treestamp-0.1.2 → treestamp-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: treestamp
-Version: 0.1.2
+Version: 0.2.0
 Summary: Generate and maintain directory trees for project documentation
 Project-URL: Homepage, https://treestamp.reponomics.org
 Project-URL: Documentation, https://github.com/reponomics/treestamp#readme
@@ -36,6 +36,13 @@ Description-Content-Type: text/markdown
     </picture>
 </div>
 
+<br>
+
+![OSSF-Scorecard Score](https://img.shields.io/ossf-scorecard/github.com/reponomics/treestamp?style=flat&label=OpenSSF%20Scorecard)
+[![OpenSSF Baseline](https://www.bestpractices.dev/projects/15900/baseline)](https://www.bestpractices.dev/projects/15900)
+[![CodeQL](https://github.com/reponomics/treestamp/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/reponomics/treestamp/actions/workflows/github-code-scanning/codeql)
+
+
 # treestamp
 
 Turn your repository into a directory tree for your README. Choose what to show, add short notes, and copy the result—from your terminal or browser.
@@ -165,7 +172,7 @@ hidden = [".dockerignore", ".gitignore", ".nvmrc", ".pre-commit-config.yaml", ".
 ./
 ├── .github/ (8 files, 2 folders)
 ├── assets/ (2 files, 1 folder)
-├── docs/ (4 files)
+├── docs/ (6 files)
 ├── scripts/ (6 files)  # Installed-package acceptance
 ├── src/
 │   └── treestamp/  # Shared model and terminal editor
@@ -198,7 +205,7 @@ hidden = [".dockerignore", ".gitignore", ".nvmrc", ".pre-commit-config.yaml", ".
 
 ## Development and support
 
-[Contributing](https://github.com/reponomics/treestamp/blob/main/.github/CONTRIBUTING.md) · [Maintenance](https://github.com/reponomics/treestamp/blob/main/docs/MAINTENANCE.md) · [Governance](https://github.com/reponomics/treestamp/blob/main/docs/GOVERNANCE.md) · [Design](https://github.com/reponomics/treestamp/blob/main/docs/design.md) · [Security assessment](https://github.com/reponomics/treestamp/blob/main/docs/security-assessment.md) · [Changelog](https://github.com/reponomics/treestamp/blob/main/CHANGELOG.md) · [Privacy](https://github.com/reponomics/treestamp/blob/main/PRIVACY.md)
+[Contributing](https://github.com/reponomics/treestamp/blob/main/.github/CONTRIBUTING.md) · [Maintenance](https://github.com/reponomics/treestamp/blob/main/docs/MAINTENANCE.md) · [Governance](https://github.com/reponomics/treestamp/blob/main/docs/GOVERNANCE.md) · [Design](https://github.com/reponomics/treestamp/blob/main/docs/design.md) · [Security assessment](https://github.com/reponomics/treestamp/blob/main/docs/security-assessment.md) · [Verifying releases](https://github.com/reponomics/treestamp/blob/main/docs/verifying-releases.md) · [Changelog](https://github.com/reponomics/treestamp/blob/main/CHANGELOG.md) · [Privacy](https://github.com/reponomics/treestamp/blob/main/PRIVACY.md)
 
 Report bugs through [GitHub issues](https://github.com/reponomics/treestamp/issues), vulnerabilities through [private security reporting](https://github.com/reponomics/treestamp/security/advisories/new), and conduct concerns to [conduct@reponomics.org](mailto:conduct@reponomics.org).
 

{treestamp-0.1.2 → treestamp-0.2.0}/README.md

@@ -4,6 +4,13 @@
     </picture>
 </div>
 
+<br>
+
+![OSSF-Scorecard Score](https://img.shields.io/ossf-scorecard/github.com/reponomics/treestamp?style=flat&label=OpenSSF%20Scorecard)
+[![OpenSSF Baseline](https://www.bestpractices.dev/projects/15900/baseline)](https://www.bestpractices.dev/projects/15900)
+[![CodeQL](https://github.com/reponomics/treestamp/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/reponomics/treestamp/actions/workflows/github-code-scanning/codeql)
+
+
 # treestamp
 
 Turn your repository into a directory tree for your README. Choose what to show, add short notes, and copy the result—from your terminal or browser.
@@ -133,7 +140,7 @@ hidden = [".dockerignore", ".gitignore", ".nvmrc", ".pre-commit-config.yaml", ".
 ./
 ├── .github/ (8 files, 2 folders)
 ├── assets/ (2 files, 1 folder)
-├── docs/ (4 files)
+├── docs/ (6 files)
 ├── scripts/ (6 files)  # Installed-package acceptance
 ├── src/
 │   └── treestamp/  # Shared model and terminal editor
@@ -166,7 +173,7 @@ hidden = [".dockerignore", ".gitignore", ".nvmrc", ".pre-commit-config.yaml", ".
 
 ## Development and support
 
-[Contributing](https://github.com/reponomics/treestamp/blob/main/.github/CONTRIBUTING.md) · [Maintenance](https://github.com/reponomics/treestamp/blob/main/docs/MAINTENANCE.md) · [Governance](https://github.com/reponomics/treestamp/blob/main/docs/GOVERNANCE.md) · [Design](https://github.com/reponomics/treestamp/blob/main/docs/design.md) · [Security assessment](https://github.com/reponomics/treestamp/blob/main/docs/security-assessment.md) · [Changelog](https://github.com/reponomics/treestamp/blob/main/CHANGELOG.md) · [Privacy](https://github.com/reponomics/treestamp/blob/main/PRIVACY.md)
+[Contributing](https://github.com/reponomics/treestamp/blob/main/.github/CONTRIBUTING.md) · [Maintenance](https://github.com/reponomics/treestamp/blob/main/docs/MAINTENANCE.md) · [Governance](https://github.com/reponomics/treestamp/blob/main/docs/GOVERNANCE.md) · [Design](https://github.com/reponomics/treestamp/blob/main/docs/design.md) · [Security assessment](https://github.com/reponomics/treestamp/blob/main/docs/security-assessment.md) · [Verifying releases](https://github.com/reponomics/treestamp/blob/main/docs/verifying-releases.md) · [Changelog](https://github.com/reponomics/treestamp/blob/main/CHANGELOG.md) · [Privacy](https://github.com/reponomics/treestamp/blob/main/PRIVACY.md)
 
 Report bugs through [GitHub issues](https://github.com/reponomics/treestamp/issues), vulnerabilities through [private security reporting](https://github.com/reponomics/treestamp/security/advisories/new), and conduct concerns to [conduct@reponomics.org](mailto:conduct@reponomics.org).
 

{treestamp-0.1.2 → treestamp-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "treestamp"
-version = "0.1.2"
+version = "0.2.0"
 description = "Generate and maintain directory trees for project documentation"
 readme = "README.md"
 license = "MIT"

{treestamp-0.1.2 → treestamp-0.2.0}/src/treestamp/codec.py

@@ -11,7 +11,6 @@ Counts and targets are regenerated facts, not saved curation.
 from __future__ import annotations
 
 import re
-from contextlib import suppress
 from dataclasses import replace
 from typing import TYPE_CHECKING
 
@@ -31,11 +30,10 @@ from treestamp.model import (
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Mapping
 
 SYMLINK_ARROW = "->"
 GITLINK_TAG = "[gitlink]"
-MAX_IDENTITY_BRANCHES = 4096
 
 # A row is one line, so control characters print as C escapes, and a byte that
 # is not UTF-8 (a surrogate, from decoding with "surrogateescape") prints as its
@@ -137,13 +135,13 @@ def _row_head(node: Node, *, markdown: bool = False) -> str:
     return text
 
 
-def special_paths(tree: Node, root: str = ".") -> frozenset[str]:
-    """Full identities for visible entries whose own names reserve the delimiter."""
-    return frozenset(
-        repo_path(node.path, root)
-        for node in tree.walk()
+def special_paths(tree: Node, root: str = ".") -> dict[int, str]:
+    """Map printed row indices to exact repository-relative special identities."""
+    return {
+        row: repo_path(node.path, root)
+        for row, node in enumerate(tree.walk(), 1)
         if ANNOTATION_DELIMITER in node.name
-    )
+    }
 
 
 def _row(node: Node, *, markdown: bool = False) -> str:
@@ -159,12 +157,22 @@ def render_tree(tree: Node, settings: Settings, *, fenced: bool = False) -> str:
 
     Bare output is for display. Reading it requires its generated special paths.
     """
+    return render_tree_with_paths(tree, settings, fenced=fenced)[0]
+
+
+def render_tree_with_paths(
+    tree: Node, settings: Settings, *, fenced: bool = False
+) -> tuple[str, dict[int, str]]:
+    """Emit rows and their special-path registrations in the same traversal."""
     markdown = settings.style == "list"
     validate_tree(tree)
     rows = [_row(tree, markdown=markdown)]
+    registered: dict[int, str] = {}
 
     def visit(node: Node, prefix: str, depth: int) -> None:
         for index, child in enumerate(node.children):
+            if ANNOTATION_DELIMITER in child.name:
+                registered[len(rows)] = repo_path(child.path, settings.root)
             last = index == len(node.children) - 1
             if settings.style == "list":
                 rows.append("  " * (depth - 1) + "- " + _row(child, markdown=True))
@@ -178,12 +186,12 @@ def render_tree(tree: Node, settings: Settings, *, fenced: bool = False) -> str:
 
     visit(tree, "", 1)
     text = "\n".join(rows) + "\n"
-    _check_rendered_tree(tree, text, settings)
+    _check_rendered_tree(tree, text, settings, registered)
     if fenced and not markdown:
         # These styles prefix every physical row with './' or a connector, so
         # embedded backticks cannot close the fence. New styles own their framing.
-        return f"```sh\n{text}```\n"
-    return text
+        text = f"```sh\n{text}```\n"
+    return text, registered
 
 
 def _facts(node: Node) -> tuple[object, ...]:
@@ -197,13 +205,15 @@ def _facts(node: Node) -> tuple[object, ...]:
     )
 
 
-def _check_rendered_tree(tree: Node, text: str, settings: Settings) -> None:
+def _check_rendered_tree(
+    tree: Node, text: str, settings: Settings, registered: Mapping[int, str]
+) -> None:
     try:
         recovered = parse_tree(
             text,
             settings.style,
             root=settings.root,
-            special_paths=special_paths(tree, settings.root),
+            special_paths=registered,
         )
     except MarkerError as exc:
         raise MarkerError(
@@ -312,37 +322,42 @@ def detect_style(text: str, *, fenced: bool = False) -> str:
     return "unicode" if fenced else "list"
 
 
-def _registered_candidates(
-    text: str, parent: str, registered: frozenset[str], *, markdown: bool
-) -> list[Node]:
-    candidates = []
-    for path in sorted(registered):
-        name = path.rsplit("/", 1)[-1]
-        printed = _display(name, markdown)
-        if not text.startswith(printed):
-            continue
-        suffix = text[len(printed) :]
-        if suffix and not suffix.startswith(
-            ("/", " [gitlink]", " -> ", ANNOTATION_DELIMITER)
-        ):
-            continue
-        try:
-            node = _parse_row("entry" + suffix, parent, markdown=markdown)
-        except MarkerError:
-            continue
-        if node.name == "entry":
-            candidates.append(replace(node, name=name, path=path))
-    with suppress(MarkerError):
-        candidates.append(_parse_row(text, parent, markdown=markdown))
-    return list(dict.fromkeys(candidates))
-
-
-def _registrations(paths: frozenset[str], root: str) -> frozenset[str]:
-    registered = frozenset(tree_path(path, root) for path in paths)
-    if any(ANNOTATION_DELIMITER not in path.rsplit("/", 1)[-1] for path in registered):
-        raise MarkerError(
-            "special_paths must register a name containing the annotation delimiter"
-        )
+def _registered_row(text: str, parent: str, path: str, *, markdown: bool) -> Node:
+    """Consume one exact registered name; only its suffix remains to parse."""
+    directory, _, name = path.rpartition("/")
+    if directory != parent:
+        raise MarkerError("special-path parent does not match the row's indentation")
+    printed = _display(name, markdown)
+    if not text.startswith(printed):
+        raise MarkerError("special-path name does not match its registered row")
+    suffix = text[len(printed) :]
+    if suffix and not suffix.startswith(
+        ("/", " [gitlink]", " -> ", ANNOTATION_DELIMITER)
+    ):
+        raise MarkerError("invalid suffix after registered special-path name")
+    node = _parse_row("entry" + suffix, parent, markdown=markdown)
+    if node.name != "entry":
+        raise MarkerError("invalid suffix after registered special-path name")
+    return replace(node, name=name, path=path)
+
+
+def _registrations(
+    paths: Mapping[int, str], root: str, row_count: int
+) -> dict[int, str]:
+    registered: dict[int, str] = {}
+    seen: set[str] = set()
+    for row, path in paths.items():
+        if type(row) is not int or not 0 < row < row_count:
+            raise MarkerError("special-path row must identify an existing non-root row")
+        relative = tree_path(path, root)
+        if ANNOTATION_DELIMITER not in relative.rsplit("/", 1)[-1]:
+            raise MarkerError(
+                "special_paths must register a name containing the annotation delimiter"
+            )
+        if relative in seen:
+            raise MarkerError("special_paths contains duplicate paths")
+        seen.add(relative)
+        registered[row] = relative
     return registered
 
 
@@ -355,138 +370,16 @@ def _row_parent(stack: list[Node], depth: int) -> Node:
     return parent
 
 
-def _indexed_rows(lines: list[str], style: str) -> list[tuple[int, str]]:
-    """Resolve indentation independently of the names assigned to each row."""
-    rows = []
-    stack = [0]
-    for index, line in enumerate(lines, 1):
-        depth, text = _depth_row(line, style)
-        if depth > len(stack):
-            raise MarkerError("tree indentation skips a parent")
-        stack = stack[:depth]
-        rows.append((stack[-1], text))
-        stack.append(index)
-    return rows
-
-
-def _assembled_tree(rows: list[tuple[int, str]], chosen: list[Node]) -> Node:
-    nodes = list(chosen)
-    children: dict[int, list[int]] = {}
-    for index, (parent, _) in enumerate(rows, 1):
-        children.setdefault(parent, []).append(index)
-    for index in reversed(range(len(nodes))):
-        nodes[index] = replace(
-            nodes[index],
-            children=tuple(nodes[child] for child in children.get(index, [])),
-        )
-    validate_tree(nodes[0])
-    return nodes[0]
-
-
-class _IdentityAssignments:
-    """Bounded backtracking over complete assignments, without recursive depth.
-
-    A registered prefix may also be an ordinary name plus an annotation. Only
-    full registration usage and the complete tree can resolve that ambiguity.
-    Ordinary rows add no branches and require no copies of the accumulated tree.
-    """
-
-    def __init__(
-        self,
-        root: Node,
-        rows: list[tuple[int, str]],
-        registered: frozenset[str],
-        *,
-        markdown: bool,
-    ) -> None:
-        self.rows, self.registered, self.markdown = rows, registered, markdown
-        self.chosen = [root]
-        self.paths = {""}
-        self.branches = 0
-        self.by_parent: dict[str, set[str]] = {}
-        for path in registered:
-            self.by_parent.setdefault(path.rpartition("/")[0], set()).add(path)
-        self.choices: list[Iterator[Node]] = [self._choices()] if rows else []
-
-    def _choices(self) -> Iterator[Node]:
-        parent_index, text = self.rows[len(self.chosen) - 1]
-        parent = self.chosen[parent_index]
-        if not parent.is_dir:
-            return iter(())
-        registered = frozenset(self.by_parent.get(parent.path, ()))
-        candidates = _registered_candidates(
-            text, parent.path, registered, markdown=self.markdown
-        )
-        remaining = len(self.rows) - len(self.chosen)
-        candidates = [
-            node
-            for node in candidates
-            if node.path not in self.paths
-            and len(self.registered - self.paths - {node.path}) <= remaining
-        ]
-        if len(candidates) > 1:
-            self.branches += 1
-        if self.branches > MAX_IDENTITY_BRANCHES:
-            raise MarkerError(
-                "special-path identity resolution exceeds the search limit"
-            )
-        return iter(candidates)
-
-    def _pop(self) -> None:
-        self.paths.remove(self.chosen.pop().path)
-
-    def _advance(self) -> bool:
-        while self.choices:
-            node = next(self.choices[-1], None)
-            if node is not None:
-                self.chosen.append(node)
-                self.paths.add(node.path)
-                return True
-            self.choices.pop()
-            if len(self.chosen) > 1:
-                self._pop()
-        return False
-
-    def trees(self) -> Iterator[Node]:
-        while self._advance():
-            if len(self.chosen) <= len(self.rows):
-                self.choices.append(self._choices())
-                continue
-            try:
-                tree = _assembled_tree(self.rows, self.chosen)
-            except MarkerError:
-                tree = None
-            if tree is not None:
-                yield tree
-            self._pop()
-
-
-def _registered_tree(
-    root: Node, lines: list[str], style: str, registered: frozenset[str]
-) -> Node:
-    assignments = _IdentityAssignments(
-        root, _indexed_rows(lines, style), registered, markdown=style == "list"
-    ).trees()
-    tree = next(assignments, None)
-    if tree is None:
-        raise MarkerError(
-            "special_paths contains unused, mismatched, or invalid identities"
-        )
-    if next(assignments, None) is not None:
-        raise MarkerError("ambiguous special-path identity in printed tree")
-    return tree
-
-
 def parse_tree(
     text: str,
     style: str | None = None,
     *,
     root: str = ".",
-    special_paths: frozenset[str] = frozenset(),
+    special_paths: Mapping[int, str] | None = None,
 ) -> Node:
     """Read structured identities and facts, using registrations before rows."""
-    registered = _registrations(special_paths, root)
     lines = text.splitlines()
+    registered = _registrations(special_paths or {}, root, len(lines))
     if not lines:
         raise MarkerError("tree is empty")
     if style is None:
@@ -495,16 +388,18 @@ def parse_tree(
         raise MarkerError(f"unknown tree style: {style!r}")
     markdown = style == "list"
     root_node = _parse_row(lines[0], "", root=True, markdown=markdown)
-    if registered:
-        return _registered_tree(root_node, lines[1:], style, registered)
     nodes = {"": root_node}
     children: dict[str, list[str]] = {"": []}
     stack = [root_node]
-    for line in lines[1:]:
+    for index, line in enumerate(lines[1:], 1):
         depth, row = _depth_row(line, style)
         parent = _row_parent(stack, depth)
         stack = stack[:depth]
-        node = _parse_row(row, parent.path, markdown=markdown)
+        node = (
+            _registered_row(row, parent.path, registered[index], markdown=markdown)
+            if index in registered
+            else _parse_row(row, parent.path, markdown=markdown)
+        )
         if node.path in nodes:
             raise MarkerError(f"duplicate tree path: {node.path!r}")
         nodes[node.path] = node

{treestamp-0.1.2 → treestamp-0.2.0}/src/treestamp/document.py

@@ -12,7 +12,7 @@ from dataclasses import dataclass, replace
 from pathlib import Path
 from typing import Literal, overload
 
-from treestamp.codec import detect_style, parse_tree, render_tree, special_paths
+from treestamp.codec import detect_style, parse_tree, render_tree_with_paths
 from treestamp.errors import MarkerError
 from treestamp.gitio import checked_path, document_path
 from treestamp.model import Node, Settings, read_path_value, tree_path
@@ -169,7 +169,30 @@ def _path_array(value: object, key: str, root: str) -> frozenset[str]:
     return frozenset(paths)
 
 
-def _metadata(text: str) -> tuple[Settings, frozenset[str], frozenset[str]]:
+def _special_path_record(item: object) -> tuple[int, object]:
+    if isinstance(item, str) or isinstance(item, dict) and set(item) == {"git_bytes"}:
+        raise MarkerError("legacy special_paths format; regenerate this treestamp")
+    if not isinstance(item, dict) or set(item) != {"row", "path"}:
+        raise MarkerError("each special_paths record must contain row and path")
+    row = item["row"]
+    if type(row) is not int or row <= 0:
+        raise MarkerError("special-path row must be a positive integer")
+    return row, item["path"]
+
+
+def _special_path_array(value: object) -> dict[int, str]:
+    if not isinstance(value, list):
+        raise MarkerError("special_paths must be an array of row/path records")
+    result: dict[int, str] = {}
+    for item in value:
+        row, path = _special_path_record(item)
+        if row in result:
+            raise MarkerError("special_paths contains duplicate rows")
+        result[row] = read_path_value(path)
+    return result
+
+
+def _metadata(text: str) -> tuple[Settings, frozenset[str], dict[int, str]]:
     try:
         values = tomllib.loads(text)
     except tomllib.TOMLDecodeError as exc:
@@ -179,9 +202,7 @@ def _metadata(text: str) -> tuple[Settings, frozenset[str], frozenset[str]]:
         raise MarkerError(f"unknown document settings: {', '.join(sorted(unknown))}")
     settings = Settings(root=read_path_value(values.get("root", ".")))
     hidden = _path_array(values.get("hidden", []), "hidden", settings.root)
-    special = _path_array(
-        values.get("special_paths", []), "special_paths", settings.root
-    )
+    special = _special_path_array(values.get("special_paths", []))
     return settings, hidden, special
 
 
@@ -220,7 +241,7 @@ def _parse_interior(interior: bytes) -> Document:
     )
     settings = Settings()
     hidden: frozenset[str] = frozenset()
-    special: frozenset[str] = frozenset()
+    special: dict[int, str] = {}
     if text.startswith(CONFIG_START):
         payload, text = _split_metadata(text)
         settings, hidden, special = _metadata(payload)
@@ -311,17 +332,20 @@ def normalized_hidden(document: Document) -> frozenset[str]:
     return frozenset(result)
 
 
-def _settings_text(document: Document) -> str:
+def _settings_text(document: Document, registered: dict[int, str]) -> str:
     rows = []
     if document.settings.root != ".":
         rows.append(f"root = {_path_literal(document.settings.root)}")
-    for key, paths in (
-        ("hidden", normalized_hidden(document)),
-        ("special_paths", special_paths(document.tree, document.settings.root)),
-    ):
-        if paths:
-            values = ", ".join(_path_literal(path) for path in sorted(paths))
-            rows.append(f"{key} = [{values}]")
+    hidden = normalized_hidden(document)
+    if hidden:
+        values = ", ".join(_path_literal(path) for path in sorted(hidden))
+        rows.append(f"hidden = [{values}]")
+    if registered:
+        values = ", ".join(
+            f"{{row = {row}, path = {_path_literal(path)}}}"
+            for row, path in registered.items()
+        )
+        rows.append(f"special_paths = [{values}]")
     return "".join(row + "\n" for row in rows)
 
 
@@ -329,8 +353,10 @@ def render_interior(document: Document, root: str | None = None) -> str:
     """Render the interior using repository-relative config identities."""
     if root is not None:
         document = replace(document, settings=replace(document.settings, root=root))
-    payload = _settings_text(document)
-    body = render_tree(document.tree, document.settings, fenced=True)
+    body, registered = render_tree_with_paths(
+        document.tree, document.settings, fenced=True
+    )
+    payload = _settings_text(document, registered)
     output = f"{CONFIG_START}\n{payload}-->\n{body}" if payload else body
     # Validate framing and metadata together before any bytes can be published.
     _parse_interior(output.encode("utf-8", "surrogateescape"))

{treestamp-0.1.2 → treestamp-0.2.0}/tests/test_codec.py

@@ -426,7 +426,7 @@ def test_ordinary_names_need_no_quotes_or_extra_marker(style: str) -> None:
     tree = build_tree(Entry(name) for name in names)
     settings = Settings(style=style)
     printed = render_tree(tree, settings)
-    assert special_paths(tree) == frozenset()
+    assert special_paths(tree) == {}
     for name in names:
         assert name in printed
     assert parse_tree(printed, style) == tree
@@ -507,16 +507,14 @@ def test_special_directory_establishes_identity_for_ordinary_children(
     )
     settings = Settings(root="src", style=style)
     paths = special_paths(tree, settings.root)
-    assert paths == frozenset(
-        {
-            "src/notes  # drafts",
-            "src/notes  # drafts/another  # draft.md",
-        }
-    )
+    assert paths == {
+        1: "src/notes  # drafts",
+        4: "src/notes  # drafts/another  # draft.md",
+    }
     text = render_tree(tree, settings)
     assert parse_tree(text, style, root="src", special_paths=paths) == tree
     collapsed = replace(tree, children=(replace(tree.children[0], children=()),))
-    assert special_paths(collapsed, "src") == frozenset({"src/notes  # drafts"})
+    assert special_paths(collapsed, "src") == {1: "src/notes  # drafts"}
 
 
 @pytest.mark.parametrize("style", ["unicode", "ascii", "list"])
@@ -543,14 +541,14 @@ def test_special_name_roundtrip_preserves_bytes_and_controls(
 @pytest.mark.parametrize(
     "paths",
     [
-        frozenset({"unused  # path"}),
-        frozenset({"ordinary"}),
-        frozenset({"other/a  # b"}),
-        frozenset({"../escape  # path"}),
+        {1: "unused  # path"},
+        {1: "ordinary"},
+        {1: "other/a  # b"},
+        {1: "../escape  # path"},
     ],
 )
 def test_special_registrations_must_match_visible_scoped_names(
-    paths: frozenset[str],
+    paths: dict[int, str],
 ) -> None:
     with pytest.raises(MarkerError):
         parse_tree("./\n└── ordinary\n", special_paths=paths)
@@ -558,7 +556,7 @@ def test_special_registrations_must_match_visible_scoped_names(
 
 @pytest.mark.parametrize("style", ["unicode", "ascii", "list"])
 @pytest.mark.parametrize("reverse", [False, True])
-def test_special_name_prefixes_resolve_using_all_registered_identities(
+def test_special_name_prefixes_resolve_using_row_identities(
     style: str, reverse: bool
 ) -> None:
     tree = build_tree([Entry("x  # y"), Entry("x  # y  # z")])
@@ -569,7 +567,7 @@ def test_special_name_prefixes_resolve_using_all_registered_identities(
 
 
 @pytest.mark.parametrize("style", ["unicode", "ascii", "list"])
-def test_special_parent_assignment_uses_descendant_registrations(style: str) -> None:
+def test_special_parents_and_children_resolve_by_row(style: str) -> None:
     tree = build_tree(
         [Entry("x  # y/a  # b"), Entry("x  # y  # z/a  # b"), Entry("ordinary")]
     )
@@ -578,28 +576,22 @@ def test_special_parent_assignment_uses_descendant_registrations(style: str) ->
     assert parse_tree(printed, style, special_paths=special_paths(tree)) == tree
 
 
-def test_multiple_complete_special_identity_assignments_are_rejected() -> None:
-    with pytest.raises(MarkerError, match="ambiguous special-path"):
-        parse_tree(
-            "./\n├── x  # y\n└── x  # y\n",
-            special_paths=frozenset({"x  # y"}),
-        )
-
-
-def test_special_identity_search_limit_is_an_explicit_error(
-    monkeypatch: pytest.MonkeyPatch,
+@pytest.mark.parametrize("registered_row", [1, 2])
+def test_identical_printed_rows_have_exact_registered_identities(
+    registered_row: int,
 ) -> None:
-    monkeypatch.setattr("treestamp.codec.MAX_IDENTITY_BRANCHES", 0)
-    with pytest.raises(
-        MarkerError, match="identity resolution exceeds the search limit"
-    ):
-        parse_tree(
-            "./\n├── x  # y\n└── ordinary\n",
-            special_paths=frozenset({"x  # y"}),
-        )
+    tree = parse_tree(
+        "./\n├── x  # y\n└── x  # y\n",
+        special_paths={registered_row: "x  # y"},
+    )
+    special = tree.children[registered_row - 1]
+    ordinary = tree.children[2 - registered_row]
+    assert (special.path, special.annotation) == ("x  # y", "")
+    assert (ordinary.path, ordinary.annotation) == ("x", "y")
 
 
-def test_filename_and_annotation_overlap_cannot_duplicate_registered_identity() -> None:
+@pytest.mark.parametrize("style", ["unicode", "ascii", "list"])
+def test_filename_and_annotation_overlap_keeps_registered_identity(style: str) -> None:
     tree = Node(
         ".",
         "",
@@ -609,8 +601,102 @@ def test_filename_and_annotation_overlap_cannot_duplicate_registered_identity()
             Node("x  # y", "x  # y", "file"),
         ),
     )
-    with pytest.raises(MarkerError, match="cannot represent"):
-        render_tree(tree, Settings())
+    printed = render_tree(tree, Settings(style=style))
+    assert parse_tree(printed, style, special_paths=special_paths(tree)) == tree
+
+
+@pytest.mark.parametrize("style", ["unicode", "ascii", "list"])
+def test_registered_prefix_file_and_directory_remain_distinct(style: str) -> None:
+    tree = Node(
+        ".",
+        "",
+        "dir",
+        children=(
+            Node("x  # y", "x  # y", "file", annotation="z"),
+            Node(
+                "x  # y  # z",
+                "x  # y  # z",
+                "dir",
+                children=(Node("ordinary", "x  # y  # z/ordinary", "file"),),
+            ),
+        ),
+    )
+    settings = Settings(root="src", style=style)
+    printed = render_tree(tree, settings)
+    assert (
+        parse_tree(printed, style, root="src", special_paths=special_paths(tree, "src"))
+        == tree
+    )
+
+
+@pytest.mark.parametrize("style", ["unicode", "ascii", "list"])
+def test_registered_rows_preserve_types_targets_and_counts(style: str) -> None:
+    tree = Node(
+        ".",
+        "",
+        "dir",
+        children=(
+            Node(
+                "dir  # name", "dir  # name", "dir", files=3, dirs=2, annotation="note"
+            ),
+            Node("link  # name", "link  # name", "symlink", target="dir/file"),
+            Node(
+                "module  # name",
+                "module  # name",
+                "gitlink",
+                annotation="nested  # note",
+            ),
+        ),
+    )
+    printed = render_tree(tree, Settings(style=style))
+    assert parse_tree(printed, style, special_paths=special_paths(tree)) == tree
+
+
+@pytest.mark.parametrize(
+    "paths",
+    [
+        {0: "x  # y"},
+        {-1: "x  # y"},
+        {3: "x  # y"},
+        {True: "x  # y"},
+        {1: "x  # y", 2: "x  # y"},
+        {1: "parent/x  # y"},
+    ],
+)
+def test_invalid_row_registrations_are_rejected(paths: dict[int, str]) -> None:
+    with pytest.raises(MarkerError):
+        parse_tree("./\n├── x  # y\n└── ordinary\n", special_paths=paths)
+
+
+@pytest.mark.parametrize("suffix", ["extra", " [gitlink]extra", "/junk"])
+def test_registered_name_requires_a_valid_suffix(suffix: str) -> None:
+    with pytest.raises(MarkerError):
+        parse_tree(f"./\n└── x  # y{suffix}\n", special_paths={1: "x  # y"})
+
+
+@pytest.mark.parametrize("ordinary_count", [400, 6400])
+def test_special_rows_do_not_revisit_following_ordinary_rows(
+    ordinary_count: int, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from treestamp import codec
+
+    names = [f"special{i:02d}  # suffix" for i in range(10)]
+    rows = [*names, *(f"ordinary{i:04d}" for i in range(ordinary_count))]
+    text = "./\n" + "".join(f"├── {name}\n" for name in rows)
+    original = codec._parse_row
+    calls = 0
+
+    def counted(
+        text: str, parent: str, *, root: bool = False, markdown: bool = False
+    ) -> Node:
+        nonlocal calls
+        calls += 1
+        return original(text, parent, root=root, markdown=markdown)
+
+    monkeypatch.setattr(codec, "_parse_row", counted)
+    parsed = parse_tree(text, special_paths=dict(enumerate(names, 1)))
+    assert [node.path for node in parsed.children] == rows
+    assert calls == len(rows) + 1
 
 
 @pytest.mark.parametrize("target", ["ordinary  # target", "null"])

{treestamp-0.1.2 → treestamp-0.2.0}/tests/test_document.py

@@ -407,8 +407,8 @@ def test_config_is_only_curation_and_minimal_special_identities(style: str) -> N
     assert 'root = "src"' in region
     assert 'hidden = ["src/hidden"]' in region
     assert (
-        'special_paths = ["src/notes  # drafts", "src/notes  # drafts/a  # b"]'
-        in region
+        'special_paths = [{row = 1, path = "src/notes  # drafts"}, '
+        '{row = 2, path = "src/notes  # drafts/a  # b"}]' in region
     )
     assert "style =" not in region and "show_counts =" not in region
     assert parse_document(region.encode()) == source
@@ -424,6 +424,15 @@ def test_root_only_style_and_count_inference(style: str) -> None:
     assert loaded.settings.show_counts is True
 
 
+@pytest.mark.parametrize("style", ["unicode", "ascii", "list"])
+def test_more_than_100_special_entries_roundtrip(style: str) -> None:
+    names = [f"file{i:03d}  # suffix" for i in range(120)]
+    document = Document(
+        build_tree([Entry(name) for name in names]), Settings(style=style)
+    )
+    assert parse_document(render_region(document).encode()) == document
+
+
 def test_count_visibility_inferred_without_config() -> None:
     from treestamp.model import Node
 
@@ -455,6 +464,75 @@ def test_invalid_metadata_never_reconstructs_another_identity(payload: str) -> N
         parse_document(content.encode())
 
 
+@pytest.mark.parametrize(
+    "records",
+    [
+        '[{row = 1, path = "x  # y"}, {row = 1, path = "z  # q"}]',
+        '[{row = 1, path = "x  # y"}, {row = 2, path = "x  # y"}]',
+        '[{row = true, path = "x  # y"}]',
+        '[{row = 1.0, path = "x  # y"}]',
+        '[{row = "1", path = "x  # y"}]',
+        '[{row = 0, path = "x  # y"}]',
+        '[{row = -1, path = "x  # y"}]',
+        '[{row = 3, path = "x  # y"}]',
+        "[{row = 1}]",
+        '[{path = "x  # y"}]',
+        '[{row = 1, path = "x  # y", extra = 0}]',
+        "[{row = 1, path = 4}]",
+        '[{row = 1, path = {git_bytes = "invalid"}}]',
+        '[{row = 1, path = "other  # name"}]',
+        '[{row = 1, path = "parent/x  # y"}]',
+        '[{row = 1, path = "../x  # y"}]',
+        '[{row = 1, path = "ordinary"}]',
+        "[4]",
+        '{row = 1, path = "x  # y"}',
+    ],
+)
+def test_invalid_special_row_metadata_is_rejected(records: str) -> None:
+    content = (
+        f"<!-- treestamp:start -->\n<!-- treestamp:config\nspecial_paths = {records}\n"
+        "-->\n```\n./\n├── x  # y\n└── z  # q\n```\n<!-- treestamp:end -->\n"
+    ).encode()
+    with pytest.raises(MarkerError):
+        parse_document(content)
+
+
+@pytest.mark.parametrize(
+    "records",
+    ['["x  # y"]', '[{git_bytes = "782020232079"}]'],
+)
+def test_legacy_special_metadata_requires_regeneration(records: str) -> None:
+    content = (
+        f"<!-- treestamp:start -->\n<!-- treestamp:config\nspecial_paths = {records}\n"
+        "-->\n```\n./\n└── x  # y\n```\n<!-- treestamp:end -->\n"
+    ).encode()
+    with pytest.raises(MarkerError, match="legacy special_paths format; regenerate"):
+        parse_document(content)
+
+
+@pytest.mark.parametrize("style", ["unicode", "ascii", "list"])
+@pytest.mark.parametrize("eol", ["\n", "\r\n"])
+def test_manual_annotations_preserve_registered_row_identities(
+    style: str, eol: str
+) -> None:
+    source = Document(
+        build_tree([Entry("x"), Entry("x  # y"), Entry("x  # y  # z")]),
+        Settings(style=style),
+    )
+    region = render_region(source).replace("\n", eol)
+    # Change only row annotations; leave the generated registrations untouched.
+    edited = region.replace("x" + eol, "x  # y" + eol).replace(
+        "x  # y  # z" + eol, "x  # y  # z  # another  # note" + eol
+    )
+    content = ("# Outside the region" + eol * 3 + edited + eol + "After.").encode()
+    loaded = parse_document(content)
+    assert {node.path: node.annotation for node in loaded.tree.walk()} == {
+        "x": "y",
+        "x  # y": "",
+        "x  # y  # z": "another  # note",
+    }
+
+
 def test_hidden_cannot_overlap_printed_rows_or_live_under_a_collapsed_directory() -> (
     None
 ):
@@ -474,11 +552,16 @@ def test_region_extraction_preserves_original_framing_and_endings() -> None:
         extract_region(b"ordinary document")
 
 
-def test_byte_special_paths_roundtrip_without_redundant_descendants() -> None:
+@pytest.mark.parametrize("style", ["unicode", "ascii", "list"])
+@pytest.mark.parametrize("root", [".", "src  # root"])
+def test_byte_special_paths_roundtrip_without_redundant_descendants(
+    style: str, root: str
+) -> None:
     source = Document(
         build_tree(
             [Entry("bad\udcff  # dir/plain"), Entry("bad\udcff  # dir/child  # name")]
-        )
+        ),
+        Settings(root=root, style=style),
     )
     content = render_region(source).encode()
     assert b"git_bytes" in content

{treestamp-0.1.2 → treestamp-0.2.0}/tests/test_editor.py

@@ -1,10 +1,17 @@
 """Fixed-snapshot editor journeys and transactional document writes."""
 
+import tomllib
 from dataclasses import replace
 
 import pytest
 
-from treestamp.document import Document, load_document, render_region, write_document
+from treestamp.document import (
+    Document,
+    load_document,
+    parse_document,
+    render_region,
+    write_document,
+)
 from treestamp.editor import OPEN_UPDATED_NOTICE, EditorController
 from treestamp.errors import MarkerError
 from treestamp.gitio import capture_snapshot
@@ -190,21 +197,113 @@ def test_noncanonical_open_is_dirty_even_when_semantics_unchanged(repo: Repo) ->
     assert destination.read_bytes() == before
 
 
-def test_special_paths_derive_from_printed_entries(repo: Repo) -> None:
-    repo.write("docs  # drafts/notes  # draft.md")
+def region_metadata(region: str) -> dict[str, object]:
+    _, separator, remainder = region.partition("<!-- treestamp:config\n")
+    return tomllib.loads(remainder.partition("-->\n")[0]) if separator else {}
+
+
+def test_special_rows_follow_expansion_hiding_and_selected_root(repo: Repo) -> None:
+    for path in (
+        "src/docs  # drafts/a.txt",
+        "src/docs  # drafts/notes  # draft.md",
+        "src/z  # last.txt",
+    ):
+        repo.write(path)
     repo.add(".")
-    editor = EditorController(capture_snapshot(repo.path), Settings())
+    editor = EditorController(
+        capture_snapshot(repo.path / "src", repository=repo.path),
+        Settings(root="src"),
+    )
     session = editor.state.session
-    session.expand("docs  # drafts")
-    session.set_annotation("docs  # drafts/notes  # draft.md", "Keep # and ##")
+    collapsed_rows = [
+        {"row": 1, "path": "src/docs  # drafts"},
+        {"row": 2, "path": "src/z  # last.txt"},
+    ]
+    assert region_metadata(editor.region_text())["special_paths"] == collapsed_rows
+    with editor.edit():
+        session.expand("docs  # drafts")
+        session.set_annotation("docs  # drafts/notes  # draft.md", "Keep  # literal")
     expanded = editor.region_text()
-    assert '"docs  # drafts/notes  # draft.md"' in expanded
-    session.collapse("docs  # drafts")
-    assert '"docs  # drafts/notes  # draft.md"' not in editor.region_text()
-    session.expand("docs  # drafts")
+    assert region_metadata(expanded)["special_paths"] == [
+        {"row": 1, "path": "src/docs  # drafts"},
+        {"row": 3, "path": "src/docs  # drafts/notes  # draft.md"},
+        {"row": 4, "path": "src/z  # last.txt"},
+    ]
+    with editor.edit():
+        session.collapse("docs  # drafts")
+    assert region_metadata(editor.region_text())["special_paths"] == collapsed_rows
+    with editor.edit():
+        session.expand("docs  # drafts")
+    assert editor.region_text() == expanded
+    with editor.edit():
+        session.hide("docs  # drafts/notes  # draft.md")
+    hidden = region_metadata(editor.region_text())
+    assert hidden["hidden"] == ["src/docs  # drafts/notes  # draft.md"]
+    assert hidden["special_paths"] == [
+        {"row": 1, "path": "src/docs  # drafts"},
+        {"row": 3, "path": "src/z  # last.txt"},
+    ]
+    session.show_hidden = True
+    assert region_metadata(editor.region_text()) == hidden
+    with editor.edit():
+        session.unhide("docs  # drafts/notes  # draft.md")
     assert editor.region_text() == expanded
-    session.hide("docs  # drafts")
-    assert "special_paths" not in editor.region_text()
+    with editor.edit():
+        session.hide("docs  # drafts")
+    hidden_parent = region_metadata(editor.region_text())
+    assert hidden_parent["hidden"] == ["src/docs  # drafts"]
+    assert hidden_parent["special_paths"] == [{"row": 1, "path": "src/z  # last.txt"}]
+    with editor.edit():
+        session.unhide("docs  # drafts")
+    assert editor.region_text() == expanded
+
+
+def test_new_editor_preflights_and_expands_more_than_100_special_entries(
+    repo: Repo,
+) -> None:
+    names = [f"docs/file{i:03d}  # draft" for i in range(101)]
+    for name in names:
+        repo.write(name)
+    repo.add(".")
+    editor = EditorController(capture_snapshot(repo.path), Settings())
+    assert "special_paths" not in region_metadata(editor.region_text())
+    with editor.edit():
+        editor.state.session.expand("docs")
+    assert region_metadata(editor.region_text())["special_paths"] == [
+        {"row": row, "path": path} for row, path in enumerate(names, 2)
+    ]
+    editor.create("tree.md")
+    loaded, _ = load_document(repo.path / "tree.md")
+    assert loaded == editor.document()
+
+
+def test_load_reindexes_special_rows_after_new_source_entries(repo: Repo) -> None:
+    repo.write("z  # draft.md")
+    repo.add(".")
+    editor = EditorController(capture_snapshot(repo.path), Settings())
+    with editor.edit():
+        editor.state.session.set_annotation("z  # draft.md", "retain  # this")
+    editor.create("tree.md")
+    original = repo.read("tree.md")
+    assert region_metadata(original)["special_paths"] == [
+        {"row": 1, "path": "z  # draft.md"}
+    ]
+    repo.write("a  # new.md")
+    repo.add("a  # new.md")
+    editor.adopt(editor.prepare_load("tree.md"))
+    assert repo.read("tree.md") == original
+    assert region_metadata(editor.region_text())["special_paths"] == [
+        {"row": 1, "path": "a  # new.md"},
+        {"row": 2, "path": "z  # draft.md"},
+    ]
+    parsed = parse_document(editor.region_text().encode())
+    assert {node.path: node.annotation for node in parsed.tree.walk()} == {
+        "a  # new.md": "",
+        "z  # draft.md": "retain  # this",
+    }
+    assert editor.dirty
+    editor.write("tree.md")
+    assert not editor.prepare_load("tree.md").dirty
 
 
 @pytest.mark.parametrize("changed", ["count", "target"])
@@ -301,16 +400,29 @@ def test_failed_source_preflight_preserves_loaded_draft(repo: Repo) -> None:
     assert repo.read("tree.md") == before
 
 
-def test_candidate_annotation_rolls_back_complete_session(repo: Repo) -> None:
+def test_annotation_can_duplicate_a_special_filename_without_changing_identity(
+    repo: Repo,
+) -> None:
     repo.write("x")
     repo.write("x  # y")
     repo.add(".")
     editor = EditorController(capture_snapshot(repo.path), Settings())
     session = editor.state.session
-    before = editor.region_text()
-    with pytest.raises(MarkerError, match="ambiguous special-path"), editor.edit():
+    with editor.edit():
         session.set_annotation("x", "y")
-    assert editor.region_text() == before and not session.annotations
+    parsed = parse_document(editor.region_text().encode())
+    assert {node.path: node.annotation for node in parsed.tree.walk()} == {
+        "x": "y",
+        "x  # y": "",
+    }
+    assert region_metadata(editor.region_text())["special_paths"] == [
+        {"row": 2, "path": "x  # y"}
+    ]
+    before = editor.region_text()
+    with pytest.raises(MarkerError, match="single line"), editor.edit():
+        session.hide("x")
+        session.set_annotation("x  # y", "invalid\nannotation")
+    assert editor.region_text() == before
 
 
 def test_preflight_only_checks_selected_subtree(repo: Repo) -> None:

{treestamp-0.1.2 → treestamp-0.2.0}/tests/test_output_bytes.py

@@ -110,7 +110,7 @@ def test_headless_hash_collision_update_and_check_preserve_authored_notes(
     repo.write("notes  # draft.md")
     repo.add("notes  # draft.md")
     output = cli_bytes(repo, "--print")
-    assert b'special_paths = ["notes  # draft.md"]' in output
+    assert b'special_paths = [{row = 3, path = "notes  # draft.md"}]' in output
     output = output.replace(
         b"notes  # draft.md\n", b"notes  # draft.md  # Keep # this note\n"
     )

{treestamp-0.1.2 → treestamp-0.2.0}/tests/test_tui.py

@@ -520,17 +520,22 @@ def test_invalid_annotation_keeps_draft_and_prompt_for_correction(repo: Repo) ->
         async with app.run_test() as pilot:
             await press(pilot, "down")
             field = await prompt(pilot, "a")
-            field.value = "y"
+            field.value = "invalid\x00note"
             await press(pilot, "enter")
             assert isinstance(app.screen, PromptScreen)
-            assert app.screen.query_one(Input).value == "y"
+            assert app.screen.query_one(Input).value == "invalid\x00note"
             assert "draft retained" in rendered_text(app.status_widget)
             assert editor.region_text() == before
             assert app.cursor.path == "x"
-            app.screen.query_one(Input).value = "valid note"
+            app.screen.query_one(Input).value = "y"
             await press(pilot, "enter")
             assert not isinstance(app.screen, PromptScreen)
-            assert editor.state.session.annotations["x"] == "valid note"
+            assert editor.state.session.annotations["x"] == "y"
+            loaded = parse_document(editor.region_text().encode())
+            assert {node.path: node.annotation for node in loaded.tree.walk()} == {
+                "x": "y",
+                "x  # y": "",
+            }
 
     asyncio.run(journey())