The Gap in v0.1.0

When I shipped ArchDogma v0.1.0 two days ago, the tool already had 11 Tier 1 detectors and 281 tests. It could analyze a Python file for architectural anti-patterns and tell you exactly which function had what problem. That's useful — but it assumed you already knew which file to look at.

Real codebases aren't one file. Real audits start with "where is the rot?" not "is this specific function rotting?" The v0.1.0 probe was a scalpel. What was missing was the x-ray.

v0.2.0 ships the x-ray: archdogma scan.

What scan Does

Update: 

pip install --upgrade archdogma

Then point it at your project: 

archdogma scan .
archdogma scan src/
archdogma scan /path/to/repo

It walks every .py file under the target directory, runs all 11 Tier 1 detectors on every function and class it finds, and reports every tag with file:line context. Not just "this file has problems" — exactly where and what.

The default output is plain text, screen-reader friendly, no color gimmicks: 

src/api/routes.py:47  [high]       broad-except
src/api/routes.py:112 [medium]     magic-numbers
src/models/user.py:23 [high]       mutable-default-arg
src/models/user.py:89 [high]       god-class
src/utils/cache.py:15 [medium]     if-on-parameter

5 tags across 3 files (14 files scanned)

Flags That Matter

--summary

Shows aggregate counts by detector, not the full list. Useful when you want to know "how many magic-numbers violations exist across the project" without scrolling through every one of them. 

archdogma scan src/ --summary
broad-except        3
magic-numbers       8
mutable-default-arg 2
god-class           1
if-on-parameter     4

Total: 18 tags across 42 files (42 files scanned)

--format json

JSON output for pipeline integration. The structure is explicit: 

archdogma scan src/ --format json
{
  "scan_root": "/absolute/path/to/src",
  "files_scanned": 42,
  "files_with_tags": 7,
  "total_tags": 18,
  "items": [
    {
      "file": "src/api/routes.py",
      "line": 47,
      "tag": "broad-except",
      "severity": "high",
      "detail": "bare except clause catches all exceptions"
    },
    ...
  ]
}

Pipe it into jq to filter by severity, by file, or count by detector. Works with any CI log parser that understands JSON.

--exclude PATTERN

Skip files matching a glob pattern. Repeatable. Useful for generated code, migrations, or test fixtures you don't want in the report: 

archdogma scan . --exclude "*/migrations/*" --exclude "*/tests/*"

--fail / --no-fail

Controls exit code. With --fail (the default), the process exits 1 if any tags are found. With --no-fail, it always exits 0 — useful when you want the report without breaking the build.

Add it to CI in one line: 

# .github/workflows/arch.yml
- name: ArchDogma scan
  run: archdogma scan src/ --format json --fail | tee arch-report.json

The god-class Fix

v0.2.0 also fixes a bug in the god-class detector that would cause it to crash when analyzing files with multiple class definitions. The detector now accepts an optional classes_in_file argument — the same interface used by the deep-inheritance detector's probe_class walker.

This wasn't caught before because the unit tests for god-class used single-class fixtures. The scan command, which processes entire files, hit the multi-class case immediately. Classic integration surface bug.

300 Tests

v0.1.0 shipped with 281 tests. v0.2.0 adds 19 more in tests/test_scan.py, bringing the total to 300. All passing.

The new tests cover: empty directories, directories with no Python files, files with syntax errors (scan skips and reports, doesn't crash), --exclude pattern matching edge cases, JSON output schema validation, --summary aggregation correctness, and exit code behavior for both --fail and --no-fail.

The 300-test milestone matters less than the coverage it represents. Every flag has tests for its happy path and its edge cases. Every output format is schema-validated. The scanner doesn't make silent assumptions about the filesystem.

What Scan Changes About the Tool

v0.1.0 was useful for auditing a specific file you were already working on. You had to bring the context — the file path, the function name. The tool was an amplifier for human intuition, not a replacement for it.

archdogma scan changes the use case. You can now run it as a pre-commit hook, as part of CI, or as the first thing you do when onboarding to an unfamiliar codebase. You don't need to already know where to look.

The output is designed to be actionable without being overwhelming. It doesn't give you a single score. It gives you a list of locations with severity labels — high-severity items first, one per line, one problem per tag. You can triage, assign, or ignore. The tool doesn't decide priorities for you.

Honest Limits

archdogma scan is still Tier 1 only: AST-based detectors that look at structure without running the code. It won't find runtime bugs, performance problems, or issues that only manifest at scale. It catches structural patterns that tend to correlate with problems — it can't prove causation.

Files with syntax errors are skipped with a notice, not crashed on. Files that are valid Python but not actually your application code (auto-generated stubs, conftest.py with unusual shapes) might produce noise. Use --exclude for those.

The tool is honest about absence: if no tags are found, it says so explicitly. "0 tags across 42 files" is a result, not silence.

Where This Goes Next

The next planned feature is import graph analysis — detecting circular import chains at the project level, not just file by file. This requires a different traversal than the current AST walker and is tracked separately.

After that: better catalog coverage. The dogma catalog currently has full post-mortem coverage for DRY, TDD, and microservices-for-everything. The remaining entries are honest drafts — marked [NEED POSTMORTEMS]. That work is ongoing.

v0.2.0 is the point where ArchDogma stops being a single-file probe and starts being a project auditor. It's on PyPI now.

Links