Kahua XML Links Extension

A powerful Visual Studio Code extension that provides intelligent navigation, completion, and cross-file symbol resolution for Kahua XML files. Navigate seamlessly between definitions and references across multiple files with support for imports, file references, qualified references, and recursive symbol loading.

Features

Go to Definition (F12) – Jump from a reference to its definition, even if defined in another file
Find All References (Shift+F12) – List all occurrences of a symbol across the current document
Autocomplete (Ctrl+Space) – Get intelligent suggestions for symbols from the current file and all referenced files
Peek Definition (Alt+F12) – Preview definitions inline without leaving your current location

🌐 Cross-File Symbol Resolution

File References – Navigate directly to other XML files by clicking on file reference attributes
Cross-File Symbol Imports – Automatically load definitions from files specified in import declarations (e.g., ImportCultures)
Cross-File Symbol References – Load definitions from files referenced by specific attributes (e.g., Properties.AppName, Extends)
Qualified References – Navigate to symbols in other files using dot notation (e.g., kahua_Core.MySymbol)
Value Lists – Support comma-separated symbol lists in attributes
Recursive Loading – Automatically follows import chains and file references
Cycle Detection – Prevents infinite loops when files have circular references

🔧 Advanced Pattern Matching

Wildcard Support – Use * to match any element or attribute name with prefix/suffix patterns
Multiple Value Extraction – Extract multiple bracketed values like [Key1] [Key2]
Value List Processing – Handle comma-separated symbol references
Conditional Definitions – Limit definitions to elements with specific descendants

Installation

From VSIX (Recommended)

Download the latest .vsix file
Open VS Code
Go to Extensions (Ctrl+Shift+X)
Click the ... menu → "Install from VSIX..."
Select the downloaded file

From Source

git clone <repository-url>
cd kahua-xml-links-extension
npm install
npm run compile

Quick Start

Install the extension – The default configuration is already set up
Configure search paths – Add this to your .vscode/settings.json:

{
  "kahuaXml.fileReferences": [
    {
      "id": "kahuaFile",
      "pattern": ["App", "Extends"],
      "searchPaths": [
        "${workspaceFolder}/xml",
        "C:/path/to/your/kahua/xml/files"
      ],
      "fileExtension": ".xml"
    }
  ]
}

Open a Kahua XML file – Navigation features work immediately!

Configuration

The extension uses a dual-configuration system that separates default patterns (maintained by the extension) from user customizations (your personal overrides and additions).

Configuration System Overview

Default Configuration: Built-in patterns for 25+ Kahua XML symbol types, automatically updated with new extension versions
User Customizations: Your personal overrides and custom patterns, preserved across updates
Automatic Merging: Both configurations are loaded and merged at runtime
Version Management: Default configuration includes version tracking for seamless updates

Using the Configuration System

Edit Your Customizations (Recommended)

Open Command Palette (Ctrl+Shift+P)
Run Kahua XML Links: Edit Configuration
This opens your personal kahua-links-custom.json file
Add custom patterns or override defaults using the same id
Save to apply changes automatically

View Default Configuration (Read-Only)

Open Command Palette (Ctrl+Shift+P)
Run Kahua XML Links: View Default Configuration
Browse the built-in patterns (read-only)
Copy patterns to customize in your personal config

Reset to Defaults

Open Command Palette (Ctrl+Shift+P)
Run Kahua XML Links: Reset Configuration to Defaults
Removes all customizations and uses only built-in defaults

Configuration Behavior

Conflict Resolution: Your custom patterns override defaults when using the same id
Error Handling: Invalid patterns are skipped with non-intrusive notifications
Auto-Reload: Custom configuration changes trigger cache clearing and re-indexing
IntelliSense: Full autocomplete and validation in configuration files
Schema Validation: Built-in JSON schema ensures correct configuration syntax

Configuration Template

Your custom configuration file includes a comprehensive template:

{
  "$schema": "./src/kahua-links-schema.json",
  "version": "1.0.0",
  "links": [
    // Uncomment and modify examples below:
    
    // {
    //   "id": "myCustomPattern",
    //   "def": ["MyElement", "Name"],
    //   "ref": [["Reference", "Target"]],
    //   "crossFileRef": {
    //     "patterns": [["App", "Extends"]],
    //     "fileRefId": "kahuaFile"
    //   }
    // }
  ],
  "fileReferences": [
    // Your custom file reference patterns
  ]
}

