surf-cli 0.7.1__tar.gz → 0.8.0__tar.gz

{surf_cli-0.7.1 → surf_cli-0.8.0}/.agents/skills/surf/SKILL.md

@@ -8,7 +8,7 @@ metadata:
     github_username: saintx
     email: alex@saintx.us
     twitter: alexsaintx
-  surf-version: "0.7.1"
+  surf-version: "0.8.0"
 ---
 
 # Surf: Progressive Context Disclosure
@@ -40,6 +40,7 @@ Resolve with `surf` against the section heading; do not bulk-ingest a whole refe
 | Wikilink and link input | `surf references/usage.md "Wikilink and link input"` |
 | Batch scanning | `surf references/usage.md "Batch scanning"` |
 | Platform aggregation (batch section extraction) | `surf references/usage.md "Platform aggregation (batch section extraction)"` |
+| Filter by frontmatter | `surf references/usage.md "Filter by frontmatter"` |
 | Additional options | `surf references/usage.md "Additional options"` |
 
 ### TeX and PDF

{surf_cli-0.7.1 → surf_cli-0.8.0}/.agents/skills/surf/references/about.md

@@ -5,7 +5,7 @@ metadata:
     github_username: saintx
     email: alex@saintx.us
     twitter: alexsaintx
-  surf-version: "0.7.1"
+  surf-version: "0.8.0"
 ---
 # Surf — About
 

{surf_cli-0.7.1 → surf_cli-0.8.0}/.agents/skills/surf/references/usage.md

@@ -5,7 +5,7 @@ metadata:
     github_username: saintx
     email: alex@saintx.us
     twitter: alexsaintx
-  surf-version: "0.7.1"
+  surf-version: "0.8.0"
 ---
 # Surf Usage
 
@@ -101,25 +101,32 @@ The `.md` extension is implicit. `surf ~/path/to/file` resolves to `~/path/to/fi
 Scan YAML across a directory without loading any body:
 
 ```bash
-ls ~/path/to/*.md | xargs -I {} surf -f {}
+surf -f ~/path/to/*.md
 ```
 
-Same pattern on nested trees:
+Two or more files print under `==> path <==` headers. Nested trees:
 
 ```bash
-ls ~/path/to/*/file.md | xargs -I {} surf -f {}
+surf -f ~/path/to/*/file.md
 ```
 
 ## Platform aggregation (batch section extraction)
 
-Print the path, then one heading, for each matching file:
+Extract one heading from each matching file. Two or more files print under `==> path <==` headers:
 
 ```bash
-find ~/path/to -path '*/subdir/file.md' | sort \
-  | xargs -I{} sh -c 'echo "### {}" && surf {} "Some Heading" && echo'
+surf -s "Some Heading" ~/path/to/*/file.md
 ```
 
-Change the `find` root, the path glob, and the heading text to match the files you have.
+Change the glob and the heading text to match the files you have.
+
+## Filter by frontmatter
+
+```bash
+surf --where metadata.skill-family=skill-authoring -s Overview ~/path/to/*/references/about.md
+```
+
+`--where KEY=VALUE` keeps files whose YAML frontmatter matches. Dotted keys walk nested maps. A list value matches on membership. Repeat `--where` to require every clause. With no other mode flag, print matching paths.
 
 ## Additional options
 
@@ -129,8 +136,11 @@ Change the `find` root, the path glob, and the heading text to match the files y
 | heading, no flag | Section content without frontmatter |
 | `--list` | Heading tree only |
 | `-f` / `--frontmatter-only` | YAML only |
+| `-s` / `--section` | Heading to extract from each file. Every positional is a file. |
+| `--where KEY=VALUE` | Keep files whose frontmatter matches. Repeatable and conjunctive. |
 | `--full` | With a named heading: YAML frontmatter, then that section. Without a heading: the file map. |
 | `--content-only` / `--body-only` | Same as a named heading with no flag. This is the default extract. |
 | `--level N` | List: ranks 1 through N. Extract: exact rank N. |
 | `--no-heading` | Omit the heading line from section output |
 | `-o <file>` | Write output to a file. |
+| `-v` / `--verbose` | Name each skipped file on stderr. |

{surf_cli-0.7.1 → surf_cli-0.8.0}/.claude-plugin/marketplace.json

@@ -3,14 +3,14 @@
   "owner": { "name": "Alexander R. Saint Croix", "email": "alex@saintx.us" },
   "metadata": {
     "description": "Plugins shipped with the surf CLI.",
-    "version": "0.7.1"
+    "version": "0.8.0"
   },
   "plugins": [
     {
       "name": "surf",
       "source": "./plugins/surf",
       "description": "Extract a markdown heading, TeX section, or PDF outline item without loading the rest of the file.",
-      "version": "0.7.1",
+      "version": "0.8.0",
       "category": "tooling",
       "keywords": ["surf", "markdown", "tex", "pdf", "context", "skills"]
     }

{surf_cli-0.7.1 → surf_cli-0.8.0}/CONTRIBUTING.md

@@ -27,7 +27,7 @@ src/surf/
   orchestrator.py  CLI: argument parsing, dispatch, exit codes
   test_*.py        tests, beside the modules they cover
 plugins/surf/      the agent skill and its manifests
-scripts/           test.sh, lint.sh, deploy.sh
+scripts/           test.sh, lint.sh, deploy.sh, spec-coverage.py
 ```
 
 The layers only depend downward, and `pypdf` is confined to `adapters.py`. Four `import-linter` contracts in `pyproject.toml` enforce this, and `scripts/lint.sh` runs them.
