development-engine-vector 0.3.0__py3-none-any.whl

dev/workflow/changelog.py

@@ -0,0 +1,102 @@
+"""CHANGELOG generation and management."""
+
+from datetime import datetime
+from pathlib import Path
+from dev.utils import error, success
+
+
+class ChangelogManager:
+    """Manages changelog.md files."""
+
+    def __init__(self, project_dir):
+        self.project_dir = Path(project_dir).resolve()
+        self.changelog_file = self.project_dir / "changelog.md"
+
+        if not self.changelog_file.exists():
+            error(f"changelog.md not found: {self.changelog_file}")
+
+    def read(self):
+        """Read current CHANGELOG."""
+        return self.changelog_file.read_text()
+
+    def add_version_section(self, version, added=None, changed=None, fixed=None):
+        """Add a new version section to CHANGELOG.
+
+        Args:
+            version: Version string (e.g. "2.0.0")
+            added: List of new features
+            changed: List of changes
+            fixed: List of fixes
+        """
+        today = datetime.now().strftime("%Y-%m-%d")
+        lines = [f"## [{version}] - {today}\n"]
+
+        if added:
+            lines.append("### Added\n")
+            for item in added:
+                lines.append(f"- {item}\n")
+            lines.append("\n")
+
+        if changed:
+            lines.append("### Changed\n")
+            for item in changed:
+                lines.append(f"- {item}\n")
+            lines.append("\n")
+
+        if fixed:
+            lines.append("### Fixed\n")
+            for item in fixed:
+                lines.append(f"- {item}\n")
+            lines.append("\n")
+
+        new_section = "".join(lines)
+
+        # Read current and find insertion point (after intro)
+        text = self.read()
+        lines = text.split("\n")
+
+        # Find first version line to insert before
+        insert_idx = 0
+        for i, line in enumerate(lines):
+            if line.startswith("## ["):
+                insert_idx = i
+                break
+
+        # Insert new section
+        lines.insert(insert_idx, new_section)
+        new_text = "\n".join(lines)
+        self.changelog_file.write_text(new_text)
+        success(f"Added changelog entry for {version}")
+
+    def verify_has_entry(self, version):
+        """Check if version has a changelog entry."""
+        text = self.read()
+        return f"## [{version}]" in text
+
+    def extract_entries(self, version):
+        """Extract Added/Changed/Fixed entries for a version."""
+        text = self.read()
+        # Simple extraction - find version section and parse
+        start = text.find(f"## [{version}]")
+        if start == -1:
+            return {"added": [], "changed": [], "fixed": []}
+
+        # Find next version or end
+        next_version = text.find("## [", start + 1)
+        section = text[start : next_version if next_version != -1 else len(text)]
+
+        result = {"added": [], "changed": [], "fixed": []}
+        current_section = None
+
+        for line in section.split("\n"):
+            line = line.strip()
+            if line.startswith("### Added"):
+                current_section = "added"
+            elif line.startswith("### Changed"):
+                current_section = "changed"
+            elif line.startswith("### Fixed"):
+                current_section = "fixed"
+            elif line.startswith("- ") and current_section:
+                result[current_section].append(line[2:])
+
+        return result

dev/workflow/preflight.py

