BlaiseGuard 💂 — a static analyser for Blaise, written in Blaise

[graemeg]

🛡️BlaiseGuard is a linter for Blaise source. It reads your code the way the
compiler does, reports things that compile cleanly but are probably not what
you meant, and can fail a CI build when it finds them.

It lives in the compiler repo under tools/blaise-guard/, and it is written in
Blaise itself.

Why another linter

Most Pascal linters check Pascal. BlaiseGuard checks Blaise — a dialect
that has deliberately dropped some things and changed others. That difference
shows up in two directions.

Rules that would be wrong here are simply absent. There is no goto rule, no
with rule, no legacy object rule — the parser rejects all three, so a rule
for them would be dead code. Likewise F := x inside function F is already a
compile error, so there is no rule for it.

Rules that only make sense here do exist. Blaise is ARC-managed, so a manual
Free is usually a mistake (BL-2001). Strings and arrays are 0-based, so a
literal [1] subscript is often a habit carried over from Delphi/FPC
(BL-2003). And one rule encodes a hard-won lesson from the compiler's own
history: Ord(S[i]) has been observed to miscompile under the self-hosted
native stage, so BL-2004 points you at StrAt/OrdAt instead.

It uses the compiler's real frontend

BlaiseGuard links the compiler's live uLexer / uParser / uAST rather than
a vendored copy. So it always analyses exactly the grammar the compiler
currently accepts, and when the grammar changes, BlaiseGuard fails to build
in that same commit rather than silently drifting onto a stale dialect.

That is also why it ships inside the compiler repo instead of on its own.

Using it

blaise-guard path/to/unit.pas        # one file
blaise-guard --scan path/to/src      # every *.pas under a tree
blaise-guard --project project.xml   # a PasBuild project

Real output:

demo.pas:10:3: warning BL-3002: case over enum covers 2 of 3 members and has no else - missing: stdone (adding an enum member will not flag this statement)
demo.pas:15:11: warning BL-1005: Comparison '= True' against a boolean literal is redundant - test the value directly
demo.pas:18:3: warning BL-2001: Manual Obj.Free is usually unnecessary under ARC; rely on scope exit or nil-assignment, and use [Weak] to break cycles
demo.pas:19:3: warning BL-2005: Empty except block silently swallows the exception - handle it, log it, or re-raise with a bare 'raise'

4 issue(s): 0 error(s), 4 warning(s), 0 info

As a CI gate

--fail-on turns findings into an exit code:

blaise-guard --scan src --fail-on warning   # exit 1 if any warning exists
blaise-guard --scan src --fail-on error     # exit 1 only on errors

Reports can be emitted as console (default), json, xml or html via
--format, and written to a file with --output. The JSON carries
ruleId, severity, file, line, col and message per finding plus a
summary block, so it is easy to feed into other tooling.

The rules

ID	Name	What it flags
BL-0000	ParseError	A file that failed to parse (engine diagnostic, suppressible)
BL-1001	MaxLineLength	Lines over maxLength (default 120)
BL-1002	MaxFunctionLines	Routines over maxLines
BL-1003	DeepNesting	Control-flow nesting over maxDepth (default 3)
BL-1004	UnusedIdentifiers	Declared and never used (off by default — heuristic)
BL-1005	RedundantComparison	X = True, and self-assignment X := X
BL-1006	UnassignedResult	A function that never assigns Result or uses Exit(value)
BL-2001	AvoidManualFree	Manual Free under ARC
BL-2002	ReferenceCycles	Strong-reference cycles (cross-file graph)
BL-2003	StringIndexing	Literal [1] subscript — Blaise is 0-based (info)
BL-2004	OrdSubscript	Ord(S[i]) instead of StrAt/OrdAt (info)
BL-2005	EmptyHandler	Empty except (a swallowed exception) or empty finally
BL-3001	DuplicateCodeBlock	Duplicated token windows, across files (Rabin-Karp)
BL-3002	ExhaustiveCase	A case over an enum that omits members and has no else

More rules will be added over time.

The ID scheme

BL-<family><ordinal>. The leading digit is the family:

