.\" sqc - Software Code Quality
.\" Man page for sqc(1)
.TH SQC 1 "June 2026" "sqc 0.4.13" "User Commands"
.SH NAME
sqc \- CERT C compliance checker for C source code
.SH SYNOPSIS
.B sqc
[\fIOPTIONS\fR] [\fIPATH\fR]
.SH DESCRIPTION
.B sqc
(Software Code Quality) is a static analysis tool that checks C source code
for violations of the SEI CERT C Coding Standard. It performs AST-based,
control-flow, dataflow, and inter-procedural analysis to detect defects
including null pointer dereferences, integer overflows, buffer overflows,
use-after-free, and resource leaks.
.PP
If \fIPATH\fR is omitted, the current directory is analyzed.
\fIPATH\fR may be a single C source file, a directory (analyzed recursively),
or a git repository (with \fB\-\-diff\fR to analyze only changed files).
.SH OPTIONS
.SS "Input & Configuration"
.TP
\fB\-m\fR, \fB\-\-manifest\fR \fIFILE\fR
Path to the rules manifest file (TOML format). The manifest controls which
rules are enabled and their severity levels. Default:
.IR rules_templates/rules\-all.toml .
.TP
\fB\-d\fR, \fB\-\-directories\fR \fIDIR\fR
Additional directories to pre-scan for function definitions, providing
cross-file context for inter-procedural analysis. May be specified multiple
times. For best results, include all source directories in the project.
.TP
\fB\-I\fR, \fB\-\-include\-path\fR \fIDIR\fR
Include search paths for resolving \fB#include\fR directives, analogous to the
compiler \fB\-I\fR flag. May be specified multiple times.
.TP
\fB\-\-suppress\-file\fR \fIFILE\fR
Path to a
.I .sqc\-suppress.toml
suppression file. If not specified, sqc auto-detects a suppression file in
the project root. The file supports \fB[[suppression]]\fR entries (by hash) and
\fB[[wildcard]]\fR entries (by glob or prefix pattern).
.SS "Output & Reporting"
.TP
\fB\-e\fR, \fB\-\-export\fR \fIFILE\fR
Export violations to a file. The output format is determined by the file
extension:
.RS
.TP
.B .csv
Comma-separated values
.TP
.B .json
JSON array of violation objects
.TP
.B .xlsx
Excel workbook with formatted columns and severity coloring
.TP
.B .sarif\fR, \fB.sarif.json
SARIF v2.1.0 for IDE and CI/CD integration
.RE
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Increase output verbosity. May be specified multiple times:
.B \-v
shows per-rule progress;
.B \-vv
shows per-violation detail.
.SS "Analysis Modes"
.TP
\fB\-i\fR, \fB\-\-interactive\fR
Run in interactive terminal UI mode with keyboard navigation, filtering,
and inline code preview. Conflicts with \fB\-\-export\fR and
\fB\-\-generate\-suppression\fR.
.TP
\fB\-\-diff\fR
Only analyze C files that are modified or new according to
.BR git\-diff (1).
Requires the target path to be inside a git repository.
.TP
\fB\-\-generate\-suppression\fR \fIFILE\fR:\fILINE\fR:\fIRULE\fR
Generate a suppression comment for the specified violation. Output is printed
to stdout. Conflicts with \fB\-\-interactive\fR and \fB\-\-export\fR.
.SS "Filtering"
.TP
\fB\-\-min\-severity\fR \fILEVEL\fR
Only report violations at or above this severity level.
\fILEVEL\fR is one of: \fBLow\fR, \fBMedium\fR, \fBHigh\fR, \fBCritical\fR.
.TP
\fB\-\-rules\fR \fIRULE1\fR,\fIRULE2\fR,...
Only report violations from the specified rules. Comma-separated list of
CERT C rule identifiers (e.g., \fBARR30\-C,MEM31\-C,STR32\-C\fR).
.SS "Exit Code Control"
.TP
\fB\-\-fail\-on\-violation\fR
Exit with code 1 if any violations are found.
.TP
\fB\-\-fail\-on\-severity\fR \fILEVEL\fR
Exit with code 1 if any violation meets or exceeds the specified severity.
\fILEVEL\fR is one of: \fBLow\fR, \fBMedium\fR, \fBHigh\fR, \fBCritical\fR.
.SS "Performance & Parallelism"
.TP
\fB\-j\fR, \fB\-\-jobs\fR \fIN\fR
Number of parallel analysis threads. \fB0\fR (default) auto-detects the
number of CPU cores. \fB1\fR forces sequential single-threaded analysis.
Each thread gets its own parser and rule registry; cross-file context is
shared read-only via \fB\-d\fR prescan data.
.TP
\fB\-\-save\-prescan\fR \fIFILE\fR
Save pre-scan context (function summaries, macro aliases, type information)
to a binary cache file. Useful for CI/CD workflows where prescan data can
be computed once and reused across runs.
.TP
\fB\-\-load\-prescan\fR \fIFILE\fR
Load pre-scan context from a cache file instead of scanning \fB\-d\fR
directories. The cache must have been generated by a prior
\fB\-\-save\-prescan\fR invocation.
.SS "Metadata"
.TP
\fB\-h\fR, \fB\-\-help\fR
Print help message and exit.
.TP
\fB\-V\fR, \fB\-\-version\fR
Print version information and exit.
.SH EXIT STATUS
.TP
.B 0
Success. No violations found, or no violations meeting the failure threshold.
.TP
.B 1
Violations found and \fB\-\-fail\-on\-violation\fR or \fB\-\-fail\-on\-severity\fR
was set.
.TP
.B 2
Analysis error (invalid path, bad manifest, parse failure).
.SH CONFIGURATION
.SS "Rules Manifest"
The rules manifest is a TOML file that controls which rules are enabled.
Each rule has a section with \fBenabled\fR and \fBseverity\fR fields:
.PP
.RS
.nf
[ARR30-C]
enabled = true
severity = "High"
[MEM31-C]
enabled = true
severity = "Critical"
.fi
.RE
.PP
A default manifest enabling all rules is provided at
.IR rules_templates/rules\-all.toml .
.SS "Suppression File"
The suppression file
.RI ( .sqc\-suppress.toml )
allows silencing specific violations:
.PP
.RS
.nf
# Suppress by hash (from --generate-suppression)
[[suppression]]
hash = "a1b2c3d4e5f6"
reason = "Intentional cast"
# Suppress by pattern
[[wildcard]]
rule = "DCL06-C"
file_glob = "third_party/**"
reason = "External code"
.fi
.RE
.SH EXAMPLES
Analyze a project directory:
.PP
.RS
.nf
sqc /path/to/project
.fi
.RE
.PP
Analyze with cross-file context and include paths:
.PP
.RS
.nf
sqc -d src/ -d lib/ -I include/ src/
.fi
.RE
.PP
Export results as SARIF for CI integration:
.PP
.RS
.nf
sqc --diff --min-severity Medium \\
--fail-on-severity High \\
--export results.sarif .
.fi
.RE
.PP
Interactive mode:
.PP
.RS
.nf
sqc -i /path/to/project
.fi
.RE
.PP
Filter to specific rules:
.PP
.RS
.nf
sqc --rules ARR30-C,MEM31-C,EXP34-C src/
.fi
.RE
.PP
Generate a suppression for a specific finding:
.PP
.RS
.nf
sqc --generate-suppression src/main.c:42:ARR30-C .
.fi
.RE
.PP
Parallel analysis using 8 threads:
.PP
.RS
.nf
sqc -j 8 -d src/ -d lib/ src/
.fi
.RE
.SH FILES
.TP
.I rules_templates/rules\-all.toml
Default rules manifest enabling all CERT C rules.
.TP
.I .sqc\-suppress.toml
Project-level suppression file (auto-detected in project root).
.SH SEE ALSO
.BR cppcheck (1),
.BR clang\-tidy (1),
.BR gcc (1)
.PP
SEI CERT C Coding Standard:
.UR https://wiki.sei.cmu.edu/confluence/display/c
.UE
.SH AUTHORS
Eric Buehler <eric.buehler@bissell.com>
.br
Brandon Arrendondo <brandon.arrendondo@bissell.com>
.SH COPYRIGHT
Copyright \(co 2024 BISSELL Homecare, Inc.
.br
Source code licensed under the Apache License, Version 2.0.
.br
Documentation licensed under CC BY 4.0.