JAM - JHL Architecture Metrics

Official distribution

Public binaries are published in `jhl-labs/dist`.

The install script downloads the matching Linux/macOS binary and verifies it with SHA256SUMS.

Install latestInstalls to /usr/local/bin/jam by default.

curl -fsSL https://jhl-labs.github.io/jam/install.sh | sudo bash

Pin versionUse this in reproducible CI bootstrap scripts.

curl -fsSL https://jhl-labs.github.io/jam/install.sh | sudo env VERSION=v0.46.0 bash

Quickstart

Run jam-lite by default, then add jam-full evidence when needed.

Static code-health scan

Write report artifacts--strict turns parse failures into exit code 3.

jam lite . --json --sarif --strict --out reports/jam

Full production gate

Compose lite + test + securityRuns external CLIs and writes jam-full.json.

jam full . --out reports/jam-full

Security-only full gate

Compose security evidenceUseful before test evidence is available.

jam full . --component security --out reports/jam-security

Metrics v14.5.0

jam-lite implements all 37 static metrics this CLI can measure alone.

Metrics need a coverage boundary. jam-lite is strong for maintainability signals, but it does not prove correctness, runtime behavior, or production readiness by itself.

What jam-lite can and cannot say

A jam-lite score answers whether the code is structurally healthy enough to keep building on. It does not prove that the code is correct. See Coverage and limitations for the full boundary.

Maintainability High · ARCH/CPLX/DUP/SIZE

Security patterns Partial · obvious risky patterns

Reliability/perf Low · RES/HYG proxy signals

Correctness/UX/compat None · requires runtime/domain evidence

ID	Purpose	Output	Meaning
SIZE-01	Find files too large to review comfortably	Code lines per file	Larger files raise understanding and change cost
SIZE-02	Find overly long functions	Function line span	Review extraction and test boundaries
SIZE-03	Find wide function interfaces	Parameter count	Possible data clump or responsibility overload
SIZE-04	Find files or types with concentrated responsibility	Declaration count, reference concentration, methods/fields	God file/type candidate
CPLX-01	Find functions with many test paths	Cyclomatic complexity	More branches mean higher path risk
CPLX-02	Find control flow that is hard to read	Cognitive complexity	Captures nesting and flow burden
CPLX-03	Find deep indentation	Maximum block depth	Pinpoints readability and review friction
CPLX-04	Find high lexical volume	Halstead Volume	Auxiliary input for maintainability
CPLX-05	Summarize file maintainability	Maintainability Index	Lower values mean harder maintenance
ARCH-01	Find module dependency cycles	Import graph SCC and cycle path	Raises change propagation and build/test cost
ARCH-02	Find tangled files inside one module	File-level symbol reference cycle	Cohesion and file-boundary review signal
ARCH-03	Find over-coupling and unstable dependencies	Ca, Ce, Instability, SDP violation	Core modules may be too fragile
ARCH-04	Find flat structure and orphan internal modules	Directory file count, orphan module	Module-boundary cleanup candidate
ARCH-05	Find hub-like dependency (God Component)	Ca and Ce both distribution outliers + absolute floor	A central bottleneck depended-on and depending-on widely
ARCH-06	Measure change propagation cost	Density of the transitive-dependency (visibility) matrix	How far a small change reaches across the system
ARCH-07	Find low cohesion (LCOM4)	Connected components of state-sharing methods (tree-sitter)	Unrelated responsibilities bundled into one type
ARCH-08	Find deep inheritance (DIT)	Project-internal inheritance chain depth (tree-sitter)	Behavior spread across many ancestors, hard to change
DUP-01	Find copy-paste duplicate blocks	Normalized-token duplication ratio	Risk of missed edits and defect propagation
DUP-02	Find near-duplicate functions	Function token similarity	Review abstraction or intentional divergence
SEC-01	Find hardcoded secrets	High-entropy strings and known token formats	Immediate exposure risk
SEC-02	Find injection-prone string construction	String assembly near risky sinks	SQL/command/HTML injection possibility
SEC-03	Find weak crypto and TLS settings	Weak crypto, random misuse, TLS verify off	Security default violation signal
SEC-04	Find unsafe deserialization and dynamic execution	eval, unsafe YAML/pickle, shell exec sinks	Execution or data-tampering risk
SEC-05	Find sensitive data logging	password/token/secret identifiers in log arguments	Operational log exposure risk
SEC-06	Find DOM XSS	dangerouslySetInnerHTML/innerHTML= etc. with non-literals (JS/TS)	Unsanitized value entering the DOM (XSS path)
SEC-07	Find path traversal	File sink + user input, intra-procedural taint tracking	Directory escape to arbitrary file access
SEC-08	Find SSRF	HTTP client + user input, taint tracking	Server coerced into requesting arbitrary internal hosts
RES-01	Find missing resource release	open/malloc/new/acquire and close/free pairs	File, memory, or handle leak possibility
RES-02	Find unbounded concurrency	Looped goroutine/thread/promise spawn	Runaway work, queue growth, failure amplification
RES-03	Find mutable global state	Module/package-level mutable globals	Hurts test isolation and concurrency safety
HYG-01	Find swallowed exceptions and ignored errors	empty catch/except, ignored error	Failure causes can be hidden
HYG-02	Find dead code	Unreferenced private symbols, unreachable statements	Maintenance noise and stale paths
HYG-03	Find abandoned TODO/FIXME markers	SATD comment count and density	Explicit technical debt accumulation
HYG-04	Find magic literal density	Numeric/string literals per KLOC	Unexplained policy values and duplicated constants
HYG-05	Find comment-density outliers	comment/CLOC, public API doc missing ratio	Documentation gap or comment overload
HYG-06	Find test absence signals	Test file ratio, directories without tests	Not coverage; test-cli should add evidence
HYG-07	Find parse failures that reduce analysis trust	parser error file:line:column	`--strict` exits with code 3

JAM Full

jam-full is the production gate that calls test-cli and security-cli.

jam-lite measures static code health, test-cli supplies test and coverage evidence, and security-cli supplies SAST/SCA/secret evidence. JAM composes those results into one score and explicit failure reasons.

Composite score jam-full = weighted evidence

50% jam-lite 25% test 25% security

Partial runs renormalize the selected default weights to 1.0.

50%

jam-lite

Runs this CLI alone. Covers static debt, strict parse failures, SARIF, CSV, and JSON.

25%

test-cli

Separates test failures, low coverage, and missing test evidence as quality failures.

25%

security-cli

Composes critical/high findings, secrets, SCA, and policy failures into the security score.

partial fullcomponent orchestration

jam full . --out reports/jam-full
jam full . --component security --out reports/jam-security
jam full . --component test --out reports/jam-test

Security assurance

Keep scanner candidates, vulnerability decisions, and compliance evidence distinct.

A central policy and commit-bound review ledger produce a security verdict. A separate control plan links hash-pinned evidence to framework controls without claiming certification or legal compliance.

security verdict + control evidencepass · fail · incomplete

jam assurance verdict --input reports/jam --policy security-policy.json --review security-review.json --gate
jam assurance evidence --plan control-plan.json --out reports/audit --gate

OverviewInstall, commands, outputs, exit codes MetricsCategories, scoring, spec version Lite / FullExternal orchestration and composite score CI/CDPR gates, SARIF upload, release gate E2E evaluationSample corpus and full evaluation results Security assuranceAdjudication, evidence mapping, and compliance boundary Full referenceRendered Korean source documents

Public binaries are published in jhl-labs/dist.