scry-parse 1.0.0__py3-none-any.whl

scry_parse/__init__.py

@@ -0,0 +1,42 @@
+"""scry-parse: Python parser for scry-spec v1.0 markers.
+
+Public API:
+    parse_markers(content, language=None, file="") -> ParseResult
+    validate_marker(marker) -> ValidationResult
+    mint_id(kind, name, content=None) -> str
+    BASELINE_KINDS
+    BASELINE_STATUSES
+
+Dataclasses:
+    EntryMarker
+    AnchorMarker
+    BindingMarker
+    ParseResult
+    ValidationResult
+"""
+
+from scry_parse.markers import (
+    parse_markers,
+    EntryMarker,
+    AnchorMarker,
+    BindingMarker,
+    ParseResult,
+)
+from scry_parse.validate import validate_marker, ValidationResult
+from scry_parse.mint import mint_id
+from scry_parse.consts import BASELINE_KINDS, BASELINE_STATUSES
+
+__all__ = [
+    "parse_markers",
+    "EntryMarker",
+    "AnchorMarker",
+    "BindingMarker",
+    "ParseResult",
+    "validate_marker",
+    "ValidationResult",
+    "mint_id",
+    "BASELINE_KINDS",
+    "BASELINE_STATUSES",
+]
+
+__version__ = "1.0.0"

scry_parse/consts.py

@@ -0,0 +1,19 @@
+"""Constants for scry-spec v1.0: baseline kinds, statuses, and ID regexes."""
+import re
+
+BASELINE_KINDS = (
+    "design", "pattern", "spec", "lesson", "internal",
+    "task", "milestone",
+    "report", "audit", "research",
+    "code",
+)
+
+BASELINE_STATUSES = ("draft", "active", "deprecated")
+
+# ID validation regexes per scry-spec v1.0
+# Entry/doc IDs: kind.name~8hexchars
+ID_REGEX = re.compile(r'^[a-z]+\.[a-z0-9-]+~[a-f0-9]{8}$')
+# Anchor/impl/test IDs: name~8hexchars (no dot)
+ANCHOR_ID_REGEX = re.compile(r'^[a-z0-9-]+~[a-f0-9]{8}$')
+# Loose anchor IDs used in refs: uppercase letters followed by digits (e.g. FR3, UT1)
+LOOSE_ANCHOR_REGEX = re.compile(r'^[A-Z]+[0-9]+$')

scry_parse/markers.py

