terp-spec 0.15.0__tar.gz

terp_spec-0.15.0/.github/workflows/ci.yml

@@ -0,0 +1,90 @@
+name: ci
+
+# The Terp Standard's own CI (ADR 0082): the spec is plain data + a tiny
+# accessor with zero dependencies, and the `standard` job proves it
+# self-consistent — versioning agreement, schema validity of every catalog
+# entry, the finding format, the refused surface's shape, and the corpus
+# ratchet. The `certify-against-reference` job closes the adoption gap the
+# package seam leaves (framework CI reads the *pinned* release, so a change
+# here would otherwise be exercised by no live implementation until the pins
+# bump): it substitutes this checkout for the pinned terp-spec/@terpjs/spec and
+# runs the framework's parity + corpus certification against it, so a catalog
+# or corpus change is proven against the reference implementation BEFORE it
+# can be released.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  standard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: pip install pytest
+      - name: Test (the spec is self-consistent)
+        run: python -m pytest
+
+  certify-against-reference:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: spec
+      # The reference implementation. Tracks its default branch deliberately:
+      # a spec change must certify against what the framework IS, and a
+      # framework change that breaks parity should surface here, not at
+      # release time. (A private framework checkout would need a repo-scoped
+      # token on this step.)
+      - uses: actions/checkout@v4
+        with:
+          repository: AITT-NL/terp-framework
+          path: framework
+      - name: Record the certified reference commit
+        run: |
+          sha="$(git -C framework rev-parse HEAD)"
+          echo "Certifying against terp-framework@${sha}" | tee -a "$GITHUB_STEP_SUMMARY"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.13
+      - name: Python certification (catalog parity + backend corpus)
+        working-directory: framework
+        run: |
+          uv sync
+          # Substitute this checkout for the pinned terp-spec release — the
+          # same seam the framework's pin bump will move, exercised early.
+          uv pip install -e ../spec
+          uv run --no-sync pytest tests/architecture/test_spec_catalog.py tests/architecture/test_spec_corpus.py -q
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - name: Frontend certification (ESLint adapter corpus + surface + findings)
+        working-directory: framework
+        run: |
+          npm ci
+          # Substitute the candidate spec under BOTH scope paths: the rename to
+          # @terpjs/spec (ADR 0086) lands here first, so the reference framework
+          # may still resolve the legacy @terp/spec until its repin lands. Drop
+          # the legacy leg once no consumer resolves it.
+          for scope in @terp @terpjs; do
+            rm -rf "node_modules/$scope/spec"
+            mkdir -p "node_modules/$scope"
+            ln -s "$GITHUB_WORKSPACE/spec" "node_modules/$scope/spec"
+          done
+          npx vitest run packages/frontend/eslint-boundaries

terp_spec-0.15.0/.github/workflows/release.yml

