familiar-cli 0.6.0__tar.gz → 0.6.1__tar.gz

{familiar_cli-0.6.0 → familiar_cli-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: familiar-cli
-Version: 0.6.0
+Version: 0.6.1
 Summary: compose and invoke ai agent prompts from reusable templates
 Author-email: cyberwitchery lab <contact@cyberwitchery.com>
 License-Expression: MIT
@@ -20,7 +20,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: dev
-Requires-Dist: ruff==0.16.1; extra == "dev"
+Requires-Dist: ruff==0.16.5; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"

{familiar_cli-0.6.0 → familiar_cli-0.6.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "familiar-cli"
-version = "0.6.0"
+version = "0.6.1"
 description = "compose and invoke ai agent prompts from reusable templates"
 readme = "readme.md"
 license = "MIT"
@@ -36,7 +36,7 @@ claude = "familiar.agents:ClaudeAgent"
 package-dir = {"" = "src"}
 
 [project.optional-dependencies]
-dev = ["ruff==0.16.1", "mypy", "pytest", "pytest-cov", "bandit"]
+dev = ["ruff==0.16.5", "mypy", "pytest", "pytest-cov", "bandit"]
 
 [tool.setuptools.package-data]
 "familiar.data.conjurings" = ["*.md"]

{familiar_cli-0.6.0 → familiar_cli-0.6.1}/src/familiar/lint.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import re
-from collections.abc import Callable
+from collections.abc import Callable, Iterator
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Literal
@@ -47,11 +47,220 @@ _TASK_LINE = re.compile(
 )
 # accept inputs, input, arguments as input sections (with or without ## heading)
 _INPUTS_SECTION = re.compile(
-    r"^(##\s+)?(inputs?|arguments?)(\s*\([^)]+\))?:?\s*$", re.IGNORECASE | re.MULTILINE
+    r"^(##\s+)?(inputs?|arguments?)(\s*\([^)]+\))?:?\s*$", re.IGNORECASE
 )
-_OUTPUT_SECTION = re.compile(
-    r"^(##\s+)?(outputs?|deliverables?):?\s*$", re.IGNORECASE | re.MULTILINE
+_OUTPUT_SECTION = re.compile(r"^(##\s+)?(outputs?|deliverables?):?\s*$", re.IGNORECASE)
+_FENCE = re.compile(r"^ {0,3}(?P<marker>`{3,}|~{3,})(?P<info>.*)$")
+_LIST_ITEM = re.compile(r"^( {0,3})([-+*]|\d{1,9})([.)]?)( +|$)")
+_ATX_HEADING = re.compile(r"^ {0,3}#{1,6}(?: |$)")
+
+_QUOTE = "quote"
+_ITEM = "item"
+
+_HTML_BLOCK_NAMES = (
+    "address|article|aside|base|basefont|blockquote|body|caption|center|col|"
+    "colgroup|dd|details|dialog|dir|div|dl|dt|fieldset|figcaption|figure|footer|"
+    "form|frame|frameset|h1|h2|h3|h4|h5|h6|head|header|hr|html|iframe|legend|li|"
+    "link|main|menu|menuitem|nav|noframes|ol|optgroup|option|p|param|search|"
+    "section|summary|table|tbody|td|tfoot|th|thead|title|tr|track|ul"
 )
+_HTML_ATTRIBUTE = (
+    r"(?:\s+[a-zA-Z_:][a-zA-Z0-9:._-]*"
+    r"(?:\s*=\s*(?:[^\"'=<>`\x00-\x20]+|'[^']*'|\"[^\"]*\"))?)"
+)
+_HTML_TAG = (
+    rf"<[A-Za-z][A-Za-z0-9-]*{_HTML_ATTRIBUTE}*\s*/?>|</[A-Za-z][A-Za-z0-9-]*\s*>"
+)
+
+# commonmark's seven html block types in order; a ``None`` end condition means
+# the block runs to the next blank line
+_HTML_BLOCKS: tuple[tuple[re.Pattern[str], re.Pattern[str] | None], ...] = (
+    (
+        re.compile(r"^ {0,3}<(?:script|pre|style|textarea)(?=\s|>|$)", re.IGNORECASE),
+        re.compile(r"</(?:script|pre|style|textarea)>", re.IGNORECASE),
+    ),
+    (re.compile(r"^ {0,3}<!--"), re.compile(r"-->")),
+    (re.compile(r"^ {0,3}<\?"), re.compile(r"\?>")),
+    (re.compile(r"^ {0,3}<![A-Za-z]"), re.compile(r">")),
+    (re.compile(r"^ {0,3}<!\[CDATA\["), re.compile(r"\]\]>")),
+    (
+        re.compile(rf"^ {{0,3}}</?(?:{_HTML_BLOCK_NAMES})(?=\s|/?>|$)", re.IGNORECASE),
+        None,
+    ),
+    (re.compile(rf"^ {{0,3}}(?:{_HTML_TAG})[ \t]*$"), None),
+)
+# type 7, any complete tag alone on a line, may not interrupt a paragraph
+_HTML_LOOSE_TAG = 6
+
+
+def _match_container(line: str, col: int, container: tuple[str, int]) -> int | None:
+    """column just past ``container``'s prefix on ``line``, or ``None`` if absent."""
+    kind, width = container
+    stop = col + (3 if kind == _QUOTE else width)
+    end = col
+    while end < len(line) and line[end] == " " and end < stop:
+        end += 1
+    if kind == _ITEM:
+        return end if end - col == width else None
+    if end >= len(line) or line[end] != ">":
+        return None
+    end += 1
+    return end + 1 if end < len(line) and line[end] == " " else end
+
+
+def _opens_item(line: str, col: int, interrupting: bool) -> int | None:
+    """content width of the list item starting at ``col``, or ``None`` if none does."""
+    item = _LIST_ITEM.match(line[col:])
+    if item is None or (item.group(2).isdigit() and not item.group(3)):
+        return None
+    content = line[col + item.end() :]
+    if interrupting and (
+        not content.strip() or item.group(2) not in ("-", "+", "*", "1")
+    ):
+        return None
+    pad = len(item.group(4))
+    marker = len(item.group(1)) + len(item.group(2)) + len(item.group(3))
+    return marker + (pad if 1 <= pad <= 4 and content else 1)
+
+
+def _open_containers(
+    line: str, col: int, stack: list[tuple[str, int]], interrupting: bool
+) -> int:
+    """push every container ``line`` opens at ``col``, returning the content column."""
+    while True:
+        quoted = _match_container(line, col, (_QUOTE, 0))
+        if quoted is not None:
+            stack.append((_QUOTE, 0))
+            col = quoted
+        else:
+            width = _opens_item(line, col, interrupting)
+            if width is None:
+                return col
+            stack.append((_ITEM, width))
+            col += width
+        interrupting = False
+
+
+def _closes(rest: str, fence: str) -> bool:
+    match = _FENCE.match(rest)
+    return (
+        match is not None
+        and match.group("marker")[0] == fence[0]
+        and len(match.group("marker")) >= len(fence)
+        and not match.group("info").strip()
+    )
+
+
+def _opens(rest: str) -> str | None:
+    match = _FENCE.match(rest)
+    if match is None:
+        return None
+    marker = match.group("marker")
+    if marker[0] == "`" and "`" in match.group("info"):
+        return None
+    return marker
+
+
+def _opens_html(rest: str, paragraph: bool) -> int | None:
+    """index into ``_HTML_BLOCKS`` of the html block ``rest`` opens, else ``None``."""
+    for kind, (start, _) in enumerate(_HTML_BLOCKS):
+        if start.match(rest):
+            return None if kind == _HTML_LOOSE_TAG and paragraph else kind
+    return None
+
+
+def _unfenced_lines(text: str) -> Iterator[tuple[int, str]]:
+    """yield ``(offset, line)`` for every line of ``text`` outside a fenced code block.
+
+    fence indentation is measured from the content column of the block quotes and
+    list items open around it. an unclosed fence runs to the end of its container,
+    or to the end of ``text`` at the top level. html blocks are tracked the same
+    way and swallow any fence marker inside them.
+    """
+    stack: list[tuple[str, int]] = []
+    fence: str | None = None
+    html: int | None = None
+    paragraph = False
+    offset = 0
+    for line in text.split("\n"):
+        expanded = line.expandtabs(4)
+        blank = not expanded.strip()
+
+        col = 0
+        depth = 0
+        for container in stack:
+            if blank:
+                if container[0] == _QUOTE:
+                    break
+            else:
+                nxt = _match_container(expanded, col, container)
+                if nxt is None:
+                    break
+                col = nxt
+            depth += 1
+
+        if fence is not None:
+            if depth == len(stack):
+                if _closes(expanded[col:], fence):
+                    fence = None
+                offset += len(line) + 1
+                continue
+            fence = None
+
+        if html is not None:
+            end = _HTML_BLOCKS[html][1]
+            inner_blank = not expanded[col:].strip()
+            if depth < len(stack) or (
+                inner_blank and (end is None or (blank and stack))
+            ):
+                html = None
+            else:
+                if end is not None and end.search(expanded[col:]):
+                    html = None
+                yield offset, line
+                offset += len(line) + 1
+                continue
+
+        del stack[depth:]
+        rest = ""
+        opened: int | None = None
+        if not blank:
+            rest = expanded[_open_containers(expanded, col, stack, paragraph) :]
+            fence = _opens(rest)
+            if fence is not None:
+                paragraph = False
+                offset += len(line) + 1
+                continue
+            opened = _opens_html(rest, paragraph)
+            if opened is not None:
+                end = _HTML_BLOCKS[opened][1]
+                html = None if end is not None and end.search(rest) else opened
+        paragraph = (
+            opened is None
+            and bool(rest.strip())
+            and not _ATX_HEADING.match(rest)
+            and (paragraph or not rest.startswith("    "))
+        )
+
+        yield offset, line
+        offset += len(line) + 1
+
+
+def _next_heading_offset(text: str) -> int | None:
+    """offset of the first line starting with ``#`` outside a fenced code block."""
+    for offset, line in _unfenced_lines(text):
+        if line.startswith("#"):
+            return offset
+    return None
+
+
+def _section_end_offset(pattern: re.Pattern[str], text: str) -> int | None:
+    """offset just past the first line matching ``pattern`` outside a fenced block."""
+    for offset, line in _unfenced_lines(text):
+        match = pattern.match(line)
+        if match:
+            return offset + match.end()
+    return None
 
 
 def lint_template(content: str, name: str) -> list[LintMessage]:
@@ -95,14 +304,12 @@ def _check_placeholder_docs(
     messages: list[LintMessage] = []
 
     # loose check: prefer the inputs section if it exists, else the whole file
-    inputs_match = _INPUTS_SECTION.search(doc_content)
-    if inputs_match:
-        start = inputs_match.end()
-        # look ahead for the next markdown heading or end of file
-        next_heading = re.search(r"^#", doc_content[start:], re.MULTILINE)
+    start = _section_end_offset(_INPUTS_SECTION, doc_content)
+    if start is not None:
+        next_heading = _next_heading_offset(doc_content[start:])
         search_area = (
-            doc_content[start : start + next_heading.start()]
-            if next_heading
+            doc_content[start : start + next_heading]
+            if next_heading is not None
             else doc_content[start:]
         ).lower()
     else:
@@ -129,7 +336,8 @@ def _check_placeholder_docs(
     for p in positional:
         if p == "ARGUMENTS":
             continue
-        pattern = rf"(\w+[:\s]+\${p}|\${p}\s+[`\w]|\${p}\s*\()"
+        ref = rf"\${p}(?!\d)"
+        pattern = rf"(\w+[:\s]+{ref}|{ref}\s+[`\w]|{ref}\s*\()"
         if not re.search(pattern, search_area):
             messages.append(
                 LintMessage(
@@ -177,7 +385,7 @@ def lint_invocation(content: str, name: str) -> list[LintMessage]:
             )
         )
 
-    if not _INPUTS_SECTION.search(content):
+    if _section_end_offset(_INPUTS_SECTION, content) is None:
         messages.append(
             LintMessage(
                 level="warning",
@@ -187,7 +395,7 @@ def lint_invocation(content: str, name: str) -> list[LintMessage]:
             )
         )
 
-    if not _OUTPUT_SECTION.search(content):
+    if _section_end_offset(_OUTPUT_SECTION, content) is None:
         messages.append(
             LintMessage(
                 level="warning",

{familiar_cli-0.6.0 → familiar_cli-0.6.1}/src/familiar/render.py

@@ -22,12 +22,26 @@ class NotFoundError(Exception):
     """raised when a conjuring, invocation, or snippet is not found."""
 
 
+def _override_present(override: Path, label: str) -> bool:
+    """report whether anything sits at ``override``, readable or not."""
+    try:
+        override.lstat()
+    except (FileNotFoundError, NotADirectoryError):
+        return False
+    except OSError as e:
+        raise NotFoundError(f"cannot read {label}: {e}")
+    return True
+
+
 def _safe_read_text(path: Path, label: str) -> str:
     """read a UTF-8 text file, converting I/O errors to :class:`NotFoundError`."""
     try:
         return path.read_text(encoding="utf-8")
+    # PermissionError is an OSError; keep it first for its specific message.
     except PermissionError:
         raise NotFoundError(f"cannot read {label}: permission denied on {path}")
+    except OSError as e:
+        raise NotFoundError(f"cannot read {label}: {e}")
     except UnicodeDecodeError:
         raise NotFoundError(f"cannot read {label}: {path} is not valid UTF-8")
 
@@ -37,8 +51,9 @@ def load_text(repo_root: Path, kind: str, name: str) -> str:
     if not _VALID_NAME.match(name):
         raise NotFoundError(f"invalid {kind.rstrip('s')} name: {name}")
     override = repo_root / ".familiar" / kind / f"{name}.md"
-    if override.exists():
-        return _safe_read_text(override, f"{kind.rstrip('s')} '{name}'")
+    label = f"{kind.rstrip('s')} '{name}'"
+    if _override_present(override, label):
+        return _safe_read_text(override, label)
     pkg = f"familiar.data.{kind}"
     try:
         return (resources.files(pkg) / f"{name}.md").read_text(encoding="utf-8")
@@ -57,8 +72,9 @@ def load_snippet(repo_root: Path, path: str) -> str:
         raise NotFoundError(f"invalid snippet path: {path}")
 
     override = repo_root / ".familiar" / "snippets" / path
-    if override.exists():
-        return _safe_read_text(override, f"snippet '{path}'")
+    label = f"snippet '{path}'"
+    if _override_present(override, label):
+        return _safe_read_text(override, label)
 
     try:
         ref: Traversable = resources.files("familiar.data.snippets")

{familiar_cli-0.6.0 → familiar_cli-0.6.1}/src/familiar_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: familiar-cli
-Version: 0.6.0
+Version: 0.6.1
 Summary: compose and invoke ai agent prompts from reusable templates
 Author-email: cyberwitchery lab <contact@cyberwitchery.com>
 License-Expression: MIT
@@ -20,7 +20,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: dev
-Requires-Dist: ruff==0.16.1; extra == "dev"
+Requires-Dist: ruff==0.16.5; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"

{familiar_cli-0.6.0 → familiar_cli-0.6.1}/src/familiar_cli.egg-info/requires.txt

@@ -1,6 +1,6 @@
 
 [dev]
-ruff==0.16.1
+ruff==0.16.5
 mypy
 pytest
 pytest-cov

{familiar_cli-0.6.0 → familiar_cli-0.6.1}/tests/test_lint.py

@@ -8,6 +8,7 @@ import pytest
 
 from familiar.lint import (
     LintMessage,
+    _unfenced_lines,
     lint_all,
     lint_collection,
     lint_invocation,
@@ -219,6 +220,562 @@ output
         placeholder_warnings = [m for m in messages if "{{spec}}" in m.message]
         assert placeholder_warnings == []
 
+    def test_fenced_example_does_not_end_inputs_section(self):
+        content = """task: do something with {{target}}
+
+## inputs
+
+```sh
+# run it like this
+familiar invoke thing
+```
+
+- {{target}}: the file to operate on
+
+## output
+
+- results
+"""
+        messages = lint_invocation(content, "test.md")
+        placeholder_warnings = [m for m in messages if "{{target}}" in m.message]
+        assert placeholder_warnings == []
+
+    def test_tilde_fenced_example_does_not_end_inputs_section(self):
+        content = """task: do something with {{target}}
+
+## inputs
+
+~~~
+# run it like this
+~~~
+
+- {{target}}: the file to operate on
+
+## output
+
+- results
+"""
+        messages = lint_invocation(content, "test.md")
+        placeholder_warnings = [m for m in messages if "{{target}}" in m.message]
+        assert placeholder_warnings == []
+
+    def test_heading_after_fence_still_ends_inputs_section(self):
+        content = """task: do something with {{target}}
+
+## inputs
+
+```sh
+# run it like this
+```
+
+- other: something else
+
+## notes
+
+- {{target}} is described here, outside the inputs section
+
+## output
+
+- results
+"""
+        messages = lint_invocation(content, "test.md")
+        placeholder_warnings = [m for m in messages if "{{target}}" in m.message]
+        assert len(placeholder_warnings) == 1
+        assert placeholder_warnings[0].level == "warning"
+
+    def test_unclosed_fence_runs_to_end_of_file(self):
+        content = """task: do something with {{target}}
+
+## inputs
+
+```sh
+# run it like this
+
+## output
+
+- {{target}}: the file to operate on
+"""
+        messages = lint_invocation(content, "test.md")
+        placeholder_warnings = [m for m in messages if "{{target}}" in m.message]
+        assert placeholder_warnings == []
+
+    def test_inline_code_line_does_not_open_a_fence(self):
+        content = """task: do something with {{target}}
+
+## inputs
+
+```familiar lint``` validates these files before you commit.
+
+- ctx: the surrounding context
+
+## output
+
+- results mentioning {{target}}
+"""
+        messages = lint_invocation(content, "test.md")
+        placeholder_warnings = [m for m in messages if "{{target}}" in m.message]
+        assert len(placeholder_warnings) == 1
+        assert placeholder_warnings[0].level == "warning"
+
+    def test_backtick_fence_does_not_close_a_tilde_fence(self):
+        content = """task: do something with {{target}}
+
+## inputs
+
+~~~
+```
+# run it like this
+~~~
+
+- {{target}}: the file to operate on
+
+## output
+
+- results
+"""
+        messages = lint_invocation(content, "test.md")
+        placeholder_warnings = [m for m in messages if "{{target}}" in m.message]
+        assert placeholder_warnings == []
+
+    def test_shorter_fence_does_not_close_a_longer_fence(self):
+        content = """task: do something with {{target}}
+
+## inputs
+
+````
+```
+# run it like this
+````
+
+- {{target}}: the file to operate on
+
+## output
+
+- results
+"""
+        messages = lint_invocation(content, "test.md")
+        placeholder_warnings = [m for m in messages if "{{target}}" in m.message]
+        assert placeholder_warnings == []
+
+    def test_fence_with_info_string_does_not_close_a_fence(self):
+        content = """task: do something with {{target}}
+
+## inputs
+
+```
+```python
+# run it like this
+```
+
+- {{target}}: the file to operate on
+
+## output
+
+- results
+"""
+        messages = lint_invocation(content, "test.md")
+        placeholder_warnings = [m for m in messages if "{{target}}" in m.message]
+        assert placeholder_warnings == []
+
+    def test_fenced_inputs_heading_does_not_count_as_the_section(self):
+        content = """task: show how to write an invocation
+
+here is the shape of one:
+
+```md
+## inputs
+
+- {{thing}}: a thing
+
+## output
+
+- results
+```
+"""
+        messages = lint_invocation(content, "test.md")
+        section_warnings = [m for m in messages if "section" in m.message]
+        assert len(section_warnings) == 2
+        assert all(m.level == "warning" for m in section_warnings)
+        assert any("'inputs' section" in m.message for m in section_warnings)
+        assert any("'output' or 'deliverables'" in m.message for m in section_warnings)
+
+    def test_tilde_fenced_output_heading_does_not_count_as_the_section(self):
+        content = """task: show how to write an invocation
+
+## inputs
+
+- ctx: the surrounding context
+
+~~~md
+## output
+
+- results
+~~~
+"""
+        messages = lint_invocation(content, "test.md")
+        output_warnings = [m for m in messages if "output" in m.message.lower()]
+        assert len(output_warnings) == 1
+        assert output_warnings[0].level == "warning"
+
+    def test_fenced_inputs_heading_does_not_anchor_placeholder_search(self):
+        content = """task: do something with {{target}}
+
+an example of what to write:
+
+```md
+## inputs
+
+- example: a placeholder
+
+## output
+
+- example results
+```
+
+## inputs
+
+- {{target}}: the file to operate on
+
+## output
+
+- results
+"""
+        messages = lint_invocation(content, "test.md")
+        assert messages == []
+
+    def test_positional_placeholder_not_matched_as_prefix(self):
+        content = """task: process $1 and $10
+
+## inputs
+
+- ctx: $10 the tenth argument
+
+## output
+
+- results
+"""
+        messages = lint_invocation(content, "test.md")
+        assert [m for m in messages if "'$10'" in m.message] == []
+        first_warnings = [m for m in messages if "'$1'" in m.message]
+        assert len(first_warnings) == 1
+        assert first_warnings[0].level == "warning"
+
+    def test_positional_placeholder_documented_with_trailing_punctuation(self):
+        for doc in [
+            "- ctx: $1",
+            "- ctx: $1, the first argument",
+            "- $1 (required): the first argument",
+        ]:
+            content = (
+                f"task: process $1\n\n## inputs\n\n{doc}\n\n## output\n\n- results\n"
+            )
+            messages = lint_invocation(content, "test.md")
+            warnings = [m for m in messages if "may not be documented" in m.message]
+            assert warnings == [], f"failed for: {doc}"
+
+
+class TestContainerAwareFences:
+    """tests for fences nested in list items and block quotes."""
+
+    @staticmethod
+    def _unfenced(text):
+        return [line for _, line in _unfenced_lines(text)]
+
+    def test_bullet_nested_fence_with_indented_closer_does_not_swallow_the_file(self):
+        content = """task: do something with {{target}}
+
+- write the invocation like this:
+
+   ```md
+   ## inputs
+    ```
+
+## inputs
+
+- {{target}}: the file to operate on
+"""
+        messages = lint_invocation(content, "test.md")
+        assert [m for m in messages if "'inputs' section" in m.message] == []
+
+    def test_fence_in_a_list_item(self):
+        text = "- item\n\n  ```\n  ## inputs\n  ```\n\n## real\n"
+        assert self._unfenced(text) == ["- item", "", "", "## real", ""]
+
+    def test_fence_in_a_block_quote(self):
+        text = "> quoted\n>\n> ```\n> ## inputs\n> ```\n\n## real\n"
+        assert self._unfenced(text) == ["> quoted", ">", "", "## real", ""]
+
+    def test_fence_in_a_list_item_inside_a_block_quote(self):
+        text = "> - item\n>\n>   ```\n>   ## inputs\n>   ```\n>\n## real\n"
+        assert self._unfenced(text) == ["> - item", ">", ">", "## real", ""]
+
+    def test_unclosed_fence_still_runs_to_the_end_of_the_file(self):
+        text = "intro\n\n```\n## inputs\n\n## output\n"
+        assert self._unfenced(text) == ["intro", ""]
+
+    def test_fence_ends_when_its_container_ends(self):
+        text = "- item\n\n  ```\n  code\n## real\n"
+        assert self._unfenced(text) == ["- item", "", "## real", ""]
+
+    def test_blank_line_does_not_end_a_fence_in_a_list_item(self):
+        text = "- item\n\n  ```\n  code\n\n  ## inputs\n  ```\n\n## real\n"
+        assert self._unfenced(text) == ["- item", "", "", "## real", ""]
+
+    def test_blank_line_ends_a_fence_in_a_block_quote(self):
+        text = "> ```\n> code\n\n## real\n"
+        assert self._unfenced(text) == ["", "## real", ""]
+
+    def test_fence_marker_past_the_item_content_column_is_not_a_fence(self):
+        text = "- item\n\n      ```\n\n## real\n"
+        assert self._unfenced(text) == ["- item", "", "      ```", "", "## real", ""]
+
+    def test_top_level_closer_indented_four_spaces_does_not_close(self):
+        text = "   ```\n   code\n    ```\n## swallowed\n"
+        assert self._unfenced(text) == []
+
+    def test_tab_indented_fence_under_a_bullet(self):
+        text = "-\ta\n\n\t```\n\t## inputs\n\t```\n\n## real\n"
+        assert self._unfenced(text) == ["-\ta", "", "", "## real", ""]
+
+    def test_ordered_marker_mid_paragraph_opens_no_container(self):
+        text = "prose\n2) not a list\n      ```\n## real\n"
+        assert self._unfenced(text) == [
+            "prose",
+            "2) not a list",
+            "      ```",
+            "## real",
+            "",
+        ]
+
+    def test_outdented_closer_ends_the_item_and_opens_a_new_fence(self):
+        text = "- item\n\n  ```\n  code\n```\n## swallowed\n"
+        assert self._unfenced(text) == ["- item", ""]
+
+
+class TestHtmlBlocks:
+    """tests for fence markers swallowed by a commonmark html block."""
+
+    @staticmethod
+    def _unfenced(text):
+        return [line for _, line in _unfenced_lines(text)]
+
+    def test_details_wrapping_an_example_does_not_swallow_the_file(self):
+        content = """task: do something with {{target}}
+
+<details>
+<summary>example</summary>
+- ```md
+  ## inputs
+```
+</details>
+
+## inputs
+
+- {{target}}: the file to operate on
+
+## output
+
+- the rewritten file
+"""
+        assert lint_invocation(content, "test.md") == []
+
+    def test_bullet_fence_under_an_open_tag_is_not_a_fence(self):
+        text = "<div>\n- ```\n## inputs\n```\n"
+        assert self._unfenced(text) == ["<div>", "- ```", "## inputs", "```", ""]
+
+    def test_blank_line_between_the_tag_and_the_fence_leaves_a_fence(self):
+        text = "<div>\n\n```\n## inputs\n```\n\n## real\n"
+        assert self._unfenced(text) == ["<div>", "", "", "## real", ""]
+
+    def test_open_tag_interrupts_a_paragraph(self):
+        text = "text\n<div>\n```\n## inputs\n```\n## real\n"
+        assert self._unfenced(text) == [
+            "text",
+            "<div>",
+            "```",
+            "## inputs",
+            "```",
+            "## real",
+            "",
+        ]
+
+    def test_html_block_ends_with_its_container(self):
+        text = "- <div>\n  ```\n## real\n```\n"
+        assert self._unfenced(text) == ["- <div>", "  ```", "## real"]
+
+    def test_html_block_in_a_list_item(self):
+        text = "- <details>\n  ```\n  ## inputs\n\n## real\n"
+        assert self._unfenced(text) == [
+            "- <details>",
+            "  ```",
+            "  ## inputs",
+            "",
+            "## real",
+            "",
+        ]
+
+    def test_html_block_in_a_block_quote(self):
+        text = "> <div>\n> ```\n> ## inputs\n\n## real\n"
+        assert self._unfenced(text) == [
+            "> <div>",
+            "> ```",
+            "> ## inputs",
+            "",
+            "## real",
+            "",
+        ]
+
+    def test_script_runs_to_its_closing_tag(self):
+        text = "<script>\n```\n## inputs\n</script>\n```\n## real\n```\n## after\n"
+        assert self._unfenced(text) == [
+            "<script>",
+            "```",
+            "## inputs",
+            "</script>",
+            "## after",
+            "",
+        ]
+
+    def test_uppercase_script_runs_to_its_closing_tag(self):
+        text = "<PRE>\n```\n## inputs\n</PRE>\n```\n## real\n```\n## after\n"
+        assert self._unfenced(text) == [
+            "<PRE>",
+            "```",
+            "## inputs",
+            "</PRE>",
+            "## after",
+            "",
+        ]
+
+    def test_script_closed_on_its_own_line_leaves_a_fence(self):
+        text = "<script>x</script>\n```\n## inputs\n```\n## real\n"
+        assert self._unfenced(text) == ["<script>x</script>", "## real", ""]
+
+    def test_comment_runs_to_its_terminator(self):
+        text = "<!--\n```\n-->\n```\n## real\n```\n## after\n"
+        assert self._unfenced(text) == ["<!--", "```", "-->", "## after", ""]
+
+    def test_comment_closed_on_its_own_line_leaves_a_fence(self):
+        text = "<!-- c -->\n```\n## inputs\n```\n## real\n"
+        assert self._unfenced(text) == ["<!-- c -->", "## real", ""]
+
+    def test_processing_instruction_runs_to_its_terminator(self):
+        text = "<?php\n```\n?>\n```\n## real\n```\n## after\n"
+        assert self._unfenced(text) == ["<?php", "```", "?>", "## after", ""]
+
+    def test_declaration_runs_to_its_terminator(self):
+        text = "<!DOCTYPE\n```\n## inputs\nfoo>\n```\n## real\n```\n## after\n"
+        assert self._unfenced(text) == [
+            "<!DOCTYPE",
+            "```",
+            "## inputs",
+            "foo>",
+            "## after",
+            "",
+        ]
+
+    def test_declaration_closed_on_its_own_line_leaves_a_fence(self):
+        text = "<!DOCTYPE html>\n```\n## inputs\n```\n## real\n"
+        assert self._unfenced(text) == ["<!DOCTYPE html>", "## real", ""]
+
+    def test_cdata_runs_to_its_terminator(self):
+        text = "<![CDATA[\n```\n]]>\n```\n## real\n```\n## after\n"
+        assert self._unfenced(text) == ["<![CDATA[", "```", "]]>", "## after", ""]
+
+    def test_empty_quote_line_ends_a_block_in_a_quote(self):
+        text = "> <details>\n>\n> ```\n> ## inputs\n> ```\n\n## real\n"
+        assert self._unfenced(text) == ["> <details>", ">", "", "## real", ""]
+
+    def test_blank_line_does_not_end_a_terminated_block(self):
+        text = "<pre>\n\n```\n## inputs\n```\n</pre>\n## real\n"
+        assert self._unfenced(text) == [
+            "<pre>",
+            "",
+            "```",
+            "## inputs",
+            "```",
+            "</pre>",
+            "## real",
+            "",
+        ]
+
+    def test_blank_line_ends_a_terminated_block_in_a_list_item(self):
+        text = "- <pre>\n\n  ```\n  ## inputs\n  ```\n\n## real\n"
+        assert self._unfenced(text) == ["- <pre>", "", "", "## real", ""]
+
+    def test_uppercase_tag_interrupts_a_paragraph(self):
+        text = "text\n<DIV>\n```\n## inputs\n```\n## real\n"
+        assert self._unfenced(text) == [
+            "text",
+            "<DIV>",
+            "```",
+            "## inputs",
+            "```",
+            "## real",
+            "",
+        ]
+
+    def test_indented_tag_interrupts_a_paragraph(self):
+        text = "text\n   <div>\n```\n## inputs\n```\n## real\n"
+        assert self._unfenced(text) == [
+            "text",
+            "   <div>",
+            "```",
+            "## inputs",
+            "```",
+            "## real",
+            "",
+        ]
+
+    def test_closing_tag_interrupts_a_paragraph(self):
+        text = "text\n</div>\n```\n## inputs\n```\n## real\n"
+        assert self._unfenced(text) == [
+            "text",
+            "</div>",
+            "```",
+            "## inputs",
+            "```",
+            "## real",
+            "",
+        ]
+
+    def test_tag_extending_a_block_name_does_not_interrupt_a_paragraph(self):
+        text = "text\n<divider>\n```\n## inputs\n```\n## real\n"
+        assert self._unfenced(text) == ["text", "<divider>", "## real", ""]
+
+    def test_tag_with_trailing_text_does_not_open_a_block(self):
+        text = "<span>i</span> trailing\n```\n## inputs\n```\n\n## real\n"
+        assert self._unfenced(text) == ["<span>i</span> trailing", "", "## real", ""]
+
+    def test_tag_alone_after_a_closed_block_opens_a_block(self):
+        text = "<pre>x</pre>\n<span>\n```\n## inputs\n```\n\n## real\n"
+        assert self._unfenced(text) == [
+            "<pre>x</pre>",
+            "<span>",
+            "```",
+            "## inputs",
+            "```",
+            "",
+            "## real",
+            "",
+        ]
+
+    def test_unknown_tag_alone_on_a_line_opens_a_block(self):
+        text = "<x-tag>\n```\n## inputs\n```\n\n## real\n"
+        assert self._unfenced(text) == [
+            "<x-tag>",
+            "```",
+            "## inputs",
+            "```",
+            "",
+            "## real",
+            "",
+        ]
+
+    def test_unknown_tag_does_not_interrupt_a_paragraph(self):
+        text = "text\n<x-tag>\n```\n## inputs\n```\n## real\n"
+        assert self._unfenced(text) == ["text", "<x-tag>", "## real", ""]
+
 
 class TestLintAll:
     """tests for linting all conjurings and invocations."""

{familiar_cli-0.6.0 → familiar_cli-0.6.1}/tests/test_render.py

@@ -141,6 +141,32 @@ class TestLoadText:
         with pytest.raises(NotFoundError, match="not valid UTF-8"):
             load_text(tmp_path, "conjurings", "binary")
 
+    def test_directory_override_raises(self, tmp_path):
+        override_dir = tmp_path / ".familiar" / "conjurings"
+        (override_dir / "nested.md").mkdir(parents=True)
+        with pytest.raises(NotFoundError, match="cannot read conjuring 'nested'"):
+            load_text(tmp_path, "conjurings", "nested")
+
+    def test_overlong_name_override_raises(self, tmp_path):
+        override_dir = tmp_path / ".familiar" / "conjurings"
+        override_dir.mkdir(parents=True)
+        with pytest.raises(NotFoundError, match="cannot read conjuring"):
+            load_text(tmp_path, "conjurings", "a" * 300)
+
+    def test_symlink_loop_override_raises(self, tmp_path):
+        override_dir = tmp_path / ".familiar" / "conjurings"
+        override_dir.mkdir(parents=True)
+        (override_dir / "python.md").symlink_to("python.md")
+        with pytest.raises(NotFoundError, match="cannot read conjuring 'python'"):
+            load_text(tmp_path, "conjurings", "python")
+
+    def test_dangling_symlink_override_raises(self, tmp_path):
+        override_dir = tmp_path / ".familiar" / "conjurings"
+        override_dir.mkdir(parents=True)
+        (override_dir / "python.md").symlink_to(tmp_path / "gone.md")
+        with pytest.raises(NotFoundError, match="cannot read conjuring 'python'"):
+            load_text(tmp_path, "conjurings", "python")
+
 
 class TestComposeSystem:
     """tests for composing system prompts."""
@@ -434,6 +460,32 @@ class TestLoadSnippet:
         with pytest.raises(NotFoundError, match="not valid UTF-8"):
             load_snippet(tmp_path, "test/binary.txt")
 
+    def test_directory_override_raises(self, tmp_path):
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "test"
+        (snippet_dir / "nested").mkdir(parents=True)
+        with pytest.raises(NotFoundError, match="cannot read snippet 'test/nested'"):
+            load_snippet(tmp_path, "test/nested")
+
+    def test_overlong_name_override_raises(self, tmp_path):
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "test"
+        snippet_dir.mkdir(parents=True)
+        with pytest.raises(NotFoundError, match="cannot read snippet"):
+            load_snippet(tmp_path, "test/" + "a" * 300)
+
+    def test_symlink_loop_override_raises(self, tmp_path):
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "python"
+        snippet_dir.mkdir(parents=True)
+        (snippet_dir / "pyproject.toml").symlink_to("pyproject.toml")
+        with pytest.raises(NotFoundError, match="cannot read snippet 'python/"):
+            load_snippet(tmp_path, "python/pyproject.toml")
+
+    def test_dangling_symlink_override_raises(self, tmp_path):
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "python"
+        snippet_dir.mkdir(parents=True)
+        (snippet_dir / "pyproject.toml").symlink_to(tmp_path / "gone.toml")
+        with pytest.raises(NotFoundError, match="cannot read snippet 'python/"):
+            load_snippet(tmp_path, "python/pyproject.toml")
+
 
 class TestResolveIncludes:
     """tests for snippet include resolution."""