Merge pull request #20 from GlobalTypeSystem/gts-spec-0.13

feat: rebase the gts-python to gts spec 0.13

Author: Artifizer

.gitignore

@@ -29,6 +29,7 @@ wheels/
 *.egg
 
 # Virtual environments
+.venv/
 venv/
 ENV/
 env/

.gts-spec

@@ -1,6 +1,30 @@
 CI := 1
 
-.PHONY: help build dev-fmt all check fmt lint mypy test security update-spec e2e coverage
+# These recipes rely on POSIX tools (command -v, touch, rm -rf, sleep, kill,
+# cat) and POSIX syntax (background jobs, inline env assignments). Require Bash
+# explicitly so GNU Make does not fall back to cmd.exe via COMSPEC on Windows.
+# On Windows, run these targets from a Bash environment (e.g. Git Bash / MSYS2).
+SHELL := /bin/bash
+
+# Python: PYTHON_BOOTSTRAP is used only to create the virtual environment;
+# PYTHON is the venv interpreter used by all other targets.
+PYTHON_BOOTSTRAP ?= $(shell command -v python3 2>/dev/null || command -v python 2>/dev/null || echo python3)
+PY_ENV_DIR ?= .venv
+ifeq ($(OS),Windows_NT)
+PYTHON ?= $(PY_ENV_DIR)/Scripts/python
+else
+PYTHON ?= $(PY_ENV_DIR)/bin/python
+endif
+PY_ENV_STAMP := $(PY_ENV_DIR)/.stamp
+INSTALL_STAMP := $(PY_ENV_DIR)/.install-stamp
+
+ifneq ($(filter install-local uninstall-local,$(MAKECMDGOALS)),)
+ifeq ($(origin PYTHON),file)
+$(error PYTHON must be set for local package targets (examples: venv: PYTHON=.venv/bin/python3.13 make install-local; global: PYTHON=python3.13 make install-local))
+endif
+endif
+
+.PHONY: help py-env install build install-local uninstall-local clean dev-fmt all check fmt lint clippy mypy test security update-spec e2e coverage
 
 # Default target - show help
 .DEFAULT_GOAL := help
@@ -9,61 +33,103 @@ CI := 1
 help:
 	@awk '/^# / { desc=substr($$0, 3) } /^[a-zA-Z0-9_-]+:/ && desc { target=$$1; sub(/:$$/, "", target); printf "%-20s - %s\n", target, desc; desc="" }' Makefile | sort
 
-# Build/install the package in development mode
-build:
-	pip install -e ./gts
+# -------- Environment --------
 
-# Fix formatting issues
-dev-fmt:
-	ruff format gts/src
+# Create/update the virtual environment and install dev/test dependencies
+py-env: $(PY_ENV_STAMP)
 
