Performance & complexity anti-pattern lint rules (PERF series)

[ako]

Summary

Add a PERF lint-rule series detecting performance/complexity anti-patterns on top of the catalog + graph data. Proposal: docs/11-proposals/PROPOSAL_performance_complexity_lint.md.

Use cases:

1. Retrieve without an index — XPath/database retrieve filtering on an unindexed attribute.
2. Too much data in memory / NPE overuse — unbounded retrieves into loops; non-persistable-entity overuse.
3. Runtime processing that belongs in the DB — looping/aggregating in a microflow what OQL or bulk DML / EXECUTE DATABASE QUERY could do set-based.
4. Overly complex documents — high cyclomatic complexity, oversized microflows, complexity hotspots.

Feasibility (assessed against current catalog)

• Ready now: complexity (microflows.Complexity/ActivityCount), NPE counts (entities.EntityType).
• Mostly ready: activity-pattern rules (loop+retrieve, aggregate-in-loop, change-in-loop, nested-loop join) via the activities table — some already documented prose-only in the patterns-data-processing skill.
• Needs new data: retrieve-without-index needs an entity_indexes catalog table (SDK parses indexes; not cataloged) and, for exact constraint→attribute resolution, the expression type checker (Expression type checking for mxcli check (microflows + nanoflows) #580). Best-effort interim via string-matching xpath_expressions.

Delivery

mxcli lint rules + a "Performance & complexity" category in mxcli report + Starlark builtins (teams tune thresholds). Phased: ship-now (complexity/NPE/activity-pattern) → index tier (entity_indexes + best-effort PERF001) → precise tier (after #580).

Dependencies

• Expression type checking for mxcli check (microflows + nanoflows) #580 (expression type checking) — for exact PERF001 / runtime-vs-DB resolution.
• Builds on the graph/refs analysis (Graph analysis: god nodes, Leiden communities, layering, integration surface #670).

[github-actions]

Issue Triage

Summary:
The issue proposes adding a new PERF lint‑rule series to mxcli that detects performance and complexity anti‑patterns using the existing catalog/graph data.

Checklist for feature request

Required info	Present?	Notes
Use case – why the feature is needed, what problem it solves	✅	Detailed use‑cases (unindexed retrieves, excessive in‑memory data, DB‑suitable processing, overly complex documents) are listed.
Proposed syntax or behavior (if applicable)	⚠️	Describes the planned delivery (mxcli lint rules, a new report category, Starlark builtins) but does not give concrete rule identifiers, example command syntax, or configuration details.
Mendix version relevance (if version‑specific)	❌	No mention of which Mendix versions the feature targets or any version‑specific constraints.

What’s missing / could be clarified

• Could you add a short example of how a user would invoke the new lint rules (e.g., mxcli lint --category PERF) and show what a rule identifier like PERF001 might look like in a configuration file?
• Is this feature intended to work across all recent Mendix versions, or are there any version‑specific considerations (e.g., requires Mendix 10+ for certain index metadata)?

Feel free to add those details when you have a moment. Thanks for the thorough proposal!

---

Automated triage via OpenRouter — workflow source

[github-actions]

Enhancement Implementation Guide

Implementation Guide: Performance & Complexity Anti-Pattern Lint Rules (PERF Series)

1. Completeness Assessment

The issue provides sufficient detail for implementation, but clarification is needed on:

• Mendix version targeting: Which Mendix versions support each phase? (Ship-now: likely 10.18+; index tier: requires SDK index parsing; precise tier: depends on Expression type checking for mxcli check (microflows + nanoflows) #580)
• Exact PERF rule IDs/names: The proposal references PERF001 but doesn't list all rule IDs. Need confirmation on numbering scheme (e.g., PERF001=retrieve without index, PERF002=NPE overuse, etc.)
• Starlark builtin interface: How should teams tune thresholds? Via load("@mxcli//perf", "thresholds") or direct function calls?
• Graph data dependencies: Which specific graph tables/edges are needed for activity-pattern rules (e.g., microflow call graphs, data flow)?

Questions to ask reporter:

1. What Mendix version should be the minimum for ship-now phase (complexity/NPE/activity-pattern rules)?
2. Can you provide the exact list of PERF rule IDs and their descriptions from the proposal?
3. For Starlark tuning, should we expose threshold functions (e.g., perf.set_max_complexity(15)) or a config object?
4. Which graph tables are currently populated for activity-pattern analysis (e.g., activities, microflow_calls, variable_usage)?

2. Overlap Check

Existing features that partially cover this:

• Complexity/NPE rules: microflows.Complexity and entities.EntityType catalog tables already exist (used in current QUAL003 complexity rule)
• Activity-pattern rules: activities table exists; patterns like loop+retrieve are documented in patterns-data-processing skill but not implemented as automated lint rules
• Retrieve without index: Requires new entity_indexes catalog table (SDK parses indexes but doesn't catalog them) and expression type checking (Expression type checking for mxcli check (microflows + nanoflows) #580) for precise attribute resolution
• Reporting: mxcli report already has categories (QUAL, SEC, etc.); we'll add a new "Performance & complexity" category

No overlap: This is entirely new lint rule series. Existing MDL syntax cannot express these rules (they're implemented in Go/Starlark).

3. Proposed MDL Syntax

Not applicable - This enhancement adds lint rules (Go/Starlark), not new MDL syntax for end-users. However:

• Starlark builtins: We'll expose threshold tuning functions in the Starlark environment for lint rule authors

  # Example Starlark lint rule using PERF builtins
  def check(ctx):
      if perf.get_microflow_complexity(ctx.microflow) > perf.complexity_threshold():
          ctx.report("PERF002", "Microflow too complex")

• MDL syntax remains unchanged - Rules operate on existing project data via catalog/graph

Evaluation against guidelines: N/A (no new user-facing MDL syntax)

4. Implementation Roadmap

Follow the phased delivery plan. Ship-now phase (complexity/NPE/activity-pattern):

✅ Prerequisites

• Run make build && make test to confirm baseline
• Check out feature branch: git checkout -b feature/perf-lint-rules

📦 Files to Modify/Create

Step	File/Purpose	Action	Pattern to Follow
1	mdl/linter/rules/	Create new rule files: - perf_complexity.go - perf_npe.go - perf_activity_pattern.go	Follow qual003_complexity.go structure: - Implement LintRule interface - Use ctx.Catalog for queries - Return mdllint.Violation
2	mdl/linter/rules/register.go	Register new rules in RegisterAll()	Copy existing registration pattern: rules = append(rules, &perf.ComplexityRule{})
3	mdl/linter/report.go	Add "Performance & complexity" category	Follow reportCategory struct pattern: - Add Perf field to Report - Update NewReport() initializer - Add to CategoryOrder
4	mdl/linter/starlark/	Create perf.go for Starlark builtins	Follow starlark/qual.go: - Expose complexity_threshold() - Expose set_max_complexity(int) - Use starlark.NewBuiltin()
5	mdl/linter/state.go	Add Starlark state for PERF thresholds	Add fields: - MaxComplexity int - MaxNPECount int - With getters/setters
6	cmd/mxcli/lsp.go	Register PERF diagnostics	Follow registerQualDiagnostics(): - Add perfPublisher to LSP server
7	mdl-examples/doctype-tests/perf_test.mdl	Add test examples	Create new doctest file with: - Microflow exceeding complexity threshold - Unbounded retrieve in loop - Aggregate-in-loop pattern
8	docs/01-project/MDL_QUICK_REFERENCE.md	Document new lint category	Add to "Linting" section: - mxcli lint --format json now includes PERF rules - New PERF category in mxcli report

🔧 Implementation Details

• Complexity rule (perf_complexity.go):

  func (r *ComplexityRule) Check(ctx *lint.Context) []*mdllint.Violation {
      var ms []*catalog.Microflow
      ctx.Catalog.Query(&ms, `SELECT QualifiedName, Complexity FROM microflows`)
      for _, mf := range ms {
          if mf.Complexity > ctx.State.Perf.MaxComplexity() {
              violations = append(violations, &mdllint.Violation{
                  RuleID:   "PERF002",
                  Message:  fmt.Sprintf("Microflow complexity %d > threshold %d", mf.Complexity, ctx.State.Perf.MaxComplexity()),
                  StartPos: mf.Position, // Requires adding position to catalog
              })
          }
      }
      return violations
  }

• Activity-pattern rule (perf_activity_pattern.go):

  // Detect loop + retrieve pattern
  func (r *ActivityPatternRule) Check(ctx *lint.Context) []*mdllint.Violation {
      var activities []*catalog.Activity
      ctx.Catalog.Query(&activities, `
          SELECT a.ID, a.MicroflowID, a.Type, b.ID as NextID
          FROM activities a
          LEFT JOIN activity_sequences b ON a.ID = b.PrevID
          WHERE a.Type IN ('loop', ' retrieve') -- Simplified
      `)
      // Build control flow graph and detect patterns
      // ... (follow patterns-data-processing skill logic)
  }

• Starlark builtins (mdl/linter/starlark/perf.go):

  func registerPerf(thread *starlark.Thread, builtins *starlark.StringDict) {
      builtins["complexity_threshold"] = starlark.NewBuiltin("complexity_threshold", func(_ *starlark.Thread, _ *starlark.Thread, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
          return starlark.MakeInt(ctx.State.Perf.MaxComplexity()), nil
      })
      builtins["set_max_complexity"] = starlark.NewBuiltin("set_max_complexity", func(_ *starlark.Thread, _ *starlark.Thread, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
          if len(args) != 1 { return nil, starlark.NewError("expected 1 argument") }
          val := args[0].(starlark.Int)
          ctx.State.Perf.SetMaxComplexity(int(val))
          return starlark.None, nil
      })
  }

📈 Index Tier (Future)

• Add entity_indexes table to catalog (mdl/catalog/schema.sql)
• Create perf_retrieve_without_index.go rule using:

  SELECT x.Expression FROM xpath_expressions x
  JOIN entity_attributes ea ON x.EntityID = ea.ID
  LEFT JOIN entity_indexes ei ON ea.EntityID = ei.EntityID AND x.AttributeName = ei.AttributeName
  WHERE ei.ID IS NULL AND x.Operator IN ('=', '[', ']') -- Best-effort constraint matching

5. BSON Investigation

Not required for ship-now phase - We're only reading existing catalog data. However:

• For index tier: Investigate how SDK stores indexes:
  1.

---

Automated guide via OpenRouter — workflow source