Claus Ibsen created CAMEL-24666:
-----------------------------------
Summary: camel-catalog: replace the Soundex suggestion strategy
with an edit-distance default in camel-core-catalog
Key: CAMEL-24666
URL: https://issues.apache.org/jira/browse/CAMEL-24666
Project: Camel
Issue Type: Improvement
Components: camel-catalog, camel-jbang
Reporter: Claus Ibsen
h3. Background
The catalog validation ({{CamelCatalog.validateEndpointProperties}}, and the
properties validation) reports unknown option names and can add "did you mean"
suggestions through a pluggable {{SuggestionStrategy}}. The only implementation
is {{CatalogSuggestionStrategy}} in the separate {{camel-catalog-suggest}}
module. It is a *phonetic* matcher: it computes the Soundex code (Apache
commons-codec, {{Soundex.US_ENGLISH_SIMPLIFIED}}) of the unknown name and of
every known option, takes the names whose codes agree on all four characters,
then on three, and finally a prefix match for names of at least four letters.
commons-codec is the module's only reason to exist beyond the catalog API.
h3. Problems
* Soundex is a 1918 surname-matching algorithm (first letter plus three digits
for consonant groups). It ignores vowels and case by design, so it rates
unrelated option names as equal when their consonants line up, and it cannot
see a transposed or missing letter the way edit distance does. Option names are
camelCase identifiers, not spoken names.
* The strategy is not installed anywhere it matters. Only
{{camel-report-maven-plugin}} and {{camel-kamelet-main}} depend on
{{camel-catalog-suggest}}; camel-jbang (CLI validators, the TUI's YAML
validator and its {{tui_catalog_doc}} endpoint check, the MCP server) load the
catalog without a strategy, so their users never get a suggestion for a
misspelled option.
* Because of that, camel-jbang-plugin-tui now carries its own small
edit-distance fallback ({{TuiToolRegistry.similarNames}}) to name the closest
options for a local AI model. One implementation in the catalog would serve all
consumers.
h3. Proposal
* Add an edit-distance based strategy (Damerau-Levenshtein, case-insensitive,
containment counts as close, threshold relative to the name length, at most 3-5
suggestions ranked by distance) to {{camel-core-catalog}} with no third-party
dependency, and make it the default {{SuggestionStrategy}} of
{{AbstractCamelCatalog}} so every catalog user gets suggestions without wiring.
* Deprecate and later drop {{camel-catalog-suggest}} together with its
commons-codec dependency (or keep it as an opt-in for those who want the
phonetic behaviour, though nothing in the code base would use it).
* Remove the fallback in camel-jbang-plugin-tui once the catalog provides
suggestions itself.
* Suggestions for unknown *component* names already exist
({{CamelCatalog.suggestComponentNames}}, {{CatalogTermMatcher}}); the
option-name suggestions should use the same kind of matching so the two behave
alike.
h3. Why now
AI assistants (the TUI's built-in AI with local models, and MCP clients) rely
on the validation messages to correct themselves; a message that names the
right option turns a retry into a fix. Edit distance is a few dozen lines and
trivially testable, which is far easier to implement and review today than when
the Soundex strategy was written.
_Claude Code on behalf of davsclaus_
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
