@pmaddire/gcie 0.1.2

package/cli/commands/setup.py

@@ -0,0 +1,73 @@
+"""One-command repository setup for GCIE."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from context.architecture_bootstrap import ensure_initialized
+
+from .index import run_index
+
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def _copy_if_needed(source: Path, target: Path, *, force: bool) -> str:
+    if not source.exists():
+        return "source_missing"
+    if target.exists() and not force:
+        return "skipped_existing"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(source.read_text(encoding="utf-8"), encoding="utf-8")
+    return "written"
+
+
+def run_setup(
+    path: str,
+    *,
+    force: bool = False,
+    include_agent_usage: bool = True,
+    include_setup_doc: bool = True,
+    run_index_pass: bool = True,
+) -> dict:
+    """Initialize a repository so GCIE can be used immediately."""
+    target = Path(path).resolve()
+    target.mkdir(parents=True, exist_ok=True)
+
+    config = ensure_initialized(target)
+    gcie_dir = target / ".gcie"
+
+    status: dict[str, object] = {
+        "repo": target.as_posix(),
+        "gcie_dir": gcie_dir.as_posix(),
+        "architecture_initialized": True,
+        "files": {},
+    }
+
+    source_root = _repo_root()
+    copied: dict[str, str] = {}
+
+    if include_agent_usage:
+        copied["AGENT_USAGE.md"] = _copy_if_needed(
+            source_root / "AGENT_USAGE.md",
+            target / "AGENT_USAGE.md",
+            force=force,
+        )
+
+    if include_setup_doc:
+        copied["SETUP_ANY_REPO.md"] = _copy_if_needed(
+            source_root / "SETUP_ANY_REPO.md",
+            target / "SETUP_ANY_REPO.md",
+            force=force,
+        )
+
+    status["files"] = copied
+    status["context_config"] = config
+
+    if run_index_pass:
+        status["index"] = run_index(target.as_posix())
+    else:
+        status["index"] = {"skipped": True}
+
+    return status

package/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration package for GCIE."""

package/config/scanner_config.py

