diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..a56b17a4f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,87 @@ +# Agent Guidelines + +This repo keeps “fresh memory” notes under `.$state/`. These docs are the primary mental model for the script editor + interpreter stack. + +Default todo list: `.$state/TODO.md` + +## Compilation and Building + +To compile the project, run the gradlew.bat compileJava task on ONLY the root project (CustomNPC-DBC-Addon). This applies for CustomNPC-Plus as well. +And WAIT!!! Waiting is essential, as the task can usually take up to 3 minutes. As long as the compileJava task is running, DO NOT close the terminal or interrupt the process. + +## How to use state docs + +Before exploring source code or making edits, scan the user prompt for subsystem keywords and open the relevant `.$state/*.md` doc(s) first. If multiple subsystems are involved, read all relevant docs (usually 1–3). + +Recommended read order (when multiple apply): +1. `.$state/SYNTAX_HIGHLIGHTER.md` +2. `.$state/AUTOCOMPLETE.md` +3. `.$state/DTS_ECOSYSTEM.md` +4. `.$state/SCRIPT_EDITOR.md` +5. `.$state/SCRIPT_HANDLING.md` + +The goal is not to treat the docs as perfectly authoritative; it’s to refresh terminology, invariants, and the intended architecture before verifying details in source. + +## State docs (what to read when) + +- `.$state/SYNTAX_HIGHLIGHTER.md` + - Read when the prompt involves: `ScriptDocument`, parsing/marking/token building, `TokenType` priority, `FieldChainMarker`, validation errors, hover/underlines, synthetic built-ins, JSDoc, or type-resolution questions involving `TypeResolver`, `resolveType` or `resolveExpressionType`. + +- `.$state/AUTOCOMPLETE.md` + - Read when the prompt involves: autocomplete UI/behavior, prefix/receiver detection, insertion behavior, providers (`JavaAutocompleteProvider`, `JSAutocompleteProvider`), suggestion ranking, usage tracking, import insertion, or missing/wrong suggestions. + +- `.$state/DTS_ECOSYSTEM.md` + - Read when the prompt involves: `.d.ts` generation (Gradle plugin in `gradle-plugins/`), `hooks.d.ts` / `index.d.ts`, runtime parsing (`TypeScriptDefinitionParser`), registry behavior (`JSTypeRegistry`), `JSTypeInfo`/`JSMethodInfo`/`JSFieldInfo`, or TypeScript generic bound handling. + +- `.$state/SCRIPT_EDITOR.md` + - Read when the prompt involves: `GuiScriptTextArea`, editor UX (scroll/selection/search/go-to-line/rename), hover UI wiring, or the client editor model (`ScriptTextContainer`). + +- `.$state/SCRIPT_HANDLING.md` + - Read when the prompt involves: (`JaninoScript`, `janino`, `GuiScriptInterface` ), runtime script storage/execution (`ScriptContainer`), script-related NBT serialization, hook dispatch, script engine selection, or script controller/handler wiring. + +## Cross-subsystem quick picks + +- Autocomplete issues that smell like “wrong receiver type / missing members / cannot resolve symbol”: + - Read `.$state/AUTOCOMPLETE.md` + `.$state/SYNTAX_HIGHLIGHTER.md` (+ `.$state/DTS_ECOSYSTEM.md` if JS/.d.ts types involved). +- JS autocomplete issues specifically: + - Read `.$state/AUTOCOMPLETE.md` + `.$state/DTS_ECOSYSTEM.md` + the relevant `.$state/SYNTAX_HIGHLIGHTER.md` sections. +- Hover tooltip / red underline / error text mismatches: + - Read `.$state/SYNTAX_HIGHLIGHTER.md`. + +## Workflow expectation + +1. Identify subsystem keywords in the user request. +2. Read the relevant `.$state/*.md` doc(s) first (before open-ended repo exploration). +3. Use the docs to decide which source files to inspect next. +4. Verify critical details against source before making edits (the docs can drift). +5. If edits change behavior/architecture described in a state doc, ask the user whether they want the doc updated as part of the change. + + +## Planning + +When I prompt you to plan something, I want you to always follow these steps: +1. Analyze the user request carefully to understand their needs and objectives. +2. Break down the request into smaller, manageable tasks or components. +3. Prioritize the tasks based on their importance and dependencies. +4. Create a detailed plan or outline that addresses each task systematically. +5. Review the plan to ensure it aligns with the user's goals and is feasible to implement. +6. Present the plan to the user for feedback and approval before proceeding with implementation. +7. Once approved, execute the plan step by step, keeping the user informed of progress and any adjustments needed along the way. +8. After completing the tasks, review the outcomes with the user to ensure satisfaction and address any further needs. +9. Document the process and results for future reference and learning. + +This plan must always be created and stored at .sisyphus/plans as a .md file with a unique name related to the task. +That document must be your main source of truth for the plan, you must always refer to it before and after taking any action. + +## Expert-Scripter Conventions + +For CustomNPC+ scripting conventions and quality standards, see `.github/agents/AGENTS.md`. + +That file documents: +- Mandatory review gates and triggers +- API verification requirements (zero-tolerance policy) +- Storage decision tree (getNbt vs getStoredData vs getTempData) +- Subagent usage rules +- Production quality checklist +- Code-Review conventions +- Training scripts policy \ No newline at end of file diff --git a/src/main/java/bigguy/texteditor/ReadinessState.java b/src/main/java/bigguy/texteditor/ReadinessState.java new file mode 100644 index 000000000..4c024de7a --- /dev/null +++ b/src/main/java/bigguy/texteditor/ReadinessState.java @@ -0,0 +1,185 @@ +package bigguy.texteditor; + +import java.util.Collections; +import java.util.EnumSet; +import java.util.Set; + +/** + * Models the readiness lifecycle of the script editor's semantic pipeline. + * + *
Inspired by IntelliJ IDEA's {@code DumbService} dumb/smart mode pattern, + * this enum tracks how much of the analysis pipeline has completed and which + * editor features are currently safe to invoke.
+ * + *{@code
+ * UNINITIALIZED ──→ SYNTAX_READY (after initial CST parse)
+ * SYNTAX_READY ──→ ANALYZING (background semantic analysis started)
+ * ANALYZING ──→ SMART (analysis complete — all features available)
+ * ANALYZING ──→ DEGRADED (analysis failed — fall back to syntax-only)
+ * Any state ──→ SYNTAX_READY (text changed — semantics invalidated)
+ * }
+ *
+ * Each state advertises which editor capabilities are available via + * {@link #isSyntaxAvailable()} and {@link #isSemanticsAvailable()}. + * UI code should query these predicates rather than comparing states + * directly, so that new states can be added without breaking callers.
+ * + *Enum constants are inherently immutable. The state variable holding
+ * the current readiness should be protected by whatever concurrency mechanism
+ * the orchestrator uses (e.g. {@code AtomicReference
When syntax is available, the following features are safe to use:
+ *When semantics are available, the following features are safe to use:
+ *UI code can use this to display a progress indicator without blocking.
+ * + * @return whether analysis is running + */ + public boolean isAnalyzing() { + return analyzing; + } + + /** + * Checks whether a transition from this state to {@code next} is valid + * according to the state machine's transition rules. + * + * @param next the proposed target state + * @return {@code true} if the transition is allowed + * @throws NullPointerException if {@code next} is {@code null} + */ + public boolean canTransitionTo(ReadinessState next) { + if (next == null) { + throw new NullPointerException("Target state must not be null"); + } + return validTargets().contains(next); + } + + /** + * Returns the set of states that this state may transition to. + * + * @return an unmodifiable set of valid target states + */ + public Set{@code
+ * onTextChanged(text)
+ * → parser.parse(text) → SyntaxTree
+ * → DocumentSyntax.create(tree, version)
+ * → queryEngine.highlights(tree, text) → HighlightCaptures
+ * → convertHighlightsToMarks(captures, text) → List
+ * → markLayer.setSyntaxMarks(marks)
+ * → markLayer.merge() → mergedMarks
+ * → renderModel.rebuild(text, mergedMarks, lineHeight)
+ * → state = SYNTAX_READY
+ * → semanticAnalyzer.scheduleAnalysis(syntax, rev, callback)
+ * → state = ANALYZING
+ * → (background) onAnalysisComplete → state = SMART
+ * onAnalysisFailed → state = DEGRADED
+ * }
+ *
+ * {@code
+ * UNINITIALIZED → SYNTAX_READY (first onTextChanged)
+ * SYNTAX_READY → ANALYZING (analysis scheduled)
+ * ANALYZING → SMART (analysis complete, revision matches)
+ * ANALYZING → DEGRADED (analysis failed, revision matches)
+ * ANALYZING → SYNTAX_READY (new text change arrives)
+ * SMART → SYNTAX_READY (text changed again)
+ * DEGRADED → SYNTAX_READY (text changed again)
+ * }
+ */
+public class ScriptOrchestrator implements SemanticAnalyzer.AnalysisCallback {
+
+ // --- Error underline colors (ARGB) ---
+ private static final int ERROR_COLOR = 0xFFFF5555;
+ private static final int WARNING_COLOR = 0xFFFFAA00;
+ private static final int INFO_COLOR = 0xFF5555FF;
+
+ // --- Core state ---
+ private volatile ReadinessState state = ReadinessState.UNINITIALIZED;
+ private final AtomicLong revision = new AtomicLong(0);
+
+ // --- Syntax layer ---
+ private final JavaParser parser;
+ private final JavaQueryEngine queryEngine;
+ private volatile DocumentSyntax currentSyntax;
+
+ // --- Render pipeline ---
+ private final MarkLayer markLayer;
+ private final RenderModel renderModel;
+ private final DiagnosticStore diagnosticStore;
+
+ // --- Configuration ---
+ private int lineHeight = 10;
+
+ // --- Semantic analysis ---
+ private final SemanticAnalyzer semanticAnalyzer;
+ private final IncrementalStrategy incrementalStrategy;
+ private TextSpan[] lastChangedRanges;
+ private volatile String currentSourceText = "";
+
+ /**
+ * Creates a new orchestrator with default-configured components.
+ *
+ * Initializes the tree-sitter parser, query engine, mark layer, + * render model, diagnostic store, semantic analyzer, and incremental + * strategy. All components start empty; call + * {@link #onTextChanged(String)} to kick off the pipeline.
+ */ + public ScriptOrchestrator() { + this.parser = new JavaParser(); + this.queryEngine = new JavaQueryEngine(); + this.markLayer = new MarkLayer(); + this.renderModel = new RenderModel(); + this.diagnosticStore = new DiagnosticStore(); + this.semanticAnalyzer = new SemanticAnalyzer(); + this.incrementalStrategy = new IncrementalStrategy(); + } + + // ==================== MAIN PIPELINE ==================== + + /** + * Called when the source text changes. Runs the syntax pipeline + * synchronously on the UI thread (fast path), then schedules + * background semantic analysis. + * + *Any in-flight analysis from a previous edit is cancelled before + * scheduling a new one, ensuring stale results are never applied.
+ * + * @param text the complete source text of the document + */ + public void onTextChanged(String text) { + long rev = revision.incrementAndGet(); + + // Cancel any in-flight analysis from the previous edit + semanticAnalyzer.cancelInFlight(); + + // Step 1: Parse CST + SyntaxTree syntaxTree = parser.parse(text); + + // Step 2: Create DocumentSyntax + currentSyntax = DocumentSyntax.create(syntaxTree, (int) rev); + + // Step 3: Collect parser errors as diagnostics + diagnosticStore.clearBySource(Diagnostic.Source.PARSER); + collectParserErrors(currentSyntax); + + // Step 4: Extract syntax highlights from tree-sitter + ListThe mapping aims to match IntelliJ-style colorization:
+ *ERROR nodes represent unparseable source regions. MISSING nodes + * represent tokens the parser expected but did not find (e.g. a + * missing semicolon).
+ * + * @param syntax the document syntax to scan for errors + */ + private void collectParserErrors(DocumentSyntax syntax) { + SemanticNode root = syntax.root(); + if (root == null || !root.hasError()) { + return; + } + collectParserErrorsRecursive(root); + } + + /** + * Recursively walks the semantic node tree, creating diagnostics + * for any ERROR or MISSING nodes encountered. + * + * @param node the current node being visited + */ + private void collectParserErrorsRecursive(SemanticNode node) { + if (node.isError()) { + TextSpan span = node.span(); + if (span != null && span.getByteLength() > 0) { + String text = node.text(); + String message = "Syntax error" + (text != null && !text.isEmpty() + ? ": unexpected '" + truncate(text, 30) + "'" + : ""); + diagnosticStore.addDiagnostic(Diagnostic.of( + span, Diagnostic.Severity.ERROR, message, Diagnostic.Source.PARSER)); + } + return; + } + if (node.isMissing()) { + TextSpan span = node.span(); + if (span != null) { + String nodeType = node.nodeType(); + String message = "Missing " + (nodeType != null ? "'" + nodeType + "'" : "token"); + diagnosticStore.addDiagnostic(Diagnostic.of( + span, Diagnostic.Severity.ERROR, message, Diagnostic.Source.PARSER)); + } + return; + } + int childCount = node.childCount(); + for (int i = 0; i < childCount; i++) { + SemanticNode child = node.child(i); + if (child != null && child.hasError()) { + collectParserErrorsRecursive(child); + } + } + } + + // ==================== STATE QUERIES ==================== + + /** + * Returns the current readiness state of the pipeline. + * + * @return the current {@link ReadinessState} + */ + public ReadinessState getReadinessState() { + return state; + } + + /** + * Returns the monotonically increasing revision counter. + * Incremented on every {@link #onTextChanged(String)} call. + * + * @return the current revision number + */ + public long getRevision() { + return revision.get(); + } + + // ==================== COMPONENT ACCESS ==================== + + /** + * Returns the render model containing the line layout and viewport calculations. + * + * @return the render model, never {@code null} + */ + public RenderModel getRenderModel() { + return renderModel; + } + + /** + * Returns the mark layer used for syntax/semantic/error mark merging. + * + * @return the mark layer, never {@code null} + */ + public MarkLayer getMarkLayer() { + return markLayer; + } + + /** + * Returns the diagnostic store containing all parser and analysis errors. + * + * @return the diagnostic store, never {@code null} + */ + public DiagnosticStore getDiagnosticStore() { + return diagnosticStore; + } + + /** + * Returns the current document syntax, or {@code null} if no parse + * has been performed yet. + * + * @return the latest {@link DocumentSyntax}, or {@code null} + */ + public DocumentSyntax getCurrentSyntax() { + return currentSyntax; + } + + /** + * Returns the current semantic model from the analyzer. + * May be {@code null} or unbuilt if no analysis has completed yet. + * + * @return the latest {@link SemanticModel}, or {@code null} + */ + public SemanticModel getSemanticModel() { + return semanticAnalyzer.getSemanticModel(); + } + + // ==================== CONFIGURATION ==================== + + /** + * Sets the pixel height per line used for render model layout. + * + * @param lineHeight pixel height per line (must be positive) + */ + public void setLineHeight(int lineHeight) { + this.lineHeight = lineHeight; + } + + /** + * Returns the current pixel height per line. + * + * @return the line height in pixels + */ + public int getLineHeight() { + return lineHeight; + } + + // ==================== DIAGNOSTIC HELPERS ==================== + + /** + * Returns diagnostic ranges for a specific render line, suitable for + * passing to {@link RenderLine#drawErrorUnderlines(int, int, List)}. + * + *Queries the {@link DiagnosticStore} for diagnostics overlapping the + * line's byte range, then converts each to a + * {@link RenderLine.DiagnosticRange} with an appropriate underline color + * based on severity.
+ * + * @param line the render line to query diagnostics for + * @return a list of diagnostic ranges, possibly empty, never {@code null} + */ + public ListDisposes the semantic analyzer (cancels in-flight analysis and shuts + * down its executor), closes the tree-sitter parser (releasing native + * memory), clears the mark layer, diagnostic store, and nullifies the + * current syntax reference.
+ */ + public void dispose() { + semanticAnalyzer.dispose(); + parser.close(); + markLayer.clear(); + diagnosticStore.clear(); + currentSyntax = null; + state = ReadinessState.UNINITIALIZED; + } + + // ==================== INTERNAL UTILITIES ==================== + + /** + * Truncates a string to the given maximum length, appending "..." if truncated. + * + * @param text the string to truncate + * @param maxLength the maximum length before truncation + * @return the original string if short enough, or a truncated version + */ + private static String truncate(String text, int maxLength) { + if (text.length() <= maxLength) { + return text; + } + return text.substring(0, maxLength) + "..."; + } + + @Override + public String toString() { + return "ScriptOrchestrator{state=" + state + + ", revision=" + revision.get() + + ", syntax=" + (currentSyntax != null ? currentSyntax : "null") + + ", renderModel=" + renderModel + + ", diagnostics=" + diagnosticStore + + '}'; + } +} diff --git a/src/main/java/bigguy/texteditor/analysis/IncrementalStrategy.java b/src/main/java/bigguy/texteditor/analysis/IncrementalStrategy.java new file mode 100644 index 000000000..406359a78 --- /dev/null +++ b/src/main/java/bigguy/texteditor/analysis/IncrementalStrategy.java @@ -0,0 +1,386 @@ +package bigguy.texteditor.analysis; + +import bigguy.texteditor.syntax.DocumentSyntax; +import bigguy.texteditor.syntax.SemanticNode; +import bigguy.texteditor.treesitter.java.TextSpan; + +import java.util.Arrays; +import java.util.Collections; +import java.util.HashSet; +import java.util.Set; + +/** + * Classifies text edits into invalidation scopes, determining how much of + * the semantic model needs rebuilding after an incremental reparse. + * + *This is the intelligence behind incremental analysis — the core of the + * "every keystroke must NOT cause a full rebuild" requirement. By inspecting + * which CST nodes changed, the strategy assigns a minimal + * {@link InvalidationScope} that tells {@code SemanticModel} exactly which + * sub-components need updating.
+ * + *The algorithm walks upward from each changed range's deepest node to + * classify the edit into one of five categories:
+ *+ * | InvalidationScope | SymbolTable | ScopeTree | ImportIndex | Cost | + * |-------------------|-------------|-----------------|-------------|---------| + * | NONE | Keep | Keep | Keep | ~0.01ms | + * | LOCAL_SCOPE | Keep | Rebuild 1 scope | Keep | ~2ms | + * | DECLARATION | Rebuild | Rebuild | Keep | ~10ms | + * | IMPORTS | Keep | Keep | Rebuild | ~10ms | + * | STRUCTURAL | Rebuild all | Rebuild all | Rebuild all | ~50ms | + *+ * + *
This class is stateless and therefore inherently thread-safe. All methods + * are pure functions of their arguments.
+ * + * @see InvalidationScope + */ +public final class IncrementalStrategy { + + // ── CST node type constants ──────────────────────────────────────────────── + // Centralised here to avoid scattered string literals throughout the class. + + private static final String NODE_IMPORT_DECLARATION = "import_declaration"; + private static final String NODE_CLASS_DECLARATION = "class_declaration"; + private static final String NODE_INTERFACE_DECLARATION = "interface_declaration"; + private static final String NODE_ENUM_DECLARATION = "enum_declaration"; + private static final String NODE_ANNOTATION_TYPE_DECLARATION = "annotation_type_declaration"; + private static final String NODE_METHOD_DECLARATION = "method_declaration"; + private static final String NODE_CONSTRUCTOR_DECLARATION = "constructor_declaration"; + private static final String NODE_FIELD_DECLARATION = "field_declaration"; + private static final String NODE_BLOCK = "block"; + private static final String NODE_PROGRAM = "program"; + + /** + * Node types that represent type/member declarations whose modification + * requires at least a {@link InvalidationScope#DECLARATION DECLARATION} + * level rebuild. + */ + private static final SetScopes are ordered from cheapest ({@link #NONE}) to most expensive + * ({@link #STRUCTURAL}). When multiple changed ranges yield different + * scopes, the highest (most expensive) scope wins.
+ */ + public enum InvalidationScope { + + /** + * No semantic change — the edit was entirely inside a string literal or + * comment. Only byte-offset adjustment is needed; all semantic data + * structures remain valid. + */ + NONE(0), + + /** + * Edit inside a method or constructor body — only the affected scope + * needs to be rebuilt in the {@code ScopeTree}. The {@code SymbolTable} + * and {@code ImportIndex} are unaffected because no declarations or + * imports changed. + */ + LOCAL_SCOPE(1), + + /** + * A type, method, or field declaration changed — the {@code SymbolTable} + * and {@code ScopeTree} need rebuilding, but the {@code ImportIndex} + * remains valid. + */ + DECLARATION(2), + + /** + * An import declaration changed — the {@code ImportIndex} needs + * rebuilding. Downstream type resolution may also need re-running. + */ + IMPORTS(3), + + /** + * A class or method boundary changed (structural edit) — all semantic + * data structures must be fully rebuilt. This is the worst case and + * corresponds to edits that alter the fundamental structure of the file + * (e.g., adding/removing a class, changing method signatures across + * multiple declarations). + */ + STRUCTURAL(4); + + private final int severity; + + InvalidationScope(int severity) { + this.severity = severity; + } + + /** + * Returns the numeric severity level for comparison. Higher values + * indicate more expensive rebuilds. + * + * @return the severity ordinal (0 = cheapest, 4 = most expensive) + */ + public int severity() { + return severity; + } + + /** + * Returns the more severe of two scopes. + * + * @param a the first scope + * @param b the second scope + * @return the scope with the higher severity + */ + public static InvalidationScope max(InvalidationScope a, InvalidationScope b) { + if (a == null) { + return b; + } + if (b == null) { + return a; + } + return a.severity >= b.severity ? a : b; + } + } + + // ── Constructor ──────────────────────────────────────────────────────────── + + /** + * Creates a new incremental strategy instance. + * + *This class is stateless; a single instance can be reused across + * all analysis cycles.
+ */ + public IncrementalStrategy() { + // Stateless — no initialisation needed. + } + + // ── Public API ───────────────────────────────────────────────────────────── + + /** + * Classifies the combined impact of all CST changes to determine how much + * of the semantic model needs re-analysis. + * + *Each changed range is classified independently via + * {@link #classifySingleChange(TextSpan, DocumentSyntax)}, and the + * worst-case (highest severity) scope across all ranges is returned.
+ * + *If no ranges changed, returns {@link InvalidationScope#NONE}.
+ * + * @param changedRanges the byte ranges that changed (from tree-sitter's + * {@code getChangedRanges()}); may be {@code null} or empty + * @param syntax the new document syntax after reparse + * @return the invalidation scope indicating how much needs rebuilding + * @throws IllegalArgumentException if {@code syntax} is {@code null} + */ + public InvalidationScope classify(TextSpan[] changedRanges, DocumentSyntax syntax) { + if (syntax == null) { + throw new IllegalArgumentException("syntax must not be null"); + } + if (changedRanges == null || changedRanges.length == 0) { + return InvalidationScope.NONE; + } + + InvalidationScope worst = InvalidationScope.NONE; + + for (TextSpan range : changedRanges) { + if (range == null) { + continue; + } + InvalidationScope rangeScope = classifySingleChange(range, syntax); + worst = InvalidationScope.max(worst, rangeScope); + + // Short-circuit: STRUCTURAL is the maximum possible severity. + if (worst == InvalidationScope.STRUCTURAL) { + return worst; + } + } + + return worst; + } + + /** + * Classifies a single changed byte range to determine its invalidation scope. + * + *The algorithm proceeds in three steps:
+ *The walk checks in order:
+ *This class is the bridge between the UI-thread syntax pipeline and the + * background semantic pipeline. It is called by the orchestrator after each + * text change and follows a strict revision-based protocol to prevent stale + * semantic data from contaminating fresh syntax state.
+ * + *The key invariant is: never blend stale semantic data with fresh + * syntax. When a revision changes:
+ *All public methods are safe to call from any thread. The executor is a + * single-thread pool, so analysis tasks are serialised. The {@code disposed} + * and {@code inFlightAnalysis} fields use {@code volatile} for visibility + * across threads, and the {@code currentRevision} uses {@link AtomicLong} + * for atomic updates.
+ * + *The {@link AnalysisCallback} is invoked on the background + * analysis thread, not the UI thread. Callers (typically the orchestrator) + * must handle the thread boundary themselves — for example, via + * Minecraft's scheduled-task system — before applying results to + * UI-visible state.
+ * + * @see SemanticModel + * @see IncrementalStrategy + * @see DocumentSyntax + */ +public final class SemanticAnalyzer { + + private static final Logger LOGGER = Logger.getLogger(SemanticAnalyzer.class.getName()); + + /** + * Name assigned to the daemon analysis thread. Appears in thread dumps + * and debugger views for easy identification. + */ + private static final String THREAD_NAME = "ScriptEditor-SemanticAnalysis"; + + /** + * Maximum time (in milliseconds) to wait for the executor to terminate + * during {@link #dispose()}. + */ + private static final long SHUTDOWN_TIMEOUT_MS = 2000L; + + // ── Callback interface ───────────────────────────────────────────────────── + + /** + * Callback interface for receiving analysis results. + * + *The orchestrator implements this to apply semantic marks and + * transition state. Important: callbacks are invoked on + * the background analysis thread, not the UI thread. Implementors must + * marshal results to the appropriate thread before modifying UI state.
+ * + *The caller must check that the revision still matches + * the current document revision before applying results. The analyzer + * performs its own revision check before invoking the callback, but there + * is an inherent race window between the check and the callback body + * executing, so a second check in the callback is recommended.
+ */ + public interface AnalysisCallback { + + /** + * Called when analysis completes successfully for the given revision. + * + *The caller must verify that the revision still + * matches the current document revision before applying results. + * If the revision has advanced, these results are stale and must + * be discarded.
+ * + * @param revision the revision number this analysis was for + * @param semanticModel the populated semantic model + * @param syntax the {@link DocumentSyntax} that was analyzed + */ + void onAnalysisComplete(long revision, SemanticModel semanticModel, DocumentSyntax syntax); + + /** + * Called when analysis fails with an exception. + * + *The revision is provided so the caller can determine whether + * the failure is still relevant to the current document state.
+ * + * @param revision the revision number this analysis was for + * @param error the exception that occurred during analysis + */ + void onAnalysisFailed(long revision, Exception error); + } + + // ── Fields ───────────────────────────────────────────────────────────────── + + /** + * Single-thread executor for background analysis. Uses a daemon thread + * so it does not prevent JVM (Minecraft) shutdown. + */ + private final ExecutorService executor; + + /** + * The semantic model being built and updated. Owned exclusively by this + * analyzer; only accessed from the analysis thread (except for + * {@link #getSemanticModel()} which returns a snapshot reference). + */ + private final SemanticModel semanticModel; + + /** + * Stateless strategy for classifying edits into invalidation scopes. + * Used by the incremental analysis path to determine which parts of + * the semantic model need rebuilding. + */ + private final IncrementalStrategy strategy; + + /** + * The currently in-flight analysis {@link Future}, or {@code null} if + * no analysis is running. Volatile for cross-thread visibility. + */ + private volatile Future> inFlightAnalysis; + + /** + * The revision number that was most recently submitted for analysis. + * Used for stale-result detection: if the revision has advanced past + * this value by the time analysis completes, the results are discarded. + */ + private final AtomicLong currentRevision; + + /** + * Set to {@code true} when {@link #dispose()} is called. Prevents new + * analysis submissions and causes in-flight analysis to bail out early. + */ + private volatile boolean disposed; + + // ── Constructor ──────────────────────────────────────────────────────────── + + /** + * Creates a new {@code SemanticAnalyzer} with a single-thread daemon + * executor, a fresh {@link SemanticModel}, and a stateless + * {@link IncrementalStrategy}. + * + *The executor uses a daemon thread with slightly lower than normal + * priority ({@link Thread#NORM_PRIORITY} - 1) so that analysis does not + * compete with UI rendering for CPU time.
+ */ + public SemanticAnalyzer() { + this.executor = Executors.newSingleThreadExecutor(createDaemonThreadFactory()); + this.semanticModel = new SemanticModel(); + this.strategy = new IncrementalStrategy(); + this.inFlightAnalysis = null; + this.currentRevision = new AtomicLong(0L); + this.disposed = false; + } + + // ── Public API ───────────────────────────────────────────────────────────── + + /** + * Schedules a full semantic analysis for the given syntax snapshot. + * + *Any currently in-flight analysis is cancelled before scheduling the + * new one. The revision number is recorded so that stale results can be + * detected and discarded when the analysis completes.
+ * + *The analysis performs a complete rebuild of the {@link SemanticModel}: + * all sub-components (SymbolTable, ScopeTree, ImportIndex, InferenceCache) + * are cleared and rebuilt from scratch by walking the CST.
+ * + *If the analyzer has been {@linkplain #dispose() disposed}, this + * method is a no-op.
+ * + * @param syntax the document syntax to analyze (immutable snapshot from + * the parser); must not be {@code null} + * @param revision the revision number for stale-detection; callers should + * use a monotonically increasing counter + * @param callback the callback to invoke with results; must not be + * {@code null} + * @throws IllegalArgumentException if {@code syntax} or {@code callback} + * is {@code null} + */ + public void scheduleAnalysis(DocumentSyntax syntax, long revision, AnalysisCallback callback) { + validateScheduleArguments(syntax, revision, callback); + if (disposed) { + return; + } + + currentRevision.set(revision); + cancelInFlight(); + + inFlightAnalysis = executor.submit(new FullAnalysisTask(syntax, revision, callback)); + } + + /** + * Schedules an incremental analysis using the provided invalidation scope. + * + *Only rebuilds the affected parts of the semantic model, as determined + * by the {@link InvalidationScope}:
+ *Any currently in-flight analysis is cancelled before scheduling. + * If the analyzer has been {@linkplain #dispose() disposed}, this method + * is a no-op.
+ * + * @param syntax the document syntax after reparse; must not be + * {@code null} + * @param revision the revision number for stale-detection + * @param scope the invalidation scope from {@link IncrementalStrategy}; + * must not be {@code null} + * @param callback the callback to invoke with results; must not be + * {@code null} + * @throws IllegalArgumentException if any argument is {@code null} + */ + public void scheduleIncrementalAnalysis(DocumentSyntax syntax, long revision, + InvalidationScope scope, + AnalysisCallback callback) { + validateScheduleArguments(syntax, revision, callback); + if (scope == null) { + throw new IllegalArgumentException("scope must not be null"); + } + if (disposed) { + return; + } + + currentRevision.set(revision); + cancelInFlight(); + + inFlightAnalysis = executor.submit( + new IncrementalAnalysisTask(syntax, revision, scope, callback) + ); + } + + /** + * Cancels any in-flight analysis. Safe to call from any thread. + * + *If an analysis is currently running, it is interrupted via + * {@link Future#cancel(boolean) cancel(true)}. The background task checks + * for interruption at key points and will bail out gracefully.
+ * + *After cancellation, {@link #isAnalyzing()} will return {@code false} + * once the background thread has actually stopped (which may not be + * immediate if the task is in the middle of a non-interruptible + * operation).
+ */ + public void cancelInFlight() { + Future> current = inFlightAnalysis; + if (current != null && !current.isDone()) { + current.cancel(true); + } + inFlightAnalysis = null; + } + + /** + * Returns whether an analysis is currently running or queued. + * + *A return value of {@code true} means there is a {@link Future} that + * has not yet completed. Note that due to the inherent race between + * checking and acting, this method is advisory only — the analysis + * may complete (or be cancelled) between the check and the caller's next + * action.
+ * + * @return {@code true} if an analysis task is in flight + */ + public boolean isAnalyzing() { + Future> current = inFlightAnalysis; + return current != null && !current.isDone(); + } + + /** + * Returns the current semantic model. + * + *The returned reference is the live model that the background + * thread mutates during analysis. Callers should be aware that the model's + * contents may change between calls if an analysis is in flight. For + * consistent reads, callers should either:
+ *This method is primarily intended for incremental analysis paths that + * need access to the previous model state before scheduling an update.
+ * + * @return the semantic model (never {@code null}) + */ + public SemanticModel getSemanticModel() { + return semanticModel; + } + + /** + * Returns the incremental strategy used by this analyzer. + * + *The strategy is stateless and can be used by external callers + * (e.g., the orchestrator) to classify edits before deciding whether + * to call {@link #scheduleAnalysis} or + * {@link #scheduleIncrementalAnalysis}.
+ * + * @return the incremental strategy (never {@code null}) + */ + public IncrementalStrategy getStrategy() { + return strategy; + } + + /** + * Returns the revision number that was most recently submitted for + * analysis. + * + *This can be compared against the document's current revision to + * determine whether the latest analysis results are still relevant.
+ * + * @return the most recently submitted revision number + */ + public long getCurrentRevision() { + return currentRevision.get(); + } + + /** + * Shuts down the background executor and cancels any in-flight analysis. + * + *Must be called when the editor closes to release + * the background thread. After disposal:
+ *This method blocks for up to {@value #SHUTDOWN_TIMEOUT_MS}ms waiting + * for the executor to terminate. If the executor does not terminate in + * time, it is forcefully shut down via {@link ExecutorService#shutdownNow()}. + *
+ * + *Safe to call multiple times; subsequent calls are no-ops.
+ */ + public void dispose() { + if (disposed) { + return; + } + disposed = true; + + cancelInFlight(); + semanticModel.clear(); + + executor.shutdown(); + try { + if (!executor.awaitTermination(SHUTDOWN_TIMEOUT_MS, TimeUnit.MILLISECONDS)) { + LOGGER.log(Level.WARNING, + "Semantic analysis executor did not terminate within {0}ms; forcing shutdown", + SHUTDOWN_TIMEOUT_MS); + executor.shutdownNow(); + } + } catch (InterruptedException e) { + executor.shutdownNow(); + Thread.currentThread().interrupt(); + } + } + + /** + * Returns whether this analyzer has been disposed. + * + * @return {@code true} if {@link #dispose()} has been called + */ + public boolean isDisposed() { + return disposed; + } + + // ── Analysis tasks ───────────────────────────────────────────────────────── + + /** + * Runnable that performs a full semantic model rebuild on the background + * thread. Checks for disposal and revision staleness before and after + * the rebuild. + */ + private final class FullAnalysisTask implements Runnable { + + private final DocumentSyntax syntax; + private final long revision; + private final AnalysisCallback callback; + + FullAnalysisTask(DocumentSyntax syntax, long revision, AnalysisCallback callback) { + this.syntax = syntax; + this.revision = revision; + this.callback = callback; + } + + @Override + public void run() { + if (shouldAbort()) { + return; + } + + try { + semanticModel.rebuild(syntax); + + if (shouldAbort()) { + return; + } + + deliverSuccess(); + } catch (Exception e) { + deliverFailure(e); + } + } + + /** + * Checks whether this task should abort execution. + * + *Abort conditions:
+ *For {@link InvalidationScope#NONE}, the model is left untouched but + * the callback is still invoked so the orchestrator can apply + * offset-adjusted decorations using the existing model state.
+ */ + private final class IncrementalAnalysisTask implements Runnable { + + private final DocumentSyntax syntax; + private final long revision; + private final InvalidationScope scope; + private final AnalysisCallback callback; + + IncrementalAnalysisTask(DocumentSyntax syntax, long revision, + InvalidationScope scope, AnalysisCallback callback) { + this.syntax = syntax; + this.revision = revision; + this.scope = scope; + this.callback = callback; + } + + @Override + public void run() { + if (shouldAbort()) { + return; + } + + try { + // For NONE scope, the model is already up-to-date; we still + // invoke the callback so the orchestrator can re-apply + // decorations with corrected offsets. + if (scope != InvalidationScope.NONE) { + semanticModel.incrementalUpdate(syntax, scope); + } + + if (shouldAbort()) { + return; + } + + deliverSuccess(); + } catch (Exception e) { + deliverFailure(e); + } + } + + /** + * Checks whether this task should abort execution. + * + * @return {@code true} if the task should stop immediately + * @see FullAnalysisTask#shouldAbort() + */ + private boolean shouldAbort() { + return disposed + || Thread.currentThread().isInterrupted() + || currentRevision.get() != revision; + } + + /** + * Delivers the successful analysis result via the callback, after a + * final staleness check. + */ + private void deliverSuccess() { + if (disposed || currentRevision.get() != revision) { + return; + } + try { + callback.onAnalysisComplete(revision, semanticModel, syntax); + } catch (Exception e) { + LOGGER.log(Level.WARNING, + "Exception in AnalysisCallback.onAnalysisComplete for revision " + revision, e); + } + } + + /** + * Delivers a failure notification via the callback. + */ + private void deliverFailure(Exception error) { + if (disposed || Thread.currentThread().isInterrupted()) { + return; + } + try { + callback.onAnalysisFailed(revision, error); + } catch (Exception e) { + LOGGER.log(Level.WARNING, + "Exception in AnalysisCallback.onAnalysisFailed for revision " + revision, e); + } + } + } + + // ── Argument validation ──────────────────────────────────────────────────── + + /** + * Validates common arguments for the {@code schedule*} methods. + * + * @param syntax the document syntax (must not be {@code null}) + * @param revision the revision number (informational; no constraint) + * @param callback the analysis callback (must not be {@code null}) + * @throws IllegalArgumentException if {@code syntax} or {@code callback} + * is {@code null} + */ + private static void validateScheduleArguments(DocumentSyntax syntax, long revision, + AnalysisCallback callback) { + if (syntax == null) { + throw new IllegalArgumentException("syntax must not be null"); + } + if (callback == null) { + throw new IllegalArgumentException("callback must not be null"); + } + } + + // ── Thread factory ───────────────────────────────────────────────────────── + + /** + * Creates a {@link ThreadFactory} that produces a single daemon thread + * with a descriptive name and slightly reduced priority. + * + *The daemon flag ensures the thread does not prevent JVM shutdown + * (critical in Minecraft's modded environment where the game client may + * close while analysis is in flight). The reduced priority + * ({@link Thread#NORM_PRIORITY} - 1) ensures analysis does not starve + * the render thread.
+ * + * @return a thread factory for the analysis executor + */ + private static ThreadFactory createDaemonThreadFactory() { + return new ThreadFactory() { + @Override + public Thread newThread(Runnable r) { + Thread t = new Thread(r, THREAD_NAME); + t.setDaemon(true); + t.setPriority(Thread.NORM_PRIORITY - 1); + return t; + } + }; + } + + @Override + public String toString() { + return "SemanticAnalyzer{" + + "analyzing=" + isAnalyzing() + + ", revision=" + currentRevision.get() + + ", disposed=" + disposed + + ", model=" + semanticModel + + '}'; + } +} diff --git a/src/main/java/bigguy/texteditor/analysis/SemanticMarkBuilder.java b/src/main/java/bigguy/texteditor/analysis/SemanticMarkBuilder.java new file mode 100644 index 000000000..92b2dea4f --- /dev/null +++ b/src/main/java/bigguy/texteditor/analysis/SemanticMarkBuilder.java @@ -0,0 +1,576 @@ +package bigguy.texteditor.analysis; + +import bigguy.texteditor.index.Symbol; +import bigguy.texteditor.index.Symbol.FieldSymbol; +import bigguy.texteditor.index.Symbol.ImportSymbol; +import bigguy.texteditor.index.Symbol.MethodSymbol; +import bigguy.texteditor.index.Symbol.TypeSymbol; +import bigguy.texteditor.index.SymbolKind; +import bigguy.texteditor.render.Mark; +import bigguy.texteditor.semantics.SemanticModel; +import bigguy.texteditor.semantics.SymbolTable; +import bigguy.texteditor.syntax.DocumentSyntax; +import bigguy.texteditor.syntax.SemanticNode; +import bigguy.texteditor.treesitter.java.TextSpan; +import noppes.npcs.client.gui.util.script.interpreter.token.TokenType; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.HashSet; +import java.util.List; +import java.util.Set; + +/** + * Translates the semantic model (symbols extracted from the CST) into {@link Mark} + * objects that the render pipeline can merge with syntax marks. + * + *This builder bridges semantic analysis and visual rendering. It walks the CST + * via {@link DocumentSyntax} to locate the name portion of each declaration, + * then creates a {@link Mark#semantic(int, int, TokenType, Object) semantic mark} + * with the correct {@link TokenType} and the originating {@link Symbol} as metadata. + * Attaching the symbol enables downstream features like hover tooltips and + * go-to-definition.
+ * + *{@link Symbol#range()} covers the entire declaration (e.g., the full + * {@code public class Foo { ... }} block for a {@link TypeSymbol}). Highlighting + * the full range would incorrectly color keywords, punctuation, and body content. + * By walking the CST and extracting each declaration's "name" child node, we + * highlight only the identifier — matching what users expect from a modern IDE.
+ * + *| Symbol type | Condition | TokenType |
|---|---|---|
| {@link TypeSymbol} | {@link SymbolKind#CLASS} | + *{@link TokenType#CLASS_DECL} |
| {@link TypeSymbol} | {@link SymbolKind#INTERFACE} | + *{@link TokenType#INTERFACE_DECL} |
| {@link TypeSymbol} | {@link SymbolKind#ENUM} | + *{@link TokenType#ENUM_DECL} |
| {@link TypeSymbol} | {@link SymbolKind#ANNOTATION} | + *{@link TokenType#JSDOC_TAG} |
| {@link MethodSymbol} | any | + *{@link TokenType#METHOD_DECL} |
| {@link FieldSymbol} | static & final | + *{@link TokenType#STATIC_FINAL_FIELD} |
| {@link FieldSymbol} | otherwise | + *{@link TokenType#GLOBAL_FIELD} |
| {@link ImportSymbol} | always | + *{@link TokenType#IMPORTED_CLASS} |
This class is stateless — all state lives in the method parameters. + * It is safe to call {@link #build(SemanticModel, DocumentSyntax)} from any + * thread, provided the model and syntax are not being concurrently mutated.
+ * + * @see Mark#semantic(int, int, TokenType, Object) + * @see SemanticModel + * @see SymbolTable + */ +public final class SemanticMarkBuilder { + + // ── CST node type constants (mirror SemanticModel's constants) ────────── + + private static final String NODE_IMPORT_DECLARATION = "import_declaration"; + private static final String NODE_CLASS_DECLARATION = "class_declaration"; + private static final String NODE_INTERFACE_DECLARATION = "interface_declaration"; + private static final String NODE_ENUM_DECLARATION = "enum_declaration"; + private static final String NODE_ANNOTATION_TYPE_DECLARATION = "annotation_type_declaration"; + private static final String NODE_METHOD_DECLARATION = "method_declaration"; + private static final String NODE_CONSTRUCTOR_DECLARATION = "constructor_declaration"; + private static final String NODE_FIELD_DECLARATION = "field_declaration"; + private static final String NODE_VARIABLE_DECLARATOR = "variable_declarator"; + private static final String NODE_SCOPED_IDENTIFIER = "scoped_identifier"; + private static final String NODE_IDENTIFIER = "identifier"; + + private static final String FIELD_NAME = "name"; + + /** + * All CST node types that represent type declarations. + */ + private static final SetWalks all declaration nodes in the CST, looks up the corresponding + * {@link Symbol} in the {@link SymbolTable}, and creates a + * {@link Mark#semantic(int, int, TokenType, Object)} for each declaration's + * name node. Only the name identifier is highlighted — keywords, + * modifiers, and body content are left to tree-sitter's syntax marks.
+ * + *The returned list is unsorted. Callers (typically {@code MarkLayer}) + * should sort the marks before merging them with syntax marks.
+ * + * @param model the populated semantic model (may be {@code null}) + * @param syntax the document syntax produced by the parser (may be {@code null}) + * @return a mutable list of semantic marks, never {@code null}; empty if the + * model is not built or either argument is {@code null} + */ + public static List build(SemanticModel model, DocumentSyntax syntax) { + if (model == null || syntax == null || !model.isBuilt()) { + return Collections.emptyList(); + } + + SymbolTable table = model.getSymbolTable(); + if (table.isEmpty()) { + return Collections.emptyList(); + } + + SemanticNode root = syntax.root(); + if (root == null) { + return Collections.emptyList(); + } + + List marks = new ArrayList(); + walkDeclarations(root, table, marks); + return marks; + } + + // ═══════════════════════════════════════════════════════════════════════════ + // CST walking + // ═══════════════════════════════════════════════════════════════════════════ + + /** + * Recursively walks the CST, visiting declaration nodes and creating marks + * for each declaration's name identifier. + * + * @param node the current CST node + * @param table the symbol table to look up symbols + * @param marks the output list to append marks to + */ + private static void walkDeclarations(SemanticNode node, SymbolTable table, List marks) { + ListFor a scoped identifier like {@code java.util.List}, the mark covers + * the entire scoped identifier node, matching how tree-sitter structures + * the import path. For wildcard imports ({@code java.util.*}), the entire + * scoped path is marked.
+ * + * @param importNode the CST node for the import declaration + * @param table the symbol table + * @param marks the output list + */ + private static void processImportDeclaration(SemanticNode importNode, + SymbolTable table, List marks) { + // Find the scoped_identifier or identifier child — this is the import path. + SemanticNode pathNode = findImportPathNode(importNode); + if (pathNode == null) { + return; + } + + TextSpan pathSpan = pathNode.span(); + if (pathSpan == null || pathSpan.getByteLength() <= 0) { + return; + } + + // Look up the import symbol by matching the full import range. + ImportSymbol symbol = findImportSymbol(table, importNode.span()); + + marks.add(Mark.semantic( + pathSpan.getStartByte(), + pathSpan.getEndByte(), + TokenType.IMPORTED_CLASS, + symbol + )); + } + + // ═══════════════════════════════════════════════════════════════════════════ + // Symbol lookup helpers + // ═══════════════════════════════════════════════════════════════════════════ + + /** + * Finds the {@link TypeSymbol} in the table matching the given name and + * whose declaration range overlaps the given CST node span. + * + *If multiple types share the same simple name (e.g., nested classes), + * the one whose range contains the declaration node's range wins.
+ * + * @param table the symbol table + * @param simpleName the type's simple name + * @param declSpan the full declaration span from the CST node + * @return the matching symbol, or {@code null} if not found + */ + private static TypeSymbol findTypeSymbol(SymbolTable table, String simpleName, + TextSpan declSpan) { + ListStatic final fields get {@link TokenType#STATIC_FINAL_FIELD} (magenta, + * bold+italic), matching IntelliJ's convention for constants. All other + * fields get {@link TokenType#GLOBAL_FIELD} (aqua).
+ * + * @param symbol the field symbol (may be {@code null} if the symbol table + * lookup failed) + * @return the token type for coloring + */ + private static TokenType mapFieldSymbol(FieldSymbol symbol) { + if (symbol != null && symbol.isStatic() && symbol.isFinal()) { + return TokenType.STATIC_FINAL_FIELD; + } + return TokenType.GLOBAL_FIELD; + } + + // ═══════════════════════════════════════════════════════════════════════════ + // Utility + // ═══════════════════════════════════════════════════════════════════════════ + + /** + * Finds the import path node (scoped_identifier or identifier) within + * an import_declaration CST node. + * + * @param importNode the import declaration node + * @return the path node, or {@code null} if not found + */ + private static SemanticNode findImportPathNode(SemanticNode importNode) { + ListSeverity levels and source categories follow the Language Server Protocol + * specification to ease future LSP integration.
+ */ +public final class Diagnostic { + + /** + * Diagnostic severity, following the LSP {@code DiagnosticSeverity} enumeration. + */ + public enum Severity { + /** A problem that prevents compilation or execution. */ + ERROR(1), + /** A potential issue that does not prevent compilation. */ + WARNING(2), + /** Informational message (e.g. deprecation notice). */ + INFO(3), + /** Subtle suggestion (e.g. unused import). */ + HINT(4); + + private final int lspValue; + + Severity(int lspValue) { + this.lspValue = lspValue; + } + + /** + * Returns the numeric value matching the LSP specification. + * + * @return the LSP {@code DiagnosticSeverity} integer (1–4) + */ + public int lspValue() { + return lspValue; + } + } + + /** + * Identifies which analysis phase produced the diagnostic, enabling + * targeted invalidation when only part of the pipeline reruns. + */ + public enum Source { + /** Syntax errors from the tree-sitter parser. */ + PARSER, + /** Declaration-level issues (duplicate names, missing types). */ + DECLARATION, + /** Type-checking errors (incompatible assignment, wrong argument type). */ + TYPE_CHECK, + /** Import resolution issues (unresolved import, wildcard ambiguity). */ + IMPORT, + /** Higher-level semantic checks (unreachable code, unused variable). */ + SEMANTIC + } + + private final TextSpan range; + private final Severity severity; + private final String message; + private final Source source; + private final String code; + + /** + * @param range the source range this diagnostic applies to + * @param severity the severity level + * @param message a human-readable description of the issue + * @param source the analysis phase that produced this diagnostic + * @param code an optional machine-readable error code (may be {@code null}) + */ + public Diagnostic(TextSpan range, Severity severity, String message, Source source, String code) { + this.range = Objects.requireNonNull(range, "range"); + this.severity = Objects.requireNonNull(severity, "severity"); + this.message = Objects.requireNonNull(message, "message"); + this.source = Objects.requireNonNull(source, "source"); + this.code = code; + } + + /** + * Convenience factory for diagnostics without an error code. + * + * @param range the source range + * @param severity the severity level + * @param message a human-readable description + * @param source the originating analysis phase + * @return a new diagnostic with a {@code null} error code + */ + public static Diagnostic of(TextSpan range, Severity severity, String message, Source source) { + return new Diagnostic(range, severity, message, source, null); + } + + /** @return the source range this diagnostic applies to */ + public TextSpan range() { return range; } + + /** @return the severity level */ + public Severity severity() { return severity; } + + /** @return a human-readable description of the issue */ + public String message() { return message; } + + /** @return the analysis phase that produced this diagnostic */ + public Source source() { return source; } + + /** @return an optional machine-readable error code, or {@code null} */ + public String code() { return code; } + + /** @return {@code true} if this diagnostic represents a compilation error */ + public boolean isError() { + return severity == Severity.ERROR; + } + + /** @return {@code true} if this diagnostic represents a warning */ + public boolean isWarning() { + return severity == Severity.WARNING; + } + + @Override + public boolean equals(Object obj) { + if (this == obj) return true; + if (!(obj instanceof Diagnostic)) return false; + Diagnostic that = (Diagnostic) obj; + return range.equals(that.range) + && severity == that.severity + && message.equals(that.message) + && source == that.source + && Objects.equals(code, that.code); + } + + @Override + public int hashCode() { + int result = range.hashCode(); + result = 31 * result + severity.hashCode(); + result = 31 * result + message.hashCode(); + result = 31 * result + source.hashCode(); + result = 31 * result + (code != null ? code.hashCode() : 0); + return result; + } + + @Override + public String toString() { + String loc = range.getStartRow() + ":" + range.getStartColumn(); + String codeStr = code != null ? " [" + code + "]" : ""; + return severity.name().toLowerCase() + "(" + loc + "): " + message + codeStr + + " (" + source.name().toLowerCase() + ")"; + } +} diff --git a/src/main/java/bigguy/texteditor/diagnostics/DiagnosticStore.java b/src/main/java/bigguy/texteditor/diagnostics/DiagnosticStore.java new file mode 100644 index 000000000..9dcf5acb9 --- /dev/null +++ b/src/main/java/bigguy/texteditor/diagnostics/DiagnosticStore.java @@ -0,0 +1,171 @@ +package bigguy.texteditor.diagnostics; + +import bigguy.texteditor.diagnostics.Diagnostic.Severity; +import bigguy.texteditor.diagnostics.Diagnostic.Source; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; +import java.util.concurrent.CopyOnWriteArrayList; +import java.util.concurrent.atomic.AtomicInteger; + +/** + * Thread-safe, centralized storage for diagnostics with query capabilities. + * + *Diagnostics are added from background analysis threads and read from the + * UI thread. All mutation operations increment the internal {@link #version()}, + * allowing consumers to detect changes cheaply via version comparison.
+ * + *All query methods return unmodifiable snapshots — callers never see + * the internal mutable list.
+ */ +public final class DiagnosticStore { + + private final CopyOnWriteArrayListFollows IntelliJ's {@code PsiElement} specialization pattern: a common + * interface with concrete final implementations for each symbol category.
+ */ +public interface Symbol { + + /** @return the unique key identifying this symbol */ + SymbolKey key(); + + /** @return the source range of the symbol's declaration */ + TextSpan range(); + + /** @return the symbol's simple name */ + String name(); + + /** @return the classification of this symbol */ + SymbolKind kind(); + + /** + * A type declaration (class, interface, enum, annotation). + */ + final class TypeSymbol implements Symbol { + + private final SymbolKey key; + private final TextSpan range; + private final String simpleName; + private final String fullName; + private final String dotName; + + /** + * @param key the unique key for this symbol + * @param range the declaration's source range + * @param simpleName the unqualified type name + * @param fullName the fully qualified name (e.g. "java.util.List") + * @param dotName the dot-path from enclosing scope (e.g. "Outer.Inner") + */ + public TypeSymbol(SymbolKey key, TextSpan range, String simpleName, + String fullName, String dotName) { + this.key = Objects.requireNonNull(key, "key"); + this.range = Objects.requireNonNull(range, "range"); + this.simpleName = Objects.requireNonNull(simpleName, "simpleName"); + this.fullName = Objects.requireNonNull(fullName, "fullName"); + this.dotName = Objects.requireNonNull(dotName, "dotName"); + } + + @Override public SymbolKey key() { return key; } + @Override public TextSpan range() { return range; } + @Override public String name() { return simpleName; } + @Override public SymbolKind kind() { return key.kind(); } + + /** @return the fully qualified name (e.g. "java.util.List") */ + public String fullName() { return fullName; } + + /** @return the dot-path from enclosing scope (e.g. "Outer.Inner") */ + public String dotName() { return dotName; } + + @Override + public boolean equals(Object obj) { + if (this == obj) return true; + if (!(obj instanceof TypeSymbol)) return false; + TypeSymbol that = (TypeSymbol) obj; + return key.equals(that.key); + } + + @Override + public int hashCode() { return key.hashCode(); } + + @Override + public String toString() { + return kind().displayName() + " " + fullName + " at " + range; + } + } + + /** + * A method or constructor declaration. + */ + final class MethodSymbol implements Symbol { + + private final SymbolKey key; + private final TextSpan range; + private final String name; + private final TextSpan bodyRange; + private final ListTwo keys are equal if and only if they share the same name, kind, and range. + * This guarantees uniqueness even for overloaded methods or shadowed variables + * at different scopes.
+ */ +public final class SymbolKey { + + private final String name; + private final SymbolKind kind; + private final TextSpan range; + + /** + * @param name the symbol's simple name + * @param kind the classification of the symbol + * @param range the source range of the symbol's declaration + */ + public SymbolKey(String name, SymbolKind kind, TextSpan range) { + this.name = Objects.requireNonNull(name, "name"); + this.kind = Objects.requireNonNull(kind, "kind"); + this.range = Objects.requireNonNull(range, "range"); + } + + /** @return the symbol's simple name */ + public String name() { return name; } + + /** @return the classification of the symbol */ + public SymbolKind kind() { return kind; } + + /** @return the source range of the symbol's declaration */ + public TextSpan range() { return range; } + + /** + * Returns a dot-qualified name for nested type display (e.g. "Outer.Inner"). + * For non-nested symbols this returns the simple name. + * + * @return the qualified name + */ + public String qualifiedName() { + return name; + } + + @Override + public boolean equals(Object obj) { + if (this == obj) return true; + if (!(obj instanceof SymbolKey)) return false; + SymbolKey that = (SymbolKey) obj; + return name.equals(that.name) && kind == that.kind && range.equals(that.range); + } + + @Override + public int hashCode() { + int result = name.hashCode(); + result = 31 * result + kind.hashCode(); + result = 31 * result + range.hashCode(); + return result; + } + + @Override + public String toString() { + return kind.displayName() + " '" + name + "' at " + range; + } +} diff --git a/src/main/java/bigguy/texteditor/index/SymbolKind.java b/src/main/java/bigguy/texteditor/index/SymbolKind.java new file mode 100644 index 000000000..8110d7b8d --- /dev/null +++ b/src/main/java/bigguy/texteditor/index/SymbolKind.java @@ -0,0 +1,84 @@ +package bigguy.texteditor.index; + +/** + * Classifies symbols within a source document for indexing, navigation, and + * icon display. + * + *Follows the LSP {@code SymbolKind} enumeration and IntelliJ IDEA's + * {@code IElementType} hierarchy, covering the Java language constructs + * relevant to the script editor.
+ */ +public enum SymbolKind { + + CLASS("Class", true, false, false), + INTERFACE("Interface", true, false, false), + ENUM("Enum", true, false, false), + ANNOTATION("Annotation", true, false, false), + METHOD("Method", false, true, false), + CONSTRUCTOR("Constructor", false, true, false), + FIELD("Field", false, false, true), + PARAMETER("Parameter", false, false, true), + LOCAL_VARIABLE("Local Variable", false, false, true), + IMPORT("Import", false, false, false), + PACKAGE("Package", false, false, false), + TYPE_PARAMETER("Type Parameter", false, false, false), + LAMBDA("Lambda", false, true, false), + ENUM_CONSTANT("Enum Constant", false, false, true), + STATIC_INITIALIZER("Static Initializer", false, false, false); + + private final String displayName; + private final boolean type; + private final boolean callable; + private final boolean variable; + + SymbolKind(String displayName, boolean type, boolean callable, boolean variable) { + this.displayName = displayName; + this.type = type; + this.callable = callable; + this.variable = variable; + } + + /** + * Returns a human-readable name suitable for UI display (e.g. "Local Variable"). + * + * @return the display name + */ + public String displayName() { + return displayName; + } + + /** + * Returns {@code true} for type-declaring symbols: + * {@link #CLASS}, {@link #INTERFACE}, {@link #ENUM}, {@link #ANNOTATION}. + * + * @return whether this kind represents a type declaration + */ + public boolean isType() { + return type; + } + + /** + * Returns {@code true} for callable symbols: + * {@link #METHOD}, {@link #CONSTRUCTOR}, {@link #LAMBDA}. + * + * @return whether this kind represents something that can be invoked + */ + public boolean isCallable() { + return callable; + } + + /** + * Returns {@code true} for variable-like symbols: + * {@link #FIELD}, {@link #PARAMETER}, {@link #LOCAL_VARIABLE}, {@link #ENUM_CONSTANT}. + * + * @return whether this kind represents a named value holder + */ + public boolean isVariable() { + return variable; + } + + @Override + public String toString() { + return displayName; + } +} diff --git a/src/main/java/bigguy/texteditor/render/Mark.java b/src/main/java/bigguy/texteditor/render/Mark.java new file mode 100644 index 000000000..e907806be --- /dev/null +++ b/src/main/java/bigguy/texteditor/render/Mark.java @@ -0,0 +1,182 @@ +package bigguy.texteditor.render; + +import noppes.npcs.client.gui.util.script.interpreter.token.TokenType; + +/** + * A highlight region produced by the analysis pipeline. + * Marks bridge the gap between CST/semantic analysis and token rendering. + * + *Marks are produced by: + *
Multiple marks can overlap. {@link MarkLayer} resolves conflicts using + * {@link TokenType#getPriority()}. + * + *
Sorting order (used by {@link MarkLayer#merge()}): + *
Thread safety: syntax marks are set from the UI thread while semantic marks + * arrive from a background analysis thread. All mutators are synchronized; + * {@link #merge()} produces a snapshot safe for the caller to iterate without + * holding the lock. + * + *
A monotonically increasing {@link #getRevision() revision} counter lets
+ * consumers detect stale merge results cheaply.
+ */
+public class MarkLayer {
+
+ private List syntaxMarks = Collections.emptyList();
+ private List semanticMarks = Collections.emptyList();
+ private List errorMarks = Collections.emptyList();
+ private volatile int revision;
+
+ /**
+ * Replace the syntax mark layer (produced by tree-sitter highlight queries).
+ *
+ * @param marks new syntax marks; must not be null
+ */
+ public synchronized void setSyntaxMarks(List marks) {
+ this.syntaxMarks = new ArrayList<>(marks);
+ revision++;
+ }
+
+ /**
+ * Replace the semantic mark layer (produced by type resolution / scope analysis).
+ * Typically called from a background thread.
+ *
+ * @param marks new semantic marks; must not be null
+ */
+ public synchronized void setSemanticMarks(List marks) {
+ this.semanticMarks = new ArrayList<>(marks);
+ revision++;
+ }
+
+ /**
+ * Replace the error mark layer (diagnostic underlines).
+ * Error marks do not participate in color conflict resolution —
+ * they are kept in a separate channel and drawn as underlines.
+ *
+ * @param marks new error marks; must not be null
+ */
+ public synchronized void setErrorMarks(List marks) {
+ this.errorMarks = new ArrayList<>(marks);
+ revision++;
+ }
+
+ /** @return the current syntax marks (defensive copy) */
+ public synchronized List getSyntaxMarks() {
+ return new ArrayList<>(syntaxMarks);
+ }
+
+ /** @return the current semantic marks (defensive copy) */
+ public synchronized List getSemanticMarks() {
+ return new ArrayList<>(semanticMarks);
+ }
+
+ /**
+ * Error marks are kept in their own channel and drawn as underlines
+ * rather than merged into the color layer.
+ *
+ * @return the current error marks (defensive copy)
+ */
+ public synchronized List getErrorMarks() {
+ return new ArrayList<>(errorMarks);
+ }
+
+ /**
+ * Monotonically increasing counter that increments on every mutation.
+ * Compare against a cached value to detect stale merge results.
+ *
+ * @return current revision
+ */
+ public int getRevision() {
+ return revision;
+ }
+
+ /**
+ * Merge syntax and semantic marks into a single non-overlapping list.
+ * Error marks are NOT included — they live in a separate rendering channel.
+ *
+ * Algorithm:
+ * Rendering flows through two paths:
+ * Tokens are immutable after {@link #buildTokensFromMarks(List, String)} completes.
+ * Error underlines are drawn via caller-supplied {@link DiagnosticRange} records
+ * rather than reaching back into a document object.
+ */
+public class RenderLine {
+
+ private static final char COLOR_CHAR = '\u00A7';
+
+ private final String text;
+ private final int globalStart;
+ private final int globalEnd;
+ private final int lineIndex;
+
+ private final List This is the decoupled replacement for
+ * {@code ScriptLine.buildTokensFromMarks(marks, fullText, document)}.
+ * No ScriptDocument parameter — removes the coupling.
+ *
+ * @param marks list of highlight marks that overlap this line, sorted by start position
+ * @param fullText the complete document text
+ */
+ public void buildTokensFromMarks(List marks, String fullText) {
+ tokens.clear();
+ int cursor = globalStart;
+
+ /*
+ * globalEnd includes the newline character position
+ * (lineEnd = lineStart + text.length() + 1), but the line's text field
+ * does NOT include the newline. Clamp all token boundaries to the
+ * displayable text end so that '\n' never leaks into rendered token text.
+ */
+ int displayEnd = Math.min(globalStart + text.length(), fullText.length());
+
+ for (Mark mark : marks) {
+ if (mark.end <= globalStart || mark.start >= displayEnd) {
+ continue;
+ }
+
+ int tokenStart = Math.max(mark.start, globalStart);
+ int tokenEnd = Math.min(mark.end, displayEnd);
+
+ tokenStart = Math.max(0, Math.min(tokenStart, fullText.length()));
+ tokenEnd = Math.max(0, Math.min(tokenEnd, fullText.length()));
+
+ if (cursor < tokenStart) {
+ int gapEnd = Math.min(tokenStart, fullText.length());
+ String gapText = fullText.substring(cursor, gapEnd);
+ addToken(Token.defaultToken(gapText, cursor, gapEnd));
+ }
+
+ if (tokenStart < tokenEnd) {
+ String tokenText = fullText.substring(tokenStart, tokenEnd);
+ Token token = new Token(tokenText, tokenStart, tokenEnd, mark.type);
+
+ if (mark.metadata != null) {
+ applyTokenMetadata(token, mark.metadata);
+ }
+
+ addToken(token);
+ }
+
+ cursor = tokenEnd;
+ }
+
+ if (cursor < displayEnd) {
+ String trailingText = fullText.substring(cursor, displayEnd);
+ addToken(Token.defaultToken(trailingText, cursor, displayEnd));
+ }
+ }
+
+ /**
+ * Apply analysis metadata to a token based on the metadata's runtime type.
+ * Handles TypeInfo, TypeParamInfo, MethodCallInfo, FieldInfo.ArgInfo,
+ * FieldInfo, MethodInfo, ImportData, FieldAccessInfo, and TokenErrorMessage.
+ *
+ * @param token the token to enrich
+ * @param metadata the analysis artifact
+ */
+ public void applyTokenMetadata(Token token, Object metadata) {
+ if (metadata instanceof TypeInfo) {
+ token.setTypeInfo((TypeInfo) metadata);
+ } else if (metadata instanceof TypeParamInfo) {
+ TypeParamInfo typeParam = (TypeParamInfo) metadata;
+ token.setTypeInfo(TypeInfo.typeParameter(typeParam.getName(), typeParam));
+ } else if (metadata instanceof MethodCallInfo) {
+ MethodCallInfo callInfo = (MethodCallInfo) metadata;
+ if (callInfo.isConstructor()) {
+ token.setTypeInfo(callInfo.getReceiverType());
+ token.setMethodInfo(callInfo.getResolvedMethod());
+ }
+ token.setMethodCallInfo(callInfo);
+ } else if (metadata instanceof FieldInfo.ArgInfo) {
+ FieldInfo.ArgInfo ctx = (FieldInfo.ArgInfo) metadata;
+ token.setFieldInfo(ctx.fieldInfo);
+ token.setMethodCallInfo(ctx.methodCallInfo);
+ } else if (metadata instanceof FieldInfo) {
+ token.setFieldInfo((FieldInfo) metadata);
+ } else if (metadata instanceof MethodInfo) {
+ token.setMethodInfo((MethodInfo) metadata);
+ } else if (metadata instanceof ImportData) {
+ token.setImportData((ImportData) metadata);
+ } else if (metadata instanceof FieldAccessInfo) {
+ FieldAccessInfo accessInfo = (FieldAccessInfo) metadata;
+ token.setFieldAccessInfo(accessInfo);
+ token.setFieldInfo(accessInfo.getResolvedField());
+ } else if (metadata instanceof TokenErrorMessage) {
+ token.setErrorMessage((TokenErrorMessage) metadata);
+ }
+ }
+
+ /**
+ * Add a token to this line and wire up intra-line navigation links.
+ */
+ private void addToken(Token token) {
+ if (!tokens.isEmpty()) {
+ Token last = tokens.get(tokens.size() - 1);
+ last.setNext(token);
+ token.setPrev(last);
+ }
+ token.setParentLine(null);
+ tokens.add(token);
+ }
+
+ // ==================== INDENT GUIDES ====================
+
+ /** Remove all indent guides from this line. */
+ public void clearIndentGuides() {
+ indentGuides.clear();
+ }
+
+ /**
+ * Add an indent guide at the specified column if not already present.
+ *
+ * @param column the column position for the guide
+ */
+ public void addIndentGuide(int column) {
+ if (!indentGuides.contains(column)) {
+ indentGuides.add(column);
+ }
+ }
+
+ // ==================== RENDERING ====================
+
+ /**
+ * Compute the rendered pixel width of a substring of this line, accounting for
+ * bold/italic token styles. Characters covered by bold or italic tokens are
+ * measured with the appropriate font style via
+ * {@link ClientProxy.Font#width(String, int)}, producing the same widths as the
+ * actual rendered output.
+ *
+ * Critical for cursor positioning and error underline alignment.
+ *
+ * @param localStart start index within the line text (inclusive)
+ * @param localEnd end index within the line text (exclusive)
+ * @return pixel width matching the rendered output
+ */
+ public int getRenderedWidth(int localStart, int localEnd) {
+ localStart = Math.max(0, Math.min(localStart, text.length()));
+ localEnd = Math.max(localStart, Math.min(localEnd, text.length()));
+ if (localStart >= localEnd) return 0;
+
+ int width = 0;
+ int cursor = localStart;
+
+ for (Token t : tokens) {
+ if (cursor >= localEnd) break;
+
+ int tokenLocalStart = t.getGlobalStart() - globalStart;
+ int tokenLocalEnd = tokenLocalStart + t.getText().length();
+
+ // Gap before this token (rendered as plain text)
+ if (cursor < tokenLocalStart) {
+ int gapEnd = Math.min(tokenLocalStart, localEnd);
+ if (gapEnd > cursor) {
+ width += ClientProxy.Font.width(text.substring(cursor, gapEnd));
+ cursor = gapEnd;
+ }
+ }
+
+ if (cursor >= localEnd) break;
+
+ // Token overlap with [localStart, localEnd)
+ int overlapStart = Math.max(cursor, tokenLocalStart);
+ int overlapEnd = Math.min(tokenLocalEnd, localEnd);
+ if (overlapEnd > overlapStart) {
+ String substr = text.substring(overlapStart, overlapEnd);
+ width += ClientProxy.Font.width(substr, t.getFontStyle());
+ cursor = overlapEnd;
+ }
+ }
+
+ // Trailing text after last token (plain)
+ if (cursor < localEnd) {
+ width += ClientProxy.Font.width(text.substring(cursor, localEnd));
+ }
+
+ return width;
+ }
+
+ /**
+ * Draw this line with hex colors. THE PRIMARY RENDERER.
+ * Builds {@link RenderSegment}s from the token list, then renders each one
+ * at the correct pixel offset via
+ * {@link ClientProxy.Font#drawString(String, int, int, int)}.
+ *
+ * Does NOT draw error underlines — call
+ * {@link #drawErrorUnderlines(int, int, List)} separately with
+ * caller-supplied diagnostics.
+ *
+ * @param x left pixel coordinate
+ * @param y top pixel coordinate
+ */
+ public void drawStringHex(int x, int y) {
+ int lastIndex = 0;
+ List Replaces the layout fields previously scattered across {@code ScriptDocument}:
+ * {@code lineHeight}, {@code totalHeight}, {@code visibleLines}, {@code linesCount}.
+ *
+ * Thread safety: the {@code lines} reference is volatile so that a background
+ * rebuild can publish a new list that the render thread picks up on the next frame.
+ * Individual reads through the accessors are safe without external synchronization.
+ */
+public class RenderModel {
+
+ private volatile List Immutable value type consumed during {@link RenderLine#drawStringHex(int, int)}
+ * rendering. Segments are built on each draw call from the line's token list and
+ * are not cached.
+ */
+public final class RenderSegment {
+
+ /** Local offset within the line text where this segment starts. */
+ public final int startPosition;
+
+ /** The displayable text content (may include style prefix codes for tokens). */
+ public final String text;
+
+ /** ARGB hex color for rendering (e.g. 0xFFFF5555 for red). */
+ public final int hexColor;
+
+ /** True if this segment was produced from a Token; false for gap/trailing text. */
+ public final boolean isToken;
+
+ /**
+ * @param startPosition local offset within the line text
+ * @param text displayable text content
+ * @param hexColor ARGB hex color
+ * @param isToken true when this segment originates from a Token
+ */
+ public RenderSegment(int startPosition, String text, int hexColor, boolean isToken) {
+ this.startPosition = startPosition;
+ this.text = text;
+ this.hexColor = hexColor;
+ this.isToken = isToken;
+ }
+
+ @Override
+ public String toString() {
+ return "RenderSegment{pos=" + startPosition
+ + ", text='" + text + "'"
+ + ", color=0x" + Integer.toHexString(hexColor)
+ + (isToken ? ", token" : ", gap")
+ + "}";
+ }
+}
diff --git a/src/main/java/bigguy/texteditor/semantics/ImportIndex.java b/src/main/java/bigguy/texteditor/semantics/ImportIndex.java
new file mode 100644
index 000000000..a963ea7c7
--- /dev/null
+++ b/src/main/java/bigguy/texteditor/semantics/ImportIndex.java
@@ -0,0 +1,530 @@
+package bigguy.texteditor.semantics;
+
+import bigguy.texteditor.treesitter.java.TextSpan;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * Unified import resolution index for a single script document.
+ *
+ * Replaces the four separate import-tracking fields that previously lived in
+ * {@code ScriptDocument} ({@code imports}, {@code wildcardPackages},
+ * {@code importsBySimpleName}, {@code implicitImports}) with a single source of
+ * truth backed by a list of {@link ImportEntry} objects. Two derived lookup maps ({@code bySimpleName} and {@code byFullPath}) are
+ * computed lazily on first access after any mutation, and cached until the next
+ * mutation invalidates them. This gives O(1) lookups without paying rebuild
+ * cost on every add. A monotonically increasing version counter is bumped on every mutation.
+ * External code can call {@link #version()} to detect whether the index has
+ * changed since its last snapshot. All mutation methods are {@code synchronized}. All query methods return
+ * defensive copies or unmodifiable snapshots, so callers never observe
+ * partially-mutated state. Instances are immutable. Two entries are equal if and only if they
+ * share the same {@code fullPath} and {@code isImplicit} flag — the
+ * source range is deliberately excluded from equality so that
+ * re-parsing the same import at a different offset does not produce
+ * a spurious "changed" signal. Automatically derives {@code simpleName}, {@code isWildcard}, and
+ * {@code packagePath} from the path. The entry is created with {@code isImplicit=true}, {@code isStatic=false},
+ * and {@code range=null}. The previous contents are discarded. This is the preferred method
+ * when rebuilding imports from a fresh parse — it avoids intermediate
+ * states visible to concurrent readers. Resolution order: This checks both exact matches (e.g. an implicit import of
+ * {@code "java.lang.String"}) and wildcard matches (e.g. an implicit
+ * import of {@code "java.lang.*"} covers {@code "java.lang.String"}). Wildcard implicit imports are never removed by this method, since
+ * they cannot be matched by simple name alone. This is typically called after the token-build pass to discard
+ * implicit imports that turned out to be unused. The version is bumped on every mutation. External code can snapshot
+ * this value and later compare to detect whether the index has changed. Replaces three separate cache maps that previously lived in
+ * {@code ScriptDocument}: The old code used raw {@code int} keys with no type safety. This
+ * class preserves the integer-keyed approach but provides strongly-typed
+ * accessor families ({@code putObjectLiteral}/{@code getObjectLiteral},
+ * {@code putLambda}/{@code getLambda}, {@code putSamContext}/{@code getSamContext})
+ * so callers cannot accidentally cross-contaminate caches. Cache entries are stored as {@link Object} internally because the
+ * concrete analysis types ({@code ObjectLiteralAnalysis},
+ * {@code LambdaCacheEntry}) live in the legacy package and this class
+ * must not depend on them. Generic getter methods perform unchecked casts
+ * that are safe as long as callers maintain type consistency per cache
+ * family. Each cache instance tracks the source version it was built against.
+ * When the source changes, callers invoke {@link #invalidateIfStale(int)}
+ * to clear all entries if the version has drifted. This class is not thread-safe. It is designed to be
+ * accessed exclusively from the analysis thread. If cross-thread access
+ * is needed in the future, external synchronization must be applied. This does not automatically invalidate existing entries.
+ * Call {@link #invalidateIfStale(int)} for conditional invalidation,
+ * or {@link #invalidateAll()} to force a full clear. This is the standard entry point at the start of an analysis pass:
+ * if the source has changed since the last pass, all cached results are
+ * stale and must be discarded. This supports fine-grained incremental invalidation: when a small
+ * edit occurs, only entries overlapping the edited range need to be
+ * discarded. The SAM context cache (string-keyed) is left untouched
+ * since method names are not offset-based. Any entry whose byte-offset key is strictly greater than
+ * {@code editStart} has its key shifted by {@code delta}. Entries at
+ * or before {@code editStart} are left in place. The SAM context
+ * cache (string-keyed) is not affected. This is used for incremental updates: after a small insertion or
+ * deletion, existing cache entries that follow the edit point can be
+ * reused if their keys are shifted to match the new byte layout. Replaces ScriptDocument's triple-nested {@code methodLocals}
+ * ({@code Map A {@code ScopeTree} instance is built once from a {@link DocumentSyntax}
+ * snapshot and is effectively immutable after construction. Multiple threads
+ * may query it concurrently without synchronization. Abstract base class (not an interface) because Java 8 lacks sealed
+ * types. Concrete subclasses are static inner classes of {@link ScopeTree}. Walks the CST recursively, creating scope nodes for each
+ * scope-introducing tree-sitter node type, extracting local variable
+ * declarations, and attaching scope references to {@link SemanticNode}s
+ * via {@link SemanticNode#setScope(Object)}. Algorithm: Uses a top-down walk from the root, narrowing into the child whose
+ * range contains the offset. Among children at the same level, the tightest
+ * (smallest range) match wins. For scope-introducing nodes, creates the appropriate {@link Scope}
+ * subclass. For variable-declaring nodes within a scope, extracts the
+ * declaration and adds it to the scope's locals. Attaches the scope
+ * to the {@link SemanticNode} via {@code setScope}. Handles: Grammar for formal_parameter:
+ * {@code (formal_parameter type: (_) name: (identifier))}
+ * Also handles {@code dimensions: "[]"} for array parameters. Grammar: {@code (local_variable_declaration type: (_)
+ * declarator: (variable_declarator name: (identifier) [value: (_)]))}
+ * A single declaration may have multiple declarators: {@code int a, b = 1;} This is the single entry point for semantic queries, replacing the scattered
+ * field access on the legacy {@code ScriptDocument}. It owns four sub-components
+ * and provides convenience query methods that delegate to them: The model follows IntelliJ IDEA's {@code FileViewProvider} pattern: a single
+ * coordinator that lazily builds and caches multiple semantic views of the same
+ * source file. Callers access sub-components directly for specialised queries,
+ * or use the convenience methods on this class for common lookups. Not thread-safe. The orchestrator (background analysis thread) must
+ * coordinate access. Sub-components have their own synchronization for
+ * query-vs-mutation safety, but the model itself does not. The model starts in an unbuilt state ({@link #isBuilt()} returns
+ * {@code false}). Call {@link #rebuild(DocumentSyntax)} after the first
+ * parse to populate the semantic data structures. Called from the background analysis thread after syntax parsing.
+ * This method performs a complete rebuild of all sub-components: Only rebuilds the sub-components that are affected by the change,
+ * as determined by the {@link InvalidationScope}: Delegates to {@link ScopeTree#resolveVariable(String, int)} to
+ * walk the scope chain from the innermost scope containing the offset
+ * outward until a matching variable declaration is found. First checks the {@link SymbolTable} for locally declared types,
+ * then falls back to the {@link ImportIndex} to check if the type was
+ * imported. If found via import, creates a synthetic {@link TypeSymbol}
+ * from the import information. Delegates to {@link SymbolTable#getMethodsByName(String)}. This is a convenience method. Since exclusion data lives on the
+ * {@link DocumentSyntax} (via its {@code ExcludedRangeIndex}), callers
+ * should use {@link DocumentSyntax#isExcluded(int)} directly when they
+ * have a syntax reference. This method exists for cases where the
+ * last-known syntax snapshot is not readily available. This version is incremented on every rebuild or incremental update.
+ * Consumers can compare versions to detect staleness without inspecting
+ * individual sub-component versions. Before the first {@link #rebuild(DocumentSyntax)} call, queries
+ * will return empty results. Callers should check this flag before
+ * relying on semantic data. After calling this method, {@link #isBuilt()} returns {@code false}
+ * and all queries return empty results until {@link #rebuild(DocumentSyntax)}
+ * is called again. Handles both regular imports ({@code import java.util.List;}) and
+ * wildcard imports ({@code import java.util.*;}) by walking the
+ * scoped_identifier chain. Replaces ScriptDocument's triple-redundant type maps ({@code scriptTypes},
+ * {@code scriptTypesByFullName}, {@code scriptTypesByDotName}) and scattered
+ * method/field collections with a single source of truth. One primary {@link LinkedHashMap} stores all symbols keyed by {@link SymbolKey}.
+ * Derived index views (types by simple name, types by full name, methods by name, etc.)
+ * are rebuilt lazily on first access after any mutation. This follows IntelliJ's
+ * {@code StubIndex} pattern: one canonical store with derived, cached projections. Mutation methods ({@link #addSymbol}, {@link #removeSymbol}, {@link #replaceAll},
+ * {@link #clear}, {@link #adjustOffsets}) are {@code synchronized} and intended to be
+ * called from a background analysis thread. Query methods return unmodifiable snapshot
+ * copies and are safe to call from the UI thread without external synchronization. An {@link AtomicInteger} version counter increments on every mutation. Consumers
+ * can poll {@link #version()} to detect staleness without deep-comparing contents. This is the primary bulk-update method used after a full analysis pass.
+ * It clears the table, inserts all new symbols, and bumps the version
+ * counter exactly once. Symbols whose range starts before {@code editStart} are left unchanged.
+ * Symbols overlapping the edit point (start < editStart < end) are
+ * removed, since their ranges are no longer valid. Note: This mutates the table in-place by rebuilding
+ * affected entries with adjusted {@link TextSpan}s and new {@link SymbolKey}s.
+ * The version counter is incremented exactly once. Wraps the low-level {@link SyntaxTree} (tree-sitter) and provides: Analogous to IntelliJ's {@code PsiFile} (root PSI element for a file)
+ * and Zed's {@code SyntaxSnapshot} (immutable syntax view). Not thread-safe. The orchestrator must coordinate access
+ * (e.g., via copy-on-parse or synchronization). Walks the CST to build the {@link ExcludedRangeIndex} for string
+ * and comment regions, and initialises an empty node cache. Walks from the root downward, at each level picking the child whose
+ * span contains the offset, until no further narrowing is possible. Built once from a tree-sitter CST walk, this index answers containment
+ * and overlap queries in O(log n) via binary search over a flat sorted array.
+ * After an edit, call {@link #shiftRanges(int, int)} to produce a new index
+ * with adjusted offsets rather than rebuilding from scratch. The {@link SyntaxNode} is the structure (syntax) — it knows about
+ * node types, positions, text, and parent/child relationships. This class is
+ * the meaning (semantics layered on top) — it carries lazily-resolved
+ * type information, symbol bindings, and scope references. The three mutable slots ({@code resolvedType}, {@code symbol}, {@code scope})
+ * are typed as {@link Object} intentionally. The concrete types (TypeInfo, Symbol,
+ * Scope) live in downstream packages that do not yet exist. Using {@code Object}
+ * avoids circular package dependencies. Callers access them through generic
+ * getters that perform an unchecked cast — the analysis pipeline guarantees the
+ * stored object matches the expected type at each call site. Semantic data is populated lazily during analysis and may be {@code null}
+ * when in "dumb mode" (i.e., only the CST has been built, no analysis pass
+ * has run yet). Not thread-safe. The owning {@link DocumentSyntax} must coordinate access. Package-private: only {@link DocumentSyntax#wrap(SyntaxNode)} should
+ * create instances, ensuring identity caching is respected.
+ *
+ *
+ * @return merged, non-overlapping mark list (safe to iterate without synchronization)
+ */
+ public List merge() {
+ List syntax;
+ List semantic;
+ synchronized (this) {
+ syntax = new ArrayList<>(syntaxMarks);
+ semantic = new ArrayList<>(semanticMarks);
+ }
+
+ if (syntax.isEmpty() && semantic.isEmpty()) {
+ return Collections.emptyList();
+ }
+
+ // Build identity set for O(1) semantic membership checks
+ Set semanticSet = Collections.newSetFromMap(new IdentityHashMap<>());
+ semanticSet.addAll(semantic);
+
+ // Collect all boundary points
+ List
+ *
+ *
+ *
+ *
+ *
+ * @param sourceText the complete document text
+ * @param mergedMarks merged marks from {@link MarkLayer#merge()}, sorted by start
+ * @param lineHeight pixel height per line
+ */
+ public void rebuild(String sourceText, List mergedMarks, int lineHeight) {
+ this.lineHeight = lineHeight;
+
+ ListLazy derived indexes
+ * Version tracking
+ * Thread safety
+ *
+ *
+ *
+ * @param simpleName the unqualified name to resolve (e.g. {@code "List"})
+ * @return the matching entry, or {@code null} if not found
+ */
+ public synchronized ImportEntry resolveBySimpleName(String simpleName) {
+ if (simpleName == null || simpleName.isEmpty()) {
+ return null;
+ }
+ ensureIndexes();
+ ImportEntry exact = bySimpleName.get(simpleName);
+ if (exact != null) {
+ return exact;
+ }
+ // Fall back to wildcard entries — return the first wildcard that could
+ // potentially provide the type (caller must verify via TypeResolver).
+ for (int i = 0, size = entries.size(); i < size; i++) {
+ ImportEntry entry = entries.get(i);
+ if (entry.isWildcard) {
+ return entry;
+ }
+ }
+ return null;
+ }
+
+ /**
+ * Resolves an import by its fully qualified path.
+ *
+ * @param fullPath the fully qualified path (e.g. {@code "java.util.List"})
+ * @return the matching entry, or {@code null} if not found
+ */
+ public synchronized ImportEntry resolveByFullPath(String fullPath) {
+ if (fullPath == null || fullPath.isEmpty()) {
+ return null;
+ }
+ ensureIndexes();
+ return byFullPath.get(fullPath);
+ }
+
+ /**
+ * Quick check whether a simple name is covered by any import
+ * (explicit, wildcard, or implicit).
+ *
+ * @param simpleName the unqualified name to check
+ * @return {@code true} if any import covers this name
+ */
+ public synchronized boolean isImported(String simpleName) {
+ return resolveBySimpleName(simpleName) != null;
+ }
+
+ /**
+ * Checks whether a fully qualified name is covered by an implicit import.
+ *
+ *
+ *
+ *
+ * Type safety
+ * Version-aware invalidation
+ * Thread safety
+ *
+ * FileScope (program)
+ * ├── ClassScope (class_body)
+ * │ ├── MethodScope (method_declaration)
+ * │ │ ├── BlockScope (block / for / if / try)
+ * │ │ └── LambdaScope (lambda_expression)
+ * │ └── FieldDecl (field_declaration)
+ * └── ImportDecl (import_declaration)
+ *
+ *
+ * Resolution algorithm (PsiScopeProcessor)
+ *
+ *
+ *
+ * Thread safety
+ *
+ *
+ *
+ * @param name the variable name to resolve
+ * @param byteOffset the byte offset of the reference site
+ * @return the resolved field symbol, or {@code null} if not found
+ */
+ public FieldSymbol resolveVariable(String name, int byteOffset) {
+ if (name == null || root == null) {
+ return null;
+ }
+
+ Scope scope = scopeAt(byteOffset);
+ if (scope == null) {
+ return null;
+ }
+
+ while (scope != null) {
+ FieldSymbol local = scope.locals().get(name);
+ if (local != null) {
+ // Variable must be declared before the reference site.
+ if (local.range().getStartByte() < byteOffset) {
+ return local;
+ }
+ // In class scope, fields are visible regardless of declaration order.
+ if (scope.kind() == ScopeKind.CLASS) {
+ return local;
+ }
+ }
+ scope = scope.parent();
+ }
+ return null;
+ }
+
+ /**
+ * Finds the deepest (most specific) scope containing the given byte offset.
+ *
+ *
+ *
+ */
+ private static void extractLocals(SemanticNode node, Scope scope) {
+ String type = node.nodeType();
+ if (type == null) {
+ return;
+ }
+
+ switch (type) {
+ case NODE_METHOD_DECLARATION:
+ case NODE_CONSTRUCTOR_DECLARATION:
+ extractFormalParameters(node, scope);
+ break;
+
+ case NODE_ENHANCED_FOR_STATEMENT:
+ extractEnhancedForVariable(node, scope);
+ break;
+
+ case NODE_CATCH_CLAUSE:
+ extractCatchParameter(node, scope);
+ break;
+
+ case NODE_LAMBDA_EXPRESSION:
+ extractLambdaParameters(node, scope);
+ break;
+
+ default:
+ break;
+ }
+ }
+
+ /**
+ * Extracts formal parameters from a method or constructor declaration.
+ */
+ private static void extractFormalParameters(SemanticNode methodNode, Scope scope) {
+ SemanticNode params = methodNode.childByFieldName(FIELD_PARAMETERS);
+ if (params == null) {
+ return;
+ }
+ List
+ * SemanticModel
+ * ├── SymbolTable — all declared symbols + indexed views
+ * ├── ScopeTree — scope hierarchy + variable resolution
+ * ├── ImportIndex — import resolution
+ * └── InferenceCache — lambda/object literal caches
+ *
+ *
+ * Lifecycle
+ *
+ *
+ *
+ * Thread safety
+ *
+ *
+ *
+ * @param syntax the document syntax produced by the parser
+ * @throws IllegalArgumentException if {@code syntax} is {@code null}
+ */
+ public void rebuild(DocumentSyntax syntax) {
+ if (syntax == null) {
+ throw new IllegalArgumentException("syntax must not be null");
+ }
+
+ clear();
+
+ inferenceCache.setSourceVersion(syntax.getSourceVersion());
+
+ SemanticNode root = syntax.root();
+ if (root == null) {
+ built = true;
+ compositeVersion++;
+ return;
+ }
+
+ extractImports(root);
+ extractDeclarations(root, "", "");
+
+ scopeTree = ScopeTree.buildFromCST(syntax);
+
+ built = true;
+ compositeVersion++;
+ }
+
+ /**
+ * Performs an incremental update based on the invalidation scope.
+ *
+ *
+ *
+ *
+ * @param syntax the updated document syntax after reparse
+ * @param scope the invalidation scope from {@link IncrementalStrategy}
+ * @throws IllegalArgumentException if either argument is {@code null}
+ */
+ public void incrementalUpdate(DocumentSyntax syntax, InvalidationScope scope) {
+ if (syntax == null) {
+ throw new IllegalArgumentException("syntax must not be null");
+ }
+ if (scope == null) {
+ throw new IllegalArgumentException("scope must not be null");
+ }
+
+ inferenceCache.setSourceVersion(syntax.getSourceVersion());
+
+ switch (scope) {
+ case NONE:
+ break;
+
+ case LOCAL_SCOPE:
+ scopeTree = ScopeTree.buildFromCST(syntax);
+ compositeVersion++;
+ break;
+
+ case DECLARATION:
+ rebuild(syntax);
+ break;
+
+ case IMPORTS:
+ rebuildImports(syntax);
+ compositeVersion++;
+ break;
+
+ case STRUCTURAL:
+ rebuild(syntax);
+ break;
+
+ default:
+ rebuild(syntax);
+ break;
+ }
+ }
+
+ // ── Convenience queries ────────────────────────────────────────────────────
+
+ /**
+ * Resolves a variable name at the given byte offset via scope walking.
+ *
+ * Architecture
+ * Thread safety
+ * Version tracking
+ *
+ *
+ *
+ * Thread safety
+ * Design (IntelliJ IDEA analogy)
+ *
+ *
+ *
+ *
+ * IntelliJ This project
+ * {@code ASTNode} {@link SyntaxNode} (raw CST)
+ * {@code PsiElement} {@code SemanticNode} (semantic view)
+ * {@code PsiFile} {@link DocumentSyntax} (root container) Semantic slots
+ * Thread safety
+ *