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.

* *

Lazy derived indexes

*

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.

* *

Version tracking

*

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.

* *

Thread safety

*

All mutation methods are {@code synchronized}. All query methods return * defensive copies or unmodifiable snapshots, so callers never observe * partially-mutated state.

* * @since Phase 2 — CST editor architecture */ public final class ImportIndex { // ── Primary store ────────────────────────────────────────────────── /** The authoritative list of all import entries (explicit + implicit). */ private final List entries; // ── Derived indexes (lazily rebuilt) ──────────────────────────────── /** Quick lookup by unqualified simple name (e.g. "List" → entry). */ private Map bySimpleName; /** Quick lookup by fully qualified path (e.g. "java.util.List" → entry). */ private Map byFullPath; /** Whether the derived indexes need rebuilding. */ private boolean dirty; /** Monotonically increasing version counter, bumped on every mutation. */ private int version; // ── Construction ─────────────────────────────────────────────────── /** * Creates a new, empty {@code ImportIndex}. */ public ImportIndex() { this.entries = new ArrayList(); this.bySimpleName = Collections.emptyMap(); this.byFullPath = Collections.emptyMap(); this.dirty = false; this.version = 0; } // ── Inner class ──────────────────────────────────────────────────── /** * An individual import declaration (explicit or implicit). * *

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.

*/ public static final class ImportEntry { private final String fullPath; private final String simpleName; private final boolean isWildcard; private final boolean isStatic; private final boolean isImplicit; private final TextSpan range; private final String packagePath; /** * Creates a new {@code ImportEntry}. * * @param fullPath the fully qualified import path, e.g. {@code "java.util.List"} * or {@code "java.util.*"} * @param simpleName the unqualified name, e.g. {@code "List"} or {@code "*"} * @param isWildcard {@code true} for wildcard imports ({@code import pkg.*}) * @param isStatic {@code true} for static imports ({@code import static ...}) * @param isImplicit {@code true} for auto-injected imports (e.g. {@code java.lang.*}) * @param range source location of the import statement; may be {@code null} * for implicit imports * @param packagePath the package portion, e.g. {@code "java.util"} */ public ImportEntry(String fullPath, String simpleName, boolean isWildcard, boolean isStatic, boolean isImplicit, TextSpan range, String packagePath) { if (fullPath == null) { throw new IllegalArgumentException("fullPath must not be null"); } if (simpleName == null) { throw new IllegalArgumentException("simpleName must not be null"); } if (packagePath == null) { throw new IllegalArgumentException("packagePath must not be null"); } this.fullPath = fullPath; this.simpleName = simpleName; this.isWildcard = isWildcard; this.isStatic = isStatic; this.isImplicit = isImplicit; this.range = range; this.packagePath = packagePath; } /** * Factory for creating an {@code ImportEntry} from a fully qualified path string. * *

Automatically derives {@code simpleName}, {@code isWildcard}, and * {@code packagePath} from the path.

* * @param fullPath the fully qualified import path * @param isStatic whether this is a static import * @param isImplicit whether this is an implicit (auto-injected) import * @param range source location, or {@code null} for implicit imports * @return a new {@code ImportEntry} */ public static ImportEntry fromFullPath(String fullPath, boolean isStatic, boolean isImplicit, TextSpan range) { boolean isWildcard = fullPath.endsWith(".*"); String simpleName; String packagePath; int lastDot = fullPath.lastIndexOf('.'); if (lastDot >= 0) { simpleName = fullPath.substring(lastDot + 1); packagePath = fullPath.substring(0, lastDot); } else { simpleName = fullPath; packagePath = ""; } return new ImportEntry(fullPath, simpleName, isWildcard, isStatic, isImplicit, range, packagePath); } /** @return the fully qualified import path (e.g. {@code "java.util.List"}) */ public String getFullPath() { return fullPath; } /** @return the unqualified name (e.g. {@code "List"} or {@code "*"}) */ public String getSimpleName() { return simpleName; } /** @return {@code true} for wildcard imports ({@code import pkg.*}) */ public boolean isWildcard() { return isWildcard; } /** @return {@code true} for static imports */ public boolean isStatic() { return isStatic; } /** @return {@code true} for auto-injected imports */ public boolean isImplicit() { return isImplicit; } /** * @return the source location of the import statement, or {@code null} * for implicit imports */ public TextSpan getRange() { return range; } /** @return the package portion (e.g. {@code "java.util"}) */ public String getPackagePath() { return packagePath; } @Override public boolean equals(Object obj) { if (this == obj) return true; if (!(obj instanceof ImportEntry)) return false; ImportEntry that = (ImportEntry) obj; return this.isImplicit == that.isImplicit && this.fullPath.equals(that.fullPath); } @Override public int hashCode() { int result = fullPath.hashCode(); result = 31 * result + (isImplicit ? 1 : 0); return result; } @Override public String toString() { StringBuilder sb = new StringBuilder(); if (isImplicit) sb.append("[implicit] "); if (isStatic) sb.append("static "); sb.append("import ").append(fullPath); if (range != null) { sb.append(" at ").append(range); } return sb.toString(); } } // ── Building (mutators) ──────────────────────────────────────────── /** * Removes all import entries and resets the version counter. */ public synchronized void clear() { entries.clear(); markDirty(); } /** * Adds a single import entry. * * @param entry the entry to add; must not be {@code null} * @throws IllegalArgumentException if {@code entry} is {@code null} */ public synchronized void addImport(ImportEntry entry) { if (entry == null) { throw new IllegalArgumentException("entry must not be null"); } entries.add(entry); markDirty(); } /** * Adds an implicit (auto-injected) import from a fully qualified path. * *

The entry is created with {@code isImplicit=true}, {@code isStatic=false}, * and {@code range=null}.

* * @param fullPath the fully qualified path (e.g. {@code "java.lang.*"}) */ public synchronized void addImplicitImport(String fullPath) { ImportEntry entry = ImportEntry.fromFullPath(fullPath, false, true, null); entries.add(entry); markDirty(); } /** * Atomically replaces all entries with the given list. * *

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.

* * @param newEntries the replacement entries; the list is defensively copied */ public synchronized void replaceAll(List newEntries) { entries.clear(); if (newEntries != null) { entries.addAll(newEntries); } markDirty(); } // ── Resolution (queries) ─────────────────────────────────────────── /** * Resolves an import by its unqualified simple name. * *

Resolution order:

*
    *
  1. Exact match in explicit (non-wildcard) imports by simple name.
  2. *
  3. If no exact match, returns the first wildcard import entry whose * package could contain the type. (Full resolution would require a * {@code TypeResolver} callback — for now the wildcard entry itself * is returned so callers can perform the lookup.)
  4. *
* * @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. * *

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"}).

* * @param fqn the fully qualified name to check * @return {@code true} if an implicit import covers this FQN */ public synchronized boolean isImplicitlyImported(String fqn) { if (fqn == null || fqn.isEmpty()) { return false; } for (int i = 0, size = entries.size(); i < size; i++) { ImportEntry entry = entries.get(i); if (!entry.isImplicit) { continue; } if (entry.fullPath.equals(fqn)) { return true; } // Check wildcard coverage: "java.lang.*" covers "java.lang.String" if (entry.isWildcard) { String pkg = entry.packagePath; if (fqn.startsWith(pkg + ".") && fqn.indexOf('.', pkg.length() + 1) < 0) { return true; } } } return false; } // ── Wildcard package queries ─────────────────────────────────────── /** * Returns all wildcard package paths (e.g. {@code "java.util"} from * {@code import java.util.*}). * * @return an unmodifiable set of package paths; never {@code null} */ public synchronized Set getWildcardPackages() { Set result = new HashSet(); for (int i = 0, size = entries.size(); i < size; i++) { ImportEntry entry = entries.get(i); if (entry.isWildcard) { result.add(entry.packagePath); } } return Collections.unmodifiableSet(result); } // ── Iteration ────────────────────────────────────────────────────── /** * Returns a snapshot of all import entries (both explicit and implicit). * * @return an unmodifiable list of all entries; never {@code null} */ public synchronized List getAllImports() { return Collections.unmodifiableList(new ArrayList(entries)); } /** * Returns a snapshot of only the implicit (auto-injected) imports. * * @return an unmodifiable list; never {@code null} */ public synchronized List getImplicitImports() { List result = new ArrayList(); for (int i = 0, size = entries.size(); i < size; i++) { ImportEntry entry = entries.get(i); if (entry.isImplicit) { result.add(entry); } } return Collections.unmodifiableList(result); } /** * Returns a snapshot of only the explicit (non-implicit) imports. * * @return an unmodifiable list; never {@code null} */ public synchronized List getExplicitImports() { List result = new ArrayList(); for (int i = 0, size = entries.size(); i < size; i++) { ImportEntry entry = entries.get(i); if (!entry.isImplicit) { result.add(entry); } } return Collections.unmodifiableList(result); } // ── Pruning ──────────────────────────────────────────────────────── /** * Removes implicit imports whose simple name is not in the given set * of used names. * *

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.

* * @param usedSimpleNames the set of simple names actually referenced * in the source; must not be {@code null} */ public synchronized void removeUnusedImplicitImports(Set usedSimpleNames) { if (usedSimpleNames == null) { throw new IllegalArgumentException("usedSimpleNames must not be null"); } boolean changed = false; Iterator it = entries.iterator(); while (it.hasNext()) { ImportEntry entry = it.next(); if (entry.isImplicit && !entry.isWildcard && !usedSimpleNames.contains(entry.simpleName)) { it.remove(); changed = true; } } if (changed) { markDirty(); } } // ── Utilities ────────────────────────────────────────────────────── /** * Returns the total number of import entries (explicit + implicit). * * @return the entry count */ public synchronized int size() { return entries.size(); } /** * Returns {@code true} if there are no import entries. * * @return {@code true} when empty */ public synchronized boolean isEmpty() { return entries.isEmpty(); } /** * Returns the current version counter. * *

The version is bumped on every mutation. External code can snapshot * this value and later compare to detect whether the index has changed.

* * @return the current version (starts at 0, increments monotonically) */ public synchronized int version() { return version; } // ── Internals ────────────────────────────────────────────────────── /** * Marks the derived indexes as stale and increments the version counter. * Must be called under the instance lock. */ private void markDirty() { dirty = true; version++; } /** * Rebuilds the derived indexes if they are stale. Must be called under * the instance lock. */ private void ensureIndexes() { if (!dirty) { return; } Map newBySimpleName = new HashMap(); Map newByFullPath = new HashMap(); for (int i = 0, size = entries.size(); i < size; i++) { ImportEntry entry = entries.get(i); newByFullPath.put(entry.fullPath, entry); // Only index non-wildcard entries by simple name; wildcard entries // are handled by the fallback scan in resolveBySimpleName(). if (!entry.isWildcard) { // Later entries with the same simple name win (last-import-wins // semantics, matching javac behavior for duplicate imports). newBySimpleName.put(entry.simpleName, entry); } } this.bySimpleName = newBySimpleName; this.byFullPath = newByFullPath; this.dirty = false; } @Override public String toString() { return "ImportIndex{size=" + entries.size() + ", version=" + version + "}"; } }