Add support for xacro arguments and environment variables via .vscode/xacro.json

[Copilot]

Implementation Complete: Xacro Arguments and Environment Variables Support

Summary

Successfully implemented support for passing arguments and environment variables to Xacro files during preview through a .vscode/xacro.json configuration file. The feature is fully functional, tested, and documented with live configuration reloading.

Latest Updates

• Live configuration reloading: File watcher automatically refreshes previews when xacro.json changes
• $(find package) support: Include directives using $(find package) syntax now properly resolved during argument detection
• Package path resolution: Uses package map to resolve package:// URIs when scanning includes
• Complete detection: Arguments in files included via $(find package)/path/file.xacro are now detected
• Error logging: Missing packages logged to output channel during scanning
• Code quality improvements: Template literal syntax corrected, high-precision performance tests

Complete Documentation

Published User Documentation:

• docs/xacro-configuration.md - Complete user guide with examples, use cases, and workflow
  • Added to mkdocs navigation for public access
  • Comprehensive examples and troubleshooting

Developer Documentation:

• README.md - Quick start and overview
• Code comments in xacroConfig.ts and utils.ts
• Test documentation with refactoring opportunities noted

Complete Test Coverage (33 Tests)

xacroConfig.test.ts (22 tests):

• Detection tests (5): Basic argument and env var detection
• Pattern detection tests (6): xacro:arg, $(arg), $(env), $(optenv) syntax
• Duplicate avoidance tests (2): Deduplication verification
• Configuration matching tests (5): Exact and wildcard pattern matching
• Edge cases (4): Empty content, null config, error handling

suite/recursiveInclude.test.ts (11 tests):

• Recursive scanning tests (5): Multi-level include processing
• Accumulation tests (3): Argument aggregation across files
• Performance tests (3): Set-based deduplication with microsecond precision, edge cases

All Features Complete ✓

• Core implementation with recursive include scanning
• $(find package) resolution in includes
• Performance optimization with Set-based deduplication
• Single and double quote support for includes
• 33 comprehensive unit tests
• User documentation published via mkdocs
• Improved error logging to output channel
• Live configuration reloading with file watcher ✓
• Template literal syntax corrected ✓
• High-precision performance benchmarks ✓
• Code review completed and addressed
• Security scan (CodeQL) passed
• Build verification passed

Live Configuration Reloading

File watcher implementation (extension.ts):

• Watches **/.vscode/xacro.json across all workspace folders
• Automatically refreshes all active URDF previews on file changes
• Handles creation, modification, and deletion events
• Logs configuration changes to "URDF Editor" output channel

User experience improvement:

• Users can now edit .vscode/xacro.json and see changes immediately in active previews
• No need to close and reopen previews after configuration modifications
• Seamless workflow for iterating on argument and environment variable values

Package Resolution in Include Scanning

Enhanced scanIncludedFile function:

• Converts $(find package_name) to package://package_name format in include paths
• Resolves package:// URIs using the package map (same logic as parser.getFileContents)
• Handles missing packages gracefully with logging to output channel
• Continues scanning other includes even if one package is not found

Example:

• Include directive: <xacro:include filename="$(find robot_pkg)/urdf/sensors.xacro"/>
• Resolved to actual filesystem path based on package map
• Arguments and environment variables in sensors.xacro are detected and offered to user

Error Handling Improvements

Changed in xacroConfig.ts:

• Line 56: vscode.window.showErrorMessage() → tracing.appendLine()
• Line 81: vscode.window.showErrorMessage() → tracing.appendLine()
• Errors now appear in "URDF Editor" output window instead of modal dialogs

Code Quality Improvements

Template literal fixes:

• Corrected ${workspaceFolder} variable placeholder syntax in configuration file paths
• Changed from string concatenation to proper template literals

Performance test enhancements:

• Using performance.now() from perf_hooks module for microsecond precision
• More reliable benchmark results for comparing Set vs Array performance

The feature is production-ready with comprehensive package path resolution support, live configuration reloading, and improved error handling that doesn't interrupt the user workflow with modal dialogs.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[feature] support XACRO parameters and environment variables</issue_title>
<issue_description>This feature is about allowing the user to specify arguments to xacro file which are used to render the urdf output, without modifying the Xacro file itself. Since Xacro is processed by the extension and not a launch file, these need to be specified easily by the user. Recall that Sometimes people use .urdf, but attempt to process like a xacro file.

To facilitate this, before processing a xacro or urdf file, introspect the file and include files for argument or environment related arguments. If there are non-present, then process normally.

If there are arguments or environment variables present, or if you cannot determine this - ask the user if they would like to create a file in the .vscode folder to allow providing values to the urdf file you are about to preview. If they say yes, then create a file like the following format (adjust as required to implement):