Kahua Links Configuration (`kahua-links.json`)

The core of the extension is the kahua-links.json configuration file, which defines how symbols are identified, linked, and resolved across files.

Configuration File Structure

{
  "links": [...],           // Array of link configurations
  "fileReferences": [...]   // Array of file reference patterns
}

Link Configuration Schema

Each link in the links array defines a pattern for connecting symbol definitions to their references:

Basic Link Fields

Field	Type	Required	Description
`id`	string	✅	Unique identifier for this link type
`def`	[string, string, string?]	⬜	Single definition pattern
`defs`	[[string, string, string?]]	⬜	Multiple definition patterns
`ref`	RefPattern[]	⬜	Array of reference patterns
`sym`	[string, string]	⬜	Symmetric pattern (both def and ref)

Note: Each link must have at least one of: def, defs, ref, or sym.

Pattern Syntax

Patterns use the format [element, attribute, condition?]:

Element: XML element name (supports wildcards)
Attribute: XML attribute name (supports wildcards)
Condition: Optional condition (currently supports hasDescendant=ElementName)

Wildcard Support

Both element and attribute names support powerful wildcard matching:

Pattern	Matches	Example
`"*"`	Any value	`"*"` matches any element
`"prefix*"`	Starts with prefix	`"kahua*"` matches `kahua_Core`, `kahua_Base`
`"*suffix"`	Ends with suffix	`"*Label"` matches `HeaderLabel`, `FooterLabel`
`"middle"`	Contains middle	`"Actor"` matches `RoleActor`, `ActorGroup`

Basic Configuration Examples

Simple Definition/Reference:

{
  "id": "directiveSet",
  "def": ["DirectiveSet", "Name"],
  "ref": [["Directives", "Set"]]
}

Multiple Definition Types:

{
  "id": "actors",
  "defs": [
    ["Actor", "Name"],
    ["RoleActor", "Name"],
    ["GroupActor", "Name"],
    ["AttributeActor", "Name"]
  ],
  "ref": [["*", "*Actor"]]
}

Symmetric (Both Definition and Reference):

{
  "id": "function",
  "sym": ["Function", "Name"]
}

Advanced Configuration Features

Value Extraction (`valueExtract`)

Controls how values are extracted from attribute content:

Option	Behavior	Example
`"brackets"`	Extract from `[value]`	`Label="[MyKey]"` → `MyKey`
`"bracketsMultiple"`	Extract all `[values]`	`"[Key1] and [Key2]"` → `Key1`, `Key2`

{
  "id": "label",
  "def": ["Label", "Key"],
  "ref": [["*", "*Label"], ["*", "*Description"]],
  "valueExtract": "bracketsMultiple"
}

Value Lists (`valueList`)

Handle comma-separated or custom-delimited symbol lists:

Global Configuration:

{
  "id": "actors",
  "ref": [["*", "*Actors"]],
  "valueList": {
    "separator": ",",
    "appliesTo": ["ref"]  // Only apply to references, not definitions
  }
}

Per-Pattern Configuration:

{
  "id": "actors", 
  "ref": [
    ["*", "*Actor"],  // Single values
    ["*", "*Actors", { "valueList": { "separator": "," } }]  // Comma-separated
  ]
}

ValueList Fields: | Field | Type | Default | Description | |-------|------|---------|-------------| | separator | string | "," | Character(s) used to split values | | appliesTo | array | ["ref"] | Which pattern types to split: "def", "ref", "sym" |

Qualified References (`valueSplit`)

Navigate to symbols in other files using dot notation:

{
  "id": "lookups",
  "def": ["LookupList", "Name"], 
  "ref": [["Attribute", "LookupListName"]],
  "valueSplit": {
    "separator": ".",
    "fileRefId": "kahuaFile"
  }
}

How it works:

LookupListName="kahua_Core.MyLookup" splits to:
- File: kahua_Core (resolved using fileRefId)
- Symbol: MyLookup (searched in that file)

ValueSplit Fields: | Field | Type | Required | Description | |-------|------|----------|-------------| | separator | string | ✅ | Character to split on (typically ".") | | fileRefId | string | ✅ | File reference config ID for resolving file names |

Conditional Definitions (`hasDescendant`)

Limit definitions to elements containing specific child elements:

{
  "id": "functionDef",
  "def": ["Function", "Name", "hasDescendant=Function.Directives"],
  "ref": [["Function", "Name"]]
}