• BL-0xxx — engine diagnostics, not rules.
• BL-1xxx — style and complexity. Applies to Pascal generally.
• BL-2xxx — Blaise semantics. Encodes a decision this language made, and
  would be wrong advice for another dialect.
• BL-3xxx — structural / cross-cutting. Needs more than one construct.

IDs are stable and never reused, so a number in an old report or a checked-in
config always means the same thing. The practical use is configuration: enable
only BL-2xxx and you get the Blaise-specific correctness checks with none of
the style opinions.

Two worth calling out

BL-3002 (ExhaustiveCase) is the one I would enable first. Add a member to
an enum and every existing case over it silently becomes incomplete — no
error, no warning. That shape has caused real bugs in the compiler's own
backends, where a new variant was handled in one dispatch and forgotten in
another.

It has a deliberate limitation. BlaiseGuard parses but does not run semantic
analysis, so it matches a case to an enum by its branch labels. If the enum
is declared in another unit, or the labels are ambiguous, the rule stays quiet
rather than guessing. It under-reports; it does not invent findings.

BL-1004 (UnusedIdentifiers) ships disabled. Closures and shadowing keep it
heuristic, so turn it on deliberately.

Configuration

blaise-guard.json:

{
  "rules": {
    "BL-1001": { "enabled": true, "severity": "warning",
                 "params": { "maxLength": 120 } },
    "BL-1003": { "enabled": true, "params": { "maxDepth": 3 } },
    "BL-1004": { "enabled": false }
  }
}

A rule absent from the file keeps its built-in default.

A note on tuning

The rules were measured against the compiler's own source rather than assumed
to be useful, and two candidates were dropped on the evidence.

A = nil → Assigned() rule fired 3242 times in compiler/src/main/pascal
alone. = nil is the house idiom there, and a rule that indicts the
prevailing style is noise, not signal. Similarly, flagging inline asm blocks
would have indicted 133 deliberate RTL routines.

By contrast, the two shapes BL-1005 does keep found zero existing sites —
so a hit there is a genuine new slip rather than a disagreement about style.
BL-1006 initially reported 108 findings, all false: SetLength(Result, N)
writes the result through a var parameter, and an asm body returns via the
ABI register without touching the Result slot. Both are now exempt, and the
count is zero.

Adding a rule

1. Create Guard.Rule.<Name> extending TLineRuleBase, TTokenRuleBase or
   TAstRuleBase; set the id/name/severity in the constructor and implement
   the single check hook.
2. initialization RegisterRule(T<Name>Rule.Create()); at the unit foot.
3. Add the unit to Guard.Rules.All.
4. Add a test suite under src/test/pascal and register it in Test.Registry.

Pick the family by what the rule is about; pick the base class by what it
needs to read. The two are independent — each family already mixes line, token
and AST rules.

Feedback and rule suggestions welcome, particularly for Blaise-specific
patterns (BL-2xxx) — those are the ones a general Pascal linter could never
give you.

[partridge6301]

[First, a bit of well-deserved praise] Wow, what a fantastic and rapid development this project has seen. For my part, I’m so impressed that I’d love to use Blaise for my upcoming project. I really hope Blaise will be ready soon. Your decisions to improve Pascal (whichever variant) really strike a chord. It feels so much better. [Enough of the well-deserved praise for now.]

Regarding BlaiseGuard, have you also planned for certain rules within the code to be ‘disabled’ in order to prevent false positives? There are cases where rules generally make sense, but shouldn’t be applied in certain places.

In other programming languages, this is generally controlled using special comments. Or are you even considering defining a language feature so that the linter can also be an (optional) component of the compiler, activated via a parameter, whilst this language feature is ignored in other contexts?

My best experiences have been when this ‘deactivation’ required a ‘reason’ to be specified, and when the linter mentions these instances appropriately in the log without triggering an error.

Is something like this in the pipeline? Or are there other considerations regarding this issue?

[graemeg]

That's already implemented (shortly after I posted the original announcement), and will land in today's batch of updates.

Syntax examples:

    { blaise-guard: ignore-file BL-2003 - Ignore whole unit - only allowed as header comment }
    X := Y;   // blaise-guard: ignore              — all rules, this line
    X := Y;   // blaise-guard: ignore BL-2003      — that rule only
    X := Y;   // blaise-guard: ignore BL-2003 - <Optional reason here>     — that rule only
    // blaise-guard: ignore BL-2003 BL-1003        — next line, two rules

