Skip to content

diagnostics.md

Latest commit

 

History

History
558 lines (391 loc) · 10 KB

diagnostics.md

File metadata and controls

558 lines (391 loc) · 10 KB

Diagnostics & Validation

← Back to Documentation Home

Real-time error detection and code validation as you type.

Overview

The Clarion Extension provides real-time diagnostics:

  • Immediate feedback - Errors highlighted as you type
  • Squiggly underlines - Visual indicators in code
  • Problems panel - List of all issues
  • Hover for details - Error descriptions on hover
  • Quick fixes - Suggested solutions (where applicable)

Supported Diagnostics

Structure Validation

Unterminated Structures

Detects missing END statements:

IF x = 1 THEN
  DoSomething()
  ! ❌ Error: Missing END

Structures checked:

  • IF/THEN → requires END
  • LOOP → requires END
  • CASE/OF → requires END
  • EXECUTE → requires END
  • BEGIN → requires END
  • CLASS → requires END
  • GROUP → requires END
  • MAP → requires END
  • MODULE → requires END

Error message:

Unterminated IF structure
Expected END statement

Mismatched Terminators

Detects wrong termination keywords:

IF x = 1 THEN
  DoSomething()
UNTIL   ! ❌ Error: Expected END, got UNTIL

RETURN Statement Validation

Missing RETURN in PROCEDURE

Detects procedures without RETURN:

MyProc PROCEDURE
CODE
  x = 10
  ! ❌ Warning: Missing RETURN statement

Note: Not required for ROUTINE blocks.

Multiple RETURN Paths

Validates all code paths have RETURN:

MyProc PROCEDURE
CODE
  IF condition
    RETURN  ! ✅ OK
  ELSE
    x = 10
    ! ❌ Warning: Missing RETURN in ELSE branch
  END

FILE Validation

Missing DRIVER Attribute

FILE declarations must have DRIVER:

MyFile FILE
Record   RECORD
         END
       END    ! ❌ Error: FILE missing DRIVER attribute

Should be:

MyFile FILE,DRIVER('TOPSPEED'),CREATE
Record   RECORD
         END
       END    ! ✅ OK

Missing RECORD Structure

FILE declarations must have RECORD:

MyFile FILE,DRIVER('TOPSPEED')
       END    ! ❌ Error: FILE missing RECORD definition

Should be:

MyFile FILE,DRIVER('TOPSPEED')
Record   RECORD
Field      LONG
         END
       END    ! ✅ OK

CASE/EXECUTE Validation

Invalid CASE Clauses

Only OF/OROF allowed in CASE:

CASE x
  OF 1
    DoSomething()
  ELSE         ! ❌ Error: ELSE not allowed in CASE (use OROF)
    DoOther()
END

Should be:

CASE x
  OF 1
    DoSomething()
  OROF 2 TO 10  ! ✅ OK
    DoOther()
END

Invalid EXECUTE Clauses

Only BEGIN allowed in EXECUTE:

EXECUTE choice
  OF 1
    DoSomething()  ! ❌ Error: Use BEGIN instead of OF in EXECUTE
END

Should be:

EXECUTE choice
  BEGIN
    DoSomething()  ! ✅ OK
  END
END

OMIT/COMPILE Block Validation

Unterminated OMIT Block

Detects missing OMIT terminator:

OMIT('DEBUG')
  DebugCode()
  ! ❌ Error: Missing OMIT terminator

Should be:

OMIT('DEBUG')
  DebugCode()
!   ! ✅ OK

Unterminated COMPILE Block

Detects missing COMPILE terminator:

COMPILE('DEBUG')
  DebugCode()
  ! ❌ Error: Missing COMPILE terminator

Reserved Keyword Usage

Detects user-defined labels that clash with Clarion reserved keywords:

LOOP LONG  ! ❌ Error: 'LOOP' is a reserved keyword and cannot be used as a label

Discarded Return Values

Warns when a procedure with a return type is called but the result is discarded:

MAP
  GetCount(), LONG
END

CODE
  GetCount()   ! ⚠️ Warning: Return value of GetCount() is discarded
  x = GetCount()  ! ✅ OK

Note: Only applies to plain MAP/MODULE procedures, not class methods.

BREAK/CYCLE Outside Loop

Detects control flow statements used in invalid context:

MyProc PROCEDURE
CODE
  BREAK    ! ❌ Error: BREAK must be inside a LOOP or ACCEPT block
  CYCLE    ! ❌ Error: CYCLE must be inside a LOOP or ACCEPT block

Missing INCLUDE Diagnostic

Detects variables whose class type is defined in an .inc file that isn't included:

st   StringTheory    ! ⚠️ Warning: 'StringTheory' is defined in 'StringTheory.inc' which is not included.
af   &FileManager    ! ⚠️ Warning: 'FileManager' is defined in 'ABFile.inc' which is not included.

How it works:

  • Checks global-scope variable declarations (column 0) whose type is a known CLASS or INTERFACE
  • Walks the full transitive include chain (any depth, cycle-safe) — a type included via A.inc → B.inc is correctly resolved
  • Also checks the MEMBER parent file's includes if the current file has a MEMBER('parent.clw') statement