.vscode\xacro.json:

{
    "version": "1.0.0",
    "${workspaceFolder}/src/....../filename.xacro":
        args: {
            "argName1": "this is to be replaced whereever argName1",
            "argName1": "arg 2",
        },
       env: {
            "envName1": "this is to be replaced whereever argName1",
       }
...

This can also use wildcards like **/ or rhrbot_*.xacro.*

When processing a xacro, load this map. For the arguments, pass them to the file being loaded based on the map.
If there is an error about missing arguments; extract the argument and add an entry to the xacro.json and inform the user with a friendly prompt about it being missing and ask them to add it.

Add environment variables similarly; however, when processing an environment variable, if the value isn't in the map, check the real environment.

</issue_description>

<agent_instructions>Provide a minimal solution to this. Recall that we are using a xacro library and properties are handled via callback; so the map may need to be plumbed through to the callback</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes [feature] support XACRO parameters and environment variables #44

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[ranchhandrobotics]

@copilot this change does not seem to detect args in included xacro files

[Copilot]

@copilot this change does not seem to detect args in included xacro files

Fixed in commit 1304507. The code now recursively scans all <xacro:include> files to detect arguments and environment variables. When you preview a xacro file that includes other files with arguments, all arguments from the main file and included files are now detected and accumulated before prompting the user to create the configuration file.

The implementation:

• Parses <xacro:include filename="..."/> directives in the main file
• Recursively scans each included file for more includes
• Detects xacro:arg, $(arg), $(env), and $(optenv) in all files
• Tracks processed files to avoid duplicates
• Accumulates all detected arguments before prompting

Test files added:

• included_with_args.xacro - Contains arguments in an included file
• main_with_includes_with_args.xacro - Main file that includes it

[ranchhandrobotics]

@copilot add unit tests to verify your changes

[Copilot]

@copilot add unit tests to verify your changes

Added comprehensive unit tests in commit b3910a6.

Test Coverage:

• 22 tests in xacroConfig.test.ts - Tests detection, pattern matching, and configuration management
• 11 tests in suite/recursiveInclude.test.ts - Tests recursive include scanning and integration

Key areas tested:

• Argument detection (xacro:arg, $(arg ...))
• Environment variable detection ($(env ...), $(optenv ...))
• Recursive include file scanning
• Single and double quote support in includes
• Wildcard pattern matching
• Duplicate prevention
• Error handling (missing files, empty content)
• Performance (Set-based deduplication)

All tests compile successfully and verify the implementation. Detailed test documentation available in docs/test-documentation.md.

[ranchhandrobotics]

@copilot user facing documentation needs to be added to mkdoc in order to be published. No need to link internal test documentation

[Copilot]

@copilot user facing documentation needs to be added to mkdoc in order to be published. No need to link internal test documentation

Added user-facing documentation to mkdocs in commit 14e4cdf.

Changes:

• Added "Xacro Arguments & Environment Variables" to mkdocs navigation (line 9 in mkdocs.yml)
• Removed internal test documentation (test-documentation.md) from docs folder
• User guide at docs/xacro-configuration.md is now published in the documentation site

The xacro configuration documentation will now appear in the published docs between "Configuration" and "WebXR Preview".

addressed

[Copilot]

Pull request overview

This pull request adds comprehensive support for passing xacro arguments and environment variables to Xacro files during preview through a .vscode/xacro.json configuration file. The implementation includes automatic detection of arguments/environment variables, configuration management, recursive scanning of included files, and improved error handling via output channel logging instead of modal dialogs.

Key changes:

• New configuration system supporting file patterns, wildcards, and variable substitution for xacro arguments and environment variables
• Recursive scanning of included files to detect all required arguments and environment variables
• Enhanced environment variable resolution with config-first fallback to process.env
• Comprehensive test suite (33 tests) covering detection, pattern matching, recursive includes, and edge cases

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
src/xacroConfig.ts	New module implementing configuration file management, argument/env detection, pattern matching, and user prompting
src/utils.ts	Integration of xacro configuration into processing pipeline with recursive include scanning and enhanced env/optenv callbacks
src/test/xacroConfig.test.ts	Unit tests for configuration detection, pattern matching, and edge cases (22 tests)
src/test/suite/recursiveInclude.test.ts	Tests for recursive include scanning with performance benchmarks (11 tests)
src/test/testdata/*.xacro	Test fixtures demonstrating various argument and environment variable usage patterns
docs/xacro-configuration.md	Comprehensive user documentation with examples, workflows, and troubleshooting
README.md	Quick start guide and feature overview for xacro configuration
mkdocs.yml	Added documentation page to navigation
package.json	Added minimatch dependency for pattern matching
package-lock.json	Lockfile updates for new dependencies