Write Lint Rules

Writing Custom Starlark Lint Rules

Custom lint rules are written in Starlark (a Python-like language) and placed in .claude/lint-rules/ as .star files. They run alongside the built-in rules when mxcli lint -p app.mpr is executed.

Rule File Structure

Every .star file must define metadata constants and a check() function:

RULE_ID = "CUSTOM001"          # unique identifier
RULE_NAME = "MyRule"           # Short display name
DESCRIPTION = "What it checks" # One-line description
CATEGORY = "security"          # Category: naming, quality, design, security, etc.
SEVERITY = "warning"           # hint, info, warning, error

def check():
    violations = []
    # ... iterate data, find issues, append violations ...
    return violations

Catalog data requirements (widgets, refs_to, cycles, …)

Some builtins need a deeper catalog than the default fast build:

• refs_to, refs_from, widgets, xpath_expressions, activities_for, permissions, permissions_for, strings and the widget_count field of a page or snippet need REFRESH CATALOG FULL — the refs, widgets, xpath_expressions, activities, permissions and strings tables and the widget counts are only written by a full build.
• The graph-analysis builtins (cycles, module_dependencies, community_of, layer_of, centrality, god_nodes, integration_surface) need REFRESH CATALOG COMMUNITIES (the graph_* tables).

You don't have to do anything: mxcli lint (and the LINT statement) auto-detect these builtins (a call name() and .widget_count in your rule's source and build the catalog at the required depth automatically. If the scan cannot see it — e.g. getattr(p, "widget_count"), or a builtin passed around by name — or you want to be explicit, declare it:

REQUIRES = ["full"]          # or ["communities"] — raises the auto-detected depth

Without this, a rule that reads a full-only table under a fast build gets [] / 0 with no warning and reports a clean pass (issue #721).

Available Query Functions

The fields of module, association, entity_event_handler, navigation_menu_item, jar_dependency, catalog_string, layout and published_rest_operation are in catalog-tables.md.

Graph-analysis functions (architecture rules)

These expose the dependency-graph facts so you can enforce your own architecture policy (layering, allowed module dependencies, no cycles, coupling budgets). They require refresh catalog communities to have populated the graph tables; otherwise they return empty/None (the rule degrades gracefully — it does not fail). In a session, run refresh catalog communities before lint.

Example — a team enforcing its own strict layering (mxcli ships no such rule):

RULE_ID = "ARCH900"
RULE_NAME = "Layering"
DESCRIPTION = "A module may only depend on lower or equal layers"
CATEGORY = "architecture"
SEVERITY = "error"

def check():
    out = []
    for d in module_dependencies():
        if d.ref_kind in ("layout", "show_page"):  # ignore UI navigation
            continue
        ls, lt = layer_of(d.source_module + ".x"), layer_of(d.target_module + ".x")
        # (resolve a real asset per module in practice; shown simplified)
        if ls != None and lt != None and ls < lt:
            out.append(violation(message = "%s depends upward on %s" % (d.source_module, d.target_module)))
    return out

Another team bans a specific dependency:

def check():
    return [violation(message = "Payments must not depend on Reporting")
            for d in module_dependencies()
            if d.source_module == "Payments" and d.target_module == "Reporting"]

Object Properties

The example values below are the real ones — do not adapt their case or their spelling. A filter on a value the catalog never emits is silent: the rule compiles, runs, matches nothing and reports a clean pass. Two traps in particular:

• Case is not cosmetic. Document and element kinds are upper-case ("MICROFLOW", "ENTITY", "READ"), attribute data types are TitleCase ("String", "DateTime"), and ref_kind is lower-case ("call", "show_page"). Guessing wrong matches zero rows.
• action_type is the SDK name, never Mendix's BSON storage name. The catalog reports ShowPageAction / ClosePageAction / CreateObjectAction / CommitObjectsAction; the storage names ShowFormAction, CloseFormAction, CreateChangeAction and CommitAction that appear in .mpr documents never reach a rule. A rule that allow-lists the storage names flags every microflow that opens a page — the inversion measured at 49% false positives in mendixlabs/mxcli#1027. The one exception is widget.action_type, which is the raw stored type of a page action ("Forms$DeleteClientAction") — page actions have no SDK-name mapping in the catalog.

To check a value against your own project rather than trusting any list:

sqlite3 .mxcli/catalog.db "SELECT DISTINCT ActionType FROM activities;"
sqlite3 .mxcli/catalog.db "SELECT DISTINCT SourceType, TargetType, RefKind FROM refs;"

Absence from your project means the construct is not used there; a value absent from the tables below is one the catalog never produces anywhere.

entity

microflow

page

enumeration

constant

widget — the struct returned by widgets() — identity, references, tree position (parent_widget_id, depth), appearance (class_name, style) and primary action (action_type, has_confirmation) — is documented in catalog-tables.md, with an example rule.

snippet

scheduled_event

queue

java_action

java_action_parameter (nested in java_action)

database_connection

document

Returned by documents().

documentable

Returned by documentable_elements().

navigation_target

Returned by navigation_targets().

xpath_expression

Returned by xpath_expressions(). Each row represents one XPath constraint used in a retrieve action, access rule, or widget data source.