plan-doc 0.1.0__py3-none-any.whl

plan_doc-0.1.0.dist-info/METADATA

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: plan-doc
+Version: 0.1.0
+Summary: Typed parser for plan-file YAML frontmatter (schema v1) — strict validation, first-block-only extraction, foreign-document discrimination
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Dynamic: license-file
+
+# plan-doc
+
+Typed parser for plan-file YAML frontmatter (schema v1). Extracts the
+machine-readable fields a plan-driven-PR workflow needs — `template`,
+`disposal`, `branch`, a planner-handoff `dossier` block — from markdown
+plan documents, with strict validation and loud failures.
+
+```python
+from pathlib import Path
+from plan_doc import PlanDoc, PlanDocError, NonDraftPrFrontmatterError
+
+doc = PlanDoc.from_path(Path("docs/plans/my-plan.md"))
+if doc.disposal == "delete-on-merge":
+    ...
+if doc.dossier is not None:
+    files = doc.dossier.get("files", [])
+```
+
+## What it enforces
+
+- **Schema v1.** `plan_schema: 1` is required; `template`, `disposal`,
+  `phase`, `cleanup_trigger`, `ticket`, `branch`, `tdd_mode`, `dossier`
+  are the only other top-level keys. Unknown keys raise `PlanDocError` —
+  this is the typo guard (`dispozal` fails loud).
+- **First-block-only parsing.** Only a `---`...`---` block at the very
+  top of the file is frontmatter. Body-level `---` horizontal rules are
+  never split on.
+- **Foreign-document discrimination.** Valid frontmatter with no
+  `plan_schema` and no plan indicator fields raises the typed subclass
+  `NonDraftPrFrontmatterError`, so callers can treat non-plan documents
+  leniently without swallowing real validation errors.
+- **No frontmatter at all** raises `PlanDocError` with an actionable
+  message (add `plan_schema: 1`).
+
+## Dependency note
+
+`pyyaml` is a hard dependency, and the module *also* keeps a minimal
+no-yaml fallback parser (`_parse_yaml_minimal`) for simple `key: value`
+frontmatter. Both halves are deliberate: the upstream source of this
+module runs in a zero-pip environment and relies on the fallback, while
+the package declares full functionality. The fallback is covered by
+tests here — don't remove either half.
+
+## Provenance
+
+Extracted verbatim (code byte-identical, module docstring reframed) from
+the draft-pr skill of the m0j0d portfolio plugin, where the vendored copy
+remains the operational source of truth. This package mirrors it at
+release points.
+
+Pool purity rule: transport-free, LLM-agnostic, no secrets. Pure parsing;
+the only I/O is `Path.read_text` in `PlanDoc.from_path`.
+
+## License
+
+MIT

plan_doc-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+plan_doc.py,sha256=_mt8zPveaop9xNGy74j4swpFBCwW7F65x8jCvUzM9cA,19116
+plan_doc-0.1.0.dist-info/licenses/LICENSE,sha256=AHOl9dkJ8tFtExkZkApUx1vccbMmXPw7i8AhZqSAl6U,1062
+plan_doc-0.1.0.dist-info/METADATA,sha256=m7vaRGgHuVRtR_koYSUQy6KKzP0CgOcjjyuzs7xvv_g,3023
+plan_doc-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+plan_doc-0.1.0.dist-info/top_level.txt,sha256=2kQZdRpU55PG0m2UVh0zLsr9ZqTkGEkK5cS-CdxjS9o,9
+plan_doc-0.1.0.dist-info/RECORD,,

plan_doc-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

plan_doc-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 m0j0d
+
+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.

plan_doc-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+plan_doc

plan_doc.py

