sqr 0.0.1

sqr — architecture diagram extraction and AST-only quality metrics (preview / lite subset).

sqr-lite — preview release of the sqr PyPI package

A reduced edition of sqr containing only the AST-driven extractors and analyses. There is no traceability layer, no sphinx-needs integration, no on-target verification, no release machinery — just diagrams and code-quality metrics.

This subdirectory is a side-project of the parent repository. Its purpose is to ship the lite subset to PyPI under the package name sqr while the full edition is still in development. Once the full version stabilises, sqr-lite gets folded back in.

Surface	Name
PyPI distribution	sqr (you pip install sqr)
Python import package	sqr_lite (from sqr_lite import ...)
CLI script	sqr-lite

What's in it

Capability	Subcommand	Backed by
Component diagrams (one per module / composite)	sqr-lite extract static	clang AST
Sequence diagrams (one per behaviour)	sqr-lite extract dynamic	clang AST
Activity diagrams (one per traced function)	sqr-lite extract activity	clang AST
LCOM4 cohesion per module	sqr-lite analyse lcom	clang AST
McCabe V(G) per function	sqr-lite analyse cyclomatic	clang AST
Worst-case stack depth per function	sqr-lite analyse stack	clang .su + AST call graph

Everything except analyse stack runs from the .ast files already produced by your build (clang -emit-ast). analyse stack additionally needs -fstack-usage -fcallgraph-info=su.

Installation

From PyPI (latest release):

pip install sqr-lite
sqr-lite --help

From a local checkout (editable install, picks up source edits):

cd sqr-lite/
poetry install --with dev
poetry run sqr-lite --help

The build uses poetry-dynamic-versioning, so the package version comes from the git tag — install it once as a Poetry plugin:

poetry self add "poetry-dynamic-versioning[plugin]"

Releases

The published version is derived from a git tag of the form vX.Y.Z-lite (e.g. v0.0.1-lite). Pushing such a tag triggers the publish-lite.yml workflow, which builds the wheel + sdist and publishes to PyPI via OIDC trusted publishing. The full sqr edition ships under vX.Y.Z-full tags through a parallel workflow, so the two version streams stay independent.

Configuration

sqr-lite reads [project.sqr] from any .toml file in (or above) the working directory — the same schema the full sqr edition uses. Extra sections (testing, review, release, target, …) are silently ignored, so a project can ship one config that drives both editions.

Minimal example:

[project.sqr]
output = "sqr-out"

[project.sqr.architecture]
build = "build"
source = "src"

[[project.sqr.architecture.behaviour]]
name = "main_loop"
description = "Top-level main loop."
entry_point = "main"
generated = "sqr-out/dynamic/main_loop.puml"

[[project.sqr.architecture.component]]
name = "core.scheduler"
static_generated = "sqr-out/static/scheduler.puml"
activity_generated = "sqr-out/activity/scheduler.puml"
activity_function = "scheduler_tick"

[project.sqr.verification.architecture.lcom]
enabled = true
warning_threshold = 2
error_threshold = 5

[project.sqr.verification.unit.cyclomatic]
enabled = true
warning_threshold = 11
error_threshold = 21

[project.sqr.verification.unit.stack_usage]
enabled = true
budget = 4096
# su_files defaults to [architecture].build (the call graph is
# derived from the loaded ASTs — no separate cgraph input).

The full reference is in docs/source/configuration.md; the same key names apply.

Typical run

# 1. Build with clang so .ast (+ .su if stack analysis) are produced.
cmake --build build/

# 2. Extract diagrams.
sqr-lite extract all

# 3. Run the analyses that are enabled in the config.
sqr-lite analyse all

Each analyse subcommand exits non-zero when any function/module crosses its configured error threshold (or when stack budget is overrun).

Relationship to sqr

sqr-lite is a strict subset of sqr. Its source is copied, not imported from sqr — this lets the two ship as independent distributions. Logic kept in lockstep:

• architecture/{static,dynamic,activity,render,models}.py
• analyses/{lcom,cyclomatic,stack}.py
• utility/ast_loader.py
• utility/config/{loader,schema,architecture}.py (the verification schema is a reduced subset).

When the parent sqr changes one of those files, the sqr-lite copy needs the same change. There is no automatic synchronisation — that's the price of keeping sqr-lite trivially installable on its own.