Only treats <Function Name="..."> as a definition if it contains <Function.Directives>.

Value Extraction (`valueExtract`)

Extract values from special formats:

{
  "id": "label", 
  "def": ["Label", "Key"],
  "ref": [["*", "*Label"], ["*", "*Description"]],
  "valueExtract": "bracketsMultiple"
}

Extraction Types:

"brackets" – Extract content from [value] (e.g., Label="[MyKey]" → MyKey)
"bracketsMultiple" – Extract all bracketed values (e.g., "[Key1] and [Key2]" → Key1, Key2)

Reference Pattern Options

Reference patterns support additional configuration via a third parameter:

{
  "ref": [
    ["Element", "Attribute"],                              // Basic pattern
    ["Element", "Attribute", { "valueList": { ... } }]    // With options
  ]
}

Available Options: | Option | Type | Description | |--------|------|-------------| | valueList | ValueListConfig | Override global valueList for this pattern |

Definition Sorting (`definitionSort`)

Control how definitions are ordered when multiple are found:

{
  "id": "label",
  "def": ["Label", "Key"],
  "ref": [["*", "*Label"]],
  "definitionSort": "distance"  // or "document"
}

Sort Options:

"distance" (default): Sort by proximity to reference location
"document": Sort by document order (top to bottom)

Cross-File Resolution

The extension supports multiple mechanisms for loading symbols from other files:

Imports (`imports`)

Load definitions from files explicitly listed in import declarations:

{
  "id": "label",
  "def": ["Label", "Key"],
  "ref": [["*", "*Label"]],
  "valueExtract": "bracketsMultiple",
  "imports": {
    "element": "Cultures",
    "attribute": "ImportCultures", 
    "fileRefId": "kahuaFile",
    "separator": ","
  }
}

How it works:

<Cultures ImportCultures="kahua_Core,kahua_WorkflowLabels">

→ Loads all Label definitions from kahua_Core.xml and kahua_WorkflowLabels.xml

Import Fields: | Field | Type | Required | Description | |-------|------|----------|-------------| | element | string | ✅ | Element containing import declaration | | attribute | string | ✅ | Attribute with comma-separated file names | | fileRefId | string | ✅ | File reference config ID for resolving files | | separator | string | ⬜ | File name separator (default: ",") |

Cross-File References (`crossFileRef`)

Load definitions from files referenced by specific attributes:

{
  "id": "function", 
  "sym": ["Function", "Name"],
  "crossFileRef": {
    "patterns": [
      ["PartsReference", "Properties.AppName"],
      ["App", "Extends"]
    ],
    "fileRefId": "kahuaFile"
  }
}

How it works:

<PartsReference Properties.AppName="kahua_Contract" />
<App Extends="kahua_Base" />

→ Loads all Function definitions from kahua_Contract.xml and kahua_Base.xml

CrossFileRef Fields: | Field | Type | Required | Description | |-------|------|----------|-------------| | patterns | [[string, string]] | ✅ | Array of [element, attribute] patterns referencing files | | fileRefId | string | ✅ | File reference config ID for resolving files |

Complete Link Example

Here's a comprehensive example showing all features:

{
  "id": "label",
  "def": ["Label", "Key"],
  "ref": [
    ["*", "*Label"],
    ["*", "*Description"],  
    ["*", "Title"],
    ["*", "DisplayName"]
  ],
  "valueExtract": "bracketsMultiple",
  "definitionSort": "document",
  "imports": {
    "element": "Cultures",
    "attribute": "ImportCultures",
    "fileRefId": "kahuaFile",
    "separator": ","
  },
  "crossFileRef": {
    "patterns": [
      ["PartsReference", "Properties.AppName"],
      ["App", "Extends"]
    ],
    "fileRefId": "kahuaFile"
  }
}

File References Configuration

File references define how to resolve file names to actual file paths and enable cross-file navigation.

File Reference Schema

{
  "fileReferences": [
    {
      "id": "kahuaFile",
      "pattern": ["App", "Extends"],
      "searchPaths": [
        "${workspaceFolder}/xml",
        "C:/Kahua/Config",
        "../shared/xml"
      ],
      "fileExtension": ".xml"
    }
  ]
}

File Reference Fields

