XBSL linter rules

The full list of linter checks, with severities and scope.

The full list of linter checks. This file is extended as rules are added; the live list at runtime is xbsl --list-rules (or the MCP list_rules). Currently there are 97 rules.

Boundary: the linter complements the compiler, it does not replace it

The linter works over text, the AST and the project model. Its rules know types at the first hop: the declared nominal type of a variable and its members, the project objects and the types they generate, enumeration values, the global types of the linked libraries (from the .xlib archive) - but they do not infer the type of an expression. The engine does infer chain types, only that feeds hover and completion in the editor, not the checks.

Some of the findings the compiler would catch as well: an unknown type, an argument count, a non-exception in catch, a return not matching the signature. The linter’s value there is not that it sees more, but that it sees them earlier - in seconds on your own machine, before the build and the deploy, pointing at the exact spot. The rest the compiler never checks at all: code-writing conventions, typography, project structure (duplicate Id, file pairing), unused variables, secrets in the sources.

What the linter does not do is anything that needs full inference of expression types: a redundant cast, an unclosed resource, whether the TYPE of a returned value matches the signature. That last one is worth separating: a structural mismatch (a value in a void method, a bare return in a typed one) is caught by code/return-mismatch, while a return of a string from a method declared : Number slips through - telling that apart needs the expression’s type.

Code correctness is verified by the server-side compilation on deploy; the linter runs before it and removes common mistakes early.

How to read the table

• Rule – the group/name identifier. The group (the part before /) lets you enable and disable rules in bulk.
• Severity – error (a build/CI should fail), warning (a convention is broken), info (a hint, usually off).
• Default – whether the rule is in the default set (on) or is enabled explicitly (off).
• Scope – file (the rule sees one file) or project (needs the whole-project index: duplicate Ids, unknown types, cross-module calls).
• Docs – a link to the platform documentation section behind the rule. In VS Code the code of such a rule in the Problems panel opens that section right in the editor.

Tiers

Rules are split into tiers A-D by what they rely on. A tier is also a quick filter for --select/--ignore (alongside the group and the identifier): --select A,B runs only structure and text, --ignore D drops the semantics over stdlib.

Tier A - structure and YAML

The file exists, parses, the object has a unique UUID, the name matches the file.

Tier B - text and conventions

Encoding, newlines, whitespace, typography (dashes, quotes, ellipsis), line length, secrets in the sources.

Tier C - code structure, basic syntax and code-writing conventions

Block and bracket balance, loop and method headers, local variables and the style/ group - conventions from the documentation section “Code-writing recommendations”. Some style/ rules are off by default (accumulated debt, info): enable them with --select style to measure.

Tier D - semantics over stdlib, forms and the metamodel

Needs the project index and platform data: unknown types and objects, enumeration values, the execution model (client/server), form handlers, properties and queries.

Group details

Queries: IN with a subquery over a composite type (rule query/in-subquery-composite)

A platform standard: IN with a subquery over an expression of a composite type is implemented inefficiently on most DBMSs, so the condition is written with EXISTS instead. The rule is a warning – the standard is mandatory:

WHERE T.Value IN (SELECT F.Value FROM Filters AS F)                    // warning
WHERE EXISTS (SELECT 1 FROM Filters AS F WHERE F.Value = T.Value)      // this way

A type counts as composite when the yaml spells two or more alternatives (String|Number|?): the ? is not a type but the admissibility of Undefined, and Array<String|Number> is not composite either. Only a field whose type is known for sure is questioned: Alias.Field or Table.Field, where the alias is unambiguous within the block and the field is found in the table’s yaml; a list of values (IN (1, 2, &Codes)) is not what the standard is about. Both spellings of the query language are understood - the English IN, NOT, SELECT and their Russian equivalents.

Project properties (the project/ rules)

Three rules from the standard “Filling in the project properties”: Vendor and Name are identifiers built from the presentations, every word capitalized; Presentation and VendorPresentation are filled in - the official name of the project and of the company that developed it; Version is three numbers A.B.C (semantic versioning), not 1.0.

Names of project elements (the naming/ rules)

Twelve rules from the platform standard “Names of project elements” – it is mandatory in new code, so all of them are warnings. They read the descriptions (.yaml): the name of the element itself and the names in its Attributes, Dimensions, Resources, TabularParts and enumeration values.

The number of a name is checked against the kind: catalogs, documents, registers and tabular sections are named in the plural, enumerations and structures in the singular (naming/number). This is morphology, not a guess by the ending: a singular noun that the standard allows is told apart from a plural that reads as a genitive singular without the case. Needs the [morph] extra (pip install "xbsl[morph]"); without it the rule stays silent.

The rest: the letter yo and underscores in names, an abbreviation written in mixed case instead of all caps, an English term transliterated rather than kept as the original (Xml, not its Cyrillic spelling), an enumeration named with the word for type where the standard asks for the word for kind, the element kind repeated inside its own name, filler words such as the ones for management or manager, an environment suffix on a common module name (the environment is a property, not a name), a boolean attribute named by a negation instead of the positive form, an empty Presentation, and the prefixes required for certain kinds - access key, right and navigation.

Code style conventions (the style/ rules)

Twenty-one rules that follow the platform documentation (“Code style conventions” and “Language idioms”): layout and expression wrapping, naming, type descriptions and signatures, collection literals, string interpolation, and checks of boolean values and Undefined.

Rules that clean code already satisfies are enabled by default (warning) – they guard against regressions. Rules that typically fire on accumulated legacy debt are info and disabled; enable them to measure the debt and pay it down:

xbsl path/to/sources --select style     # ONLY these rules (replaces the default set)
xbsl path/to/sources --enable style     # the default set PLUS these
xbsl path/to/sources --ignore style     # the default set minus these

--select, --enable and --ignore accept a rule id, a group (the part before /) or a tier letter, repeated or comma-separated. --select narrows to exactly the given rules; --enable switches on off-by-default rules on top of the defaults.

Query{ ... } blocks (the query DSL) and string literals (HTML/CSS/SVG in web views) are excluded from these checks. Not covered, and left to the author and review: indentation being a multiple of four, collection idioms, Rows.Join() for bulk concatenation, the ?. / ?? idioms, and case instead of an else if chain.

Enabling and disabling

--select and --ignore accept a rule identifier, a group (the part before /, e.g. style) or a tier letter A/B/C/D. A plugin may override a rule’s severity (the xbsl.severity entry-points group); XBSL_NO_PLUGINS=1 disables plugins and restores the built-in values from this table.