ontolith 1.0.0__tar.gz

ontolith-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,221 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Least privilege (security review finding, M4 Workstream 7): none of this
+# workflow's jobs write to the repo, comment on PRs, or otherwise need more
+# than read access — checkout, running tests/lint/benchmarks, and uploading
+# to codecov.io (no token; codecov-action doesn't need repo write access to
+# do that) all only need contents: read. security.yml already scopes itself
+# the same way, for the same reason.
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Code Quality
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Full history so the griffe-diff step below can resolve the PR's
+          # base ref (KI-020) — same reason commitlint's checkout does this.
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Format check
+        run: uv run ruff format --check
+
+      - name: Lint
+        run: uv run ruff check
+
+      - name: Type check
+        run: uv run mypy --strict src conformance/conftest.py
+
+      - name: Dependency rule check
+        run: uv run lint-imports
+
+      - name: Docstring coverage
+        run: uv run interrogate src/ontolith -c pyproject.toml
+
+      - name: Public API surface diff (KI-020)
+        if: matrix.python-version == '3.12'
+        # Blocking as of the 1.0 tag (Implementation Plan §5's "warn pre-1.0,
+        # block post-1.0"). This is NOT a required status check in the repo's
+        # branch ruleset (checked directly: only deletion, non_fast_forward,
+        # pull_request, code_quality, and code_scanning rules exist — no
+        # required_status_checks rule) — "blocking" here means a visible red
+        # CI failure a reviewer sees and must knowingly merge past, the same
+        # as any other job in this workflow, not a structural merge block.
+        #
+        # Griffe checks a module's `__all__` members if it has one, else its
+        # non-underscore/non-imported names — NOT "every non-underscore
+        # module-level function" (an earlier version of this comment claimed
+        # that; wrong, see below). A pure addition to `__all__` exits 0
+        # (confirmed). But it does NOT follow that only a genuine breaking
+        # change exits 1 — a still-earlier draft claimed that too, also
+        # wrong: griffe's breakage detector (`find_breaking_changes`) flags
+        # a public attribute's value TEXT changing even when semantically
+        # identical (confirmed: reordering `frozenset({"entity",
+        # "assertion"})` to `frozenset({"assertion", "entity"})` in
+        # store/base.py — same set, exit 1, "Attribute value was changed"),
+        # and a signature change on any name actually listed in its own
+        # module's `__all__` (or re-exported via another module's `__all__`
+        # — griffe follows the alias), even one this project's own ADR-0019
+        # doesn't consider part of the 13-package public surface (confirmed:
+        # adding a required parameter to plugins/sandbox/wire.py's
+        # restricted_loads, listed in that module's own `__all__` but not
+        # ADR-0019's — exit 1). A signature change on a name NOT listed in
+        # its own (or any re-exporting) module's `__all__` does NOT trip it
+        # (confirmed: same edit on cli.py's db_status, absent from cli.py's
+        # own `__all__ = ["app"]` and never re-exported — exit 0) — nothing
+        # catches this case, which is intended: `ontolith.interfaces.cli` is
+        # deliberately outside ADR-0019's SDK surface, and
+        # `test_public_api_surface.py`'s own docstring says plainly it does
+        # NOT catch signature-level changes at all, only export
+        # additions/removals/renames within the 13 packages it pins.
+        # Removing something from `__all__` alone, with the import kept,
+        # also doesn't trip this step (confirmed: exit 0) — for one of the
+        # 13 ADR-0019-pinned packages, `test_public_api_surface.py`'s own
+        # pinned `_EXPECTED` dict catches that instead; for `wire.py` or any
+        # other unpinned module, nothing catches it, same as the
+        # signature-change case above. Expect this gate to occasionally flag
+        # a cosmetic or internal-but-`__all__`-listed change as a false
+        # positive; that's a known, accepted cost of blocking it, not a bug
+        # in this workflow.
+        # Compares against the PR's base commit; on a push-to-main run (no
+        # PR context) compares against HEAD itself, i.e. a no-op — the
+        # meaningful comparison already happened during the PR's own run.
+        env:
+          BASE_REF: ${{ github.event.pull_request.base.sha || 'HEAD' }}
+        run: uv run python -m griffe check ontolith -s src -a "$BASE_REF" -f github
+
+  commitlint:
+    name: Commit message format
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Validate Conventional Commits format
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          pattern='^(feat|fix|docs|test|refactor|chore|perf|ci)(\([a-zA-Z0-9_-]+\))?: .+'
+          failed=0
+          while IFS= read -r line; do
+            sha="${line%% *}"
+            subject="${line#* }"
+            if [[ ! "$subject" =~ $pattern ]]; then
+              echo "::error::Commit $sha does not follow Conventional Commits: $subject"
+              failed=1
+            fi
+          done < <(git log --no-merges --format='%H %s' "$BASE_SHA..$HEAD_SHA")
+          exit $failed
+
+  test:
+    name: Tests
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install libseccomp (Linux only — ADR-0051 plugin sandbox enforcement)
+        if: matrix.os == 'ubuntu-latest'
+        run: sudo apt-get update && sudo apt-get install -y libseccomp2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run tests + conformance (combined coverage)
+        env:
+          HYPOTHESIS_PROFILE: ci
+        # Folded scalar (`>-`), not a `\`-continued literal block: this step
+        # runs on windows-latest too, whose default shell is PowerShell, which
+        # doesn't treat a trailing backslash as a line continuation and fails
+        # to parse the command (`Missing expression after unary operator
+        # '--'`). A folded scalar collapses to one line, valid in every shell.
+        run: >-
+          uv run pytest tests/ conformance/
+          --cov=src/ontolith --cov-report=xml --cov-report=term
+          --cov-fail-under=90
+
+      - name: Upload coverage
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+
+      - name: Run quickstart example
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        run: uv run python examples/quickstart.py
+
+  benchmarks:
+    # M4 Workstream 1 exit gate: the 5 SPEC §9 budget rows are enforced as
+    # hard per-test ceilings inside tests/benchmarks/ itself (see
+    # tests/benchmarks/conftest.py's assert_within_budget) — this job is
+    # blocking (no continue-on-error, runs on every PR, not just pushes to
+    # main) precisely because those assertions, not this job definition,
+    # are what fails a genuine regression.
+    name: Benchmarks (§9 budgets)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run benchmarks
+        run: uv run pytest tests/benchmarks/ --benchmark-only --benchmark-json=benchmark-results.json -q
+
+      - name: Upload benchmark results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results
+          path: benchmark-results.json
+          overwrite: true

