calliope-studio 0.1.0__tar.gz

calliope_studio-0.1.0/.gitattributes

@@ -0,0 +1,21 @@
+# Line endings are LF in the repository and LF in the working tree, on every
+# platform. Without this, a Windows checkout with git's default `core.autocrlf`
+# hands CRLF to the YAML and CSV fixtures — and the round-trip tests assert that
+# a rewrite preserves comments and line count, while `save-check` asserts that a
+# no-op save changes nothing at all. Both would be measuring git's translation
+# rather than this project's, and the CSVs are read by pandas besides.
+#
+# `eol=lf` rather than bare `text=auto`, which normalises on commit but still
+# lets the working tree be CRLF.
+* text=auto eol=lf
+
+# Binary, so git neither translates nor tries to merge them.
+*.nc binary
+*.ico binary
+*.icns binary
+*.png binary
+*.woff binary
+*.woff2 binary
+*.ttf binary
+
+pixi.lock linguist-generated=true merge=binary

calliope_studio-0.1.0/.github/dependabot.yml

@@ -0,0 +1,63 @@
+version: 2
+
+# Nothing surfaced dependency advisories before this: there was no audit step,
+# no update automation, and nine open advisories in the frontend tree that the
+# pnpm migration was the first thing to notice.
+#
+# Grouped, because ungrouped updates across three ecosystems open a PR per
+# package and the review then never happens. Note that pixi.lock is *not*
+# covered by any of this — conda dependencies stay a manual job.
+updates:
+  # Dependabot reads pnpm-lock.yaml under the "npm" ecosystem.
+  - package-ecosystem: npm
+    directory: /web
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      minor-and-patch:
+        update-types: [minor, patch]
+      # Majors are grouped for the same reason the others are, learned the hard
+      # way: left ungrouped they arrive one PR per package, and five of them —
+      # typescript, maplibre-gl, echarts, apache-arrow, vitest — filled
+      # `open-pull-requests-limit` exactly, which then blocked the
+      # minor-and-patch PR from opening at all. The group carrying routine
+      # updates was starved by the group nobody merges in a hurry. (Security
+      # updates have their own separate limit and were never at risk.)
+      major:
+        update-types: [major]
+    ignore:
+      # Pinned deliberately: 0.53 changed how a worker hands its foreign module
+      # to the main thread, monaco-yaml still speaks the older protocol, and
+      # under 0.55 the YAML language worker answered nothing at all. Lifting
+      # the pin is a decision `pixi run -- pnpm --dir web run monaco-check`
+      # makes, not one a bot should.
+      - dependency-name: monaco-editor
+        update-types:
+          - "version-update:semver-minor"
+          - "version-update:semver-major"
+      # TypeScript 7 is the Go compiler, and vue-tsc cannot run on it: Volar
+      # embeds TypeScript's classic programmatic API, which 7.0 ships without a
+      # stable replacement for — that is 7.1's headline, expected around
+      # October 2026. `pixi run web-typecheck` *is* vue-tsc, so a bump here is
+      # not a config nit but a dead type check: it fails in vue-tsc's own
+      # entry point with ERR_PACKAGE_PATH_NOT_EXPORTED. Lift the pin when
+      # vue-tsc declares support, not when 7.x merely installs.
+      - dependency-name: typescript
+        update-types:
+          - "version-update:semver-major"
+
+  # This is what keeps the SHA-pinned actions in ci.yml current. Without it,
+  # pinning by SHA means pinning to whatever was true the day it was written.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]
+
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: monthly

