feat: Package scaffolding, CI, lint/mypy/coverage gating

Adds the repo plumbing the rest of the branch builds on:

  - pyproject (uv build backend, mypy strict, 100% branch coverage gate,
    clickhouse-connect dev dep)
  - Makefile (install / lint / typecheck / test)
  - pre-commit (ruff, uv-lock, flagsmith-lint-tests, local mypy)
  - GitHub Actions CI: lint → typecheck → ClickHouse docker-compose →
    test → cobertura coverage gate
  - engine-test-data submodule pinned at v3.7.0
  - docker-compose for the ClickHouse parity harness
  - CODEOWNERS, renovate, .python-version, gitignore additions
  - py.typed marker and empty package skeleton

beep boop

Author: khvn26

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+jobs:
+  ci:
+    name: CI
+    runs-on: ubuntu-latest
+    env:
+      CLICKHOUSE_HOST: localhost
+      CLICKHOUSE_PORT: "8123"
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          submodules: recursive
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: make lint
+      - run: make typecheck
+      - name: Start ClickHouse
+        run: docker compose up --detach --wait clickhouse
+      - run: make test
+      - name: Check Coverage
+        uses: 5monkeys/cobertura-action@v14
+        with:
+          minimum_coverage: 100
+          fail_below_threshold: true
+          show_missing: true

.gitignore

@@ -13,3 +13,11 @@ wheels/
 .pytest_cache/
 .mypy_cache/
 .ruff_cache/
+
+# Coverage
+.coverage
+coverage.xml
+htmlcov/
+
+# Local secrets
+.env

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "engine-test-data"]
+	path = engine-test-data
+	url = https://github.com/Flagsmith/engine-test-data.git
+	branch = v3.7.0

.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.6
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.10.10
+    hooks:
+      - id: uv-lock
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-yaml
+      - id: check-json
+      - id: check-toml
+  - repo: https://github.com/Flagsmith/flagsmith-common
+    rev: v3.8.2
+    hooks:
+      - id: flagsmith-lint-tests
+  - repo: local
+    hooks:
+      - id: python-typecheck
+        name: python-typecheck
+        language: system
+        entry: make typecheck
+        require_serial: true
+        pass_filenames: false
+        types: [python]

.python-version

@@ -0,0 +1 @@
+3.10

CODEOWNERS

@@ -0,0 +1 @@
+* @flagsmith/flagsmith-back-end

Makefile

@@ -0,0 +1,29 @@
+.PHONY: install-packages
+install-packages: ## Install all required packages
+	uv sync
+
+.PHONY: install-pre-commit
+install-pre-commit: ## Install pre-commit hooks
+	uv run prek install
+
+.PHONY: install
+install: install-packages install-pre-commit ## Ensure the environment is set up
+
+.PHONY: lint
+lint: ## Run linters (pre-commit hooks across the tree)
+	uv run prek run --all-files
+
+.PHONY: test
+test: ## Run unit tests. Override scope with opts, e.g. `make test opts='-m engine_parity'`
+	uv run pytest $(opts)
+
+.PHONY: typecheck
+typecheck: ## Run mypy
+	uv run mypy
+
+.PHONY: help
+help:
+	@echo "Usage: make [target]"
+	@echo ""
+	@echo "Available targets:"
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  \033[36m%-30s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)

docker-compose.yml

@@ -0,0 +1,19 @@
+services:
+  clickhouse:
+    image: clickhouse/clickhouse-server:25.5.6
+    environment:
+      # Skip the random-password bootstrap. The container is only ever
+      # reachable from the harness on the same compose network / host
+      # loopback, so the default `default` user with no password is fine.
+      CLICKHOUSE_SKIP_USER_SETUP: "1"
+    ports:
+      - "8123:8123"
+    ulimits:
+      nofile:
+        soft: 262144
+        hard: 262144
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://localhost:8123/ping"]
+      interval: 2s
+      timeout: 2s
+      retries: 15

engine-test-data

@@ -0,0 +1,75 @@
+[project]
+name = "flagsmith-sql-flag-engine"
+version = "0.1.0a2"
+description = "SQL translator for Flagsmith segment predicates."
+readme = "README.md"
+authors = [{ name = "Flagsmith", email = "engineering@flagsmith.com" }]
+requires-python = ">=3.10"
+license = "BSD-3-Clause"
+classifiers = [
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: SQL",
+    "Topic :: Database",
+]
+dependencies = ["flagsmith-flag-engine>=10", "jsonpath-rfc9535>=0.2"]
+
+[project.urls]
+Homepage = "https://github.com/Flagsmith/flagsmith-sql-flag-engine"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-xdist>=3",
+    "mypy>=1.10",
+    "prek>=0.3",
+    "clickhouse-connect>=0.7",
+    "json5>=0.14.0",
+    "pytest-cov>=7.1.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.14,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+addopts = [
+    "-ra",
+    "--cov",
+    "src",
+    "--cov-report",
+    "term-missing",
+    "--cov-report",
+    "xml",
+]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["src"]
+
+[tool.coverage.report]
+# `match` statements exhaustive over a Literal type record a phantom
+# fall-through branch from the last case to function exit; coverage.py
+# can't see the type-system exhaustiveness mypy enforces. Treat any
+# `case` line as a possibly-partial branch so the gate stays at 100%
+# without us littering the source with `# pragma: no branch`.
+partial_branches = [
+    "pragma: no branch",
+    "case .+:",
+]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+files = ["src/flagsmith_sql_flag_engine", "tests"]
+
+[[tool.mypy.overrides]]
+module = "clickhouse_connect.*"
+ignore_missing_imports = true