@@ -0,0 +1,574 @@
+"""Marker parsing for scry-spec v1.0.
+
+Implements FR1-FR11. Recognizes:
+- @scry.entry  (block marker — declarative knowledge entry)
+- @scry.anchor (block marker — named code location)
+- @scry.bind   (line or block marker — binding / cross-reference)
+
+Comment prefix detection is inferred from the opening sentinel line.
+Legacy @scry.doc and @scry.file are not recognized per v1.0.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+import yaml
+
+
+# ---------------------------------------------------------------------------
+# Dataclasses
+# ---------------------------------------------------------------------------
+
+@dataclass
+class EntryMarker:
+    id: str
+    kind: str
+    summary: str
+    status: str
+    weight: float | None  # None → default 0.5
+    tags: list[str]
+    rationale: str | None
+    applies: str | None
+    seeded_questions: list[str]
+    depends_on: list[str]
+    implements: str | None
+    supersedes: str | None
+    file: str
+    span: tuple[int, int]  # (start_line, end_line) 1-indexed
+
+
+@dataclass
+class AnchorMarker:
+    name: str   # the {local-id} from the sentinel
+    description: str
+    seeded_questions: list[str]
+    file: str
+    span: tuple[int, int]
+
+
+@dataclass
+class BindingMarker:
+    local_id: str
+    ref: str
+    comment: str | None
+    file: str
+    offset: int              # line number (1-indexed) of the @scry.bind line
+    span: tuple[int, int] | None  # (start, end) for block form; None for single-line
+
+
+@dataclass
+class ParseResult:
+    entries: list[EntryMarker] = field(default_factory=list)
+    anchors: list[AnchorMarker] = field(default_factory=list)
+    bindings: list[BindingMarker] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Comment-prefix detection
+# ---------------------------------------------------------------------------
+
+# Maps sentinel prefix → (open_prefix, body_strip_prefix, close_suffix)
+# For markdown: body lines are raw (no prefix strip); open/close include <!-- -->
+_COMMENT_STYLES: list[tuple[str, str | None, str | None]] = [
+    # (detect_prefix, body_line_prefix_to_strip, close_suffix_hint)
+    ("<!-- ", None, " -->"),   # HTML/markdown — body is raw, strip nothing
+    ("# ",   "# ",  None),     # Python / shell
+    ("// ",  "// ", None),     # TypeScript / JS
+    ("-- ",  "-- ", None),     # SQL
+    (";; ",  ";; ", None),     # Lisp double-semi
+    ("; ",   "; ",  None),     # Lisp single-semi
+]
+
+
+def _detect_comment_style(sentinel_line: str) -> tuple[str | None, str | None]:
+    """Return (body_strip_prefix, close_suffix) from the opening sentinel line.
+
+    body_strip_prefix: prefix to strip from each body line (None = strip nothing)
+    close_suffix: suffix that appears on the closing sentinel line (e.g. ' -->')
+    """
+    for detect, body_prefix, close_suffix in _COMMENT_STYLES:
+        if detect in sentinel_line:
+            return body_prefix, close_suffix
+    return None, None
+
+
+# ---------------------------------------------------------------------------
+# Regexes
+# ---------------------------------------------------------------------------
+
+# Matches the open sentinel for block markers (entry/anchor)
+# Captures: (kind, rest_of_line)
+_BLOCK_OPEN_RE = re.compile(r'@scry\.(entry|anchor)(?!\.end)\b(.*)')
+# Matches the close sentinel
+_BLOCK_CLOSE_RE = re.compile(r'@scry\.(entry|anchor)\.end\b')
+
+# Bind markers
+_BIND_OPEN_RE = re.compile(r'@scry\.bind(?!\.end)\b(.*)')
+_BIND_CLOSE_RE = re.compile(r'@scry\.bind\.end\b')
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _strip_body_prefix(line: str, prefix: str | None) -> str:
+    """Strip the comment prefix from a single body line."""
+    if prefix is None:
+        return line
+    if line.startswith(prefix):
+        return line[len(prefix):]
+    # Handle trailing-whitespace variant (e.g. "#\n" instead of "# \n")
+    stripped = prefix.rstrip()
+    if stripped and line.startswith(stripped):
+        return line[len(stripped):].lstrip(" ")
+    return line
+
+
+def _clean_body(lines: list[str], body_strip_prefix: str | None) -> str:
+    """Strip comment prefixes from all body lines and join."""
+    cleaned = [_strip_body_prefix(ln, body_strip_prefix) for ln in lines]
+    return "".join(cleaned)
+
+
+# Matches any @scry.* marker token line that might appear inside a block body
+_SCRY_LINE_RE = re.compile(r'^\s*@scry\.\w+.*$', re.MULTILINE)
+
+
+def _parse_yaml(text: str) -> dict[str, Any] | None:
+    """Parse YAML safely; return None on failure.
+
+    Strips any embedded @scry.* marker lines before parsing (they can appear
+    inside block bodies due to FR3 positional exclusion — the parser doesn't
+    index them, but they can still break YAML).
+    """
+    # Remove embedded @scry.* lines to avoid YAML parse errors
+    cleaned = _SCRY_LINE_RE.sub("", text)
+    try:
+        data = yaml.safe_load(cleaned)
+    except yaml.YAMLError:
+        return None
+    if not isinstance(data, dict):
+        return None
+    return data
+
+
+def _coerce_list(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return [str(v) for v in value]
+    if isinstance(value, str):
+        return [value] if value.strip() else []
+    return [str(value)]
+
+
+def _coerce_str(value: Any) -> str | None:
+    if value is None:
+        return None
+    s = str(value).strip()
+    return s if s else None
+
+
+def _coerce_float(value: Any) -> float | None:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Block-span finder
+# ---------------------------------------------------------------------------
+
+def _find_block_spans(lines: list[str]) -> list[tuple[int, int, str, str]]:
+    """Find all declarative block spans (entry, anchor).
+
+    Returns list of (start_line_1idx, end_line_1idx, kind, sentinel_line).
+    Lines are 1-indexed (matching span convention).
+    """
+    spans: list[tuple[int, int, str, str]] = []
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        m = _BLOCK_OPEN_RE.search(line)
+        if not m:
+            i += 1
+            continue
+        kind = m.group(1)
+        open_line_idx = i  # 0-indexed
+        # Scan forward for matching close
+        j = i + 1
+        close_idx = None
+        while j < len(lines):
+            cm = _BLOCK_CLOSE_RE.search(lines[j])
+            if cm and cm.group(1) == kind:
+                close_idx = j
+                break
+            j += 1
+        if close_idx is None:
+            # Unterminated block — skip (FR: unterminated → 0 entries)
+            i += 1
+            continue
+        # 1-indexed span
+        spans.append((open_line_idx + 1, close_idx + 1, kind, line))
+        i = close_idx + 1
+    return spans
+
+
+def _inside_any_span(
+    line_1idx: int,
+    spans: list[tuple[int, int, str, str]],
+) -> bool:
+    """Return True if line_1idx falls inside any declarative block span."""
+    for start, end, _kind, _sentinel in spans:
+        if start <= line_1idx <= end:
+            return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Binding marker parser
+# ---------------------------------------------------------------------------
+
+def _parse_bindings(
+    lines: list[str],
+    block_spans: list[tuple[int, int, str, str]],
+    body_strip_prefix: str | None,
+    file: str,
+) -> list[BindingMarker]:
+    """Scan lines for @scry.bind markers.
+
+    FR3: skip any bind line that falls inside a declarative block span.
+    FR2: forward-scan to determine block vs single-line form.
+    """
+    result: list[BindingMarker] = []
+    i = 0
+    while i < len(lines):
+        line_1idx = i + 1
+        line = lines[i]
+
+        m = _BIND_OPEN_RE.search(line)
+        if not m:
+            i += 1
+            continue
+
+        # FR3 exclusion
+        if _inside_any_span(line_1idx, block_spans):
+            i += 1
+            continue
+
+        rest = m.group(1).strip()
+
+        # Forward-scan disambiguation (FR2):
+        # Look for @scry.bind.end before the next @scry.bind
+        is_block = False
+        close_line_idx = None
+        j = i + 1
+        while j < len(lines):
+            if _BIND_CLOSE_RE.search(lines[j]):
+                is_block = True
+                close_line_idx = j
+                break
+            if _BIND_OPEN_RE.search(lines[j]):
+                # Next bind found before close → single-line form
+                break
+            j += 1
+
+        if is_block and close_line_idx is not None:
+            # Block form: extract body lines between open and close
+            body_lines = lines[i + 1: close_line_idx]
+            body_text = _clean_body(body_lines, body_strip_prefix).strip()
+            span: tuple[int, int] | None = (line_1idx, close_line_idx + 1)
+            # Parse local_id, ref, comment from rest (open line) + body
+            local_id, ref, comment = _parse_bind_content(rest, body_text)
+            end_line = close_line_idx + 1
+            i = close_line_idx + 1
+        else:
+            # Single-line form
+            body_text = ""
+            span = None
+            local_id, ref, comment = _parse_bind_content(rest, "")
+            end_line = line_1idx
+            i += 1
+
+        if not local_id or not ref:
+            continue
+
+        # Multi-anchor expansion (FR2): ref may contain {id}#{A},{B},{C}
+        bindings = _expand_binding(local_id, ref, comment, file, line_1idx, span)
+        result.extend(bindings)
+
+    return result
+
+
+def _parse_bind_content(
+    rest: str, body_text: str
+) -> tuple[str, str, str | None]:
+    """Extract local_id, ref, and optional comment from bind marker content.
+
+    Single-line form: `@scry.bind <local_id> <ref> [# comment]`
+    Block form: open line has local_id + ref; body has comment.
+    """
+    # Try to parse from the rest (tokens after @scry.bind)
+    tokens = rest.split()
+    local_id = tokens[0] if len(tokens) >= 1 else ""
+    ref = tokens[1] if len(tokens) >= 2 else ""
+
+    # Comment: anything after the second token on the open line,
+    # or the body text for block form
+    if len(tokens) >= 3:
+        comment: str | None = " ".join(tokens[2:]).lstrip("# ").strip()
+    elif body_text:
+        comment = body_text
+    else:
+        comment = None
+
+    if comment == "":
+        comment = None
+
+    return local_id, ref, comment
+
+
+def _expand_binding(
+    local_id: str,
+    ref: str,
+    comment: str | None,
+    file: str,
+    offset: int,
+    span: tuple[int, int] | None,
+) -> list[BindingMarker]:
+    """Expand multi-anchor refs (FR2).
+
+    If ref is `{artifact}#{A},{B},{C}`, expand to N BindingMarker records.
+    Range syntax `{A}-{B}` is treated as a single anchor name (no expansion).
+    """
+    # Check for comma-separated loose anchors in the fragment
+    # Pattern: something~hash#ANCHOR1,ANCHOR2,...
+    # or just: something#ANCHOR1,ANCHOR2,...
+    comma_re = re.compile(r'^(.+)#([^,#]+(?:,[^,#]+)+)$')
+    m = comma_re.match(ref)
+    if m:
+        base = m.group(1)
+        anchors_str = m.group(2)
+        anchors = [a.strip() for a in anchors_str.split(",")]
+        # Only expand if these look like loose anchors (LOOSE_ANCHOR_REGEX)
+        from scry_parse.consts import LOOSE_ANCHOR_REGEX
+        if all(LOOSE_ANCHOR_REGEX.match(a) for a in anchors):
+            return [
+                BindingMarker(
+                    local_id=local_id,
+                    ref=f"{base}#{anchor}",
+                    comment=comment,
+                    file=file,
+                    offset=offset,
+                    span=span,
+                )
+                for anchor in anchors
+            ]
+
+    # Single binding
+    return [BindingMarker(
+        local_id=local_id,
+        ref=ref,
+        comment=comment,
+        file=file,
+        offset=offset,
+        span=span,
+    )]
+
+
+# ---------------------------------------------------------------------------
+# Main parser
+# ---------------------------------------------------------------------------
+
+def parse_markers(
+    content: str,
+    language: str | None = None,
+    file: str = "",
+) -> ParseResult:
+    """Parse all scry markers from file content.
+
+    Args:
+        content: The raw file content to parse.
+        language: Optional language hint (currently unused; style is
+                  inferred from the sentinel line).
+        file: Optional file path to record in markers.
+
+    Returns:
+        ParseResult with entries, anchors, and bindings.
+    """
+    result = ParseResult()
+    if "@scry." not in content:
+        return result
+
+    lines = content.splitlines(keepends=True)
+
+    # First pass: find all declarative block spans
+    block_spans = _find_block_spans(lines)
+
+    # Second pass: parse each block
+    for start_1idx, end_1idx, kind, sentinel_line in block_spans:
+        body_strip_prefix, _close_suffix = _detect_comment_style(sentinel_line)
+
+        # Body lines (between open and close, exclusive)
+        body_lines = lines[start_1idx: end_1idx - 1]  # 0-indexed slice
+        body_text = _clean_body(body_lines, body_strip_prefix)
+
+        if kind == "anchor":
+            _parse_anchor_block(
+                sentinel_line, body_text, file,
+                (start_1idx, end_1idx), result
+            )
+        elif kind == "entry":
+            _parse_entry_block(
+                body_text, file, (start_1idx, end_1idx), result
+            )
+
+    # Third pass: parse binding markers
+    bindings = _parse_bindings(lines, block_spans, None, file)
+
+    # For bindings, we need to infer the body_strip_prefix per bind line.
+    # Re-do with proper per-line prefix detection.
+    result.bindings = _parse_bindings_with_prefix(lines, block_spans, file)
+
+    return result
+
+
+def _parse_bindings_with_prefix(
+    lines: list[str],
+    block_spans: list[tuple[int, int, str, str]],
+    file: str,
+) -> list[BindingMarker]:
+    """Parse bindings, detecting comment prefix per bind sentinel line."""
+    result: list[BindingMarker] = []
+    i = 0
+    while i < len(lines):
+        line_1idx = i + 1
+        line = lines[i]
+
+        m = _BIND_OPEN_RE.search(line)
+        if not m:
+            i += 1
+            continue
+
+        # FR3 exclusion
+        if _inside_any_span(line_1idx, block_spans):
+            i += 1
+            continue
+
+        # Detect comment style from this line
+        body_strip_prefix, _close_suffix = _detect_comment_style(line)
+        rest = m.group(1).strip()
+
+        # Forward-scan disambiguation (FR2)
+        is_block = False
+        close_line_idx = None
+        j = i + 1
+        while j < len(lines):
+            if _BIND_CLOSE_RE.search(lines[j]):
+                is_block = True
+                close_line_idx = j
+                break
+            if _BIND_OPEN_RE.search(lines[j]):
+                break
+            j += 1
+
+        if is_block and close_line_idx is not None:
+            body_lines = lines[i + 1: close_line_idx]
+            body_text = _clean_body(body_lines, body_strip_prefix).strip()
+            span: tuple[int, int] | None = (line_1idx, close_line_idx + 1)
+            local_id, ref, comment = _parse_bind_content(rest, body_text)
+            i = close_line_idx + 1
+        else:
+            span = None
+            local_id, ref, comment = _parse_bind_content(rest, "")
+            i += 1
+
+        if not local_id or not ref:
+            continue
+
+        bindings = _expand_binding(local_id, ref, comment, file, line_1idx, span)
+        result.extend(bindings)
+
+    return result
+
+
+def _parse_anchor_block(
+    sentinel_line: str,
+    body_text: str,
+    file: str,
+    span: tuple[int, int],
+    result: ParseResult,
+) -> None:
+    """Parse an @scry.anchor block and append to result."""
+    # Extract name from sentinel line: `@scry.anchor {name}`
+    m = _BLOCK_OPEN_RE.search(sentinel_line)
+    if not m:
+        return
+    rest = m.group(2).strip()
+    # Name is the first token after the sentinel
+    name_part = rest.split()[0] if rest.split() else ""
+    if not name_part:
+        return
+
+    data = _parse_yaml(body_text) or {}
+    description = _coerce_str(data.get("description")) or ""
+    seeded_questions = _coerce_list(data.get("seeded_questions"))
+
+    result.anchors.append(AnchorMarker(
+        name=name_part,
+        description=description,
+        seeded_questions=seeded_questions,
+        file=file,
+        span=span,
+    ))
+
+
+def _parse_entry_block(
+    body_text: str,
+    file: str,
+    span: tuple[int, int],
+    result: ParseResult,
+) -> None:
+    """Parse a @scry.entry block and append to result."""
+    data = _parse_yaml(body_text)
+    if data is None:
+        # Invalid YAML — fail gracefully, produce 0 entries
+        return
+
+    marker_id = _coerce_str(data.get("id"))
+    if not marker_id:
+        return
+
+    kind = _coerce_str(data.get("kind")) or "internal"
+    summary = _coerce_str(data.get("summary")) or ""
+    status = _coerce_str(data.get("status")) or "draft"
+    weight = _coerce_float(data.get("weight"))
+    tags = _coerce_list(data.get("tags"))
+    rationale = _coerce_str(data.get("rationale"))
+    applies = _coerce_str(data.get("applies"))
+    seeded_questions = _coerce_list(data.get("seeded_questions"))
+    depends_on = _coerce_list(data.get("depends_on"))
+    implements = _coerce_str(data.get("implements"))
+    supersedes = _coerce_str(data.get("supersedes"))
+
+    result.entries.append(EntryMarker(
+        id=marker_id,
+        kind=kind,
+        summary=summary,
+        status=status,
+        weight=weight,
+        tags=tags,
+        rationale=rationale,
+        applies=applies,
+        seeded_questions=seeded_questions,
+        depends_on=depends_on,
+        implements=implements,
+        supersedes=supersedes,
+        file=file,
+        span=span,
+    ))

scry_parse/mint.py

@@ -0,0 +1,34 @@
+"""ID generation for scry-spec v1.0 markers."""
+from __future__ import annotations
+
+import hashlib
+import secrets
+
+
+def mint_id(kind: str, name: str, content: str | None = None) -> str:
+    """Generate a spec-conformant marker ID: '{kind}.{name}~{hash}'.
+
+    For entry markers, the full ID is '{kind}.{name}~{8hexchars}'.
+    For anchor/impl/test markers, the convention is '{name}~{8hexchars}'
+    (no dot prefix) — callers should pass name only without kind in that case,
+    or use kind="" and name="name~...".
+
+    Args:
+        kind: The marker kind (e.g. "design", "spec"). Use "" for anchors/impls/tests
+              where the ID format is just '{name}~{hash}'.
+        name: The human-readable name portion (e.g. "auth-flow").
+        content: Optional content for deterministic hash. If None, a random
+                 4-byte hex string is generated.
+
+    Returns:
+        A spec-conformant ID string.
+    """
+    if content is not None:
+        hash_hex = hashlib.sha256(content.encode()).hexdigest()[:8]
+    else:
+        hash_hex = secrets.token_hex(4)  # 4 bytes = 8 hex chars
+
+    if kind:
+        return f"{kind}.{name}~{hash_hex}"
+    else:
+        return f"{name}~{hash_hex}"

scry_parse/validate.py

@@ -0,0 +1,116 @@
+"""Validation for parsed scry markers per scry-spec v1.0."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from scry_parse.consts import (
+    ID_REGEX,
+    ANCHOR_ID_REGEX,
+    BASELINE_KINDS,
+    BASELINE_STATUSES,
+)
+from scry_parse.markers import EntryMarker, AnchorMarker, BindingMarker
+
+
+@dataclass
+class ValidationResult:
+    valid: bool
+    errors: list[str]
+    warnings: list[str]
+
+
+def validate_marker(marker: EntryMarker | AnchorMarker | BindingMarker) -> ValidationResult:
+    """Validate a parsed marker against spec rules.
+
+    Returns a ValidationResult with errors (spec violations) and warnings
+    (non-standard but tolerated values).
+    """
+    if isinstance(marker, EntryMarker):
+        return _validate_entry(marker)
+    if isinstance(marker, AnchorMarker):
+        return _validate_anchor(marker)
+    if isinstance(marker, BindingMarker):
+        return _validate_binding(marker)
+    return ValidationResult(
+        valid=False,
+        errors=[f"Unknown marker type: {type(marker).__name__}"],
+        warnings=[],
+    )
+
+
+def _validate_entry(marker: EntryMarker) -> ValidationResult:
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    # id must match ID_REGEX
+    if not marker.id or not ID_REGEX.match(marker.id):
+        errors.append(
+            f"id {marker.id!r} does not match expected pattern "
+            f"'<kind>.<name>~<8hexchars>' (got {marker.id!r})"
+        )
+
+    # kind must be non-empty; warn if not in BASELINE_KINDS
+    if not marker.kind or not marker.kind.strip():
+        errors.append("kind must be a non-empty string")
+    elif marker.kind not in BASELINE_KINDS:
+        warnings.append(
+            f"kind {marker.kind!r} is not in the baseline kinds list; "
+            f"expected one of: {', '.join(BASELINE_KINDS)}"
+        )
+
+    # summary must be non-empty
+    if not marker.summary or not marker.summary.strip():
+        errors.append("summary must be non-empty")
+
+    # status must be non-empty; warn if not in BASELINE_STATUSES
+    if not marker.status or not marker.status.strip():
+        errors.append("status must be a non-empty string")
+    elif marker.status not in BASELINE_STATUSES:
+        warnings.append(
+            f"status {marker.status!r} is not in the baseline statuses list; "
+            f"expected one of: {', '.join(BASELINE_STATUSES)}"
+        )
+
+    valid = len(errors) == 0
+    return ValidationResult(valid=valid, errors=errors, warnings=warnings)
+
+
+def _validate_anchor(marker: AnchorMarker) -> ValidationResult:
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    # name must match ANCHOR_ID_REGEX
+    if not marker.name or not ANCHOR_ID_REGEX.match(marker.name):
+        errors.append(
+            f"name {marker.name!r} does not match expected pattern "
+            f"'<name>~<8hexchars>' (got {marker.name!r})"
+        )
+
+    # description must be non-empty
+    if not marker.description or not marker.description.strip():
+        errors.append("description must be non-empty")
+
+    # seeded_questions must be declared (can be empty list)
+    # It's a list type so always present; no additional check needed.
+
+    valid = len(errors) == 0
+    return ValidationResult(valid=valid, errors=errors, warnings=warnings)
+
+
+def _validate_binding(marker: BindingMarker) -> ValidationResult:
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    # local_id must match ANCHOR_ID_REGEX
+    if not marker.local_id or not ANCHOR_ID_REGEX.match(marker.local_id):
+        errors.append(
+            f"local_id {marker.local_id!r} does not match expected pattern "
+            f"'<name>~<8hexchars>' (got {marker.local_id!r})"
+        )
+
+    # ref must be non-empty
+    if not marker.ref or not marker.ref.strip():
+        errors.append("ref must be non-empty")
+
+    valid = len(errors) == 0
+    return ValidationResult(valid=valid, errors=errors, warnings=warnings)

