A reduced edition of sqrcontaining 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.
Its purpose is to provide a subset of key tools to validate its functionalities before the full version stabilises.
| Surface | Name |
|---|---|
| PyPI distribution | sqr (you pip install sqr) |
| Python import package | sqr_lite (from sqr_lite import ...) |
| CLI script | sqr-lite |
| 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 (the call graph is derived from
the AST).
All three diagram kinds render to either PlantUML (default) or
Mermaid. Pick the format with diagram_format in the config:
[project.sqr.architecture]
diagram_format = "mermaid" # or "plantuml" (default)or override per run with --format:
sqr-lite extract all --format mermaidThe format changes only the content of the generated files — the
output path is whatever you configure (name your files .mmd for
Mermaid, .puml for PlantUML). Both formats carry the same
information; see the docs for how the two map.
From PyPI (latest release):
pip install sqr
sqr-lite --helpFrom a local checkout (editable install, picks up source edits):
cd sqr-lite/
poetry install --with dev
poetry run sqr-lite --helpThe 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]"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.
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.
# 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 allEach analyse subcommand exits non-zero when any function/module
crosses its configured error threshold (or when stack budget is
overrun).
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}.pyanalyses/{lcom,cyclomatic,stack}.pyutility/ast_loader.pyutility/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.
Apache License 2.0. See LICENSE and NOTICE.
This package was developed interactively with Claude (Anthropic) as a coding and documentation assistant. All output was reviewed and directed by the author.