@@ -0,0 +1,82 @@
+"""Scanner configuration models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable
+
+
+@dataclass(slots=True)
+class ScannerConfig:
+    """Configuration for repository scanning."""
+
+    include_extensions: set[str] = field(
+        default_factory=lambda: {
+            ".py",
+            ".pyi",
+            ".md",
+            ".txt",
+            ".toml",
+            ".yaml",
+            ".yml",
+            ".json",
+            ".ini",
+            ".cfg",
+            ".rst",
+            ".sh",
+        }
+    )
+    exclude_dirs: set[str] = field(
+        default_factory=lambda: {
+            ".git",
+            ".hg",
+            ".svn",
+            ".venv",
+            "venv",
+            "__pycache__",
+            "node_modules",
+            "build",
+            "dist",
+            ".pytest_cache",
+            ".mypy_cache",
+            ".idea",
+            ".vscode",
+        }
+    )
+    exclude_globs: tuple[str, ...] = ()
+    max_file_size_bytes: int = 1_000_000
+    include_hidden: bool = False
+
+    def is_excluded_dir(self, directory_name: str) -> bool:
+        """Return True if a directory should be skipped during scanning."""
+        if not self.include_hidden and directory_name.startswith("."):
+            return True
+        return directory_name in self.exclude_dirs
+
+    def allows_extension(self, path: Path) -> bool:
+        """Return True when the file extension is in the allow-list."""
+        return path.suffix.lower() in self.include_extensions
+
+    def matches_exclude_glob(self, relative_path: Path) -> bool:
+        """Return True when the path matches any configured exclusion glob."""
+        return any(relative_path.match(pattern) for pattern in self.exclude_globs)
+
+    @classmethod
+    def from_extensions(
+        cls,
+        include_extensions: Iterable[str],
+        *,
+        max_file_size_bytes: int = 1_000_000,
+        include_hidden: bool = False,
+    ) -> "ScannerConfig":
+        """Build config from extension iterable."""
+        normalized = {
+            ext.lower() if ext.startswith(".") else f".{ext.lower()}"
+            for ext in include_extensions
+        }
+        return cls(
+            include_extensions=normalized,
+            max_file_size_bytes=max_file_size_bytes,
+            include_hidden=include_hidden,
+        )

package/context/__init__.py

@@ -0,0 +1 @@
+

package/context/architecture_bootstrap.py

@@ -0,0 +1,170 @@
+"""Bootstrap GCIE-managed architecture artifacts."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .architecture_index import build_architecture_index, refresh_architecture_if_needed, write_architecture_index
+from .architecture_parser import parse_architecture
+
+
+_DEFAULT_DOC_CANDIDATES = [
+    "ARCHITECTURE.md",
+    "README.md",
+    "PROJECT.md",
+    "docs/architecture.md",
+    "docs/system_design.md",
+    "docs/design.md",
+]
+
+_EXCLUDED_DIRS = {".git", ".gcie", ".venv", "node_modules", "__pycache__"}
+
+
+def find_user_architecture_docs(repo_path: Path) -> list[Path]:
+    """Find likely user-managed architecture documents in the repo."""
+    docs = []
+    for candidate in _DEFAULT_DOC_CANDIDATES:
+        path = repo_path / candidate
+        if path.exists() and path.is_file():
+            docs.append(path)
+    return docs
+
+
+def _summarize_docs(docs: list[tuple[Path, str]]) -> str:
+    if not docs:
+        return "No user-managed architecture docs were found."
+
+    lines = []
+    for path, content in docs:
+        excerpt = ""
+        for line in content.splitlines():
+            if line.strip():
+                excerpt = line.strip()
+                break
+        lines.append(f"- {path.as_posix()}: {excerpt[:120]}")
+    return "\n".join(lines)
+
+
+def _discover_subsystems(repo_path: Path) -> list[tuple[str, list[str]]]:
+    subsystems = []
+    for child in repo_path.iterdir():
+        if not child.is_dir() or child.name in _EXCLUDED_DIRS:
+            continue
+        key_files = []
+        for path in child.rglob("*"):
+            if path.is_file() and path.suffix.lower() in {".py", ".js", ".jsx", ".ts", ".tsx"}:
+                key_files.append(path.relative_to(repo_path).as_posix())
+            if len(key_files) >= 5:
+                break
+        subsystems.append((child.name, key_files))
+    return subsystems
+
+
+def _render_architecture(repo_path: Path, docs: list[tuple[Path, str]]) -> str:
+    summary = _summarize_docs(docs)
+    subsystems = _discover_subsystems(repo_path)
+    active_work = "\n".join(f"- {name}" for name, _ in subsystems) or "- core"
+
+    subsystem_blocks = []
+    for name, key_files in subsystems:
+        key_lines = "\n".join(f"- {path}" for path in key_files) or "- "
+        subsystem_blocks.append(
+            "\n".join(
+                [
+                    f"### Subsystem: {name}",
+                    "Purpose: ",
+                    "Status: active",
+                    "Key Files:",
+                    key_lines,
+                    "Interfaces:",
+                    "- ",
+                    "Depends On:",
+                    "- ",
+                    "Used By:",
+                    "- ",
+                    "Failure Modes:",
+                    "- ",
+                    "Notes:",
+                    "- ",
+                ]
+            )
+        )
+
+    return "\n".join(
+        [
+            "# GCIE Architecture",
+            "",
+            "## Project Summary",
+            summary,
+            "",
+            "## System Stage",
+            "unknown",
+            "",
+            "## Global Constraints",
+            "",
+            "## Subsystems",
+            "",
+            "\n\n".join(subsystem_blocks) if subsystem_blocks else "### Subsystem: core\nPurpose: ",
+            "",
+            "## Data Flow",
+            "",
+            "## Entry Points",
+            "",
+            "## Active Work Areas",
+            active_work,
+            "",
+            "## Known Risks",
+            "",
+        ]
+    )
+
+
+def _write_context_config(config_path: Path, *, architecture_source: str) -> dict:
+    config = {
+        "architecture_slicer_enabled": True,
+        "fallback_to_normal_on_low_confidence": True,
+        "confidence_threshold": 0.2,
+        "architecture_source": architecture_source,
+        "last_bootstrap_time": datetime.now(timezone.utc).isoformat(),
+        "last_architecture_update": None,
+    }
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(json.dumps(config, indent=2), encoding="utf-8")
+    return config
+
+
+def ensure_initialized(repo_path: Path) -> dict:
+    """Ensure GCIE-managed architecture artifacts exist for the repo."""
+    gcie_dir = repo_path / ".gcie"
+    architecture_path = gcie_dir / "architecture.md"
+    index_path = gcie_dir / "architecture_index.json"
+    config_path = gcie_dir / "context_config.json"
+
+    config = None
+    if config_path.exists():
+        try:
+            config = json.loads(config_path.read_text(encoding="utf-8"))
+        except Exception:
+            config = None
+
+    if not architecture_path.exists():
+        docs = [(path, path.read_text(encoding="utf-8")) for path in find_user_architecture_docs(repo_path)]
+        architecture_text = _render_architecture(repo_path, docs)
+        gcie_dir.mkdir(parents=True, exist_ok=True)
+        architecture_path.write_text(architecture_text, encoding="utf-8")
+
+    if not index_path.exists() and architecture_path.exists():
+        parsed = parse_architecture(architecture_path.read_text(encoding="utf-8"))
+        index_data = build_architecture_index(parsed, repo_path)
+        write_architecture_index(index_path, index_data)
+
+    if config is None:
+        config = _write_context_config(config_path, architecture_source=architecture_path.as_posix())
+
+    if refresh_architecture_if_needed(repo_path, architecture_path, index_path):
+        config["last_architecture_update"] = datetime.now(timezone.utc).isoformat()
+        config_path.write_text(json.dumps(config, indent=2), encoding="utf-8")
+
+    return config or {}

