domainforge 0.13.0

package/scripts/bump-version.sh

@@ -0,0 +1,245 @@
+#!/usr/bin/env bash
+# bump-version.sh - Semantic version bumping for DomainForge
+# Usage: ./scripts/bump-version.sh [major|minor|patch|X.Y.Z] [OPTIONS]
+#
+# Updates version in:
+# - domainforge-core/Cargo.toml
+# - domainforge-python/pyproject.toml
+# - domainforge-typescript/package.json
+
+set -euo pipefail
+
+# ============================================================================
+# Configuration
+# ============================================================================
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+# Flags
+DRY_RUN=false
+NO_COMMIT=false
+
+# ============================================================================
+# Helper Functions
+# ============================================================================
+log_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
+log_success() { echo -e "${GREEN}[✓]${NC} $1"; }
+log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+log_error() { echo -e "${RED}[✗]${NC} $1"; }
+
+usage() {
+    cat <<EOF
+Usage: $(basename "$0") [VERSION_TYPE] [OPTIONS]
+
+Bump version across all DomainForge package files.
+
+VERSION_TYPE:
+    major           Bump major version (X.0.0)
+    minor           Bump minor version (x.Y.0)
+    patch           Bump patch version (x.y.Z)
+    X.Y.Z           Set explicit version (e.g., 1.2.3)
+    X.Y.Z-suffix    Set version with pre-release (e.g., 1.2.3-alpha)
+
+OPTIONS:
+    --dry-run       Show what would be changed without modifying files
+    --no-commit     Update files but don't create git commit
+    -h, --help      Show this help message
+
+FILES UPDATED:
+    - domainforge-core/Cargo.toml
+    - domainforge-python/pyproject.toml
+    - domainforge-typescript/package.json
+
+EXAMPLES:
+    $(basename "$0") patch                    # 0.6.2 -> 0.6.3
+    $(basename "$0") minor                    # 0.6.2 -> 0.7.0
+    $(basename "$0") major                    # 0.6.2 -> 1.0.0
+    $(basename "$0") 2.0.0                    # Set explicit version
+    $(basename "$0") 1.0.0-beta.1             # Pre-release version
+    $(basename "$0") patch --dry-run          # Preview changes
+EOF
+}
+
+get_current_version() {
+    grep -m1 '^version = ' "$PROJECT_ROOT/domainforge-core/Cargo.toml" | sed 's/version = "\(.*\)"/\1/'
+}
+
+calculate_new_version() {
+    local current="$1"
+    local bump_type="$2"
+    
+    # Handle explicit version
+    if [[ "$bump_type" =~ ^[0-9]+\.[0-9]+\.[0-9]+ ]]; then
+        echo "$bump_type"
+        return
+    fi
+    
+    # Parse current version (strip pre-release suffix for calculation)
+    local base_version="${current%-*}"
+    IFS='.' read -r major minor patch <<< "$base_version"
+    
+    case "$bump_type" in
+        major)
+            major=$((major + 1))
+            minor=0
+            patch=0
+            ;;
+        minor)
+            minor=$((minor + 1))
+            patch=0
+            ;;
+        patch)
+            patch=$((patch + 1))
+            ;;
+        *)
+            log_error "Invalid bump type: $bump_type"
+            exit 1
+            ;;
+    esac
+    
+    echo "${major}.${minor}.${patch}"
+}
+
+update_cargo_toml() {
+    local current="$1"
+    local new="$2"
+    
+    if $DRY_RUN; then
+        log_info "Would update domainforge-core/Cargo.toml: $current -> $new"
+    else
+        sed -i "s/^version = \"$current\"/version = \"$new\"/" "$PROJECT_ROOT/domainforge-core/Cargo.toml"
+        log_success "Updated domainforge-core/Cargo.toml"
+    fi
+}
+
+update_pyproject_toml() {
+    local current="$1"
+    local new="$2"
+    
+    if $DRY_RUN; then
+        log_info "Would update pyproject.toml: $current -> $new"
+    else
+        sed -i "s/^version = \"$current\"/version = \"$new\"/" "$PROJECT_ROOT/domainforge-python/pyproject.toml"
+        log_success "Updated domainforge-python/pyproject.toml"
+    fi
+}
+
+update_package_json() {
+    local new="$1"
+    
+    if $DRY_RUN; then
+        log_info "Would update package.json to: $new"
+    else
+        # Use jq to update version (avoids npm dependency issues)
+        cd "$PROJECT_ROOT"
+        jq --arg v "$new" '.version = $v' domainforge-typescript/package.json > domainforge-typescript/package.json.tmp && mv domainforge-typescript/package.json.tmp domainforge-typescript/package.json
+        log_success "Updated domainforge-typescript/package.json"
+    fi
+}
+
+# ============================================================================
+# Parse Arguments
+# ============================================================================
+VERSION_TYPE=""
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --dry-run)
+            DRY_RUN=true
+            shift
+            ;;
+        --no-commit)
+            NO_COMMIT=true
+            shift
+            ;;
+        -h|--help)
+            usage
+            exit 0
+            ;;
+        -*)
+            log_error "Unknown option: $1"
+            usage
+            exit 1
+            ;;
+        *)
+            if [[ -z "$VERSION_TYPE" ]]; then
+                VERSION_TYPE="$1"
+            else
+                log_error "Too many arguments"
+                usage
+                exit 1
+            fi
+            shift
+            ;;
+    esac
+done
+
+if [[ -z "$VERSION_TYPE" ]]; then
+    log_error "Version type required"
+    usage
+    exit 1
+fi
+
+# ============================================================================
+# Main
+# ============================================================================
+cd "$PROJECT_ROOT"
+
+echo ""
+echo "=============================================="
+echo "  DomainForge Version Bump"
+echo "=============================================="
+echo ""
+
+if $DRY_RUN; then
+    log_warn "DRY RUN MODE - No files will be modified"
+    echo ""
+fi
+
+# Get current version
+CURRENT_VERSION=$(get_current_version)
+log_info "Current version: $CURRENT_VERSION"
+
+# Calculate new version
+NEW_VERSION=$(calculate_new_version "$CURRENT_VERSION" "$VERSION_TYPE")
+log_info "New version:     $NEW_VERSION"
+echo ""
+
+# Validate new version
+if [[ "$CURRENT_VERSION" == "$NEW_VERSION" ]]; then
+    log_warn "New version is same as current version"
+fi
+
+# Update files
+log_info "Updating version files..."
+update_cargo_toml "$CURRENT_VERSION" "$NEW_VERSION"
+update_pyproject_toml "$CURRENT_VERSION" "$NEW_VERSION"
+update_package_json "$NEW_VERSION"
+
+# Create git commit
+if ! $DRY_RUN && ! $NO_COMMIT; then
+    echo ""
+    log_info "Creating git commit..."
+    git add domainforge-core/Cargo.toml domainforge-python/pyproject.toml domainforge-typescript/package.json
+    git commit -m "chore: bump version to v$NEW_VERSION" --quiet
+    log_success "Created commit: chore: bump version to v$NEW_VERSION"
+fi
+
+echo ""
+echo "=============================================="
+log_success "Version bumped to $NEW_VERSION"
+echo "=============================================="
+
+# Output just the version for use in scripts
+if $DRY_RUN; then
+    echo ""
+    echo "# Output (for script chaining):"
+fi
+echo "$NEW_VERSION"

