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 191 rules.

The table describes the toolkit as it ships. An installed plugin may add rules of its own and override severities and default states (see Extending), so the runtime list can differ from this one – xbsl --list-rules shows what your environment actually runs, and XBSL_NO_PLUGINS=1 shows the set below.

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).

The engine DOES infer the type of an expression - xbsl.typeinfer answers for a receiver, a member, a constructor, a cast and a non-null operator, and the inference of chains and locals feeds hover and completion in the editor. The checks do not rest on it: the rules judge by the declared types - see below on what the linter does not do.

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, a leaked resource in the general case, whether the TYPE of a returned value matches the signature. Two of those are worth separating. A structural return 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. And a resource is judged only in the one shape where the declaration itself says everything: code/unclosed-resource follows a closeable from its declaration to the loop over it in the same method; a resource that travels through calls or collections stays out of reach.

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.
• Level – error (a build and CI should fail), warning (a convention is broken), info (a hint, usually off).
• Default – ✓ the rule is in the default set, – it is enabled explicitly.
• Scope – file (the rule sees one file) or project (needs the whole-project index: duplicate Ids, unknown types, cross-module calls).
• The link at the end of a description – 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.

Reading the columns: error · warning · info; ✓ – in the default set, – turned on explicitly; the scope is one file or the whole project.

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)

Four 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). For a Russian name 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 Russian names stay silent. An English name (a translated tree) is judged by its last word with suffix heuristics and the irregular plurals listed, and needs no extra; mass nouns and ambiguous tails are left undecided.

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-eight rules that follow the platform documentation (“Code style conventions”, “Language idioms”) and the “Variable and constant names” development standard: layout and expression wrapping, naming, type descriptions and signatures, collection literals, string interpolation, and checks of boolean values and Undefined.

Of the variable-names standard the token-provable part is checked: abstract names, single-letter names outside lambdas, Cyrillic and Latin abbreviations not written as one word, boolean names built from the negation, a container type inside a name, numerals inside constant names, and the shadowing of project element names. Left to the author and review: redundant words in a name, abbreviations beyond the capitalization law, digits in place of a qualifier over a meaningful stem (Stage1 and Data1 differ only in meaning), and the abstractness of a constant name beyond numerals (the role of INITIAL_STAGE against the value of STAGE_QUESTIONNAIRE is invisible to tokens).

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.

Code semantics (the code/ rules)

The largest group - sixty-four rules, thirty-four of them errors. This is what the compiler rejects or what the platform does differently from how the code reads: an unknown name or member, the arity of a call, the environment (client code in a server method and the other way round), an instance reached through its type, a caught non-exception, an unclosed resource, a walk over a collection while it is being changed, and the platform traps whose only sign is the shape of the code. Some of the rules are project-scoped (--stdin does not run those): they need the paired yaml and the names of the objects.

Element descriptions (the yaml/ rules)

Fifty-seven rules over the descriptions (.yaml): required and unique ids, known keys and types, references to components, handlers and localized strings, what the platform requires of field types (a reference and an enumeration admit an empty value), the settings of dynamic lists and forms, and the layout traps that apply without an error yet draw differently from the intent. Six rules are info and off: they say “this is how the platform works”, not “this is a mistake”.

Project conventions (the conventions/ rules)

Rules about what the PROJECT agreed on rather than what the platform demands. The base set carries the bilingual-project family: conventions/untranslated-visible-literal (on by default) reports visible text left as a Cyrillic literal where the project already routes the same property through the localization dictionary, and conventions/untranslated-code-literal with conventions/missing-translation (both off) extend that to module literals and to the translation dictionary - whether every human-readable string must come from the dictionary is a per-project decision, so the base set does not impose it.

The group is also the extension point by design: a project plugin registers its own house rules under conventions/ (a ban on task numbers in comments, internal references and the like) and decides their severity and defaults for that project - see Extending. Runtime truth is xbsl --list-rules; the table above lists the base set only.

The small groups

• typography/ - typographic characters in prose and comments: em dash, the ellipsis character, curly quotes, guillemets in comments, plus the letter “ё” in the text a user reads;
• whitespace/ - trailing spaces and mixed newlines;
• encoding/ - a file that is not UTF-8;
• structure/ - the pairing of Name.yaml and Name.xbsl;
• security/ - a secret in the sources (a token, a password, a key);
• form/ - a form handler the module does not have, and a handler whose signature contradicts the event of the component (project-scoped rules);
• query/ - queries: an unknown table, ISNULL, a named parameter, an immediate deletion mark and the standard about IN with a subquery (discussed above).

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.