Field	Type	Required	Description
`id`	string	✅	Unique identifier for this file reference type
`pattern`	[string, string]	✅	Element/attribute pattern for file references
`searchPaths`	string[]	✅	Ordered directories to search for files
`fileExtension`	string	⬜	Extension to append (default: `".xml"`)

Path Variables

Variable	Description	Example
`${workspaceFolder}`	VS Code workspace root	`/home/user/project`
Relative paths	Relative to workspace	`../shared`, `./xml`
Absolute paths	Full system paths	`C:/Kahua/Config`

Search Behavior

File Resolution Process:
- Take file name from XML (e.g., kahua_Core)
- Append fileExtension → kahua_Core.xml
- Search through searchPaths in order
- Return first match found
- Cache result for performance
Example Resolution:
```
<App Extends="kahua_Core" />
```
With searchPaths: ["./xml", "C:/Kahua"]

Tries:
- ./xml/kahua_Core.xml
- C:/Kahua/kahua_Core.xml
- Returns first existing file

Multiple File Reference Types

You can define multiple file reference configurations for different use cases:

{
  "fileReferences": [
    {
      "id": "kahuaFile",
      "pattern": ["App", "Extends"],
      "searchPaths": ["./xml", "../shared"],
      "fileExtension": ".xml"
    },
    {
      "id": "templateFile", 
      "pattern": ["Template", "Source"],
      "searchPaths": ["./templates", "C:/Templates"],
      "fileExtension": ".tpl"
    }
  ]
}

Default Configuration

The extension includes comprehensive default configuration for 25+ common Kahua XML patterns:

Core Symbols

DirectiveSets – Navigate between <DirectiveSet Name="..."> and <Directives Set="...">
Functions – Navigate between function definitions and calls
Variables – Navigate between variable definitions, sets, and usage (supports 38+ variable types)
Events – Navigate between event definitions and <OnEvent> handlers
Queries – Navigate between query definitions and references

Data & Attributes

Attributes – Navigate between attribute definitions and path references
Entity Definitions – Navigate between EntityDef definitions and references
LookupLists – Navigate between lookup definitions and references (with qualified support)
DataTags – Navigate between data tag definitions and references

UI & Display

Labels – Navigate between label definitions and bracketed references with import support
ContentRegions – Navigate between region definitions and usage
ViewDefs/FieldDefs – Navigate between view/field definitions and references

Workflow & Process

Steps – Navigate between workflow step definitions and references
Actors – Navigate between actor definitions (Actor, RoleActor, etc.) and references
OnEvents – Navigate between OnEvent definitions with nested scoping support

Advanced Features

Scope Containers – HubDef isolation and OnEvent nested scoping
Variable Scoping – Hierarchical variable resolution with VariableSet support
Cross-File Resolution – Automatic import and reference loading
Value Pattern Matching – Support for {variable:name}, [Attribute(name)], and ValueVariable patterns

All patterns support cross-file navigation, imports, qualified references, and value extraction.

Configuration Examples

Minimal Setup (Recommended)

For most users, only file reference configuration is needed:

In VS Code settings.json:

{
  "kahuaXml.fileReferences": [
    {
      "id": "kahuaFile", 
      "pattern": ["App", "Extends"],
      "searchPaths": [
        "${workspaceFolder}/xml",
        "C:/Kahua/Config",
        "../shared-kahua-files"
      ],
      "fileExtension": ".xml"
    }
  ]
}

The extension automatically uses its built-in configuration for 20+ symbol types.

Custom Link Configuration

Using the Configuration Editor:

Run Kahua XML Links: Edit Configuration
Modify the opened kahua-links-custom.json file
Save to apply changes (automatically clears cache and re-indexes)

Example custom link:

{
  "links": [
    {
      "id": "customSymbol",
      "def": ["MyElement", "Name"],
      "ref": [["Reference", "Target"]],
      "crossFileRef": {
        "patterns": [["App", "Extends"]],
        "fileRefId": "kahuaFile"
      }
    }
  ]
}

Advanced Multi-File Setup

Complex project with multiple file types:

{
  "kahuaXml.fileReferences": [
    {
      "id": "kahuaFile",
      "pattern": ["App", "Extends"], 
      "searchPaths": [
        "${workspaceFolder}/src/xml",
        "${workspaceFolder}/lib/kahua",
        "C:/Kahua/Standard",
        "//shared/kahua-repository"
      ],
      "fileExtension": ".xml"
    },
    {
      "id": "partialFile",
      "pattern": ["Include", "Source"],
      "searchPaths": [
        "${workspaceFolder}/partials",
        "${workspaceFolder}/shared"
      ], 
      "fileExtension": ".partial.xml"
    }
  ]
}