Quick fix (Ctrl+.):

  • Add INCLUDE to this file — inserts INCLUDE('type.inc'),ONCE at module scope
  • Add INCLUDE to MEMBER parent — inserts into the parent .clw file instead
  • Add INCLUDE + constants — inserts the include and any missing DefineConstants entries in one step

Missing DefineConstants Diagnostic

Detects class types whose .inc is present but required Link()/DLL() constants are missing from the project:

st   StringTheory    ! ℹ️ Info: 'StringTheory' requires project constants that are not defined: ST_LinkMode, ST_DllMode

This fires as Information severity (blue squiggle) — the code compiles but will link or run incorrectly without the constants.

Quick fix (Ctrl+.):

  • Add Link constants — QuickPick prompts: Static link (LinkMode=>1, DllMode=>0) or DLL mode (LinkMode=>0, DllMode=>1). Adds the chosen constants to DefineConstants in the .cwproj.

The diagnostic clears immediately once the constants are added (the extension watches the .cwproj file for changes).

Viewing Diagnostics

In-Editor Indicators

Squiggly underlines:

  • Red squiggles - Errors
  • Yellow squiggles - Warnings
  • Blue squiggles - Information

Hover for details:

  • Place mouse over squiggle
  • Tooltip shows error message
  • May include suggested fix

Problems Panel

View all issues:

  1. Press Ctrl+Shift+M
  2. Or: View → Problems

Shows:

  • File name and path
  • Line and column number
  • Error severity (Error/Warning/Info)
  • Error message

Click to navigate:

  • Click any problem in list
  • Editor jumps to that line
  • Squiggle highlighted

Status Bar

Bottom-left shows issue count:

❌ 2  ⚠️ 3  ℹ️ 1
  • ❌ - Errors
  • ⚠️ - Warnings
  • ℹ️ - Information

Click count to open Problems panel

Error Severity Levels

Errors (Red)

Critical issues that prevent compilation:

  • Unterminated structures
  • Missing required attributes (DRIVER, RECORD)
  • Invalid syntax

Must be fixed before application can be built.

Warnings (Yellow)

Issues that may cause problems:

  • Missing RETURN statements
  • Unreachable code
  • Questionable patterns

Should be reviewed but won't prevent compilation.

Information (Blue)

Suggestions and hints:

  • Code style recommendations
  • Optimization opportunities
  • Best practice hints

Optional to fix.

Configuration

Enable/Disable Diagnostics

Turn all diagnostics off:

{
  "clarion.diagnostics.enabled": false
}

Disable Specific Validations

Structure validation:

{
  "clarion.diagnostics.validateStructures": false
}

FILE validation:

{
  "clarion.diagnostics.validateFiles": false
}

RETURN validation:

{
  "clarion.diagnostics.validateReturns": false
}

Adjust Severity Levels

Make warnings errors:

{
  "clarion.diagnostics.missingReturn": "error"  // Default: "warning"
}

Suppress warnings:

{
  "clarion.diagnostics.missingReturn": "information"
}

Unreachable Code Detection

What It Does

Visually dims code that cannot be executed:

MyProc PROCEDURE
CODE
  IF condition
    RETURN
  END
  
  x = 10      ! ← Dimmed (unreachable after RETURN)
  RETURN

Detected patterns:

  • Code after unconditional RETURN
  • Code after unconditional EXIT
  • Code after unconditional HALT

How It Works

Scope-aware detection:

  • Only dims code at top execution level
  • ROUTINE blocks always considered reachable
  • Respects Clarion semantics (STOP is not a terminator)

Visual effect:

  • 40% opacity dimming
  • Non-intrusive
  • Zero false positives

Configuration

Disable unreachable code detection:

{
  "clarion.unreachableCode.enabled": false
}

Best Practices

Fix Errors First

  1. Address red squiggles (errors) before warnings
  2. Errors prevent compilation, warnings don't
  3. Use Problems panel to see all errors at once

Review Warnings

  1. Warnings indicate potential issues
  2. May cause runtime problems
  3. Consider fixing before production

Use Diagnostics as You Code

  1. Don't wait until end to check errors
  2. Fix issues as they appear
  3. Faster than debugging later

Troubleshooting

False Positives

If diagnostic is incorrect:

  1. Check code syntax is valid
  2. Verify structure termination
  3. Report issue on GitHub if bug confirmed

Workaround: Disable specific validation temporarily

Missing Diagnostics

If errors not detected:

  1. Check clarion.diagnostics.enabled is true
  2. Verify file extension is .clw, .inc, or .equ
  3. Reload window: Ctrl+Shift+P → "Developer: Reload Window"

Performance Impact

If diagnostics slow down editor:

  1. Disable validations you don't need
  2. Larger files take longer to validate
  3. Consider disabling for very large files (10K+ lines)
{
  "clarion.diagnostics.validateOnChange": false  // Validate on save only
}

Related Features