ddmodl 0.1.0__tar.gz

ddmodl-0.1.0/.envrc

@@ -0,0 +1 @@
+[[ -d .venv ]] && source .venv/bin/activate

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

@@ -0,0 +1,116 @@
+# Model Ledger — Project Guidelines
+
+## Project Overview
+
+`modl` is a CLI tool for maintaining an **append-only identity ledger** for evolving data models.
+It tracks how model elements (entities and properties) change over time using four CSV tables:
+`concepts`, `revisions`, `contracts`, `bindings`.
+
+The tool is language-agnostic: language adapters produce a diff report in ModL's IR format, which feeds the sync engine. See [README.md](../README.md) for the full picture with examples.
+
+## Architecture
+
+```
+Config YAML  →  BreakingChangeConfig (config.py)
+Diff JSON    →  DiffReport (ir.py)
+               ↓
+             sync() [cli.py → ledger.py]
+               ↓
+        Four CSV files on disk
+```
+
+| Module | Role |
+|--------|------|
+| `cli.py` | Entry point; `modl sync` command via `rich-click` |
+| `config.py` | Pydantic models for the YAML config (namespace, breaking change rules) |
+| `ir.py` | Intermediate representation: `DiffReport`, `EntityChanged`, `PropertyChanged`, `ChangeType` |
+| `models.py` | Pydantic row models for the four ledger tables; `ElementStatus`, `ElementKind` enums (`ENTITY`, `PROPERTY`, `ENUMERATION_SET`, `ENUM_VALUE`) |
+| `ledger.py` | Ledger I/O, multi-level CSV validation, base-36 URI serial encoding |
+
+## Domain Vocabulary
+
+| Term | Meaning |
+|------|---------|
+| **Concept** | The agreed meaning of a model element (stable identity, independent of implementation) |
+| **Revision** | An audit record of any detected change (breaking or not) |
+| **Contract** | A versioned data contract for a concept — each contract captures a distinct variant of the concept's essential metadata |
+| **Binding** | Maps a property contract to a runtime path via an instance label |
+| **Entity** | Top-level model object (e.g., `Vehicle`, `Vehicle.Door`) — receives concepts/revisions/contracts; **no bindings** |
+| **Property** | Field of an entity (e.g., `Vehicle.Speed`, `Vehicle.Door.IsOpen`) — receives concepts/revisions/contracts; **bindings** (one per instance, or one singleton if no instances) |
+| **EnumerationSet** | Vocabulary entity (enum type, unit group, code list) — receives concepts/revisions/contracts but **no bindings**; set `kind: ENUMERATION_SET` in the diff event |
+| **EnumValue** | Child of an `EnumerationSet` (e.g., `SpeedUnit.KMH`) — receives concepts/revisions/contracts but **no bindings**; set `kind: ENUM_VALUE` in the diff event |
+| **Instance** | A concrete occurrence of a multi-instance entity (e.g., `Left`, `Right`) |
+| **Breaking change** | Modification to an attribute listed in `essential_attributes` in the config |
+
+## Coding Conventions
+
+- **Python ≥ 3.11**; all modules start with `from __future__ import annotations`
+- **Type hints everywhere**: use `|` union syntax, `Path` for file paths, `dict[str, Any]` for flexible dicts
+- **Pydantic v2** for all data models: `BaseModel` + `ConfigDict(extra="forbid")` on config models
+- **Enums are `StrEnum`** subclasses with UPPERCASE string values
+- **Field validators** use `@field_validator` + `@classmethod` (Pydantic v2 style)
+- **Docstrings**: concise, meaning-first (e.g., "Indicates whether ..." not "This method checks whether ...")
+- Ledger validation is **fail-fast**: stop and raise `LedgerValidationError` on the first violation
+- URI serials are **base-36 encoded** (lowercase `0-9a-z`): `b36encode(serial)` must match the URI suffix
+
+## Build and Test
+
+```bash
+# Install (with uv)
+uv sync --dev
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=modl
+
+# Lint / format
+ruff check src tests
+ruff format src tests
+
+# Type check
+ty check src
+```
+
+Line length is **120 characters** (ruff).
+
+Lint rules enabled: `E, F, I, UP, PGH, B, SIM`.
+
+## Config File Format
+
+```yaml
+namespace:
+  namespace: "https://myproject.org/model/"   # required; absolute URI ending with / or #
+  prefix: "mp"                                # optional display alias
+entity:
+  name.modified: false      # renames are non-breaking; suppresses --strict warnings
+  instances.added: false    # adding an instance is non-breaking
+  instances.removed: true   # removing an instance is breaking
+  type: true                # breaking — triggers a new contract
+  description: false        # known, non-breaking; suppresses --strict warnings
+property:
+  name.modified: false
+  output_type: true         # breaking — triggers a new contract
+  unit: true                # breaking — triggers a new contract
+  description: false        # known, non-breaking; suppresses --strict warnings
+enumeration_set:
+  name.modified: false
+  values.added: false
+  values.removed: true
+enum_value:
+  name.modified: true
+  symbol: true
+```
+
+All four sections (`entity`, `property`, `enumeration_set`, `enum_value`) are flat `dict[str, bool]` maps. Keys use a flat dotted form for per-op control (`unit.added`, `unit.modified`, `unit.removed`); a plain key is shorthand for all three ops. `true` = breaking, `false` = known non-breaking (silences `--strict`), absent = unknown (warns). Plain `name` is forbidden — use `name.modified`. The structural keys (`name.modified`, `instances.added`, `instances.removed`, `properties.added`, `properties.removed`, `values.added`, `values.removed`) are always recognised by the engine and never produce unknown-key warnings.
+
+On entity `MODIFIED` events, instance-list changes are reported as a directional delta: `instances_added` and `instances_removed` (not the full `instances` list). The plain `instances` key is only valid on entity `ADDED` events.
+
+## Test Conventions
+
+- Use `tmp_path` (pytest built-in) for temporary file I/O
+- Use `caplog` to assert on log output
+- CLI tests use `click.testing.CliRunner`
+- Use `pytest.raises(ValidationError)` to test Pydantic schema violations
+- Prefer round-trip tests (write → read → compare) for I/O code

