petrowsky/fmlint

FMLint — FileMaker Code Linter

Validate FileMaker scripts for structural correctness, naming conventions, reference integrity, best practices, and calculation validity.

---

Step 1: Determine what to lint

Identify the target:

1. Just-generated script — lint the file in agent/sandbox/ that was most recently written
2. Specific file — lint a file the developer names explicitly
3. All sandbox files — lint everything in agent/sandbox/
4. HR script text — lint human-readable script content directly (from webviewer or clipboard)

---

Step 2: Run FMLint

Run the linter from the project root:

# Lint a specific file
python3 -m agent.fmlint agent/sandbox/MyScript.xml

# Lint all sandbox XML files
python3 -m agent.fmlint agent/sandbox/

# JSON output (for programmatic use)
python3 -m agent.fmlint --format json agent/sandbox/MyScript.xml

# Force tier or disable rules
python3 -m agent.fmlint --tier 2 --disable N003,D002 agent/sandbox/

The linter auto-detects:

• Format (XML vs HR) from file content
• Tier from available context (CONTEXT.json → tier 2, OData → tier 3)

---

Step 3: Interpret results

Severity levels

| Level | Meaning | Action | |-------|---------|--------| | ERROR | Will break in FileMaker | Must fix before deployment | | WARNING | Likely bug or convention violation | Should fix | | INFO | Style suggestion | Optional improvement | | HINT | Minor recommendation | Informational only |

Rule categories

| Prefix | Category | Tier | Examples | |--------|----------|------|----------| | S | Structure | 1 | Block pairing, XML well-formedness, step attributes | | N | Naming | 1 | Unicode operators, variable naming, hard tabs | | D | Documentation | 1 | PURPOSE comment, $README block | | B | Best Practices | 1 | Error capture pairing, commit before nav | | C | Calculations | 1/3 | Unclosed strings, unbalanced parens, live eval | | R | References | 2 | Field/layout/script existence, ID matching |

---

Step 4: Fix issues

For each ERROR or WARNING:

1. Read the diagnostic message and rule ID
2. Apply the fix (the fix_hint field suggests how)
3. Re-run the linter to verify the fix

Common fixes:

• S005 (paired blocks): Add missing End If / End Loop / Commit Transaction
• N001 (operators): Replace <> with ≠, <= with ≤, >= with ≥
• N002 (variable naming): Use $camelCase, $$ALL_CAPS, ~camelCase
• N004 (hard tabs): Replace leading spaces with tab characters in CDATA calculations
• D001 (purpose): Add # PURPOSE: description as the first step

---

Step 5: Tier 3 — Live calculation validation (optional)

When OData is configured in agent/config/automation.json and the developer approves:

1. The linter extracts all calculation expressions from the script
2. Calls AGFMEvaluation via OData for each unique expression
3. Reports C004 errors for calculations that fail in the FM engine

Important: Always confirm with the developer before triggering OData calls:

FMLint found N calculations to validate against the live FM engine. Proceed?

This catches issues that offline analysis cannot — invalid field references, nonexistent custom functions, context-dependent calculation failures.

---

Step 6: Integration with script creation workflow

When used as part of the standard script creation workflow (CLAUDE.md steps 6-7):

1. After writing fmxmlsnippet to agent/sandbox/, run:

   python3 -m agent.fmlint agent/sandbox/<script_name>
   

2. Fix any ERROR-level diagnostics before deployment
3. Review WARNING-level diagnostics with the developer
4. Proceed to deploy.py only after errors are resolved

The linter replaces validate_snippet.py as the primary validation tool while maintaining backward compatibility — validate_snippet.py continues to work for its original XML-only checks.