package/context/architecture_index.py

@@ -0,0 +1,185 @@
+"""Build and maintain architecture index data."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .architecture_parser import ArchitectureDoc
+
+
+_EXCLUDED_DIRS = {".git", ".gcie", ".venv", "node_modules", "__pycache__"}
+_CODE_EXTENSIONS = {".py", ".pyi", ".js", ".jsx", ".ts", ".tsx"}
+_CORE_HINTS = {
+    "router",
+    "routing",
+    "fallback",
+    "context",
+    "slicer",
+    "architecture",
+    "validation",
+    "mode",
+    "confidence",
+}
+_CORE_DIRS = {"context", "router", "routing"}
+_CORE_EXCLUDED_DIRS = {"tests", "test"}
+
+
+def compute_repo_fingerprint(repo_path: Path) -> dict:
+    """Compute a lightweight fingerprint for detecting structural changes."""
+    top_level_dirs = []
+    file_count = 0
+
+    for child in repo_path.iterdir():
+        if child.is_dir() and child.name not in _EXCLUDED_DIRS:
+            top_level_dirs.append(child.name)
+
+    for path in repo_path.rglob("*"):
+        if path.is_dir():
+            if path.name in _EXCLUDED_DIRS:
+                continue
+        if path.is_file() and path.suffix.lower() in _CODE_EXTENSIONS:
+            if any(part in _EXCLUDED_DIRS for part in path.parts):
+                continue
+            file_count += 1
+
+    return {
+        "top_level_dirs": sorted(top_level_dirs),
+        "code_file_count": file_count,
+    }
+
+
+def _is_core_infrastructure(path: Path) -> bool:
+    lowered = path.as_posix().lower()
+    parts = {part.lower() for part in path.parts}
+    if parts & _CORE_EXCLUDED_DIRS:
+        return False
+    if parts & _CORE_DIRS:
+        return True
+    return any(hint in lowered for hint in _CORE_HINTS)
+
+
+def _discover_core_infrastructure(repo_path: Path) -> list[str]:
+    core_files: list[str] = []
+    for path in repo_path.rglob("*"):
+        if path.is_dir():
+            if path.name in _EXCLUDED_DIRS:
+                continue
+        if not path.is_file() or path.suffix.lower() not in _CODE_EXTENSIONS:
+            continue
+        if any(part in _EXCLUDED_DIRS for part in path.parts):
+            continue
+        if _is_core_infrastructure(path):
+            core_files.append(path.relative_to(repo_path).as_posix())
+    return sorted(set(core_files))
+
+
+def build_architecture_index(doc: ArchitectureDoc, repo_path: Path) -> dict:
+    """Build an index structure from parsed architecture data."""
+    subsystems = []
+    file_map: dict[str, list[str]] = {}
+
+    for subsystem in doc.subsystems or []:
+        subsystems.append(
+            {
+                "name": subsystem.name,
+                "purpose": subsystem.purpose,
+                "status": subsystem.status,
+                "key_files": subsystem.key_files or [],
+                "interfaces": subsystem.interfaces or [],
+                "depends_on": subsystem.depends_on or [],
+                "used_by": subsystem.used_by or [],
+                "failure_modes": subsystem.failure_modes or [],
+                "notes": subsystem.notes or [],
+            }
+        )
+        for path in subsystem.key_files or []:
+            file_map.setdefault(path, []).append(subsystem.name)
+
+    return {
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "repo_fingerprint": compute_repo_fingerprint(repo_path),
+        "subsystems": subsystems,
+        "file_map": file_map,
+        "core_infrastructure": _discover_core_infrastructure(repo_path),
+    }
+
+
+def write_architecture_index(path: Path, index_data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(index_data, indent=2), encoding="utf-8")
+
+
+def load_architecture_index(path: Path) -> dict | None:
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+
+
+def has_structural_change(repo_path: Path, index_data: dict) -> bool:
+    """Detect whether the repo has structural changes since last index."""
+    current = compute_repo_fingerprint(repo_path)
+    previous = index_data.get("repo_fingerprint", {})
+
+    if set(current.get("top_level_dirs", [])) != set(previous.get("top_level_dirs", [])):
+        return True
+
+    prev_count = previous.get("code_file_count", 0)
+    curr_count = current.get("code_file_count", 0)
+    if prev_count == 0:
+        return False
+    delta = abs(curr_count - prev_count) / max(prev_count, 1)
+    return delta >= 0.15
+
+
+def _replace_section(text: str, section_title: str, new_body: str) -> str:
+    heading = f"## {section_title}"
+    if heading not in text:
+        return text.rstrip() + f"\n\n{heading}\n{new_body}\n"
+
+    parts = text.split(heading)
+    before = parts[0].rstrip()
+    after = heading.join(parts[1:])
+    remainder = after.split("\n## ", 1)
+    tail = ""
+    if len(remainder) == 2:
+        tail = "\n## " + remainder[1]
+    return f"{before}\n\n{heading}\n{new_body}\n{tail}".strip() + "\n"
+
+
+def refresh_architecture_if_needed(
+    repo_path: Path,
+    architecture_path: Path,
+    index_path: Path,
+) -> bool:
+    """Refresh architecture artifacts when structural changes are detected."""
+    index_data = load_architecture_index(index_path)
+    if index_data is None:
+        return False
+
+    if not has_structural_change(repo_path, index_data):
+        if not index_data.get("core_infrastructure"):
+            index_data["core_infrastructure"] = _discover_core_infrastructure(repo_path)
+            index_data["generated_at"] = datetime.now(timezone.utc).isoformat()
+            write_architecture_index(index_path, index_data)
+            return True
+        return False
+
+    if architecture_path.exists():
+        text = architecture_path.read_text(encoding="utf-8")
+        fingerprint = compute_repo_fingerprint(repo_path)
+        active = "\n".join(f"- {name}" for name in fingerprint.get("top_level_dirs", []))
+        updated = _replace_section(text, "Active Work Areas", active)
+        architecture_path.write_text(updated, encoding="utf-8")
+
+    index_data["repo_fingerprint"] = compute_repo_fingerprint(repo_path)
+    index_data["generated_at"] = datetime.now(timezone.utc).isoformat()
+    index_data["core_infrastructure"] = _discover_core_infrastructure(repo_path)
+    write_architecture_index(index_path, index_data)
+    return True
+
+

package/context/architecture_parser.py

@@ -0,0 +1,170 @@
+"""Parse GCIE-managed architecture files."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Subsystem:
+    name: str
+    purpose: str = ""
+    status: str = ""
+    key_files: list[str] | None = None
+    interfaces: list[str] | None = None
+    depends_on: list[str] | None = None
+    used_by: list[str] | None = None
+    failure_modes: list[str] | None = None
+    notes: list[str] | None = None
+
+
+@dataclass
+class ArchitectureDoc:
+    project_summary: str = ""
+    system_stage: str = ""
+    global_constraints: str = ""
+    subsystems: list[Subsystem] | None = None
+    data_flow: str = ""
+    entry_points: str = ""
+    active_work_areas: str = ""
+    known_risks: str = ""
+
+
+_LIST_FIELDS = {
+    "Key Files": "key_files",
+    "Interfaces": "interfaces",
+    "Depends On": "depends_on",
+    "Used By": "used_by",
+    "Failure Modes": "failure_modes",
+    "Notes": "notes",
+}
+
+_REQUIRED_SECTIONS = {
+    "Project Summary",
+    "System Stage",
+    "Global Constraints",
+    "Subsystems",
+    "Data Flow",
+    "Entry Points",
+    "Active Work Areas",
+    "Known Risks",
+}
+
+
+class ArchitectureParseError(ValueError):
+    """Raised when a GCIE architecture document is malformed."""
+
+
+def parse_architecture(text: str) -> ArchitectureDoc:
+    """Parse a GCIE architecture.md file into a structured object.
+
+    Raises ArchitectureParseError when required sections are missing.
+    """
+    lines = text.splitlines()
+
+    if not lines or not lines[0].strip().startswith("# GCIE Architecture"):
+        raise ArchitectureParseError("missing_header")
+
+    subsystems: list[Subsystem] = []
+
+    project_summary = ""
+    system_stage = ""
+    global_constraints = ""
+    data_flow = ""
+    entry_points = ""
+    active_work_areas = ""
+    known_risks = ""
+
+    seen_sections: set[str] = set()
+    current_section = ""
+    current_subsystem: Subsystem | None = None
+    current_list_field: str | None = None
+    buffer: list[str] = []
+
+    def flush_section() -> str:
+        content = "\n".join(line.strip() for line in buffer if line.strip())
+        buffer.clear()
+        return content
+
+    def commit_subsystem() -> None:
+        nonlocal current_subsystem
+        if current_subsystem is not None:
+            subsystems.append(current_subsystem)
+        current_subsystem = None
+
+    for line in lines[1:]:
+        stripped = line.strip()
+        if stripped.startswith("## "):
+            if current_subsystem is None and current_section:
+                content = flush_section()
+                if current_section == "Project Summary":
+                    project_summary = content
+                elif current_section == "System Stage":
+                    system_stage = content
+                elif current_section == "Global Constraints":
+                    global_constraints = content
+                elif current_section == "Data Flow":
+                    data_flow = content
+                elif current_section == "Entry Points":
+                    entry_points = content
+                elif current_section == "Active Work Areas":
+                    active_work_areas = content
+                elif current_section == "Known Risks":
+                    known_risks = content
+            current_section = stripped[len("## ") :]
+            seen_sections.add(current_section)
+            current_list_field = None
+            continue
+
+        if stripped.startswith("### Subsystem:"):
+            commit_subsystem()
+            name = stripped.split(":", 1)[1].strip()
+            if not name:
+                raise ArchitectureParseError("subsystem_missing_name")
+            current_subsystem = Subsystem(name=name)
+            current_list_field = None
+            continue
+
+        if current_subsystem is not None:
+            if stripped.endswith(":") and stripped[:-1] in _LIST_FIELDS:
+                current_list_field = _LIST_FIELDS[stripped[:-1]]
+                setattr(current_subsystem, current_list_field, [])
+                continue
+
+            if stripped.startswith("Purpose:"):
+                current_subsystem.purpose = stripped.split(":", 1)[1].strip()
+                current_list_field = None
+                continue
+
+            if stripped.startswith("Status:"):
+                current_subsystem.status = stripped.split(":", 1)[1].strip()
+                current_list_field = None
+                continue
+
+            if stripped.startswith("-") and current_list_field:
+                value = stripped.lstrip("- ").strip()
+                if value:
+                    target = getattr(current_subsystem, current_list_field)
+                    if target is not None:
+                        target.append(value)
+                continue
+
+        if current_section and current_subsystem is None:
+            buffer.append(line)
+
+    commit_subsystem()
+
+    missing_sections = _REQUIRED_SECTIONS - seen_sections
+    if missing_sections:
+        raise ArchitectureParseError("missing_sections")
+
+    return ArchitectureDoc(
+        project_summary=project_summary,
+        system_stage=system_stage,
+        global_constraints=global_constraints,
+        subsystems=subsystems,
+        data_flow=data_flow,
+        entry_points=entry_points,
+        active_work_areas=active_work_areas,
+        known_risks=known_risks,
+    )