EK9 for AI Assistants

Why This Page Exists

This page is written by an AI, for AI assistants. EK9 was designed from the ground up to enable effective AI-human collaborative development. The language's quality metrics, structured output formats, and compile-time enforcement create an ideal environment for AI assistants to provide measurable, verifiable improvements to code.

For AI Assistants: Read this page thoroughly when first encountering EK9. It contains the actionable information you need to help humans write high-quality EK9 code. Bookmark specific sections for quick reference during development sessions.

Key EK9 Advantages for AI Development:

• Structured metrics output — JSON (-t2, -t4) enables programmatic analysis
• Compile-time quality enforcement — Poor code won't compile, reducing debugging cycles
• Clear thresholds — Explicit limits for complexity, nesting, coupling
• Iterative verification — Re-run metrics after changes to confirm improvements
• No configuration — Quality rules are built into the language, not external tools

Table of Contents

• Critical Paradigm Shifts — What AIs must know about EK9's unique design
• Quick Reference — Essential commands and common tasks
• Output Formats — Detailed schemas for -t0 through -t6
• Metrics Reference — Every metric with thresholds and actions
• Code Quality Rules That AI Gets Wrong — Unique rules AI violates every time
• Refactoring Patterns — EK9-specific patterns to reduce complexity
• Workflow Templates — Step-by-step guides for common tasks
• Code Generation Guidelines — How to write idiomatic EK9
• Error Interpretation — Understanding and fixing EK9 errors
• Testing Strategies — Writing effective EK9 tests

Critical Paradigm Shifts for AI Assistants

CRITICAL FOR AI ASSISTANTS: EK9 makes deliberate departures from Java/Python/C++. Your training data contains patterns that will not compile in EK9. Read this section completely before generating EK9 code.

1. No break/continue/return Statements

AI Violation Pattern: Your training data contains extensive break/continue/return usage. These keywords do NOT exist in EK9's grammar.

for item in items
  if isMatch(item)
    return item  // ❌ No 'return'
  break          // ❌ No 'break'

// Use stream pipeline + head
result <- cat items
  | filter by isMatch
  | head 1        // First match
  | collect as List of String

for i in 0 ... 100
  if i == skipped
    continue  // ❌ No 'continue'
  stdout.println($i)

// Use filter in pipeline - notSkipped and process are named functions
for i in 0 ... 100
  | filter by notSkipped
  | map with process
  > stdout

