consync 0.1.0__py3-none-any.whl

consync/config.py

@@ -0,0 +1,200 @@
+"""Configuration loader for .consync.yaml files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from consync.models import ConsyncConfig, MappingConfig, SyncDirection
+
+DEFAULT_CONFIG_NAME = ".consync.yaml"
+
+# Format auto-detection from file extensions
+EXTENSION_TO_FORMAT: dict[str, str] = {
+    ".xlsx": "xlsx",
+    ".xls": "xlsx",
+    ".csv": "csv",
+    ".json": "json",
+    ".toml": "toml",
+    ".h": "c_header",
+    ".hpp": "c_header",
+    ".hh": "c_header",
+    ".c": "c_header",
+    ".cs": "csharp",
+    ".py": "python",
+    ".rs": "rust",
+    ".v": "verilog",
+    ".sv": "verilog",
+    ".vhd": "vhdl",
+    ".vhdl": "vhdl",
+}
+
+
+def find_config(start_dir: Path | None = None) -> Path | None:
+    """Walk up from start_dir looking for .consync.yaml.
+
+    Similar to how .gitignore or pyproject.toml are found.
+    """
+    if start_dir is None:
+        start_dir = Path.cwd()
+    start_dir = start_dir.resolve()
+
+    for directory in [start_dir, *start_dir.parents]:
+        candidate = directory / DEFAULT_CONFIG_NAME
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def detect_format(filepath: str) -> str:
+    """Auto-detect format from file extension."""
+    ext = Path(filepath).suffix.lower()
+    fmt = EXTENSION_TO_FORMAT.get(ext, "")
+    if not fmt:
+        raise ValueError(
+            f"Cannot auto-detect format for '{filepath}'. "
+            f"Supported extensions: {', '.join(sorted(EXTENSION_TO_FORMAT.keys()))}. "
+            f"Specify format explicitly in .consync.yaml."
+        )
+    return fmt
+
+
+def _parse_direction(raw: str) -> SyncDirection:
+    """Parse direction string from YAML config."""
+    mapping = {
+        "source_to_target": SyncDirection.SOURCE_TO_TARGET,
+        "target_to_source": SyncDirection.TARGET_TO_SOURCE,
+        "both": SyncDirection.BOTH,
+        "s2t": SyncDirection.SOURCE_TO_TARGET,
+        "t2s": SyncDirection.TARGET_TO_SOURCE,
+        "bidirectional": SyncDirection.BOTH,
+    }
+    normalized = raw.lower().strip().replace("-", "_").replace(" ", "_")
+    if normalized not in mapping:
+        raise ValueError(
+            f"Invalid direction '{raw}'. "
+            f"Use: source_to_target, target_to_source, or both."
+        )
+    return mapping[normalized]
+
+
+def _parse_mapping(raw: dict[str, Any], config_dir: Path) -> MappingConfig:
+    """Parse a single mapping entry from YAML."""
+    source = raw.get("source", "")
+    target = raw.get("target", "")
+
+    if not source:
+        raise ValueError("Each mapping must have a 'source' field.")
+    if not target:
+        raise ValueError("Each mapping must have a 'target' field.")
+
+    source_format = raw.get("source_format", "") or raw.get("format_source", "")
+    target_format = raw.get("target_format", "") or raw.get("format_target", "") or raw.get("format", "")
+
+    # Auto-detect formats if not specified
+    if not source_format:
+        source_format = detect_format(source)
+    if not target_format:
+        target_format = detect_format(target)
+
+    direction = _parse_direction(raw.get("direction", "source_to_target"))
+
+    return MappingConfig(
+        source=source,
+        target=target,
+        source_format=source_format,
+        target_format=target_format,
+        direction=direction,
+        precision=int(raw.get("precision", 17)),
+        header_guard=raw.get("header_guard", ""),
+        namespace=raw.get("namespace", ""),
+        module_name=raw.get("module_name", ""),
+        prefix=raw.get("prefix", ""),
+        uppercase_names=raw.get("uppercase_names", True),
+        output_style=raw.get("output_style", "const"),
+        static_const=raw.get("static_const", False),
+        typed_ints=raw.get("typed_ints", True),
+        validators=raw.get("validators", {}),
+    )
+
+
+def load_config(config_path: Path | str | None = None) -> ConsyncConfig:
+    """Load and validate a .consync.yaml configuration.
+
+    Args:
+        config_path: Explicit path to config file. If None, searches
+                     upward from CWD.
+
+    Returns:
+        Parsed ConsyncConfig.
+
+    Raises:
+        FileNotFoundError: If no config file found.
+        ValueError: If config is invalid.
+    """
+    if config_path is None:
+        found = find_config()
+        if found is None:
+            raise FileNotFoundError(
+                f"No {DEFAULT_CONFIG_NAME} found. Run 'consync init' to create one."
+            )
+        config_path = found
+    else:
+        config_path = Path(config_path)
+
+    if not config_path.exists():
+        raise FileNotFoundError(f"Config file not found: {config_path}")
+
+    config_dir = config_path.parent
+
+    with open(config_path) as f:
+        raw = yaml.safe_load(f) or {}
+
+    if not isinstance(raw, dict):
+        raise ValueError(f"Invalid config: expected a YAML mapping, got {type(raw).__name__}")
+
+    raw_mappings = raw.get("mappings", [])
+    if not raw_mappings:
+        raise ValueError("Config must have at least one entry in 'mappings'.")
+
+    mappings = [_parse_mapping(m, config_dir) for m in raw_mappings]
+
+    return ConsyncConfig(
+        mappings=mappings,
+        state_file=raw.get("state_file", ".consync.state.json"),
+        watch_debounce=float(raw.get("watch_debounce", 2.0)),
+        on_conflict=raw.get("on_conflict", "source_wins"),
+    )
+
+
+def generate_default_config() -> str:
+    """Generate a default .consync.yaml template for `consync init`."""
+    return """\
+# consync configuration — https://github.com/naveenkumarbaskaran/consync
+# Sync constants between spreadsheets and source code with full decimal precision.
+
+mappings:
+  - source: constants.xlsx          # Where constants are defined (spreadsheet)
+    target: include/constants.h     # Generated code file
+    direction: both                 # source_to_target | target_to_source | both
+    precision: 17                   # Significant digits (17 = full IEEE 754 double)
+    header_guard: HW_CONSTANTS_H   # C header include guard
+
+    # Optional:
+    # prefix: ""                    # Prefix all constant names (e.g., "HW_")
+    # uppercase_names: true         # Force UPPER_CASE names in output
+
+  # Add more mappings as needed:
+  # - source: parameters.xlsx
+  #   target: src/params.v
+  #   direction: source_to_target
+  #   precision: 12
+  #   module_name: design_params
+
+# Global settings:
+# state_file: .consync.state.json   # Track sync state (gitignore this)
+# watch_debounce: 2.0               # Seconds to wait before re-syncing
+# on_conflict: source_wins          # source_wins | target_wins | fail
+"""

consync/hooks.py

@@ -0,0 +1,81 @@
+"""Git hook installer — adds consync check to pre-commit or pre-push."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+
+HOOK_TEMPLATE = """\
+#!/usr/bin/env bash
+# consync — auto-generated git hook
+# Verifies constants are in sync before {hook_type}.
+# To skip: git {git_cmd} --no-verify
+
+set -euo pipefail
+
+if command -v consync &> /dev/null; then
+    echo "🔍 consync: checking sync state..."
+    if ! consync check; then
+        echo ""
+        echo "❌ Constants out of sync! Run 'consync sync' first."
+        exit 1
+    fi
+    echo "✅ consync: all constants in sync."
+else
+    echo "⚠️  consync not installed — skipping sync check."
+    echo "   Install with: pip install consync"
+fi
+"""
+
+
+def install_git_hook(hook_type: str = "pre-commit"):
+    """Install a git hook that runs 'consync check'.
+
+    Args:
+        hook_type: "pre-commit" or "pre-push"
+
+    Raises:
+        FileNotFoundError: If not in a git repository.
+    """
+    git_dir = _find_git_dir()
+    hooks_dir = git_dir / "hooks"
+    hooks_dir.mkdir(exist_ok=True)
+
+    hook_file = hooks_dir / hook_type
+
+    git_cmd = "commit" if hook_type == "pre-commit" else "push"
+
+    # Check for existing hook
+    if hook_file.exists():
+        existing = hook_file.read_text()
+        if "consync" in existing:
+            click.echo(f"✔️  consync hook already installed in .git/hooks/{hook_type}")
+            return
+
+        # Append to existing hook
+        click.echo(f"⚠️  Existing {hook_type} hook found — appending consync check.")
+        with open(hook_file, "a") as f:
+            f.write("\n\n# --- consync sync check ---\n")
+            f.write(HOOK_TEMPLATE.format(hook_type=hook_type, git_cmd=git_cmd))
+    else:
+        # Create new hook
+        hook_file.write_text(HOOK_TEMPLATE.format(hook_type=hook_type, git_cmd=git_cmd))
+
+    hook_file.chmod(0o755)
+    click.echo(f"✅ Installed consync check in .git/hooks/{hook_type}")
+    click.echo(f"   Will run 'consync check' before every {git_cmd}.")
+    click.echo(f"   Skip with: git {git_cmd} --no-verify")
+
+
+def _find_git_dir() -> Path:
+    """Find the .git directory by walking up from CWD."""
+    cwd = Path.cwd()
+    for directory in [cwd, *cwd.parents]:
+        git_dir = directory / ".git"
+        if git_dir.is_dir():
+            return git_dir
+    raise FileNotFoundError(
+        "Not a git repository. Run this command from within a git repo."
+    )