@@ -0,0 +1,507 @@
+"""plan_doc — typed parser for plan-file YAML frontmatter (schema v1).
+
+Provenance: extracted verbatim from the draft-pr skill of the m0j0d
+portfolio plugin (``plugin/skills/draft-pr/scripts/plan_doc.py``), where it
+is the single source of truth for extracting structured fields from
+plan-driven-PR documents. The vendored plugin copy remains operational
+there; this package mirrors it at release points.
+
+Design decisions:
+- YAML frontmatter for machine-readable fields; markdown body for human content.
+- First-`---`-block-only parser: extracts ONLY the first ``---``...``---`` block
+  at the very top of the file. Does NOT split on body-level ``---`` horizontal
+  rules (common as horizontal rules in real-world plan bodies).
+- When NO frontmatter block is present, raises ``PlanDocError`` with an actionable
+  message directing the author to add a ``plan_schema: 1`` frontmatter block.
+  Unmigrated files fail loud.
+- When a frontmatter block IS present, validation is strict: missing required
+  fields and unknown fields both raise ``PlanDocError``.
+
+Schema v1 fields:
+    plan_schema  int     required when block present; must equal 1
+    template     str     optional; values: "minimal", "standard"
+    disposal     str     optional; values: "delete-on-merge", "deferred"
+    phase        str     optional
+    cleanup_trigger str  optional
+    ticket       str     optional
+    branch       str     optional
+    tdd_mode     str     optional
+    dossier      dict    optional; Thinker-Doer handoff block (schema
+                         defined by the source portfolio's
+                         thinker-doer-dossier-handoff pattern). Lightly
+                         validated: must be a mapping; recognized sub-keys
+                         (files, symbols, patterns, exclusions, not_in_scope,
+                         open_questions, escape_log, hot_spans,
+                         thinker_tokens_used) must have the right container
+                         type when present.
+
+Ad-hoc top-level key policy:
+    ONLY the fields listed above are allowed as top-level frontmatter keys.
+    Ad-hoc keys like ``owner``, ``created``, ``revised``, ``sequencing``,
+    ``problem_one_liner``, ``status`` etc. are NOT whitelisted and raise
+    ``PlanDocError``. Rationale: preserves the typo guard (``dispozal`` must
+    still raise) and the "plans don't invent top-level keys" discipline.
+    The ``dossier:`` block is the designed mechanism for planner metadata;
+    ad-hoc keys belong inside it or in the plan body.
+
+Usage::
+
+    from plan_doc import PlanDoc, PlanDocError, NonDraftPrFrontmatterError
+
+    doc = PlanDoc.from_path(Path("docs/plans/my-plan.md"))
+    if doc.template == "minimal":
+        ...
+    if doc.disposal == "delete-on-merge":
+        ...
+    if doc.dossier is not None:
+        files = doc.dossier.get("files", [])
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+try:
+    import yaml as _yaml
+    _YAML_AVAILABLE = True
+except ImportError:
+    _YAML_AVAILABLE = False
+
+
+# ---------------------------------------------------------------------------
+# Error types
+# ---------------------------------------------------------------------------
+
+
+class PlanDocError(ValueError):
+    """Raised when a plan frontmatter block is present but malformed or invalid."""
+
+
+class NonDraftPrFrontmatterError(PlanDocError):
+    """Raised when frontmatter is present but belongs to a foreign (non-draft-pr)
+    document schema — i.e. it has NO ``plan_schema`` key AND contains NONE of the
+    known draft-pr indicator fields.
+
+    Callers catch this specific subclass and construct a field-less ``PlanDoc``
+    (``template=None``, ``disposal=None``, body intact) — foreign documents get
+    standard-template treatment and no disposal step. All other ``PlanDocError``
+    subclasses propagate as strict validation failures.
+    """
+
+
+# ---------------------------------------------------------------------------
+# Schema constants
+# ---------------------------------------------------------------------------
+
+_SUPPORTED_SCHEMA_VERSIONS = {1}
+_ALLOWED_DISPOSAL_VALUES = {"delete-on-merge", "deferred"}
+_KNOWN_FIELDS = frozenset({
+    "plan_schema",
+    "template",
+    "disposal",
+    "phase",
+    "cleanup_trigger",
+    "ticket",
+    "branch",
+    "tdd_mode",
+    # Thinker-Doer handoff block (atlas/patterns/thinker-doer-dossier-handoff.md).
+    # Recognized and lightly validated; see _validate_dossier().
+    "dossier",
+})
+
+# Sub-keys of the dossier block that must be lists when present.
+# Extra sub-keys beyond this set are allowed (lenient validation — the pattern
+# permits keys like hot_spans, thinker_tokens_used without a schema version bump).
+_DOSSIER_LIST_KEYS = frozenset({
+    "files",
+    "symbols",
+    "patterns",
+    "exclusions",
+    "not_in_scope",
+    "open_questions",
+    "escape_log",
+})
+
+# Fields (excluding plan_schema itself) that positively identify a draft-pr
+# document.  A frontmatter block that has NONE of these AND no plan_schema is
+# treated as a "foreign" document (infra-099-style, loki-exec-light-style) and
+# raises NonDraftPrFrontmatterError, which callers tolerate as a field-less PlanDoc.
+_DRAFT_PR_INDICATOR_FIELDS = frozenset({
+    "template",
+    "disposal",
+    "phase",
+    "cleanup_trigger",
+    "ticket",
+    "branch",
+    "tdd_mode",
+})
+
+
+# ---------------------------------------------------------------------------
+# PlanDoc dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class PlanDoc:
+    """Typed representation of a /draft-pr plan document.
+
+    Fields are populated from YAML frontmatter. When no frontmatter block is
+    present, ``from_text`` / ``from_path`` raise ``PlanDocError`` with an
+    actionable message directing the author to add ``plan_schema: 1``.
+
+    Foreign-schema docs (valid YAML, no ``plan_schema``, no draft-pr indicator
+    fields) raise ``NonDraftPrFrontmatterError`` — callers catch this specific
+    subclass and construct a field-less ``PlanDoc(template=None, disposal=None,
+    body=text)`` for standard-template treatment with no disposal step.
+
+    The raw markdown body (everything after the closing frontmatter ``---``) is
+    available as ``.body``.
+    """
+
+    # Schema version — required when frontmatter block is present
+    plan_schema: Optional[int] = None
+
+    # Core lifecycle fields
+    template: Optional[str] = None
+    disposal: Optional[str] = None
+
+    # Optional metadata
+    phase: Optional[str] = None
+    cleanup_trigger: Optional[str] = None
+    ticket: Optional[str] = None
+    branch: Optional[str] = None
+    tdd_mode: Optional[str] = None
+
+    # Thinker-Doer handoff block (atlas/patterns/thinker-doer-dossier-handoff.md).
+    # None when not present in frontmatter; populated dict when present.
+    dossier: Optional[dict] = field(default=None, repr=False)
+
+    # Raw body text (everything after the frontmatter block, or full text for
+    # legacy plans)
+    body: str = field(default="", repr=False)
+
+    # Internal flag: True when loaded from frontmatter (strict mode),
+    # False when constructed directly (e.g. field-less PlanDoc for foreign docs)
+    _from_frontmatter: bool = field(default=False, repr=False)
+
+    # -----------------------------------------------------------------------
+    # Factory methods
+    # -----------------------------------------------------------------------
+
+    @classmethod
+    def from_path(cls, path: Path) -> PlanDoc:
+        """Load a PlanDoc from a file on disk.
+
+        Parameters
+        ----------
+        path:
+            Absolute path to the plan markdown file.
+
+        Returns
+        -------
+        PlanDoc
+            Populated from frontmatter (strict validation).
+
+        Raises
+        ------
+        PlanDocError
+            When no frontmatter block is present, or when the frontmatter block
+            is malformed, has missing required fields, has invalid field values,
+            or has unknown fields.
+        FileNotFoundError
+            When the file does not exist.
+        """
+        text = Path(path).read_text(encoding="utf-8")
+        try:
+            return cls.from_text(text)
+        except PlanDocError as exc:
+            # Re-raise with file path context if not already present.
+            # Use type(exc)(...) to preserve the exact subclass (e.g.
+            # NonDraftPrFrontmatterError) so callers that discriminate on
+            # the subclass work identically whether they call from_path or
+            # from_text.
+            msg = str(exc)
+            if str(path) not in msg and Path(path).name not in msg:
+                raise type(exc)(f"{path}: {msg}") from exc
+            raise
+
+    @classmethod
+    def from_text(cls, text: str) -> PlanDoc:
+        """Load a PlanDoc from raw plan text.
+
+        Parameters
+        ----------
+        text:
+            Raw content of the plan markdown file.
+
+        Returns
+        -------
+        PlanDoc
+            Populated from frontmatter (strict validation).
+
+        Raises
+        ------
+        PlanDocError
+            When no frontmatter block is present at the top of the file, or
+            when the frontmatter block is present but malformed or invalid.
+            Unmigrated plans (no leading ``---`` block) raise with an actionable
+            message: add ``plan_schema: 1``; see references/frontmatter-schema.md.
+        """
+        fm_data, body = _extract_frontmatter(text)
+        if fm_data is not None:
+            return cls._from_frontmatter_dict(fm_data, body)
+        else:
+            raise PlanDocError(
+                "No frontmatter block found at the top of this plan file. "
+                "Add a 'plan_schema: 1' frontmatter block to the top of the file. "
+                "See references/frontmatter-schema.md for the full schema."
+            )
+
+    # -----------------------------------------------------------------------
+    # Internal construction
+    # -----------------------------------------------------------------------
+
+    @classmethod
+    def _from_frontmatter_dict(
+        cls, data: dict, body: str
+    ) -> PlanDoc:
+        """Construct a PlanDoc from a parsed frontmatter dict (strict mode).
+
+        Raises NonDraftPrFrontmatterError when the frontmatter block looks like a
+        foreign (non-draft-pr) document: no ``plan_schema`` key AND none of the
+        known draft-pr indicator fields present.  This lets callers fall back to
+        legacy regex extraction for infrastructure plans (infra-099-style,
+        loki-exec-light-style) without silently swallowing real validation errors.
+
+        Raises PlanDocError on:
+        - missing required field ``plan_schema`` (when draft-pr indicator fields
+          ARE present — this is a malformed draft-pr plan, not a foreign doc)
+        - unsupported ``plan_schema`` value
+        - invalid ``disposal`` value
+        - unknown fields (when plan_schema is present)
+        """
+        # Foreign-document discriminator: no plan_schema AND no draft-pr indicator
+        # fields → this is not a draft-pr plan at all (e.g. infra-099, loki-exec).
+        # Raise the typed subclass so callers can catch ONLY this case.
+        has_plan_schema = "plan_schema" in data
+        has_indicator_fields = bool(set(data.keys()) & _DRAFT_PR_INDICATOR_FIELDS)
+        if not has_plan_schema and not has_indicator_fields:
+            raise NonDraftPrFrontmatterError(
+                "Frontmatter block present but contains no 'plan_schema' key and "
+                "no draft-pr indicator fields — this appears to be a non-draft-pr "
+                "document. Known draft-pr fields: "
+                f"{sorted(_DRAFT_PR_INDICATOR_FIELDS | {'plan_schema'})}"
+            )
+
+        # Unknown field check (only for plans that have at least one draft-pr marker)
+        unknown = set(data.keys()) - _KNOWN_FIELDS
+        if unknown:
+            names = ", ".join(sorted(unknown))
+            raise PlanDocError(
+                f"Unknown frontmatter field(s): {names}. "
+                f"Known fields: {sorted(_KNOWN_FIELDS)}"
+            )
+
+        # plan_schema is required when frontmatter block is present and we know
+        # this is a draft-pr plan (indicator fields are present)
+        if not has_plan_schema:
+            raise PlanDocError(
+                "Frontmatter block present but 'plan_schema' field is missing. "
+                "Add 'plan_schema: 1' to the frontmatter block."
+            )
+
+        schema_version = data["plan_schema"]
+        if schema_version not in _SUPPORTED_SCHEMA_VERSIONS:
+            raise PlanDocError(
+                f"Unsupported plan_schema value: {schema_version!r}. "
+                f"Supported versions: {sorted(_SUPPORTED_SCHEMA_VERSIONS)}"
+            )
+
+        # Validate disposal value if provided
+        disposal = data.get("disposal")
+        if disposal is not None and disposal not in _ALLOWED_DISPOSAL_VALUES:
+            raise PlanDocError(
+                f"Invalid disposal value: {disposal!r}. "
+                f"Allowed values: {sorted(_ALLOWED_DISPOSAL_VALUES)}"
+            )
+
+        # Validate and extract dossier block if present
+        dossier = data.get("dossier")
+        if dossier is not None:
+            _validate_dossier(dossier)
+
+        return cls(
+            plan_schema=schema_version,
+            template=data.get("template"),
+            disposal=disposal,
+            phase=data.get("phase"),
+            cleanup_trigger=data.get("cleanup_trigger"),
+            ticket=data.get("ticket"),
+            branch=data.get("branch"),
+            tdd_mode=data.get("tdd_mode"),
+            dossier=dossier,
+            body=body,
+            _from_frontmatter=True,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Frontmatter extraction (first-block-only parser)
+# ---------------------------------------------------------------------------
+
+
+def _extract_frontmatter(text: str) -> tuple[Optional[dict], str]:
+    """Extract the first ``---``...``---`` YAML frontmatter block from text.
+
+    Rules:
+    - The file MUST begin with a ``---`` line (optionally with trailing
+      whitespace) for a frontmatter block to be recognized.
+    - The parser extracts ONLY the first such block. Everything after the
+      closing ``---`` line is returned verbatim as the body.
+    - Does NOT split on body-level ``---`` horizontal rules — those are part
+      of the body.
+    - Returns (None, text) when no frontmatter block is present at the top.
+
+    Parameters
+    ----------
+    text:
+        Raw file content.
+
+    Returns
+    -------
+    (dict, str) when a frontmatter block is found and parsed.
+    (None, text) when no frontmatter block is present.
+
+    Raises
+    ------
+    PlanDocError
+        When a frontmatter block opening ``---`` is found at the top but the
+        YAML inside is malformed or the closing ``---`` is never found.
+    """
+    lines = text.splitlines(keepends=True)
+    if not lines:
+        return None, text
+
+    # The first line must be exactly "---" (with optional trailing whitespace)
+    first_line = lines[0].rstrip()
+    if first_line != "---":
+        return None, text
+
+    # Find the closing --- (starting from line 1, skipping the opening ---)
+    closing_idx = None
+    for i in range(1, len(lines)):
+        if lines[i].rstrip() == "---":
+            closing_idx = i
+            break
+
+    if closing_idx is None:
+        raise PlanDocError(
+            "Frontmatter block opened with '---' but no closing '---' found."
+        )
+
+    # Extract the YAML content between the two --- markers
+    fm_lines = lines[1:closing_idx]
+    fm_text = "".join(fm_lines)
+
+    # Parse the YAML
+    data = _parse_yaml(fm_text)
+
+    # Everything after the closing --- is the body
+    body_lines = lines[closing_idx + 1:]
+    body = "".join(body_lines)
+
+    return data, body
+
+
+def _parse_yaml(text: str) -> dict:
+    """Parse YAML text and return a dict.
+
+    Uses PyYAML when available; falls back to a minimal parser for simple
+    key: value pairs.
+
+    Raises
+    ------
+    PlanDocError
+        When the YAML is malformed.
+    """
+    if _YAML_AVAILABLE:
+        try:
+            result = _yaml.safe_load(text)
+        except _yaml.YAMLError as exc:
+            raise PlanDocError(f"Malformed YAML in frontmatter: {exc}") from exc
+        if result is None:
+            return {}
+        if not isinstance(result, dict):
+            raise PlanDocError(
+                f"Frontmatter YAML must be a mapping (dict), got {type(result).__name__}"
+            )
+        return result
+    else:
+        # Minimal fallback parser for simple key: value pairs
+        return _parse_yaml_minimal(text)
+
+
+def _parse_yaml_minimal(text: str) -> dict:
+    """Minimal YAML parser for simple ``key: value`` pairs (no PyYAML fallback).
+
+    Handles only scalar values. Raises PlanDocError on anything complex.
+    """
+    result = {}
+    for line_num, line in enumerate(text.splitlines(), start=1):
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if ":" not in line:
+            raise PlanDocError(
+                f"Malformed YAML in frontmatter at line {line_num}: "
+                f"expected 'key: value', got {line!r}"
+            )
+        key, _, value = line.partition(":")
+        key = key.strip()
+        value = value.strip()
+        # Try to parse simple int values
+        if value.isdigit():
+            result[key] = int(value)
+        else:
+            # Strip surrounding quotes if present
+            if (value.startswith('"') and value.endswith('"')) or \
+               (value.startswith("'") and value.endswith("'")):
+                value = value[1:-1]
+            result[key] = value
+    return result
+
+
+def _validate_dossier(dossier: object) -> None:
+    """Light structural validation of the dossier block.
+
+    Rules (lenient by design — the pattern allows extension without version bumps):
+    - ``dossier`` must be a mapping (dict), not a scalar or list.
+    - Each of the recognized list-typed sub-keys (``files``, ``symbols``,
+      ``patterns``, ``exclusions``, ``not_in_scope``, ``open_questions``,
+      ``escape_log``) must be a list when present.
+    - Extra sub-keys beyond the recognized set are allowed; over-constraining
+      would break plans that use valid pattern extensions.
+
+    Raises
+    ------
+    PlanDocError
+        When ``dossier`` is not a mapping, or a recognized list-typed sub-key
+        has the wrong type.  The message names the offending sub-key.
+    """
+    if not isinstance(dossier, dict):
+        raise PlanDocError(
+            f"'dossier' frontmatter block must be a mapping (dict), "
+            f"got {type(dossier).__name__!r}"
+        )
+    for key in _DOSSIER_LIST_KEYS:
+        value = dossier.get(key)
+        if value is not None and not isinstance(value, list):
+            raise PlanDocError(
+                f"'dossier.{key}' must be a list, "
+                f"got {type(value).__name__!r}: {value!r}"
+            )
+
+