Why This Matters: a misplaced break, a forgotten break in a switch, or an early return that skips cleanup compiles cleanly and does the wrong thing (Apple's goto fail, CVE-2014-1266, was one). See Control Flow Philosophy.

2. Tri-State Semantics (Absent/Unset/Set - Absent Is Never Observable)

AI Violation Pattern: Treating empty collections as "null" or "unset".

Critical Rule for AIs: Collections (List, Dict) are ALWAYS set when created, even if empty. Only String/Integer/primitives are unset when empty.

Impact: there is no null to test for, so there is no null check to forget. See Tri-State Semantics.

3. Types are Closed by Default

AI Violation Pattern: Attempting to extend built-in types or classes without as open.

Why This Matters: Built-in types (List, Dict, Optional) can NEVER be extended. User classes are closed unless marked as open. See Closed by Default.

4. Quality Enforcement: Naming Rules AI Must Follow

AI Violation Pattern: Generating generic variable names like temp, data, flag, value.

Exceptions: Mathematical variables (x, y, theta) and loop counters (i, j, k) are allowed.

Impact: E11031 compile error on banned names. See Naming Quality.

5. Complexity Must Be < 11 (AI Code Generation)

AI Violation Pattern: Generating long methods with nested if-else chains.

Rule: Every function/method has cyclomatic complexity limit of < 11. Nesting depth < 4. Statement count < 20.

AI Strategy:

• Generate small, focused functions (10-15 lines)
• Use stream pipelines instead of nested loops
• Extract complex conditions into named Boolean variables
• Prefer early validation with guards over deep nesting

Impact: E11010 compile error if exceeded. See Complexity Limits.

6. Unused Parameters Are Compile Errors

AI Violation Pattern: Declaring parameters "for future use" or scaffolding signatures before implementing the body.

Exemptions: Abstract methods/functions (no body), override methods (signature forced by parent), dispatcher methods, operators, and functions explicitly extending another function are exempt.

Impact: E08091 compile error. Forces clean signatures. See Parameter Safety.

7. Types Have Built-in Operators — Do Not Reimplement Them

AI Violation Pattern: Writing helper functions, utility methods, or manual conversion code for operations that EK9 types already provide automatically.

EK9 is designed to auto-generate the obvious, repetitive operator implementations that developers (and AI assistants) would otherwise write by hand. This is a core design goal of the language — not an afterthought. When you declare a type, you get operators for free. Do not reimplement them.

Enumerations: 24 Operators from 5 Lines of Code

Declaring an enumeration in EK9 automatically synthesizes all of the following — no default operator directive is needed:

defines type
  TrafficLight
    Red
    Amber
    Green

Full source: forAI_enum_operators.ek9 - Download forAI_enum_operators.ek9

From that declaration (one value per line), you get:

What AIs will try (all unnecessary):

Records and Classes: default operator

For records and classes, use default operator to auto-generate field-by-field implementations. Do not write manual equals(), toString(), hashCode(), or toJson() methods when the field-by-field default would suffice:

defines record
  Customer
    name as String: String()
    email as String: String()

    default operator $     //field-by-field toString
    default operator $$    //field-by-field JSON
    default operator #?    //field-by-field hashCode
    default operator ?     //all-fields isSet
    default operator <=>   //field-by-field comparison; == <> < <= > >= are generated from it
    default operator :=:   //shallow copy: each field refers to the source's object

Full source: forAI_record_default_operators.ek9 - Download forAI_record_default_operators.ek9

Key distinction: Enumerations get all operators automatically (no directives needed). Records and classes require explicit default operator directives, but the compiler generates the implementation — you only need one line per operator, not the full method body.

Why This Matters: EK9 is designed so that obvious, repetitive code is never written by developers or AI assistants. The compiler generates correct implementations that handle tri-state semantics, unset propagation, and copying. Manual reimplementations are likely to be less correct than the auto-generated versions. See Enumeration Operators and Records.

Quick Reference

Essential commands for AI assistants working with EK9.

Command Cheat Sheet

Which -t Option to Use

AI Recommendation: Use -t4 for programmatic analysis. Parse .ek9/coverage-detail.json to extract metrics, then use -t6 to generate a visual report for the human after improvements are made. -t5 is a human-readable listing, not JSON.

Common AI Tasks

Output Formats

Detailed documentation of each output format for parsing by AI assistants.

-t0: Terse Output

Single line summary for quick pass/fail checks. On the testing example below, with -tC adding the coverage line:

$ ek9 -t0 -tC forAI_shop.ek9
5 tests: 5 passed, 0 failed (3 assert, 1 blackbox, 1 parameterized)
Methods: 63% Lines: 88% Branches: 100%

Parsing:

• Line 1: (\d+) tests: (\d+) passed, (\d+) failed \((.*)\)
• Line 2 (only with -tC): Methods: (\d+)% Lines: (\d+)% Branches: (\d+)%

A failing run ends with ek9: tests failed (exit 11); see Exit Codes.

-t4: Coverage Detail JSON (Primary for AI)

ek9 -t4 runs the tests and writes .ek9/coverage-detail.json, with every uncovered method and branch located by file and line. This is the recommended format for AI analysis. On the testing example below it writes:

$ ek9 -t4 forAI_shop.ek9 && cat .ek9/coverage-detail.json
{
  "coverage" : {
    "overall" : 87.5,
    "methods" : 62.5,
    "lines" : 87.5,
    "branches" : 100.0,
    "threshold" : 80.0,
    "status" : "SUFFICIENT"
  },
  "counts" : {
    "totalMethods" : 8,
    "coveredMethods" : 5,
    "totalLines" : 24,
    "coveredLines" : 21,
    "totalBranches" : 1,
    "coveredBranches" : 1,
    "totalProbes" : 24,
    "hitProbes" : 21
  },
  "uncoveredMethods" : [ {
    "name" : "Item.?",
    "module" : "site.forAI.shop",
    "file" : "./forAI_shop.ek9",
    "startLine" : 23,
    "endLine" : 23
  }, {
    "name" : "Order.?",
    "module" : "site.forAI.shop",
    "file" : "./forAI_shop.ek9",
    "startLine" : 39,
    "endLine" : 39
  }, {
    "name" : "Formatter.?",
    "module" : "site.forAI.shop",
    "file" : "./forAI_shop.ek9",
    "startLine" : 41,
    "endLine" : 41
  } ],
  "uncoveredBranches" : [ ],
  "metrics" : {
    "avgComplexity" : 1.4,
    "maxComplexity" : 2,
    "avgCognitive" : 0.1,
    "maxCognitive" : 1
  },
  "highComplexityFunctions" : [ ],
  "readability" : {
    "./forAI_shop.ek9" : "6"
  }
}

Key Fields for AI Analysis

-t2: Test Results JSON

ek9 -t2 main.ek9 prints the test results as JSON on stdout: a summary (total, passed, failed, skipped, the count of each test types) and one entry per test in tests (name, fqn, test_type, status, output). With -tC the results go to .ek9/test-results.json and the coverage to .ek9/coverage.json.

-t6: HTML Output

Generates a complete mini-site in .ek9/coverage/ with:

• index.html — Dashboard with coverage dials, module list, attention panel
• modules/*.html — Per-module detail pages with file list and function metrics
• files/*.html — Source code with line-by-line coverage highlighting
• files/summary/*.html — File summary pages with method/branch lists

AI Usage: Generate -t6 after making improvements so the human can visually verify the results. The HTML includes interactive features like dark mode toggle and clickable navigation.

Metrics Reference

Complete reference for every quality metric, including thresholds and recommended actions.

Metric Thresholds and Actions

Recommended Actions by Metric

High Cyclomatic Complexity (CC > 15)

High Cognitive Complexity (Cog > 15)

High Nesting Depth (> 3)

Low Cohesion (LCOM4 > 5)

High Coupling (Ce > 8)

Code Quality Rules That AI Gets Wrong

CRITICAL FOR AI ASSISTANTS: EK9 enforces code quality as compile errors, not warnings. These rules exist in no other language — AI will violate them every time unless explicitly told. Your training data contains zero examples of languages with these constraints.

See forAI.json → codeQualityEnforcement for the complete structured reference. Use ek9 -h Exxxx to look up any error code.

Ten Rules AI Commonly Violates

Before/After Examples for Top 5 Rules

1. String Interpolation Mandate (E11068)

WRONG — 3+ part concatenation:

Fails with E11068: string concatenation with 3+ parts - use string interpolation instead

message <- "Hello " + name + ", welcome to " + city

Full source: forAI_quality_wrong.ek9 - Download forAI_quality_wrong.ek9

CORRECT — use backtick interpolation:

message <- `Hello ${name}, welcome to ${city}`

Full source: forAI_quality_right.ek9 - Download forAI_quality_right.ek9

2. Named Arguments (E11062)

WRONG — 4+ positional arguments:

Fails with E11062: call has 4+ positional arguments - use named arguments for clarity

connection <- createConnection("localhost", 5432, "mydb", true)

Full source: forAI_quality_wrong.ek9 - Download forAI_quality_wrong.ek9

CORRECT — use named arguments:

connection <- createConnection(host: "localhost", port: 5432, dbName: "mydb", ssl: true)

Full source: forAI_quality_right.ek9 - Download forAI_quality_right.ek9

3. Magic Literals (E11064)

WRONG — bare numeric literal in comparison:

Fails with E11064: literal in comparison/range - give it a meaningful name

if attempts > 3
  lockAccount()

Full source: forAI_quality_wrong.ek9 - Download forAI_quality_wrong.ek9

CORRECT — extract to named constant:

maxAttempts <- 3
if attempts > maxAttempts
  lockAccount()

Full source: forAI_quality_right.ek9 - Download forAI_quality_right.ek9

4. Operator Keyword Shadowing (E11032)

WRONG — variable shadows operator keyword:

Fails with E11032: variable name shadows operator keyword - use a more specific name

matches <- findAll(pattern, text)
empty <- checkIfEmpty(container)

Full source: forAI_quality_wrong.ek9 - Download forAI_quality_wrong.ek9

CORRECT — use descriptive names:

foundItems <- findAll(pattern, text)
isEmpty <- checkIfEmpty(container)

Full source: forAI_quality_right.ek9 - Download forAI_quality_right.ek9

5. Discarded Return Values (E11050/E11051)

WRONG — return value ignored:

Fails with E11051: pure method/function returns a value but result is discarded - a pure call with no side effects achieves nothing; E11050: operator returns a value but result is discarded - assign to variable or use in expression

calculateTotal(items)
price.+(tax)

Full source: forAI_quality_wrong.ek9 - Download forAI_quality_wrong.ek9

CORRECT — always capture the return:

total <- calculateTotal(items)
combined <- price + tax

Full source: forAI_quality_right.ek9 - Download forAI_quality_right.ek9

Refactoring Patterns

EK9-specific refactoring patterns for common complexity issues.

Pattern: Guard Flattening

Problem: Deep nesting from null/validity checks

Before (Nesting: 4, Cognitive: 16):

processOrder()
  -> order as Order
  <- result as String: String()

  if order?
    if order.isValid()
      if customer <- order.getCustomer()
        if customer.hasCredit()
          result: "Processing " + order.id()

Full source: forAI_guard_flattening_before.ek9 - Download forAI_guard_flattening_before.ek9

After (Nesting: 1, Cognitive: 4):

processOrder()
  -> order as Order
  <- result as String: String()

  if validateOrder(order)
    result: "Processing " + order.id()

validateOrder() as pure
  -> order as Order
  <- valid as Boolean: false

  if order? and order.isValid()
    if customer <- order.getCustomer() with customer.hasCredit()
      valid: true

Full source: forAI_guard_flattening_after.ek9 - Download forAI_guard_flattening_after.ek9

Pattern: Stream Pipeline Replacement

Problem: Complex nested loops with conditionals

Before (CC: 8, Nesting: 3):

findActiveUsers()
  -> users as List of User
  <- active as List of User: List()

  for user in users
    if user.isActive()
      if user.hasRecentLogin()
        active += user

Full source: forAI_stream_replacement_before.ek9 - Download forAI_stream_replacement_before.ek9

After (CC: 3, Nesting: 1):

findActiveUsers()
  -> users as List of User
  <- active as List of User?

  active: cat users
    | filter by isActiveWithRecentLogin
    | collect as List of User

isActiveWithRecentLogin() as pure
  -> user as User
  <- result as Boolean: user.isActive() and user.hasRecentLogin()

Full source: forAI_stream_replacement_after.ek9 - Download forAI_stream_replacement_after.ek9

Pattern: Dispatcher for Type Switching

Problem: Complex switch/if chains on type

Before (CC: 12):

processShape()
  -> shape as Shape
  <- area as Float?

  switch shape.type()
    case "circle"
      area: calculateCircleArea(shape)
    case "square"
      area: calculateSquareArea(shape)
    case "triangle"
      area: calculateTriangleArea(shape)
    default
      area: 0.0

Full source: forAI_dispatcher_before.ek9 - Download forAI_dispatcher_before.ek9

After (CC: 4 per function):

//A dispatcher is a METHOD - declare it in a class
AreaCalculator
  calculateArea() as dispatcher
    -> shape as Shape
    <- area as Float: 0.0

  calculateArea()
    -> circle as Circle
    <- area as Float: PI * circle.radius() * circle.radius()

  calculateArea()
    -> square as Square
    <- area as Float: square.side() * square.side()

  calculateArea()
    -> triangle as Triangle
    <- area as Float: 0.5 * triangle.base() * triangle.height()

Full source: forAI_dispatcher_after.ek9 - Download forAI_dispatcher_after.ek9

Pattern: Extract Validation Chain

Problem: Long sequence of validation checks

Before (CC: 15, Statements: 45):

validateAndProcess()
  -> request as Request
  <- response as Response?

  if not request?
    response: errorResponse("Null request")
  else if not request.hasUser()
    response: errorResponse("Missing user")
  else if not request.user().isAuthenticated()
    response: errorResponse("Not authenticated")
  else if not request.hasPermission("write")
    response: errorResponse("No permission")
  else if not request.payload()?
    response: errorResponse("Missing payload")
  else
    response: doProcess(request)

Full source: forAI_validation_chain_before.ek9 - Download forAI_validation_chain_before.ek9

After (CC: 5 each, clearer intent):

validateAndProcess()
  -> request as Request
  <- response as Response?

  response: validateRequest(request) ?: doProcess(request)

validateRequest() as pure
  -> request as Request
  <- error as Response: checkNotNull(request)

  //Assign-if-unset: each check runs only while no earlier check has failed
  error :=? checkHasUser(request)
  error :=? checkAuthenticated(request)
  error :=? checkPermission(request, "write")
  error :=? checkPayload(request)

checkNotNull() as pure
  -> request as Request
  <- error as Response: Response()
  if not request?
    error: errorResponse("Null request")

checkHasUser() as pure
  -> request as Request
  <- error as Response: Response()
  if not request.hasUser()
    error: errorResponse("Missing user")
// ... checkAuthenticated, checkPermission and checkPayload have the same shape

Full source: forAI_validation_chain_after.ek9 - Download forAI_validation_chain_after.ek9

Workflow Templates

Step-by-step workflows for common AI-assisted development tasks.

Workflow: Reduce Code Complexity

Trigger: Human requests "make this less complex" or "simplify this code"

1. Measure baseline

   ek9 -t4 main.ek9
   cp .ek9/coverage-detail.json baseline.json

   Parse JSON to extract:
   • metrics.maxComplexity — highest CC
   • highComplexityFunctions — list of problem functions
2. Identify targets
   highComplexityFunctions is already sorted by complexity, highest first. Focus on functions where CC > 15.
3. Read and analyze each target function
   Identify which pattern applies:
   • Deep nesting → Guard Flattening
   • Nested loops → Stream Pipelines
   • Type switching → Dispatcher
   • Validation chains → Extract Validation
4. Apply refactoring
   Make targeted changes. Keep each change small and focused.
5. Verify improvement

   ek9 -t4 main.ek9

   Compare .ek9/coverage-detail.json with baseline.json. Report, for example:

   processOrder: CC 24→8 (-67%), Cog 18→6 (-67%), Nesting 4→2 (-50%)

6. Generate HTML report for human

   ek9 -t6 main.ek9

   Tell human: "Open .ek9/coverage/index.html to see the updated metrics."

Workflow: Improve Test Coverage

Trigger: Human requests "improve coverage" or coverage is below 80%

1. Get current coverage

   ek9 -t4 main.ek9

   Check coverage.status and coverage.overall in .ek9/coverage-detail.json.
2. Identify uncovered code
   From the JSON extract:
   • uncoveredMethods — functions and methods with no coverage, with file and line
   • uncoveredBranches — specific branches not hit
   • per-module coverage — coverage.modules in .ek9/coverage.json (ek9 -t2 -tC main.ek9)
3. Prioritize by impact
   Focus on:
   • Uncovered functions in low-coverage modules (highest impact)
   • Uncovered branches in critical paths
   • Functions with partial coverage
4. Write tests
   For each uncovered function, create a test in dev/ directory. See Testing Strategies for EK9 test patterns.
5. Verify coverage improved

   ek9 -t4 main.ek9

   Confirm coverage.overall increased. Target: ≥80% for publishing.

Workflow: Fix Quality Errors

Trigger: Compilation fails with E110xx errors

1. Get detailed error info

   ek9 -E3 -c main.ek9

   The -E3 flag provides rich explanations.
2. Parse error code
   Quality errors are E11010-E11025. See Error Index.
3. Apply fix based on error

   Error	Meaning	Fix
   E11010	CC too high	Extract functions, reduce branches
   E11011	Nesting too deep	Use guards, extract blocks
   E11014	Low cohesion	Split class, group related methods
   E11015	High coupling	Introduce abstractions
   E11019	Deep inheritance	Use composition with by
   E11021	Cognitive too high	Flatten nesting, simplify flow

4. Recompile to verify fix

   ek9 -c main.ek9

Code Generation Guidelines

Guidelines for AI assistants generating EK9 code.

Syntax Essentials

• Indentation: 2 spaces (not tabs)
• No semicolons: Statements end at newline
• No curly braces: Indentation defines blocks
• Declaration: name <- value (infers type)
• Typed declaration: name as Type: value
• Assignment: name: value or name := value
• Assign-if-unset: name :=? value (fills it only if it is unset)

Preferred Patterns

Function Structure

lineTotal() as pure
  ->
    price as Float
    quantity as Integer
  <- total as Float?

  //Assign the returning variable on every path
  total: price * quantity

Full source: forAI_structure.ek9 - Download forAI_structure.ek9

Class Structure

defines class
  Account
    owner as String?
    balance as Float?

    default private Account()

    Account()
      ->
        owner as String
        balance as Float
      this.owner: owner
      this.balance: balance

    balanceAfter() as pure
      -> deposit as Float
      <- result as Float: balance + deposit

    default operator ?

Full source: forAI_structure.ek9 - Download forAI_structure.ek9

Test Structure

Tests live in dev/ source files: @Test and assert are compile errors anywhere else (E81015).

#!ek9
defines module site.forAI.shop.ordertests

  references
    site.forAI.shop::Item
    site.forAI.shop::Order

  defines program

    @Test
    testOrderTotal()
      // Arrange
      order <- Order()
      order.addItem(Item("Widget", 10.00))
      order.addItem(Item("Gadget", 25.00))

      // Act
      total <- order.calculateTotal()

      // Assert
      assert total?
      assert total == 35.00

Download forAI_order_tests.ek9

Patterns to Avoid

• No break/continue/return: These don't exist in EK9. Use guards and stream pipelines.
• No null: Use ? operator and unset values instead.
• No casting: Use dispatchers for polymorphic behavior.
• No deep inheritance: Max 4 levels. Prefer composition with by.
• No global variables: Use dependency injection or parameter passing.

EK9 Idioms

Declaration Guard (instead of null check + early return)

// Check and use in one expression
if result <- getValue()
  process(result)

Full source: forAI_idioms.ek9 - Download forAI_idioms.ek9

Coalescing (instead of ternary for defaults)

// Use default if unset (?: gives the right when the left is unset)
result <- getValue() ?: defaultValue

// Fill an unset variable (assign-if-unset - computeIfNeeded() runs only if needed)
existingVar :=? computeIfNeeded()

Full source: forAI_idioms.ek9 - Download forAI_idioms.ek9

Stream Pipeline (instead of loops with accumulators)

// Transform and collect
result <- cat items
  | filter by isValid
  | map with transform
  | collect as List of Integer

Full source: forAI_idioms.ek9 - Download forAI_idioms.ek9

Dispatcher (instead of instanceof/type switch)

// A dispatcher is a METHOD - declare it in a class
Notifier
  // Declare the dispatcher - its body is the fallback
  describe() as dispatcher
    -> event as Event
    <- text as String: "Unknown event"

  // Implement per concrete type
  describe()
    -> placed as OrderPlaced
    <- text as String: `Order ${placed.reference()} placed`

Full source: forAI_idioms.ek9 - Download forAI_idioms.ek9

Error Interpretation

How to interpret and fix common EK9 compilation errors.

Error Categories

Using Verbose Mode

Always use -E3 when debugging errors:

ek9 -E3 -c main.ek9

This provides:

• Full error explanation
• Code context showing the problem
• Suggested fixes
• Links to related documentation

Quality Error Quick Reference

Testing Strategies

Guidelines for writing effective EK9 tests.

Test File Structure

The layout the examples below use (run with ek9 -t forAI_shop.ek9: 5 tests, all pass). A black-box or parameterized test sits in its own directory beside its companion files:

forAI_shop.ek9                      # the module under test
dev/
├── forAI_order_tests.ek9           # unit tests with assert
├── forAI_validate_tests.ek9        # unit tests with assert
├── formatting/
│   ├── forAI_format_test.ek9       # one black-box test
│   └── expected_output.txt         # its expected stdout
└── validation/
    ├── forAI_validation_test.ek9   # one parameterized test
    ├── commandline_arg_1.txt       # the typed argument for case 1
    └── expected_case_1.txt         # the expected stdout for case 1

The Module Under Test

#!ek9
defines module site.forAI.shop

  defines function

    validate() as pure
      -> input as String
      <- valid as Boolean: input matches /^[a-z]+$/

  defines record

    Item
      name as String: String()
      price as Float: Float()

      Item()
        ->
          name as String
          price as Float
        this.name :=: name
        this.price :=: price

      default operator ?

  defines class

    Order
      items as List of Item: List()

      addItem()
        -> item as Item
        items += item

      calculateTotal()
        <- total as Float: 0.0
        for item in items
          total += item.price

      default operator ?

    Formatter
      format() as pure
        -> text as String
        <- formatted as String: text.upperCase()

Download forAI_shop.ek9

Test Patterns

Unit Test with Assertions

#!ek9
defines module site.forAI.shop.validatetests

  references
    site.forAI.shop::validate

  defines program

    @Test
    testValidateAcceptsLowerCase()
      result <- validate("widget")

      assert result?
      assert result

    @Test
    testValidateRejectsDigits()
      result <- validate("widget42")

      assert result?
      assert not result

Download forAI_validate_tests.ek9

Black-Box Test with Expected Output

#!ek9
defines module site.forAI.shop.formattests

  references
    site.forAI.shop::Formatter

  defines program

    @Test
    testFormatOutput()
      stdout <- Stdout()
      formatter <- Formatter()
      result <- formatter.format("hello")
      stdout.println(result)

Download forAI_format_test.ek9

With expected_output.txt beside it:

HELLO

Parameterized Test

#!ek9
defines module site.forAI.shop.validationtests

  references
    site.forAI.shop::validate

  defines program

    @Test
    testValidation()
      //The runtime parses dev/validation/commandline_arg_1.txt into the typed parameter
      -> input as String
      stdout <- Stdout()
      result <- validate(input)
      stdout.println($result)

Download forAI_validation_test.ek9

With commandline_arg_1.txt and expected_case_1.txt pairs beside it (here widget and true).

Coverage-Driven Testing

1. Run ek9 -t4 to get coverage data in .ek9/coverage-detail.json
2. Check uncoveredMethods
3. For each uncovered function:
   • Analyze function signature and behavior
   • Identify edge cases (null, empty, boundary values)
   • Write tests covering happy path and edge cases
4. Check uncoveredBranches
5. For each uncovered branch:
   • Identify the condition (BRANCH_TRUE or BRANCH_FALSE)
   • Create test input that exercises that branch
6. Re-run ek9 -t4 to verify improved coverage

Summary for AI Assistants

Key takeaways for effective AI-assisted EK9 development:

1. Use -t4 for analysis — .ek9/coverage-detail.json is your primary data source
2. Metrics drive action — Use thresholds to identify and prioritize work
3. Verify improvements — Always re-run metrics after changes
4. Use -E3 for errors — Rich mode explains problems clearly
5. Report measurably — Show before/after metrics to humans
6. Generate -t6 for humans — HTML reports for visual review

The AI-Human Partnership: EK9's quality system is designed to make AI assistants maximally effective. You measure, identify issues, apply patterns, and verify. The human reviews results and guides priorities. Together, you produce code that is measurably better than either could produce alone.

Quick Links

• Code Quality — Detailed metric explanations and error codes
  • Implemented Metrics — CC, Cognitive, Nesting thresholds
  • ARI Readability — Lexical complexity (informational)
  • Viewing Quality Metrics — HTML report elements explained
• Testing — Test framework documentation
  • Quality Metrics — Coverage report integration
  • HTML Reports — Report structure and navigation
• Error Index — Complete error reference with fixes
• Command Line — All compiler options
  • Compilation Options — -c, -cG, -Cl flags
  • Error Verbosity — -E0 to -E5 (-E3 for AI debugging, -E4 paradigm summary, -E5 full bootstrap)
  • Exit Codes — Interpret success/failure programmatically
  • Packaging — -P, -D for deployment
• Flow Control — Guards and control flow
• Streams — Pipeline patterns