Usage Examples

Example 1: Navigate to DirectiveSet

File: workflow.xml

<DirectiveSet Name="ValidateLinearLocation">
  <!-- definition -->
</DirectiveSet>

<Step.Commands>
  <Directives Set="ValidateLinearLocation" />
  <!-- Press F12 on "ValidateLinearLocation" to jump to the definition -->
</Step.Commands>

Example 2: Cross-File Function Reference

File: app_extension.xml

<App Extends="kahua_Base">
  <Function Name="MyFunction" />
  <!-- References kahua_Base.xml -->
</App>

File: kahua_Base.xml

<Function Name="BaseFunction" />
<!-- This function is now available in app_extension.xml -->

When you type <Function Name=" in app_extension.xml, autocomplete will suggest both MyFunction and BaseFunction.

Example 3: Label Imports

File: my_app.xml

<Cultures ImportCultures="kahua_Core,kahua_WorkflowLabels">
  <Culture Code="en">
    <Labels>
      <Label Key="MyCustomLabel">My Label</Label>
    </Labels>
  </Culture>
</Cultures>

<Field Label="[MyCustomLabel]" />
<!-- Also can reference labels from kahua_Core and kahua_WorkflowLabels -->

Press F12 on MyCustomLabel to jump to the definition, even if it's in an imported file.

Example 4: Qualified References

File: invoice.xml

<Attribute LookupListName="kahua_UniversalLookup.Universal1" />
<!-- Press F12 to navigate to "Universal1" lookup in kahua_UniversalLookup.xml -->

Example 5: Value Lists

File: permissions.xml

<Command Actors="Administrator,Contributor,Moderator" />
<!-- Press F12 on any actor name to navigate to its definition -->

Example 6: Cross-File Parts Reference

File: contract.xml

<PartsReference Properties.AppName="kahua_FundSource_Parts" />
<!-- All symbols from kahua_FundSource_Parts.xml are now available -->

How It Works

Symbol Resolution Flow

Document Opens → Extension parses the XML
Local Symbols → Extracts definitions and references from current file
Import Processing → If imports configured, loads symbols from imported files
Cross-File References → If crossFileRef configured, loads symbols from referenced files
Recursive Loading → Recursively processes imports/references in loaded files
Cycle Detection → Prevents infinite loops from circular references
Index Building → Merges all symbols and builds position information
Navigation Ready → F12, Shift+F12, and autocomplete now work across all files

File Resolution

When resolving a file name like "kahua_Core":

Append file extension: "kahua_Core.xml"
Search through searchPaths in order
Return first match found
Cache result for performance

Development

Building

npm install
npm run compile

Testing

npm test

All tests use the Mocha framework with TypeScript support.

Packaging

Create a distributable VSIX file:

npm run package

Or using vsce directly:

vsce package

Troubleshooting

Symbols not found across files

Check:

searchPaths are correctly configured in kahuaXml.fileReferences
File names match exactly (case-sensitive on some systems)
Check the Output panel (View → Output → Kahua XML Links) for error messages

Autocomplete not showing cross-file symbols

Verify:

The file reference pattern is correctly configured
imports or crossFileRef is properly set on the link configuration
Referenced files exist in the configured search paths

Extension not activating

The extension activates automatically for XML files. If it's not working:

Ensure the file has .xml extension
Check VS Code's language mode (bottom right) shows "XML"
Reload window (Ctrl+Shift+P → "Reload Window")

Extension Settings

The extension provides numerous settings for fine-tuning behavior. All settings are prefixed with kahuaXml.:

Core Configuration

Setting	Type	Default	Description
`kahuaXml.links`	array	`[]`	Symbol link patterns (use configuration editor instead)
`kahuaXml.fileReferences`	array	`[]`	File reference patterns for cross-file navigation

Performance & Indexing

Setting	Type	Default	Description
`kahuaXml.indexDelayMs`	number	`400`	Delay before indexing after edits (reduces indexing churn)
`kahuaXml.largeFileSizeKb`	number	`2000`	File size threshold for large file handling (KB)
`kahuaXml.largeFileIndexDelayMs`	number	`2500`	Extended delay for large files before indexing
`kahuaXml.largeFileIndexOnSave`	boolean	`false`	Skip indexing large files while typing, only index on save
`kahuaXml.indexWorkspace`	boolean	`false`	Index all workspace XML files at startup (vs. on-demand)
`kahuaXml.indexConcurrency`	number	`1`	Number of files to index simultaneously

