how to contribute patterns and conventions

Patterns and conventions

Lode keeps the public interface small and JSON-friendly. Most contributors will touch src/lode/indexer.py, src/lode/storage.py, src/lode/graph.py, or src/lode/cli.py, so changes should preserve local-first behavior and stable file/line citations.

Code style

• Use snake_case for functions, variables, and modules.
• Use PascalCase for classes and dataclasses, as seen in src/lode/model.py and src/lode/indexer.py.
• Keep public CLI and daemon output backward compatible unless the change is deliberate.
• Prefer structured JSON responses for agent-facing commands in src/lode/cli.py and src/lode/daemon.py.

Error handling

main() in src/lode/cli.py catches common file, JSON, SQLite, URL, and value errors and returns either plain stderr or JSON error output. LodeHandler.do_POST() in src/lode/daemon.py similarly catches invalid input and storage errors, then returns an {"ok": false, "error": ...} response.

Fact confidence

Parser-emitted facts usually start as strong or heuristic in src/lode/indexer.py. Resolved facts are rebuilt by resolve_graph() in src/lode/graph.py with resolved confidence, and exact IDs are used where the model can make a deterministic relationship.

Security expectations

src/lode/observability.py redacts sensitive field names before logging. Keep source local by default, avoid hosted telemetry, and use .env.example as the template for environment variables.

Related pages

• Development workflow
• Security
• Graph and impact