Rationale for the shape: SonarQube's bare // NOSONAR suppresses EVERYTHING on the line, which silently hides later, unrelated findings. BlaiseGuard allows you to specify one or more rules, so other and future rules would still apply.

[rchastain2]

Excellent!

My first question.

program ControlFlow1;

var
  i: integer;

begin
  i := 4;
  
  if i > 0 then
    if i > 1 then
      if i > 2 then
        if i > 3 then
          WriteLn('i > 3');
end.

$ blaise-guard controlflow1.pas
controlflow1.pas:13:9: warning BL-1003: Control-flow nesting is 4 levels deep, exceeding the maximum of 3

1 issue(s): 0 error(s), 1 warning(s), 0 info

What is exactly the meaning of that maximum? I wonder because the above program is giving the expected result, although the maximum has been exceeded.

$ blaise --source controlflow1.pas --output controlflow1
$ ./controlflow1
i > 3

[rchastain2]

There is also a maximum for the number of lines in a procedure? Why?

$ blaise-guard easter.pas
easter.pas:11:121: warning BL-1001: Line exceeds 120 characters (183)
easter.pas:12:121: warning BL-1001: Line exceeds 120 characters (305)
easter.pas:14:1: warning BL-1002: Routine spans 17 lines, exceeding the maximum of 15

3 issue(s): 0 error(s), 3 warning(s), 0 info

easter.pas

(Here again, the programme is producing the expected result.)

[graemeg]

You can read a more detailed breakdown in SonarQube — what BlaiseGuard was inspired by — but there are many other static analysis tools as well, such as SpotBugs, FindBugs, and PMD. Unfortunately most, if not all, don't support the Object Pascal language.

To answer both of your questions: static analysis tools evaluate code quality and catch potential bugs before code ever reaches production.

Specifically, rules around deep nesting and method length target cognitive complexity and maintainability:

• Deep Nesting: When you have many nested if/else statements or loops, it forces a developer to track multiple branch conditions mentally all at once, making logic bugs and missed edge cases much more likely.

• Large Methods: Long methods usually violate the Single Responsibility Principle (doing too many things at once), making the code harder to read, harder to unit test, and risky to modify.

It's standard practice to use these tools in professional engineering workflows. For example, at my work, if the static analysis check fails in our CI pipeline, the Merge Request is blocked until the issue is resolved.

That said, rules aren't rigid laws. Configuration files allow you to adjust thresholds to fit your team's style and safety requirements, or disable rules entirely. If 15–20 lines is considered standard for a method in your codebase and doesn't add unreasonable complexity, you can simply tweak that threshold to 25 or 30 lines.

Hope this helps! Let me know if you'd like to dive deeper into any of these points.

[graemeg]

Looking at your easter.pas example, it's the OudinNumber() function that caused the BL-1002 warning. You could rewrite it like this, which then passes the BL-1002 rule, but still has the same overall logic.

// Corrects special case exceptions in the 19-year Metonic cycle
function CalculateEpactCorrection(const AG, AH: word): word;
var
  K: word;
begin
  K := AH div 28;
  result := (K * (29 div (AH + 1)) * ((21 - AG) div 11) - 1) * K + AH;
end;

function OudinNumber(const AAnnee: word): word;
var
  G, C, C4, E, H, I, J2: word;
begin
  G := AAnnee mod 19;
  C := AAnnee div 100;
  C4 := C div 4;
  E := (8 * C + 13) div 25;
  H := (19 * G + C - C4 - E + 15) mod 30;
  
  I := CalculateEpactCorrection(G, H);
  J2 := ((AAnnee div 4) + AAnnee + I + 2 + C4 - C) mod 7;
  
  result := 28 + I - J2;
end;

Why this works:

• Isolates the most opaque mathematical formula (K * P * Q) into a dedicated, testable helper.
• Keeps OudinNumber at a clean 8 lines of body code.
• Reduces cognitive load by giving names to abstract steps of the Gregorian calendar correction.