specsmith 0.1.4.dev30__tar.gz → 0.1.4.dev33__tar.gz

{specsmith-0.1.4.dev30/src/specsmith.egg-info → specsmith-0.1.4.dev33}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.1.4.dev30
+Version: 0.1.4.dev33
 Summary: Forge governed project scaffolds from the Agentic AI Development Workflow Specification.
 Author: BitConcepts
 License: MIT

{specsmith-0.1.4.dev30 → specsmith-0.1.4.dev33}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.1.4.dev30"
+version = "0.1.4.dev33"
 description = "Forge governed project scaffolds from the Agentic AI Development Workflow Specification."
 readme = "README.md"
 license = {text = "MIT"}

specsmith-0.1.4.dev33/src/specsmith/architect.py

@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Architect — scan project and generate architecture documentation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def scan_project_structure(root: Path) -> dict[str, object]:  # noqa: C901
+    """Scan a project and extract architecture-relevant information.
+
+    Returns a dict with modules, entry_points, languages, dependencies,
+    git_summary, and existing_docs.
+    """
+    from specsmith.importer import (
+        _extract_git_commits,
+        _extract_git_contributors,
+        _extract_readme_summary,
+        _parse_dependencies,
+        detect_project,
+    )
+
+    result = detect_project(root)
+    commits = _extract_git_commits(root)
+    contributors = _extract_git_contributors(root)
+    readme = _extract_readme_summary(root)
+    deps = _parse_dependencies(root)
+
+    # Find existing architecture docs
+    existing_arch: list[str] = []
+    docs_dir = root / "docs"
+    if docs_dir.is_dir():
+        for p in docs_dir.rglob("*"):
+            if p.is_file() and "architecture" in p.name.lower():
+                existing_arch.append(str(p.relative_to(root)))
+
+    return {
+        "name": root.name,
+        "languages": result.languages,
+        "primary_language": result.primary_language,
+        "secondary_languages": result.secondary_languages,
+        "build_system": result.build_system,
+        "test_framework": result.test_framework,
+        "modules": result.modules,
+        "entry_points": result.entry_points,
+        "dependencies": deps,
+        "readme_summary": readme,
+        "recent_commits": commits[:10],
+        "contributors": contributors,
+        "existing_arch_docs": existing_arch,
+        "file_count": result.file_count,
+        "inferred_type": result.inferred_type.value if result.inferred_type else "unknown",
+    }
+
+
+def generate_architecture(
+    root: Path,
+    *,
+    components: list[dict[str, str]] | None = None,
+    data_flow: str = "",
+    deployment: str = "",
+    scan: dict[str, object] | None = None,
+) -> Path:
+    """Generate docs/architecture.md from scan data + user input.
+
+    Returns the path to the generated file.
+    """
+    if scan is None:
+        scan = scan_project_structure(root)
+
+    name = str(scan.get("name", root.name))
+    langs: dict[str, int] = dict(scan.get("languages", {}) or {})  # type: ignore[call-overload]
+    primary = str(scan.get("primary_language", "unknown"))
+    secondary: list[str] = list(scan.get("secondary_languages", []) or [])  # type: ignore[call-overload]
+    lang_list = [primary] + secondary
+    lang_display = ", ".join(str(l) for l in lang_list if l)  # noqa: E741
+
+    doc = f"# Architecture — {name}\n\n"
+
+    # Overview
+    doc += "## Overview\n\n"
+    readme = scan.get("readme_summary", "")
+    if readme:
+        doc += f"{readme}\n\n"
+    doc += f"- **Languages**: {lang_display}\n"
+    doc += f"- **Build system**: {scan.get('build_system', 'not detected')}\n"
+    doc += f"- **Test framework**: {scan.get('test_framework', 'not detected')}\n"
+    doc += f"- **Project type**: {scan.get('inferred_type', 'unknown')}\n"
+    doc += f"- **Files**: {scan.get('file_count', 0)}\n\n"
+
+    # Components
+    if components:
+        doc += "## Components\n\n"
+        for comp in components:
+            doc += f"### {comp.get('name', 'unnamed')}\n"
+            if comp.get("purpose"):
+                doc += f"- **Purpose**: {comp['purpose']}\n"
+            if comp.get("interfaces"):
+                doc += f"- **Interfaces**: {comp['interfaces']}\n"
+            if comp.get("dependencies"):
+                doc += f"- **Dependencies**: {comp['dependencies']}\n"
+            doc += "\n"
+    elif scan.get("modules"):
+        doc += "## Modules\n\n"
+        for mod in list(scan.get("modules", []) or []):  # type: ignore[call-overload]
+            doc += f"### {mod}\n- **Purpose**: [Describe {mod} purpose]\n\n"
+
+    # Data flow
+    if data_flow:
+        doc += f"## Data Flow\n\n{data_flow}\n\n"
+    else:
+        doc += "## Data Flow\n\n[Describe how data flows between components]\n\n"
+
+    # Dependencies
+    deps: list[str] = list(scan.get("dependencies", []) or [])  # type: ignore[call-overload]
+    if deps:
+        doc += "## External Dependencies\n\n"
+        for dep in deps[:30]:
+            doc += f"- `{dep}`\n"
+        doc += "\n"
+
+    # Entry points
+    eps: list[str] = list(scan.get("entry_points", []) or [])  # type: ignore[call-overload]
+    if eps:
+        doc += "## Entry Points\n\n"
+        for ep in eps:
+            doc += f"- `{ep}`\n"
+        doc += "\n"
+
+    # Language distribution
+    if langs and len(langs) > 1:
+        doc += "## Language Distribution\n\n"
+        for lang_name, count in sorted(langs.items(), key=lambda x: -x[1]):
+            doc += f"- {lang_name}: {count} files\n"
+        doc += "\n"
+
+    # Deployment
+    if deployment:
+        doc += f"## Deployment\n\n{deployment}\n\n"
+
+    # Existing architecture references
+    existing: list[str] = list(scan.get("existing_arch_docs", []) or [])  # type: ignore[call-overload]
+    if existing:
+        doc += "## Related Documents\n\n"
+        for ref in existing:
+            doc += f"- [{ref}]({ref})\n"
+        doc += "\n"
+
+    # Write
+    arch_path = root / "docs" / "architecture.md"
+    arch_path.parent.mkdir(parents=True, exist_ok=True)
+    arch_path.write_text(doc, encoding="utf-8")
+    return arch_path