Cross-File Features

Setting	Type	Default	Description
`kahuaXml.maxImportDepth`	number	`3`	Maximum recursion depth for following imports/references
`kahuaXml.enableSlowFeatures`	boolean	`true`	Enable cross-file resolution (disable for performance)
`kahuaXml.ignoredFolders`	array	`[]`	Glob patterns to exclude from indexing

Completion Behavior

Setting	Type	Default	Description
`kahuaXml.highPriorityCompletions`	boolean	`true`	Sort Kahua completions before others
`kahuaXml.mergeCompletions`	boolean	`true`	Allow other completion providers to contribute

Backend & Diagnostics

Setting	Type	Default	Description
`kahuaXml.useLspBackend`	boolean	`true`	Use LSP backend (recommended)
`kahuaXml.enableDiagnostics`	boolean	`false`	Enable verbose performance logging

Available Commands

The extension provides several commands accessible via the Command Palette (Ctrl+Shift+P):

Configuration Commands

Kahua XML Links: Edit Configuration
- Opens your personal kahua-links-custom.json customization file
- Allows adding custom patterns or overriding built-in defaults
- Changes take effect immediately after saving with automatic cache clearing
Kahua XML Links: View Default Configuration
- Opens the built-in kahua-links-defaults.json file in read-only mode
- Browse all default patterns included with the extension
- Copy patterns to customize in your personal configuration
Kahua XML Links: Reset Configuration to Defaults
- Removes all customizations and resets to built-in defaults
- Useful for starting fresh or troubleshooting configuration issues
- Automatically clears cache and re-indexes after reset

Cache Management

Kahua XML Links: Clear Cache
- Clears all cached symbol indices and resolved file paths
- Forces re-indexing of all open documents
- Useful when file references have changed or symbols aren't updating

Diagnostics & Monitoring

Kahua XML Links: Show Indexing Files
- Displays a list of files currently being processed by the indexer
- Shows progress during large workspace indexing operations
- Helps identify performance bottlenecks
Kahua XML Links: Show LSP Diagnostics
- Displays detailed performance metrics and timing information
- Shows which files are taking longest to index
- Lists memory usage and cache statistics
- Requires kahuaXml.enableDiagnostics: true for full details
Kahua XML Links: Show All Symbols
- Lists all symbols found in the current workspace
- Groups by symbol type (DirectiveSets, Functions, Labels, etc.)
- Shows symbol counts and source files
- Useful for understanding what the extension has indexed

Performance Considerations

LSP Backend – Uses a dedicated language server for optimal performance
File Caching – Resolved file paths are cached to avoid repeated filesystem lookups
Lazy Loading – Cross-file symbols are only loaded when needed
Cycle Detection – Each file is processed only once per import chain
Incremental Updates – Only affected files are re-indexed on save
Large File Handling – Special optimizations for files over 800KB

Performance Settings

You can fine-tune performance via these settings:

{
  "kahuaXml.indexDelayMs": 400,
  "kahuaXml.largeFileSizeKb": 2000,
  "kahuaXml.largeFileIndexDelayMs": 2500,
  "kahuaXml.maxImportDepth": 3,
  "kahuaXml.indexWorkspace": false,
  "kahuaXml.indexConcurrency": 1,
  "kahuaXml.enableSlowFeatures": true
}

Limitations

Navigation is currently limited to the active workspace
Large import chains (50+ files) may take a few seconds to index initially
Cross-file references require proper searchPaths configuration

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass (npm test)
Submit a pull request

License

This project is licensed under the MIT License. See LICENSE for details.

Repository

This project is hosted at: kahua-xml-links-extension

Issues and contributions welcome!

Changelog

Version 2.4.2 (Current)

🚀 Dual Configuration System – Separates default patterns from user customizations
✨ Version Management – Automatic default updates while preserving customizations
✨ Enhanced Variable Support – Full support for 38+ Kahua variable types with proper scoping
✨ Scope Containers – HubDef isolation and OnEvent nested scoping
✨ Advanced Value Patterns – Support for {variable:name}, [Attribute(name)], ValueVariable patterns
✨ Configuration Commands – View defaults, edit customizations, reset to defaults
✨ Auto-Reload – Configuration changes trigger automatic cache clearing and re-indexing
✨ Schema Validation – Full IntelliSense and validation in configuration files
✨ Build Integration – Configuration files properly copied during F5 debugging
🐛 Fixed Document Selector – Added proper scheme to avoid VS Code warnings