ddmodl-0.1.0/.gitignore

@@ -0,0 +1,160 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

ddmodl-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,39 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-ast
+      - id: check-builtin-literals
+      - id: check-case-conflict
+      - id: check-docstring-first
+      - id: check-illegal-windows-names
+      - id: check-merge-conflict
+      - id: check-json
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+      - id: check-vcs-permalinks
+      - id: check-shebang-scripts-are-executable
+      - id: trailing-whitespace
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.3
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.9.7
+    hooks:
+      - id: uv-lock
+
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty check
+        entry: uv run ty check
+        language: system
+        pass_filenames: false

ddmodl-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0] - 2026-05-20
+
+### Added
+
+- Everything (init)

ddmodl-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to Model Ledger
+
+## Development Environment
+
+Model Ledger uses [uv](https://docs.astral.sh/uv/) for packaging and
+dependency management. To start developing with Model Ledger, install `uv`
+using the [recommended method](https://docs.astral.sh/uv/#getting-started).
+
+Once `uv` is installed, install the dependencies with the following command:
+
+```
+uv sync
+```
+
+It will create a `.venv` in the root of the project.
+
+If you want to have a shell in the virtual environment you can activate it with (for Linux/MacOS):
+
+```
+. .venv/bin/activate
+```
+
+The package is linked in editable mode so you will not need to reinstall the package when changing something.
+
+Alternatively you can run things in the virtual environment by using a `uv run` prefix for commands, e.g.:
+
+```
+uv run pytest
+```
+
+**The following section commands assume you are in the virtual environment by either activating or prefixing commands with `uv run`!**
+
+### Pre-Commit-Hooks
+
+Pre commit hooks can be setup with:
+
+```
+pre-commit install
+```
+
+### Tests
+
+Run tests with the following command:
+
+```
+pytest --cov-report term-missing --cov=modl -vv
+```
+
+New code should ideally have tests and not break existing tests.
+
+### Type Checking
+
+Model Ledger uses type annotations throughout, and `ty` to do the checking. Run the following to type check Model Ledger:
+
+```
+ty check
+```
+
+### Code Formatting
+
+Model Ledger uses [`ruff`](https://docs.astral.sh/ruff/) for code formatting.
+Since it is very fast it makes sense to setup your editor to format on save.
+
+Use `ruff format` to format all files in the current directory
+
+### Versioning
+
+- This tool is using [semantic versioning](https://semver.org/spec/v2.0.0.html). [CHANGELOG.md](./CHANGELOG.md) should be updated on every source code change.
+- A new version can be bumped with the support of [bump-my-version](https://github.com/callowayproject/bump-my-version), which is a `dev` dependency:
+  ```bash
+  # major,minor,patch
+  bump-my-version bump minor
+  ```