{specsmith-0.1.4.dev30 → specsmith-0.1.4.dev33}/src/specsmith/auditor.py

@@ -120,11 +120,19 @@ def check_governance_files(root: Path) -> list[AuditResult]:
 
     for f in RECOMMENDED_FILES:
         path = root / f
+        found = path.exists()
+        # For architecture.md, also search subdirectories (e.g. docs/architecture/*.md)
+        if not found and "architecture" in f:
+            found = bool(
+                list((root / "docs").glob("**/architecture*"))
+                + list((root / "docs").glob("**/ARCHITECTURE*"))
+            ) if (root / "docs").is_dir() else False
         results.append(
             AuditResult(
                 name=f"recommended:{f}",
-                passed=path.exists(),
-                message=f"Recommended file {f} {'exists' if path.exists() else 'missing'}",
+                passed=found,
+                message=f"Recommended file {f} {'exists' if found else 'missing'}",
+                fixable=not found,
             )
         )
 
@@ -558,4 +566,42 @@ def run_auto_fix(root: Path, report: AuditReport) -> list[str]:
                 except Exception:  # noqa: BLE001
                     pass  # Best-effort
 
+        # Fix missing recommended files
+        elif result.name == "recommended:docs/architecture.md" and not result.passed:
+            from specsmith.architect import generate_architecture
+
+            try:
+                generate_architecture(root)
+                fixed.append("Generated docs/architecture.md from project scan")
+            except Exception:  # noqa: BLE001
+                # Fallback stub
+                path = root / "docs" / "architecture.md"
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text(
+                    f"# Architecture — {root.name}\n\n"
+                    "[Run `specsmith architect` to populate]\n",
+                    encoding="utf-8",
+                )
+                fixed.append("Created stub docs/architecture.md")
+
+        elif result.name == "recommended:docs/REQUIREMENTS.md" and not result.passed:
+            path = root / "docs" / "REQUIREMENTS.md"
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(
+                "# Requirements\n\nNo requirements defined yet.\n\n"
+                "## REQ-CORE-001\n- **Component**: core\n"
+                "- **Status**: Draft\n- **Description**: [Define]\n",
+                encoding="utf-8",
+            )
+            fixed.append("Created stub docs/REQUIREMENTS.md")
+
+        elif result.name == "recommended:docs/TEST_SPEC.md" and not result.passed:
+            path = root / "docs" / "TEST_SPEC.md"
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(
+                "# Test Specification\n\nNo tests defined yet.\n",
+                encoding="utf-8",
+            )
+            fixed.append("Created stub docs/TEST_SPEC.md")
+
     return fixed

