@deftai/directive-content 0.55.2 → 0.56.0

package/scripts/codebase_map.py

@@ -0,0 +1,304 @@
+#!/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

@@ -0,0 +1,104 @@
+#!/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

@@ -0,0 +1,94 @@
+#!/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())