Class MagicLiteralTracker

java.lang.Object

org.ek9lang.compiler.phase5.MagicLiteralTracker

class MagicLiteralTracker
extends Object

Tracks literal occurrences across files for repeated magic literal detection (E11065). A repeated magic literal is the same value appearing 3+ times in a single file or 4+ times across files in the same module. Only String literals are tracked — numeric literals in test/production code are domain data, not duplication bugs. This matches SonarQube S1192 and PMD AvoidDuplicateLiterals (strings only).

Thread-safe: designed to be used during parallel file processing where multiple PreIRListener instances (one per file) share a single MagicLiteralTracker.

Context exemptions: literals in constant declarations, list/dict literals, require/assert statements, constrain declarations, range expressions, string concatenation, and named arguments - the label documents the value, and the compiler checks it against the declared parameter (E06240/E06250), so it cannot lie.

A constructor call is NOT exempt (D4, Steve 2026-10-03): Person("Steve", "Limb") repeated is as opaque as any call; label it (Person(firstName: "Steve", lastName: "Limb")) or name a shared value as a constant. It was once exempt by the callee's name starting with an uppercase letter, which also exempted any function so named.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
(package private) static final record	MagicLiteralTracker.LiteralRecord	One recorded occurrence of a literal.

Constructor Summary

Constructors

Constructor	Description
MagicLiteralTracker()

Method Summary

Modifier and Type	Method	Description
(package private) List<MagicLiteralTracker.LiteralRecord>	getRecords(String moduleName)	Get a snapshot copy of literal records for a specific module.
(package private) static boolean	isExempt(String moduleName)	Check if a module is exempt from magic literal checking.
(package private) void	processLiteral(EK9Parser.LiteralContext literal, String moduleName, String filePath, Set<org.antlr.v4.runtime.Token> reportedByTier1)	Record a literal occurrence for a specific module, if not exempt.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

MagicLiteralTracker

MagicLiteralTracker()

Method Details

processLiteral

void processLiteral(EK9Parser.LiteralContext literal,
 String moduleName,
 String filePath,
 Set<org.antlr.v4.runtime.Token> reportedByTier1)

Record a literal occurrence for a specific module, if not exempt.

Parameters:

literal - the literal parser context

moduleName - the module containing the literal

filePath - the source file path

reportedByTier1 - tokens already reported by Tier 1 (to avoid double-reporting)

getRecords

List<MagicLiteralTracker.LiteralRecord> getRecords(String moduleName)

Get a snapshot copy of literal records for a specific module.

Parameters:

moduleName - the module to query

Returns:

list of literal records (may be empty, never null)

isExempt

static boolean isExempt(String moduleName)

Check if a module is exempt from magic literal checking. Built-in modules (org.ek9.*) are exempt.