@deftai/directive-content 0.59.0 → 0.60.0

package/scripts/codebase_map.py

@@ -1,304 +0,0 @@
-#!/usr/bin/env python3
-"""Render the #1595 generated codebase MAP projection."""
-
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-from pathlib import Path
-from typing import Any
-
-import code_structure_validate
-from codebase_default_extractor import config_error_to_dict, default_code_structure_path
-from codebase_projection_registry import CODEBASE_MAP_KIND
-from codebase_provider import artifact_sha256, select_codebase_map
-
-GENERATED_SENTINEL = "AUTO-GENERATED by task codebase:map"
-DEFAULT_OUTPUT_PATH = Path(".planning/codebase/MAP.md")
-BANNER_TEMPLATE = (
-    "<!-- AUTO-GENERATED by task codebase:map -- DO NOT EDIT MANUALLY -->\n"
-    "<!-- Purpose: generated codebase MAP projection -->\n"
-    "<!-- Source of truth: vbrief/PROJECT-DEFINITION.vbrief.json "
-    "plan.architecture.codeStructure -->\n"
-    "<!-- Regenerate with: task codebase:map -->\n"
-)
-
-
-def _markdown_text(value: object) -> str:
-    text = "" if value is None else str(value)
-    return text.replace("|", "\\|").replace("\n", " ").strip()
-
-
-def _code(value: object) -> str:
-    text = _markdown_text(value)
-    if not text:
-        return ""
-    return f"`{text.replace('`', '')}`"
-
-
-def _join_code(values: object, *, limit: int | None = None) -> str:
-    if not isinstance(values, list):
-        return ""
-    items = [str(item) for item in values if isinstance(item, str) and item.strip()]
-    truncated = False
-    if limit is not None and len(items) > limit:
-        items = items[:limit]
-        truncated = True
-    rendered = ", ".join(_code(item) for item in items)
-    if truncated:
-        rendered = f"{rendered}, ..."
-    return rendered
-
-
-def _display_path(path_value: object, project_root_value: object) -> str:
-    if not isinstance(path_value, str) or not path_value:
-        return ""
-    if not isinstance(project_root_value, str) or not project_root_value:
-        return path_value
-    try:
-        path = Path(path_value).resolve()
-        project_root = Path(project_root_value).resolve()
-        return path.relative_to(project_root).as_posix()
-    except (OSError, ValueError):
-        return path_value
-
-
-def _source_digest(artifact: dict[str, Any]) -> str:
-    source = artifact.get("source")
-    if not isinstance(source, dict):
-        return artifact_sha256(artifact)
-    content_hash = source.get("contentHash")
-    if isinstance(content_hash, dict) and isinstance(content_hash.get("value"), str):
-        return content_hash["value"]
-    return artifact_sha256(artifact)
-
-
-def projection_output_path(project_root: Path, explicit_output: str | None = None) -> Path:
-    """Resolve the MAP output path from CLI or projectionManifest."""
-    if explicit_output:
-        return Path(explicit_output)
-
-    project_definition = project_root / "vbrief" / "PROJECT-DEFINITION.vbrief.json"
-    if not project_definition.exists():
-        return DEFAULT_OUTPUT_PATH
-
-    data = code_structure_validate.load_json_file(project_definition)
-    extracted = code_structure_validate.extract_code_structure(data)
-    if extracted is None:
-        return DEFAULT_OUTPUT_PATH
-    for entry in extracted.record.get("projectionManifest", []):
-        if not isinstance(entry, dict):
-            continue
-        if entry.get("kind") == CODEBASE_MAP_KIND and isinstance(entry.get("path"), str):
-            return Path(str(entry["path"]))
-    return DEFAULT_OUTPUT_PATH
-
-
-def render_codebase_map(artifact: dict[str, Any]) -> str:
-    """Return a deterministic Markdown MAP projection for one codebase-map artifact."""
-    source = artifact.get("source") if isinstance(artifact.get("source"), dict) else {}
-    provider = artifact.get("provider") if isinstance(artifact.get("provider"), dict) else {}
-    source_path = _display_path(source.get("codeStructurePath"), source.get("projectRoot"))
-    source_home = source.get("codeStructureHome") or "directory-derived fallback"
-    artifact_digest = artifact_sha256(artifact)
-    source_digest = _source_digest(artifact)
-
-    lines: list[str] = [
-        BANNER_TEMPLATE.rstrip(),
-        f"<!-- Artifact sha256: {artifact_digest} -->",
-        f"<!-- Source digest sha256: {source_digest} -->",
-        "",
-        "# Codebase MAP",
-        "",
-        "| Field | Value |",
-        "| --- | --- |",
-        f"| Projection kind | {_code(artifact.get('kind'))} |",
-        f"| Format | {_code(artifact.get('formatVersion'))} |",
-        f"| Provider | {_code(provider.get('name'))} {_code(provider.get('version'))} |",
-        f"| Provider mode | {_code(provider.get('mode'))} |",
-        f"| Source | {_code(source_path)} at {_code(source_home)} |",
-        f"| Source digest | {_code(source_digest)} |",
-        "",
-        "## Modules",
-        "",
-        "| Module | Name | Purpose | Paths | Files |",
-        "| --- | --- | --- | --- | ---: |",
-    ]
-
-    for module in artifact.get("modules", []):
-        if not isinstance(module, dict):
-            continue
-        file_count = module.get("fileCount")
-        if not isinstance(file_count, int) or isinstance(file_count, bool):
-            files = module.get("files")
-            file_count = len(files) if isinstance(files, list) else 0
-        lines.append(
-            "| "
-            f"{_code(module.get('id'))} | "
-            f"{_markdown_text(module.get('name'))} | "
-            f"{_markdown_text(module.get('purpose'))} | "
-            f"{_join_code(module.get('pathGlobs'), limit=4)} | "
-            f"{file_count} |"
-        )
-
-    lines.extend(["", "## Coupling", ""])
-    coupling = [entry for entry in artifact.get("coupling", []) if isinstance(entry, dict)]
-    if coupling:
-        lines.extend(
-            [
-                "| From | To | Confidence | Evidence |",
-                "| --- | --- | --- | --- |",
-            ]
-        )
-        for edge in coupling:
-            evidence_text = ""
-            evidence = edge.get("evidence")
-            if isinstance(evidence, list) and evidence:
-                first = evidence[0]
-                if isinstance(first, dict):
-                    path = first.get("path", "")
-                    line = first.get("line", "")
-                    ref = first.get("import", "")
-                    evidence_text = f"{path}:{line} imports {ref}"
-            lines.append(
-                "| "
-                f"{_code(edge.get('from'))} | "
-                f"{_code(edge.get('to'))} | "
-                f"{_markdown_text(edge.get('confidence'))} | "
-                f"{_markdown_text(evidence_text)} |"
-            )
-    else:
-        lines.append("No cross-module coupling was reported by the selected artifact.")
-
-    lines.extend(["", "## Entry Points", ""])
-    entry_points = [entry for entry in artifact.get("entryPoints", []) if isinstance(entry, dict)]
-    if entry_points:
-        lines.extend(["| Path | Module | Confidence |", "| --- | --- | --- |"])
-        for entry in entry_points:
-            lines.append(
-                "| "
-                f"{_code(entry.get('path'))} | "
-                f"{_code(entry.get('module'))} | "
-                f"{_markdown_text(entry.get('confidence'))} |"
-            )
-    else:
-        lines.append("No entry points were reported by the selected artifact.")
-
-    lines.extend(["", "## Languages", ""])
-    languages = [
-        entry for entry in artifact.get("languageDistribution", []) if isinstance(entry, dict)
-    ]
-    if languages:
-        lines.extend(["| Language | Files |", "| --- | ---: |"])
-        for entry in languages:
-            lines.append(
-                "| "
-                f"{_markdown_text(entry.get('language'))} | "
-                f"{_markdown_text(entry.get('files'))} |"
-            )
-    else:
-        lines.append("No language distribution was reported by the selected artifact.")
-
-    lines.extend(["", "## Degraded Signals", ""])
-    degraded = [entry for entry in artifact.get("degraded", []) if isinstance(entry, dict)]
-    if degraded:
-        for entry in degraded:
-            lines.append(f"- {_code(entry.get('code'))}: {_markdown_text(entry.get('message'))}")
-    else:
-        lines.append("No degraded signals were reported by the selected artifact.")
-
-    return "\n".join(lines).rstrip() + "\n"
-
-
-def is_deft_generated(path: Path) -> bool:
-    """Return true when an existing MAP is a Deft-generated projection."""
-    if not path.is_file():
-        return True
-    try:
-        with path.open(encoding="utf-8", errors="replace") as handle:
-            return GENERATED_SENTINEL in handle.read(4096)
-    except OSError:
-        return False
-
-
-def write_codebase_map(
-    project_root: Path,
-    *,
-    output_path: Path,
-    artifact_path: str | None = None,
-    generate_with: str | None = None,
-    force: bool = False,
-) -> Path:
-    """Select an artifact, render it, and write the MAP projection."""
-    resolved_output = output_path if output_path.is_absolute() else project_root / output_path
-    if not force and not is_deft_generated(resolved_output):
-        raise RuntimeError(
-            f"refusing to overwrite non-generated MAP at {resolved_output}; "
-            f"missing {GENERATED_SENTINEL!r} banner"
-        )
-    selection = select_codebase_map(
-        project_root,
-        generate_with,
-        artifact_path=artifact_path,
-    )
-    document = render_codebase_map(selection.artifact)
-    resolved_output.parent.mkdir(parents=True, exist_ok=True)
-    resolved_output.write_text(document, encoding="utf-8")
-    return resolved_output
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(description="Render .planning/codebase/MAP.md.")
-    parser.add_argument("--project-root", default=".", help="Repository root to inspect.")
-    parser.add_argument("--output", help="Projection output path.")
-    parser.add_argument("--artifact-path", help="Read a provider artifact from this path.")
-    parser.add_argument(
-        "--generate-with",
-        help="Disposable provider command convenience; canonical policy uses artifactPath.",
-    )
-    parser.add_argument("--stdout", action="store_true", help="Print Markdown instead of writing.")
-    parser.add_argument("--force", action="store_true", help="Overwrite non-generated output.")
-    args = parser.parse_args(argv)
-
-    project_root = Path(args.project_root).resolve()
-    try:
-        output_path = projection_output_path(project_root, args.output)
-        resolved_output = output_path if output_path.is_absolute() else project_root / output_path
-        if not args.stdout and not args.force and not is_deft_generated(resolved_output):
-            print(
-                f"Error: refusing to overwrite non-generated MAP at {resolved_output}. "
-                f"This file lacks the {GENERATED_SENTINEL!r} banner.",
-                file=sys.stderr,
-            )
-            return 2
-
-        selection = select_codebase_map(
-            project_root,
-            args.generate_with,
-            artifact_path=args.artifact_path,
-        )
-        document = render_codebase_map(selection.artifact)
-        if args.stdout:
-            print(document, end="")
-            return 0
-
-        resolved_output.parent.mkdir(parents=True, exist_ok=True)
-        resolved_output.write_text(document, encoding="utf-8")
-    except code_structure_validate.CodeStructureConfigError as exc:
-        print(
-            json.dumps(
-                config_error_to_dict(default_code_structure_path(project_root, None), exc),
-                indent=2,
-                sort_keys=True,
-            ),
-            file=sys.stderr,
-        )
-        return 2
-
-    print(f"Codebase MAP written to {resolved_output}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/scripts/codebase_map_fresh.py

@@ -1,104 +0,0 @@
-#!/usr/bin/env python3
-"""Freshness check for the #1595 generated codebase MAP projection."""
-
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-from pathlib import Path
-
-import code_structure_validate
-from codebase_default_extractor import config_error_to_dict, default_code_structure_path
-from codebase_map import GENERATED_SENTINEL, projection_output_path, render_codebase_map
-from codebase_provider import select_codebase_map
-
-
-def check_codebase_map_fresh(
-    project_root: Path,
-    *,
-    output_path: Path,
-    artifact_path: str | None = None,
-) -> list[str]:
-    """Return freshness errors for the generated MAP projection."""
-    resolved_output = output_path if output_path.is_absolute() else project_root / output_path
-    # #1932: the generated MAP is an on-demand, gitignored artifact. An absent
-    # projection is OK (advisory) -- the gate must not force per-branch
-    # regeneration + commit, which guaranteed mechanical MAP.md collisions across
-    # concurrent branches. When a MAP IS present locally the freshness check below
-    # still flags it if stale; the durable plan.architecture.codeStructure stays
-    # gated by codebase:validate-structure.
-    if not resolved_output.exists():
-        return []
-    try:
-        current = resolved_output.read_text(encoding="utf-8")
-    except OSError as exc:
-        return [f"generated codebase MAP could not be read: {exc}"]
-    if GENERATED_SENTINEL not in current[:4096]:
-        return [
-            f"generated codebase MAP lacks the {GENERATED_SENTINEL!r} banner: "
-            f"{resolved_output}"
-        ]
-
-    selection = select_codebase_map(project_root, artifact_path=artifact_path)
-    expected = render_codebase_map(selection.artifact)
-    if current != expected:
-        return [
-            "generated codebase MAP is stale; run `task codebase:map` "
-            f"to refresh {resolved_output}"
-        ]
-    return []
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(description="Verify generated codebase MAP freshness.")
-    parser.add_argument("--project-root", default=".", help="Repository root to inspect.")
-    parser.add_argument("--output", help="Projection output path.")
-    parser.add_argument("--artifact-path", help="Read a provider artifact from this path.")
-    parser.add_argument("--json", action="store_true", help="Emit a JSON result envelope.")
-    args = parser.parse_args(argv)
-
-    project_root = Path(args.project_root).resolve()
-    try:
-        output_path = projection_output_path(project_root, args.output)
-        errors = check_codebase_map_fresh(
-            project_root,
-            output_path=output_path,
-            artifact_path=args.artifact_path,
-        )
-    except code_structure_validate.CodeStructureConfigError as exc:
-        if args.json:
-            print(
-                json.dumps(
-                    config_error_to_dict(default_code_structure_path(project_root, None), exc),
-                    indent=2,
-                    sort_keys=True,
-                )
-            )
-        else:
-            print(str(exc), file=sys.stderr)
-        return 2
-
-    if args.json:
-        resolved_output = output_path if output_path.is_absolute() else project_root / output_path
-        print(
-            json.dumps(
-                {
-                    "ok": not errors,
-                    "path": str(resolved_output),
-                    "errors": errors,
-                },
-                indent=2,
-                sort_keys=True,
-            )
-        )
-    elif errors:
-        for error in errors:
-            print(f"Error: {error}", file=sys.stderr)
-    else:
-        print("OK: generated codebase MAP is fresh")
-    return 1 if errors else 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/scripts/codebase_projection_registry.py

@@ -1,94 +0,0 @@
-#!/usr/bin/env python3
-"""Projection-kind registry for #1595 codebase structure artifacts.
-
-The authored ``codeStructure.projectionManifest[]`` record stores intent:
-``kind``, ``path``, ``source``, and ``generated``. Runner-specific commands stay
-out of that canonical metadata. This registry is the framework-owned bridge
-from a stable projection kind to the contract details later task wrappers can
-use.
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-from dataclasses import asdict, dataclass
-
-CODEBASE_MAP_KIND = "codebase-map"
-CODEBASE_MAP_FORMAT_VERSION = "codebase-map.v1"
-CODEBASE_PROVIDER_CONTRACT_VERSION = "codebase-provider.v1"
-
-
-@dataclass(frozen=True)
-class ProjectionKind:
-    """Framework-owned behavior for one ``projectionManifest[].kind`` value."""
-
-    kind: str
-    artifact_format_version: str
-    provider_contract_version: str
-    output_role: str
-    generate_action: str
-    freshness_action: str
-    description: str
-
-    def to_dict(self) -> dict[str, str]:
-        """Return a JSON-serializable representation."""
-        return asdict(self)
-
-
-_REGISTRY: tuple[ProjectionKind, ...] = (
-    ProjectionKind(
-        kind=CODEBASE_MAP_KIND,
-        artifact_format_version=CODEBASE_MAP_FORMAT_VERSION,
-        provider_contract_version=CODEBASE_PROVIDER_CONTRACT_VERSION,
-        output_role="architecture-map",
-        generate_action="generate-codebase-map",
-        freshness_action="verify-codebase-map-freshness",
-        description=(
-            "Generated codebase orientation map derived from authored "
-            "codeStructure metadata plus code-derived facts."
-        ),
-    ),
-)
-
-
-def list_projection_kinds() -> list[ProjectionKind]:
-    """Return registered projection kinds in deterministic order."""
-    return sorted(_REGISTRY, key=lambda entry: entry.kind)
-
-
-def resolve_projection_kind(kind: str) -> ProjectionKind:
-    """Resolve one projection kind or raise ``KeyError`` with a useful message."""
-    for entry in _REGISTRY:
-        if entry.kind == kind:
-            return entry
-    known = ", ".join(entry.kind for entry in list_projection_kinds()) or "<none>"
-    raise KeyError(f"unknown projection kind {kind!r}; known kinds: {known}")
-
-
-def main(argv: list[str] | None = None) -> int:
-    """CLI entry point for registry inspection."""
-    parser = argparse.ArgumentParser(description="Inspect codebase projection kinds.")
-    parser.add_argument("--kind", help="Projection kind to resolve.")
-    parser.add_argument("--list", action="store_true", help="List all projection kinds.")
-    args = parser.parse_args(argv)
-
-    if args.list:
-        payload: object = [entry.to_dict() for entry in list_projection_kinds()]
-    elif args.kind:
-        try:
-            payload = resolve_projection_kind(args.kind).to_dict()
-        except KeyError as exc:
-            print(str(exc), file=sys.stderr)
-            return 1
-    else:
-        parser.print_help()
-        return 0
-
-    print(json.dumps(payload, indent=2, sort_keys=True))
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())