xtalate 0.1.0.dev0__tar.gz → 0.3.0__tar.gz

xtalate-0.3.0/.github/ISSUE_TEMPLATE/bug_incorrect_conversion.yml

@@ -0,0 +1,50 @@
+name: "Bug: incorrect conversion"
+description: A conversion kept, dropped, transformed, or fabricated something wrong.
+labels: ["bug", "conversion"]
+body:
+  - type: markdown
+    attributes:
+      value: >-
+        The Conversion Report and Validation Report are **designed to be the bug report**
+        (`docs/MASTER_SPEC.md` Part 4 §2, Part 5 §3). Paste them below — they tell us far more
+        than a prose description can.
+  - type: textarea
+    id: source
+    attributes:
+      label: Source file (or minimal reproducer)
+      description: >-
+        Paste the smallest file that reproduces the problem, or attach it. If it can be
+        donated to the golden corpus, say so and its license (see the license field below).
+      render: text
+    validations:
+      required: true
+  - type: input
+    id: target
+    attributes:
+      label: Target format
+      placeholder: "e.g. poscar"
+    validations:
+      required: true
+  - type: textarea
+    id: reports
+    attributes:
+      label: Conversion Report + Validation Report (JSON)
+      description: "Output of `xtalate convert ... --json` (and `xtalate validate ... --json` if relevant)."
+      render: json
+    validations:
+      required: true
+  - type: textarea
+    id: expected_vs_observed
+    attributes:
+      label: Expected vs observed
+      description: What should the report/output have said or done, and what did it actually do?
+    validations:
+      required: true
+  - type: input
+    id: versions
+    attributes:
+      label: Xtalate + schema versions
+      description: "`xtalate --version`, and the `schema_version` from the report."
+      placeholder: "xtalate 0.2.0, schema 0.1.0"
+    validations:
+      required: true

xtalate-0.3.0/.github/ISSUE_TEMPLATE/bug_parse_failure.yml

@@ -0,0 +1,54 @@
+name: "Bug: parse failure"
+description: A file failed to parse, or parsed with a wrong or missing ParseIssue.
+labels: ["bug", "parser"]
+body:
+  - type: textarea
+    id: file
+    attributes:
+      label: File (or minimal reproducer)
+      description: Paste or attach the file that fails to parse.
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: error
+    attributes:
+      label: Full error envelope / ParseIssue list
+      description: >-
+        The complete error output (`docs/MASTER_SPEC.md` Part 3 §5, Part 6 §6) — codes,
+        messages, line numbers. Run with `--json` if using the CLI.
+      render: text
+    validations:
+      required: true
+  - type: input
+    id: producer
+    attributes:
+      label: What produced the file?
+      placeholder: "e.g. VASP 6.4, ASE 3.23, hand-written"
+    validations:
+      required: true
+  - type: dropdown
+    id: donate
+    attributes:
+      label: Can this file be donated to the golden corpus?
+      description: >-
+        If yes, we may add it as a regression fixture. This requires an explicit data
+        license (see below) — a file without one cannot be admitted.
+      options:
+        - "No"
+        - "Yes — I hold the rights and grant Apache-2.0 / a compatible license"
+        - "Yes — it is published open data (I'll give the license + attribution)"
+    validations:
+      required: true
+  - type: input
+    id: license
+    attributes:
+      label: License status of the file (if donating)
+      placeholder: "e.g. CC-BY-4.0 (Materials Project), CC0, my own work"
+  - type: input
+    id: versions
+    attributes:
+      label: Xtalate + schema versions
+      placeholder: "xtalate 0.2.0, schema 0.1.0"
+    validations:
+      required: true

xtalate-0.3.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or discussion
+    url: https://github.com/jsong1218/Xtalate/discussions
+    about: For questions and open-ended discussion, use Discussions rather than an issue.

xtalate-0.3.0/.github/ISSUE_TEMPLATE/format_request.yml

