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, and recursive symbol loading.

Features

🎯 Core Navigation

• 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)
• Recursive Loading – Automatically follows import chains and file references
• Cycle Detection – Prevents infinite loops when files have circular references

🔧 Advanced Pattern Matching

• Wildcard Elements – Use * to match any element name
• Attribute Matching Modes – Exact, contains, startsWith, endsWith
• Value Extraction – Extract values from brackets like [LabelKey]
• Conditional Definitions – Limit definitions to elements with specific descendants

Installation

From VSIX (Recommended)

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

From Source

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

Quick Start

1. Install the extension – The default configuration is already set up
2. 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"
    }
  ]
}

3. Open a Kahua XML file – Navigation features work immediately!

Configuration

The extension is configured via two main settings in your VS Code settings.json:

1. Symbol Links (kahuaXml.links)

Defines patterns for symbol definitions, references, and navigation behavior.

Basic Link Configuration

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

Fields:

Field	Type	Required	Description
id	string	✅	Unique identifier for this link type
def	[string, string, string?]	⬜	Definition pattern: [element, attribute, condition?]
ref	[[string, string, matchType?]]	⬜	Array of reference patterns: [[element, attribute, matchType?]]
sym	[string, string]	⬜	Symmetric pattern: [element, attribute] (both def and ref)

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

Advanced Configuration Options

Attribute Matching (refAttrMatch)

Control how reference attribute names are matched:

{
  "id": "label",
  "def": ["Label", "Key"],
  "ref": [["*", "Label"]],
  "refAttrMatch": "contains"
}

Match Types:

• "exact" (default) – Attribute name must match exactly
• "contains" – Attribute name must contain the pattern (e.g., HeaderLabel matches Label)
• "startsWith" – Attribute name must start with the pattern
• "endsWith" – Attribute name must end with the pattern

Value Extraction (valueExtract)

Extract values from special formats:

{
  "id": "label",
  "def": ["Label", "Key"],
  "ref": [["*", "Label"]],
  "refAttrMatch": "contains",
  "valueExtract": "brackets"
}

Extraction Types:

• "brackets" – Extract content from [value] (e.g., Label="[MyKey]" → MyKey)

Cross-File Imports (imports)

Load definitions from files listed in an import declaration:

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

How it works: When the extension finds:

<Cultures ImportCultures="kahua_Core,kahua_WorkflowLabels">

It automatically loads all Label definitions from kahua_Core.xml and kahua_WorkflowLabels.xml.

Import Fields:

Field	Type	Required	Description
element	string	✅	Element containing the import declaration
attribute	string	✅	Attribute containing comma-separated file names
fileRefId	string	✅	ID of file reference config to use for resolving files
separator	string	⬜	Separator character (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: When the extension finds:

<PartsReference Properties.AppName="kahua_Contract" />

or

<App Extends="kahua_Base" />

It automatically loads all Function definitions from those referenced files.

CrossFileRef Fields:

Field	Type	Required	Description
patterns	[[string, string]]	✅	Array of [element, attribute] patterns that reference files
fileRefId	string	✅	ID of file reference config to use for resolving files

Conditional Definitions (hasDescendant)

Require elements to have specific descendants:

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

How it works: Only treats <Function Name="..."> as a definition if it contains a <Function.Directives> child element.

2. File References (kahuaXml.fileReferences)

Defines patterns for navigating to other files and configures search paths.

{
  "kahuaXml.fileReferences": [
    {
      "id": "kahuaFile",
      "pattern": ["App", "Extends"],
      "searchPaths": [
        "${workspaceFolder}/xml",
        "G:/OneDrive/Documents/vscode projects/xml_files",
        "C:/Kahua/Config"
      ],
      "fileExtension": ".xml"
    }
  ]
}

Fields:

Field	Type	Required	Description
id	string	✅	Unique identifier referenced by imports/crossFileRef
pattern	[string, string]	✅	Pattern identifying file references: [element, attribute]
searchPaths	string[]	✅	Ordered list of directories to search for files
fileExtension	string	⬜	File extension to append (default: ".xml")

Path Variables:

• ${workspaceFolder} – Root directory of your workspace

Search Behavior: Files are searched in the order listed. The first match wins.

Complete Configuration Example

Here's a full example with all features enabled:

{
  "kahuaXml.fileReferences": [
    {
      "id": "kahuaFile",
      "pattern": ["App", "Extends"],
      "searchPaths": [
        "${workspaceFolder}/xml",
        "G:/OneDrive/Documents/vscode projects/kahua_xml"
      ],
      "fileExtension": ".xml"
    }
  ],
  "kahuaXml.links": [
    {
      "id": "directiveSet",
      "def": ["DirectiveSet", "Name"],
      "ref": [["Directives", "Set"]],
      "crossFileRef": {
        "patterns": [
          ["PartsReference", "Properties.AppName"],
          ["App", "Extends"]
        ],
        "fileRefId": "kahuaFile"
      }
    },
    {
      "id": "function",
      "sym": ["Function", "Name"],
      "crossFileRef": {
        "patterns": [
          ["PartsReference", "Properties.AppName"],
          ["App", "Extends"]
        ],
        "fileRefId": "kahuaFile"
      }
    },
    {
      "id": "onEvent",
      "def": ["OnEvent", "Name"],
      "ref": [["OnEvent", "Event"]],
      "crossFileRef": {
        "patterns": [
          ["PartsReference", "Properties.AppName"],
          ["App", "Extends"]
        ],
        "fileRefId": "kahuaFile"
      }
    },
    {
      "id": "label",
      "def": ["Label", "Key"],
      "ref": [["*", "Label"], ["*", "Description"]],
      "refAttrMatch": "contains",
      "valueExtract": "brackets",
      "imports": {
        "element": "Cultures",
        "attribute": "ImportCultures",
        "fileRefId": "kahuaFile",
        "separator": ","
      },
      "crossFileRef": {
        "patterns": [
          ["PartsReference", "Properties.AppName"],
          ["App", "Extends"]
        ],
        "fileRefId": "kahuaFile"
      }
    }
  ]
}

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: 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

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

File Resolution

When resolving a file name like "kahua_Core":

1. Append file extension: "kahua_Core.xml"
2. Search through searchPaths in order
3. Return first match found
4. 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:

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

Autocomplete not showing cross-file symbols

Verify:

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

Extension not activating

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

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

Performance Considerations

• 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

Limitations

• Navigation is currently limited to the active workspace
• Large import chains (50+ files) may take a few seconds to index
• Changes in referenced files require re-opening the referencing file to reflect

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass (npm test)
5. Submit a pull request

License

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

Changelog

Version 1.0.1

• ✨ Added cross-file symbol resolution with imports support
• ✨ Added cross-file reference resolution with crossFileRef
• ✨ Added file reference navigation
• ✨ Added advanced attribute matching modes
• ✨ Added value extraction for bracket notation
• ✨ Added recursive loading with cycle detection
• 🐛 Fixed test infrastructure to work without vscode module
• 📚 Comprehensive documentation and examples

Version 1.0.0

• 🎉 Initial release
• ✨ Basic symbol navigation (definitions, references, symmetric)
• ✨ Conditional definitions with hasDescendant
• ✨ Configurable link patterns