se-theory-reference-kit 0.1.0__tar.gz

se_theory_reference_kit-0.1.0/.editorconfig

@@ -0,0 +1,125 @@
+# ============================================================
+# .editorconfig (Keep files consistent across editors and IDEs)
+# ============================================================
+
+# REQ.UNIVERSAL: All professional GitHub project repositories MUST include .editorconfig.
+# WHY: Establish a cross-editor baseline so diffs stay clean and formatting is consistent.
+# ALT: Repository may omit .editorconfig ONLY if formatting is enforced equivalently by CI and formatter tooling.
+# CUSTOM: Adjust indent_size defaults only if organizational standards change; keep stable across projects.
+# NOTE: Sections are ordered by editorial importance, not strict alphabetical order.
+# EditorConfig is documented at https://editorconfig.org
+
+root = true
+
+# === Global defaults (always apply) ===
+
+[*]
+# WHY: Normalize line endings and encoding across Windows, macOS, and Linux.
+end_of_line = lf
+charset = utf-8
+
+# WHY: Newline at EOF avoids noisy diffs and tool warnings.
+insert_final_newline = true
+
+# WHY: Remove accidental whitespace noise in diffs.
+trim_trailing_whitespace = true
+
+# WHY: Default to 2 spaces for configs and markup; language-specific overrides follow.
+indent_style = space
+indent_size = 2
+
+
+# === Build systems (special rules) ===
+
+[Makefile]
+# WHY: Makefiles require tabs.
+indent_style = tab
+
+[*.mk]
+# WHY: Makefile includes require tabs.
+indent_style = tab
+
+
+# === Citation and metadata ===
+
+[CITATION.cff]
+# WHY: Citation tooling expects stable YAML formatting.
+indent_size = 2
+indent_style = space
+
+
+# === Markup and documentation ===
+
+[*.md]
+# WHY: Keep Markdown clean; use explicit <br> for hard line breaks.
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.{tex,cls,sty}]
+# WHY: LaTeX convention is 2 spaces.
+indent_size = 2
+indent_style = space
+
+[*.xml]
+# WHY: XML convention is 2 spaces.
+indent_size = 2
+indent_style = space
+
+[*.{yml,yaml}]
+# WHY: YAML convention is 2 spaces.
+indent_size = 2
+indent_style = space
+
+
+# === Data and configuration ===
+
+[*.{json,jsonc,jsonl,ndjson}]
+# WHY: JSON tooling typically expects 2 spaces.
+indent_size = 2
+indent_style = space
+
+[*.toml]
+# WHY: TOML often follows 4-space indentation in many projects.
+indent_size = 4
+indent_style = space
+
+
+# === Programming languages ===
+
+[*.{js,ts}]
+# WHY: JS/TS ecosystem commonly uses 2 spaces.
+indent_size = 2
+indent_style = space
+
+[*.{py,pyi}]
+# WHY: Python convention is 4 spaces.
+indent_size = 4
+indent_style = space
+
+[*.ps1]
+# WHY: PowerShell convention is 4 spaces.
+indent_size = 4
+indent_style = space
+
+[*.{c,cpp,h,java,cs,go,rs}]
+# WHY: Many C-family and systems languages commonly use 4 spaces.
+indent_size = 4
+indent_style = space
+
+[*.{sh,bash}]
+# WHY: Shell script convention is 2 spaces.
+indent_size = 2
+indent_style = space
+
+
+# === Proof assistants and formal languages ===
+
+[*.lean]
+# WHY: Lean 4 convention is 2 spaces; matches Mathlib and stdlib style.
+indent_size = 2
+indent_style = space
+
+[*.{v,vo}]
+# WHY: Coq convention is 2 spaces.
+indent_size = 2
+indent_style = space

se_theory_reference_kit-0.1.0/.gitattributes