{specsmith-0.1.4.dev30 → specsmith-0.1.4.dev33}/src/specsmith/cli.py

@@ -646,6 +646,68 @@ def _run_guided_architecture(cfg: ProjectConfig, target: Path) -> list[Path]:
     return created
 
 
+@main.command()
+@click.option("--project-dir", type=click.Path(exists=True), default=".", help="Project root.")
+@click.option("--non-interactive", is_flag=True, default=False, help="Skip prompts, auto-generate.")
+def architect(project_dir: str, non_interactive: bool) -> None:
+    """Generate or enrich architecture documentation.
+
+    Scans the project for modules, languages, dependencies, git history,
+    then optionally interviews you about components and data flow.
+    """
+    from specsmith.architect import generate_architecture, scan_project_structure
+
+    root = Path(project_dir).resolve()
+    console.print(f"[bold]Scanning[/bold] {root}...\n")
+    scan = scan_project_structure(root)
+
+    modules: list[str] = list(scan.get("modules", []) or [])  # type: ignore[call-overload]
+    deps_list: list[str] = list(scan.get("dependencies", []) or [])  # type: ignore[call-overload]
+    eps_list: list[str] = list(scan.get("entry_points", []) or [])  # type: ignore[call-overload]
+    existing: list[str] = list(scan.get("existing_arch_docs", []) or [])  # type: ignore[call-overload]
+
+    console.print(f"  Languages: {scan.get('primary_language', '?')}")
+    console.print(f"  Modules: {', '.join(modules) or 'none'}")
+    console.print(f"  Dependencies: {len(deps_list)}")
+    console.print(f"  Entry points: {', '.join(eps_list) or 'none'}")
+    if existing:
+        console.print(f"  Existing arch docs: {', '.join(existing)}")
+    console.print()
+
+    components: list[dict[str, str]] | None = None
+    data_flow = ""
+    deployment = ""
+
+    if not non_interactive:
+        console.print("[bold]Architecture Interview[/bold]\n")
+        comp_str = click.prompt(
+            "Major components (comma-separated)",
+            default=", ".join(modules or ["core"]),
+        )
+        components = []
+        for name in [c.strip() for c in comp_str.split(",") if c.strip()]:
+            purpose = click.prompt(f"  {name} purpose", default="")
+            interfaces = click.prompt(f"  {name} interfaces", default="")
+            components.append({"name": name, "purpose": purpose, "interfaces": interfaces})
+
+        data_flow = click.prompt("\nData flow description", default="")
+        deployment = click.prompt("Deployment notes", default="")
+
+    path = generate_architecture(
+        root, components=components, data_flow=data_flow, deployment=deployment, scan=scan
+    )
+    rel = path.relative_to(root)
+    console.print(f"\n[green]\u2713[/green] Generated {rel}")
+    if existing:
+        console.print(
+            f"  [yellow]Note:[/yellow] Existing docs at {', '.join(existing)} "
+            "are referenced but not merged. Review manually."
+        )
+    console.print(
+        "  [dim]Run \"specsmith audit --project-dir .\" to verify governance health.[/dim]"
+    )
+
+
 # ---------------------------------------------------------------------------
 # Ledger subcommands
 # ---------------------------------------------------------------------------

{specsmith-0.1.4.dev30 → specsmith-0.1.4.dev33}/src/specsmith/importer.py

