reactive-research 0.1.0__tar.gz

reactive_research-0.1.0/.annotations/annotations.md

@@ -0,0 +1,10 @@
+# Annotations
+
+<!--
+WHY: This repository uses the Structural Explainability Annotation Standard
+to document decisions, constraints, and alternatives directly alongside
+code and configuration.
+-->
+
+This repository uses the annotation standard defined at:
+<https://github.com/structural-explainability/.github/blob/main/ANNOTATIONS.md>

reactive_research-0.1.0/.editorconfig

@@ -0,0 +1,197 @@
+# ============================================================
+# .editorconfig (ALL-REPOS)
+# ============================================================
+# Updated: 2026-09-25
+#
+# REQ: All professional GitHub project repositories MUST include .editorconfig.
+# WHY: Establish a cross-editor baseline so diffs stay clean and formatting
+# is consistent across editors and IDEs.
+# 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.
+# EditorConfig: https://editorconfig.org
+
+root = true
+
+
+# === Core defaults ===
+
+[*]
+# WHY: Normalize line endings and encoding across Windows, macOS, and Linux.
+charset = utf-8
+end_of_line = lf
+
+# WHY: Default to 2 spaces for configs and markup; language-specific overrides follow.
+indent_size = 2
+indent_style = space
+
+# 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
+
+
+# === Named root and metadata files ===
+
+[CITATION.cff]
+# WHY: Citation tooling expects stable YAML formatting.
+indent_size = 2
+indent_style = space
+
+[CODEOWNERS]
+# WHY: CODEOWNERS is a structured text file; keep formatting simple and stable.
+indent_size = 2
+indent_style = space
+
+[LICENSE]
+# WHY: License text should remain plain, stable, and editor-neutral.
+indent_size = 2
+indent_style = space
+
+
+# === Build systems ===
+
+[Makefile]
+# WHY: Makefile recipe lines require real tab characters.
+indent_style = tab
+indent_size = tab
+
+[*.mk]
+# WHY: Makefile includes may contain recipes and should preserve real tabs.
+indent_style = tab
+indent_size = tab
+
+
+# === Markup and documentation ===
+
+[*.md]
+# WHY: Keep Markdown clean; use explicit <br> for hard line breaks.
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.qmd]
+# WHY: Quarto Markdown follows Markdown-style formatting.
+indent_size = 2
+indent_style = space
+
+[*.rst]
+# WHY: reStructuredText documentation benefits from stable 2-space indentation.
+indent_size = 2
+indent_style = space
+
+[*.{bib,cls,sty,tex,typ}]
+# WHY: LaTeX, BibTeX, and Typst source use a stable 2-space convention.
+indent_size = 2
+indent_style = space
+
+[*.{css,html,xml}]
+# WHY: Web and XML markup convention is 2 spaces.
+indent_size = 2
+indent_style = space
+
+
+# === Configuration and structured text ===
+
+[*.env]
+# WHY: Environment templates should remain simple line-oriented text.
+indent_size = 2
+indent_style = space
+
+[*.{cfg,ini}]
+# WHY: INI-style configuration convention is 2 spaces.
+indent_size = 2
+indent_style = space
+
+[*.{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
+
+[*.{yaml,yml}]
+# WHY: YAML convention is 2 spaces.
+indent_size = 2
+indent_style = space
+
+
+# === Programming languages and scripts ===
+
+[*.{bat,cmd}]
+# WHY: Windows batch and command scripts use a simple 2-space shared baseline.
+indent_size = 2
+indent_style = space
+
+[*.{bash,sh}]
+# WHY: Shell script convention is 2 spaces.
+indent_size = 2
+indent_style = space
+
+[*.{c,cpp,cs,go,h,hpp,java,rs}]
+# WHY: Many C-family and systems languages commonly use 4 spaces.
+indent_size = 4
+indent_style = space
+
+[*.jl]
+# WHY: Julia convention commonly uses 4 spaces.
+indent_size = 4
+indent_style = space
+
+[*.{cjs,js,jsx,mjs,ts,tsx}]
+# WHY: JavaScript and TypeScript ecosystems commonly use 2 spaces.
+indent_size = 2
+indent_style = space
+
+[*.mojo]
+# WHY: Mojo uses Python-like syntax and commonly follows 4-space indentation.
+indent_size = 4
+indent_style = space
+
+[*.ps1]
+# WHY: PowerShell convention is 4 spaces.
+indent_size = 4
+indent_style = space
+
+[*.{py,pyi}]
+# WHY: Python convention is 4 spaces.
+indent_size = 4
+indent_style = space
+
+[*.{r,R}]
+# WHY: R convention commonly uses 2 spaces.
+indent_size = 2
+indent_style = space
+
+[*.sql]
+# WHY: SQL formatting varies, but 2 spaces is a stable shared baseline.
+indent_size = 2
+indent_style = space
+
+
+# === Formal, math, and proof languages ===
+
+[*.lean]
+# WHY: Lean 4 convention is 2 spaces; matches Mathlib and stdlib style.
+indent_size = 2
+indent_style = space
+
+
+# === Notebooks ===
+
+[*.ipynb]
+# WHY: Jupyter notebooks are JSON documents; keep embedded formatting stable.
+indent_size = 2
+indent_style = space
+
+
+# === Text and tabular data ===
+
+[*.{csv,dat,psv,tsv,txt,ged}]
+# WHY: Text and tabular data should remain simple line-oriented text.
+indent_size = 2
+indent_style = space

reactive_research-0.1.0/.gitattributes

@@ -0,0 +1,209 @@
+# ============================================================
+# .gitattributes (ALL-REPOS)
+# ============================================================
+# Updated: 2026-09-25
+#
+# REQ: All professional GitHub repositories SHOULD include .gitattributes.
+# WHY: Keep line endings, diffs, merges, and file classification consistent
+# across Windows, macOS, Linux, GitHub Actions, and other environments.
+# CUSTOM: Add repository-specific rules when files require different handling.
+# Git attributes: https://git-scm.com/docs/gitattributes
+
+
+# === Core defaults ===
+
+# WHY: Auto-detect text files and normalize text to LF unless a later rule
+# is more specific.
+* text=auto eol=lf
+
+
+# === Named root and metadata files ===
+
+# WHY: Important repository metadata files are text and should use LF.
+.gitattributes   text eol=lf
+.gitignore       text eol=lf
+.editorconfig    text eol=lf
+.python-version  text eol=lf
+CODEOWNERS       text eol=lf
+LICENSE          text eol=lf
+uv.lock          text eol=lf
+
+
+# === Operating-system files ===
+
+# WHY: OS metadata files are binary/noisy and should not be normalized or diffed.
+.DS_Store    binary
+Thumbs.db    binary
+desktop.ini  binary
+
+
+# === Markup and documentation ===
+
+# WHY: Documentation, web, and math markup use LF for stable cross-platform diffs.
+*.bib   text eol=lf
+*.cff   text eol=lf
+*.cls   text eol=lf
+*.css   text eol=lf
+*.html  text eol=lf
+*.md    text eol=lf
+*.qmd   text eol=lf
+*.rst   text eol=lf
+*.sty   text eol=lf
+*.tex   text eol=lf
+*.typ   text eol=lf
+*.xml   text eol=lf
+
+
+# === Configuration and structured text ===
+
+# WHY: Configuration and structured text files should produce stable diffs.
+*.cfg     text eol=lf
+*.env     text eol=lf
+*.ini     text eol=lf
+*.json    text eol=lf
+*.jsonc   text eol=lf
+*.jsonl   text eol=lf
+*.ndjson  text eol=lf
+*.toml    text eol=lf
+*.txt     text eol=lf
+*.yaml    text eol=lf
+*.yml     text eol=lf
+
+
+# === Programming languages and scripts ===
+
+# WHY: Source and script files use LF for CI, shells, containers, and tooling.
+*.c     text eol=lf
+*.cpp   text eol=lf
+*.cs    text eol=lf
+*.go    text eol=lf
+*.h     text eol=lf
+*.hpp   text eol=lf
+*.java  text eol=lf
+*.jl    text eol=lf
+*.js    text eol=lf
+*.jsx   text eol=lf
+*.mjs   text eol=lf
+*.cjs   text eol=lf
+*.mojo  text eol=lf
+*.ps1   text eol=lf
+*.py    text eol=lf
+*.pyi   text eol=lf
+*.r     text eol=lf
+*.R     text eol=lf
+*.rs    text eol=lf
+*.sh    text eol=lf
+*.sql   text eol=lf
+*.ts    text eol=lf
+*.tsx   text eol=lf
+
+# WHY: Windows batch scripts conventionally use CRLF and may be consumed by
+# Windows tooling that expects Windows-style line endings.
+*.bat  text eol=crlf
+*.cmd  text eol=crlf
+
+
+# === Formal, math, and proof languages ===
+
+# WHY: Lean source files are text; Lean build artifacts are binary.
+*.ilean  binary
+*.lean   text eol=lf
+*.olean  binary
+*.trace  binary
+
+# WHY: Lake build output should not be normalized if accidentally tracked.
+.lake/**  binary
+
+
+# === Notebooks ===
+
+# WHY: Jupyter notebooks are JSON-based text files and benefit from stable
+# cross-platform line endings.
+*.ipynb  text eol=lf
+
+
+# === Text and tabular data ===
+
+# WHY: Small text data files benefit from readable diffs.
+*.csv  text eol=lf
+*.dat  text eol=lf
+*.psv  text eol=lf
+*.tsv  text eol=lf
+
+
+# === Images and web binary assets ===
+
+# WHY: Image and compiled web asset formats are binary; text diffs are not meaningful.
+*.avif   binary
+*.bmp    binary
+*.gif    binary
+*.ico    binary
+*.jpeg   binary
+*.jpg    binary
+*.png    binary
+*.webp   binary
+*.wasm   binary
+
+# WHY: SVG is XML-based text and benefits from readable diffs.
+*.svg  text eol=lf
+
+
+# === Databases ===
+
+# WHY: Database files are binary; text diffs are not meaningful.
+*.db       binary
+*.duckdb   binary
+*.sqlite   binary
+*.sqlite3  binary
+
+
+# === Columnar and analytical data ===
+
+# WHY: Columnar and analytical formats are binary; text diffs are not meaningful.
+*.arrow    binary
+*.avro     binary
+*.feather  binary
+*.orc      binary
+*.parquet  binary
+
+
+# === Office, BI, PDF, and compressed artifacts ===
+
+# WHY: Office, BI, PDF, and archive files are binary.
+*.7z    binary
+*.bz2   binary
+*.doc   binary
+*.docx  binary
+*.gz    binary
+*.odp   binary
+*.ods   binary
+*.odt   binary
+*.pbix  binary
+*.pbit  binary
+*.pdf   binary
+*.ppt   binary
+*.pptx  binary
+*.rar   binary
+*.tar   binary
+*.tgz   binary
+*.xls   binary
+*.xlsm  binary
+*.xlsx  binary
+*.xz    binary
+*.zip   binary
+
+
+# === Logs and generated runtime output ===
+
+# WHY: Logs are text when intentionally committed and should remain readable
+# and diffable.
+# NOTE: Most logs are ignored by .gitignore. Repository-specific research
+# evidence may override text normalization with -text when exact bytes matter.
+*.log  text eol=lf
+
+
+# === GitHub metadata and UI ===
+
+# WHY: Exclude documentation and tests from GitHub language statistics.
+docs/**   linguist-documentation
+tests/**  linguist-documentation

reactive_research-0.1.0/.github/.yamllint.yml

@@ -0,0 +1,31 @@
+# ============================================================
+# .github/.yamllint.yml (ALL-REPOS)
+# ============================================================
+# Updated: 2026-09-25
+#
+# REQ: All repositories with YAML SHOULD lint YAML files
+# to keep them clean and consistent.
+# WHY: Detect malformed YAML, duplicate keys, indentation errors, trailing
+# whitespace, and other structural problems before they reach CI/CD tooling.
+# ALT: Style-only rules that create noise without improving correctness are
+# intentionally relaxed for GitHub Actions and shared project configuration.
+# yamllint: https://yamllint.readthedocs.io/
+
+extends: default
+
+rules:
+  # WHY: Workflow expressions, URLs, commands, and generated values can
+  # legitimately exceed an arbitrary line-length limit.
+  line-length: disable
+
+  # WHY: Repository YAML files do not require an explicit YAML document marker.
+  document-start: disable
+
+  # WHY: Comment layout is documentation style rather than YAML correctness.
+  comments: disable
+
+  # WHY: GitHub Actions uses `on` as a mapping key. Under YAML 1.1 semantics,
+  # yamllint may otherwise treat that key as a truthy value.
+  # WHY: Keep truthy-value checking for actual values while excluding keys.
+  truthy:
+    check-keys: false

reactive_research-0.1.0/.github/dependabot.yml

@@ -0,0 +1,47 @@
+# ============================================================
+# .github/dependabot.yml (ALL-REPOS)
+# ============================================================
+# Updated: 2026-09-25
+#
+# REQ: All repositories SHOULD track GitHub Actions updates automatically.
+# WHY: GitHub Actions are executable dependencies and may receive security,
+# reliability, or behavior updates.
+# OBS: Language-level dependencies (for example, Python packages) are upgraded
+# manually using the project's package-management workflow.
+# OBS: GitHub Actions are the only dependency class automated here.
+# ALT: Dependabot version updates may be omitted when Actions are pinned and
+# reviewed manually through another established maintenance process.
+# CUSTOM: Adjust the schedule when repository activity or security posture
+# warrants a different review cadence.
+#
+# NOTE: Dependabot updates GitHub Actions references used in workflow files,
+# including Actions pinned to full commit SHAs.
+# NOTE: When a pinned Action has a version comment on the same line, Dependabot
+# can update that documentation along with the commit reference.
+# NOTE: Dependabot security updates are distinct from scheduled version updates
+# and can raise pull requests for vulnerable Actions when enabled in GitHub.
+#
+# Dependabot:
+# https://docs.github.com/code-security/dependabot
+
+version: 2
+
+updates:
+  - package-ecosystem: "github-actions"
+
+    # WHY: "/" tells Dependabot to inspect GitHub Actions workflows for this
+    # repository.
+    directory: "/"
+
+    schedule:
+      # WHY: Weekly checks keep executable CI dependencies reasonably current
+      # without creating daily maintenance noise.
+      interval: "weekly"
+
+    commit-message:
+      # WHY: Use a recognizable dependency prefix for filtering and history.
+      prefix: "(deps)"
+
+    cooldown:
+      default-days: 7
+      # WHY: Match the 7-day cooldown used by uv exclude-newer and prek.

reactive_research-0.1.0/.github/lychee.toml

@@ -0,0 +1,88 @@
+# ============================================================
+# .github/lychee.toml (ALL-REPOS)
+# ============================================================
+# Updated: 2026-09-25
+#
+# REQ: Repositories with documentation SHOULD check links automatically.
+# WHY: Broken links reduce the reliability and reproducibility of documentation,
+# references, instructions, and external resources.
+# REQ: Link checking MUST be reliable and CI-safe.
+# WHY: Configuration should detect genuinely broken links while minimizing
+# false failures caused by rate limiting, authentication, and anti-bot services.
+# OBS: Lychee configuration uses a flat structure for these options.
+# OBS: Repository-specific path exclusions should be added only when needed.
+# CUSTOM: Add exclusions only for links or paths that are known to be unsuitable
+# for automated checking.
+#
+# Lychee: https://lychee.cli.rs/
+
+# === Output ===
+
+# WHY: Provide enough information to diagnose failures without excessive CI noise.
+verbose = "info"
+
+# WHY: Interactive progress bars are not useful in CI logs.
+no_progress = true
+
+# === Request reliability ===
+
+# WHY: Limit parallel requests so CI does not overwhelm external servers.
+max_concurrency = 6
+
+# WHY: Retry transient network failures before declaring a link broken.
+max_retries = 3
+
+# WHY: Allow transient rate limits or service interruptions time to clear.
+retry_wait_time = 8
+
+# WHY: Prevent an unresponsive external service from blocking the workflow indefinitely.
+timeout = 30
+
+# === Accepted HTTP responses ===
+
+# WHY: Accept common status codes that don't indicate broken links
+# OBS: 403 and 429 reduce false positives
+accept = [
+  "200..=299", # OK, partial content, etc.
+  301, # Moved permanently
+  302, # Found (temporary redirect)
+  307, # Temporary redirect
+  308, # Permanent redirect
+  403, # Forbidden (often false positive)
+  429, # Too many requests (rate limiting)
+]
+
+# === Network exclusions ===
+
+# WHY: Localhost and loopback URLs describe local development services and are
+# not expected to resolve from GitHub Actions.
+exclude_loopback = true
+
+# === URL exclusions ===
+
+# WHY: Exclude external services known to block or interfere with automated
+# link-checking requests.
+# NOTE: Values are regular expressions matched against URLs.
+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
+]
+
+# === Path exclusions ===
+
+# WHY: Exclude paths not relevant for link checking.
+# NOTE: These names are used by the shared template repository and are harmless
+# in repositories that do not contain matching paths.
+exclude_path = [
+  "ALL",
+  "ALL-PY",
+  "ALL-PY-SRC",
+  "ALL-COURSE",
+  "ALL-COURSE-PY-SRC",
+]