@@ -0,0 +1,130 @@
+# ============================================================
+# .gitattributes (Keep files consistent across operating systems)
+# ============================================================
+
+# REQ.UNIVERSAL: All professional GitHub project repositories MUST include .gitattributes.
+# WHY: Ensure consistent line endings, diff behavior, and file classification
+# across Windows, macOS, and Linux environments.
+# ALT: Repository may omit .gitattributes ONLY if equivalent normalization is
+# enforced reliably by tooling and CI (rare and fragile).
+# CUSTOM: Update file-type rules only when introducing new languages,
+# binary artifacts, or documentation formats.
+# NOTE: Rules are ordered by impact and generality, not alphabetically.
+# Git attributes are documented at https://git-scm.com/docs/gitattributes
+
+# === Core defaults (always apply) ===
+
+# WHY: Auto-detect text files and normalize line endings to avoid cross-platform drift.
+* text=auto
+
+
+# === Programming languages and scripts ===
+
+# WHY: Python and shell scripts must use LF for CI/CD, Linux environments, and containers.
+*.py    text eol=lf
+*.sh    text eol=lf
+
+# WHY: PowerShell convention on Windows uses CRLF.
+*.ps1   text eol=crlf
+
+
+# === Markup and documentation ===
+
+# WHY: Documentation and markup files use LF; standard for cross-platform tooling.
+*.md    text eol=lf
+*.tex   text eol=lf
+*.sty   text eol=lf
+*.cls   text eol=lf
+*.bib   text eol=lf
+
+
+# === Configuration and structured text ===
+
+# WHY: Configuration and structured text formats use LF for stable diffs.
+*.json     text eol=lf
+*.jsonc   text eol=lf
+*.jsonl   text eol=lf
+*.ndjson  text eol=lf
+*.toml    text eol=lf
+*.yaml    text eol=lf
+*.yml     text eol=lf
+
+
+# === Proof assistants and formal languages ===
+
+# WHY: Lean source files must use LF for cross-platform consistency and CI.
+*.lean   text eol=lf
+
+# WHY: Lean build artifacts are binary; prevent normalization and meaningless diffs.
+*.olean  binary
+*.ilean  binary
+*.trace  binary
+
+# WHY: Coq source uses LF; compiled objects are binary.
+*.v      text eol=lf
+*.vo     binary
+*.vok    binary
+*.vos    binary
+*.glob   binary
+
+# WHY: Lake build directory should be excluded, but if tracked, treat as binary.
+.lake/**  binary
+
+
+# === Notebooks ===
+
+# WHY: Jupyter notebooks require specialized diff and merge handling.
+*.ipynb   diff=jupyternotebook
+*.ipynb   merge=jupyternotebook
+
+
+# === Databases (binary) ===
+
+# WHY: Database files are binary; prevent text normalization and meaningless diffs.
+*.db       binary
+*.duckdb   binary
+*.sqlite   binary
+*.sqlite3  binary
+
+
+# === Columnar and analytical data (binary) ===
+
+# WHY: Columnar and analytical data formats are binary; diffs are not meaningful.
+*.arrow    binary
+*.avro     binary
+*.feather  binary
+*.orc      binary
+*.parquet  binary
+
+
+# === Office, BI, PDFs, and compressed artifacts (binary) ===
+
+# WHY: Office documents, BI files, PDFs, and compressed artifacts are binary.
+*.7z     binary
+*.bz2    binary
+*.docx   binary
+*.gz     binary
+*.pbix   binary
+*.pbit   binary
+*.pdf    binary
+*.pptx   binary
+*.rar    binary
+*.tar    binary
+*.tgz    binary
+*.xls    binary
+*.xlsm   binary
+*.xlsx   binary
+*.xz     binary
+*.zip    binary
+
+
+# === GitHub metadata and UI ===
+
+# WHY: Exclude documentation and tests from GitHub language statistics.
+docs/**    linguist-documentation
+tests/**   linguist-documentation
+
+# === LOG FILES ===
+# WHY: Log files are typically large and binary in nature; prevent text normalization.
+*.log binary
+project.log binary

se_theory_reference_kit-0.1.0/.github/.importlinter

@@ -0,0 +1,17 @@
+# .github/.importlinter
+# contract checks (should be all kept, 0 broken)
+# $env:PYTHONPATH = "src"
+# uvx --python 3.13 --from import-linter lint-imports --config .github/.importlinter
+
+[importlinter]
+root_package = se_theory_reference_kit
+
+[importlinter:contract:layers]
+name = SE reference kit layering
+type = layers
+layers =
+    se_theory_reference_kit.validation
+    se_theory_reference_kit.export
+    se_theory_reference_kit.reference
+    se_theory_reference_kit.declarations
+    se_theory_reference_kit.base

se_theory_reference_kit-0.1.0/.github/.yamllint.yml

@@ -0,0 +1,16 @@
+# ============================================================
+# .github/.yamllint.yml (Keep YAML files clean and consistent)
+# ============================================================
+# Updated: 2026-04-13
+
+# WHY: Enforce YAML correctness (.github/.yamllint.yml) without arbitrary style constraints.
+# OBS: Default yamllint rules conflict with GitHub Actions YAML.
+#      Line length, document start, truthy, and comment spacing are intentionally disabled.
+
+extends: default
+
+rules:
+  line-length: disable
+  document-start: disable
+  truthy: disable
+  comments: disable

se_theory_reference_kit-0.1.0/.github/dependabot.yml

@@ -0,0 +1,24 @@
+# ============================================================
+# .github/dependabot.yml (Check for GitHub Actions updates)
+# ============================================================
+# REQ.PROJECT: This repository SHOULD track GitHub Actions updates automatically.
+# WHY-FILE: GitHub Actions are executable dependencies and may receive security or behavior updates.
+# OBS: Language-level dependencies (e.g., Python packages) are upgraded manually.
+# OBS: GitHub Actions are the only dependency class automated here.
+# ALT: Dependabot could be omitted if workflows are pinned and reviewed manually.
+# CUSTOM: Update interval if CI cadence or security posture changes.
+
+# NOTE: This file automatically updates the versions used in Actions workflows.
+# You don't need to modify this file.
+# To disable: Delete this file or set enabled: false below.
+# enabled: false # Uncomment to disable Dependabot
+
+version: 2 # Dependabot configuration version
+
+updates:
+  - package-ecosystem: "github-actions" # Dependency type
+    directory: "/" # Location of GitHub Actions workflows
+    schedule:
+      interval: "monthly" # ALT: Use "weekly" for higher security when needed
+    commit-message:
+      prefix: "(deps)"  # WHY: enable filtering by commit type

se_theory_reference_kit-0.1.0/.github/lychee.toml

@@ -0,0 +1,48 @@
+# ============================================================
+# .github/lychee.toml (Lychee link checker configuration)
+# ============================================================
+# Updated: 2026-04-13
+
+# REQ.PROJECT: Automatic link checking using GitHub Actions and Lychee.
+# WHY-FILE: Shared Lychee configuration (lychee.toml) for documentation-heavy repositories.
+# REQ: Link checking MUST be reliable and CI-safe.
+# WHY: Configures Lychee link checker behavior for CI/CD.
+# OBS: Flat structure required by lychee v0.22+; no nested sections.
+# OBS: No path exclusions; all documentation files are expected to be link-clean.
+# OBS: Link integrity preserves stable, reconstructible references over time.
+# OBS: Link integrity maintains connections to external resources.
+
+# WHY: Control verbosity and CI-friendly output
+verbose = "info"   # WHY: Balance between detail and noise
+no_progress = true # WHY: Progress bars don't work well in CI logs
+
+# WHY: Performance tuning for link checking
+max_concurrency = 6 # WHY: Parallel requests without overwhelming servers
+max_retries = 3     # WHY: Retry flaky connections before failing
+retry_wait_time = 8 # WHY: Wait 8 seconds between retries
+timeout = 30        # WHY: 30 seconds per request before timeout
+
+# WHY: Accept common status codes that don't indicate broken links
+# OBS: 403 and 429 reduce false positives
+accept = [
+  200, # OK
+  206, # Partial content
+  301, # Moved permanently
+  302, # Found (temporary redirect)
+  307, # Temporary redirect
+  308, # Permanent redirect
+  403, # Forbidden (often false positive)
+  429, # Too many requests (rate limiting)
+]
+
+# WHY: Exclude patterns that shouldn't be checked
+exclude = [
+  "^https://shields\\.io", # WHY: Shields.io badges often have anti-bot measures that cause false positives
+  "^https://img\\.shields\\.io", # WHY: Shields.io image badges often have anti-bot measures that cause false positives
+  "^https://badges\\.github\\.com", # WHY: GitHub badges often have anti-bot measures that cause false positives
+  "^https://www\\.linkedin\\.com", # WHY: LinkedIn often blocks automated requests, causing false positives
+  "example\\.com",   # WHY: Exclude example domains in documentation
+  "localhost",       # WHY: Exclude local development URLs
+  "127\\.0\\.0\\.1", # WHY: Exclude local loopback
+  "\\.local",        # WHY: Exclude local network domains
+]

se_theory_reference_kit-0.1.0/.github/workflows/ci-python-zensical.yml

@@ -0,0 +1,112 @@
+# ============================================================
+# .github/workflows/ci-python-zensical.yml (Continuous Integration)
+# ============================================================
+# Updated: 2026-06-01 (pypi ci)
+#
+# WHY-FILE: Validate repository hygiene, Python correctness, and documentation builds.
+#
+# === COVERAGE ===
+#
+# COVERED BY PRE-COMMIT - not repeated as explicit steps:
+#   - ruff-check (lint with autofix)
+#   - ruff-format (formatting)
+#   - trailing whitespace, line endings, JSON/TOML/YAML syntax, large files
+#
+# WHY SEPARATE: These tools are slower, require the full environment,
+# or produce output worth seeing in CI logs independently.
+
+name: CI (Python + Zensical)
+
+on:
+  push:
+    branches: [main]       # WHY: Validate every push to main.
+  pull_request:
+    branches: [main]       # WHY: Validate PRs before merge.
+  workflow_dispatch:        # WHY: Allow manual trigger from Actions tab.
+
+permissions:
+  contents: read            # WHY: Least privilege; CI only reads, never writes.
+
+env:
+  PYTHONUNBUFFERED: "1"    # WHY: Real-time log output in CI.
+  PYTHONIOENCODING: "utf-8" # WHY: Consistent encoding across platforms.
+  PYTHON_VERSION: "3.15"
+
+
+jobs:
+  ci:
+    name: Repository / Python checks and Zensical build
+    runs-on: ubuntu-latest  # WHY: Linux matches most production deployments.
+    timeout-minutes: 30     # WHY: Fail fast if a step hangs unexpectedly.
+
+    steps:
+      # ============================================================
+      # A) ASSEMBLE: Checkout code and set up environment
+      # ============================================================
+
+      - name: A1) Checkout repository code
+        uses: actions/checkout@v6
+        # WHY: Required so all subsequent steps can access repo files.
+
+      - name: A2) Install uv (with caching)
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          # WHY: Cache the uv tool itself for faster subsequent runs.
+          cache-dependency-glob: "uv.lock"
+          # WHY: Invalidate cache only when locked dependencies change.
+
+      - name: A3) Install Python ${{ env.PYTHON_VERSION }}
+        run: uv python install ${{ env.PYTHON_VERSION }}
+        # WHY: Ensures the pinned Python version is available in CI.
+        # OBS: Does not modify the repo; uv manages the interpreter locally.
+
+      - name: A4) Install all dependencies
+        run: uv sync --extra dev --extra docs --upgrade
+        # WHY: Install dev and docs extras so all check and build tools are available.
+        # OBS: --upgrade ensures CI catches dependency drift early.
+
+      - name: A5) Show tool versions
+        run: |
+          uv --version
+          uv run python --version
+          uv run python -m ruff --version
+          uv run python -m pyright --version
+          if [ -f "zensical.toml" ]; then
+            uv run python -m zensical --version
+          fi
+
+      - name: A6) Run pre-commit on all files
+        run: uv tool run pre-commit run --all-files
+
+      # ============================================================
+      # B) BASELINE CHECKS: Tools not covered by pre-commit
+      # ============================================================
+      - name: B1) Run Pyright type checker
+        run: uv run python -m pyright
+
+      # ============================================================
+      # C) COVERAGE & TESTING: Python tests (pytest)
+      # ============================================================
+
+      - name: C1) Run pytest
+        run: uv run python -m pytest
+
+      # ============================================================
+      # D) Docs build (no deployment)
+      # ============================================================
+
+      - name: D1) Build documentation with Zensical
+        run: |
+          if [ -f "zensical.toml" ]; then
+            uv run python -m zensical build
+          else
+            echo "No zensical.toml found; skipping docs build."
+          fi
+
+      # ============================================================
+      # E) Execute local cli commands for additional checks
+      # ============================================================
+
+      - name: E1) Validate repository manifest against schema
+        run: uvx --from se-manifest-schema se-manifest validate-manifest --path SE_MANIFEST.toml --strict

se_theory_reference_kit-0.1.0/.github/workflows/deploy-zensical.yml

@@ -0,0 +1,125 @@
+# ============================================================
+# .github/workflows/deploy-zensical.yml (Deploy Docs)
+# ============================================================
+# Updated: 2026-06-01 (pypi docs deploy)
+#
+# WHY-FILE: Build and deploy documentation to GitHub Pages on pushes to main.
+#
+# REQ: Repo Settings -> Pages -> Build and deployment -> Source:
+#      GitHub Actions
+# WHY: Without this setting, the deploy-pages action will fail with a 403.
+#
+# OBS: This workflow deploys only. Correctness of the build is validated
+#      by ci-python-zensical.yml before merging to main.
+# OBS: Deployment runs after CI passes on push to main, not on PRs.
+# WHY: PRs use CI to validate; deployment only happens on confirmed main commits.
+
+name: Docs Deploy (Zensical)
+
+on:
+  push:
+    branches: [main]    # WHY: Deploy on every confirmed push to main.
+  workflow_dispatch:     # WHY: Allow manual redeploy from Actions tab if needed.
+
+permissions:
+  contents: read        # WHY: Needed to checkout code.
+  pages: write          # WHY: Required to deploy to GitHub Pages.
+  id-token: write       # WHY: Required by deploy-pages for OIDC authentication.
+
+env:
+  PYTHONUNBUFFERED: "1"     # WHY: Real-time log output in CI.
+  PYTHONIOENCODING: "utf-8" # WHY: Consistent encoding across platforms.
+  PYTHON_VERSION: "3.15"
+
+concurrency:
+  group: github-pages
+  # WHY: Pages is a single deployment environment per repo. A static group
+  #      serializes every Pages deploy across all workflows and refs, so a
+  #      tag-triggered docs deploy cannot race a main-push deploy.
+  # OBS: Any other workflow that deploys to Pages must reuse this exact group.
+  cancel-in-progress: false
+  # WHY: Never cancel a live deployment. Let the in-progress run finish and
+  #      skip intermediate queued runs, keeping only the latest.
+
+jobs:
+  docs:
+    name: Deploy Documentation site
+    runs-on: ubuntu-latest
+    timeout-minutes: 30   # WHY: Fail fast if a step hangs unexpectedly.
+
+    steps:
+      # ============================================================
+      # A) ASSEMBLE: Checkout code and set up environment
+      # ============================================================
+
+      - name: A1) Checkout repository code
+        uses: actions/checkout@v6
+        # WHY: Required so all subsequent steps can access repo files.
+
+      - name: A2) Configure GitHub Pages
+        uses: actions/configure-pages@v6
+        # WHY: Sets Pages metadata used by upload-pages-artifact and deploy-pages.
+        # OBS: Must run before the build step so base URL is available if needed.
+
+      - name: A3) Install uv (with caching)
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          # WHY: Invalidate cache only when locked dependencies change.
+
+      - name: A4) Install Python ${{ env.PYTHON_VERSION }}
+        run: uv python install ${{ env.PYTHON_VERSION }}
+
+      - name: A5) Install all dependencies
+        run: uv sync --extra dev --extra docs --upgrade
+        # WHY: Docs extras required for Zensical build; dev extras for consistency.
+
+      - name: A6) Show tool versions
+        run: |
+          uv --version
+          uv run python --version
+          if [ -f "zensical.toml" ]; then
+            uv run python -m zensical --version
+          fi
+        # WHY: Version output makes deployment logs easier to debug when tools change.
+
+      # ============================================================
+      # D) DEPLOY: Build and publish docs
+      # ============================================================
+
+      - name: D1) Build docs with Zensical
+        run: |
+          if [ ! -f "zensical.toml" ]; then
+            echo "zensical.toml not found; refusing to deploy." >> "$GITHUB_STEP_SUMMARY"
+            exit 1
+          fi
+          uv run python -m zensical build
+        # WHY: Hard-fail if zensical.toml is missing rather than deploying nothing.
+        # OBS: In CI (ci-python-zensical.yml) the missing config is a soft skip.
+        #      Here it is a hard failure because a deploy without docs is wrong.
+
+      - name: D2) Verify site output exists
+        run: |
+          if [ ! -d "site" ]; then
+            echo "## Documentation build output missing" >> "$GITHUB_STEP_SUMMARY"
+            echo "Expected directory 'site/' was not created." >> "$GITHUB_STEP_SUMMARY"
+            echo "Check the Zensical build step and zensical.toml configuration." >> "$GITHUB_STEP_SUMMARY"
+            exit 1
+          fi
+        # WHY: Catch a silent build failure before attempting to upload an empty artifact.
+        # OBS: Zensical outputs to site/ by default; update this path if zensical.toml
+        #      configures a different output directory.
+
+      - name: D3) Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+        # WHY: Packages the built static site for the deploy-pages action.
+        # OBS: path must match the output directory verified in D2.
+
+      - name: D4) Deploy to GitHub Pages
+        uses: actions/deploy-pages@v5
+        # WHY: Publishes the uploaded artifact to GitHub Pages.
+        # OBS: Requires pages: write and id-token: write permissions (set above).
+        # OBS: The deployed URL is shown in the Actions log after this step completes.

se_theory_reference_kit-0.1.0/.github/workflows/links.yml

@@ -0,0 +1,53 @@
+# ============================================================
+# .github/workflows/links.yml (Lychee Link Checker)
+# ============================================================
+# Updated: 2026-06-01 (all repos link check)
+
+# WHY-FILE: Automated link checking.
+# OBS: Behavior is configured in lychee.toml in this repository.
+# OBS: Runs on pull requests and monthly on schedule; manual trigger always available.
+
+name: Check Links
+
+on:
+  workflow_call: # WHY: Allow this workflow to be called by other workflows if needed
+  workflow_dispatch: # WHY: Manual trigger - always available
+  pull_request: # WHY: Validates PR links before merge
+  schedule:
+    - cron: "0 6 1 * *" # WHY: Runs monthly (1st of month)
+
+concurrency:
+  # WHY: Prevent multiple simultaneous link checks on same ref
+  group: link-check-${{ github.ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read # WHY: Needed to checkout code.
+
+env:
+  PYTHONUNBUFFERED: "1" # WHY: Real-time logging.
+  PYTHONIOENCODING: "utf-8" # WHY: Ensure UTF-8 encoding for international characters.
+  REPORT_PATH: "./lychee/out.md" # WHY: Predictable markdown report path for summary generation.
+
+jobs:
+  lychee:
+    name: Link checks
+    runs-on: ubuntu-latest # WHY: Linux environment matches most production deployments
+    timeout-minutes: 20 # WHY: Prevent hanging jobs. If over time, likely stuck.
+
+    steps:
+      - name: 1) Checkout repository code
+        uses: actions/checkout@v6
+        # WHY: Required so Lychee can inspect repository files.
+
+      - name: 2) Run Lychee
+        uses: lycheeverse/lychee-action@v2.8.0
+        with:
+          args: >
+            --config .github/lychee.toml
+            --verbose
+            --no-progress
+            './**/*.md'
+            './**/*.html'
+            './**/*.yml'
+            './**/*.yaml'