consync/lock.py

@@ -0,0 +1,118 @@
+"""Lock file — advisory locking to prevent concurrent sync operations.
+
+Uses a .consync.lock file in the project root during sync. If another
+process is already syncing, the lock prevents corruption.
+
+Features:
+  - Advisory lock (not system-level flock — works on all OSes)
+  - Stale lock detection (PID check — if process is dead, lock is reclaimed)
+  - Configurable timeout
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+LOCK_FILENAME = ".consync.lock"
+LOCK_TIMEOUT_SECONDS = 30  # Max age before considering stale
+
+
+class LockError(Exception):
+    """Raised when a lock cannot be acquired."""
+    pass
+
+
+class SyncLock:
+    """Advisory lock file for preventing concurrent sync operations.
+
+    Usage:
+        with SyncLock(project_dir):
+            # ... do sync ...
+    """
+
+    def __init__(self, project_dir: Path | None = None, timeout: float = LOCK_TIMEOUT_SECONDS):
+        self.project_dir = project_dir or Path.cwd()
+        self.lock_path = self.project_dir / LOCK_FILENAME
+        self.timeout = timeout
+        self._acquired = False
+
+    def acquire(self) -> None:
+        """Acquire the lock. Raises LockError if already held by another live process."""
+        if self.lock_path.exists():
+            info = self._read_lock()
+            if info and self._is_stale(info):
+                logger.warning(
+                    "Removing stale lock (PID %s, created %s)",
+                    info.get("pid"), info.get("created"),
+                )
+                self.lock_path.unlink(missing_ok=True)
+            elif info:
+                raise LockError(
+                    f"Another consync process is running (PID {info.get('pid')}, "
+                    f"started {info.get('created')}). "
+                    f"If this is stale, delete {self.lock_path}"
+                )
+
+        # Write lock
+        lock_info = {
+            "pid": os.getpid(),
+            "created": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+            "hostname": os.uname().nodename,
+        }
+        self.lock_path.write_text(json.dumps(lock_info, indent=2))
+        self._acquired = True
+        logger.debug("Lock acquired: %s", self.lock_path)
+
+    def release(self) -> None:
+        """Release the lock."""
+        if self._acquired and self.lock_path.exists():
+            self.lock_path.unlink(missing_ok=True)
+            self._acquired = False
+            logger.debug("Lock released: %s", self.lock_path)
+
+    def _read_lock(self) -> dict | None:
+        """Read lock file contents."""
+        try:
+            return json.loads(self.lock_path.read_text())
+        except (json.JSONDecodeError, OSError):
+            return None
+
+    def _is_stale(self, info: dict) -> bool:
+        """Check if a lock is stale (process dead or too old)."""
+        pid = info.get("pid")
+
+        # Check if process is still alive
+        if pid:
+            try:
+                os.kill(pid, 0)  # Signal 0 = check existence
+            except ProcessLookupError:
+                return True  # Process doesn't exist
+            except PermissionError:
+                pass  # Process exists but we can't signal it
+
+        # Check age
+        created = info.get("created", "")
+        if created:
+            try:
+                lock_time = datetime.fromisoformat(created)
+                age = (datetime.now(timezone.utc) - lock_time).total_seconds()
+                if age > self.timeout:
+                    return True
+            except ValueError:
+                pass
+
+        return False
+
+    def __enter__(self) -> "SyncLock":
+        self.acquire()
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.release()

consync/logging_config.py

@@ -0,0 +1,273 @@
+"""Logging configuration for consync.
+
+Provides structured logging with:
+- Console output (stderr) controlled by --verbose / --debug CLI flags
+- File logging to .consync.log with rotation (default: 5MB × 3 backups)
+- Audit log (.consync.audit.jsonl) — one JSON line per sync event with:
+  timestamp, user, direction, source, target, constants (names + values)
+- Per-module loggers following `consync.*` hierarchy
+
+Usage in any module:
+    import logging
+    logger = logging.getLogger(__name__)
+    logger.debug("Parsed %d constants from %s", count, filepath)
+    logger.info("Synced source → target: %d constants", count)
+    logger.warning("Both files changed — conflict detected")
+
+CLI verbosity levels:
+    (default)    WARNING+ to stderr, INFO+ to file
+    --verbose    INFO+ to stderr, DEBUG+ to file
+    --debug      DEBUG+ to stderr and file
+
+Log file location: .consync.log in the working directory (or config dir).
+Rotation: 5MB max, 3 backup files (.log.1, .log.2, .log.3).
+
+Audit log: .consync.audit.jsonl — append-only, one JSON object per line.
+Retention: configurable max_audit_lines (default 10000 lines ≈ 2-4MB).
+"""
+
+from __future__ import annotations
+
+import getpass
+import json
+import logging
+import logging.handlers
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from consync.models import Constant
+
+# Package-level logger — all modules use children of this
+ROOT_LOGGER_NAME = "consync"
+
+# Defaults
+DEFAULT_LOG_FILE = ".consync.log"
+DEFAULT_AUDIT_FILE = ".consync.audit.jsonl"
+DEFAULT_MAX_BYTES = 5 * 1024 * 1024  # 5 MB
+DEFAULT_BACKUP_COUNT = 3
+DEFAULT_MAX_AUDIT_LINES = 10000
+DEFAULT_FILE_LEVEL = logging.INFO
+DEFAULT_CONSOLE_LEVEL = logging.WARNING
+
+# Format strings
+FILE_FORMAT = "%(asctime)s [%(levelname)-5s] %(name)s: %(message)s"
+CONSOLE_FORMAT = "%(levelname)s: %(message)s"
+DEBUG_FORMAT = "%(asctime)s.%(msecs)03d [%(levelname)-5s] %(name)s:%(funcName)s:%(lineno)d — %(message)s"
+
+
+def setup_logging(
+    *,
+    verbose: bool = False,
+    debug: bool = False,
+    log_file: str | Path | None = DEFAULT_LOG_FILE,
+    log_dir: Path | None = None,
+    max_bytes: int = DEFAULT_MAX_BYTES,
+    backup_count: int = DEFAULT_BACKUP_COUNT,
+    quiet: bool = False,
+) -> logging.Logger:
+    """Configure the consync logging hierarchy.
+
+    Args:
+        verbose: Show INFO+ on console (default: WARNING+).
+        debug: Show DEBUG+ on console AND file.
+        log_file: Log filename (None = disable file logging).
+        log_dir: Directory for log file (default: cwd).
+        max_bytes: Max log file size before rotation.
+        backup_count: Number of rotated backup files to keep.
+        quiet: Suppress all console output (file logging still active).
+
+    Returns:
+        The root 'consync' logger.
+    """
+    logger = logging.getLogger(ROOT_LOGGER_NAME)
+
+    # Avoid duplicate handlers on repeated calls
+    if logger.handlers:
+        return logger
+
+    logger.setLevel(logging.DEBUG)  # Capture everything; handlers filter
+
+    # ─── Console handler (stderr) ───
+    if not quiet:
+        console = logging.StreamHandler()
+        if debug:
+            console.setLevel(logging.DEBUG)
+            console.setFormatter(logging.Formatter(DEBUG_FORMAT, datefmt="%H:%M:%S"))
+        elif verbose:
+            console.setLevel(logging.INFO)
+            console.setFormatter(logging.Formatter(CONSOLE_FORMAT))
+        else:
+            console.setLevel(logging.WARNING)
+            console.setFormatter(logging.Formatter(CONSOLE_FORMAT))
+        logger.addHandler(console)
+
+    # ─── File handler (rotating) ───
+    if log_file:
+        log_path = (log_dir or Path.cwd()) / log_file
+        try:
+            log_path.parent.mkdir(parents=True, exist_ok=True)
+            file_handler = logging.handlers.RotatingFileHandler(
+                log_path,
+                maxBytes=max_bytes,
+                backupCount=backup_count,
+                encoding="utf-8",
+            )
+            file_level = logging.DEBUG if debug else DEFAULT_FILE_LEVEL
+            file_handler.setLevel(file_level)
+            file_handler.setFormatter(logging.Formatter(FILE_FORMAT, datefmt="%Y-%m-%d %H:%M:%S"))
+            logger.addHandler(file_handler)
+        except OSError:
+            # Can't write log file (read-only FS, permissions) — silently skip
+            pass
+
+    return logger
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Get a child logger under the consync namespace.
+
+    Args:
+        name: Typically __name__ (e.g., 'consync.sync', 'consync.parsers.csv_parser')
+
+    Returns:
+        Logger instance.
+    """
+    return logging.getLogger(name)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Audit Log — structured JSON Lines file
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def _get_user() -> str:
+    """Get current OS username for audit trail."""
+    try:
+        return getpass.getuser()
+    except Exception:
+        return "unknown"
+
+
+def _serialize_value(value: Any) -> Any:
+    """Serialize a constant value for JSON audit output."""
+    if isinstance(value, list):
+        return value
+    if isinstance(value, float):
+        return value
+    if isinstance(value, int):
+        return value
+    return str(value)
+
+
+def write_audit_entry(
+    *,
+    direction: str,
+    source: str,
+    target: str,
+    constants: list[Constant],
+    result: str,
+    dry_run: bool = False,
+    audit_file: Path | None = None,
+    max_lines: int = DEFAULT_MAX_AUDIT_LINES,
+) -> None:
+    """Append a structured audit entry to .consync.audit.jsonl.
+
+    Each line is a self-contained JSON object:
+    {
+        "timestamp": "2026-05-05T08:45:12Z",
+        "user": "naveenkumar",
+        "direction": "source → target",
+        "source": "params.csv",
+        "target": "ecu_params.h",
+        "result": "synced",
+        "count": 5,
+        "dry_run": false,
+        "constants": [
+            {"name": "BRAKE_MAX", "value": 250, "unit": "bar"},
+            {"name": "THRESHOLDS", "value": [50, 100, 150]},
+            ...
+        ]
+    }
+
+    Retention: trims oldest lines when file exceeds max_lines.
+    """
+    if audit_file is None:
+        audit_file = Path.cwd() / DEFAULT_AUDIT_FILE
+
+    entry = {
+        "timestamp": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "user": _get_user(),
+        "direction": direction,
+        "source": source,
+        "target": target,
+        "result": result,
+        "count": len(constants),
+        "dry_run": dry_run,
+        "constants": [
+            {
+                "name": c.name,
+                "value": _serialize_value(c.value),
+                **({"unit": c.unit} if c.unit else {}),
+            }
+            for c in constants
+        ],
+    }
+
+    try:
+        audit_file.parent.mkdir(parents=True, exist_ok=True)
+
+        # Append entry
+        with audit_file.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+        # Retention: trim if over max_lines
+        _trim_audit_file(audit_file, max_lines)
+
+    except OSError:
+        # Can't write audit — log warning but don't fail sync
+        logger = logging.getLogger(ROOT_LOGGER_NAME)
+        logger.warning("Could not write audit log to %s", audit_file)
+
+
+def _trim_audit_file(audit_file: Path, max_lines: int) -> None:
+    """Trim audit file to max_lines, keeping newest entries."""
+    try:
+        lines = audit_file.read_text(encoding="utf-8").splitlines()
+        if len(lines) > max_lines:
+            # Keep the last max_lines entries
+            trimmed = lines[-max_lines:]
+            audit_file.write_text("\n".join(trimmed) + "\n", encoding="utf-8")
+    except OSError:
+        pass
+
+
+def read_audit_log(
+    audit_file: Path | None = None,
+    last_n: int = 20,
+) -> list[dict]:
+    """Read the last N entries from the audit log.
+
+    Args:
+        audit_file: Path to .consync.audit.jsonl (default: cwd).
+        last_n: Number of recent entries to return.
+
+    Returns:
+        List of parsed audit entries (newest last).
+    """
+    if audit_file is None:
+        audit_file = Path.cwd() / DEFAULT_AUDIT_FILE
+
+    if not audit_file.exists():
+        return []
+
+    lines = audit_file.read_text(encoding="utf-8").splitlines()
+    entries = []
+    for line in lines[-last_n:]:
+        line = line.strip()
+        if line:
+            try:
+                entries.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+    return entries