@@ -35,10 +35,11 @@ The layers only depend downward, and `pypdf` is confined to `adapters.py`. Four
 ## Tests
 
 ```bash
-scripts/test.sh    # uv run pytest src/surf -q
+scripts/test.sh                      # uv run pytest src/surf -q
+python scripts/spec-coverage.py      # which spec scenarios have a passing test
 ```
 
-Tests live in `src/surf/test_*.py` and are excluded from the wheel. The root `tests/` directory is unused.
+Unit tests live in `src/surf/test_*.py` and are excluded from the wheel. A test that demonstrates a scenario cites it with a docstring line `spec: <slug>#Scenario`. `python scripts/spec-coverage.py` reports which scenarios under `spec/features/` those citations cover.
 
 ## Lint
 

{surf_cli-0.7.1 → surf_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: surf-cli
-Version: 0.7.1
+Version: 0.8.0
 Summary: List headings, or extract one section by name, from Markdown, TeX, or PDF.
 Project-URL: Homepage, https://github.com/saintx/surf-cli
 Project-URL: Repository, https://github.com/saintx/surf-cli
@@ -71,7 +71,7 @@ metadata:
     github_username: saintx
     email: alex@saintx.us
     twitter: alexsaintx
-  surf-version: "0.7.1"
+  surf-version: "0.8.0"
 ---
 
 - Surf — About
@@ -237,7 +237,13 @@ Matching ignores case. `surf guide` resolves to `guide.md`; `.tex` and `.pdf` ne
 **Scan a directory.** Frontmatter across many files, no body loaded:
 
 ```bash
-ls docs/*.md | xargs -I {} surf -f {}
+surf -f docs/*.md
+```
+
+Keep files whose frontmatter matches a key:
+
+```bash
+surf --where title=Guide docs/*.md
 ```
 
 `surf --help` lists every flag.

{surf_cli-0.7.1 → surf_cli-0.8.0}/README.md

@@ -36,7 +36,7 @@ metadata:
     github_username: saintx
     email: alex@saintx.us
     twitter: alexsaintx
-  surf-version: "0.7.1"
+  surf-version: "0.8.0"
 ---
 
 - Surf — About
@@ -202,7 +202,13 @@ Matching ignores case. `surf guide` resolves to `guide.md`; `.tex` and `.pdf` ne
 **Scan a directory.** Frontmatter across many files, no body loaded:
 
 ```bash
-ls docs/*.md | xargs -I {} surf -f {}
+surf -f docs/*.md
+```
+
+Keep files whose frontmatter matches a key:
+
+```bash
+surf --where title=Guide docs/*.md
 ```
 
 `surf --help` lists every flag.

{surf_cli-0.7.1 → surf_cli-0.8.0}/flake.nix

@@ -55,7 +55,7 @@
 
         surf = pythonPkgs.buildPythonApplication {
           pname = "surf";
-          version = "0.7.1";
+          version = "0.8.0";
           src = cliSrc;
           pyproject = true;
 

{surf_cli-0.7.1 → surf_cli-0.8.0}/plugins/surf/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "surf",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Extract a markdown heading, TeX section, or PDF outline item without loading the rest of the file. Skill for agents using the surf CLI.",
   "author": { "name": "Alexander R. Saint Croix", "email": "alex@saintx.us" },
   "homepage": "https://github.com/saintx/surf-cli",

{surf_cli-0.7.1 → surf_cli-0.8.0}/plugins/surf/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "surf",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Extract a markdown heading, TeX section, or PDF outline item without loading the rest of the file. Skill for agents using the surf CLI.",
   "author": { "name": "Alexander R. Saint Croix", "email": "alex@saintx.us", "url": "https://github.com/saintx" },
   "homepage": "https://github.com/saintx/surf-cli",

{surf_cli-0.7.1 → surf_cli-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "surf-cli"
-version = "0.7.1"
+version = "0.8.0"
 description = "List headings, or extract one section by name, from Markdown, TeX, or PDF."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -37,6 +37,7 @@ dev = [
     "isort>=6.0.1",
     "pyright>=1.1.407",
     "pytest>=9.1.1",
+    "pyyaml>=6",
 ]
 
 [tool.uv]
@@ -85,3 +86,10 @@ source_modules = ["surf.models", "surf.logic", "surf.orchestrator"]
 forbidden_modules = ["pypdf"]
 type = "forbidden"
 allow_indirect_imports = true
+
+[[tool.importlinter.contracts]]
+name = "Models, logic, and orchestrator cannot import yaml"
+source_modules = ["surf.models", "surf.logic", "surf.orchestrator"]
+forbidden_modules = ["yaml"]
+type = "forbidden"
+allow_indirect_imports = true

surf_cli-0.8.0/scripts/spec-coverage.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+# scripts/spec-coverage.py
+"""Which scenarios under spec/features/ are demonstrated by passing tests.
+
+    python scripts/spec-coverage.py [--junit results.xml] [--tests 'src/surf/test_*.py'] [--strict]
+
+Scenarios come from `surf spec/features/<slug>.md --list` for every feature file:
+the H1 is the feature, each level-2 heading is a scenario, and a scenario's
+address is "<slug>#<Scenario>".
+
+A test cites the scenario it demonstrates with a docstring line:
+
+    def test_nested_path_selects_child():
+        \"\"\"spec: section-extraction#Nested path selects the child inside the named parent\"\"\"
+
+One test may cite several scenarios, one per line. Outcomes come from pytest's
+JUnit report; without --junit the script runs `uv run pytest src/surf --junitxml`
+itself.
+
+Forward check: every cited address exists in the spec (else "unknown address").
+Reverse check: every scenario is cited by at least one passing test (else
+"untested" or "failing"). Exit 1 on any failing or unknown; with --strict, also
+on any untested.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import glob
+import re
+import subprocess
+import sys
+import tempfile
+import xml.etree.ElementTree as ET
+from collections import defaultdict
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+FEATURES = ROOT / "spec" / "features"
+_CITE_RE = re.compile(r"^\s*spec:\s*(.+?)\s*$")
+
+
+def scenarios_from_spec() -> list[tuple[str, str, str, str]]:
+    """(slug, feature name, status, scenario) in file order."""
+    rows: list[tuple[str, str, str, str]] = []
+    for path in sorted(FEATURES.glob("*.md")):
+        slug = path.stem
+        fm = subprocess.run(
+            ["uv", "run", "surf", "-f", str(path)],
+            capture_output=True,
+            text=True,
+            cwd=ROOT,
+        ).stdout
+        status = next(
+            (ln.split(":", 1)[1].strip() for ln in fm.splitlines() if ln.startswith("status:")),
+            "?",
+        )
+        out = subprocess.run(
+            ["uv", "run", "surf", str(path), "--list"],
+            capture_output=True,
+            text=True,
+            check=True,
+            cwd=ROOT,
+        ).stdout
+        feature = None
+        for line in out.splitlines():
+            indent = len(line) - len(line.lstrip(" "))
+            text = line.strip()[2:]
+            if indent == 0:
+                feature = text
+            elif indent == 2 and feature is not None:
+                rows.append((slug, feature, status, text))
+    return rows
+
+
+def citations_from_tests(pattern: str) -> dict[str, list[str]]:
+    cites: dict[str, list[str]] = {}
+    for path in sorted(glob.glob(pattern, recursive=True)):
+        tree = ast.parse(Path(path).read_text(encoding="utf-8"))
+        module = Path(path).stem
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name.startswith(
+                "test"
+            ):
+                doc = ast.get_docstring(node) or ""
+                addrs = [m.group(1) for ln in doc.splitlines() if (m := _CITE_RE.match(ln))]
+                if addrs:
+                    cites[f"{module}::{node.name}"] = addrs
+    return cites
+
+
+def outcomes_from_junit(path: Path) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for case in ET.parse(path).getroot().iter("testcase"):
+        module = case.get("classname", "").split(".")[-1]
+        name = case.get("name", "").split("[")[0]
+        status = "passed"
+        for child in case:
+            if child.tag in ("failure", "error"):
+                status = "failed"
+            elif child.tag == "skipped":
+                status = "skipped"
+        key = f"{module}::{name}"
+        if result.get(key) != "failed":
+            result[key] = status
+    return result
+
+
+def run_pytest_junit() -> Path:
+    tmp = Path(tempfile.mkdtemp()) / "results.xml"
+    proc = subprocess.run(
+        ["uv", "run", "pytest", "src/surf", "-q", f"--junitxml={tmp}"],
+        cwd=ROOT,
+        capture_output=True,
+        text=True,
+    )
+    if not tmp.exists():
+        sys.stderr.write("spec-coverage.py: pytest produced no JUnit report\n")
+        sys.stderr.write(proc.stdout[-2000:] + proc.stderr[-2000:])
+        sys.exit(2)
+    return tmp
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="spec-coverage.py", description=__doc__.split("\n\n")[0]
+    )
+    parser.add_argument(
+        "--junit", type=Path, help="pytest --junitxml report; runs pytest if omitted"
+    )
+    parser.add_argument(
+        "--tests", default="src/surf/test_*.py", help="glob of test files to scan for citations"
+    )
+    parser.add_argument("--strict", action="store_true", help="also fail on untested scenarios")
+    args = parser.parse_args(argv)
+
+    rows = scenarios_from_spec()
+    addresses = {f"{slug}#{scenario}" for slug, _, _, scenario in rows}
+    pattern = args.tests if Path(args.tests).is_absolute() else str(ROOT / args.tests)
+    cites = citations_from_tests(pattern)
+    outcomes = outcomes_from_junit(args.junit or run_pytest_junit())
+
+    by_address: dict[str, list[tuple[str, str]]] = defaultdict(list)
+    unknown: list[tuple[str, str]] = []
+    for test_id, addrs in cites.items():
+        for addr in addrs:
+            if addr in addresses:
+                by_address[addr].append((test_id, outcomes.get(test_id, "not run")))
+            else:
+                unknown.append((test_id, addr))
+
+    counts = {"passing": 0, "failing": 0, "untested": 0}
+    per_status: dict[str, dict[str, int]] = defaultdict(
+        lambda: {"passing": 0, "failing": 0, "untested": 0}
+    )
+    current = None
+    for slug, feature, status, scenario in rows:
+        if slug != current:
+            current = slug
+            print(f"\n{feature}  [{slug}, {status}]")
+        tests = by_address.get(f"{slug}#{scenario}", [])
+        if not tests:
+            state = "untested"
+        elif any(o == "passed" for _, o in tests) and not any(o == "failed" for _, o in tests):
+            state = "passing"
+        else:
+            state = "failing"
+        counts[state] += 1
+        per_status[status][state] += 1
+        mark = {"passing": "✓", "failing": "✗", "untested": "·"}[state]
+        detail = ", ".join(t for t, _ in tests)
+        print(f"  {mark} {scenario}" + (f"  [{detail}]" if detail else ""))
+
+    if unknown:
+        print("\nunknown addresses (cited by a test, absent from the spec):")
+        for test_id, addr in unknown:
+            print(f"  {test_id} -> {addr}")
+
+    total = len(rows)
+    by_status = "; ".join(
+        f"{s}: {c['passing']} passing, {c['untested']} untested" for s, c in per_status.items()
+    )
+    print(
+        f"\n{total} scenarios: {counts['passing']} passing, {counts['failing']} failing, "
+        f"{counts['untested']} untested; {len(unknown)} unknown addresses ({by_status})"
+    )
+    bad = counts["failing"] or unknown or (args.strict and counts["untested"])
+    return 1 if bad else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

surf_cli-0.8.0/spec/README.md

@@ -0,0 +1,26 @@
+# surf specification
+
+One file per feature under `features/`. Each file carries frontmatter (`feature`, `status`, and the version it was verified against or targets), an H1 with the feature name, a `Feature:` fence, and one H2 per scenario with an intent line and a `Scenario:` fence. A feature's fences concatenate into a valid `.feature` file.
+
+Every scenario in a file marked `status: shipped` was run against the version in that file's `verified-against` and prints what it says.
+
+Addresses: `surf spec/features/<slug>.md --list` lists a feature's scenarios; `surf spec/features/<slug>.md "Scenario"` returns one. The status board is `surf -f spec/features/*.md`. Tests cite a scenario with a docstring line `spec: <slug>#Scenario`; `python scripts/spec-coverage.py` reports which scenarios are demonstrated by passing tests.
+
+Fixtures: `references/` means `plugins/surf/skills/surf/references/` (`about.md`, `usage.md`, `surf.tex`, `surf.pdf`, one paper as TeX and as PDF). Other files a scenario names are given in full by the scenario's `Given` steps.
+
+| Slug | Feature | Status |
+|------|---------|--------|
+| command-line | Command line | shipped |
+| file-map | File map | shipped |
+| frontmatter-only | Frontmatter only | shipped |
+| heading-tree | Heading tree | shipped |
+| section-extraction | Section extraction | shipped |
+| link-targets | Link targets | shipped |
+| what-counts-as-a-heading | What counts as a heading | shipped |
+| tex-addressing | TeX addressing | shipped |
+| pdf-addressing | PDF addressing | shipped |
+| no-structural-index | No structural index | shipped |
+| errors-and-exit-codes | Errors and exit codes | shipped |
+| multiple-files | Multiple files | shipped |
+| filter-by-frontmatter | Filter by frontmatter | shipped |
+| frontmatter-grammar | Frontmatter grammar | shipped |

surf_cli-0.8.0/spec/features/command-line.md

@@ -0,0 +1,53 @@
+---
+feature: Command line
+status: shipped
+verified-against: "0.7.1"
+---
+# Command line
+
+The grammar of a call. The first positional is the target, a file path or a link; the second, when present, is the heading to extract.
+
+```gherkin
+Feature: Command line
+  The first positional is the target, a file path or a link.
+  The second, when present, is the heading to extract.
+```
+
+## Version flag prints the installed version
+
+```gherkin
+Scenario: Version flag prints the installed version
+  When I run "surf --version"
+  Then stdout is "surf " followed by the installed version number
+  And that version number has the form MAJOR.MINOR.PATCH
+  And the exit status is 0
+```
+
+## Positionals are target then heading
+
+The order shows in the output: the first argument is opened, the second is looked up in it.
+
+```gherkin
+Scenario: Positionals are target then heading
+  Given a file "file.md" containing:
+    """
+    # Doc
+
+    ## My Heading
+
+    Body.
+    """
+  When I run "surf file.md 'My Heading'"
+  Then stdout begins with "## My Heading"
+```
+
+## Reversed positionals name a missing file
+
+```gherkin
+Scenario: Reversed positionals name a missing file
+  Given a file "file.md" with a section "## My Heading"
+  And no file named "My Heading" exists
+  When I run "surf 'My Heading' file.md"
+  Then stderr is "Error: File not found: My Heading"
+  And the exit status is 2
+```

surf_cli-0.8.0/spec/features/errors-and-exit-codes.md

@@ -0,0 +1,67 @@
+---
+feature: Errors and exit codes
+status: shipped
+verified-against: "0.7.1"
+---
+# Errors and exit codes
+
+Exit 0 on success, including "no structural index"; 1 when the address is not found or the file cannot be read as its format; 2 on usage errors and missing files.
+
+```gherkin
+Feature: Errors and exit codes
+  Exit 0 on success, including "no structural index"; 1 when the address is not
+  found or the file cannot be read as its format; 2 on usage errors and missing files.
+```
+
+## No target
+
+```gherkin
+Scenario: No target
+  When I run "surf" with no arguments
+  Then stderr is "Error: no target specified. Use surf --help for usage."
+  And the exit status is 2
+```
+
+## Heading not found
+
+```gherkin
+Scenario: Heading not found
+  Given the fixture file "guide.md", which has no heading "Nope"
+  When I run "surf guide.md Nope"
+  Then stderr is 'Error: heading "Nope" not found in guide.md.'
+  And the exit status is 1
+```
+
+## Missing file
+
+```gherkin
+Scenario: Missing file
+  Given no file named "nope.md" exists
+  When I run "surf nope.md"
+  Then stderr is "Error: File not found: nope.md"
+  And the exit status is 2
+```
+
+## Unreadable PDF
+
+The PDF library prints its own warnings first; the error line is surf's.
+
+```gherkin
+Scenario: Unreadable PDF
+  Given a file "garbage.pdf" containing "not a pdf"
+  When I run "surf garbage.pdf --list"
+  Then stderr contains "Error: could not read PDF: garbage.pdf"
+  And stderr does not contain "Traceback"
+  And the exit status is 1
+```
+
+## Directory as target
+
+```gherkin
+Scenario: Directory as target
+  Given "." is a directory
+  When I run "surf ."
+  Then stderr is "Error: . is a directory"
+  And stderr does not contain "Traceback"
+  And the exit status is 2
+```