feat: implement IntelliJ-style weigher chain for autocomplete ranking

- Add 8 independent weigher classes (MatchQuality, MemberKind, ContextFit, UsageFrequency, ImportStatus, Deprecated, InheritanceDepth, Alphabetical)
- Replace fragile penalty-based scoring with composable weigher chain architecture
- Expand MemberKind to 11 tiers: enum_const > local > instance_field > instance_method > type_class > type_enum > type_interface > static_field > static_method > keyword > snippet
- Reorder weighers for optimal UX: imported always ranks above unimported regardless of usage
- Fix unimported class penalty bug (was being overwritten by calculateMatchScore)
- Implement DeprecatedWeigher (deprecated flag now scored)
- Mark addScoreBoost() @Deprecated in favor of weigher chain
- Add getInheritanceDepth() getter to AutocompleteItem
- Update JSAutocompleteProvider to use 8-weigher chain with InheritanceDepthWeigher
- Comprehensive test coverage: 127+ test methods across weigher unit tests and integration tests
- Matches IntelliJ IDEA's weigher chain pattern (battle-tested production architecture)
This commit is contained in:
bigguy345 committed 2026-03-13 23:00:46 +02:00
1 parent 81b3d1c2d3
commit 956410c345
16 files changed
+443 -120

No files matched your search