@@ -0,0 +1,237 @@
+name: release
+
+# The Terp Standard's release seam (ADR 0082, published per ADR 0086): a tag
+# turns into two registry releases (`terp-spec` on PyPI, `@terpjs/spec` on npm)
+# plus a GitHub Release. This workflow makes tagging fail-closed instead of a
+# raw `git push origin v*`:
+# the tag must match the checked-in VERSION (and the package manifests, which
+# the test suite holds to VERSION), the tagged commit must be REACHABLE FROM
+# THE DEFAULT BRANCH (provenance: no releasing an unreviewed side branch or a
+# rewritten commit), the self-consistency suite must pass at the tagged
+# commit, the spec must certify against the reference implementation, and both
+# the publish jobs and the release job are BOUND to the verified commit (a tag
+# moved or deleted mid-workflow is refused, never released). A GitHub Release
+# then documents it with generated notes.
+#
+# Publishing uses Trusted Publishing (OIDC) on both registries — no long-lived
+# token is stored here.
+#
+# tests/test_release_workflow.py holds this file to that contract.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+# One run per tag ref: a retrigger or a racing duplicate never interleaves
+# with an in-flight verification/release of the same tag.
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    outputs:
+      # The commit the checks below actually verified — the release job binds
+      # to THIS sha, so a tag force-moved mid-workflow cannot smuggle an
+      # unverified commit into the release.
+      verified_sha: ${{ steps.provenance.outputs.sha }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Full history: the ancestry check below proves the tagged commit
+          # is reachable from the default branch — a shallow clone cannot.
+          fetch-depth: 0
+      - name: Tag matches the checked-in VERSION
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          checked_in="$(tr -d '[:space:]' < VERSION)"
+          [ "$version" = "$checked_in" ] \
+            || { echo "tag $GITHUB_REF_NAME != VERSION ($checked_in)"; exit 1; }
+      - name: Tagged commit is reachable from the default branch
+        id: provenance
+        env:
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          # Fail closed at every step: no resolvable default branch, no
+          # dereferenceable tag, or no ancestry = no release.
+          [ -n "$DEFAULT_BRANCH" ] \
+            || { echo "could not resolve the repository default branch"; exit 1; }
+          git fetch --no-tags origin \
+            "refs/heads/${DEFAULT_BRANCH}:refs/remotes/origin/${DEFAULT_BRANCH}"
+          tagged="$(git rev-parse "refs/tags/${GITHUB_REF_NAME}^{commit}")" \
+            || { echo "cannot dereference tag $GITHUB_REF_NAME to a commit"; exit 1; }
+          git merge-base --is-ancestor "$tagged" "refs/remotes/origin/${DEFAULT_BRANCH}" \
+            || { echo "tag $GITHUB_REF_NAME ($tagged) is not reachable from" \
+                      "'${DEFAULT_BRANCH}' — release tags must point at reviewed," \
+                      "merged history"; exit 1; }
+          echo "sha=$tagged" >> "$GITHUB_OUTPUT"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: The spec is self-consistent at the tagged commit
+        run: |
+          pip install pytest
+          python -m pytest
+
+  # A spec release must be certified against the live reference implementation
+  # (the same substitution ci.yml runs on every push): a tag can never publish a
+  # catalog or corpus no conformant checker exists for. Fail closed — the
+  # GitHub Release requires this job.
+  certify-against-reference:
+    needs: verify
+    runs-on: ubuntu-latest
+    outputs:
+      # The reference commit this release was certified against — recorded in
+      # the GitHub Release so the certification claim is reproducible: check
+      # out exactly this framework commit, substitute the tagged spec, re-run.
+      reference_sha: ${{ steps.reference.outputs.sha }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: spec
+      - uses: actions/checkout@v4
+        with:
+          repository: AITT-NL/terp-framework
+          path: framework
+      - name: Record the certified reference commit
+        id: reference
+        run: |
+          sha="$(git -C framework rev-parse HEAD)"
+          echo "sha=$sha" >> "$GITHUB_OUTPUT"
+          echo "Certifying against terp-framework@${sha}" | tee -a "$GITHUB_STEP_SUMMARY"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.13
+      - name: Python certification (catalog parity + backend corpus)
+        working-directory: framework
+        run: |
+          uv sync
+          uv pip install -e ../spec
+          uv run --no-sync pytest tests/architecture/test_spec_catalog.py tests/architecture/test_spec_corpus.py -q
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - name: Frontend certification (ESLint adapter corpus + surface + findings)
+        working-directory: framework
+        run: |
+          npm ci
+          # Substitute the candidate spec under BOTH scope paths: the rename to
+          # @terpjs/spec (ADR 0086) lands here first, so the reference framework
+          # may still resolve the legacy @terp/spec until its repin lands. Drop
+          # the legacy leg once no consumer resolves it.
+          for scope in @terp @terpjs; do
+            rm -rf "node_modules/$scope/spec"
+            mkdir -p "node_modules/$scope"
+            ln -s "$GITHUB_WORKSPACE/spec" "node_modules/$scope/spec"
+          done
+          npx vitest run packages/frontend/eslint-boundaries
+
+  # ADR 0086: the standard is published, not only tagged. Both publish jobs
+  # require certification (a version no conformant checker exists for can never
+  # reach a registry) and check out the VERIFIED COMMIT rather than the tag —
+  # a tag force-moved mid-workflow cannot change what gets published. Both are
+  # idempotent so a partially failed release is re-runnable.
+  publish-pypi:
+    needs: [verify, certify-against-reference]
+    runs-on: ubuntu-latest
+    # Part of the OIDC identity both registries verify: the trusted-publisher
+    # configurations name repository + workflow file + this environment, so a
+    # publish attempt from anywhere else is refused by the registry itself.
+    environment: release
+    permissions:
+      contents: read
+      id-token: write # PyPI Trusted Publishing (OIDC) — no API token stored
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.verify.outputs.verified_sha }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build the sdist + wheel
+        run: |
+          pip install build
+          python -m build
+      - name: Publish to PyPI (trusted publishing)
+        # Pinned by digest: this action holds a publishing credential.
+        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # release/v1
+        with:
+          skip-existing: true
+
+  publish-npm:
+    needs: [verify, certify-against-reference]
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: read
+      id-token: write # npm Trusted Publishing (OIDC) + provenance
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.verify.outputs.verified_sha }}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: https://registry.npmjs.org
+      # Trusted Publishing (OIDC) needs npm >= 11.5.1; Node 22 ships an older
+      # npm. Upgrading lets `npm publish` exchange the id-token for a
+      # short-lived registry credential — no stored registry secret.
+      - run: npm install -g npm@latest
+      - name: Publish @terpjs/spec (public, via Trusted Publishing)
+        run: |
+          set -eu
+          # Data only: no dependencies, no build step — nothing to install
+          # before publishing.
+          version="${GITHUB_REF_NAME#v}"
+          if [ "$(npm view "@terpjs/spec@$version" version 2>/dev/null || true)" = "$version" ]; then
+            echo "@terpjs/spec@$version already on the registry — skipping"
+            exit 0
+          fi
+          npm publish --access public --provenance
+
+  github-release:
+    # The Release announces a published standard: it requires both registries
+    # (fail closed) so a Release can never point at a version consumers cannot
+    # install. Publishing binds to the verified COMMIT; the Release additionally
+    # re-verifies the tag IDENTITY below.
+    needs: [verify, certify-against-reference, publish-pypi, publish-npm]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: The tag still points at the verified commit
+        env:
+          VERIFIED_SHA: ${{ needs.verify.outputs.verified_sha }}
+        run: |
+          # Re-resolve the tag from the REMOTE at release time: a tag that
+          # was deleted or force-moved between verification and release is
+          # refused instead of released.
+          [ -n "$VERIFIED_SHA" ] \
+            || { echo "no verified sha handed over from the verify job"; exit 1; }
+          git fetch --no-tags origin "refs/tags/${GITHUB_REF_NAME}" \
+            || { echo "tag $GITHUB_REF_NAME no longer exists on origin"; exit 1; }
+          current="$(git rev-parse 'FETCH_HEAD^{commit}')"
+          [ "$current" = "$VERIFIED_SHA" ] \
+            || { echo "tag $GITHUB_REF_NAME moved after verification" \
+                      "($current != verified $VERIFIED_SHA) — refusing to release"; exit 1; }
+      - name: Create the GitHub Release (generated notes)
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REFERENCE_SHA: ${{ needs.certify-against-reference.outputs.reference_sha }}
+        run: |
+          # --verify-tag: never create the tag as a side effect — release
+          # only an existing remote tag (the one just re-verified above).
+          # The certified reference commit makes the claim reproducible.
+          gh release create "$GITHUB_REF_NAME" \
+            --verify-tag \
+            --title "Terp Standard $GITHUB_REF_NAME" \
+            --generate-notes \
+            --notes "Certified against the reference implementation at [AITT-NL/terp-framework@${REFERENCE_SHA}](https://github.com/AITT-NL/terp-framework/commit/${REFERENCE_SHA})."

terp_spec-0.15.0/.gitignore

@@ -0,0 +1,221 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$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
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.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
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.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/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Data-only spec package: no runtime deps, the lock is test-env noise.
+uv.lock