scry_parse-1.0.0.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: scry-parse
+Version: 1.0.0
+Summary: Python parser for scry-spec v1.0 markers
+Project-URL: Repository, https://github.com/prmichaelsen/scry-spec
+License: MIT License
+        
+        Copyright (c) 2026 reflection
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# scry-parse
+
+Python parser for the [scry-spec v1.0](https://github.com/prmichaelsen/scry-spec) marker format.
+
+## Install
+
+```bash
+uv pip install scry-parse
+# or:
+pip install scry-parse
+```
+
+## Usage
+
+```python
+from scry_parse import parse_markers, validate_marker, mint_id, BASELINE_KINDS, BASELINE_STATUSES
+
+# Parse markers from file content
+with open("my_file.md") as f:
+    content = f.read()
+
+result = parse_markers(content)
+
+for entry in result.entries:
+    print(entry.id, entry.kind, entry.summary)
+
+for anchor in result.anchors:
+    print(anchor.name, anchor.description)
+
+for binding in result.bindings:
+    print(binding.local_id, binding.ref)
+
+# Validate a parsed marker
+vr = validate_marker(result.entries[0])
+if not vr.valid:
+    print(vr.errors)
+
+# Generate a new marker ID
+entry_id = mint_id("design", "auth-flow")          # random hash
+entry_id = mint_id("design", "auth-flow", content)  # deterministic hash
+```
+
+## Supported comment styles
+
+- HTML/Markdown: `<!-- @scry.entry ... @scry.entry.end -->`
+- Python/Shell: `# @scry.entry ... # @scry.entry.end`
+- TypeScript/JS: `// @scry.entry ... // @scry.entry.end`
+- SQL: `-- @scry.entry ... -- @scry.entry.end`
+- Lisp: `;; @scry.entry ... ;; @scry.entry.end`
+
+## License
+
+MIT — see [LICENSE](LICENSE).

scry_parse-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+scry_parse/__init__.py,sha256=GiNrb0jdZ2aXFwP-mNgRKM6X2_ek5chaGxBhCxq2Mnk,915
+scry_parse/consts.py,sha256=ILXHa9pzv8WFXXtCNTZYLAmDN58zmw8nhW5PCm-qj38,675
+scry_parse/markers.py,sha256=iSkS-jHSxD1If0btrs91-9jIU3iaKYxKWgCLD_AVd3k,18003
+scry_parse/mint.py,sha256=jQ8oI-qUb_HyEljSGGU4CAL6kXMyWgmo7NjglDbf0RE,1197
+scry_parse/validate.py,sha256=BHe9I9t5xf9FEcecOYb3Q41FHGrA6SYGOkPVxpbjluM,3893
+scry_parse-1.0.0.dist-info/METADATA,sha256=VkJZ4nW2MgOx4vhvUdSaOTFdL19Z7177yGBezAnsA94,2857
+scry_parse-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+scry_parse-1.0.0.dist-info/licenses/LICENSE,sha256=9j-1QE48XqQoy_Sh9nueXMhr7z2niD1G9tS9QM9Zb_Q,1067
+scry_parse-1.0.0.dist-info/RECORD,,

scry_parse-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

scry_parse-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 reflection
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.