OikosBot

A code-analysis GitHub/GitLab App that adds ecological and economic review to pull requests.

Note

This repository is only OikosBot, and it is easy to confuse with two similarly-named-but-separate things: oikos — the stock-flow consistent economics DSL, now in hyperpolymath/oikos-economics-accounting-dsl. sustainabot — a reserved member slot of hyperpolymath/gitbot-fleet (bots/sustainabot/), to be prototyped later. OikosBot is not sustainabot; the implementation that briefly lived there was a misfiled copy of OikosBot and has been moved into this repo. See DISAMBIGUATION.adoc for the full breakdown.

Table of Contents

• Documentation
• Status
• Repository Layout
• Data Layer
• Local Checks
• GitHub App
• Licence

Documentation

For a map of all documentation — grouped by audience (developer / maintainer / end-user) and by concept — see docs/README.adoc.

Status

0.1.0-dev. OikosBot is not currently deployed in production.

The Rust analysis workspace (crates/oikosbot-*: CLI, analysis engine, metrics, SARIF output, and Eclexia policy evaluation) builds and tests cleanly and is the most complete surface — it was extracted from the former gitbot-fleet/bots/sustainabot/ and renamed.

The AffineScript webhook receiver (bot-integration-affine/) is a scaffold. HMAC-SHA256 webhook signature verification is implemented in bot-integration-affine/src/Webhook.affine (constant-time, via the hpm-crypto RSR FFI), and the upstream AffineScript standard-library prerequisites have landed (json RSR rewire, affinescript#421; Http server RSR rewire, affinescript#425). The webhook → analyse → comment orchestration is now wired in source (src/Payload.affine extracts the PR fields and handle_github_webhook runs Oikos.handle_pr_event); what remains is binding the HTTP listener (Sub.http_server), which is gated on the stdlib Http::Server host type. (The AffineScript changes are unverified — there is no AS toolchain in this environment.)

The Haskell analyzer scaffold (analyzers/code-haskell/) builds independently.

Repository Layout

oikosbot/
|-- crates/                  # Rust workspace (oikosbot-* analysis engine + CLI)
|   |-- oikosbot-cli/        #   `oikosbot` binary (analyze / check / report)
|   |-- oikosbot-analysis/   #   tree-sitter analysis + eco/econ heuristics
|   |-- oikosbot-metrics/    #   shared metric/result types
|   |-- oikosbot-sarif/      #   SARIF report generation
|   |-- oikosbot-eclexia/    #   Eclexia (.ecl) policy evaluation
|   `-- oikosbot-fleet/      #   OPTIONAL gitbot-fleet bridge (excluded by default)
|-- bot-integration-affine/  # AffineScript webhook receiver (in flight)
|-- analyzers/code-haskell/  # Haskell eco/econ/quality analysis engine
|-- policy-engine/           # Datalog and DeepProbLog policy rules
|-- policies/                # Eclexia (.ecl) policy definitions
|-- config/oikos.yaml        # Bot configuration
|-- databases/ontology/      # eco.ttl — VeriSimDB semantic-witness ontology seed
|-- examples/                # Example CI integration
|-- fuzz/                    # cargo-fuzz targets (excluded from the workspace)
|-- docs/                    # GITHUB_APP_SETUP.adoc, tech-debt audit
|-- ARCHITECTURE.adoc        # Platform architecture (target design)
|-- DISAMBIGUATION.adoc      # oikos vs OikosBot vs sustainabot
|-- QUICKSTART.adoc          # CLI quickstart
`-- DEPLOY.adoc              # Deployment status and runbook notes

Data Layer

OikosBot persists analysis results, code-relationship graphs, and the eco/econ knowledge base in a single identity-consonance store, VeriSimDB. In VeriSimDB one identity is an octad of modal witnesses — graph, vector, tensor, semantic, document, temporal, provenance, spatial. The graph + document witnesses take over the role once planned for ArangoDB (code-dependency graphs, analysis history, project metadata), and the semantic witness takes over the role once planned for Virtuoso/RDF (ontology knowledge, proof blobs). The eco/econ ontology seed for the semantic witness lives at databases/ontology/eco.ttl.

VeriSimDB is v0.1.0 and OikosBot’s runtime client is deferred: the data layer is retargeted in design and configuration now (see config/oikos.yaml and ARCHITECTURE.adoc), with runtime wiring tracked on the roadmap. The legacy ArangoDB + Virtuoso assets were retired (recoverable in git history).

Local Checks

cargo build --workspace      # or: just rust-build
cargo test  --workspace      # or: just rust-test
just haskell-build
just haskell-test
just affine-check

The default cargo workspace deliberately excludes crates/oikosbot-fleet (the optional gitbot-fleet bridge) so OikosBot builds standalone. See DISAMBIGUATION.adoc.

just affine-check expects an AffineScript compiler. Override the compiler path with AS_BIN=/path/to/main.exe when needed.

GitHub App

The app manifest lives at .github/app.yml. The setup guide is docs/GITHUB_APP_SETUP.adoc.

Licence

MPL-2.0. See LICENSE.