Troubleshooting

Troubleshooting

This page lists the problems that most often look like parser, generator, or editor bugs.

.lexicon Nesting Looks Wrong

Cause: leading spaces.

Lexicon hierarchy uses tabs. Spaces in leading indentation are ignored for hierarchy.

Fix:

• Configure the editor to use hard tabs for .lexicon.
• Run the LSP and fix indentation diagnostics.
• Use lexicon tree to confirm the parsed hierarchy.

swift run lexicon tree commerce.lexicon commerce --depth 5 --metadata

Import Paths Do Not Resolve

Cause: imports are relative to the importing file or LSP config context, not to the shell's current directory.

Fix:

• Keep imports relative.
• Run validation from the repository root.
• Check the root lexicon path in lexicon-lsp.json.

swift run lexicon validate lexicons/commerce.lexicon

Generation Fails with Composition Conflicts

Cause: two imported branches declare incompatible concrete nodes or references no longer resolve after grafting.

Fix:

1. Run lexicon inspect on the conflicting path.
2. Move shared vocabulary into a shared import.
3. Replace duplicate local spellings with synonyms where they really mean the same thing.
4. Re-run generation.

swift run lexicon inspect commerce.lexicon commerce.ui.product.card

Generated File Is Empty or Missing

Cause: output path confusion.

-o is a path without the extension. This command:

swift run lexicon-generate commerce.lexicon --type rust -o src/lexicon

writes:

src/lexicon.rs

If two selected generators share an extension, one can overwrite the other. Generate those targets separately.

Go Package Name Fails

Cause: invalid Go package identifier.

Fix:

swift run lexicon-generate commerce.lexicon \
	--type go \
	--go-package commerce \
	-o internal/commerce/lexicon

Avoid keywords and punctuation in --go-package.

Rust Keyword Paths Are Awkward

Use the exact-path macro when lexical spelling matters:

let node = lexicon::l!(test.type.even.bad);

Use raw identifiers in the typed API:

let node = lexicon::l().test().r#type().even().bad();

LSP Does Not Start

Check:

• lexicon-lsp was built with swift build -c release --product lexicon-lsp.
• the editor path points to the executable, not the build directory.
• the binary is executable.
• lexicon-lsp.json exists under the workspace root.
• the editor log shows the server command being launched.

Direct smoke test:

.build/release/lexicon-lsp --help

LSP Starts but Has No Completions

Check:

• the opened file is under the configured scope
• the configured lexicon path exists
• imports compose successfully
• the cursor is inside a supported reference context

Supported contexts:

node:
	+ commerce.
alias:
	= commerce.
default:
	? @ commerce.

l("commerce.

l!(commerce.

Run:

swift run lexicon validate lexicons/commerce.lexicon
swift run lexicon tree lexicons/commerce.lexicon commerce --depth 3 --inherited

Semantic Search Is Slow the First Time

Cause: the embedding cache is being built.

Fix:

• Let the first run finish.
• Reuse the default cache.
• Pass --embedding-cache for CI or a shared local path.
• Pass --rebuild-embeddings only when the cache should be regenerated.

swift run --traits MLXSearch lexicon search commerce.lexicon "customer refund" \
	--mode semantic \
	--embedding-provider mlx \
	--embedding-cache .lexicon-cache

Search Results Feel Too Broad

Use a narrower mode:

swift run lexicon search commerce.lexicon checkout button --mode token --names-only

Or limit the root:

swift run lexicon search commerce.lexicon checkout --root commerce.ui --mode hybrid

README and Wiki Differ

The README should stay a short overview. The wiki is the source for step-by-step setup and language/editor pages. If a detailed instruction appears in the README, move it to the wiki and leave a link.