ontolith-1.0.0/.github/workflows/security.yml

@@ -0,0 +1,86 @@
+name: Security
+
+on:
+  pull_request:
+    branches: [main]
+  schedule:
+    # Weekly, independent of PR activity — catches newly-disclosed CVEs in
+    # already-merged dependencies (Implementation Plan §7.1).
+    - cron: "0 6 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  # pip-audit, bandit, and SBOM generation share one checkout + `uv sync`
+  # instead of three, to cut per-PR Actions-minute usage on this repo's
+  # private-repo minute allotment (this workflow otherwise roughly doubles
+  # security.yml's total runner time for no benefit — none of the three
+  # steps depend on each other's output, they're just sharing setup cost).
+  scan:
+    name: Dependency + static security scan
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run pip-audit
+        run: uv run pip-audit
+
+      # `if: always()` below: these three steps are otherwise independent of
+      # pip-audit's outcome, but without it a pip-audit failure silently
+      # skips bandit/SBOM for the rest of the job (a real incident — a
+      # newly-disclosed transitive-dependency CVE masked two genuine bandit
+      # findings for a full PR before anyone noticed bandit hadn't actually
+      # run). The job still fails overall if any step fails; this only
+      # ensures every step gets a chance to report its own result.
+      - name: Run bandit
+        if: always()
+        run: uv run bandit -r src/ontolith -c pyproject.toml
+
+      - name: Generate SBOM
+        if: always()
+        run: uv run cyclonedx-py environment --pyproject pyproject.toml -o sbom.json
+
+      - name: Upload SBOM
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: sbom
+          path: sbom.json
+
+  gitleaks:
+    name: Secret scanning (gitleaks)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run gitleaks
+        uses: gitleaks/gitleaks-action@v3
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # This repo is private under a personal account (not an
+          # organization) — gitleaks-action's license requirement is gated
+          # on org vs. personal account, not public vs. private repo
+          # visibility, so no GITLEAKS_LICENSE is needed here. That would
+          # change if this repo ever moved under an organization.
+          #
+          # PR comments disabled so this job only needs the default
+          # read-only GITHUB_TOKEN (workflow permissions: contents: read,
+          # above) rather than pull-requests: write — findings still surface
+          # via the job's own log/summary output.
+          GITLEAKS_ENABLE_COMMENTS: false

ontolith-1.0.0/.gitignore

@@ -0,0 +1,51 @@
+# Claude Code configuration (maintainer-only)
+.claude/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.hypothesis/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.db
+*.sqlite
+*.sqlite3

ontolith-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.2.2
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.8.0
+    hooks:
+      - id: mypy
+        args: [--strict, --ignore-missing-imports]
+        additional_dependencies: [pydantic>=2.0, python-ulid>=2.0]
+        files: ^(src/|conformance/conftest\.py$)