package/scripts/check_unused_test_imports.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""
+Scan test files (domainforge-core/tests/*.rs) for `use` statements and detect likely unused imports.
+Only flags imports where the `use` imports a single identifier and that identifier is not used elsewhere in the file.
+This heuristic avoids removing multi-import groups that might be used via macros or shadowed names.
+"""
+
+import re
+from pathlib import Path
+
+repo_root = Path(__file__).resolve().parents[1]
+
+
+def get_test_files():
+    tests_dir = repo_root / "domainforge-core" / "tests"
+    return list(tests_dir.glob("*.rs"))
+
+
+USE_RE = re.compile(r"^use\s+([^;]+);")
+GROUPED_RE = re.compile(r"^(?P<prefix>[^:;{]+::)\{(?P<items>[^}]+)\}$")
+SIMPLE_SINGLE_IDENT_RE = re.compile(r"^(?P<path>[^:]+)::(?P<ident>[A-Za-z0-9_]+)$")
+
+candidates = []
+for f in get_test_files():
+    text = f.read_text(encoding="utf8")
+    lines = text.splitlines()
+    for i, line in enumerate(lines, start=1):
+        m = USE_RE.match(line.strip())
+        if not m:
+            continue
+        use_expr = m.group(1).strip()
+        # Detect grouped imports like `foo::bar::{A, B as C}`
+        group_match = GROUPED_RE.match(use_expr)
+        if group_match:
+            prefix = group_match.group("prefix")
+            items = [it.strip() for it in group_match.group("items").split(",")]
+            for item in items:
+                # Handle `A as B` case, take alias as `B` or `A` when no alias
+                parts = [p.strip() for p in item.split(" as ")]
+                if len(parts) == 2:
+                    ident = parts[1]
+                else:
+                    ident = parts[0]
+                # If the item has a path `kg::KnowledgeGraph`, only the last segment
+                # (the type or ident) is relevant for references in the file.
+                if "::" in ident:
+                    ident = ident.split("::")[-1]
+                # Don't try to remove common traits which are used via method calls
+                if ident == "FromStr":
+                    continue
+                occ = [
+                    j
+                    for j, line_text in enumerate(lines, start=1)
+                    if j != i and re.search(r"\b" + re.escape(ident) + r"\b", line_text)
+                ]
+                if not occ:
+                    candidates.append((str(f), i, line.strip(), ident))
+            continue
+        # Try to capture single import names like `crate::graph::Graph` or `domainforge_core::Graph` or `std::fmt::Result`
+        # Remove trailing traits like "pub use"? Not present here
+        if "::" not in use_expr:
+            continue
+        # Extract the last path component
+        ident = use_expr.split("::")[-1]
+        if not ident.isidentifier():
+            continue
+        # Search if ident appears elsewhere in file
+        # Exclude the import line
+        occ = [
+            j
+            for j, line_text in enumerate(lines, start=1)
+            if j != i and re.search(r"\b" + re.escape(ident) + r"\b", line_text)
+        ]
+        # Skip flagging trait names which are used implicitly (FromStr)
+        if ident == "FromStr":
+            continue
+        if not occ:
+            candidates.append((str(f), i, line.strip(), ident))
+
+if candidates:
+    print("Potential unused single-ident imports detected:")
+    for path, line_no, line, ident in candidates:
+        print(f"{path}:{line_no}: {line}  (ident={ident})")
+else:
+    print("No obvious single-identifier unused imports detected in test files.")

package/scripts/ci_tasks.py

@@ -0,0 +1,379 @@
+#!/usr/bin/env python3
+"""
+CI Tasks Script - Cross-platform CI automation helpers.
+
+This script consolidates common CI tasks to reduce duplication across
+GitHub Actions workflows and ensure consistency between local and CI environments.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import tarfile
+import zipfile
+from pathlib import Path
+from typing import Optional
+
+
+def check_size(file_path: str, max_bytes: int, label: str = "File") -> int:
+    """
+    Check if a file's size is within the specified limit.
+
+    Args:
+        file_path: Path to the file to check
+        max_bytes: Maximum allowed size in bytes
+        label: Human-readable label for error messages
+
+    Returns:
+        0 if size is within limit, 1 otherwise
+    """
+    path = Path(file_path)
+
+    if not path.exists():
+        print(f"::error::File not found: {file_path}", file=sys.stderr)
+        return 1
+
+    if not path.is_file():
+        print(f"::error::Not a file: {file_path}", file=sys.stderr)
+        return 1
+
+    size = path.stat().st_size
+    size_mb = size / (1024 * 1024)
+    max_mb = max_bytes / (1024 * 1024)
+
+    print(f"{label} size: {size:,} bytes ({size_mb:.2f} MB)")
+
+    if size > max_bytes:
+        print(
+            f"::error::{label} exceeds {max_bytes:,} bytes ({max_mb:.2f} MB): "
+            f"actual size is {size:,} bytes ({size_mb:.2f} MB)",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(f"[OK] {label} is within size limit ({max_mb:.2f} MB)")
+    return 0
+
+
+def package_archive(
+    input_path: str,
+    output_path: str,
+    archive_format: Optional[str] = None,
+    base_name: Optional[str] = None,
+) -> int:
+    """
+    Package a file or directory into an archive.
+
+    Args:
+        input_path: Path to file or directory to package
+        output_path: Output archive path
+        archive_format: 'zip' or 'tar.gz' (auto-detected from output_path if not specified)
+        base_name: Base name for the archived file (defaults to input filename)
+
+    Returns:
+        0 on success, 1 on failure
+    """
+    input_p = Path(input_path)
+    output_p = Path(output_path)
+
+    if not input_p.exists():
+        print(f"::error::Input path not found: {input_path}", file=sys.stderr)
+        return 1
+
+    # Auto-detect format from extension
+    if archive_format is None:
+        if output_path.endswith(".zip"):
+            archive_format = "zip"
+        elif output_path.endswith(".tar.gz") or output_path.endswith(".tgz"):
+            archive_format = "tar.gz"
+        else:
+            print(
+                f"::error::Cannot determine archive format from: {output_path}",
+                file=sys.stderr,
+            )
+            return 1
+
+    # Determine the name to use inside the archive
+    if base_name is None:
+        base_name = input_p.name
+
+    try:
+        output_p.parent.mkdir(parents=True, exist_ok=True)
+
+        if archive_format == "zip":
+            with zipfile.ZipFile(output_p, "w", zipfile.ZIP_DEFLATED) as zf:
+                if input_p.is_file():
+                    zf.write(input_p, base_name)
+                else:
+                    for file in input_p.rglob("*"):
+                        if file.is_file():
+                            arcname = base_name / file.relative_to(input_p)
+                            zf.write(file, arcname)
+            print(f"[OK] Created ZIP archive: {output_p}")
+
+        elif archive_format == "tar.gz":
+            with tarfile.open(output_p, "w:gz") as tf:
+                if input_p.is_file():
+                    tf.add(input_p, arcname=base_name)
+                else:
+                    tf.add(input_p, arcname=base_name)
+            print(f"[OK] Created tar.gz archive: {output_p}")
+
+        else:
+            print(
+                f"::error::Unsupported archive format: {archive_format}",
+                file=sys.stderr,
+            )
+            return 1
+
+        return 0
+
+    except Exception as e:
+        print(f"::error::Failed to create archive: {e}", file=sys.stderr)
+        return 1
+
+
+def verify_cli_binary(binary_path: str, expected_output: Optional[str] = None) -> int:
+    """
+    Verify that a CLI binary can execute successfully.
+
+    Args:
+        binary_path: Path to the binary to test
+        expected_output: Optional substring to check in output
+
+    Returns:
+        0 if binary runs successfully, 1 otherwise
+    """
+    path = Path(binary_path)
+
+    if not path.exists():
+        print(f"::error::Binary not found: {binary_path}", file=sys.stderr)
+        return 1
+
+    if not path.is_file():
+        print(f"::error::Not a file: {binary_path}", file=sys.stderr)
+        return 1
+
+    # Make executable on Unix-like systems
+    if platform.system() != "Windows":
+        path.chmod(path.stat().st_mode | 0o111)
+
+    # Set up environment for dynamic libraries
+    env = os.environ.copy()
+    bin_dir = str(path.parent.absolute())
+
+    if platform.system() == "Darwin":
+        dyld_path = env.get("DYLD_LIBRARY_PATH", "")
+        env["DYLD_LIBRARY_PATH"] = f"{bin_dir}:{dyld_path}" if dyld_path else bin_dir
+    elif platform.system() == "Linux":
+        ld_path = env.get("LD_LIBRARY_PATH", "")
+        env["LD_LIBRARY_PATH"] = f"{bin_dir}:{ld_path}" if ld_path else bin_dir
+    elif platform.system() == "Windows":
+        path_env = env.get("PATH", "")
+        env["PATH"] = f"{bin_dir};{path_env}" if path_env else bin_dir
+
+    try:
+        print(f"Running: {binary_path} --version")
+        result = subprocess.run(
+            [str(path), "--version"],
+            capture_output=True,
+            text=True,
+            env=env,
+            timeout=10,
+        )
+
+        if result.returncode != 0:
+            print(
+                f"::error::Binary exited with code {result.returncode}", file=sys.stderr
+            )
+            print(f"stdout: {result.stdout}", file=sys.stderr)
+            print(f"stderr: {result.stderr}", file=sys.stderr)
+            return 1
+
+        output = result.stdout + result.stderr
+        print("[OK] Binary executed successfully")
+        print(f"Output: {output.strip()}")
+
+        if expected_output and expected_output not in output:
+            print(
+                f"::error::Expected output '{expected_output}' not found in: {output}",
+                file=sys.stderr,
+            )
+            return 1
+
+        return 0
+
+    except subprocess.TimeoutExpired:
+        print("::error::Binary execution timed out", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"::error::Failed to execute binary: {e}", file=sys.stderr)
+        return 1
+
+
+def _is_safe_path(target_dir: str, member_path: str) -> bool:
+    abs_target = os.path.realpath(target_dir)
+    abs_member = os.path.realpath(os.path.join(target_dir, member_path))
+    return abs_member.startswith(abs_target + os.sep) or abs_member == abs_target
+
+
+def _validate_tar_member(target_dir: str, member: tarfile.TarInfo) -> None:
+    if member.name.startswith("/") or ".." in member.name.split("/"):
+        raise ValueError(f"Unsafe path in tar: {member.name}")
+    if member.issym() or member.islnk():
+        raise ValueError(f"Symlink/hardlink in tar: {member.name}")
+    if not _is_safe_path(target_dir, member.name):
+        raise ValueError(f"Path traversal in tar: {member.name}")
+
+
+def _validate_zip_member(target_dir: str, filename: str) -> None:
+    if filename.startswith("/") or ".." in filename.split("/"):
+        raise ValueError(f"Unsafe path in zip: {filename}")
+    if not _is_safe_path(target_dir, filename):
+        raise ValueError(f"Path traversal in zip: {filename}")
+
+
+def unpack_and_verify(archive_path: str, binary_name: str) -> int:
+    """
+    Unpack an archive and verify the binary inside can execute.
+
+    Args:
+        archive_path: Path to the archive
+        binary_name: Name of the binary to verify
+
+    Returns:
+        0 on success, 1 on failure
+    """
+    archive_p = Path(archive_path)
+
+    if not archive_p.exists():
+        print(f"::error::Archive not found: {archive_path}", file=sys.stderr)
+        return 1
+
+    temp_dir = Path("tmp_verify_unpack")
+    temp_dir.mkdir(exist_ok=True)
+
+    try:
+        if archive_path.endswith(".zip"):
+            with zipfile.ZipFile(archive_p, "r") as zf:
+                for info in zf.infolist():
+                    _validate_zip_member(str(temp_dir), info.filename)
+                zf.extractall(temp_dir)
+        elif archive_path.endswith(".tar.gz") or archive_path.endswith(".tgz"):
+            with tarfile.open(archive_p, "r:gz") as tf:
+                for member in tf.getmembers():
+                    _validate_tar_member(str(temp_dir), member)
+                if sys.version_info >= (3, 12):
+                    tf.extractall(temp_dir, filter="data")
+                else:
+                    tf.extractall(temp_dir)
+        else:
+            print(
+                f"::error::Unsupported archive format: {archive_path}", file=sys.stderr
+            )
+            return 1
+
+        print(f"[OK] Unpacked archive to {temp_dir}")
+
+        # Find the binary
+        binary_path = None
+        for file in temp_dir.rglob(binary_name):
+            if file.is_file():
+                binary_path = file
+                break
+
+        # Also check with .exe extension on Windows
+        if binary_path is None and platform.system() == "Windows":
+            for file in temp_dir.rglob(f"{binary_name}.exe"):
+                if file.is_file():
+                    binary_path = file
+                    break
+
+        if binary_path is None:
+            print(
+                f"::error::Binary '{binary_name}' not found in archive", file=sys.stderr
+            )
+            print("Archive contents:", file=sys.stderr)
+            for file in temp_dir.rglob("*"):
+                print(f"  {file.relative_to(temp_dir)}", file=sys.stderr)
+            return 1
+
+        print(f"Found binary: {binary_path}")
+
+        # Verify it runs
+        return verify_cli_binary(str(binary_path))
+
+    finally:
+        # Cleanup
+        if temp_dir.exists():
+            shutil.rmtree(temp_dir, ignore_errors=True)
+
+
+def main() -> int:
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description="CI tasks automation script",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Command to run")
+
+    # check-size command
+    size_parser = subparsers.add_parser("check-size", help="Check file size")
+    size_parser.add_argument("--file", required=True, help="File to check")
+    size_parser.add_argument(
+        "--max-bytes", type=int, required=True, help="Maximum size in bytes"
+    )
+    size_parser.add_argument(
+        "--label", default="File", help="Label for output messages"
+    )
+
+    # package command
+    package_parser = subparsers.add_parser("package", help="Package files into archive")
+    package_parser.add_argument(
+        "--input", required=True, help="Input file or directory"
+    )
+    package_parser.add_argument("--output", required=True, help="Output archive path")
+    package_parser.add_argument(
+        "--format", choices=["zip", "tar.gz"], help="Archive format"
+    )
+    package_parser.add_argument("--base-name", help="Base name for archived content")
+
+    # verify-cli command
+    verify_parser = subparsers.add_parser(
+        "verify-cli", help="Verify CLI binary executes"
+    )
+    verify_parser.add_argument("--binary", required=True, help="Path to binary")
+    verify_parser.add_argument("--expected-output", help="Expected substring in output")
+
+    # unpack-verify command
+    unpack_parser = subparsers.add_parser(
+        "unpack-verify", help="Unpack archive and verify binary"
+    )
+    unpack_parser.add_argument("--archive", required=True, help="Archive path")
+    unpack_parser.add_argument(
+        "--binary-name", required=True, help="Binary name to verify"
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "check-size":
+        return check_size(args.file, args.max_bytes, args.label)
+    elif args.command == "package":
+        return package_archive(args.input, args.output, args.format, args.base_name)
+    elif args.command == "verify-cli":
+        return verify_cli_binary(args.binary, args.expected_output)
+    elif args.command == "unpack-verify":
+        return unpack_and_verify(args.archive, args.binary_name)
+    else:
+        parser.print_help()
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())