@@ -0,0 +1,48 @@
+name: "Format request"
+description: Request support for a new file format.
+labels: ["enhancement", "format-request"]
+body:
+  - type: markdown
+    attributes:
+      value: >-
+        A well-scoped format request — especially with example files and a draft capability
+        row — is a genuinely valuable contribution even if you never write a line of code.
+  - type: input
+    id: name
+    attributes:
+      label: Format name / spec link
+      placeholder: "e.g. CIF — https://www.iucr.org/resources/cif/spec"
+    validations:
+      required: true
+  - type: textarea
+    id: capability_draft
+    attributes:
+      label: Which canonical fields can it express? (a draft capability row!)
+      description: >-
+        Which of the canonical categories (Geometry, Cell, Trajectory, Dynamics, Electronic,
+        Metadata) can this format hold, and which can it not? Honest PARTIAL beats optimistic
+        FULL — this becomes the format's Capability Matrix row (`docs/MASTER_SPEC.md` Part 3 §3).
+    validations:
+      required: true
+  - type: textarea
+    id: examples
+    attributes:
+      label: Example files + license status
+      description: >-
+        Links or attachments, each with its data license. Licensed examples can seed the
+        golden corpus; unlicensed ones cannot be admitted.
+    validations:
+      required: true
+  - type: dropdown
+    id: contribute
+    attributes:
+      label: Would you be willing to contribute a plugin?
+      description: >-
+        Heads up: the plugin SDK is not frozen until v1.0 (risk R12), so a plugin may need to
+        follow SDK changes between minor versions until then.
+      options:
+        - "No — requesting only"
+        - "Maybe, with guidance"
+        - "Yes"
+    validations:
+      required: true

xtalate-0.3.0/.github/ISSUE_TEMPLATE/general.yml

