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.

What's in it

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.