mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
Renn F
17ec52d1b7
Harden the architectural-conventions standard so it works out-of-the-box on any project and resolves for projects that predate it, and make RoboCo pass its own gate. General defaults (apply to every project, not just one with a tuned file): - The auto-scan excludes test and documentation trees (tests/, docs/) — those legitimately define fixtures and aren't enforced code. - Helper placement seeds at warn, not block: `helper` matches any top-level function, too blunt a signal to hard-block a route file's small private glue. Misplaced model/route/component stay block; the body-level thin_routes check remains the real fat-handler guard. - thin_routes no longer counts transaction-lifecycle calls (commit/flush/ refresh) as data access — an explicit `db.commit()` after delegating to a service is a valid pattern. - no_lint_suppressions exempts a small allowlist of structurally-unavoidable framework codes (ruff TC001-TC003, pydantic prop-decorator); bare or other suppressions still flag. - CLAUDE.md rule-lifting skips bare common-word tokens that would match everywhere (e.g. "commit"), keeping only specific identifiers. - The ambient prompt block lists only constrained modules and truncates at a line boundary with a "+N more" pointer instead of cutting mid-line. Backfill: the standard previously read the committed file + repo scan from project.workspace_path, a field only a manual API call set — so an older project (or one whose workspace was cleared) showed an empty "missing" map no matter what was pushed. The service now ensures a dedicated, default-branch read clone on demand (WorkspaceService.ensure_read_clone) and resolves from it, persisting the resolved path + real HEAD. The panel tab, the spawn-time ambient block, and the per-task constraints all resolve the committed standard with no manual setup. Adopt in-repo: relocate the inline request/response models from the system and *_live route modules into roboco/api/schemas/ so the codebase passes its own placement gate, and ship a canonical .roboco/conventions.yml. no_models_in_routes and modular_cohesion are now clean and enforced at block. Docs updated across the user guide, the agent-facing RAG standard, the developer and pr_reviewer role prompts, CLAUDE.md, and the changelog. New unit tests cover the scan exclusions, helper-warn, the suppression allowlist, the commit exemption, and the resolve/backfill path; the conventions + project integration suites pass against Postgres.
103 lines
3.4 KiB
YAML
103 lines
3.4 KiB
YAML
# Architectural conventions for RoboCo.
|
|
#
|
|
# This file overlays the auto-derived scan: every consumer (the validator, the
|
|
# per-task constraints, the spawn-time ambient block) reads the merged effective
|
|
# map, so only project-specific divergences need to live here. The scan already
|
|
# excludes tests/ and docs/, maps the backend (roboco/) + frontend (panel/)
|
|
# layers, and defaults misplaced-helper to warn — so this file is mostly a small
|
|
# set of module declarations plus the rule-level policy below.
|
|
#
|
|
# Posture: BLOCK every boundary the codebase already honors (a model or helper
|
|
# in a route, a route in a service, a model/route in a panel component, a hook
|
|
# returning JSX — all refused), WARN the boundaries that still carry debt so a
|
|
# task is never stranded on pre-existing code.
|
|
|
|
version: 1
|
|
languages:
|
|
- python
|
|
- typescript
|
|
|
|
modules:
|
|
# --- Backend: roboco/ --------------------------------------------------------
|
|
- path: roboco/models
|
|
purpose: SQLAlchemy + Pydantic data models
|
|
forbidden:
|
|
- route
|
|
- path: roboco/api
|
|
purpose: API package wiring — app, deps, middleware, websocket
|
|
forbidden:
|
|
- model
|
|
- path: roboco/api/routes
|
|
purpose: HTTP routes — thin handlers that delegate to services
|
|
forbidden:
|
|
- model
|
|
- helper
|
|
- path: roboco/api/schemas
|
|
purpose: API request / response schemas
|
|
forbidden:
|
|
- route
|
|
- path: roboco/mcp/schemas
|
|
purpose: MCP tool input / output schemas
|
|
forbidden:
|
|
- route
|
|
- path: roboco/services
|
|
purpose: business logic, DB writes, side effects — the only layer that owns them
|
|
forbidden:
|
|
- route
|
|
- path: roboco/utils
|
|
purpose: shared, side-effect-free helpers
|
|
forbidden:
|
|
- route
|
|
- component
|
|
|
|
# --- Frontend: panel/ --------------------------------------------------------
|
|
- path: panel/src/components
|
|
purpose: presentational UI components
|
|
forbidden:
|
|
- model
|
|
- route
|
|
- path: panel/src/hooks
|
|
purpose: React hooks — data fetching + state, no JSX
|
|
forbidden:
|
|
- component
|
|
- model
|
|
- route
|
|
- path: panel/src/store
|
|
purpose: client-side state management
|
|
forbidden:
|
|
- component
|
|
- route
|
|
- path: panel/src/lib/api
|
|
purpose: typed API client
|
|
forbidden:
|
|
- model
|
|
- path: panel/src/lib
|
|
purpose: shared frontend helpers / utilities
|
|
forbidden:
|
|
- route
|
|
- component
|
|
|
|
rules:
|
|
# Comments are welcome in RoboCo — intent is documented in-code and in
|
|
# docstrings. The rule only nudges (full-line comments are never flagged).
|
|
no_inline_comments:
|
|
level: warn
|
|
# A handful of unavoidable framework suppressions are auto-allowed
|
|
# (TC001-003, pydantic prop-decorator); the few remaining inline E402 / E501 /
|
|
# arg-type suppressions stay warn until they migrate to pyproject config.
|
|
no_lint_suppressions:
|
|
level: warn
|
|
# RoboCo routes deliberately call db.commit() (get_db auto-commit is unreliable
|
|
# under BaseHTTPMiddleware); explicit commits no longer count as data access,
|
|
# so this stays advisory for the few routes that still read/write directly.
|
|
thin_routes:
|
|
level: warn
|
|
# A few panel components still fetch inline; extract into hooks, then promote.
|
|
thin_components:
|
|
level: warn
|
|
# Everything else inherits the derived BLOCK level — no models/helpers in
|
|
# routes, no routes in services, no models/routes in panel components, etc.
|
|
|
|
custom: []
|
|
waivers: []
|