Revos: Architecture Checks for AI-Generated Code

Notifications You must be signed in to change notification settings

Fork 0

Star 0

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

47 Commits

47 Commits

.github/workflows

.github/workflows

.revos

.revos

apps/cli

apps/cli

docs

docs

examples

examples

packages

packages

.gitignore

.gitignore

LICENSE

LICENSE

README.md

README.md

package.json

package.json

pnpm-lock.yaml

pnpm-lock.yaml

pnpm-workspace.yaml

pnpm-workspace.yaml

tsconfig.base.json

tsconfig.base.json

Repository files navigation

Architecture governance for AI-assisted software development.

Revos scans a codebase, builds a dependency graph, detects architecture violations, explains what went wrong, and suggests possible fixes.

It is designed for teams using AI coding tools, where code can compile and tests can pass while the architecture slowly drifts.

Install

Run Revos without installing it globally:

npx @revoscli/cli scan https://github.com/fastapi/fastapi --report all

Or install it globally:

npm install -g @revoscli/cli revos --help

The npm package is:

@revoscli/cli

The installed command is:

revos

Quick start

Scan a local project:

revos scan .

Scan a public GitHub repository:

revos scan https://github.com/user/repo --report all

Scan a subdirectory inside a repository:

revos scan https://github.com/user/repo --subdir backend --report all

Initialize Revos in a project:

revos init . --auto --force

Or choose a preset manually:

revos init . --preset default --force revos init . --preset clean-architecture --force revos init . --preset nextjs --force revos init . --preset nestjs --force revos init . --preset laravel --force revos init . --preset laravel-clean-architecture --force revos init . --preset fastapi --force

Why Revos exists

Modern teams can generate code very quickly.

The problem is that working code is not always well-structured code.

A project can compile, tests can pass, and the product can still slowly develop architecture problems such as:

UI components importing database clients.

Domain code depending on frameworks.

Controllers accessing repositories or databases directly.

Client code importing server-only modules.

Circular dependencies.

Modules importing internal details from other modules.

Application or domain layers depending on infrastructure.

Revos helps catch these problems early.

It is not a replacement for mature static analyzers. It is an architecture guardrail for the AI era: fast scans, framework presets, readable reports, CI-friendly output, and practical suggestions.

Example output

Scanning project: https://github.com/fastapi/fastapi Detected plugins: python Detected frameworks: fastapi Found 1119 source files

Dependency Graph Nodes: 1021 Edges: 3388

Architecture Issues

[HIGH] Circular dependency detected Type: circular-dependency

Files:

• fastapi/utils.py
• fastapi/routing.py
• fastapi/utils.py

Problem: Two or more files depend on each other. This makes the architecture harder to maintain and can create runtime bugs.

Suggested fix: Extract the shared logic into a separate file or module, then make both files depend on that shared abstraction instead of depending on each other.

Summary Files scanned: 1119 Detected plugins: python Dependencies: 3388 Issues found: 6 High: 6 Medium: 0 Low: 0

What Revos checks

Revos currently supports:

Project scanning from local paths.

Public GitHub repository scanning.

Subdirectory scanning with --subdir.

Dependency graph generation.

Circular dependency detection.

Forbidden import rules.

Framework-aware presets.

Rule-level ignores.

Targeted issue ignores.

Issue deduplication.

Markdown reports.

JSON reports.

CI failure with --fail-on.

Supported stacks

Currently supported:

TypeScript

TSX

React

Next.js

NestJS

Express detection

Laravel / PHP

Laravel Clean Architecture

Python

FastAPI

Django detection

Flask detection

Reports

Generate a Markdown report:

revos scan . --report markdown

Generate a JSON report:

revos scan . --report json

Generate both:

revos scan . --report all

Local project reports are written to:

.revos/report.md .revos/report.json

For GitHub repository scans, reports are copied to the current working directory by default:

revos-report.md revos-report.json

Choose a custom output directory:

revos scan https://github.com/user/repo --report all --output ./reports

CI usage

Fail CI when high severity issues are found:

revos scan . --report all --fail-on high

Example GitHub Actions workflow:

name: Revos

on: pull_request: push: branches:

• main

jobs: revos: name: Architecture checks runs-on: ubuntu-latest

steps:

• name: Checkout repository

uses: actions/checkout@v4

• name: Setup Node.js

uses: actions/setup-node@v4 with: node-version: 20

• name: Install Revos

run: npm install -g @revoscli/cli

• name: Initialize Revos config if missing

run: | if [ ! -f ".revos/rules.json" ]; then revos init . --auto fi

• name: Run Revos

run: revos scan . --report all --fail-on high

• name: Upload Revos reports

if: always() uses: actions/upload-artifact@v4 with: name: revos-reports path: | .revos/report.md .revos/report.json

A sample workflow is available here:

examples/github-actions/revos.yml

Configuration

Revos uses a project-level configuration file:

.revos/rules.json

Example:

{ "forbiddenImports": [ { "id": "domain-no-fastapi", "from": "/domain/", "to": "[external] fastapi", "severity": "high", "title": "Domain depends on FastAPI", "message": "Domain code should not depend on FastAPI.", "suggestedFix": "Move FastAPI-specific code into API routes or adapters." } ] }

Supported severities:

low medium high

Read more:

docs/configuration.md

docs/presets.md

docs/plugins.md

Presets

Available presets:

default clean-architecture nextjs nestjs laravel laravel-clean-architecture fastapi

Use a preset:

revos init . --preset nextjs --force

Auto-detect a suitable preset:

revos init . --auto --force

Language support

TypeScript / Next.js / NestJS

The TypeScript plugin supports:

.ts

.tsx

static imports

side-effect imports

export from

dynamic imports

relative imports

tsconfig.json aliases

framework detection from nested package.json files

Detected frameworks include:

Next.js

React

NestJS

Express

Laravel / PHP

The Laravel plugin supports:

.php

use imports

aliased imports

grouped imports

fully-qualified class references

static class references

short class references resolved through use

Composer PSR-4 mappings

Laravel fallback mappings

Laravel detection

Laravel Clean Architecture detection

Read more:

docs/laravel.md

Python / FastAPI

The Python plugin supports:

.py

standard imports

from imports

alias imports

relative imports

root layout

src/ layout

package init.py

FastAPI detection

Django detection

Flask detection

FastAPI preset

Read more:

docs/python.md

Development

Install dependencies:

pnpm install

Run tests:

pnpm test

Build the CLI:

pnpm --filter @revoscli/cli build

Run the CLI locally:

pnpm --filter @revoscli/cli dev scan .

Run a local scan with reports:

pnpm --filter @revoscli/cli dev scan . --report all

Monorepo structure

revos/ apps/ cli/

packages/ core/ plugin-typescript/ plugin-laravel/ plugin-python/

docs/ examples/ .github/

Status

Revos is currently an early alpha / serious technical MVP.

It is useful for:

detecting common architecture drift;

keeping framework boundaries clean;

making CI fail on serious architecture issues;

helping teams review generated code;

explaining architecture problems clearly.

Revos should not yet be described as:

production-ready enterprise software;

a complete replacement for mature static analyzers;

a tool that covers every language or framework edge case.

Current positioning:

Early alpha architecture governance CLI for AI-era codebases.

Roadmap

Near-term ideas:

SARIF output for GitHub Code Scanning.

Better monorepo visualization.

Improved false-positive filtering.

More framework presets.

HTML reports.

More real-world repository benchmarks.

License

MIT.

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks

Report repository

Releases

1 tags

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

TypeScript 100.0%