-# Run all checks and build
-all: check build
+$(PY_ENV_STAMP): gts/pyproject.toml .gts-spec/tests/requirements.txt Makefile
+	@echo "Creating/updating Python virtual environment in $(PY_ENV_DIR)..."
+	$(PYTHON_BOOTSTRAP) -m venv $(PY_ENV_DIR)
+	$(PYTHON) -m pip install --upgrade pip
+	$(PYTHON) -m pip install -r .gts-spec/tests/requirements.txt
+	$(PYTHON) -m pip install --no-deps 'httprunner>=4,<5'
+	$(PYTHON) -m pip install ruff mypy
+	@touch $@
+
+# Install gts package into the venv (editable, for development)
+install: $(INSTALL_STAMP)
+
+$(INSTALL_STAMP): $(PY_ENV_STAMP) gts/pyproject.toml
+	$(PYTHON) -m pip install -e ./gts
+	@touch $@
+
+# Build source and wheel distributions into dist/
+build: py-env
+	$(PYTHON) -m pip install --upgrade build
+	$(PYTHON) -m build --outdir dist ./gts
+
+# Install the locally built wheel, equivalent to installing the published gts package
+install-local: build
+	$(PYTHON) -m pip install --force-reinstall dist/gts-*.whl
+
+# Uninstall gts from the selected interpreter
+uninstall-local:
+	$(PYTHON) -m pip uninstall --yes gts
+	@rm -f $(INSTALL_STAMP)
+
+# Remove venv and build artifacts
+clean:
+	rm -rf $(PY_ENV_DIR) dist/ gts/dist/ gts/*.egg-info
+
+# -------- Code quality --------
+
+# Fix formatting issues
+dev-fmt: py-env
+	$(PYTHON) -m ruff format gts/src
 
 # Check code formatting
-fmt:
-	ruff format --check gts/src
+fmt: py-env
+	$(PYTHON) -m ruff format --check gts/src
 
 # Run linter (ruff)
-lint:
-	ruff check gts/src
+lint: py-env
+	$(PYTHON) -m ruff check gts/src
 
 # Run clippy-equivalent linter with auto-fix
-clippy:
-	ruff check --fix gts/src
+clippy: py-env
+	$(PYTHON) -m ruff check --fix gts/src
 
 # Run type checker
-mypy:
-	mypy gts/src/gts --ignore-missing-imports
+mypy: py-env
+	$(PYTHON) -m mypy gts/src/gts --ignore-missing-imports
 
-# Run all tests
-test:
-	pytest tests/ -v
+# -------- Tests --------
 
-# Check dependencies for security vulnerabilities
-security:
-	@command -v pip-audit >/dev/null || (echo "Installing pip-audit..." && pip install pip-audit)
-	pip-audit
+# Run all tests
+test: install
+	$(PYTHON) -m pytest tests/ -v
 
 # Measure code coverage
-coverage:
-	pytest tests/ --cov=gts --cov-report=xml --cov-report=term
-
-# Update gts-spec submodule to latest
-update-spec:
-	git submodule update --remote .gts-spec
+coverage: install
+	$(PYTHON) -m pip install 'pytest-cov>=5,<7'
+	$(PYTHON) -m pytest tests/ --cov=gts --cov-report=xml --cov-report=term
 
 # Run end-to-end tests against gts-spec
-e2e: build
+e2e: install
 	@echo "Starting server in background..."
-	@python -m gts server --port 8000 & echo $$! > .server.pid
+	@$(PYTHON) -m gts server --port 8000 & echo $$! > .server.pid
 	@sleep 2
 	@echo "Running e2e tests..."
-	@PYTHONDONTWRITEBYTECODE=1 pytest -p no:cacheprovider --log-file=e2e.log ./.gts-spec/tests || (kill `cat .server.pid` 2>/dev/null; rm -f .server.pid; exit 1)
+	@PYTHONDONTWRITEBYTECODE=1 $(PYTHON) -m pytest -p no:cacheprovider --log-file=e2e.log ./.gts-spec/tests || (kill `cat .server.pid` 2>/dev/null; rm -f .server.pid; exit 1)
 	@echo "Stopping server..."
 	@kill `cat .server.pid` 2>/dev/null || true
 	@rm -f .server.pid
 	@echo "E2E tests completed successfully"
 
+# -------- Misc --------
+
+# Check dependencies for security vulnerabilities
+security: py-env
+	$(PYTHON) -m pip install pip-audit
+	$(PYTHON) -m pip_audit
+
+# Update gts-spec submodule to latest
+update-spec:
+	git submodule update --remote .gts-spec
+
+# Run all checks and build
+all: check build
+
 # Run all quality checks
 check: fmt lint test e2e

Makefile

@@ -6,6 +6,8 @@ A minimal, idiomatic Python library for working with **GTS** ([Global Type Syste
 
 ## Roadmap
 
+Current supported GTS spec version: 0.13
+
 Featureset:
 
 - [x] **OP#1 - ID Validation**: Verify identifier syntax using regex patterns
@@ -22,7 +24,8 @@ Featureset:
 - [x] **OP#9 - Version Casting**: Transform instances between compatible MINOR versions
 - [x] **OP#10 - Query Execution**: Filter identifier collections using the GTS query language
 - [x] **OP#11 - Attribute Access**: Retrieve property values and metadata using the attribute selector (`@`)
-- [ ] **OP#12 - Schema Validation**: Validate schema against its precedent schema
+- [x] **OP#12 - Type Derivation Validation**: Validate that derived GTS Type Schemas correctly extend their base chain
+- [x] **OP#13 - Schema Traits Validation**: Validate schema traits (`x-gts-traits-schema` / `x-gts-traits`).
 
 See details in [gts/README.md](gts/README.md)
 
@@ -32,26 +35,46 @@ Other GTS spec [Reference Implementation](https://github.com/globaltypesystem/gt
 - [x] **CLI** - command-line interface for all GTS operations
 - [x] **Web server** - a non-production web-server with REST API for the operations processing and testing
 - [x] **x-gts-ref support** - to support special GTS entity reference annotation in schemas
-- [ ] **YAML support** - to support YAML files (*.yml, *.yaml) as input files
-- [ ] **TypeSpec support** - add [typespec.io](https://typespec.io/) files (*.tsp) support
-- [ ] **UUID for instances** - to support UUID as ID in JSON instances
+- [x] **YAML support** - to support YAML files (*.yml, *.yaml) as input files
+- [x] **UUID for instances** - to support UUID as ID in JSON instances
+- [ ] **TypeSpec support** - direct support for [typespec.io](https://typespec.io/) files (*.tsp) input files
 
 Technical Backlog:
 
-- [ ] **Code coverage** - target is 90%
-- [ ] **Documentation** - add documentation for all the features
-- [ ] **Interface** - export publicly available interface and keep cli and others private
-- [ ] **Server API** - finalise the server API
-- [ ] **Final code cleanup** - remove unused code, denormalize, add critical comments, etc.
+- [x] **Code coverage** - target is 90%
+- [x] **Documentation** - add documentation for all the features
+- [x] **Interface** - export publicly available interface and keep cli and others private
+- [x] **Server API** - finalise the server API
+- [x] **Final code cleanup** - remove unused code, denormalize, add critical comments, etc.
 
 ## Installation
 
+GTS requires Python 3.9 or later.
+
+### Local development
+
+From the repository root, build and install the same wheel artifact that will later be published and installed with `pip install gts`. `install-local` requires an explicit `PYTHON` environment variable so you choose the target interpreter:
+
+```bash
+PYTHON=.venv/bin/python make install-local
+```
+
+This creates the `.venv` virtual environment when needed, writes source and wheel distributions to `dist/`, and installs the wheel into the interpreter specified by `PYTHON`. Activate it to use the locally installed library and CLI:
+
 ```bash
-# install in editable mode
-pip install -e ./gts
+source .venv/bin/activate
+python -c "import gts; print(gts.__file__)"
+gts --help
+```
+
+Use `make build` when you only need the distributable artifacts. Remove the locally installed package with `PYTHON=.venv/bin/python make uninstall-local`. For an editable installation while changing source files, use `make install`.
 
-# install from PyPI, not supported yet
-# pip install gts
+### Published package
+
+After `gts` is published to PyPI, install it with:
+
+```bash
+pip install gts
 ```
 
 ## Usage