@deftai/directive-content 0.59.0 → 0.61.0

package/scripts/_vbrief_sources.py

@@ -1,312 +0,0 @@
-"""_vbrief_sources.py -- pre-cutover source-file readers for migrate:vbrief.
-
-Extracted from ``scripts/migrate_vbrief.py`` so the migrator meets the
-<1000-line file-size MUST from ``deft/main.md`` after the #495/#505
-extractions.  Pure helpers with no dependencies on the other migrator
-submodules (#454, #495, #505); behaviour is unchanged.
-
-Exports
--------
-parse_roadmap_items(path)
-    Parse ROADMAP.md into active items, phase descriptions, and completed
-    items (replaces ``_parse_roadmap_items``).
-resolve_repo_url(spec_vbrief)
-    Resolve the GitHub repository URL from spec_vbrief metadata.
-extract_tech_stack(project_content)
-    Extract a tech-stack string from PROJECT.md markdown.
-first_prose_paragraph(content)
-    Return the first plain prose paragraph (skipping code blocks, lists,
-    etc.), falling back to the first H1 title.
-derive_overview_narrative(...)
-    Resolution order for the Overview narrative on
-    ``PROJECT-DEFINITION.vbrief.json`` (#417).
-
-Issue: #312 (original migrator); extracted by #495 + #505 swarm (Agent A).
-"""
-
-from __future__ import annotations
-
-import re
-from pathlib import Path
-from urllib.parse import urlparse
-
-DEPRECATION_SENTINEL = "<!-- deft:deprecated-redirect -->"
-
-
-def parse_roadmap_items(
-    roadmap_path: Path,
-) -> tuple[list[dict], dict[str, str], list[dict]]:
-    """Parse ROADMAP.md and extract items as structured data.
-
-    Returns a tuple of:
-      - active items: list of dicts with keys: number, title, phase, tier.
-      - phase_descriptions: dict mapping phase heading -> description text.
-      - completed items: list of dicts with keys: number, title, phase.
-    """
-    if not roadmap_path.exists():
-        return [], {}, []
-
-    content = roadmap_path.read_text(encoding="utf-8")
-    items: list[dict] = []
-    completed_items: list[dict] = []
-    phase_descriptions: dict[str, str] = {}
-    current_phase = ""
-    current_tier = ""
-    in_completed = False
-    desc_lines: list[str] = []
-    capturing_desc = False
-    _synthetic_counter = 0
-
-    for line in content.splitlines():
-        phase_match = re.match(r"^##\s+(.+)", line)
-        if phase_match:
-            if current_phase and desc_lines:
-                phase_descriptions[current_phase] = "\n".join(desc_lines).strip()
-            desc_lines = []
-            current_phase = phase_match.group(1).strip()
-            current_tier = ""
-            if "completed" in current_phase.lower():
-                in_completed = True
-                capturing_desc = False
-            else:
-                in_completed = False
-                capturing_desc = True
-            continue
-
-        tier_match = re.match(r"^###\s+(.+)", line)
-        if tier_match:
-            if current_phase and desc_lines and capturing_desc:
-                phase_descriptions[current_phase] = "\n".join(desc_lines).strip()
-                desc_lines = []
-                capturing_desc = False
-            current_tier = tier_match.group(1).strip()
-            continue
-
-        if capturing_desc and not in_completed:
-            stripped = line.strip()
-            if stripped and not stripped.startswith("-"):
-                desc_lines.append(stripped)
-                continue
-            if stripped.startswith("-"):
-                if desc_lines:
-                    phase_descriptions[current_phase] = "\n".join(desc_lines).strip()
-                    desc_lines = []
-                capturing_desc = False
-            else:
-                if desc_lines:
-                    desc_lines.append("")
-                continue
-
-        if not current_phase:
-            continue
-
-        if in_completed:
-            comp_match = re.match(r"^-\s+~~(?:#?(\d+)\s*--?\s*)?(.+?)~~", line)
-            if comp_match:
-                comp_number = comp_match.group(1) or ""
-                comp_title = comp_match.group(2).strip()
-                completed_items.append({
-                    "number": comp_number,
-                    "title": comp_title,
-                    "phase": current_phase,
-                })
-            continue
-
-        item_match = re.match(r"^-\s+\*\*#(\d+)\*\*\s+--\s+(.+)", line)
-        if item_match:
-            items.append({
-                "number": item_match.group(1),
-                "title": item_match.group(2).strip(),
-                "phase": current_phase,
-                "tier": current_tier,
-            })
-            continue
-
-        task_match = re.match(
-            r"^-\s+(?:\*\*)?`([^`]+)`(?:\*\*)?\s+(.+)", line
-        )
-        if task_match:
-            task_id = task_match.group(1).strip()
-            title = task_match.group(2).strip()
-            items.append({
-                "number": "",
-                "title": title,
-                "phase": current_phase,
-                "tier": current_tier,
-                "task_id": task_id,
-            })
-            continue
-
-        generic_match = re.match(r"^-\s+(.+)", line)
-        if generic_match:
-            title = generic_match.group(1).strip()
-            if not title:
-                continue
-            _synthetic_counter += 1
-            items.append({
-                "number": "",
-                "title": title,
-                "phase": current_phase,
-                "tier": current_tier,
-                "synthetic_id": f"roadmap-{_synthetic_counter}",
-            })
-            continue
-
-    if current_phase and desc_lines and not in_completed:
-        phase_descriptions[current_phase] = "\n".join(desc_lines).strip()
-
-    return items, phase_descriptions, completed_items
-
-
-def resolve_repo_url(spec_vbrief: dict | None) -> str:
-    """Resolve the GitHub repository URL from spec_vbrief metadata.
-
-    Falls back to an empty string if no repository can be determined.
-    """
-    if spec_vbrief:
-        repo = spec_vbrief.get("vBRIEFInfo", {}).get("repository", "")
-        if repo:
-            return f"https://github.com/{repo}"
-        refs = spec_vbrief.get("plan", {}).get("references", [])
-        for ref in refs:
-            uri = ref.get("uri", "")
-            if urlparse(uri).netloc in ("github.com", "www.github.com"):
-                parts = uri.split("github.com/")[-1].split("/")
-                if len(parts) >= 2:
-                    return f"https://github.com/{parts[0]}/{parts[1]}"
-    return ""
-
-
-def extract_tech_stack(project_content: str) -> str:
-    """Extract a tech-stack string from PROJECT.md content.
-
-    Recognises ``**Tech Stack**: value``, ``## Tech Stack`` sections, and
-    plain ``Tech Stack: value``.
-    """
-    match = re.search(
-        r"\*\*Tech\s+Stack\*\*\s*:\s*(.+)", project_content, re.IGNORECASE
-    )
-    if match:
-        return match.group(1).strip()
-
-    section_match = re.search(
-        r"##\s+Tech\s+Stack\s*\n(.*?)(?=\n##\s|\Z)",
-        project_content,
-        re.IGNORECASE | re.DOTALL,
-    )
-    if section_match:
-        section = section_match.group(1).strip()
-        if section:
-            return section
-
-    plain_match = re.search(
-        r"Tech\s+Stack\s*:\s*(.+)", project_content, re.IGNORECASE
-    )
-    if plain_match:
-        return plain_match.group(1).strip()
-
-    return ""
-
-
-def first_prose_paragraph(content: str) -> str:
-    """Return the first non-empty prose paragraph from markdown content."""
-    if not content:
-        return ""
-    first_h1 = ""
-    in_code_block = False
-    paragraph_lines: list[str] = []
-
-    def _flush() -> str:
-        if paragraph_lines:
-            return " ".join(paragraph_lines).strip()
-        return ""
-
-    for line in content.splitlines():
-        stripped = line.strip()
-        if stripped.startswith("```"):
-            in_code_block = not in_code_block
-            continue
-        if in_code_block:
-            continue
-        if re.match(r"^#\s+", stripped) and not first_h1:
-            first_h1 = re.sub(r"^#\s+", "", stripped).strip()
-            continue
-        if stripped.startswith("#"):
-            para = _flush()
-            if para:
-                return para
-            paragraph_lines.clear()
-            continue
-        if stripped.startswith(("-", "*", ">", "|")) or re.match(r"^\d+\.\s", stripped):
-            para = _flush()
-            if para:
-                return para
-            paragraph_lines.clear()
-            continue
-        if not stripped:
-            para = _flush()
-            if para:
-                return para
-            paragraph_lines.clear()
-            continue
-        paragraph_lines.append(stripped)
-
-    para = _flush()
-    if para:
-        return para
-    return first_h1
-
-
-def derive_overview_narrative(
-    spec_vbrief: dict | None,
-    spec_md_content: str | None,
-    project_content: str | None,
-    scope_item_count: int,
-) -> str:
-    """Derive an Overview narrative for PROJECT-DEFINITION.vbrief.json (#417).
-
-    Resolution order:
-      1. ``spec_vbrief.plan.narratives['Overview']`` if non-empty.
-      2. First prose paragraph / H1 of ``SPECIFICATION.md`` (pre-sentinel).
-      3. First prose paragraph / H1 of ``PROJECT.md`` (pre-sentinel).
-      4. Synthesized placeholder naming the scope count.
-    """
-    if spec_vbrief:
-        narratives = spec_vbrief.get("plan", {}).get("narratives", {})
-        if isinstance(narratives, dict):
-            ov = narratives.get("Overview")
-            if isinstance(ov, str) and ov.strip():
-                return ov.strip()
-
-    if spec_md_content and DEPRECATION_SENTINEL not in spec_md_content:
-        derived = first_prose_paragraph(spec_md_content)
-        if derived:
-            return derived
-
-    if project_content and DEPRECATION_SENTINEL not in project_content:
-        derived = first_prose_paragraph(project_content)
-        if derived:
-            return derived
-
-    if scope_item_count > 0:
-        return (
-            f"Project overview was not auto-derived during migration. "
-            f"{scope_item_count} scope item(s) were created in vbrief/pending/. "
-            f"Update vbrief/PROJECT-DEFINITION.vbrief.json narratives['Overview'] "
-            f"manually to describe your project."
-        )
-    return (
-        "Project overview was not auto-derived during migration. "
-        "Update vbrief/PROJECT-DEFINITION.vbrief.json narratives['Overview'] "
-        "manually to describe your project."
-    )
-
-
-__all__ = [
-    "DEPRECATION_SENTINEL",
-    "derive_overview_narrative",
-    "extract_tech_stack",
-    "first_prose_paragraph",
-    "parse_roadmap_items",
-    "resolve_repo_url",
-]