@@ -0,0 +1,307 @@
+"""Pre-flight validation checks."""
+
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from dev.utils import error, info, yellow
+
+# Project-specific preflight modules — each must define:
+#   is_applicable(project_dir) -> bool
+#   run(project_dir) -> list[dict]  (list of check result dicts)
+try:
+    from dev.workflow.cda import CdaPreflightModule
+    PREFLIGHT_MODULES = [CdaPreflightModule]
+except ImportError:
+    PREFLIGHT_MODULES = []
+
+
+class PreflightChecks:
+    """Validates project state before release."""
+
+    def __init__(self, project_dir):
+        self.project_dir = Path(project_dir).resolve()
+        self.issues = []
+        self.checks = []
+
+    def _record_check(self, name, passed, message=None, details=None):
+        item = {
+            "name": name,
+            "passed": passed,
+            "message": message or ("OK" if passed else "Failed"),
+        }
+        if details is not None:
+            item["details"] = details
+        self.checks.append(item)
+
+        if not passed and message:
+            self.issues.append(message)
+
+    def run_all(self, full=False, report_path=None):
+        """Run all pre-flight checks."""
+        self.issues = []
+        self.checks = []
+
+        self.check_git_status()
+        self.check_version_file()
+        self.check_changelog()
+        self.check_pyproject()
+        self.check_readme()
+        self.check_license()
+        self.check_requirements()
+        self.check_local_build_directory()
+        self.check_sensitive_files()
+
+        if full:
+            self.check_branch("main")
+            self.check_git_remote()
+            self.check_package_build()
+
+        # Run project-specific modules
+        for module in PREFLIGHT_MODULES:
+            if module.is_applicable(self.project_dir):
+                extra = module.run(self.project_dir)
+                for check in extra:
+                    self.checks.append(check)
+                    if not check.get("passed"):
+                        self.issues.append(check.get("message", "Unknown failure"))
+
+        if report_path:
+            self.write_report(report_path, full)
+
+        if self.issues:
+            print(yellow("\n⚠ Pre-flight check failures:\n"))
+            for issue in self.issues:
+                print(f"  • {issue}")
+            error("Fix issues before proceeding")
+
+        info("All pre-flight checks passed.")
+        return True
+
+    def check_git_status(self):
+        """Verify no uncommitted changes."""
+        try:
+            output = subprocess.run(
+                ["git", "status", "--porcelain"],
+                cwd=self.project_dir,
+                capture_output=True,
+                text=True,
+                check=True,
+            ).stdout.strip()
+
+            if output:
+                self._record_check(
+                    "git_status",
+                    False,
+                    "Uncommitted changes in git (run git status)",
+                    output,
+                )
+            else:
+                self._record_check("git_status", True, "Clean git working tree")
+
+        except subprocess.CalledProcessError:
+            self._record_check("git_status", False, "Not a git repository or git unavailable")
+
+    def check_branch(self, expected="main"):
+        """Verify current branch name."""
+        try:
+            branch = subprocess.run(
+                ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+                cwd=self.project_dir,
+                capture_output=True,
+                text=True,
+                check=True,
+            ).stdout.strip()
+
+            if branch != expected:
+                self._record_check(
+                    "git_branch",
+                    False,
+                    f"Current branch is '{branch}'; expected '{expected}'",
+                )
+            else:
+                self._record_check("git_branch", True, f"On branch '{branch}'")
+
+        except subprocess.CalledProcessError:
+            self._record_check("git_branch", False, "Unable to determine git branch")
+
+    def check_git_remote(self):
+        """Verify origin remote exists."""
+        try:
+            remote = subprocess.run(
+                ["git", "remote", "get-url", "origin"],
+                cwd=self.project_dir,
+                capture_output=True,
+                text=True,
+                check=True,
+            ).stdout.strip()
+            self._record_check("git_remote", True, f"Origin remote configured: {remote}")
+        except subprocess.CalledProcessError:
+            self._record_check("git_remote", False, "Git origin remote is not configured")
+
+    def check_version_file(self):
+        """Verify VERSION file exists and is valid."""
+        version_file = self.project_dir / "version"
+        if not version_file.exists():
+            self._record_check("version_file", False, "version file not found")
+            return
+
+        text = version_file.read_text().strip()
+        if not re.fullmatch(r"\d+\.\d+\.\d+", text):
+            self._record_check("version_file", False, f"Invalid version format: {text}")
+        else:
+            self._record_check("version_file", True, f"Version file is valid: {text}")
+
+    def check_changelog(self):
+        """Verify CHANGELOG.md exists."""
+        changelog = self.project_dir / "changelog.md"
+        if not changelog.exists():
+            self._record_check("changelog", False, "changelog.md not found")
+        else:
+            self._record_check("changelog", True, "changelog.md exists")
+
+    def check_pyproject(self):
+        """Verify pyproject.toml exists and parses."""
+        pyproject = self.project_dir / "pyproject.toml"
+        if not pyproject.exists():
+            self._record_check("pyproject", False, "pyproject.toml not found")
+            return
+
+        try:
+            try:
+                import tomllib  # type: ignore[import-not-found]
+            except ModuleNotFoundError:
+                import tomli as tomllib  # type: ignore[import-not-found,no-redef]
+
+            tomllib.loads(pyproject.read_text())
+            self._record_check("pyproject", True, "pyproject.toml is valid")
+        except Exception as e:
+            self._record_check("pyproject", False, f"pyproject.toml is invalid: {e}")
+
+    def check_readme(self):
+        """Verify README exists."""
+        readme = self.project_dir / "readme.md"
+        if not readme.exists():
+            self._record_check("readme", False, "readme.md not found")
+        else:
+            self._record_check("readme", True, "readme.md exists")
+
+    def check_license(self):
+        """Verify LICENSE exists."""
+        license_file = self.project_dir / "license"
+        if not license_file.exists():
+            self._record_check("license", False, "license not found")
+        else:
+            self._record_check("license", True, "license exists")
+
+    def check_requirements(self):
+        """Verify requirements files exist and are parseable."""
+        for name in ["requirements.txt", "dev-requirements.txt"]:
+            file_path = self.project_dir / name
+            if file_path.exists():
+                text = file_path.read_text().strip()
+                if not text:
+                    self._record_check(name, False, f"{name} is empty")
+                else:
+                    lines = [line.strip() for line in text.splitlines() if line.strip() and not line.strip().startswith("#")]
+                    self._record_check(name, True, f"{name} contains {len(lines)} entries", lines[:10])
+            else:
+                self._record_check(name, True, f"{name} not present")
+
+    def check_local_build_directory(self):
+        """Detect local build output directories that can shadow the build backend."""
+        build_dir = self.project_dir / "build"
+        if build_dir.exists():
+            result = subprocess.run(
+                ["git", "check-ignore", "-q", str(build_dir)],
+                cwd=self.project_dir,
+                capture_output=True,
+            )
+            if result.returncode == 0:
+                self._record_check("local_build_dir", True, "build/ present but properly gitignored")
+                return
+            self._record_check(
+                "local_build_dir",
+                False,
+                "Local build/ directory exists and may shadow the build backend",
+                str(build_dir),
+            )
+        else:
+            self._record_check("local_build_dir", True, "No local build/ directory present")
+
+    def check_sensitive_files(self):
+        """Warn if local secret files are present and not gitignored."""
+        env_file = self.project_dir / ".env"
+        if env_file.exists():
+            # Check if it's properly gitignored
+            result = subprocess.run(
+                ["git", "check-ignore", "-q", str(env_file)],
+                cwd=self.project_dir,
+                capture_output=True,
+            )
+            if result.returncode == 0:
+                self._record_check("env_file", True, ".env present but properly gitignored")
+            else:
+                self._record_check("env_file", False, ".env exists and is NOT gitignored — risk of credential exposure")
+        else:
+            self._record_check("env_file", True, ".env not present")
+
+    def check_package_build(self):
+        """Verify the project can build distributions."""
+        try:
+            with tempfile.TemporaryDirectory() as tmpdir:
+                env = os.environ.copy()
+                env.pop("PYTHONPATH", None)
+                subprocess.run(
+                    [sys.executable, "-m", "build", str(self.project_dir), "--sdist", "--wheel", "--outdir", tmpdir],
+                    cwd=tmpdir,
+                    env=env,
+                    capture_output=True,
+                    text=True,
+                    check=True,
+                )
+            self._record_check("package_build", True, "Project builds successfully")
+        except subprocess.CalledProcessError as exc:
+            details = exc.stderr or exc.stdout
+            if "No module named build" in details or "build.__main__" in details:
+                details = (
+                    "Python build backend 'build' is missing or shadowed by a local build/ directory. "
+                    "Install the build package and ensure the repository root does not contain a build/ package directory."
+                )
+            self._record_check(
+                "package_build",
+                False,
+                "Project build failed",
+                details,
+            )
+        except FileNotFoundError:
+            self._record_check("package_build", False, "Python build tools not available")
+
+    def write_report(self, report_path, full=False):
+        """Write a structured preflight report."""
+        report_path = Path(report_path)
+        report_path.parent.mkdir(parents=True, exist_ok=True)
+        report = {
+            "project": str(self.project_dir),
+            "full": full,
+            "summary": {
+                "passed": len(self.issues) == 0,
+                "issues": len(self.issues),
+            },
+            "checks": self.checks,
+        }
+        report_path.write_text(json.dumps(report, indent=2))
+        info(f"Preflight report written to {report_path}")
+
+    def report(self):
+        """Report check results."""
+        if not self.issues:
+            print("  All pre-flight checks passed ✓\n")
+        return len(self.issues) == 0
+        """Report check results."""
+        if not self.issues:
+            print("  All pre-flight checks passed ✓\n")
+        return len(self.issues) == 0