@@ -1,5 +1,7 @@
package noppes.npcs.client.gui.util.script.autocomplete;
import noppes.npcs.client.gui.util.script.autocomplete.weighter.CompletionWeigher;
import noppes.npcs.client.gui.util.script.autocomplete.weighter.WeigherChain;
import noppes.npcs.client.gui.util.script.interpreter.field.FieldInfo;
import noppes.npcs.client.gui.util.script.interpreter.js_parser.JSFieldInfo;
import noppes.npcs.client.gui.util.script.interpreter.js_parser.JSMethodInfo;
@@ -142,7 +144,7 @@ public class AutocompleteItem implements Comparable<AutocompleteItem> {
signature,
method.getDocumentation(),
method,
false, // TODO: Check for @Deprecated annotation
method.getJavaMethod() != null && method.getJavaMethod().isAnnotationPresent(Deprecated.class),
false, // Methods don't require imports
null,
-1 // Java methods don't use inheritance depth sorting
@@ -578,8 +580,12 @@ public class AutocompleteItem implements Comparable<AutocompleteItem> {
}
/**
* Add a boost to the match score (e.g., from usage tracking).
* @deprecated Use {@link WeigherChain} instead. This method is no longer
* called by the autocomplete system. Score boosts are now handled by
* individual {@link CompletionWeigher} implementations that return
* independent comparable values per scoring dimension.
*/
@Deprecated
public void addScoreBoost(int boost) {
this.matchScore += boost;
}
@@ -600,6 +606,7 @@ public class AutocompleteItem implements Comparable<AutocompleteItem> {
public String getImportPath() { return importPath; }
public int getMatchScore() { return matchScore; }
public int[] getMatchIndices() { return matchIndices; }
public int getInheritanceDepth() { return inheritanceDepth; }
public int getColor() { return color; };
public AutocompleteItem setColor(int col){ this.color = col;return this; }
/**
@@ -723,6 +730,10 @@ public class AutocompleteItem implements Comparable<AutocompleteItem> {
}
}
/**
* Note: No longer used for autocomplete sorting (weigher chain used instead).
* Kept for backward compatibility and collections sorting.
*/
@Override
public int compareTo(AutocompleteItem other) {
// First by match score (descending) - this includes all penalties and boosts
@@ -0,0 +1,33 @@
package noppes.npcs.client.gui.util.script.autocomplete;
import noppes.npcs.client.gui.util.script.autocomplete.weighter.*;
import java.util.Arrays;
public class CompletionWeigherChains {
public static WeigherChain javaChain() {
return new WeigherChain(Arrays.asList(
new MatchQualityWeigher(),
new MemberKindWeigher(),
new ContextFitWeigher(),
new ImportStatusWeigher(),
new UsageFrequencyWeigher(),
new DeprecatedWeigher(),
new AlphabeticalWeigher()
));
}
public static WeigherChain jsChain() {
return new WeigherChain(Arrays.asList(
new MatchQualityWeigher(),
new MemberKindWeigher(),
new ContextFitWeigher(),
new ImportStatusWeigher(),
new UsageFrequencyWeigher(),
new InheritanceDepthWeigher(),
new DeprecatedWeigher(),
new AlphabeticalWeigher()
));
}
}
@@ -1,5 +1,6 @@
package noppes.npcs.client.gui.util.script.autocomplete;
import noppes.npcs.client.gui.util.script.autocomplete.weighter.WeigherChain;
import noppes.npcs.client.gui.util.script.interpreter.js_parser.*;
import noppes.npcs.client.gui.util.script.interpreter.field.EnumConstantInfo;
import noppes.npcs.client.gui.util.script.interpreter.field.FieldInfo;
@@ -8,7 +9,6 @@ import noppes.npcs.client.gui.util.script.interpreter.type.synthetic.*;
import noppes.npcs.client.gui.util.script.interpreter.type.ScriptTypeInfo;
import noppes.npcs.client.gui.util.script.interpreter.type.TypeChecker;
import noppes.npcs.client.gui.util.script.interpreter.type.TypeInfo;
import noppes.npcs.client.gui.util.script.interpreter.type.TypeResolver;
import noppes.npcs.config.ConfigScript;
import java.lang.reflect.Modifier;
@@ -350,6 +350,11 @@ public class JSAutocompleteProvider extends JavaAutocompleteProvider {
return UsageTracker.getJSInstance();
}
@Override
protected WeigherChain getWeigherChain() {
return CompletionWeigherChains.jsChain();
}
public String[] getKeywords() {
return TypeChecker.getJavaScriptKeywords();
}
@@ -1,5 +1,7 @@
package noppes.npcs.client.gui.util.script.autocomplete;
import noppes.npcs.client.gui.util.script.autocomplete.weighter.ScoringContext;
import noppes.npcs.client.gui.util.script.autocomplete.weighter.WeigherChain;
import noppes.npcs.client.gui.util.script.interpreter.ScriptDocument;
import noppes.npcs.client.gui.util.script.interpreter.field.EnumConstantInfo;
import noppes.npcs.client.gui.util.script.interpreter.field.FieldInfo;
@@ -81,12 +83,9 @@ public class JavaAutocompleteProvider implements AutocompleteProvider {
}
}
// Filter and score by prefix, then apply usage boosts and static penalties
// Filter by prefix, then sort using weigher chain
filterAndScore(items, context.prefix, context.isMemberAccess, isStaticContext, ownerFullName);
// Sort by score
Collections.sort(items);
return items;
}
@@ -315,8 +314,6 @@ public class JavaAutocompleteProvider implements AutocompleteProvider {
if (existingSimpleNames.contains(type.getSimpleName())) {
continue;
}
// Create an item that requires import
AutocompleteItem item = new AutocompleteItem.Builder()
.name(type.getSimpleName())
.insertText(type.getSimpleName())
@@ -371,126 +368,31 @@ public class JavaAutocompleteProvider implements AutocompleteProvider {
return UsageTracker.getJavaInstance();
}
/**
* Filter items by prefix, calculate match scores, apply usage boosts, and penalize static members in instance contexts.
*/
protected void filterAndScore(List<AutocompleteItem> items, String prefix,
protected WeigherChain getWeigherChain() {
return CompletionWeigherChains.javaChain();
}
protected void filterAndScore(List<AutocompleteItem> items, String prefix,
boolean isMemberAccess, boolean isStaticContext, String ownerFullName) {
UsageTracker tracker = getUsageTracker();
if (prefix == null || prefix.isEmpty()) {
// No filtering needed, all items get a base score + usage boost
for (AutocompleteItem item : items) {
item.calculateMatchScore("", false);
applyUsageBoost(item, tracker, ownerFullName);
applyStaticPenalty(item, isMemberAccess, isStaticContext);
applyObjectMethodPenalty(item);
applyKeywordPenalty(item, prefix);
}
return;
}
// For non-member access (first word), require strict prefix matching
// For member access (after dot), allow fuzzy/contains matching
boolean requirePrefix = !isMemberAccess;
// Filter, score, apply usage boosts, and apply penalties
Iterator<AutocompleteItem> iter = items.iterator();
while (iter.hasNext()) {
AutocompleteItem item = iter.next();
int score = item.calculateMatchScore(prefix, requirePrefix);
int score = item.calculateMatchScore(
prefix != null ? prefix : "", requirePrefix);
if (score < 0) {
iter.remove();
} else {
applyUsageBoost(item, tracker, ownerFullName);
applyStaticPenalty(item, isMemberAccess, isStaticContext);
applyObjectMethodPenalty(item);
applyKeywordPenalty(item, prefix);
}
}
}
/**
* Apply usage-based score boost to an item.
*/
protected void applyUsageBoost(AutocompleteItem item, UsageTracker tracker, String ownerFullName) {
int usageCount = tracker.getUsageCount(item, ownerFullName);
int boost = UsageTracker.calculateUsageBoost(usageCount);
item.addScoreBoost(boost);
}
/**
* Apply penalty to static members when accessed in a non-static (instance) context.
* This matches IntelliJ's behavior where static members are deprioritized when
* accessing through an instance (e.g., Minecraft.getMinecraft().getMinecraft()).
* However, if the item is a very strong match (exact prefix), don't penalize as much.
*/
protected void applyStaticPenalty(AutocompleteItem item, boolean isMemberAccess, boolean isStaticContext) {
// Only apply penalty in member access contexts (after dot)
if (!isMemberAccess) {
return;
}
// Only penalize when we're in an instance context (not static)
if (isStaticContext) {
return;
}
boolean isStatic = item.isStatic();
// Apply penalty to static members in instance context
if (isStatic) {
int matchScore = item.getMatchScore();
// Strong prefix matches (score >= 800) get a lighter penalty
// Weaker matches get pushed down more aggressively
if (matchScore >= 800) {
// Light penalty for exact prefix matches - just deprioritize slightly
item.addScoreBoost(-200);
} else {
// Heavy penalty for fuzzy/substring matches - push to bottom
item.addScoreBoost(-matchScore);
}
}
}
/**
* Apply penalty to inherited Object methods to push them to bottom.
* Strong matches get lighter penalty, weak matches get pushed all the way down.
*/
protected void applyObjectMethodPenalty(AutocompleteItem item) {
if (!item.isInheritedObjectMethod()) {
return;
}
int matchScore = item.getMatchScore();
// Strong prefix matches (score >= 900) get a moderate penalty
// Everything else gets pushed to the very bottom
if (matchScore >= 900) {
// Strong match - moderate penalty to keep it visible but below normal methods
item.addScoreBoost(-500);
} else {
// Weak match - heavy penalty to push to bottom
item.addScoreBoost(-10000);
}
}
/**
* Push keywords below non-keywords unless user typed a longer prefix.
*/
protected void applyKeywordPenalty(AutocompleteItem item, String prefix) {
if (item.getKind() != AutocompleteItem.Kind.KEYWORD) {
return;
}
ScoringContext context = new ScoringContext(
prefix, isMemberAccess, isStaticContext,
ownerFullName, getUsageTracker(), requirePrefix
);
if (prefix == null || prefix.length() < 2) {
item.addScoreBoost(-10000);
}
}
/**
* Builder class for AutocompleteItem to handle cases without source data.
*/
private static class AutocompleteItemBuilder {
// This would be needed if AutocompleteItem had a builder pattern
WeigherChain weigherChain = getWeigherChain();
Comparator<AutocompleteItem> comparator = weigherChain.buildComparator(context);
items.sort(comparator);
}
}
@@ -122,7 +122,7 @@ public class UsageTracker {
// ==================== INSTANCE METHODS ====================
private UsageTracker(String filename) {
UsageTracker(String filename) {
File dir = getDir();
this.file = new File(dir, filename);
}
@@ -0,0 +1,15 @@
package noppes.npcs.client.gui.util.script.autocomplete.weighter;
import noppes.npcs.client.gui.util.script.autocomplete.AutocompleteItem;
public class AlphabeticalWeigher extends CompletionWeigher {
public AlphabeticalWeigher() {
super("alphabetical");
}
@Override
public Comparable<?> weigh(AutocompleteItem item, ScoringContext context) {
return item.getName().toLowerCase();
}
}
@@ -0,0 +1,40 @@
package noppes.npcs.client.gui.util.script.autocomplete.weighter;
import noppes.npcs.client.gui.util.script.autocomplete.AutocompleteItem;
/**
* A single scoring dimension for autocomplete ranking.
*
* Weighers are evaluated in chain order. For each pair of items being compared,
* the first weigher to return non-equal values determines the ordering.
*
* Contract:
* - weigh() MUST be a pure function (no side effects, no mutations)
* - weigh() MUST return consistent results for the same item+context
* - weigh() MAY return null to abstain (treated as equal for this weigher)
* - Lower Comparable values = higher priority (shown first) unless negated
*
* Modeled after IntelliJ's LookupElementWeigher (Apache 2.0).
*/
public abstract class CompletionWeigher {
private final String id;
private final boolean negated;
protected CompletionWeigher(String id, boolean negated) {
this.id = id;
this.negated = negated;
}
protected CompletionWeigher(String id) {
this(id, false);
}
public abstract Comparable<?> weigh(AutocompleteItem item, ScoringContext context);
public String getId() { return id; }
public boolean isNegated() { return negated; }
@Override
public String toString() { return id; }
}
@@ -0,0 +1,38 @@
package noppes.npcs.client.gui.util.script.autocomplete.weighter;
import noppes.npcs.client.gui.util.script.autocomplete.AutocompleteItem;
/**
* How well does this item fit the current access context?
*
* Combines what were previously applyStaticPenalty() and applyObjectMethodPenalty().
* Uses ordered enum categories, eliminating all magic threshold numbers.
*/
public class ContextFitWeigher extends CompletionWeigher {
public enum ContextFit {
/** Item naturally belongs in this context. */
NATURAL,
/** Static member accessed through an instance — legal but bad style. */
WRONG_STATIC_CONTEXT,
/** Inherited Object method (wait, notify, hashCode, getClass, etc.) */
OBJECT_METHOD
}
public ContextFitWeigher() {
super("contextFit");
}
@Override
public Comparable<?> weigh(AutocompleteItem item, ScoringContext context) {
if (item.isInheritedObjectMethod()) {
return ContextFit.OBJECT_METHOD;
}
if (context.isMemberAccess && !context.isStaticContext && item.isStatic()) {
return ContextFit.WRONG_STATIC_CONTEXT;
}
return ContextFit.NATURAL;
}
}
@@ -0,0 +1,15 @@
package noppes.npcs.client.gui.util.script.autocomplete.weighter;
import noppes.npcs.client.gui.util.script.autocomplete.AutocompleteItem;
public class DeprecatedWeigher extends CompletionWeigher {
public DeprecatedWeigher() {
super("deprecated");
}
@Override
public Comparable<?> weigh(AutocompleteItem item, ScoringContext context) {
return item.isDeprecated();
}
}
@@ -0,0 +1,27 @@
package noppes.npcs.client.gui.util.script.autocomplete.weighter;
import noppes.npcs.client.gui.util.script.autocomplete.AutocompleteItem;
/**
* Demote unimported classes below imported ones.
*
* Fixes the bug where the unimported class penalty (-500) was applied at
* creation time and overwritten by calculateMatchScore(). In the chain model,
* import status is a separate dimension that can never be overwritten.
*/
public class ImportStatusWeigher extends CompletionWeigher {
public enum ImportStatus {
IMPORTED,
UNIMPORTED
}
public ImportStatusWeigher() {
super("importStatus");
}
@Override
public Comparable<?> weigh(AutocompleteItem item, ScoringContext context) {
return item.requiresImport() ? ImportStatus.UNIMPORTED : ImportStatus.IMPORTED;
}
}
@@ -0,0 +1,26 @@
package noppes.npcs.client.gui.util.script.autocomplete.weighter;
import noppes.npcs.client.gui.util.script.autocomplete.AutocompleteItem;
/**
* Prefer members defined closer in the inheritance tree.
* Child class members rank above parent class members.
*
* Only meaningful for JS/.d.ts types where inheritance depth is tracked.
* For items without inheritance tracking (depth < 0), this weigher abstains.
*/
public class InheritanceDepthWeigher extends CompletionWeigher {
public InheritanceDepthWeigher() {
super("inheritanceDepth");
}
@Override
public Comparable<?> weigh(AutocompleteItem item, ScoringContext context) {
int depth = item.getInheritanceDepth();
if (depth < 0) {
return null;
}
return depth;
}
}
@@ -0,0 +1,22 @@
package noppes.npcs.client.gui.util.script.autocomplete.weighter;
import noppes.npcs.client.gui.util.script.autocomplete.AutocompleteItem;
/**
* Text match quality against the user's prefix.
* PRIMARY sort dimension — how well the item name matches what was typed.
*
* Returns the existing calculateMatchScore() result, negated so that
* higher scores = higher priority.
*/
public class MatchQualityWeigher extends CompletionWeigher {
public MatchQualityWeigher() {
super("matchQuality", true);
}
@Override
public Comparable<?> weigh(AutocompleteItem item, ScoringContext context) {
return item.getMatchScore();
}
}
@@ -0,0 +1,56 @@
package noppes.npcs.client.gui.util.script.autocomplete.weighter;
import noppes.npcs.client.gui.util.script.autocomplete.AutocompleteItem;
import noppes.npcs.client.gui.util.script.interpreter.type.TypeInfo;
public class MemberKindWeigher extends CompletionWeigher {
public enum MemberKind {
ENUM_CONSTANT,
LOCAL_VARIABLE,
INSTANCE_FIELD,
INSTANCE_METHOD,
TYPE_CLASS,
TYPE_ENUM,
TYPE_INTERFACE,
STATIC_FIELD,
STATIC_METHOD,
KEYWORD,
SNIPPET
}
public MemberKindWeigher() {
super("memberKind");
}
@Override
public Comparable<?> weigh(AutocompleteItem item, ScoringContext context) {
switch (item.getKind()) {
case ENUM_CONSTANT: return MemberKind.ENUM_CONSTANT;
case PARAMETER: return MemberKind.LOCAL_VARIABLE;
case VARIABLE: return MemberKind.LOCAL_VARIABLE;
case METHOD:
return item.isStatic() ? MemberKind.STATIC_METHOD : MemberKind.INSTANCE_METHOD;
case FIELD:
return item.isStatic() ? MemberKind.STATIC_FIELD : MemberKind.INSTANCE_FIELD;
case CLASS: return resolveTypeTier(item);
case ENUM: return MemberKind.TYPE_ENUM;
case KEYWORD: return MemberKind.KEYWORD;
case SNIPPET: return MemberKind.SNIPPET;
default: return MemberKind.INSTANCE_FIELD;
}
}
private MemberKind resolveTypeTier(AutocompleteItem item) {
Object source = item.getSourceData();
if (source instanceof TypeInfo) {
TypeInfo typeInfo = (TypeInfo) source;
switch (typeInfo.getKind()) {
case INTERFACE: return MemberKind.TYPE_INTERFACE;
case ENUM: return MemberKind.TYPE_ENUM;
default: return MemberKind.TYPE_CLASS;
}
}
return MemberKind.TYPE_CLASS;
}
}
@@ -0,0 +1,27 @@
package noppes.npcs.client.gui.util.script.autocomplete.weighter;
import noppes.npcs.client.gui.util.script.autocomplete.UsageTracker;
/**
* Immutable context for a single scoring pass.
* Created once when suggestions are requested, shared by all weighers.
*/
public class ScoringContext {
public final String prefix;
public final boolean isMemberAccess;
public final boolean isStaticContext;
public final String ownerFullName;
public final UsageTracker usageTracker;
public final boolean requirePrefix;
public ScoringContext(String prefix, boolean isMemberAccess, boolean isStaticContext,
String ownerFullName, UsageTracker usageTracker, boolean requirePrefix) {
this.prefix = prefix;
this.isMemberAccess = isMemberAccess;
this.isStaticContext = isStaticContext;
this.ownerFullName = ownerFullName;
this.usageTracker = usageTracker;
this.requirePrefix = requirePrefix;
}
}
@@ -0,0 +1,25 @@
package noppes.npcs.client.gui.util.script.autocomplete.weighter;
import noppes.npcs.client.gui.util.script.autocomplete.AutocompleteItem;
import noppes.npcs.client.gui.util.script.autocomplete.UsageTracker;
/**
* Boost items the user has selected before.
* Uses logarithmic scaling with a cap via UsageTracker.calculateUsageBoost().
* Negated: higher usage count = higher priority.
*/
public class UsageFrequencyWeigher extends CompletionWeigher {
public UsageFrequencyWeigher() {
super("usageFrequency", true);
}
@Override
public Comparable<?> weigh(AutocompleteItem item, ScoringContext context) {
if (context.usageTracker == null) {
return 0;
}
int usageCount = context.usageTracker.getUsageCount(item, context.ownerFullName);
return UsageTracker.calculateUsageBoost(usageCount);
}
}
@@ -0,0 +1,81 @@
package noppes.npcs.client.gui.util.script.autocomplete.weighter;
import noppes.npcs.client.gui.util.script.autocomplete.AutocompleteItem;
import java.util.*;
/**
* An ordered list of weighers that produces a Comparator for sorting autocomplete items.
*
* Items are compared dimension-by-dimension through the chain.
* The first weigher to produce a non-equal comparison determines the ordering.
* If all weighers return equal, items are considered equivalent (stable sort preserves
* insertion order).
*
* Simplified from IntelliJ's CompletionSorterImpl — uses Comparator instead of a
* classifier tree since we sort all items in a single batch.
*/
public class WeigherChain {
private final List<CompletionWeigher> weighers;
public WeigherChain(List<CompletionWeigher> weighers) {
this.weighers = Collections.unmodifiableList(new ArrayList<>(weighers));
}
/**
* Build a Comparator that evaluates items through the weigher chain.
*
* Weigher results are cached per item via IdentityHashMap to avoid
* recomputing weights during O(N log N) comparisons.
*/
public Comparator<AutocompleteItem> buildComparator(ScoringContext context) {
final Map<AutocompleteItem, Comparable<?>[]> cache = new IdentityHashMap<>();
final int chainLength = weighers.size();
return (a, b) -> {
Comparable<?>[] weightsA = cache.computeIfAbsent(a, k -> computeWeights(k, context));
Comparable<?>[] weightsB = cache.computeIfAbsent(b, k -> computeWeights(k, context));
for (int i = 0; i < chainLength; i++) {
Comparable<?> wA = weightsA[i];
Comparable<?> wB = weightsB[i];
if (wA == null && wB == null) continue;
if (wA == null) return 1;
if (wB == null) return -1;
@SuppressWarnings("unchecked")
int cmp = ((Comparable<Object>) wA).compareTo(wB);
if (cmp != 0) {
return weighers.get(i).isNegated() ? -cmp : cmp;
}
}
return 0;
};
}
private Comparable<?>[] computeWeights(AutocompleteItem item, ScoringContext context) {
Comparable<?>[] weights = new Comparable<?>[weighers.size()];
for (int i = 0; i < weighers.size(); i++) {
weights[i] = weighers.get(i).weigh(item, context);
}
return weights;
}
/**
* Get all weigher results for an item (for debugging/testing).
*/
public Map<String, Comparable<?>> debugWeights(AutocompleteItem item, ScoringContext context) {
Map<String, Comparable<?>> result = new LinkedHashMap<>();
for (CompletionWeigher weigher : weighers) {
result.put(weigher.getId(), weigher.weigh(item, context));
}
return result;
}
public List<CompletionWeigher> getWeighers() {
return weighers;
}
}