@@ -0,0 +1,16 @@
+name: "General bug / docs issue"
+description: Anything that doesn't fit the other templates.
+labels: ["triage"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What's the issue? For a docs issue, link the doc/section.
+    validations:
+      required: true
+  - type: input
+    id: versions
+    attributes:
+      label: Xtalate + schema versions (if applicable)
+      placeholder: "xtalate 0.2.0, schema 0.1.0"

xtalate-0.3.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,32 @@
+<!-- Thanks for contributing to Xtalate. Keep PRs small and single-purpose. -->
+
+## What & why
+
+<!-- What does this change do, and why? For any nontrivial design decision, name at least
+     one reasonable rejected alternative — the standard the whole doc set holds itself to. -->
+
+## Rejected alternative (for design changes)
+
+<!-- e.g. "Considered threading choices into build_preflight; rejected because it breaks the
+     draft's purity (D46)." Delete this section only for pure docs/typo PRs. -->
+
+## Checklist
+
+- [ ] **Docs updated or confirmed unaffected.** The docs are the constitution; a behavior
+      change and its doc change are one PR (`docs/MASTER_SPEC.md` Part 10 §4.6).
+- [ ] **Golden cases added** for new behavior, each with a licensed `manifest.yaml`
+      (`08 §3.2`), and `tests/golden/ATTRIBUTIONS.md` regenerated (`python
+      tests/golden/_governance.py`) if any manifest changed.
+- [ ] **No parser defaulting introduced** — the absence convention holds and the
+      default-laundering suite passes (P3, Part 3 §2).
+- [ ] **Completeness invariant green** — the runtime assertion and the property suite
+      (`tests/property/`) both pass; no field is lost, dropped, or fabricated silently (P1/P4).
+- [ ] **Capability declarations updated** and the Part 3 §3 table sync test is green.
+- [ ] **Rejected alternative named** in the description for design changes.
+- [ ] **Attribution file regenerates cleanly** — the governance suite
+      (`tests/golden/test_corpus_governance.py`) is green.
+- [ ] **Contributed files carry license grants** — for any file added under
+      `origin.kind: contributed`, I have the right to contribute it and grant it under the
+      recorded license (Apache-2.0 or a compatible data license).
+- [ ] **Full local gate passed:** `ruff check .`, `ruff format --check .`, `mypy`,
+      `lint-imports`, `pytest`.

xtalate-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # 3.11 is the supported floor (catches use of newer syntax); 3.13 is the
+        # local dev interpreter (DECISIONS.md D11) — testing both keeps dev and CI
+        # from drifting.
+        python-version: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Ruff (lint)
+        run: ruff check .
+
+      - name: Ruff (format)
+        run: ruff format --check .
+
+      - name: Mypy
+        run: mypy
+
+      # Promoted to a required check in v0.2 M11 (Part 10 §1 deferral table, "earliest
+      # v0.2"): the import-linter contract from M0 confirmed as a blocking gate.
+      - name: Import-graph lint (P2)
+        run: lint-imports
+
+      # Install the example third-party plugin (M16B) so entry-point discovery is exercised
+      # against a real installed distribution — without it, tests/test_toyfmt_plugin.py skips.
+      # `--no-deps`: its declared `xtalate` dependency is already satisfied by the editable install
+      # above, and xtalate is not on any index yet (D52), so pip must not try to resolve it.
+      - name: Install entry-point discovery fixture (M16B)
+        run: pip install --no-deps ./tests/fixtures/xtalate_toyfmt
+
+      # Pytest enforces the coverage ratchet (--cov-fail-under in pyproject addopts) and the
+      # golden-corpus governance suite: manifest schema + license, per-source sha256, the
+      # schema-version migration-chain load, and the ATTRIBUTIONS.md regeneration diff
+      # (Part 8 §3; v0.2 M11). A silent fixture edit or a lapsed attribution fails here.
+      - name: Pytest (unit + golden + governance, with coverage gate)
+        run: pytest

xtalate-0.3.0/.github/workflows/nightly.yml

@@ -0,0 +1,106 @@
+name: nightly
+
+# The scheduled companion to ci.yml (MASTER_SPEC Part 8 §5, Part 9 §3). The PR suite is capped near
+# ten minutes; anything super-linear in formats or frames is deferred here, never dropped (M15B). A
+# nightly failure opens an issue automatically rather than blocking anyone's PR — visible, tracked,
+# not a surprise tax on unrelated work.
+on:
+  schedule:
+    # 07:00 UTC daily — off the working day, well clear of PR-triggered runs.
+    - cron: "0 7 * * *"
+  workflow_dispatch: {}
+
+# issues:write lets the failure step open the tracking issue; nothing else here needs write access.
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: nightly
+  cancel-in-progress: false
+
+jobs:
+  nightly:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Single interpreter (3.13, the dev floor's upper leg, DECISIONS.md D11): the deferred work
+      # here — the matrix, benchmarks, extended properties, audit — is not interpreter-sensitive the
+      # way the syntax-floor guard is, so the 3.11×3.13 fan-out stays on the PR (ci.yml).
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      # Stage 1 — the full n×n round-trip matrix beyond the curated PR subset (Part 8 §2.4).
+      # XTALATE_FULL_MATRIX=1 un-gates the `nightly`-marked pairs (tests/conftest.py); `-m nightly`
+      # then runs *only* them — the curated high-risk pairs already ran on the PR, so re-running them
+      # here would be waste. --no-cov because the coverage ratchet is a PR gate: this deliberately
+      # narrow subset would never clear the --cov-fail-under floor, and coverage is not what nightly
+      # is measuring.
+      - name: Full round-trip matrix
+        env:
+          XTALATE_FULL_MATRIX: "1"
+        run: pytest -m nightly --no-cov
+
+      # Stage 2 — the performance corpus (Part 8 §4), measured not gated: a budget breach is
+      # reported, only a *crash* fails the step (non-zero exit). The >20% regression tripwire against
+      # a rolling median is deliberately NOT wired here — shared GitHub runners are too noisy for
+      # comparable timings; it activates on v0.5's pinned runner (harness docstring; slice plan 15C).
+      - name: Performance benchmarks
+        run: python -m benchmarks --out benchmark-results
+
+      # The wall-time + peak-RSS series (JSON + CSV) — the artifact a maintainer downloads to chart
+      # the trend by hand until the automated tripwire lands. always() so a benchmark crash still
+      # uploads whatever series was written before it.
+      - name: Upload benchmark series
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results
+          path: benchmark-results/
+          if-no-files-found: warn
+
+      # Stage 3 — the extended property run at the widened hypothesis budget (max_examples=2000).
+      # HYPOTHESIS_PROFILE=nightly selects the `nightly` profile registered in tests/conftest.py; the
+      # PR run caps the same suite at the cheap `pr` profile. --no-cov for the same reason as stage 1.
+      - name: Extended property tests
+        env:
+          HYPOTHESIS_PROFILE: nightly
+        run: pytest tests/property --no-cov
+
+      # Stage 4 — dependency vulnerability audit (Part 8 §5). Advisory, not blocking:
+      # continue-on-error keeps a fresh advisory against a pinned dependency visible (the step goes
+      # yellow) without failing the job or opening a spurious issue. pip-audit is a dev-extra.
+      - name: Dependency audit
+        continue-on-error: true
+        run: pip-audit
+
+  # A failure in the nightly job (a crashed benchmark, a red matrix, a broken property) opens a
+  # tracking issue — the "failures auto-open issues" of Part 9 §3, so the scheduled run is visible
+  # without anyone watching the Actions tab. The dependency audit is excluded by design (it is
+  # continue-on-error, so an advisory never reaches here). Its own failure is swallowed (`|| true`):
+  # the issue is a courtesy, never a second thing that can break the pipeline.
+  open-issue-on-failure:
+    needs: nightly
+    if: failure()
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - name: Open a tracking issue
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          gh issue create --repo "${{ github.repository }}" \
+            --title "Nightly failure — $(date -u +%Y-%m-%d)" \
+            --body "The scheduled nightly workflow failed. Run: ${RUN_URL}" \
+            || true