package/scripts/_vbrief_speckit.py

@@ -1,262 +0,0 @@
-"""_vbrief_speckit.py -- speckit plan.vbrief.json -> scope vBRIEFs translator.
-
-Extracted from ``scripts/migrate_vbrief.py`` so the migrator meets the
-<1000-line file-size MUST from ``deft/main.md`` after the #495/#505
-extractions.  Behaviour is unchanged; import names preserved for the
-existing test surface.
-
-Story: #436 / #458.  Extracted by #495 + #505 swarm (Agent A).
-"""
-
-from __future__ import annotations
-
-import json
-import re
-from pathlib import Path
-
-from _vbrief_build import (
-    EMITTED_VBRIEF_VERSION as _EMITTED_VBRIEF_VERSION,
-    reference_with_default_trust as _reference_with_default_trust,
-    slugify as _slugify_shared,
-)
-
-
-def edge_nodes(edge: dict) -> tuple[str, str]:
-    """Return (from_id, to_id) for a vBRIEF edge, reading both dialects.
-
-    Speckit plan edges use ``from`` / ``to`` in current drafts, but earlier
-    drafts used ``source`` / ``target``. Prefer the current keys when they
-    are populated and fall back to the legacy keys.
-    """
-    if not isinstance(edge, dict):
-        return "", ""
-    src = edge.get("from") or edge.get("source", "")
-    tgt = edge.get("to") or edge.get("target", "")
-    return str(src or ""), str(tgt or "")
-
-
-def dependencies_for_item(item_id: str, edges: list[dict]) -> list[str]:
-    """Return the list of item IDs that block ``item_id`` (bilingual reader).
-
-    An edge with ``type == 'blocks'`` and target equal to ``item_id`` means
-    the edge's source blocks this item -- so the source is a dependency.
-    """
-    deps: list[str] = []
-    for edge in edges or []:
-        if not isinstance(edge, dict):
-            continue
-        if edge.get("type", "") != "blocks":
-            continue
-        src, tgt = edge_nodes(edge)
-        if tgt == item_id and src and src not in deps:
-            deps.append(src)
-    return deps
-
-
-def speckit_ip_slug(title: str, item_id: str) -> str:
-    """Return a slug for a speckit IP item filename."""
-    source = (title or item_id or "").strip()
-    source = re.sub(
-        r"^\s*IP[\s-]*\d+\s*[:\-]\s*", "", source, flags=re.IGNORECASE
-    )
-    slug = _slugify_shared(source)
-    return slug or _slugify_shared(item_id) or "ip-phase"
-
-
-def speckit_ip_index(item: dict, fallback_index: int) -> int:
-    """Derive the numeric IP index for a speckit plan item."""
-    item_id = str(item.get("id", "") or "")
-    tail = re.search(r"(\d+)\s*$", item_id)
-    if tail:
-        return int(tail.group(1))
-    title = str(item.get("title", "") or "")
-    lead = re.search(r"IP[\s-]*(\d+)", title, flags=re.IGNORECASE)
-    if lead:
-        return int(lead.group(1))
-    return fallback_index
-
-
-def _non_empty_text(value: object, fallback: str) -> str:
-    text = str(value or "").strip()
-    return text or fallback
-
-
-def create_speckit_scope_vbrief(
-    item: dict,
-    *,
-    ip_index: int,
-    dependencies: list[str],
-    spec_ref: str,
-) -> dict:
-    """Build a Phase 4 scope vBRIEF dict for a speckit implementation phase.
-
-    Populates the canonical narrative keys (``Description``, ``Acceptance``,
-    ``Traces``), writes ``plan.metadata.dependencies`` at the plan level,
-    and links back to the parent ``specification.vbrief.json`` via a
-    ``x-vbrief/plan`` reference.
-    """
-    spec_ref = _vbrief_relative_spec_ref(spec_ref)
-    fallback_title = f"IP-{ip_index}"
-    title = _non_empty_text(item.get("title"), fallback_title)
-    narrative = item.get("narrative") or {}
-    if not isinstance(narrative, dict):
-        narrative = {}
-
-    def _pick(*keys: str) -> str:
-        for key in keys:
-            value = narrative.get(key)
-            if isinstance(value, str) and value.strip():
-                return value.strip()
-        return ""
-
-    description = _pick("Description", "Summary") or title or fallback_title
-    acceptance = _pick("Acceptance", "AcceptanceCriteria")
-    traces = _pick("Traces", "Trace", "Requirements") or fallback_title
-
-    default_acceptance = (
-        f"Acceptance criteria for IP-{ip_index} "
-        f"(copy from specification.vbrief.json)."
-    )
-    narratives: dict[str, str] = {
-        "Description": description,
-        "Acceptance": acceptance or default_acceptance,
-        "Traces": traces,
-    }
-    for extra in ("Phase", "PhaseDescription", "Tier"):
-        value = narrative.get(extra)
-        if isinstance(value, str) and value.strip():
-            narratives[extra] = value.strip()
-
-    references = [
-        _reference_with_default_trust({"type": "x-vbrief/plan", "uri": spec_ref})
-    ]
-    for ref in item.get("references", []) or []:
-        if isinstance(ref, dict) and ref.get("type") != "x-vbrief/plan":
-            references.append(_reference_with_default_trust(ref))
-
-    plan: dict = {
-        "title": title,
-        "status": "pending",
-        "narratives": narratives,
-        "items": [],
-        "metadata": {"kind": "phase"},
-        "references": references,
-    }
-    if dependencies:
-        plan["metadata"]["dependencies"] = list(dependencies)
-
-    return {
-        "vBRIEFInfo": {
-            "version": _EMITTED_VBRIEF_VERSION,
-            "description": f"Scope vBRIEF for speckit IP-{ip_index}",
-        },
-        "plan": plan,
-    }
-
-
-def _vbrief_relative_spec_ref(spec_ref: str) -> str:
-    """Return a vbrief-directory-relative reference for the parent spec."""
-    normalized = spec_ref.strip()
-    while normalized.startswith("../"):
-        normalized = normalized[3:]
-    return normalized or "specification.vbrief.json"
-
-
-def migrate_speckit_plan(
-    plan_path: Path,
-    *,
-    pending_dir: Path | None = None,
-    date: str | None = None,
-    spec_ref: str = "specification.vbrief.json",
-    today: str | None = None,
-) -> tuple[bool, list[str]]:
-    """Translate a speckit-shaped ``plan.vbrief.json`` into scope vBRIEFs.
-
-    Each ``plan.items`` entry becomes a file in ``pending_dir`` named
-    ``YYYY-MM-DD-ip<NNN>-<slug>.vbrief.json``.
-    """
-    actions: list[str] = []
-    if not plan_path.is_file():
-        return False, [f"ERROR: plan.vbrief.json not found at {plan_path}"]
-
-    try:
-        plan_data = json.loads(plan_path.read_text(encoding="utf-8"))
-    except json.JSONDecodeError as exc:
-        return False, [f"ERROR: invalid JSON in {plan_path.name}: {exc}"]
-
-    plan = plan_data.get("plan", {}) if isinstance(plan_data, dict) else {}
-    items = plan.get("items", []) if isinstance(plan, dict) else []
-    edges = plan.get("edges", []) if isinstance(plan, dict) else []
-
-    if not items:
-        return False, [
-            "ERROR: plan.vbrief.json has no items to migrate (empty speckit plan?)"
-        ]
-
-    pending_dir = pending_dir or (plan_path.parent / "pending")
-    pending_dir.mkdir(parents=True, exist_ok=True)
-    effective_date = date or today
-    if effective_date is None:  # pragma: no cover -- caller always supplies
-        from datetime import UTC, datetime  # noqa: WPS433 -- lazy import
-        effective_date = datetime.now(UTC).strftime("%Y-%m-%d")
-
-    created_paths: list[Path] = []
-    for idx, item in enumerate(items, start=1):
-        if not isinstance(item, dict):
-            continue
-        ip_index = speckit_ip_index(item, idx)
-        item_id = str(item.get("id", "") or f"ip-{ip_index}")
-        dependencies = dependencies_for_item(item_id, edges)
-        slug = speckit_ip_slug(str(item.get("title", "")), item_id)
-        ip_token = f"ip{ip_index:03d}"
-        filename = f"{effective_date}-{ip_token}-{slug}.vbrief.json"
-        target = pending_dir / filename
-        if target.exists():
-            actions.append(f"SKIP   pending/{filename} already exists")
-            created_paths.append(target)
-            continue
-        scope = create_speckit_scope_vbrief(
-            item,
-            ip_index=ip_index,
-            dependencies=dependencies,
-            spec_ref=spec_ref,
-        )
-        target.write_text(
-            json.dumps(scope, indent=2, ensure_ascii=False) + "\n",
-            encoding="utf-8",
-        )
-        actions.append(f"CREATE pending/{filename} (IP-{ip_index})")
-        created_paths.append(target)
-
-    envelope = plan_data.get("vBRIEFInfo", {}) if isinstance(plan_data, dict) else {}
-    # #533: force the emitted envelope to the current canonical version so a
-    # v0.5 speckit plan migrated today produces a v0.6 session scaffold.
-    envelope["version"] = _EMITTED_VBRIEF_VERSION
-    envelope["description"] = (
-        "Session-level tactical plan (migrated from speckit plan). "
-        "Scope vBRIEFs live in vbrief/pending/."
-    )
-    session_plan = {
-        "vBRIEFInfo": envelope,
-        "plan": {
-            "title": str(plan.get("title", "Session plan")) or "Session plan",
-            "status": "running",
-            "items": [],
-        },
-    }
-    plan_path.write_text(
-        json.dumps(session_plan, indent=2, ensure_ascii=False) + "\n",
-        encoding="utf-8",
-    )
-    actions.append(f"REWRITE {plan_path.name} -> session-todo scaffold")
-    return True, actions
-
-
-__all__ = [
-    "create_speckit_scope_vbrief",
-    "dependencies_for_item",
-    "edge_nodes",
-    "migrate_speckit_plan",
-    "speckit_ip_index",
-    "speckit_ip_slug",
-]