feat: add contract audit pack#99
Conversation
|
✅ PR size is within recommended limits |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughUpdated the contract documentation to add Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d4a2815c90
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | `health-probe` | API | `chassis/app.py` | GET /v1/health endpoint | | ||
| | `PacketEnvelope` | Data | `engine/packet/packet_envelope.py` | Core immutable message envelope | | ||
| | `DomainSpec` | Data | `engine/config/schema.py` | Full domain pack configuration model | | ||
| | `OutcomeRecord` | Data | `engine/models/outcomes.py` | Match outcome feedback record | |
There was a problem hiding this comment.
The README states that each contract maps to a concrete source file, but this index includes paths that are not present in the repo (for example engine/models/outcomes.py and contracts/contract_*.yaml, with additional missing paths referenced later in the same document). This makes the contract map non-auditable and sends readers to nonexistent code, which undermines the purpose of the contract pack.
Useful? React with 👍 / 👎.
| npx @redocly/cli lint docs/contracts/api/openapi.yaml | ||
| npx @asyncapi/cli validate docs/contracts/events/asyncapi.yaml | ||
| find docs/contracts -name "*.schema.json" | xargs -I{} npx ajv compile -s {} | ||
| pytest tests/contracts/ -m contract -v |
There was a problem hiding this comment.
The documented validation workflow references files/directories that do not exist in this tree (docs/contracts/api/openapi.yaml, docs/contracts/events/asyncapi.yaml, and tests/contracts/). As written, the first command set cannot be executed successfully in this repository, so users cannot reproduce the claimed contract validation process.
Useful? React with 👍 / 👎.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/contracts/README.md`:
- Line 13: The Contracts Index table entry uses `openapi.yaml` without its path
while the validation command expects `docs/contracts/api/openapi.yaml`; update
the table row (the cell containing `openapi.yaml`) to the full path
`docs/contracts/api/openapi.yaml` so the README matches the validation command
and other references; ensure the description and linked file references (the API
column and mention of `chassis/app.py`, `chassis/chassis_app.py`,
`chassis/actions.py`) remain unchanged.
- Line 66: The README contains an incorrect pytest invocation ("pytest
tests/contracts/ -m contract -v"); remove or replace that line and instead
document the actual contract validation steps used by the project: invoke the
static analyzer tools/contract_scanner.py and the verifier
tools/verify_contracts.py (the same commands used by the pre-commit hook) so the
README reflects the real contract validation workflow.
- Line 64: The README validation commands reference missing contract files and
directories (notably docs/contracts/events/asyncapi.yaml,
docs/contracts/api/openapi.yaml and docs/contracts/*.schema.json); either add
the missing contract files and parent directories with valid
AsyncAPI/OpenAPI/JSON Schema content or remove/comment the offending npx
`@asyncapi/cli` validate commands in the README to avoid CI failures—update the
lines referencing docs/contracts/events/asyncapi.yaml,
docs/contracts/api/openapi.yaml and docs/contracts/*.schema.json accordingly so
the commands point to real files or are removed.
- Line 7: The Contracts Index in docs/contracts/README.md omits the "health" and
"healthcheck" actions even though chassis/actions.py registers all eight actions
(match, sync, admin, outcomes, resolve, health, healthcheck, enrich); update the
index block (the list of handlers at lines 20–25) to include "health" and
"healthcheck" so the README matches the action mappings and engine/handlers.py
handler set, preserving the same formatting and ordering used for the other
actions.
- Line 65: The Validation Commands and Contracts Index reference non-existent
files; update docs/contracts/README.md to point to real paths or remove invalid
commands: replace references to docs/contracts/api/openapi.yaml and
docs/contracts/events/asyncapi.yaml with the actual OpenAPI/AsyncAPI file
locations (or remove those lines), and update the AJV command that uses
*.schema.json to target the real schema files (or remove it) — also update the
Contracts Index entry that references contracts/contract_*.yaml to reflect the
true contract file locations or patterns used in the repository (search for
actual contract file names and align the README entries accordingly).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: d96f38c3-a719-4d19-a818-c12bfca63d9a
📒 Files selected for processing (1)
docs/contracts/README.md
|
|
||
| ## Architecture Summary | ||
|
|
||
| CEG is a **domain-agnostic graph-native matching engine** built on a FastAPI chassis + Neo4j 5 Enterprise + Redis 7 stack. It exposes a **single ingress endpoint** (`POST /v1/execute`) that routes 8 named actions to typed handler functions in `engine/handlers.py`. Behavior is entirely driven by **domain spec YAML files** (`domains/*.yaml`) loaded at runtime via `DomainPackLoader`. The system implements seL4-inspired capability-based access control, PacketEnvelope immutability, and a gate-then-score query architecture. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Count the number of handler functions and supported actions
echo "=== Searching for handler functions in engine/handlers.py ==="
rg -n 'def (handle_\w+|.*_handler)\(' engine/handlers.py
echo -e "\n=== Searching for action mappings ==="
# Look for action-to-handler mappings in chassis/actions.py or similar
rg -n -A 5 'action.*map|ACTION.*MAP|handle.*match' chassis/actions.py chassis/app.py
echo -e "\n=== Searching for ExecuteRequest action validation ==="
# Check if there's an enum or list of valid actions
ast-grep --pattern 'class ExecuteRequest'Repository: cryptoxdog/Cognitive.Engine.Graphs
Length of output: 2697
🏁 Script executed:
# Get the complete action mappings dictionary
rg -n -A 10 '"match":' chassis/actions.pyRepository: cryptoxdog/Cognitive.Engine.Graphs
Length of output: 508
🏁 Script executed:
# Check which handlers are registered and exposed
rg -n 'register|register_handler|action.*=' engine/handlers.py | head -20Repository: cryptoxdog/Cognitive.Engine.Graphs
Length of output: 955
Update the Contracts Index to document all 8 supported actions.
The architecture summary correctly states "8 named actions." The action mappings in chassis/actions.py (lines 52–60) confirm all 8 are registered: match, sync, admin, outcomes, resolve, health, healthcheck, and enrich. However, the Contracts Index (lines 20–25) documents only 6 handlers, omitting health and healthcheck. Update the index to include these two actions.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/contracts/README.md` at line 7, The Contracts Index in
docs/contracts/README.md omits the "health" and "healthcheck" actions even
though chassis/actions.py registers all eight actions (match, sync, admin,
outcomes, resolve, health, healthcheck, enrich); update the index block (the
list of handlers at lines 20–25) to include "health" and "healthcheck" so the
README matches the action mappings and engine/handlers.py handler set,
preserving the same formatting and ordering used for the other actions.
|
|
||
| | Contract | Type | Source File | Description | | ||
| |----------|------|-------------|-------------| | ||
| | `openapi.yaml` | API | `chassis/app.py`, `chassis/chassis_app.py`, `chassis/actions.py` | OpenAPI 3.1 spec for all HTTP endpoints | |
There was a problem hiding this comment.
Path inconsistency for openapi.yaml.
The Contracts Index table lists the contract as openapi.yaml without a path prefix, but the validation command on line 63 references it as docs/contracts/api/openapi.yaml. For consistency and clarity, consider including the full path in the table.
📝 Proposed fix for path consistency
-| `openapi.yaml` | API | `chassis/app.py`, `chassis/chassis_app.py`, `chassis/actions.py` | OpenAPI 3.1 spec for all HTTP endpoints |
+| `docs/contracts/api/openapi.yaml` | API | `chassis/app.py`, `chassis/chassis_app.py`, `chassis/actions.py` | OpenAPI 3.1 spec for all HTTP endpoints |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | `openapi.yaml` | API | `chassis/app.py`, `chassis/chassis_app.py`, `chassis/actions.py` | OpenAPI 3.1 spec for all HTTP endpoints | | |
| | `docs/contracts/api/openapi.yaml` | API | `chassis/app.py`, `chassis/chassis_app.py`, `chassis/actions.py` | OpenAPI 3.1 spec for all HTTP endpoints | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/contracts/README.md` at line 13, The Contracts Index table entry uses
`openapi.yaml` without its path while the validation command expects
`docs/contracts/api/openapi.yaml`; update the table row (the cell containing
`openapi.yaml`) to the full path `docs/contracts/api/openapi.yaml` so the README
matches the validation command and other references; ensure the description and
linked file references (the API column and mention of `chassis/app.py`,
`chassis/chassis_app.py`, `chassis/actions.py`) remain unchanged.
|
|
||
| ```bash | ||
| npx @redocly/cli lint docs/contracts/api/openapi.yaml | ||
| npx @asyncapi/cli validate docs/contracts/events/asyncapi.yaml |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Check if asyncapi.yaml exists
echo "=== Searching for asyncapi.yaml ==="
fd -t f 'asyncapi\.yaml' docs/
echo -e "\n=== Checking for any async/event-related documentation ==="
fd -t f -e yaml -e json . docs/contracts/events/ 2>/dev/null || echo "docs/contracts/events/ directory not found"Repository: cryptoxdog/Cognitive.Engine.Graphs
Length of output: 216
🏁 Script executed:
cat -n docs/contracts/README.md | sed -n '60,70p'Repository: cryptoxdog/Cognitive.Engine.Graphs
Length of output: 404
🏁 Script executed:
# Also check if there's an openapi.yaml mentioned on line 63
fd -t f 'openapi\.yaml' docs/contracts/Repository: cryptoxdog/Cognitive.Engine.Graphs
Length of output: 60
🏁 Script executed:
# Check what contracts/directories actually exist
fd -t d . docs/contracts/Repository: cryptoxdog/Cognitive.Engine.Graphs
Length of output: 60
🏁 Script executed:
# Let me check if there's a Contracts Index table earlier in the README
cat docs/contracts/README.md | head -70Repository: cryptoxdog/Cognitive.Engine.Graphs
Length of output: 3725
🏁 Script executed:
# Also check if docs/contracts directory structure exists at all
ls -la docs/contracts/ 2>/dev/null || echo "docs/contracts directory check completed"Repository: cryptoxdog/Cognitive.Engine.Graphs
Length of output: 1632
🏁 Script executed:
# Check if there's any documentation about the structure or if these are placeholders
rg -A 3 -B 3 "Contracts Index" docs/contracts/README.mdRepository: cryptoxdog/Cognitive.Engine.Graphs
Length of output: 719
Line 64 validation command references non-existent asyncapi contract.
The validation command references docs/contracts/events/asyncapi.yaml, but neither the docs/contracts/events/ directory nor the asyncapi.yaml file exist. Similarly, line 63 references docs/contracts/api/openapi.yaml and line 65 references docs/contracts/*.schema.json files, which are also not present in the repository. Either create these contract files and their parent directories, or remove/comment out the incomplete validation commands to prevent CI/CD failures.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/contracts/README.md` at line 64, The README validation commands
reference missing contract files and directories (notably
docs/contracts/events/asyncapi.yaml, docs/contracts/api/openapi.yaml and
docs/contracts/*.schema.json); either add the missing contract files and parent
directories with valid AsyncAPI/OpenAPI/JSON Schema content or remove/comment
the offending npx `@asyncapi/cli` validate commands in the README to avoid CI
failures—update the lines referencing docs/contracts/events/asyncapi.yaml,
docs/contracts/api/openapi.yaml and docs/contracts/*.schema.json accordingly so
the commands point to real files or are removed.
| npx @redocly/cli lint docs/contracts/api/openapi.yaml | ||
| npx @asyncapi/cli validate docs/contracts/events/asyncapi.yaml | ||
| find docs/contracts -name "*.schema.json" | xargs -I{} npx ajv compile -s {} | ||
| pytest tests/contracts/ -m contract -v |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Verify contract tests exist
echo "=== Checking for tests/contracts/ directory ==="
fd -t f -e py . tests/contracts/ 2>/dev/null || echo "tests/contracts/ directory not found"
echo -e "\n=== Searching for pytest markers 'contract' ==="
rg -n '@pytest\.mark\.contract|pytestmark.*contract' tests/Repository: cryptoxdog/Cognitive.Engine.Graphs
Length of output: 211
🏁 Script executed:
# Check the structure of docs/contracts/
find docs/contracts/ -type f | head -20Repository: cryptoxdog/Cognitive.Engine.Graphs
Length of output: 774
🏁 Script executed:
# Get full context around line 66 in docs/contracts/README.md
cat -n docs/contracts/README.md | head -80Repository: cryptoxdog/Cognitive.Engine.Graphs
Length of output: 4194
🏁 Script executed:
# Examine contract_scanner.py to understand how contracts are validated
head -100 tools/contract_scanner.pyRepository: cryptoxdog/Cognitive.Engine.Graphs
Length of output: 2542
🏁 Script executed:
# Check verify_contracts.py
head -100 tools/verify_contracts.pyRepository: cryptoxdog/Cognitive.Engine.Graphs
Length of output: 2635
Remove or replace the pytest contract validation command.
The command at line 66 (pytest tests/contracts/ -m contract -v) references a test infrastructure that does not exist. The repository validates contracts through static analysis (tools/contract_scanner.py) and file verification (tools/verify_contracts.py) instead, not through pytest markers or test files. Either remove this command or replace it with the actual contract validation steps used in the pre-commit hook.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/contracts/README.md` at line 66, The README contains an incorrect pytest
invocation ("pytest tests/contracts/ -m contract -v"); remove or replace that
line and instead document the actual contract validation steps used by the
project: invoke the static analyzer tools/contract_scanner.py and the verifier
tools/verify_contracts.py (the same commands used by the pre-commit hook) so the
README reflects the real contract validation workflow.
PR #99 Review: feat: add contract audit packAuthor: cryptoxdog Descriptionadds contract documentation pack under docs/contracts, includes api spec, env contract, graph schema, and dependency mappings Summary by CodeRabbit
CommitsChanged Files📝 Docs (1 files)
Automated AnalysisDiff Findings✅ No issues found in diff analysis Test CoverageTest coverage looks adequate for changed files. Local LintSkipped (repo not checked out locally or linters not found). Summary✅ LOOKS GOOD — No automated issues found. Ready for human review. Automated PR review • 2026-04-21 18:07 |
cryptoxdog
force-pushed
the
feature/contracts-audit-pack
branch
from
2ceee67 to
1375dc3
Compare
|
2 participants
adds contract documentation pack under docs/contracts, includes api spec, env contract, graph schema, and dependency mappings
Summary by CodeRabbit