Skip to content
TsukiNi22Public

About

xstyle: checker and fixer of my coding style (C++20 / libutils first, Python, shell, Rust, CMake, generic rules), auto fixes, --rtk output for AI, RPM / DEB / Arch packages

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

xstyle

Tip

Documentation TsukiNi22/xstyle (v1.2.0): user guide, concepts, every option and rule (searchable, EN / FR) and the interactive project graph.

Checker and fixer of my coding style, C++ first (cpp-style, cpp-comments, cpp-class layout, libutils usage), then C, assembly (NASM x86-64), Python, shell, Rust and the generic rules of every language. Each issue is printed with its file, line and column (terminal hyperlink), the rule broken and the fix proposed; a summary counts the issues by severity (unforgivable, major, minor, negligible) and by rule, plus one mandatory reminder that is never counted (R34). Everything that can be fixed safely is fixed with --fix, for every rule or only some codes, files or directories.

Moved out of ai-utils (style/xstyle, history kept) into its own repository: RPM / DEB / Arch (pacman) packages on the gh-pages branch, also listed in my-universe with the other packages of TsukiNi22.

Table of Contents

Dependencies

Caution

The MIT license of this project (LICENSE) only applies to the code of xstyle itself, not to its dependencies.

Name + Link Status Last Update
libutils CD - Dispatch
Name Version Fedora (dnf) Debian/Ubuntu (apt) Arch (pacman)
clang++ / cmake C++20 / >= 3.20 clang cmake clang cmake clang cmake
libutils 4.x (>= 4.1.0, >= 4.2.0 on Arch) libutils libutils libutils
GoogleTest (tests only) any gtest-devel libgtest-dev gtest
ccache [OPTIONAL] any ccache ccache ccache

Note

The libutils checks read the installed headers: /usr/include, /usr/local/include, ~/.local/include, CPATH, else its Windows build (the MinGW sysroot of the mingw64-libutils packages, or a source build of libutils.sh windows). xstyle --libutils-check compares them with the reference of the libutils skill of ai-utils ($XSTYLE_LIBUTILS_SKILL, else ~/.claude/skills/libutils, else ~/personal_delivery/other/ai-utils/libutils/libutils).

Packages

Note

Every package has a pre-release/unstable version named <package_name>-pre. The -pre packages are marked as obsolete by any release/stable package (without -pre) of the same version or higher.

The same packages exist as RPM (Fedora), DEB (Debian/Ubuntu) and Arch Linux (pacman, .pkg.tar.zst): same names, content and dependencies.

File Name Content
xstyle Install the default package (xstyle-op)
xstyle-op Executable compiled with the optimization options
xstyle-db Executable compiled with the debug options (intended for debugging only)
xstyle-as Executable compiled with the asan options (intended for debugging only)

Warning

The three variants install the same /usr/bin/xstyle: only one of them can be installed at a time.

Every package also installs the completion of the shells (flags, rule codes, severities, languages, comma lists), generated by xstyle --completion bash|zsh|fish:

Shell File Loaded
bash /usr/share/bash-completion/completions/xstyle on demand by bash-completion
zsh /usr/share/zsh/site-functions/_xstyle new shells (compinit)
fish /usr/share/fish/vendor_completions.d/xstyle.fish on demand

Quick Setup - 1 (all)

Setup into /usr/local (or ~/.local)

Clone the repository

git clone https://github.com/TsukiNi22/xstyle.git
cd xstyle

Build & install

export BUILD_DIR=build
cmake -S . -B $BUILD_DIR -DCMAKE_BUILD_TYPE=Optimized
cmake --build $BUILD_DIR --parallel $(nproc)                       # ./xstyle at the root + build/completion/
sudo cmake --build $BUILD_DIR --target install --parallel $(nproc) # /usr/local/bin/xstyle + the completions
cmake --install $BUILD_DIR --prefix ~/.local                       # or without root: ~/.local/bin/xstyle

Quick Setup - 2 (Limited)

Setup into /usr

Warning

If during the installation using tools like dnf, apt... you see an invalid hash error, reset the cache of the tool or relaunch the setup.sh script.

If the error still persists, it might be due to an error in the repository.

Warning

Restriction: fedora-based (rpm), debian-based (deb), arch-based (pacman)

Note

The usage of sudo in the script can be removed with the --no-sudo argument.

Every package repository of TsukiNi22 at once (xstyle, libutils, brain, context-forge...), with my-universe:

curl -fsSL https://tsukini22.github.io/my-universe/install.sh | bash -s   # then: sudo dnf install xstyle (apt / pacman)

