mirror of
https://github.com/microsoft/regorus.git
synced 2026-08-05 02:16:11 +00:00
feat: add copilot instructions, workflows, and architecture docs
Co-authored-by: anakrish <35780660+anakrish@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
committed by
GitHub
GitHub
parent
524aab5528
commit
29acccc407
135
.github/copilot-instructions.md
vendored
Normal file
135
.github/copilot-instructions.md
vendored
Normal file
@@ -0,0 +1,135 @@
|
||||
<!-- Copyright (c) Microsoft Corporation. All rights reserved. -->
|
||||
<!-- Licensed under the MIT License. -->
|
||||
|
||||
# Regorus — Copilot Instructions
|
||||
|
||||
> If these instructions conflict with the actual codebase, the code is the
|
||||
> source of truth. Flag any discrepancy you notice.
|
||||
|
||||
## Identity
|
||||
|
||||
Regorus is a **multi-policy-language evaluation engine** written in Rust. Its
|
||||
primary language is [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/)
|
||||
(Open Policy Agent), with extensible support for additional policy languages via
|
||||
`src/languages/`. It is used in **production at scale** where **correctness is
|
||||
security-critical** — a bug in policy evaluation can mean `allow` when the
|
||||
answer should be `deny`.
|
||||
|
||||
**Key properties:**
|
||||
- 9 language targets: Rust, C, C (no_std), C++, C#, Go, Java, Python, Ruby, WASM
|
||||
- `#![no_std]` by default (`extern crate alloc`), `#![forbid(unsafe_code)]`
|
||||
- Two execution paths: tree-walking interpreter and **RVM** (bytecode VM)
|
||||
- 80+ deny lints in `src/lib.rs` — no panics, no unchecked indexing, no unchecked arithmetic
|
||||
|
||||
**Strategic direction:**
|
||||
- **RVM is the strategic execution path** — new optimization work focuses there
|
||||
- **Isolated / daemon execution** — long-lived process, clean resource lifecycle
|
||||
- **Error migration** — `anyhow` → `thiserror` strongly typed errors (RVM leads)
|
||||
- **Formal verification** — Miri (active CI), Z3 and Verus (planned)
|
||||
- **Multi-policy-language** — extensible via `src/languages/`, don't disclose specifics
|
||||
|
||||
## Deep Knowledge
|
||||
|
||||
For complex subsystems, read the knowledge files in `docs/knowledge/` before
|
||||
making changes. These capture invariants, edge cases, and institutional
|
||||
knowledge that isn't obvious from the code alone:
|
||||
|
||||
| File | Covers |
|
||||
|------|--------|
|
||||
| `value-semantics.md` | Value type, Undefined propagation, three-valued logic |
|
||||
| `rvm-architecture.md` | VM execution modes, frame stack, serialization, register pooling |
|
||||
| `builtin-system.md` | Builtin registration, feature gating, OPA conformance |
|
||||
| `ffi-boundary.md` | Safety across 9 bindings, handles, panic containment, poisoning |
|
||||
| `feature-composition.md` | Feature flag interactions, no_std boundary, testing matrix |
|
||||
| `error-handling-migration.md` | anyhow → thiserror migration strategy, VmError pattern |
|
||||
| `policy-evaluation-security.md` | DoS protection, resource limits, input validation |
|
||||
| `rego-semantics.md` | Evaluation model, undefined propagation, backtracking, `with` |
|
||||
| `interpreter-architecture.md` | Context stack, scope management, rule lifecycle |
|
||||
| `compilation-pipeline.md` | Scheduler, loop hoisting, destructuring planner |
|
||||
| `azure-policy-language.md` | Azure Policy evaluation model, effects, alias normalization |
|
||||
| `azure-rbac-language.md` | RBAC condition interpreter, ABAC builtins, context model |
|
||||
| `engine-api.md` | Public API surface, add_policy → compile → eval flow |
|
||||
| `time-builtins-compat.md` | Go time.Parse compatibility, timezone handling |
|
||||
| `language-extension-guide.md` | Adding new policy languages, LSP/tooling vision |
|
||||
| `tooling-architecture.md` | Language server, linter, analyzer design patterns |
|
||||
| `causality-and-partial-eval.md` | Causality tracking and partial evaluation design |
|
||||
| `rego-compiler.md` | Worklist algorithm, expression codegen, register allocation |
|
||||
| `azure-policy-aliases.md` | Alias registry, ARM normalization/denormalization pipeline |
|
||||
| `telemetry-and-diagnostics.md` | Error traceability, structured diagnostics, cloud-scale telemetry |
|
||||
|
||||
Also see `docs/rvm/architecture.md`, `docs/rvm/instruction-set.md`,
|
||||
`docs/rvm/vm-runtime.md` for RVM internals.
|
||||
|
||||
## Essential Coding Rules
|
||||
|
||||
**No panics — ever** (deny lints enforce this):
|
||||
```rust
|
||||
// Use typed errors for new code
|
||||
let v = map.get("key").ok_or(MyError::MissingKey("key"))?;
|
||||
// Or anyhow in existing modules
|
||||
let v = map.get("key").ok_or_else(|| anyhow!("missing key"))?;
|
||||
```
|
||||
|
||||
**No unchecked indexing** — use `.get()` + `?` or iterate.
|
||||
|
||||
**No unchecked arithmetic** — use `checked_add()`, `saturating_add()`, etc.
|
||||
|
||||
**no_std discipline** — `use core::` and `alloc::` by default. Only `std::`
|
||||
behind `#[cfg(feature = "std")]`.
|
||||
|
||||
**Unsafe forbidden** — `#![forbid(unsafe_code)]` in the core crate. Only FFI
|
||||
binding crates may use unsafe.
|
||||
|
||||
**Error handling** — new modules: `thiserror` enums (see `src/rvm/vm/errors.rs`).
|
||||
Existing modules: `anyhow` is acceptable for consistency within the module.
|
||||
|
||||
**Feature gating** — gate modules, registrations, and public API. Add `docsrs`
|
||||
annotation. Verify non-default combinations compile.
|
||||
|
||||
## Build & Test
|
||||
|
||||
```bash
|
||||
cargo xtask ci-debug # Full debug CI suite
|
||||
cargo xtask ci-release # Full release CI suite (superset)
|
||||
cargo xtask test-all-bindings # All 9 language binding smoke tests
|
||||
cargo xtask test-no-std # Verify no_std builds (thumbv7m-none-eabi)
|
||||
cargo xtask fmt # Format workspace + bindings
|
||||
cargo xtask clippy # Lint workspace + bindings
|
||||
cargo test --test opa # OPA conformance (needs opa-testutil feature)
|
||||
```
|
||||
|
||||
Git hooks auto-installed by `build.rs`: pre-commit (build+format+clippy),
|
||||
pre-push (+ doc tests + no_std + OPA conformance).
|
||||
|
||||
## Repository Layout
|
||||
|
||||
```
|
||||
src/ Core library (no_std, forbid(unsafe_code))
|
||||
rvm/ Rego Virtual Machine ← strategic focus
|
||||
languages/ Policy language extensions
|
||||
builtins/ Builtin functions (~19 modules)
|
||||
value.rs Value type (Null, Bool, Number, String, Array, Set, Object, Undefined)
|
||||
interpreter.rs Tree-walking interpreter (legacy path)
|
||||
engine.rs Public API
|
||||
bindings/ 9 language targets (ffi/, c/, cpp/, csharp/, go/, java/, python/, ruby/, wasm/)
|
||||
tests/ Integration, conformance, domain-specific tests
|
||||
docs/ Grammar, builtins, RVM docs, knowledge base
|
||||
xtask/ Development automation CLI
|
||||
benches/ Criterion benchmarks
|
||||
```
|
||||
|
||||
## Supply Chain Security
|
||||
|
||||
- `dependency-audit.yml` — cargo-audit + cargo-deny across all Cargo.lock files
|
||||
- Dependabot — weekly updates for Cargo, Actions, Maven, NuGet, pip, npm, bundler, Go
|
||||
- All GitHub Actions references use pinned commit SHAs, not mutable tags
|
||||
- `cargo fetch --locked` / `--frozen` in CI for reproducible builds
|
||||
|
||||
## When Making Changes
|
||||
|
||||
1. **Read relevant knowledge files** in `docs/knowledge/` first
|
||||
2. **Consider all 9 binding targets** — API changes affect every language
|
||||
3. **Both execution paths** — features must work in interpreter AND RVM
|
||||
4. **Test Undefined propagation** — `Undefined ≠ false`, test both paths
|
||||
5. **Run `cargo xtask ci-debug`** before submitting
|
||||
6. **Update docs** — `docs/builtins.md`, `docs/rvm/`, knowledge files as needed
|
||||
Reference in New Issue
Block a user