dev/workflow/release.py

@@ -0,0 +1,217 @@
+"""dev.workflow.release — release orchestration for the Development Engine Vector.
+
+All actions are recorded to dev.kernel.db for run history.
+"""
+
+from pathlib import Path
+
+from dev.utils import header, info, success, error, warn, cyan, run_command
+from dev.kernel import db
+from dev.vcs.git import GitOps
+from dev.workflow.versioning import VersionManager
+from dev.workflow.changelog import ChangelogManager
+from dev.workflow.preflight import PreflightChecks
+
+
+class ReleaseOrchestrator:
+    """Coordinates the release workflow."""
+
+    def __init__(self, project_dir):
+        self.project_dir = Path(project_dir).resolve()
+        self.git = GitOps(self.project_dir)
+        self.version = VersionManager(self.project_dir)
+        self.changelog = ChangelogManager(self.project_dir)
+        self.checks = PreflightChecks(self.project_dir)
+
+    def preflight(self):
+        """Run pre-flight checks and verify branch state."""
+        header("Pre-flight Checks")
+        project_name = self.project_dir.name
+        run_id = db.record_run(project_name, "preflight", "running")
+        try:
+            self.checks.run_all()
+            self.ensure_main_branch()
+            db.finish_run(run_id, "pass")
+        except SystemExit:
+            db.finish_run(run_id, "fail")
+            raise
+        return True
+
+    def ensure_main_branch(self):
+        branch = self.git.get_current_branch()
+        if branch != "main":
+            warn(f"Current branch is '{branch}', but release should run from 'main'.")
+            error("Switch to main before releasing.")
+
+    def bump_and_sync(self, level, custom_version=None):
+        """Bump version and sync to all files."""
+        header("Version Management")
+
+        if custom_version:
+            new_version = custom_version
+            info(f"Using custom version: {new_version}")
+        else:
+            old_version = self.version.read()
+            new_version = self.version.bump(level)
+            info(f"Bumping {level}: {old_version} → {new_version}")
+
+        self.version.write(new_version)
+        success(f"Updated version file to {new_version}")
+
+        targets = self.version.get_sync_targets()
+        self.version.sync_to_files(new_version, targets)
+        return new_version
+
+    def validate_changelog_entry(self, version):
+        if not self.changelog.verify_has_entry(version):
+            error(
+                f"changelog.md does not contain an entry for version {version}."
+                " Add a section before releasing."
+            )
+        success(f"Found changelog entry for {version}")
+
+    def commit_and_tag(self, version):
+        """Commit changes and create tag."""
+        header("Git Operations")
+
+        files_to_stage = [
+            "version",
+            "changelog.md",
+            "pyproject.toml",
+            "setup.py",
+            "vscode_ark/__init__.py",
+        ]
+
+        existing = [path for path in files_to_stage if (self.project_dir / path).exists()]
+        if not existing:
+            error("No release files were found to stage.")
+
+        info("Staging files...")
+        self.git.stage_files(existing)
+
+        message = f"Release v{version}: Version bump and changelog"
+        self.git.commit(message)
+        self.git.create_tag(version, f"Release {version}")
+
+        info("Pushing to origin...")
+        self.git.push_main(push_tags=True)
+
+    def build(self):
+        """Build distributions."""
+        header("Build")
+        project_name = self.project_dir.name
+        version = self.version.read()
+        run_id = db.record_run(project_name, "build", "running", version=version)
+        info("Building source and wheel distributions...")
+        try:
+            run_command(["python", "-m", "build", "--sdist", "--wheel"], cwd=self.project_dir)
+            db.finish_run(run_id, "pass")
+            success("Build complete")
+        except SystemExit:
+            db.finish_run(run_id, "fail")
+            raise
+
+    def publish(self):
+        """Publish to PyPI."""
+        header("PyPI Publish")
+        project_name = self.project_dir.name
+        version = self.version.read()
+        run_id = db.record_run(project_name, "publish", "running", version=version)
+        info(f"Publishing version {version}...")
+        try:
+            run_command(["pypi", "publish", str(self.project_dir)], cwd=self.project_dir)
+            db.finish_run(run_id, "pass")
+        except SystemExit:
+            warn("Primary publish command failed, trying fallback path...")
+            try:
+                run_command(["python", "-m", "pypi", "publish", str(self.project_dir)], cwd=self.project_dir)
+                db.finish_run(run_id, "pass")
+            except SystemExit:
+                db.finish_run(run_id, "fail")
+                raise
+        db.upsert_project(project_name, str(self.project_dir), version=version)
+        success(f"Published {version} to PyPI")
+
+    def bootstrap(self, install_editable=True, install_dependencies=True, install_dev_dependencies=False):
+        """Bootstrap the project environment."""
+        header("Bootstrap / Sync")
+
+        if (self.project_dir / ".gitmodules").exists():
+            info("Initializing git submodules...")
+            self.git.run_git(["submodule", "update", "--init", "--recursive"])
+            success("Submodules initialized")
+
+        if install_dependencies and (self.project_dir / "requirements.txt").exists():
+            info("Installing requirements.txt...")
+            run_command(["python", "-m", "pip", "install", "-r", "requirements.txt"], cwd=self.project_dir)
+            success("Installed requirements")
+
+        if install_dev_dependencies and (self.project_dir / "dev-requirements.txt").exists():
+            info("Installing dev-requirements.txt...")
+            run_command(["python", "-m", "pip", "install", "-r", "dev-requirements.txt"], cwd=self.project_dir)
+            success("Installed dev requirements")
+
+        if install_editable and (self.project_dir / "pyproject.toml").exists():
+            info("Installing project in editable mode...")
+            run_command(["python", "-m", "pip", "install", "-e", "."], cwd=self.project_dir)
+            success("Editable install complete")
+
+        success("Bootstrap complete")
+
+    def run_tests(self):
+        header("Run Tests")
+        info("Executing pytest...")
+        run_command(["python", "-m", "pytest", "-q"], cwd=self.project_dir)
+        success("Tests passed")
+
+    def run_compile(self):
+        header("Compile Check")
+        info("Checking Python syntax across project...")
+        run_command(["python", "-m", "compileall", "-q", "."], cwd=self.project_dir)
+        success("Compilation check passed")
+
+    def run_lint(self):
+        header("Lint")
+        info("Running ruff if available...")
+        try:
+            run_command(["python", "-m", "ruff", "check", "."], cwd=self.project_dir)
+            success("Lint check passed")
+        except SystemExit:
+            warn("ruff is not installed or lint failed. Install ruff to enable lint checks.")
+
+    def full_release(self, level=None, version=None, skip_build=False, skip_publish=False, dry_run=False):
+        """Execute full release workflow."""
+        header("Full Release Workflow")
+        project_name = self.project_dir.name
+
+        self.preflight()
+        new_version = self.bump_and_sync(level, version)
+        self.validate_changelog_entry(new_version)
+
+        if dry_run:
+            info("Dry run enabled; skipping commit, build, and publish steps.")
+            return
+
+        run_id = db.record_run(project_name, "release", "running", version=new_version)
+        try:
+            self.commit_and_tag(new_version)
+            if not skip_build:
+                self.build()
+            if not skip_publish:
+                self.publish()
+            db.finish_run(run_id, "pass")
+        except SystemExit:
+            db.finish_run(run_id, "fail")
+            raise
+
+        header("Release Complete")
+        info(f"Version {cyan(new_version)} is now live on PyPI")
+        print()
+
+    def sync_versions_only(self):
+        """Just sync version without release."""
+        header("Version Sync")
+        version = self.version.read()
+        targets = self.version.get_sync_targets()
+        self.version.sync_to_files(version, targets)
+        success(f"Synced version {version} to all files")