@@ -997,73 +997,67 @@ def generate_overlay(
     existing_reqs = list(target.glob("docs/**/REQUIREMENTS*")) + list(
         target.glob("docs/**/requirements*")
     )
-    if existing_reqs and not force:
-        pass  # Preserve existing requirements doc
-    else:
+    if not (existing_reqs and not force):
         reqs = "# Requirements\n\nRequirements auto-generated from project detection.\n\n"
-    for module in result.modules:
-        mu = module.upper().replace(" ", "-")
-        reqs += (
-            f"## REQ-{mu}-001\n"
-            f"- **Component**: {module}\n"
-            f"- **Status**: Draft\n"
-            f"- **Description**: [Describe requirements for {module}]\n\n"
-        )
-    if result.build_system:
-        reqs += (
-            "## REQ-BUILD-001\n"
-            f"- **Build system**: {result.build_system}\n"
-            "- **Status**: Draft\n"
-            f"- **Description**: Project builds successfully with {result.build_system}\n\n"
-        )
+        for module in result.modules:
+            mu = module.upper().replace(" ", "-")
+            reqs += (
+                f"## REQ-{mu}-001\n"
+                f"- **Component**: {module}\n"
+                f"- **Status**: Draft\n"
+                f"- **Description**: [Describe requirements for {module}]\n\n"
+            )
+        if result.build_system:
+            reqs += (
+                "## REQ-BUILD-001\n"
+                f"- **Build system**: {result.build_system}\n"
+                "- **Status**: Draft\n"
+                f"- **Description**: Project builds successfully with {result.build_system}\n\n"
+            )
         _write("docs/REQUIREMENTS.md", reqs)
 
     # docs/TEST_SPEC.md — skip if project already has one
     existing_tests = list(target.glob("docs/**/TEST_SPEC*")) + list(
         target.glob("docs/**/test_spec*")
     )
-    if existing_tests and not force:
-        pass  # Preserve existing test spec
-    else:
+    if not (existing_tests and not force):
         tests = "# Test Specification\n\nTests auto-generated from project detection.\n\n"
-    for i, test_file in enumerate(result.test_files[:20], 1):
-        tests += f"## TEST-{i:03d}\n- **File**: {test_file}\n- **Status**: Detected\n"
-        for module in result.modules:
-            if module in test_file:
-                tests += f"- **Requirement**: REQ-{module.upper()}-001\n"
-                break
-        tests += "\n"
+        for i, test_file in enumerate(result.test_files[:20], 1):
+            tests += f"## TEST-{i:03d}\n- **File**: {test_file}\n- **Status**: Detected\n"
+            for module in result.modules:
+                if module in test_file:
+                    tests += f"- **Requirement**: REQ-{module.upper()}-001\n"
+                    break
+            tests += "\n"
         _write("docs/TEST_SPEC.md", tests)
 
     # docs/architecture.md — skip if project has architecture doc anywhere under docs/
     existing_arch = list(target.glob("docs/**/architecture*")) + list(
         target.glob("docs/**/ARCHITECTURE*")
     )
-    if existing_arch and not force:
-        pass  # Preserve existing architecture doc
-    else:
+    if not (existing_arch and not force):
         arch = (
-        f"# Architecture — {name}\n\n"
-        "Architecture auto-generated from project detection.\n\n"
-        "## Overview\n"
-        f"- **Languages**: {lang_display}\n"
-        f"- **Build system**: {result.build_system or 'not detected'}\n"
-        f"- **Test framework**: {result.test_framework or 'not detected'}\n\n"
-    )
-    if result.modules:
-        arch += "## Modules\n"
-        for module in result.modules:
-            arch += f"- **{module}**: [Describe module purpose]\n"
-        arch += "\n"
-    if result.entry_points:
-        arch += "## Entry Points\n"
-        for ep in result.entry_points:
-            arch += f"- `{ep}`\n"
-        arch += "\n"
-    if result.languages:
-        arch += "## Language Distribution\n"
-        for lang_name, count in sorted(result.languages.items(), key=lambda x: -x[1]):
-            arch += f"- {lang_name}: {count} files\n"
+            f"# Architecture — {name}\n\n"
+            "Architecture auto-generated from project detection.\n\n"
+            "## Overview\n"
+            f"- **Languages**: {lang_display}\n"
+            f"- **Build system**: {result.build_system or 'not detected'}\n"
+            f"- **Test framework**: {result.test_framework or 'not detected'}\n\n"
+        )
+        if result.modules:
+            arch += "## Modules\n"
+            for module in result.modules:
+                arch += f"- **{module}**: [Describe module purpose]\n"
+            arch += "\n"
+        if result.entry_points:
+            arch += "## Entry Points\n"
+            for ep in result.entry_points:
+                arch += f"- `{ep}`\n"
+            arch += "\n"
+        if result.languages:
+            arch += "## Language Distribution\n"
+            for lang_name, count in sorted(result.languages.items(), key=lambda x: -x[1]):
+                arch += f"- {lang_name}: {count} files\n"
         _write("docs/architecture.md", arch)
 
     # --- Modular governance files ---

{specsmith-0.1.4.dev30 → specsmith-0.1.4.dev33/src/specsmith.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.1.4.dev30
+Version: 0.1.4.dev33
 Summary: Forge governed project scaffolds from the Agentic AI Development Workflow Specification.
 Author: BitConcepts
 License: MIT

{specsmith-0.1.4.dev30 → specsmith-0.1.4.dev33}/src/specsmith.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ README.md
 pyproject.toml
 src/specsmith/__init__.py
 src/specsmith/__main__.py
+src/specsmith/architect.py
 src/specsmith/auditor.py
 src/specsmith/cli.py
 src/specsmith/compressor.py