consync 0.1.0__tar.gz

consync-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default owner for everything in the repo
+* @naveenkumarbaskaran

consync-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,94 @@
+# Copilot Instructions for consync
+
+## What is consync?
+
+A Python CLI that bidirectionally syncs constants between spreadsheets (xlsx/csv/json/toml)
+and source code (C, C#, Python, Rust, Verilog, VHDL). Built for embedded/firmware engineers
+who need full IEEE 754 precision (17 significant digits).
+
+## Project Structure
+
+```
+consync/
+├── cli.py              # Click CLI — init, sync, check, watch, diff, recover, log, status
+├── sync.py             # Core engine — direction detection, backup, validate, render
+├── config.py           # .consync.yaml loader + format auto-detect
+├── models.py           # Constant, MappingConfig, ConsyncConfig dataclasses
+├── state.py            # SyncState (MD5 hashes for change detection)
+├── watcher.py          # File watcher — queues events, retries on lock, startup sync
+├── hooks.py            # Git pre-commit hook installer
+├── backup.py           # Timestamped snapshots + recovery
+├── lock.py             # Advisory .consync.lock with stale-PID detection
+├── validators.py       # Range/type/pattern/length checks
+├── logging_config.py   # 3-layer: console, rotating file, audit JSONL
+├── parsers/            # xlsx, csv, json, toml, c_header
+└── renderers/          # c_header, csharp, python, rust, verilog, vhdl, json, csv
+tests/
+├── test_parsers.py     # Parser unit tests
+├── test_renderers.py   # Renderer unit tests
+├── test_sync.py        # Sync engine + state tests
+├── test_arrays.py      # Array constant support tests
+├── test_safety.py      # Backup, recover, validation, lock tests
+└── ...
+```
+
+## Key Patterns
+
+- **Universal model**: `Constant(name: str, value: int|float|str|list, unit: str, description: str)`
+- **Every format is a parser AND/OR renderer** — enables bootstrap and round-trip
+- **Safety-first for firmware**: backup before write, validate before render, lock during sync
+- **Watcher queues events** — never drops changes, retries on lock conflict
+- **Audit trail**: JSONL log with every constant value for traceability
+
+## When Editing Code
+
+1. **Adding a parser/renderer**: Register in `__init__.py` of the package + add to `EXTENSION_TO_FORMAT` in `config.py`
+2. **Adding CLI command**: Use `@main.command()` in `cli.py`, lazy imports inside function
+3. **Modifying sync behavior**: Ensure backup + validation + lock flow is preserved
+4. **Running tests**: `pytest tests/ -v` (151+ tests, takes ~0.5s)
+
+## Constraints
+
+- Python >=3.10
+- Minimal deps: openpyxl, click, watchdog, pyyaml
+- Precision: 17 significant digits default (IEEE 754 round-trip fidelity)
+- Never drop file changes in watcher (queue + coalesce)
+- Lock must be held during all write operations
+- Backup must exist before overwriting any file
+
+## Config Example (.consync.yaml)
+
+```yaml
+mappings:
+  - source: calibration.xlsx
+    target: firmware/config.h
+    direction: source_to_target
+    precision: 17
+    header_guard: CONFIG_H
+    static_const: true
+    typed_ints: true
+    validators:
+      BRAKE_PRESSURE:
+        min: 0
+        max: 300
+      TIMEOUT_MS:
+        type: int
+        min: 100
+```
+
+## CLI Command Reference
+
+| Command | Purpose |
+|---------|---------|
+| `consync init` | Create .consync.yaml template |
+| `consync sync` | Sync all mappings |
+| `consync sync --dry-run` | Show what would be synced |
+| `consync sync --from source` | Force direction |
+| `consync check` | CI gate — exit 1 if out of sync |
+| `consync watch` | File watcher with auto-sync |
+| `consync diff` | Unified diff preview |
+| `consync recover --list` | List backup snapshots |
+| `consync recover --file X --last` | Restore most recent backup |
+| `consync log` | Show audit trail with values |
+| `consync install-hook` | Install git pre-commit hook |
+| `consync status` | Show sync state per mapping |

consync-0.1.0/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      all:
+        patterns:
+          - "*"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      github-actions:
+        patterns:
+          - "*"

consync-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check consync/ tests/
+
+      - name: Run tests
+        run: pytest --cov=consync --cov-report=xml -v
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml
+        continue-on-error: true

consync-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,40 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 1" # Every Monday at 06:00 UTC
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [python]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:${{ matrix.language }}"

consync-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

consync-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.coverage
+.sync_state.json
+*.xlsx
+!examples/**/*.xlsx
+.consync.state.json
+
+# consync runtime files
+.consync.log
+.consync.log.*
+.consync.audit.jsonl
+.consync.state.json
+.consync.lock
+.consync/

consync-0.1.0/CLAUDE.md

@@ -0,0 +1,132 @@
+# consync — AI Assistant Instructions (CLAUDE.md)
+
+## Project Overview
+
+**consync** is a pip-installable Python CLI for bidirectional synchronisation between
+spreadsheets (xlsx/csv/json/toml) and source code constant declarations (C, C#, Python,
+Rust, Verilog, VHDL). It preserves full IEEE 754 precision (17 significant digits) and
+supports embedded/firmware workflows.
+
+**Repo:** https://github.com/naveenkumarbaskaran/consync  
+**Author:** Naveen Kumar Baskaran (naveenkb142@gmail.com)  
+**Python:** >=3.10  
+**Build:** hatchling  
+**CLI:** Click  
+
+---
+
+## Architecture
+
+```
+.consync.yaml  →  Config Loader  →  Sync Engine  →  State Tracker (.consync.state.json)
+                       ↓                  ↓
+               ┌──────────────┐    ┌──────────────┐
+               │   Parsers    │    │  Renderers   │
+               │ xlsx csv json│    │ c_header csv │
+               │ toml c_header│    │ csharp python│
+               └──────────────┘    │ rust verilog │
+                                   │ vhdl json    │
+                                   └──────────────┘
+```
+
+**Key design:** Every format can be both parser AND renderer. This enables bootstrap
+(create spreadsheet from existing code) and round-trip (code → spreadsheet → code).
+
+---
+
+## Module Map
+
+| File | Purpose |
+|------|---------|
+| `consync/cli.py` | Click CLI entry point — all commands |
+| `consync/sync.py` | Core sync engine — direction detection, orchestration |
+| `consync/config.py` | YAML config loader, format auto-detection |
+| `consync/models.py` | `Constant`, `MappingConfig`, `ConsyncConfig` dataclasses |
+| `consync/state.py` | `SyncState` — MD5 hashes per-mapping for change detection |
+| `consync/watcher.py` | File watcher with debounce, queue, lock-retry |
+| `consync/hooks.py` | Git hook installer |
+| `consync/backup.py` | Auto-snapshot before every write + recovery |
+| `consync/lock.py` | Advisory `.consync.lock` with stale-PID detection |
+| `consync/validators.py` | User-defined value constraints (range/type/pattern) |
+| `consync/logging_config.py` | 3-layer logging (console, file, audit JSONL) |
+| `consync/parsers/` | One module per input format |
+| `consync/renderers/` | One module per output format |
+
+---
+
+## Conventions
+
+- **Dataclass-centric**: All data flows through `Constant(name, value, unit, description, metadata)`
+- **No global state**: Config/state passed explicitly; watcher is the only stateful entry point
+- **Format string IDs**: `"xlsx"`, `"csv"`, `"c_header"`, `"csharp"`, `"python"`, `"rust"`, `"verilog"`, `"vhdl"`, `"json"`, `"toml"`
+- **Tests**: pytest, grouped by feature in `tests/`. Run with `pytest tests/ -v`
+- **Logging**: Use `logger = logging.getLogger(__name__)` in every module. Audit via `write_audit_entry()`
+
+---
+
+## Adding a New Parser
+
+1. Create `consync/parsers/my_format.py` with function `parse(filepath: Path) -> list[Constant]`
+2. Register in `consync/parsers/__init__.py` → `PARSERS` dict
+3. Add extension mapping in `consync/config.py` → `EXTENSION_TO_FORMAT`
+4. Add tests in `tests/test_parsers.py`
+
+## Adding a New Renderer
+
+1. Create `consync/renderers/my_format.py` with function `render(constants: list[Constant], filepath: Path, config: MappingConfig)`
+2. Register in `consync/renderers/__init__.py` → `RENDERERS` dict
+3. Add extension mapping in `consync/config.py` → `EXTENSION_TO_FORMAT`
+4. Add tests in `tests/test_renderers.py`
+
+---
+
+## Safety Features (Critical for Embedded)
+
+| Feature | Module | Behaviour |
+|---------|--------|-----------|
+| **Backup** | `backup.py` | Copies target to `.consync/backups/` before every write. Retains 20/file. |
+| **Recovery** | `backup.py` + CLI `recover` | Restore any file by timestamp. Creates safety backup before restoring. |
+| **Validation** | `validators.py` | Blocks sync if values violate `validators:` rules in config. |
+| **Lock** | `lock.py` | Advisory PID-based lock prevents concurrent writes. Auto-reclaims stale. |
+| **Audit** | `logging_config.py` | Every sync logged with timestamp, user, direction, all values. |
+| **Queue** | `watcher.py` | Events during debounce are queued (never dropped). Lock conflicts retried 3x. |
+| **Startup sync** | `watcher.py` | On `consync watch`, a full sync runs first to recover any drift. |
+
+---
+
+## Common Tasks
+
+### Run tests
+```bash
+cd /path/to/consync
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+### Run a specific test file
+```bash
+pytest tests/test_safety.py -v
+```
+
+### Test the CLI manually
+```bash
+cd examples/
+consync sync --dry-run
+consync diff
+consync log -n 5
+consync recover --list
+```
+
+### Add a new CLI command
+1. Add function with `@main.command()` decorator in `cli.py`
+2. Follow pattern: import lazily inside function, handle errors, call `sys.exit(1)` on failure
+
+---
+
+## Do NOT
+
+- Put secrets/credentials in any file (there are none in this project)
+- Modify `pyproject.toml` build config without testing `pip install -e .`
+- Break round-trip precision (17 sig digits must survive parse→render→parse)
+- Remove the lock/backup from sync.py — these are safety-critical for firmware engineers
+- Add heavy dependencies (keep it lightweight: openpyxl, click, watchdog, pyyaml only)

consync-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing to consync
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Development Setup
+
+```bash
+git clone https://github.com/naveenkumarbaskaran/consync.git
+cd consync
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+pytest
+```
+
+All 77+ tests should pass. Tests cover precision, parsers, renderers, sync engine, and CLI.
+
+## Code Style
+
+This project uses [ruff](https://docs.astral.sh/ruff/) for linting and formatting:
+
+```bash
+ruff check .
+ruff format .
+```
+
+## Making Changes
+
+1. Fork the repo and create a feature branch from `main`
+2. Make your changes with clear, descriptive commits
+3. Add or update tests for any new functionality
+4. Ensure all tests pass and linting is clean
+5. Open a pull request against `main`
+
+## Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat: add TOML renderer for constants output`
+- `fix: handle hex values in C header parser`
+- `test: add round-trip precision tests for verilog`
+- `docs: update CLI reference for --from flag`
+
+## Architecture Overview
+
+```
+Source (xlsx/csv/json/toml) ←→ [consync engine] ←→ Target (C/Python/Rust/Verilog/VHDL)
+```
+
+### Key Modules
+
+- `consync/parsers/` — Read constants from various file formats
+- `consync/renderers/` — Write constants to target languages
+- `consync/sync.py` — Core sync engine (direction detection, state management)
+- `consync/precision.py` — IEEE 754 precision formatting
+- `consync/cli.py` — Click-based CLI entry point
+- `consync/watcher.py` — File watcher for continuous sync
+- `consync/state.py` — Hash-based change detection
+
+## Adding a New Parser
+
+1. Create `consync/parsers/your_format.py`
+2. Implement a function that returns `list[Constant]`
+3. Decorate with `@register("format_name")`
+4. Import in `consync/parsers/__init__.py`
+5. Add tests in `tests/test_parsers.py`
+
+## Adding a New Renderer
+
+1. Create `consync/renderers/your_format.py`
+2. Implement a function that writes constants to a file
+3. Decorate with `@register("format_name")`
+4. Import in `consync/renderers/__init__.py`
+5. Add tests in `tests/test_renderers.py`
+
+## Reporting Issues
+
+- Use GitHub Issues with a clear title and reproduction steps
+- Include your Python version, OS, and error output
+- For sync issues, include your `.consync.yaml` (redact any sensitive paths)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.