iris-context/docs/dev/spec.md

Command specification & lookup engine (spec/)

The spec module is the language parser of Iris. It understands the relationship between commands, subcommands, and flags.

Data structures

• Spec: Top-level command definition (e.g. git).
• Subcommand: Recursively defined children (e.g. commit under git).
• Generator: A function providing dynamic content (e.g. file paths, docker IDs).

The Lookup algorithm

The core path-traversal function:

1. Tokenization: Splits "git commit -m" into ["git", "commit", "-m"]. Empty tokens (from trailing space) indicate the user is ready for the next suggestion level.
2. Tree walking: Starts at the root node (git) and matches each token against available subcommands.
3. Context identification: When traversal stops (partial word or option prefix), it defines:
   • prefix: the path already traversed.
   • partial: the word currently being typed.
4. Result collection: Gathers all subcommands and options matching the partial prefix.

Example

Input: git com

1. Tokens: ["git", "com"].
2. Walk: root is git.
3. Next token com doesn't match commit exactly.
4. Stop. partial = "com".
5. Suggestions: subcommands of git starting with com.
6. Return: git commit.

Shell aliases & priority

• Dynamic alias parsing: Scans shell config files (.bashrc, .zshrc) for defined aliases.
• Highest priority: Aliases appear above spec and system command suggestions.
• Token injection: When a root command is an alias (e.g. gr for go run), Iris injects expanded tokens into the lookup engine for accurate subcommand suggestions.
• Display: Shows the expanded command (e.g. tmux a -t) with the alias name in the description (e.g. alias: ta).