calliope_studio-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,437 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Nothing in this workflow writes back to the repository, so the default
+# token scope is more than any job needs. Dependabot keeps the SHA pins below
+# current; pinning by tag would let a retagged action ship new code silently.
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  python:
+    name: Python
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # setuptools-scm derives the version from tags.
+          fetch-depth: 0
+      - uses: prefix-dev/setup-pixi@f00437f565399d418b0acc85936d12c1fb668347 # v0.10.1
+        with:
+          cache: true
+      - name: Lint
+        run: pixi run lint
+      - name: Check formatting
+        run: pixi run format-check
+      # The sample .nc files are gitignored, and the numerical comparison
+      # against v0.2.0 skips without them — which meant the only evidence the
+      # results layer is correct never ran here. Solving Calliope's own two
+      # templates takes a minute and removes the skip.
+      - name: Solve the example models
+        run: pixi run solve-examples
+      - name: Test
+        run: pixi run test-cov
+
+      # `fail_ci_if_error` stays false, which is the action's own default and
+      # deliberate here: `secrets.CODECOV_TOKEN` is not readable by a
+      # Dependabot-triggered run unless the same value is also stored under the
+      # repository's *Dependabot* secrets, so a strict upload would turn every
+      # dependency PR red over something that is not a test failure. A Codecov
+      # outage should not gate a merge either.
+      - name: Upload coverage
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        with:
+          files: coverage.xml
+          flags: python
+          # The report names exactly one file, so searching the tree for others
+          # can only find something unintended.
+          disable_search: true
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
+
+  web:
+    name: Frontend
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      # Node and pnpm both come from pixi, so their versions are pinned in
+      # pixi.lock alongside everything else rather than drifting against it.
+      # Every step below is a pixi task, which is why there is no
+      # `working-directory` here: the tasks carry their own `cwd = "web"`.
+      - uses: prefix-dev/setup-pixi@f00437f565399d418b0acc85936d12c1fb668347 # v0.10.1
+        with:
+          cache: true
+      - name: Install
+        run: pixi run web-install
+      - name: Lint
+        run: pixi run web-lint
+      - name: Type check
+        run: pixi run web-typecheck
+      - name: Audit
+        run: pixi run web-audit
+      - name: Test
+        run: pixi run -- pnpm --dir web run test:coverage
+
+      # vitest writes lcov paths relative to `web/`, so the report says
+      # `src/App.vue` where the repository says `web/src/App.vue`. Codecov
+      # resolves that by matching the report path against its file network, and
+      # `network_filter` is what makes the match unambiguous: without it the
+      # network also holds the Python `src/`, and the two trees are one bad
+      # guess apart. See the `python` job above for `fail_ci_if_error`.
+      - name: Upload coverage
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        with:
+          files: web/coverage/lcov.info
+          flags: web
+          network_filter: web/
+          disable_search: true
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
+
+      - name: Build
+        run: pixi run web-build
+
+  windows:
+    name: Windows
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: prefix-dev/setup-pixi@f00437f565399d418b0acc85936d12c1fb668347 # v0.10.1
+        with:
+          cache: true
+
+      # Windows is where this project's platform-specific code lives, and until
+      # this job existed none of it had run: the job-object process group, the
+      # native stdio capture, the `os.replace` retry, and every relative path
+      # that reaches the API or `snapshot.json`. Real solves included — pixi
+      # brings coin-or-cbc here as it does everywhere else.
+      #
+      # The exclusions below are a *deny* list on purpose. A new test file runs
+      # here by default and has to be excluded deliberately, because a forgotten
+      # exclusion costs a little CPU while a forgotten inclusion costs coverage
+      # on the platform least likely to be tried by hand. Each name below has no
+      # platform surface at all — YAML and math semantics, source scanning, log
+      # parsing, and numerics against the frozen v0.2.0 implementation. They are
+      # fully covered by the Linux job.
+      #
+      # Skipping `test_oracle.py` is also what lets this job skip
+      # `solve-examples`: it is the only selection that needs the sample `.nc`
+      # files. Reading them is pure xarray, and `test_results.py` still solves a
+      # model here and reads the result back.
+      - name: Test
+        run: >
+          pixi run test
+          --ignore=tests/test_entities.py
+          --ignore=tests/test_layering.py
+          --ignore=tests/test_math_render.py
+          --ignore=tests/test_mathcache.py
+          --ignore=tests/test_mathdef.py
+          --ignore=tests/test_modeldef_geo.py
+          --ignore=tests/test_oracle.py
+          --ignore=tests/test_overrides.py
+          --ignore=tests/test_resolution_parity.py
+          --ignore=tests/test_results_api.py
+          --ignore=tests/test_run_stages.py
+
+  browser:
+    name: Browser
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: prefix-dev/setup-pixi@f00437f565399d418b0acc85936d12c1fb668347 # v0.10.1
+        with:
+          cache: true
+
+      - name: Install the frontend and build it into the package
+        run: pixi run web-build
+
+      - name: Install Chromium
+        # The scripts use playwright-core, which ships no browsers. Matching the
+        # installer's version to playwright-core's is what makes
+        # `chromium.executablePath()` resolve to the one it just downloaded.
+        run: |
+          version=$(pixi run -- pnpm --dir web exec node -p "require('playwright-core/package.json').version")
+          pixi run -- pnpm --dir web dlx playwright@$version install --with-deps chromium
+          echo "CHROMIUM=$(pixi run -- pnpm --dir web exec node -e "console.log(require('playwright-core').chromium.executablePath())")" >> "$GITHUB_ENV"
+
+      - name: Scaffold a model to drive
+        run: pixi run example
+
+      # `http-get://`, not `http://`. wait-on's `http://` scheme issues a
+      # **HEAD**, and `/api/health` answers GET only: Starlette's `Route` adds
+      # HEAD wherever GET is present, and FastAPI's `APIRoute` does not. So the
+      # endpoint returned 405 to every probe and wait-on burned its full 120s,
+      # which is why this step had never passed in any recorded run.
+      #
+      # The server was never at fault, which took capturing its output to
+      # establish — it had been discarded. That capture stays: a `wait-on`
+      # timeout with no other evidence is exactly what cost three runs.
+      - name: Start the server on it
+        run: |
+          pixi run calliope-studio --no-browser --port 8791 example-model \
+            > server.log 2>&1 &
+          echo $! > server.pid
+          if ! pixi run -- pnpm dlx wait-on -t 120000 http-get://127.0.0.1:8791/api/health
+          then
+            echo "::group::server.log"
+            cat server.log || echo "(no server.log)"
+            echo "::endgroup::"
+            echo "::group::is the process alive?"
+            ps -p "$(cat server.pid)" -o pid,stat,etime,cmd || echo "(gone)"
+            echo "::endgroup::"
+            echo "::group::is anything listening on 8791?"
+            ss -ltnp 2>/dev/null | grep 8791 || echo "(nothing listening)"
+            echo "::endgroup::"
+            echo "::group::what does the endpoint say?"
+            curl -sv -m 10 http://127.0.0.1:8791/api/health 2>&1 | tail -30 \
+              || echo "(curl failed)"
+            echo "::endgroup::"
+            exit 1
+          fi
+
+      # The design tokens, and every renderer that reads them outside the DOM.
+      # Every check below records a marker instead of aborting the job, and the
+      # gate at the end fails if any exist. These are the only coverage of a
+      # dozen behaviours that nothing else tests, and finding them one push at a
+      # time — three minutes each — is not a reasonable way to learn what is
+      # already broken.
+      #
+      # The step re-raises after recording, so it shows as failed rather than
+      # green; `continue-on-error` is what carries the job on to the remaining
+      # checks; and the marker is what the gate reads at the end. All three, and
+      # the first is easy to lose: a bare `cmd || touch marker` exits 0, so the
+      # step reports success and only the gate knows anything went wrong.
+      #
+      # They share one server and one model, and some mutate it: a check that
+      # dies before its own cleanup can make later ones fail for reasons of its
+      # making. Read the first failure as the real one.
+      - name: Collect check failures
+        run: mkdir -p .check-failed
+
+      - name: Token check
+        continue-on-error: true
+        run: pixi run -- pnpm --dir web run token-check http://127.0.0.1:8791 || { touch .check-failed/token-check; exit 1; }
+
+      # The YAML language worker, which answered nothing at all until the
+      # monaco-editor pin. This is what notices if the pin is lifted.
+      - name: Monaco check
+        continue-on-error: true
+        run: pixi run -- pnpm --dir web run monaco-check http://127.0.0.1:8791 || { touch .check-failed/monaco-check; exit 1; }
+
+      # A no-op save must not change the file, across every structured section.
+      - name: Faithful-save check
+        continue-on-error: true
+        run: pixi run -- pnpm --dir web run save-check http://127.0.0.1:8791 || { touch .check-failed/save-check; exit 1; }
+
+      # The guard between a user and their unsaved edits. A no-op guard fails
+      # silently — no error, no console output, just the edits gone — so the
+      # only way to know it still works is to dirty a tab and try to leave.
+      - name: Unsaved-changes guard
+        continue-on-error: true
+        run: pixi run -- pnpm --dir web run confirm-check http://127.0.0.1:8791 || { touch .check-failed/confirm-check; exit 1; }
+
+      # The explorer filters. A search borrows Reka's expansion model and has to
+      # give it back exactly as it was, which nothing but a rendered tree shows:
+      # with the two sets confused, collapsing a branch mid-search silently does
+      # nothing and clearing the field loses the expansion the user built.
+      - name: Tree search
+        continue-on-error: true
+        run: pixi run -- pnpm --dir web run tree-search http://127.0.0.1:8791 || { touch .check-failed/tree-search; exit 1; }
+
+      # Every popup lands where a person can see it. A popper with no anchor
+      # stays at Reka's off-screen default while the DOM looks entirely healthy,
+      # so presence is not the property — position is.
+      - name: Popup placement
+        continue-on-error: true
+        run: pixi run -- pnpm --dir web run menu-check http://127.0.0.1:8791 || { touch .check-failed/menu-check; exit 1; }
+
+      # The map as an input: it has a size at all, a node drags, a link draws.
+      - name: Map editing
+        continue-on-error: true
+        run: pixi run -- pnpm --dir web run map-edit http://127.0.0.1:8791 || { touch .check-failed/map-edit; exit 1; }
+
+      # Where an inherited value comes from, and that clicking it goes there. A
+      # source that fails to resolve renders as plain text, which is
+      # indistinguishable from a deliberate design, and a link to the wrong file
+      # opens a file and says nothing — neither is visible without a browser.
+      - name: Source links
+        continue-on-error: true
+        run: pixi run -- pnpm --dir web run source-link http://127.0.0.1:8791 || { touch .check-failed/source-link; exit 1; }
+
+      # The picker's entries are not clipped, and a model can be created.
+      - name: Model picker
+        continue-on-error: true
+        run: pixi run -- pnpm --dir web run model-picker http://127.0.0.1:8791 || { touch .check-failed/model-picker; exit 1; }
+
+      # Custom math, end to end: a file is declared, enabled, rendered and read.
+      # Both halves are invisible without a browser — KaTeX turns an equation it
+      # cannot parse into markup rather than an exception, so a formulation with
+      # one missing looks exactly like one without it; and a math file declared
+      # but never enabled is read by nobody with Calliope saying nothing at all.
+      - name: Custom math
+        continue-on-error: true
+        run: pixi run -- pnpm --dir web run math-check http://127.0.0.1:8791 || { touch .check-failed/math-check; exit 1; }
+
+      # Creating a file and a folder, and what a file that is not text shows.
+      # A binary used to open in Monaco as a screenful of replacement
+      # characters, which Ctrl/Cmd+S then wrote back over the original bytes —
+      # so the save keystroke is asserted here, not only the message.
+      - name: File actions and viewers
+        continue-on-error: true
+        run: pixi run -- pnpm --dir web run file-actions http://127.0.0.1:8791 || { touch .check-failed/file-actions; exit 1; }
+
+      # Reordering tabs by dragging them. The order is applied mid-drag, so the
+      # element under the pointer is re-parented while it is being held — which
+      # cancels the drag outright if Vue rebuilds the row rather than moving it.
+      # And the drag must offer a payload no one else takes: as `text/plain` a
+      # tab released over the editor pastes its own id into the user's file,
+      # which this check does end to end because it really happened.
+      - name: Tab reordering
+        continue-on-error: true
+        run: pixi run -- pnpm --dir web run tab-drag http://127.0.0.1:8791 || { touch .check-failed/tab-drag; exit 1; }
+
+      # Really solves, with CBC, and drives the run tab from log to charts.
+      - name: Run lifecycle
+        continue-on-error: true
+        run: pixi run -- pnpm --dir web run run-lifecycle http://127.0.0.1:8791 || { touch .check-failed/run-lifecycle; exit 1; }
+
+      # The README's pictures, taken but not published — publishing happens on a
+      # tag, in its own workflow, and a selector that has moved should be found
+      # here rather than in the middle of cutting a release. Nearly free: it
+      # reuses the run `run-lifecycle` has just left in the model, so it solves
+      # nothing.
+      - name: README screenshots
+        continue-on-error: true
+        run: |
+          pixi run -- pnpm --dir web run screenshots http://127.0.0.1:8791 results /tmp/shots \
+            && pixi run -- pnpm --dir web run screenshots http://127.0.0.1:8791 editor /tmp/shots \
+            || { touch .check-failed/screenshots; exit 1; }
+
+      # Not on what `run-lifecycle` just produced: smoke-charts asserts that
+      # with nothing summed *no* technology colour is painted, and whether that
+      # holds is a property of the model. `choose_index` puts techs on the index
+      # for urban_scale and nodes on it for national_scale, so that assertion
+      # legitimately fails against a national_scale run on working code.
+      - name: Results view, on the urban_scale example
+        continue-on-error: true
+        run: |
+          pixi run solve-examples urban_scale
+          pixi run calliope-studio --no-browser --port 8792 examples/nc_files/urban_scale.nc &
+          pixi run -- pnpm dlx wait-on -t 120000 http-get://127.0.0.1:8792/api/health
+          pixi run -- pnpm --dir web run smoke http://127.0.0.1:8792 || { touch .check-failed/smoke; exit 1; }
+
+      - name: Fail if any browser check failed
+        run: |
+          if [ -n "$(ls -A .check-failed 2>/dev/null)" ]; then
+            echo "::error::browser checks failed: $(ls .check-failed | tr '\n' ' ')"
+            exit 1
+          fi
+          echo "every browser check passed"
+
+      - name: Keep the screenshots when something fails
+        if: failure()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: browser-screenshots
+          path: /tmp/calliope-studio-*.png
+          if-no-files-found: ignore
+
+      # The README's, always — the only way to see what a change did to them
+      # without cutting a release to find out.
+      - name: Keep the README screenshots
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: readme-screenshots
+          path: /tmp/shots/*.png
+          if-no-files-found: ignore
+
+  package:
+    name: Package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: prefix-dev/setup-pixi@f00437f565399d418b0acc85936d12c1fb668347 # v0.10.1
+        with:
+          cache: true
+      - name: Build wheel and check the interface is bundled
+        # `python -m build` alone succeeds without the frontend and produces a
+        # wheel with no interface, so the check is the point of this job.
+        run: pixi run -e build build
+
+      # Handed to `interpreters` below rather than rebuilt there: that job is
+      # about the *artefact* installing, and a wheel built per interpreter would
+      # not be the one we ship.
+      - name: Keep the artefacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          retention-days: 1
+
+  # `pixi run test` covers one interpreter — whichever `pixi.lock` pins — so
+  # nothing here used to exercise the rest of the declared `requires-python`
+  # range. This installs the built wheel from PyPI-resolved dependencies on each
+  # supported version, which is what a user actually does, and is the only place
+  # a version-specific resolution failure or C-extension mismatch would show up.
+  #
+  # Deliberately not pixi: conda-forge resolves a different dependency set, so a
+  # pixi environment per interpreter would test the one path this job is not
+  # about.
+  interpreters:
+    name: Python ${{ matrix.python-version }}
+    needs: package
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Must stay equal to `requires-python` in `pyproject.toml`. 3.14 is
+        # absent because pandas ships no cp314 wheel before 2.3.3 and Calliope
+        # 0.7.0.dev7 caps pandas below that; see the comment there.
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install the wheel
+        # No `--pre`, on purpose: Calliope 0.7 is a pre-release, and this asserts
+        # that the `>=0.7.0.dev7` lower bound is enough to resolve it the way the
+        # README's install line promises.
+        run: pip install dist/*.whl
+
+      - name: Import the stack
+        # An import is what catches a version-specific break — a C extension
+        # built for the wrong ABI, or a dependency that resolved but cannot load.
+        # `server.app` is included because importing it builds the FastAPI app.
+        run: |
+          python - <<'EOF'
+          import calliope, calliope_studio, netCDF4, numpy, pandas, pyarrow, xarray
+          from calliope_studio.server.app import app
+          print("studio  ", calliope_studio.__version__)
+          print("calliope", calliope.__version__)
+          print("pandas  ", pandas.__version__)
+          print("xarray  ", xarray.__version__)
+          print("routes  ", len(app.routes))
+          EOF
+
+      - name: Run the console script
+        run: calliope-studio --help