Version 2.3.5

🚀 LSP Backend – Migrated to dedicated Language Server Protocol for better performance
✨ Multiple Definitions – Support for defs array to handle symbols with multiple declaration patterns
✨ Value Lists – Handle comma-separated symbol references with per-pattern configuration
✨ Qualified References – Navigate to symbols in other files using dot notation (file.symbol)
✨ Multiple Bracket Extraction – Extract multiple bracketed values from single attributes
✨ Enhanced Configuration – Built-in configuration editor and comprehensive defaults
✨ Performance Optimizations – Large file handling, workspace indexing controls, concurrency settings
✨ Diagnostics – LSP diagnostics command for performance monitoring
🐛 Improved Reliability – Better error handling and cycle detection

Version 2.0.0

🔄 Major Refactor – Complete rewrite with improved architecture
✨ Comprehensive Defaults – Built-in configuration for 20+ Kahua XML patterns
✨ Advanced Pattern Matching – Wildcard support with prefix/suffix matching
✨ Better Cross-File Support – Enhanced import and reference resolution
✨ Configuration Commands – Easy configuration management via Command Palette

Version 1.1.0

✨ Added support for Query definitions and references
✨ Added support for Attribute (Path) definitions and references
✨ Added support for Actor definitions and references
✨ Added support for ContentRegion definitions and references
✨ Added support for ViewDef definitions and references
✨ Added support for DataTag definitions and references
✨ Added support for Mappings (To/From attribute references)

Version 1.0.0

🎉 Initial release
✨ Basic symbol navigation (definitions, references, symmetric)
✨ Cross-file symbol resolution with imports and crossFileRef
✨ File reference navigation
✨ Value extraction for bracket notation
✨ Conditional definitions with hasDescendant
✨ Recursive loading with cycle detection

Kahua XML Links

Sammy

Kahua XML Links Extension

Features

🎯 Core Navigation

🌐 Cross-File Symbol Resolution

🔧 Advanced Pattern Matching

Installation

From VSIX (Recommended)

From Source

Quick Start

Configuration

Configuration System Overview

Using the Configuration System

Edit Your Customizations (Recommended)

View Default Configuration (Read-Only)

Reset to Defaults

Configuration Behavior

Configuration Template

Kahua Links Configuration (kahua-links.json)

Configuration File Structure

Link Configuration Schema

Basic Link Fields

Pattern Syntax

Wildcard Support

Basic Configuration Examples

Advanced Configuration Features

Value Extraction (valueExtract)

Value Lists (valueList)

Qualified References (valueSplit)

Conditional Definitions (hasDescendant)

Value Extraction (valueExtract)

Reference Pattern Options

Definition Sorting (definitionSort)

Cross-File Resolution

Imports (imports)

Cross-File References (crossFileRef)

Complete Link Example

File References Configuration

File Reference Schema

File Reference Fields

Path Variables

Search Behavior

Multiple File Reference Types

Default Configuration

Core Symbols

Data & Attributes

UI & Display

Workflow & Process

Advanced Features

Configuration Examples

Minimal Setup (Recommended)

Custom Link Configuration

Advanced Multi-File Setup

Usage Examples

Example 1: Navigate to DirectiveSet

Example 2: Cross-File Function Reference

Example 3: Label Imports

Example 4: Qualified References

Example 5: Value Lists

Example 6: Cross-File Parts Reference

How It Works

Symbol Resolution Flow

File Resolution

Development

Building

Testing

Packaging

Troubleshooting

Symbols not found across files

Autocomplete not showing cross-file symbols

Extension not activating

Extension Settings

Core Configuration

Performance & Indexing

Cross-File Features

Completion Behavior

Backend & Diagnostics

Available Commands

Configuration Commands

Kahua Links Configuration (`kahua-links.json`)

Value Extraction (`valueExtract`)

Value Lists (`valueList`)

Qualified References (`valueSplit`)

Conditional Definitions (`hasDescendant`)

Value Extraction (`valueExtract`)

Definition Sorting (`definitionSort`)

Imports (`imports`)

Cross-File References (`crossFileRef`)