Or only the one of xstyle, with its setup script (no clone needed). It registers the package repository (gh-pages branch) so the system package manager can install the packages:

  1. Detect the distribution from /etc/os-release (rpm, deb or arch based).
  2. rpm: add /etc/yum.repos.d/xstyle.repo and import the GPG key.
  3. deb: add the GPG key in /etc/apt/keyrings/xstyle.gpg, the source in /etc/apt/sources.list.d/xstyle.list, then apt-get update.
  4. arch: add the GPG key to the pacman keyring (pacman-key --add + --lsign-key), the [xstyle] repository in /etc/pacman.conf (SigLevel = Required), then pacman -Sy.
  5. With --install only: install the package xstyle (--pre for the unstable one).
wget -qO- https://raw.githubusercontent.com/TsukiNi22/xstyle/main/setup.sh | bash -s -- --install

or with curl:

curl -fsSL https://raw.githubusercontent.com/TsukiNi22/xstyle/main/setup.sh | bash -s -- --install
Argument Effect
--no-sudo Run without sudo (the script must already run as root)
--install Also install the package (by default only the mirror & GPG key are setup)
--pre Select the pre-release/unstable package (xstyle-pre)
-h, --help Display the usage

Usage

xstyle                                 # check the current directory (recursive), every known language
xstyle -r src include                  # only these directories (recursive with -r)
xstyle src/core/Engine.cpp             # one file
xstyle -S                              # only the summary (counters by severity and by rule)
xstyle --rtk                           # compact output for an AI (5x fewer tokens): no color, no source, one line per issue
xstyle -s major                        # only the major and unforgivable issues
xstyle -m force,manual                 # only these fix levels (auto, force, ask, manual), comma separated
xstyle -c CPP-THIS,LU                  # only these rules (code, prefix or pattern: CPP, LU-*, G-TAB)
xstyle -i G-TODO,CPP-AUTO              # every rule except these
xstyle -l cpp,rs                       # only the C++ and Rust files (-t: only the most used language)
xstyle --ignore-path 'tests/**:CPP-AUTO'  # rules ignored on some paths only (GLOB[:CODES], ; separated)
xstyle --exclude-from paths.txt        # the -e patterns of a file (one per line)
xstyle --no-gitignore                  # also the files ignored by git (skipped by default)
xstyle --show-ignored                  # also list the issues silenced (comment, path, rule), not only their count
xstyle --no-inline-ignore              # audit: no suppression comment, no .xignore, no [[path]] of .xconfig
xstyle --add-ignore -c CPP-AUTO        # write xstyle: ignore CPP-AUTO on the lines of these issues (-n to preview)
xstyle --fix                           # fix everything that can be fixed
xstyle --fix CPP-NULL,G-TRAILING src   # fix only these rules, only in src
xstyle --fix --force                   # also the [force-fix] ones (can change the behavior: check with -n first)
xstyle --fix --dangerous-force         # also the [danger-fix] ones: guessed (types from the usage...), can be wrong
xstyle --fix --header default          # missing file headers with the XARTANIA banner (none | default | <text>), no question
xstyle -f -n -c CPP -r src/core        # preview (dry run) of the C++ fixes of one directory
xstyle -o report.md                    # report in this file (.txt, .md or .json), nothing in the terminal
xstyle -x CPP-THIS                     # explain a rule, -L lists every rule
xstyle --diff                          # only the lines changed since HEAD (staged + not staged, new files)
xstyle --diff-ref main                 # only the lines changed since a branch / tag / commit
xstyle --staged --fix                  # only the staged lines (pre-commit hook)
xstyle --fix --commit                  # fix, then commit the fixed files: chore(style): apply the xstyle fixes (...)
xstyle --fix --commit-all --message "chore(core): ..."  # fix + commit every tracked change with the fixes
xstyle --libutils-check                # is the libutils skill reference up to date? (exit 0 yes, 1 no)
xstyle --r34                           # I have read the Terms and Conditions of Rule 34, I accept them: R34 is not displayed
  • Paths: files or directories given as bare arguments; with no path the current directory is scanned recursively. Hidden folders, build*, cmake-build-*, third_party, extern, vendor, node_modules... and the generated_* files are skipped, so are the files ignored by git (--no-gitignore checks them; a file given as argument is always checked) and the paths of the .xignore files; -e build,*.gen.hpp excludes more (folder name, path prefix or glob), see Ignoring rules and files.

  • Fix level of every issue, right after its code (Fix column of the table below, fix field of the JSON):

    Tag Fixed by Meaning
    [auto-fix] --fix safe, the behavior can't change (spaces, includes order, nullptr, [ ] -> [[ ]] when equivalent...)
    [force-fix] --fix --force can change the behavior: set -euo pipefail (a failing command now stops the script), encoding="utf-8" (a file in another encoding now fails), [ a -o b ] / unquoted patterns, a comment replaced; preview with -n
    [danger-fix] --fix --dangerous-force (implies --force) guessed, can be wrong: Python types guessed from the usage / the name / a local variable, T | None (Python 3.10+), static_cast of a C pointer cast (reinterpret_cast needed if it doesn't compile)
    [ask-fix] --fix + a question the missing file header: banner [n]one, [d]efault (XARTANIA) or [t]ext + description, per file (upper case answer: same for the next files); --header none|default|<text> and --header-desc "..." answer without question (CI, no terminal: skipped)
    [manual] by hand needs a decision a tool can't take (a type to write, a name to choose, a code to rewrite with libutils...)

    Python type hints, per parameter / return:

    • certain ([auto-fix]): a literal default (level=2 -> level: int = 2), -> None without any return value / yield, every return of the same certain type: literal, display ([...] list, {...} dict / set, (a, b) tuple), builtin (len() int, str(), isinstance() bool...), stdlib (os.path.join() str, os.path.exists() bool...), not / is / in (bool), "text" + x (str);
    • guessed ([danger-fix]): from the usage in the body (x.split() str, x.append() list, x.items() dict, open(x) str, range(x) int), from the name (is_* / verbose bool, *_path / name str, count / size int), a local variable assigned once (parts = line.split(",") then return parts), comparisons == / < (bool, can be overloaded), methods on an unknown value (x.strip() str), T | None;
    • unknown ([manual], listed as "by hand"): anything else; a stub (..., raise NotImplementedError) or a generator is never typed.
  • Filter by level: -m auto,force,dangerous,ask,manual (one or several, forced / danger accepted) keeps only those issues, in the display, the counters, the report and --fix (xstyle --fix --force -m auto applies only the safe fixes).

  • Templates: a file with {{NAME}} placeholders is not valid code yet, only the generic rules are checked there.

  • Fix: the fixes are applied in passes (a fix can reveal another issue: [[nodiscard]] -> _nodiscard -> #define _Attribute missing -> added), only the fixable rules (yes in the table) are touched, the logic never. Review the result with git diff.

  • AI mode (--rtk, or XSTYLE_RTK=1): what an assistant needs and nothing else: a legend line, >file once, then line:col CODE severity fix message => fix|hint per issue (the message / hint shared by every issue of a rule written once in * CODE ... lines at the end), fixed N: CODExK, one = N issues ... summary line, errors on one plain line. No color, no hyperlink, no source line, no table. The skills and the CLAUDE.md files run xstyle this way.

  • Hyperlinks: the locations are OSC 8 links in the terminal (--link file, default), or vscode:// links (--link vscode, opens the file at the line), --no-color / NO_COLOR for plain text.

  • Changed lines (--diff, --diff-ref, --staged): only the issues on the lines changed in git (whole file issues when the file changed), with no path the changed files themselves; the fixes follow the same filter.

  • Commit (--commit, --commit-all, with --fix): the message is chore(style): apply the xstyle fixes (N issues) with one line per rule (or --message). --commit only takes the files that had no change before the fixes (their own changes would end up in the commit, they are listed and left), --commit-all takes every tracked change too. Never with --dry-run.

  • Exit status: 0 clean, 1 issues left (from --fail-on <severity>, default every severity), 255 error. The mandatory rule (R34) is never counted: not in the exit status, the totals, --fail-on nor the pre-commit hook.

  • Environment: XSTYLE_CODES, XSTYLE_IGNORE, XSTYLE_IGNORE_PATH, XSTYLE_SEVERITY, XSTYLE_EXCLUDE, XSTYLE_LIBUTILS, XSTYLE_LINK, XSTYLE_REPORT give the default of the flag of the same name; XSTYLE_R34=1 is --r34. They win over the .xconfig of the project, the command line wins over both.

Rule R34 (mandatory)

R34 is the only rule of the severity mandatory: Rule 34: if it exists, there is porn of it. No exceptions. It is a reminder, not a style rule:

  • it is displayed once per run, for the whole project, with a green link to the article of the rule (https://en.wikipedia.org/wiki/Rule_34), and in the --rtk output as a ! R34 ... line;
  • it is never counted: not in the totals (its own mandatory row in the summary), the exit status, --fail-on nor the hook; -s does not hide it, -c / -i / -m select it like any other rule;
  • it is acknowledged (not displayed any more) by the integer 34, or r34 (any case) in an identifier, a string or a comment of a checked file, by a file named R34.md in the directory where xstyle is run, by the flag --r34 or by XSTYLE_R34=1;
  • xstyle --fix --force writes R34.md (a long explanation of the rule: statement, origin, spread, interpretation), which acknowledges it; an existing R34.md is never replaced; xstyle -x R34 explains it.

Ignoring rules and files

In a comment of the file (Markdown: in a <!-- --> comment); without a code every rule is silenced there, a code can be a prefix or a pattern (CPP, LU-*), a reason after the codes starts with a lower case word or a parenthesis:

Comment Silences
xstyle: ignore [CODE,...] this line
xstyle: ignore-next [N] [CODE,...] the next line (the next N lines)
xstyle: off [CODE,...] ... xstyle: on [CODE,...] the lines between (up to the end of the file without on; on alone closes every open region)
xstyle: ignore-file [CODE,...] the whole file
xstyle: skip-file the file is not checked nor counted

A comment that silences nothing any more is reported by G-UNUSED-IGNORE (removed by --fix; an off region loses its on too). The rules that are off (libutils), R34 and the comments silencing G-UNUSED-IGNORE itself are never reported; only a comment naming it (xstyle: ignore G-UNUSED-IGNORE) silences it, never a comment of every rule.

By path, a .xignore file in any directory of the project (read from the project root down to the file, like a .gitignore): one pattern per line, # comments, * / ? / ** jokers, a pattern with a / is relative to the directory of the .xignore (else a name at any depth), name/ matches directories only, !pattern includes again (the last matching line wins). A line ending with :CODE,... does not exclude the paths: it ignores these rules there.

# .xignore
third_party_copy/           # not checked at all
*.gen.hpp
!keep.gen.hpp
tests/**:CPP-AUTO,G-TODO    # still checked, these rules ignored

Project configuration, .xconfig (TOML; the closest one from the working directory up to the project root): the default of the flags (the environment and the command line win, ignore is added to -i), exclude / ignore-path patterns relative to its directory, and [[path]] tables:

# .xconfig
severity = "minor"            # -s
fail-on = "major"             # -F
ignore = ["CPP-AUTO"]         # -i (added)
lang = ["cpp", "py"]          # -l
libutils = "auto"             # -u
gitignore = true              # false: --no-gitignore
inline-ignore = true          # false: --no-inline-ignore
exclude = ["third/**"]        # like a .xignore line
ignore-path = ["examples/*:G-TODO"]

[[path]]
match = ["tests/**", "bench/**"]
ignore = ["CPP-FUNC-LENGTH", "CPP-UNCHECKED-RETURN"]

[[path]]
match = "generated/"
exclude = true

Keys: code, ignore, severity, fail-on, lang, mode, libutils, top, link, header, header-desc, r34, gitignore, inline-ignore, exclude, ignore-path; an unknown key or a wrong value stops xstyle with <file>:<line>.

Flags: -i CODES (every path), --ignore-path 'GLOB[:CODES];...' (relative to the working directory, no codes: every rule), -e PATTERNS / --exclude-from FILE (paths skipped), --no-gitignore, --no-inline-ignore (audit: the comments, the .xignore files and the [[path]] tables are not read; the flags and the other keys of .xconfig stay).

Adopting xstyle on old code: --add-ignore writes xstyle: ignore CODE,... at the end of the line of every issue left (after -c / -s / -m / --diff; -n previews), in the comment of the language (//, #, --, ;). Never on a line ending in a string, a here-document or a \ continuation, an empty line, a line that already has a directive, nor for a whole file issue; a comment that would silence nothing (it removes the issue itself, like a trailing whitespace) is taken back. Markdown, JSON and YAML files are left as they are.

The issues silenced by a comment, a rule by path or -i are counted (Ignored 3 issue(s) silenced (comment 1, path 2), | ignored 3 (...) in --rtk, ignored in the JSON report), --show-ignored lists them.

std::cout << "\033[1m"; // xstyle: ignore LU-ANSI
// xstyle: ignore-next 2 CPP-AUTO
auto lambda = [](int x) {return x * 2;};
auto other = [](int x) {return x * 3;};
// xstyle: off CPP-ONELINER-ALIGN (table aligned by hand)
// ...
// xstyle: on
// xstyle: ignore-file CPP-GUARD-MISSING (no guard on purpose)

libutils

The LU-* rules are enabled when libutils is installed (/usr/include, /usr/local/include, ~/.local/include or CPATH) and used by the project (find_package(utils) / utils::utils in the root CMakeLists.txt, or utils.hpp included); --libutils on|off forces them. Inside libutils itself they are off.

  • includes: one root <utils/utils.hpp> preceded by the #define _Section of every section used (detected from the utils::<section>:: names and the attribute macros of the file), never a libutils header one by one;
  • [[nodiscard]], [[maybe_unused]], alignas(...)... -> the libutils macros (_nodiscard, _unused, _alignas...);
  • deprecated names -> new names, read from the _migration aliases of the installed headers, plus the names libutils v4.0.0 removed (isloaded() -> isLoaded(), utils::network::socket::is_ip -> utils::network::is_ip, setStyle -> set_style, fixed_string -> FixedString...: a v3 code moved to v4 is told what to write);
  • code that libutils already gives: standard exceptions, argv parsed by hand, raw ANSI sequences, BSD sockets, pipe / fork / epoll / shm_open / dlopen, thread pools, degree / radian conversions, base64, verbose flags, string distances (hint with the libutils class to use).

Languages

Language Files Rules
C++ .cpp .cc .cxx .hpp .hh .hxx .ipp .tpp .inl .h generic + CPP-* + LU-* (libutils installed and used)
C .c (+ .h of a project without C++ sources) generic + C-* (the layout rules shared with the C++ under their own C- code, then the C rules)
Assembly (NASM x86-64) .asm .nasm .s .S generic + ASM-* (a GAS file, AT&T or .intel_syntax: ASM-HEADER + generic only)
Rust .rs generic + RS-* (tests: #[cfg(test)] module, tests/, benches/, examples/ excepted for unwrap / panic)
Python .py generic + PY-*
Shell .sh .bash generic + SH-*
Lua, JS / TS, CMake .lua, .js .mjs .ts .tsx .jsx, CMakeLists.txt .cmake generic
Makefile, YAML Makefile .mk, .yml .yaml generic (no indentation by 4, Makefile recipe tabs allowed)
JSON, Markdown .json, .md generic (Markdown: trailing spaces allowed)

Any other file is skipped when a directory is scanned; given explicitly, it gets the basic generic rules.

Rules

Severity: unforgivable > major > minor > negligible; mandatory is outside this scale (displayed, never counted). Languages: * = every file checked.

Code Severity Fix Languages Rule
R34 mandatory force * Rule 34: if it exists, there is porn of it. No exceptions (R34)
G-CRLF major auto * Windows line endings (CRLF), use LF
G-TAB major auto * Tab used for the indentation, use 4 spaces (except Makefile recipes)
G-TRAILING minor auto * Trailing whitespace
G-EMPTY-LINES minor auto * Two or more consecutive empty lines, one is the maximum
G-EOF-NEWLINE negligible auto * No newline at the end of the file
G-EOF-EMPTY negligible auto * Empty lines at the end of the file
G-TODO minor - * TODO / FIXME / XXX tag, describe the limitation in a normal comment instead
G-UNUSED-IGNORE minor auto * Suppression comment (xstyle: ignore / ignore-next / ignore-file / off) that silences nothing, remove it
G-INDENT negligible - cpp,c,py,sh,lua,js,rs,cmake Indentation that is not a multiple of 4 spaces
CPP-USING-NAMESPACE unforgivable - cpp using namespace, always write the fully qualified names
CPP-GUARD-MISSING major auto cpp Header without include guard (#ifndef NAME_H / #define NAME_H)
CPP-PRAGMA-ONCE minor auto cpp #pragma once instead of the include guard NAME_H
CPP-GUARD-NAME minor auto cpp Include guard not named after the file (Name.hpp -> NAME_H)
CPP-ENDIF-COMMENT negligible auto cpp Guard #endif without its /* NAME_H */ comment
CPP-PREPRO-INDENT negligible auto cpp #if block not at the indent of the code around with its content one level more (directives: 4 per #if / guard level)
CPP-HEADER minor ask cpp Missing file header (cpp-class scripts/header.py)
CPP-HEADER-FILE negligible auto cpp @file of the header is not the name of the file
CPP-NULL major auto cpp NULL instead of nullptr
CPP-C-CAST major auto cpp C cast, use static_cast (only (void) is allowed)
CPP-AUTO major - cpp auto, write the type (allowed: iterators, structured bindings)
CPP-USING-STD major - cpp using std::x, always write std::x
CPP-TYPEDEF minor auto cpp typedef, use using Name = Type
CPP-BRACE-FUNCTION major auto cpp Function opening brace on the signature line, it goes on its own line
CPP-BRACE-OWN-LINE major auto cpp Opening brace of a class / namespace / control block on its own line, it goes on the same line
CPP-ELSE-LINE minor auto cpp else / catch not on the closing brace line (} else {)
CPP-KEYWORD-SPACE minor auto cpp No space between if / for / while / switch / catch and the parenthesis
CPP-PAREN-SPACE negligible auto cpp Space inside the parentheses of a control statement
CPP-COLON-SPACE negligible auto cpp Space before ':' of a range-for, an inheritance or an enum base
CPP-PTR-REF minor auto cpp & / * glued to the name instead of the type (const T& name, char* buf)
CPP-VOID-PARAM minor auto cpp Empty parameter list, write (void)
CPP-THIS minor auto cpp Member accessed without this->
CPP-NAMESPACE-NESTED minor - cpp Nested namespace blocks, use namespace a::b {
CPP-NAMESPACE-COMMENT negligible auto cpp Namespace block without // namespace start / // namespace end
CPP-NAMESPACE-INDENT minor - cpp Content of a namespace indented (it is not)
CPP-INCLUDE-ORDER minor auto cpp Include order: personal libs (+ defines), project, external; longest name first
CPP-CLASS-NAME major - cpp Class / struct / enum not in PascalCase
CPP-MEMBER-NAME minor - cpp Class data member not named _camelCase
CPP-MACRO-NAME minor - cpp Macro not in UPPER_SNAKE (or _lower for attribute / section macros)
CPP-ONE-LINER negligible auto cpp One-liner body not written {statement}; (an empty one: { /* Nothing */ };)
CPP-EMPTY-BODY minor auto cpp Empty constructor / destructor / operator of a class on several lines (one line: sig: init { /* Nothing */ }; // comment)
CPP-ONELINER-ALIGN negligible auto cpp One-liner functions of a group not aligned tight: their { right after the longest signature + 1 (lengths far apart: one column per level of 2+ lines)
CPP-INIT-COLON minor auto cpp Init list on the line of its constructor: its : glued to the ) (Name(int a): _a{a})
CPP-ACCESS-ORDER negligible - cpp public before private / protected in a class
CPP-SINGLE-STATEMENT minor - cpp Single statement function defined in the .cpp, define it inline in the header
CPP-DOXYGEN minor - cpp Doxygen comment (@brief, @param, ///, /**), short plain comments only
CPP-UNCHECKED-RETURN minor - cpp Result of a function returning a value ignored (free functions of the project, libc / POSIX): use it or cast the call to (void)
CPP-INCLUDE-COMMENT minor - cpp Include of a header without its trailing comment listing what is used
CPP-COMMENT-ALIGN negligible auto cpp Trailing comments of an include block not aligned on one column
CPP-EMPTY-SECTION minor auto cpp Section separator / class block with nothing linked to it
CPP-CLASS-BLOCK minor - cpp Declaration in the wrong class block: Pre-Function = declared only (body in the .cpp), Function = defined in the header, Constructor / Destructor = theirs, data members before the blocks (Operator: free)
CPP-ORPHAN-GROUP negligible auto cpp /* group */ label with nothing under it
C-GUARD-MISSING major auto c Header without include guard (#ifndef NAME_H / #define NAME_H)
C-PRAGMA-ONCE minor auto c #pragma once instead of the include guard NAME_H
C-GUARD-NAME minor auto c Include guard not named after the file (name.h -> NAME_H)
C-ENDIF-COMMENT negligible auto c Guard #endif without its /* NAME_H */ comment
C-PREPRO-INDENT negligible auto c #if block not at the indent of the code around with its content one level more (directives: 4 per #if / guard level)
C-HEADER minor ask c Missing file header (XARTANIA banner, none or a text: asked by --fix, like the C++)
C-HEADER-FILE negligible auto c @file of the header is not the name of the file
C-BRACE-FUNCTION major auto c Function opening brace on the signature line, it goes on its own line
C-BRACE-OWN-LINE major auto c Opening brace of a struct / union / enum / control block on its own line, it goes on the same line
C-ELSE-LINE minor auto c else not on the closing brace line (} else {)
C-KEYWORD-SPACE minor auto c No space between if / for / while / switch and the parenthesis
C-PAREN-SPACE negligible auto c Space inside the parentheses of a control statement
C-PTR-REF minor auto c * glued to the name instead of the type (char* buf, like the C++)
C-VOID-PARAM minor auto c Empty parameter list, write (void)
C-INCLUDE-ORDER minor auto c Include order: personal libs (+ defines), project, external; longest name first
C-MACRO-NAME minor - c Macro not in UPPER_SNAKE (or _lower for attribute / section macros)
C-DOXYGEN minor - c Doxygen comment (@brief, @param, ///, /**), short plain comments only
C-INCLUDE-COMMENT minor - c Include of a header without its trailing comment listing what is used
C-COMMENT-ALIGN negligible auto c Trailing comments of an include block not aligned on one column
C-EMPTY-SECTION minor auto c Section separator with nothing linked to it
C-ORPHAN-GROUP negligible auto c /* group */ label with nothing under it
C-UNCHECKED-RETURN minor - c Result of a function returning a value ignored (functions of the project, libc / POSIX): use it or cast the call to (void)
C-TYPE-NAME major - c struct / union / enum not in snake_case ending with _s / _u / _e, typedef not ending with _t, enum value not in UPPER_SNAKE
C-FUNC-NAME minor - c Function, parameter or variable not in snake_case (global const: UPPER_SNAKE allowed)
C-PTR-CHECK minor - c Pointer parameter of a non static function dereferenced (p->, p[, *p) before being checked (if (!ptr) return KO;)
C-FUNC-LENGTH minor - c Function body longer than 40 lines of code (empty and comment lines not counted)
C-NESTING minor - c Control blocks (if / for / while / switch / do / else) nested more than 4 levels deep (a bare { } is not a level)
ASM-HEADER minor ask asm Missing file header (the C / C++ one in ; comments: XARTANIA banner, none or a text, asked by --fix)
ASM-HEADER-FILE negligible auto asm @file of the header is not the name of the file
ASM-SECTION-ORDER minor - asm Sections not in the order .data, .rodata, .bss, .text
ASM-SYMBOL-DECL minor - asm extern after a section, global not at the start of section .text, global without its label, extern never used
ASM-INDENT minor auto asm Indentation: section / function label at 0, their content at 4, a local label at its block level and its content (up to its last backward jump) one level more
ASM-COMMENT-ALIGN negligible auto asm Trailing ; comments of consecutive lines not aligned on one column
ASM-CASE negligible auto asm Mnemonic, register, size or directive not in lower case (MOV RAX -> mov rax)
ASM-LABEL-NAME minor - asm Label not in snake_case (local: .snake_case); a static function (not global) starts with _, a global one never does (_start excepted)
ASM-LOCAL-LABEL minor - asm Label only jumped to from its function: make it local (.name)
ASM-CONST-NAME minor - asm equ / %define / %assign / %macro name not in UPPER_SNAKE
ASM-DATA-NAME minor - asm Data label (.data / .rodata / .bss) not in snake_case or named like a register
ASM-REG-COMMENT minor force asm Function label without the comment of its registers (; in: rdi, rsi | out: rax), written from the registers read / written with --force
ASM-FALLTHROUGH major - asm Function falling through into the next one (its last instruction is not ret / jmp / the exit syscall)
ASM-CALLEE-SAVED major - asm Global function changing rbx, rbp or r12-r15 without push / pop (System V ABI)
ASM-FRAME major - asm push rbp without pop rbp / leave before a ret, or pop rbp / leave without push rbp
ASM-FRAME-UNUSED negligible - asm Stack frame (push rbp / mov rbp, rsp) of a function using no stack: no other push / pop, no call, no [rbp] / [rsp], rsp unchanged
ASM-SYSCALL-COMMENT minor auto asm mov rax, N of a syscall without the comment of its name (; write), written by --fix
ASM-ZERO-XOR negligible force asm mov reg, 0: xor reg, reg (shorter; the flags change: --force)
CMAKE-SECTION-ORDER minor - cmake Sections not in the cmake-style order
CMAKE-BANNER negligible auto cmake Section banner not '# ' + 25 '='
CMAKE-COMPILER-ORDER major force cmake set(CMAKE_CXX_COMPILER) after project(): ignored, it goes before
CMAKE-GLOB-SOURCES major - cmake Sources collected with file(GLOB), list them in set(SRC ...)
CMAKE-UNREGISTERED major force cmake Source file of src/ missing from set(SRC ...)
LU-INCLUDE major auto cpp libutils header included directly, use #define _Section + <utils/utils.hpp>
LU-BARE-INCLUDE major auto cpp <utils/utils.hpp> without any #define _Section before it
LU-SECTION minor auto cpp libutils section used without its #define before <utils/utils.hpp>
LU-ATTRIBUTE minor auto cpp Standard attribute with a libutils macro equivalent ([[nodiscard]] -> _nodiscard)
LU-MIGRATION major auto cpp Deprecated libutils name (migration alias), use the new name
LU-EXCEPTION major - cpp Standard exception thrown, use utils::exception::ErrorException
LU-ARGS minor - cpp Arguments parsed by hand, use utils::arguments::ArgParser
LU-ANSI minor - cpp Raw ANSI escape sequence, use utils::iomanip
LU-SOCKET minor - cpp Raw BSD socket, use utils::network (TCPSocket, Server, Client)
LU-SYSCALL minor - cpp Raw pipe / dup / fork / epoll / shm / dlopen, use utils::encapsulation
LU-THREADS minor - cpp Hand made thread pool, use utils::pool::Cluster or utils::system::Scheduler
LU-ANGLE minor - cpp Degree / radian conversion by hand, use utils::math::trigo
LU-BASE64 minor - cpp Hand made base64, use utils::smanip::codec::Base64Codec
LU-VERBOSE minor - cpp Hand made verbose flag, use utils::verbose (set_verbose, onBasicVerbose)
LU-DISTANCE minor - cpp Hand made string distance, use utils::algorithms::c2dmp
PY-WILDCARD-IMPORT major - py from x import *, import the names explicitly
PY-BARE-EXCEPT major - py Bare except:, catch the exceptions expected
PY-TYPE-HINTS minor auto py Function without type hints (added when certain: literal defaults, None / literal returns)
PY-PRINT-ERROR minor auto py print(..., file=stderr), use stderr.write
PY-OPEN-ENCODING minor force py open() of a text file without encoding="utf-8"
RS-UNWRAP major - rs .unwrap() outside of the tests, propagate with ? (and a context) or handle the error
RS-PANIC major - rs panic! / process::exit in a library file, todo! / unimplemented! left anywhere
RS-GLOB-IMPORT major - rs use path::, import the names explicitly (super:: and preludes excepted)
RS-NAMING minor - rs fn / variables snake_case, types PascalCase, const / static UPPER_SNAKE
RS-UNSAFE minor - rs unsafe block without a // SAFETY: comment explaining why it is sound
RS-PRINT-ERROR minor auto rs Error printed with println!, use eprintln! (stderr)
RS-DBG minor - rs dbg! left in the code
SH-SHEBANG minor - sh Script without shebang (#!/bin/bash)
SH-STRICT minor force sh Bash script without set -euo pipefail
SH-TEST negligible auto sh [ ] test in a bash script, use [[ ]]

Development

make                                                      # Configure & build into build/
export BUILD_DIR=build
cmake -S . -B $BUILD_DIR -DCMAKE_BUILD_TYPE=Debug         # Debug build (-g -ggdb3)
cmake -S . -B $BUILD_DIR -DCMAKE_BUILD_TYPE=Asan          # AddressSanitizer build
cmake --build $BUILD_DIR --target release                 # Debug, Asan & Optimized builds
cmake --build $BUILD_DIR --target package_release         # RPM / DEB / Arch packages of every variant (build/*.rpm, *.deb, *.pkg.tar.zst)
cmake --build $BUILD_DIR --target get_unregistered_files  # .cpp files missing from the SRC / SRC_SHARED lists
./xstyle --rtk -r src include tests CMakeLists.txt        # xstyle stays clean on itself (checked by the CI)
Path Content
src/xstyle/ Sources: main.cpp (entry), Core.cpp (arguments, run), Checker.cpp, Reporter.cpp, Rules.cpp, check/ (one file per family of rules)
include/xstyle/ Headers
assets/fonts/ansi_shadow.flf Banner font of the file headers (--header), embedded at build time (build/generated/xstyle/Font.hpp)
tests/xstyle/ Unit tests (GoogleTest) + command line tests (ctest)
cmake/package/ CMake package config and the CPack scripts (Arch packages)
docs/ Documentation site (docs/site/: Markdown sources + generators, built pages in docs/) and the project graph

Note

Every new .cpp must be added to the SRC (executable only) or SRC_SHARED (executable and tests) list of the CMakeLists.txt (get_unregistered_files lists the missing ones).

Unit tests

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=ON
cmake --build build --parallel $(nproc)                       # ./unit_tests at the root
(cd build && ctest --output-on-failure)

Pre-commit hook

The shared hook (.githooks/pre-commit) runs xstyle on the staged lines at each git commit and refuses a major (or worse) issue.

git config core.hooksPath .githooks   # once per new clone
git commit --no-verify                # skip the hook once (or XSTYLE_HOOK=0 git commit ...)
xstyle --fix --staged                 # fix what can be, then git add -u

Workflows/Release

Workflows

  • Dispatch (CI/CD): runs on every push (branch main or tag v*, not for *.md / *.txt / docs/ only changes) and decides what to trigger from the ref / commit message
  • Unit Tests (CI): builds and runs the unit tests, always first in the unit-tests image
  • Build (CI): only builds the project in the ci image, checks the outputs and runs xstyle on its own sources (--fail-on major), without producing packages
  • Build - Packages (CI/CD): builds the packages (RPM/DEB/Arch, in the ci image), signs them and publishes them on the gh-pages repository
  • Release - GitHub (CD): creates the GitHub release of a tag from its section of the CHANGELOG.md, once the packages are published
  • Docs - Pages (CD): copies docs/ on the gh-pages branch on every push changing it (https://tsukini22.github.io/xstyle/docs/)
  • Sync Packages (CD) (on gh-pages): rebuilds the metadata and signatures of the package repository after a manual push on the branch

Note

Build (CI) only runs when Dispatch (CI/CD) decides not to build the packages, to check that the code still compiles.

Important

The workflows need the repository variable RUNNER (gh variable set RUNNER --body <runner>), the containers ghcr.io/tsukini22/ci, unit-tests, package, git, the secrets GPG_PRIVATE_KEY (base64), GPG_KEY_ID, GPG_PASSPHRASE to sign and publish the packages, and DOCKER_IMAGE_REPO_TOKEN (fine-grained token shared by libutils, brain and xstyle: Contents read and write on docker-image) to notify docker-image.

Tip

A commit containing [ignore] skips the whole CI.

Pre-Release (unstable)

The pre-release of the packages (<package_name>-pre) is triggered by:

  • a tag with a suffix, matching vx.x.x-<suffix> (ex: v1.0.1-pre, x = major, minor, fix)
  • or a commit containing [build]

Note

Only the 5 last versions of each -pre package are kept in the package repository, every release is kept.

Release (stable)

The release of the packages (channel stable) and the GitHub release are only triggered by a tag matching exactly vx.x.x (ex: v1.0.0), whose section must exist in the CHANGELOG.md. A pre-release tag also gets a GitHub release (marked pre-release), with its own ## [vx.x.x-pre] section or the ## [pre-release] one.

Downstream notification

Dispatch (CI/CD) notifies the docker-image repository (repository_dispatch xstyle-released, job notify-docker-image) after the packages are published, to rebuild the ci and mingw64-ci images (and their unit-tests images) with the new packages:

  • on every package build (release or pre-release)
  • or on a commit containing [release]

About

xstyle: checker and fixer of my coding style (C++20 / libutils first, Python, shell, Rust, CMake, generic rules), auto fixes, --rtk output for AI, RPM / DEB / Arch packages

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages