docs: expand website documentation with guides and architecture #228
Conversation
📝 WalkthroughWalkthroughAdds extensive documentation pages (installation, building, CLI reference, multiple guides, Claude integration), updates site navigation and homepage, introduces a VSCode workspace setting, and adjusts site CSS for table header alignment; no public API changes. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Organization UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (2)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
In @README.md:
- Around line 105-134: Replace the incorrect CLI subcommand name
"shell-completion" with the correct "generate-completion" in the README
examples: update the Bash examples `source <(oscal-cli shell-completion bash)`
and `oscal-cli shell-completion bash --to ~/.oscal-completion.bash` to `source
<(oscal-cli generate-completion bash)` and `oscal-cli generate-completion bash
--to ~/.oscal-completion.bash`, and update the Zsh example `oscal-cli
shell-completion zsh > ~/.zsh/completions/_oscal-cli` to `oscal-cli
generate-completion zsh > ~/.zsh/completions/_oscal-cli` so the documented
command (generate-completion) matches the implemented CLI.
In @src/site/markdown/building.md.vm:
- Around line 13-21: The JAVA_HOME instructions mix a macOS-only command with
Linux, so split OS-specific guidance: replace the single "Linux/macOS" block
with separate entries for "macOS" (keep export
JAVA_HOME=$(/usr/libexec/java_home -v 17)) and "Linux" (tell users to export
JAVA_HOME to their JDK path, e.g. /usr/lib/jvm/java-17-openjdk), and ensure the
Windows example remains as the separate "Windows" entry; update the surrounding
text in building.md.vm to label each OS explicitly and note that Linux users
should adjust the path to their installation.
In @src/site/markdown/claude-integration.md.vm:
- Around line 16-18: The prerequisites section contains a broken link to
"Metaschema plugins" pointing at
https://github.com/metaschema-framework/claude-plugins; update the link target
in src/site/markdown/claude-integration.md.vm by either replacing that URL with
the correct repository URL if it exists (verify the correct org/repo and update
the markdown list item for "Metaschema plugins") or remove the entire second
list item if the plugins are not available, ensuring the numbered list remains
valid.
In @src/site/markdown/guides/validating-oscal.md.vm:
- Around line 80-84: The docs list a "Mappings" validation command that isn't
implemented; either remove that section or add CLI support: implement a
MappingCommand and a ValidateSubcommand for mapping (mirror the existing
catalog/profile/ssp command structure), ensure the mapping validate handler
accepts oscal-cli validate /path/to/mapping.json, wire the new MappingCommand
into the main validate command registry (same place other types are registered),
and add tests and help text so the documentation matches the implemented
commands.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (13)
.vscode/settings.jsonREADME.mdsrc/site/markdown/building.md.vmsrc/site/markdown/claude-integration.md.vmsrc/site/markdown/guides/cli-reference.md.vmsrc/site/markdown/guides/converting-formats.md.vmsrc/site/markdown/guides/resolving-profiles.md.vmsrc/site/markdown/guides/validating-oscal.md.vmsrc/site/markdown/guides/working-with-metaschema.md.vmsrc/site/markdown/index.md.vmsrc/site/markdown/installation.md.vmsrc/site/resources/css/custom.csssrc/site/site.xml
🧰 Additional context used
🧠 Learnings (4)
📚 Learning: 2024-12-12T00:15:45.005Z
Learnt from: aj-stein-gsa
Repo: metaschema-framework/oscal-server PR: 44
File: .oscal/component.oscal.yaml:2-2
Timestamp: 2024-12-12T00:15:45.005Z
Learning: When reviewing OSCAL content in YAML format, validate general content quality aspects like UUID uniqueness across entities, in addition to OSCAL-specific validations.
Applied to files:
src/site/markdown/guides/converting-formats.md.vmsrc/site/markdown/guides/validating-oscal.md.vm
📚 Learning: 2026-01-05T18:03:33.537Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java/dev/metaschema/core/datatype/package-info.java:52-52
Timestamp: 2026-01-05T18:03:33.537Z
Learning: In metaschema-framework/metaschema-java, CLAUDE.md is the canonical coding-guidelines document and now specifies dev.metaschema.* as the Java package convention (updated in PR #618).
Applied to files:
src/site/markdown/guides/working-with-metaschema.md.vmsrc/site/markdown/index.md.vmsrc/site/markdown/claude-integration.md.vm
📚 Learning: 2025-12-30T19:08:21.896Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: src/site/markdown/index.md.vm:3-3
Timestamp: 2025-12-30T19:08:21.896Z
Learning: In the metaschema-framework/metaschema-java repository, https://framework.metaschema.dev/ is the project's preferred and canonical documentation URL for the Metaschema framework. While https://pages.nist.gov/metaschema/ is an alternative, the project uses framework.metaschema.dev as the official reference in documentation and should not be changed to pages.nist.gov URLs.
Applied to files:
src/site/markdown/guides/working-with-metaschema.md.vm
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to **/metapath/**/*.java : Metapath is an implementation of XPath 3.1. Use the XPath 3.1 specification (https://www.w3.org/TR/xpath-31/) and XPath Functions 3.1 (https://www.w3.org/TR/xpath-functions-31/) as authoritative reference when implementing new functions, fixing bugs, or understanding error handling. Raise clarification before making changes if implementation differs from spec.
Applied to files:
src/site/markdown/guides/working-with-metaschema.md.vm
🧬 Code graph analysis (1)
src/site/markdown/guides/resolving-profiles.md.vm (3)
src/main/java/gov/nist/secauto/oscal/tools/cli/core/commands/AbstractResolveCommand.java (1)
AbstractResolveCommand(48-264)src/main/java/gov/nist/secauto/oscal/tools/cli/core/commands/ResolveCommand.java (1)
ResolveCommand(14-24)src/main/java/gov/nist/secauto/oscal/tools/cli/core/commands/profile/ResolveSubcommand.java (1)
ResolveSubcommand(18-36)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Code
- GitHub Check: Website
🔇 Additional comments (46)
.vscode/settings.json (1)
1-3: LGTM!The VS Code workspace configuration correctly enables interactive Java build configuration updates, which will prompt developers when
pom.xmlchanges are detected. This is a sensible default for a Maven-based project.src/site/resources/css/custom.css (1)
24-29: LGTM!The CSS override correctly addresses the flexmark limitation by forcing left-alignment on table headers. The use of
!importantis justified to override Bootstrap's default styles, and the comment clearly explains the workaround.README.md (1)
138-138: LGTM!The Maven version requirement update from 3.8.4+ to 3.9.0+ is consistent with the same requirement documented in
src/site/markdown/building.md.vmline 10.src/site/markdown/building.md.vm (4)
23-36: LGTM!The repository cloning instructions are correct and include the necessary
--recurse-submodulesflag, with a helpful alternative for users who cloned without submodules initially.
72-86: LGTM!The CI/CD build instructions correctly document the profiles (
-PCI -Prelease) and the additional quality checks they enable. This is valuable for contributors who want to replicate the full CI build locally.
88-140: LGTM!The code quality commands, CLI execution instructions, and container/site building commands are all accurate and follow standard Maven and Docker conventions.
190-192: Documentation links are correctly referenced. Bothinstallation.md.vmandguides/cli-reference.md.vmexist in the repository at the expected locations (src/site/markdown/andsrc/site/markdown/guides/respectively).src/site/markdown/guides/cli-reference.md.vm (6)
5-61: LGTM!The global options and validate command documentation is comprehensive and well-structured, with clear examples and exit code documentation that will help users troubleshoot validation issues.
64-137: LGTM!The convert and resolve-profile command documentation follows a consistent pattern with clear argument descriptions and practical examples for common use cases.
222-241: LGTM!The format detection and environment variable documentation is accurate and covers the expected file extensions and standard Java configuration options.
243-277: LGTM!The container reference section provides practical Docker examples for volume mounting and resource limits, which will help users work with large OSCAL documents in containerized environments.
278-284: All See Also link targets exist—no action required.All five referenced documentation files are present in the repository, confirming that the links in the See Also section are valid.
206-220: Themapping-collectionroot element for the Mapping document type is documented in the official NIST OSCAL Reference as part of the prototype mapping model specification. The table entry is correct and requires no changes.src/site/markdown/index.md.vm (6)
29-56: LGTM! Clear Quick Start examples.The Docker and CLI examples provide practical starting points. The volume mounting syntax is correct, and the command examples demonstrate common operations effectively.
58-78: LGTM! Comprehensive feature overview.The feature descriptions effectively communicate the CLI's capabilities with clear explanations of each major function and its value proposition.
80-89: LGTM! Command table is accurate.The command listing matches the CLI implementation, including the top-level
resolve-profilecommand documented in the codebase.
102-127: LGTM! Container and shell completion instructions are clear.The Docker examples and shell completion setup instructions provide practical guidance for different use cases.
129-148: LGTM! Good references and support information.The related projects table and support section provide helpful context and resources. The use of Maven variables for project URLs ensures consistency across the documentation.
91-101: All referenced guide files exist in the repository. The filesbuilding.md.vm,guides/converting-formats.md.vm,guides/working-with-metaschema.md.vm, andguides/cli-reference.md.vmare present and accounted for. No action required.Likely an incorrect or invalid review comment.
src/site/markdown/guides/resolving-profiles.md.vm (8)
1-28: LGTM! Clear explanation of profile resolution.The rationale and overview effectively communicate the purpose and benefits of profile resolution, with practical examples of use cases.
30-62: LGTM! Command examples are accurate.The basic resolution commands and format conversion options correctly demonstrate the CLI's capabilities, consistent with the implementation in AbstractResolveCommand.
84-97: LGTM! Clear explanation of profile chaining.The ASCII diagram and explanation effectively illustrate how profile chains are resolved recursively.
99-125: LGTM! Remote resource handling is well documented.The examples correctly demonstrate how to resolve profiles that reference remote catalogs, with accurate JSON structure for the import element.
143-177: LGTM! CI/CD integration example is well-structured.The GitHub Actions workflow provides a practical automation pattern, and the Velocity escape syntax
#[[ ]]#correctly prevents Maven from processing the YAML content.
189-219: LGTM! Helpful troubleshooting guidance.The common errors and their solutions provide practical debugging assistance for users encountering profile resolution issues.
221-246: LGTM! Technical details are accurate.The resolution behavior and order tables provide useful reference information for advanced users needing to understand the detailed mechanics of profile resolution.
247-253: LGTM! Good navigation to related guides.The Next Steps section provides logical progression paths for users to continue learning about the CLI.
src/site/markdown/guides/validating-oscal.md.vm (6)
1-24: LGTM! Clear validation rationale and levels.The explanation of validation importance and the three-tier validation approach provides users with a solid understanding of what validation checks.
26-62: LGTM! Validation command examples are clear.The basic validation commands and mode options demonstrate the CLI's validation capabilities effectively.
116-148: LGTM! Output format documentation is helpful.The explanation of validation output, including the structured error format with severity, location, and description, helps users interpret validation results effectively.
149-183: LGTM! Practical error examples and solutions.The common validation errors and their fixes provide valuable troubleshooting guidance, with concrete examples and actionable solutions.
185-228: LGTM! Batch validation and automation examples are practical.The shell scripting examples and CI/CD integration patterns provide useful automation guidance for validating multiple files.
230-245: LGTM! Standard exit codes and good navigation.The exit code reference is helpful for CI/CD integration, and the Next Steps provide logical progression to related guides.
src/site/markdown/installation.md.vm (6)
1-29: LGTM! Clear installation method guidance.The comparison table helps users choose the appropriate installation method, and the prerequisites are clearly documented with version requirements.
58-113: LGTM! Container instructions are accurate.The Docker and Podman examples are correct, including the
:ZSELinux label for Podman which is appropriate for systems with SELinux enabled.
115-165: LGTM! Comprehensive CI/CD examples.The examples for GitHub Actions, GitLab CI, and Jenkins provide practical patterns for integrating the CLI into different CI/CD platforms.
167-196: LGTM! Shell completion setup is well documented.The instructions for both Bash and Zsh cover temporary and permanent installation, with appropriate paths and completion cache rebuilding for Zsh.
198-219: LGTM! Good verification steps and navigation.The verification commands help users confirm correct installation, and the Next Steps provide logical progression to usage guides.
31-56: Maven artifact coordinates are correct.Verified against pom.xml and assembly.xml:
- Group ID:
dev.metaschema.oscal✓- Artifact ID:
oscal-cli-enhanced✓- Distribution file:
-oscal-cli.zip✓ (from assembly id)The Maven Central repository URL and installation instructions at lines 31-56 accurately reflect the published artifact coordinates.
src/site/markdown/claude-integration.md.vm (3)
47-82: LGTM! Realistic Claude Code interaction examples.The example workflows demonstrate practical use cases for AI-assisted OSCAL development, with clear prompts that users can adapt.
84-107: LGTM! Practical tips and command reference.The usage tips help users communicate effectively with Claude Code, and the command examples reinforce the CLI patterns shown throughout the documentation.
109-115: LGTM! Helpful external resources.The Learn More section provides appropriate links to Claude Code documentation, OSCAL specification, and the CLI reference guide.
src/site/markdown/guides/converting-formats.md.vm (1)
1-252: LGTM! Comprehensive and well-structured format conversion guide.This documentation provides clear, actionable guidance for converting OSCAL documents between formats. The command examples are correct, Docker integration is well-explained, and the troubleshooting section addresses common issues effectively. The structure flows logically from basic concepts to advanced usage patterns.
src/site/markdown/guides/working-with-metaschema.md.vm (2)
1-235: Well-structured guide with clear examples.The Metapath expression syntax tables, practical examples, and OSCAL model modules overview provide excellent reference material. The progression from basic queries to complex patterns is pedagogically sound.
236-236: Update the Metapath specification URL to use the correct path.The URL should be
https://pages.nist.gov/metaschema/specification/syntax/metapath/(note the/syntax/directory). The current URL is missing the/syntax/path component and will not resolve correctly.src/site/site.xml (1)
52-63: LGTM! Clean navigation structure.The new Documentation and Guides menus provide logical grouping for the expanded content. The menu organization (setup instructions under Documentation, usage patterns under Guides) makes the site structure intuitive and discoverable.
| ### Mappings | ||
|
|
||
| ```bash | ||
| oscal-cli validate /path/to/mapping.json | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify Mapping model support in the codebase
echo "=== Checking for Mapping model class definitions ==="
rg --type=java 'class.*Mapping|interface.*Mapping' -g '!**/test/**' src/main/java/ | head -20
echo ""
echo "=== Checking for mapping enum or document type references ==="
rg --type=java 'Mapping|MAPPING' -g '!**/test/**' src/main/java/ | grep -E '(enum|case|DocumentType|Type\.)' | head -30
echo ""
echo "=== Checking validation support for mapping ==="
rg --type=java 'validate.*[Mm]apping|mapping.*validat' src/main/java/ | head -20
echo ""
echo "=== Checking CLI commands for mapping support ==="
rg --type=java 'mapping' src/main/java/gov/nist/oscal/cli/ -i | head -20
echo ""
echo "=== Looking for model/binding references ==="
fd -t f -e java . src/main/java | xargs grep -l "Mapping" | grep -E '(model|binding)' | head -10Repository: metaschema-framework/oscal-cli
Length of output: 426
🏁 Script executed:
#!/bin/bash
# Explore repository structure
echo "=== Repository structure ==="
ls -la | head -20
echo ""
echo "=== Looking for Java source files ==="
find . -type d -name 'src' -o -name 'java' -o -name 'main' 2>/dev/null | head -20
echo ""
echo "=== All .java files in repository ==="
find . -name '*.java' -type f 2>/dev/null | head -20
echo ""
echo "=== Searching for any 'Mapping' references ==="
rg -i 'mapping' --type=java | head -30
echo ""
echo "=== Checking OSCAL model or configuration files ==="
find . -name '*.xml' -o -name '*.xsd' -o -name '*.json' | grep -i model | head -20Repository: metaschema-framework/oscal-cli
Length of output: 3611
🏁 Script executed:
#!/bin/bash
# List all command subdirectories
echo "=== Command subdirectories ==="
find ./src/main/java/dev/metaschema/oscal/tools/cli/core/commands -mindepth 1 -maxdepth 1 -type d | sort
echo ""
echo "=== All Java files in commands directory ==="
find ./src/main/java/dev/metaschema/oscal/tools/cli/core/commands -name '*.java' | sort
echo ""
echo "=== Searching for 'mapping' in all source files ==="
rg -i 'mapping' --type=java -A 2 -B 2
echo ""
echo "=== Checking documentation files ==="
find . -name '*.md' -o -name '*.vm' | xargs grep -l -i 'mapping' 2>/dev/nullRepository: metaschema-framework/oscal-cli
Length of output: 4837
🏁 Script executed:
#!/bin/bash
# Check the file being reviewed
echo "=== Checking the documentation file around lines 80-84 ==="
sed -n '70,95p' ./src/site/markdown/guides/validating-oscal.md.vm
echo ""
echo "=== Check full context of document type sections ==="
grep -n "###" ./src/site/markdown/guides/validating-oscal.md.vm | head -20
echo ""
echo "=== Look for Mapping references in doc files ==="
grep -n -i "mapping" ./src/site/markdown/guides/validating-oscal.md.vm
echo ""
echo "=== Check git diff for this file ==="
git diff --no-color HEAD -- src/site/markdown/guides/validating-oscal.md.vm | head -100Repository: metaschema-framework/oscal-cli
Length of output: 1180
🌐 Web query:
OSCAL mapping document type model
💡 Result:
OSCAL provides a Control Mapping (or "mapping") model — a document-type for describing relationships (mappings) between collections of security controls/control statements (e.g., crosswalks, mappings between catalogs or profiles). The model is part of the OSCAL Reference and is published with XML/JSON/YAML format references and metaschema (prototype and development snapshots). See NIST/OSCAL reference pages for the model, XML/JSON format references, and metaschema. [1][2][3]
Sources:
- OSCAL Control Mapping model (prototype mapping model overview). [1]
- OSCAL Control Mapping — XML format reference. [2]
- OSCAL Control Mapping — JSON/metaschema reference (development snapshot). [3]
Remove Mapping section or implement CLI support.
Mapping is a valid OSCAL document type, but the oscal-cli does not currently support validation of Mapping documents. The documentation references mapping validation at lines 80-84, but there is no corresponding command implementation in the codebase (no mapping/ command directory exists, unlike catalog, profile, ssp, componentdefinition, assessmentplan, assessmentresults, and poam). Either remove this section from the guide or implement the necessary CLI commands (MappingCommand, ValidateSubcommand, etc.) to support it.
🤖 Prompt for AI Agents
In @src/site/markdown/guides/validating-oscal.md.vm around lines 80 - 84, The
docs list a "Mappings" validation command that isn't implemented; either remove
that section or add CLI support: implement a MappingCommand and a
ValidateSubcommand for mapping (mirror the existing catalog/profile/ssp command
structure), ensure the mapping validate handler accepts oscal-cli validate
/path/to/mapping.json, wire the new MappingCommand into the main validate
command registry (same place other types are registered), and add tests and help
text so the documentation matches the implemented commands.
There was a problem hiding this comment.
The Mapping model IS supported. It is included in the oscal_complete_metaschema.xml which imports oscal_mapping_metaschema.xml. The MappingCollection class is generated and available in liboscal-java (see oscal-metaschema-bindings.xml lines 177-184). Restored the Mapping Collection examples in the documentation.
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify the user's claims about Mapping model support
echo "=== Checking for oscal_complete_metaschema.xml ==="
find . -name "oscal_complete_metaschema.xml" -type f 2>/dev/null | head -5
echo ""
echo "=== Checking for oscal_mapping_metaschema.xml ==="
find . -name "oscal_mapping_metaschema.xml" -type f 2>/dev/null | head -5
echo ""
echo "=== Checking for oscal-metaschema-bindings.xml ==="
find . -name "oscal-metaschema-bindings.xml" -type f 2>/dev/null | head -5
echo ""
echo "=== If found, check lines 177-184 of oscal-metaschema-bindings.xml ==="
find . -name "oscal-metaschema-bindings.xml" -type f -exec sed -n '170,190p' {} \; 2>/dev/null
echo ""
echo "=== Search for MappingCollection class references ==="
rg -i "MappingCollection" --type=java -A 2 -B 2 | head -40
echo ""
echo "=== Check if mapping validation is supported in CLI ==="
rg -i "mapping" --type=java src/main/java/dev/metaschema/oscal/tools/cli/core/commands/ -A 2 -B 2 | head -50
Length of output: 1105
🏁 Script executed:
#!/bin/bash
# Check how the validate command works and what document types it supports
echo "=== Find ValidateCommand or validate-related files ==="
find . -name "*Validate*.java" -type f | grep -v test | head -20
echo ""
echo "=== Check validate command implementation ==="
rg "class.*Validate.*Command" --type=java -A 10 | head -60
echo ""
echo "=== Check for document type detection or enumeration ==="
rg "DocumentType|OscalModelType|catalog|profile|ssp" --type=java src/main/java/dev/metaschema/oscal/tools/cli/core/commands/ -B 2 -A 2 | head -80
echo ""
echo "=== Check pom.xml for liboscal-java dependency ==="
grep -A 5 -B 2 "liboscal-java\|oscal-metaschema" pom.xml | head -30
echo ""
echo "=== Look at the main CLI commands directory structure ==="
ls -la src/main/java/dev/metaschema/oscal/tools/cli/core/commands/ 2>/dev/null || echo "Directory not found"
Length of output: 12962
🏁 Script executed:
#!/bin/bash
# Check the generic validation command implementation
echo "=== Check AbstractOscalValidationCommand ==="
cat src/main/java/dev/metaschema/oscal/tools/cli/core/commands/AbstractOscalValidationCommand.java
echo ""
echo "=== Check ValidateCommand full implementation ==="
cat src/main/java/dev/metaschema/oscal/tools/cli/core/commands/ValidateCommand.java
echo ""
echo "=== Check what resources are available in liboscal-java for schema validation ==="
rg "oscal.*_schema\.(xsd|json)" --type=java | head -20
echo ""
echo "=== Check if there's a mapping schema reference ==="
rg -i "mapping.*schema|oscal-mapping" --type=java
Length of output: 9420
@david-waltermire, you're absolutely right, and I apologize for the incorrect review comment.
I can now see that the generic ValidateCommand uses oscal-complete_schema.xsd and oscal-complete_schema.json for validation, which includes all OSCAL document types, including Mapping. The validation architecture supports two approaches:
- Generic validation via
oscal-cli validate <file>- uses the complete schema (supports all document types including Mapping) - Type-specific validation via
oscal-cli <type> validate <file>- uses type-specific schemas (catalog, profile, ssp, etc.)
Since the Mapping model is included in the complete schema (which imports oscal_mapping_metaschema.xml as you mentioned), the documentation at lines 80-84 is correct—users can validate mapping documents using the generic validate command without needing a dedicated mapping command directory.
Thank you for the correction and for clarifying the architecture!
✏️ Learnings added
Learnt from: david-waltermire
Repo: metaschema-framework/oscal-cli PR: 228
File: src/site/markdown/guides/validating-oscal.md.vm:0-0
Timestamp: 2026-01-10T23:52:01.344Z
Learning: In oscal-cli, the generic `validate` command uses the complete OSCAL schema (oscal-complete_schema.xsd/json) which includes all OSCAL document types including Mapping. Document types don't require dedicated command directories if they're supported through the generic validation path.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
🧠 Learnings used
Learnt from: aj-stein-gsa
Repo: metaschema-framework/oscal-server PR: 44
File: .oscal/component.oscal.yaml:2-2
Timestamp: 2024-12-12T00:15:45.005Z
Learning: When reviewing OSCAL content in YAML format, validate general content quality aspects like UUID uniqueness across entities, in addition to OSCAL-specific validations.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/DefaultMetaschemaClassFactory.java:480-484
Timestamp: 2025-12-30T04:19:49.192Z
Learning: In metaschema-framework/metaschema-java, when users configure custom superinterfaces via binding configuration, david-waltermire prefers both documentation (explaining how to add dependencies to the Maven plugin) and validation mechanisms (warnings when classes aren't on classpath) to prevent redundant IBoundObject interface additions during code generation.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/csrc/ns/metaschema/test_suite/_1_0/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:40.208Z
Learning: In metaschema-framework/metaschema-java, generated binding classes in package gov.nist.csrc.ns.metaschema.test_suite._1_0 (and similar generated binding packages) are pre-generated by metaschema-maven-plugin and checked into source control. Javadoc coverage issues in these generated classes should be tracked as code generator improvements rather than file-level issues, and improvements are deferred to generator enhancements.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/GenerationCase.java:74-80
Timestamp: 2025-12-24T21:22:07.082Z
Learning: Files in the package gov.nist.secauto.metaschema.model.testing.testsuite in metaschema-testing are generated binding classes created from Metaschema definitions. Documentation and style improvements for these files should be made at the code generator level (metaschema-maven-plugin) rather than by manually editing the generated code.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:56.361Z
Learning: In metaschema-testing, generated binding classes under gov.nist.secauto.metaschema.model.testing.testsuite are produced by metaschema-maven-plugin from YAML metaschema definitions. Javadoc issues in these generated classes should not be flagged for manual fixes; improvements are tracked and handled through code generator enhancements rather than manual edits to the generated source.
- Add installation.md.vm with download, container, and CI/CD instructions - Add building.md.vm with JDK 17 requirement and CI profile instructions - Add claude-integration.md.vm documenting Claude Code plugin skills - Add 5 guide pages covering validation, format conversion, profile resolution, Metapath queries, and CLI command reference - Update site.xml with Documentation and Guides navigation menus - Enhance index.md.vm with quick start and feature overview
- Fix shell-completion to generate-completion in README - Clarify OS-specific JAVA_HOME instructions (separate macOS/Linux) - Remove broken claude-plugins link - Remove unsupported Mapping model sections - Use canonical URL framework.metaschema.dev
david-waltermire
force-pushed
the
site-expansion
branch
from
5b36c84 to
0bc9f80
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In @src/site/markdown/index.md.vm:
- Around line 117-128: Update the "Shell Completion" section (the "Shell
Completion" header and the two oscal-cli generate-completion examples) to
include brief prerequisite notes and directory-creation/sourcing guidance:
mention that Bash users may need to create and source
~/.local/share/bash-completion/completions and possibly source the distro
bash_completion file, and that Zsh users must create ~/.zsh/completions and add
it to $fpath before running compinit; add these notes immediately before the
Bash/Zsh examples so users know to ensure directories exist and their shell
configs are updated.
- Around line 143-148: Replace the hardcoded branch in the CONTRIBUTING.md link
so it is branch-agnostic: locate the link string
"[Contributing](${project.scm.url}/blob/develop/CONTRIBUTING.md)" in
src/site/markdown/index.md.vm and change it to use a branch-agnostic reference
(for example replace "blob/develop" with "blob/HEAD" or a URL form that omits
the branch) so the link resolves correctly across branches and future branch
changes.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (13)
.vscode/settings.jsonREADME.mdsrc/site/markdown/building.md.vmsrc/site/markdown/claude-integration.md.vmsrc/site/markdown/guides/cli-reference.md.vmsrc/site/markdown/guides/converting-formats.md.vmsrc/site/markdown/guides/resolving-profiles.md.vmsrc/site/markdown/guides/validating-oscal.md.vmsrc/site/markdown/guides/working-with-metaschema.md.vmsrc/site/markdown/index.md.vmsrc/site/markdown/installation.md.vmsrc/site/resources/css/custom.csssrc/site/site.xml
✅ Files skipped from review due to trivial changes (1)
- src/site/markdown/guides/working-with-metaschema.md.vm
🚧 Files skipped from review as they are similar to previous changes (6)
- src/site/site.xml
- src/site/markdown/guides/validating-oscal.md.vm
- src/site/markdown/claude-integration.md.vm
- README.md
- src/site/markdown/installation.md.vm
- src/site/resources/css/custom.css
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2024-12-12T00:15:45.005Z
Learnt from: aj-stein-gsa
Repo: metaschema-framework/oscal-server PR: 44
File: .oscal/component.oscal.yaml:2-2
Timestamp: 2024-12-12T00:15:45.005Z
Learning: When reviewing OSCAL content in YAML format, validate general content quality aspects like UUID uniqueness across entities, in addition to OSCAL-specific validations.
Applied to files:
src/site/markdown/guides/converting-formats.md.vmsrc/site/markdown/index.md.vm
📚 Learning: 2026-01-05T18:03:33.537Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java/dev/metaschema/core/datatype/package-info.java:52-52
Timestamp: 2026-01-05T18:03:33.537Z
Learning: In metaschema-framework/metaschema-java, CLAUDE.md is the canonical coding-guidelines document and now specifies dev.metaschema.* as the Java package convention (updated in PR #618).
Applied to files:
src/site/markdown/index.md.vm
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Website
- GitHub Check: Code
🔇 Additional comments (16)
.vscode/settings.json (1)
1-3: LGTM! Appropriate VSCode configuration for Maven projects.The
interactivemode for build configuration updates is a sensible choice for a Maven-based Java project, ensuring developers are prompted before automatic updates occur.src/site/markdown/guides/cli-reference.md.vm (3)
1-283: Well-structured and comprehensive CLI reference documentation.The documentation provides clear command syntax, options, examples, and cross-references. The structure is consistent across all commands, making it easy to navigate.
206-219: No action needed. The document types table is accurate and complete.The table lists all seven OSCAL document types defined in the official specification (catalog, profile, system-security-plan, component-definition, assessment-plan, assessment-results, and plan-of-action-and-milestones). This matches exactly with the OSCAL Model Modules documented in
working-with-metaschema.md.vm. "Mapping" is not an official OSCAL document type and does not appear in the specification's module definitions.Likely an incorrect or invalid review comment.
47-48: Verify remote URL validation support by testing the actual CLI.The documentation explicitly claims remote URL support for the validate command (lines 30, 48). The code structure is consistent with this feature (URL imports, method signatures), but the implementation is delegated to the external
metaschema-cliparent library. To confirm this feature works as documented, manually test the CLI with a remote OSCAL document URL.src/site/markdown/guides/converting-formats.md.vm (1)
1-246: Excellent format conversion guide with practical examples.The guide provides clear explanations, covers batch operations and CI/CD integration, and includes helpful troubleshooting tips. The Velocity template escaping is used correctly for shell examples.
src/site/markdown/guides/resolving-profiles.md.vm (1)
1-253: Comprehensive and technically accurate profile resolution guide.The guide effectively explains OSCAL profile concepts, resolution workflow, and provides practical examples for common scenarios. The JSON example syntax is correct, and the troubleshooting section covers key error scenarios.
src/site/markdown/building.md.vm (2)
1-195: Well-organized build documentation with helpful troubleshooting.The guide provides comprehensive build instructions, covers development workflows, and includes practical troubleshooting for common issues. Maven commands and Git operations are correct.
6-11: Investigate Maven version requirement further.The prerequisites specify Maven 3.9.0 as required, but no enforcer rules in the local pom.xml or anywhere in this repository enforce this minimum version. The CI workflows use Maven 3.9.8, and the troubleshooting section mentions "enforcer rule failures" despite no enforcer plugin being present locally. The requirement likely originates from the parent POM (oss-parent:9), which is external to this repository. Consider clarifying whether 3.9.0 is strictly enforced or a soft recommendation, and update the documentation if the actual constraint is less restrictive.
src/site/markdown/index.md.vm (8)
1-4: LGTM!Clear and concise introduction with appropriate external links to OSCAL and Metaschema official resources.
5-28: LGTM!Well-structured introduction that clearly communicates the tool's value proposition and practical use cases. The benefits are concrete and the reference to the underlying library is appropriate.
29-57: LGTM!The Quick Start examples are well-structured and technically correct. Docker volume mounting syntax is proper, and the CLI examples are consistent with container usage patterns.
58-79: LGTM!Comprehensive feature descriptions that accurately explain both capabilities and use cases. Technical details are correct, including validation constraints, format conversion fidelity, and Metapath's relationship to XPath.
80-101: LGTM!Both tables are well-formatted and provide clear navigation. The guide links correctly reference the new documentation structure introduced in this PR.
102-116: LGTM!Container usage examples are consistent with the Quick Start section and use correct Docker syntax. The reference to the installation guide for CI/CD integration is appropriate.
129-138: LGTM!Related projects are well-organized and link to appropriate external resources. The ecosystem context helps users understand the broader framework.
139-142: LGTM!Appropriate reference to the Claude integration documentation added in this PR. The link correctly points to the generated HTML output.
The shell-completion command was incorrectly documented as generate-completion in several places. Updated README.md and website documentation to use the correct command name.
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Fix all issues with AI agents
In @src/site/markdown/index.md.vm:
- Around line 117-128: Update the Shell Completion examples so the target
directories are created before redirecting output and add a Zsh fpath note: run
mkdir -p for ~/.local/share/bash-completion/completions and ~/.zsh/completions
before running the respective oscal-cli shell-completion commands, and mention
that users should ensure ~/.zsh/completions is in their fpath (or add it and run
autoload -U compinit; compinit) so Zsh finds the completion file.
In @src/site/markdown/installation.md.vm:
- Around line 33-42: The Quick Start uses literal LATEST_VERSION placeholders
that will 404; update the markdown in installation.md.vm so the download snippet
is actually copy/pasteable by replacing the bare LATEST_VERSION tokens with a
clear VERSION variable pattern and derived BASE URL (e.g., introduce a
VERSION="<REPLACE_WITH_VERSION_FROM_MAVEN_CENTRAL>" and BASE derived from that)
and construct the curl URL using those variables so users can paste, set VERSION
once, and run the curl/unzip commands without manual inline token replacements.
- Around line 171-195: Update the shell completion install steps to create
target directories before redirecting or moving files and ensure zsh's compinit
is available: add a mkdir -p step before the Bash permanent install (before
`oscal-cli shell-completion bash >
~/.local/share/bash-completion/completions/oscal-cli`) and before the Zsh
install directory (before `mv _oscal-cli ~/.zsh/completions/`), and add a
note/guard to run `compinit` only if it exists (or show how to initialize it)
instead of unconditionally running `rm -f ~/.zcompdump && compinit`.
- Around line 121-137: The Velocity template is consuming literal CI tokens like
`${{ github.workspace }}` and `${WORKSPACE}`; update the occurrences in
installation.md.vm to escape the `$` so they render literally (e.g., replace
`${{ github.workspace }}` with `\${{ github.workspace }}` and `${WORKSPACE}`
with `\${WORKSPACE}`) wherever those tokens appear (including the validate
workflow snippet and the later occurrences), ensuring Velocity outputs the raw
CI syntax instead of interpolating it.
- Around line 57-64: Replace the non-browsable raw.githubusercontent.com link
with the GitHub tree view so users can browse snapshots; update the link in the
Download Snapshot Versions section to the repository tree URL (e.g.,
https://github.com/metaschema-framework/maven2/tree/main/dev/metaschema/oscal/oscal-cli-enhanced/)
and ensure the surrounding step text still refers to browsing and downloading
the latest -oscal-cli.zip file.
🧹 Nitpick comments (1)
src/site/markdown/index.md.vm (1)
60-79: Consider softening “full fidelity / no data loss” unless it’s guaranteed for all OSCAL constructs.“Round-trip … without data loss” (Line 66) is a strong guarantee; if there are any known edge cases (ordering, formatting, YAML nuances, etc.), this should be qualified to avoid bug reports that are really doc issues.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
README.mdsrc/site/markdown/guides/cli-reference.md.vmsrc/site/markdown/index.md.vmsrc/site/markdown/installation.md.vm
🚧 Files skipped from review as they are similar to previous changes (1)
- src/site/markdown/guides/cli-reference.md.vm
🧰 Additional context used
🧠 Learnings (5)
📚 Learning: 2024-12-12T00:15:45.005Z
Learnt from: aj-stein-gsa
Repo: metaschema-framework/oscal-server PR: 44
File: .oscal/component.oscal.yaml:2-2
Timestamp: 2024-12-12T00:15:45.005Z
Learning: When reviewing OSCAL content in YAML format, validate general content quality aspects like UUID uniqueness across entities, in addition to OSCAL-specific validations.
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: All PRs must be created from a personal fork and must target the develop branch (BLOCKING - required by CONTRIBUTING.md)
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2026-01-07T04:40:01.060Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 623
File: .github/workflows/build.yml:8-14
Timestamp: 2026-01-07T04:40:01.060Z
Learning: In the metaschema-java repository, the build workflow intentionally includes `main` in the `pull_request.branches` trigger even though CONTRIBUTING.md requires PRs to target `develop`. This is a defensive design to provide feedback if someone accidentally targets main, rather than silent failure. The UPLOAD_SCAN_SARIF logic also needs main for security scan results.
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: All PRs must target the `develop` branch, not `main`. The `main` branch receives merges only from `develop` during releases.
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2026-01-05T18:03:33.537Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java/dev/metaschema/core/datatype/package-info.java:52-52
Timestamp: 2026-01-05T18:03:33.537Z
Learning: In metaschema-framework/metaschema-java, CLAUDE.md is the canonical coding-guidelines document and now specifies dev.metaschema.* as the Java package convention (updated in PR #618).
Applied to files:
src/site/markdown/index.md.vm
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Code
🔇 Additional comments (8)
README.md (2)
105-135: Shell Completion section is clear and comprehensive.The new Shell Completion section provides well-organized, practical instructions for both Bash and Zsh with clear separation between temporary and persistent setup approaches. The use of the correct
shell-completioncommand aligns with the documented fix in this PR.Please confirm that the
shell-completioncommand is fully implemented and tested in the CLI to ensure users can actually run these documented commands.
138-138: Maven version requirement updated correctly.The requirement has been updated from 3.8.4 to 3.9.0. Ensure this version requirement is aligned with the actual build environment constraints and CI/CD pipeline configuration.
src/site/markdown/index.md.vm (5)
80-89: Command table looks good; please confirm subcommand names/options are exact.Nice concise “Common Commands” section. The only risk is drift vs the actual CLI (
metapath eval,shell-completion,resolve-profile,convert --to=…). If any of these are aliases or have different flag spellings, users will copy/paste into failures.
90-101: Good “Getting Started” mapping; verify the linked pages exist at these exact paths.The table is a solid onboarding funnel. Please confirm the site actually generates
installation.html,building.html, and theguides/*.htmlpaths as written (case/path sensitivity).
31-41: Current examples are correct as-is; the proposed--entrypointfix contains an error.The Docker image already has
ENTRYPOINT [ "/opt/oscal-cli/bin/oscal-cli" ]defined in bothDockerfile.ciandDockerfile.local, so the current examples work correctly without explicitly setting--entrypoint.If explicit entrypoint specification were added for robustness, it would need to be the full path (
--entrypoint /opt/oscal-cli/bin/oscal-cli), not justoscal-clias suggested in the proposed diff—oscal-clialone wouldn't resolve unless it's in the container's PATH.Additionally, using
"$(pwd)"is more portable than$PWD(which may not be set in all shell environments), so that change should not be made.The examples are stable as-is because any changes to the image's entrypoint would be controlled through the Dockerfiles in this repository.
Likely an incorrect or invalid review comment.
3-28: Remove or clarify the claim about NIST's libraries on line 23.The statement "Built on the same libraries used by NIST for OSCAL reference implementations" is overstated. The project uses
liboscal-javaand Metaschema Java libraries that are derived from NIST's work, but the README indicates it's feature-compatible with NIST v1.0.3 while using newer library versions with additional bug fixes. Either remove this phrase or replace it with more precise language like "Uses the OSCAL Java library derived from NIST's reference implementations" with a link toliboscal-java.⛔ Skipped due to learnings
Learnt from: david-waltermire Repo: metaschema-framework/metaschema-java PR: 605 File: src/site/markdown/index.md.vm:3-3 Timestamp: 2025-12-30T19:08:21.896Z Learning: In the metaschema-framework/metaschema-java repository, https://framework.metaschema.dev/ is the project's preferred and canonical documentation URL for the Metaschema framework. While https://pages.nist.gov/metaschema/ is an alternative, the project uses framework.metaschema.dev as the official reference in documentation and should not be changed to pages.nist.gov URLs.Learnt from: david-waltermire Repo: metaschema-framework/metaschema-java PR: 618 File: core/src/main/java/dev/metaschema/core/datatype/package-info.java:52-52 Timestamp: 2026-01-05T18:03:33.537Z Learning: In metaschema-framework/metaschema-java, CLAUDE.md is the canonical coding-guidelines document and now specifies dev.metaschema.* as the Java package convention (updated in PR #618).
147-148: Fix the fragile Velocity link:${project.scm.url}/blob/...produces invalid GitHub URLs.
${project.scm.url}resolves tohttps://github.com/metaschema-framework/oscal-cli/tree/develop(from the pom.xml<scm><url>element), which when concatenated with/blob/develop/CONTRIBUTING.mdproduceshttps://github.com/metaschema-framework/oscal-cli/tree/develop/blob/develop/CONTRIBUTING.md— an invalid URL mixing GitHub's/tree/and/blob/path segments.Use the base
scm.urlproperty directly (without/tree/develop) or introduce a dedicated property for the GitHub HTTPS repo base URL to construct valid file links.⛔ Skipped due to learnings
Learnt from: david-waltermire Repo: metaschema-framework/metaschema-java PR: 623 File: .github/workflows/build.yml:8-14 Timestamp: 2026-01-07T04:40:01.060Z Learning: In the metaschema-java repository, the build workflow intentionally includes `main` in the `pull_request.branches` trigger even though CONTRIBUTING.md requires PRs to target `develop`. This is a defensive design to provide feedback if someone accidentally targets main, rather than silent failure. The UPLOAD_SCAN_SARIF logic also needs main for security scan results.src/site/markdown/installation.md.vm (1)
1-15: Nice structure and method comparison table; reads well.
| ### Download Snapshot Versions | ||
|
|
||
| Snapshot versions contain the latest changes from the `develop` branch. These include new features and bug fixes that haven't been released yet, but may be less stable: | ||
|
|
||
| 1. Browse the [snapshot repository](https://raw.githubusercontent.com/metaschema-framework/maven2/refs/heads/main/dev/metaschema/oscal/oscal-cli-enhanced/) | ||
| 2. Download the latest `-oscal-cli.zip` file | ||
| 3. Extract and add to PATH | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Test the raw.githubusercontent.com URL behavior
echo "=== Testing raw.githubusercontent.com URL behavior ==="
echo "Testing: https://raw.githubusercontent.com/metaschema-framework/maven2/refs/heads/main/dev/metaschema/oscal/oscal-cli-enhanced/"
curl -s -I "https://raw.githubusercontent.com/metaschema-framework/maven2/refs/heads/main/dev/metaschema/oscal/oscal-cli-enhanced/" | head -20
echo -e "\n=== Testing the suggested GitHub tree view URL ==="
echo "Testing: https://github.com/metaschema-framework/maven2/tree/main/dev/metaschema/oscal/oscal-cli-enhanced"
curl -s -I "https://github.com/metaschema-framework/maven2/tree/main/dev/metaschema/oscal/oscal-cli-enhanced" | head -20
echo -e "\n=== Checking if the repository exists ==="
curl -s -I "https://api.github.com/repos/metaschema-framework/maven2" | head -20Repository: metaschema-framework/oscal-cli
Length of output: 7087
The snapshot repository link uses raw.githubusercontent.com which returns HTTP 400 and won't display as a browsable directory. Use the GitHub tree view URL instead so users can actually browse the snapshot repository:
Suggested fix
-1. Browse the [snapshot repository](https://raw.githubusercontent.com/metaschema-framework/maven2/refs/heads/main/dev/metaschema/oscal/oscal-cli-enhanced/)
+1. Browse the [snapshot repository](https://github.com/metaschema-framework/maven2/tree/main/dev/metaschema/oscal/oscal-cli-enhanced)🤖 Prompt for AI Agents
In @src/site/markdown/installation.md.vm around lines 57 - 64, Replace the
non-browsable raw.githubusercontent.com link with the GitHub tree view so users
can browse snapshots; update the link in the Download Snapshot Versions section
to the repository tree URL (e.g.,
https://github.com/metaschema-framework/maven2/tree/main/dev/metaschema/oscal/oscal-cli-enhanced/)
and ensure the surrounding step text still refers to browsing and downloading
the latest -oscal-cli.zip file.
There was a problem hiding this comment.
@coderabbitai The raw.githubusercontent.com URLs use the VERSION variable that users set. The instructions explain how to find the latest version and set the variable accordingly. This pattern works correctly for downloading release artifacts.
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Get the full content of the installation.md.vm file to understand the complete context
cat src/site/markdown/installation.md.vm
Length of output: 6859
🏁 Script executed:
#!/bin/bash
# Demonstrate that the browse link returns HTTP 400
echo "=== Testing the browse link from line 61 ==="
echo "URL: https://raw.githubusercontent.com/metaschema-framework/maven2/refs/heads/main/dev/metaschema/oscal/oscal-cli-enhanced/"
curl -sL -w "\nHTTP Status: %{http_code}\n" \
"https://raw.githubusercontent.com/metaschema-framework/maven2/refs/heads/main/dev/metaschema/oscal/oscal-cli-enhanced/" \
| head -20
echo -e "\n=== Testing the GitHub tree view URL ==="
echo "URL: https://github.com/metaschema-framework/maven2/tree/main/dev/metaschema/oscal/oscal-cli-enhanced"
curl -sL -w "\nHTTP Status: %{http_code}\n" \
"https://github.com/metaschema-framework/maven2/tree/main/dev/metaschema/oscal/oscal-cli-enhanced" \
| head -5
Length of output: 355
@david-waltermire Thank you for the clarification. I understand that download URLs with VERSION variables work correctly. However, my comment was specifically about the browse link on line 61, which is intended for users to find the latest snapshot version.
The script results show that the raw.githubusercontent.com URL returns 400: Invalid request when used as a browsing/directory listing link:
URL: https://raw.githubusercontent.com/metaschema-framework/maven2/refs/heads/main/dev/metaschema/oscal/oscal-cli-enhanced/
400: Invalid request
HTTP Status: 400
The current instruction says "Browse the [snapshot repository]" - this browse action fails with HTTP 400. The GitHub tree view URL (https://github.com/metaschema-framework/maven2/tree/main/dev/metaschema/oscal/oscal-cli-enhanced) works for browsing and returns HTTP 200, allowing users to see the directory listing and identify which snapshot version to download.
Once users identify the version from browsing, they would then use it in their download URL (with the VERSION variable as you mentioned). The suggestion is only to change the browse/discovery link, not the download pattern.
That said, if you prefer to keep the current approach or have instructions elsewhere that make this work, I'll defer to your judgment on this.
There was a problem hiding this comment.
@coderabbitai The raw.githubusercontent.com URLs use the VERSION variable that users set. The instructions explain how to find the latest version and set the variable accordingly.
| ### GitLab CI | ||
|
|
||
| ```yaml | ||
| validate-oscal: | ||
| image: ghcr.io/metaschema-framework/oscal-cli:latest | ||
| script: | ||
| - oscal-cli validate ssp.json | ||
| ``` | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, find and read the installation.md.vm file
fd installation.md.vmRepository: metaschema-framework/oscal-cli
Length of output: 110
🏁 Script executed:
# Read the installation.md.vm file to see the full context
cat -n src/site/markdown/installation.md.vmRepository: metaschema-framework/oscal-cli
Length of output: 8127
🏁 Script executed:
# Find Dockerfile or any container-related files
fd -i dockerfileRepository: metaschema-framework/oscal-cli
Length of output: 104
🏁 Script executed:
# Check both Dockerfile files
cat -n Dockerfile.ci
echo "---"
cat -n Dockerfile.localRepository: metaschema-framework/oscal-cli
Length of output: 3260
🏁 Script executed:
# Check if /bin/sh exists in eclipse-temurin:17 base image and if oscal-cli is added to PATH
# Let's search for any PATH modifications in the Dockerfiles
grep -n "PATH" Dockerfile.ci Dockerfile.localRepository: metaschema-framework/oscal-cli
Length of output: 207
🏁 Script executed:
# Let me verify GitLab CI script execution behavior and how it handles ENTRYPOINTs
# Create a simple test to understand the issue
# First, let's check what the eclipse-temurin:17 base image includes
# It's a full JDK image, so it definitely has /bin/sh, but let's verify the entrypoint issue
# The concern is valid: when ENTRYPOINT is set to a binary directly,
# GitLab CI's script directive may not work as expected
# Let's check the GitLab documentation understanding by searching for any .gitlab-ci.yml examples in the repo
find . -name ".gitlab-ci.yml" -o -name "*.gitlab-ci.yml" 2>/dev/null | head -5Repository: metaschema-framework/oscal-cli
Length of output: 56
🏁 Script executed:
# Let me create a Python script to verify GitLab CI's behavior with custom ENTRYPOINTs
python3 << 'EOF'
# Research findings about GitLab CI Docker executor:
# When GitLab CI uses the Docker executor with a custom image:
# 1. It can override the ENTRYPOINT for script execution
# 2. The /bin/sh availability depends on the base image
# 3. eclipse-temurin:17 is a full JDK image that includes /bin/sh
# Key facts:
# - Dockerfile.ci and Dockerfile.local both set: ENTRYPOINT [ "/opt/oscal-cli/bin/oscal-cli" ]
# - Base image is eclipse-temurin:17 (a full JDK image, NOT minimal)
# - eclipse-temurin:17 definitely includes /bin/sh (it's based on Debian/Ubuntu)
print("Analysis of the review comment concerns:")
print("1. 'Image has oscal-cli entrypoint': TRUE - confirmed by ENTRYPOINT directive")
print("2. 'Image lacks /bin/sh': FALSE - eclipse-temurin:17 is a full JDK image with /bin/sh")
print("3. 'GitLab CI script will fail': NEEDS VERIFICATION")
print("\nGitLab CI Docker executor behavior:")
print("- Can override ENTRYPOINT for script: execution")
print("- Will use /bin/sh -c to execute script commands if available")
print("- Should work fine with this image since /bin/sh exists")
EOFRepository: metaschema-framework/oscal-cli
Length of output: 160
🏁 Script executed:
# Check if there are any tests or documentation about GitLab CI in the repo
find . -type f \( -name "*.md" -o -name "*.yml" -o -name "*.yaml" \) | xargs grep -l "gitlab\|GitLab" 2>/dev/null | head -10Repository: metaschema-framework/oscal-cli
Length of output: 56
🌐 Web query:
GitLab CI Docker executor ENTRYPOINT override script directive
💡 Result:
Short answer — in .gitlab-ci.yml set image with an entrypoint. Example:
image:
name: my-image:tag
entrypoint: [""]
script:
- echo "runs with ENTRYPOINT overridden"
Notes:
- Docker executor by default does NOT override an image ENTRYPOINT; giving entrypoint: [""] passes --entrypoint "" to docker run and allows the runner to start a shell command. [1][2]
- Older Docker (<17.06) may require a shell entrypoint instead (e.g. ["/bin/sh","-c"]). [3]
- Kubernetes executor behavior differs (it may ignore/replace ENTRYPOINT), so behavior can be executor-dependent. [4]
Sources: GitLab Runner docs (Docker executor and image:entrypoint) and related docs/issues. [1][2][3][4]
References
[1] GitLab Docs — Docker executor (Configure a Docker ENTRYPOINT). (docs.gitlab.com)
[2] GitLab CI/CD YAML reference — image:entrypoint. (docs.gitlab.com)
[3] GitLab help / Using docker images (notes on Docker version differences). (gitlab.schbrain.com)
[4] GitLab Runner issue discussing Kubernetes executor ENTRYPOINT behavior. (gitlab.com)
Citations:
- 1: https://docs.gitlab.com/runner/executors/docker/?utm_source=openai
- 2: https://docs.gitlab.com/ee/ci/yaml/?utm_source=openai
- 3: https://gitlab.schbrain.com/gitlab/help/ci/docker/using_docker_images.md?utm_source=openai
- 4: https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4125?utm_source=openai
GitLab CI example requires ENTRYPOINT override. The image has a custom ENTRYPOINT (/opt/oscal-cli/bin/oscal-cli), and GitLab CI's Docker executor does not override it by default. The script: directive will fail without explicitly clearing the ENTRYPOINT. Add entrypoint: [""] to the image configuration:
Corrected example
validate-oscal:
image:
name: ghcr.io/metaschema-framework/oscal-cli:latest
entrypoint: [""]
script:
- oscal-cli validate ssp.jsonThere was a problem hiding this comment.
@coderabbitai The installation instructions include the prerequisite of setting the VERSION variable. Users who follow the steps sequentially will have VERSION defined before reaching these commands.
There was a problem hiding this comment.
@david-waltermire I think there may be some confusion here. My comment was specifically about the GitLab CI example (lines 137-144) requiring an entrypoint: [""] override to work correctly with the container's custom ENTRYPOINT.
The VERSION variable you're referring to doesn't appear in the GitLab CI example—that example simply references the image and runs oscal-cli validate ssp.json. The issue is that GitLab CI's Docker executor won't override the container's ENTRYPOINT by default, so the script: commands won't execute as shell commands without explicitly clearing the ENTRYPOINT.
Did you perhaps mean to respond to a different review comment? The GitLab CI example still needs the correction I mentioned to function properly in GitLab CI pipelines.
🧠 Learnings used
Learnt from: david-waltermire
Repo: metaschema-framework/oscal-cli PR: 228
File: src/site/markdown/guides/validating-oscal.md.vm:0-0
Timestamp: 2026-01-10T23:52:11.139Z
Learning: In oscal-cli, the generic `validate` command uses the complete OSCAL schema (oscal-complete_schema.xsd/json) which includes all OSCAL document types including Mapping. Document types don't require dedicated command directories if they're supported through the generic validation path.
Learnt from: david-waltermire
Repo: metaschema-framework/oscal-cli PR: 228
File: src/site/markdown/index.md.vm:0-0
Timestamp: 2026-01-11T15:57:01.784Z
Learning: In oscal-cli site documentation (src/site/markdown/index.md.vm), the CONTRIBUTING.md link intentionally references the `develop` branch (not HEAD or main) because CONTRIBUTING.md is maintained on develop and that's where contributions are made. This ensures users see the correct contribution guidelines.
There was a problem hiding this comment.
@coderabbitai The installation instructions include the prerequisite of setting the VERSION variable. Users who follow the steps sequentially will have VERSION defined before reaching these commands.
There was a problem hiding this comment.
@david-waltermire I notice this is the same response as your previous comment. Just to clarify—my review comment is specifically about the GitLab CI example (lines 137-144), which doesn't reference a VERSION variable.
The concern is that the GitLab CI Docker executor doesn't override the ENTRYPOINT of a Docker image by default. Since the oscal-cli container has ENTRYPOINT ["/opt/oscal-cli/bin/oscal-cli"], the script: commands in the GitLab CI example won't execute as shell commands without explicitly clearing the ENTRYPOINT.
The documented solution is to add entrypoint: [""] to the image configuration, as shown in my original suggestion. If there's a different concern about the VERSION variable in another part of the documentation, I'd be happy to discuss that separately.
Would you like to address the GitLab CI ENTRYPOINT issue, or would you prefer to handle this differently?
🧠 Learnings used
Learnt from: david-waltermire
Repo: metaschema-framework/oscal-cli PR: 228
File: src/site/markdown/guides/validating-oscal.md.vm:0-0
Timestamp: 2026-01-10T23:52:11.139Z
Learning: In oscal-cli, the generic `validate` command uses the complete OSCAL schema (oscal-complete_schema.xsd/json) which includes all OSCAL document types including Mapping. Document types don't require dedicated command directories if they're supported through the generic validation path.
Learnt from: david-waltermire
Repo: metaschema-framework/oscal-cli PR: 228
File: src/site/markdown/index.md.vm:0-0
Timestamp: 2026-01-11T15:57:01.784Z
Learning: In oscal-cli site documentation (src/site/markdown/index.md.vm), the CONTRIBUTING.md link intentionally references the `develop` branch (not HEAD or main) because CONTRIBUTING.md is maintained on develop and that's where contributions are made. This ensures users see the correct contribution guidelines.
- Restore Mapping Collection examples in validation and conversion guides (Mapping is supported in oscal-complete schema) - Add Mapping Collection to document types table in CLI reference - Add claude-plugins link in claude-integration.md.vm
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
In @src/site/markdown/guides/cli-reference.md.vm:
- Around line 206-220: Update the wording in the "OSCAL Document Types" section:
replace the phrase "root element" with a neutral term such as "root name /
top-level object" (or "root name/top-level object") in the section header text
and the explanatory sentence, and ensure the table header or surrounding
sentence reflects the new phrasing so it applies to XML, JSON, and YAML equally
(refer to the "OSCAL Document Types" heading and the sentence "The CLI
automatically detects the document type by examining the root element").
- Around line 5-61: Update the docs to reflect that the metapath command is a
subcommand of metaschema: change any top-level usage like "oscal-cli metapath
eval" to "oscal-cli metaschema metapath eval" (including all examples and
headings) and group the metapath documentation under the metaschema command
section; also update the Exit Codes table to reference the actual ExitCode enum
names (OK / FAIL / INVALID_ARGUMENTS) and ensure the numeric mappings (0 / 1 /
2) shown correspond to those enum values in the metaschema framework.
In @src/site/markdown/guides/converting-formats.md.vm:
- Around line 7-16: Update the sentence that claims conversions occur "without
data loss" to clarify it only guarantees preservation of model content (the
OSCAL data semantics), and explicitly state that comments, whitespace, and
formatting (e.g., YAML/JSON/XML comments and original
whitespace/ordering/indentation) are not preserved across conversions; replace
the current sentence in the converting-formats guide where "without data loss"
appears with this clarified wording so readers understand comments/formatting
are not retained.
- Around line 150-169: The batch Docker example mixes invoking the image's
default CLI (convert) with a separate shell loop using sh -c but doesn't
override the image entrypoint, so the sh -c command won't run as written; update
the second docker run to override the entrypoint (add --entrypoint sh) and then
run the shell loop that calls the image's oscal-cli convert inside the loop (or
alternatively keep the entrypoint and run a docker-for-each on the host invoking
oscal-cli per file), ensuring you reference the image
ghcr.io/metaschema-framework/oscal-cli:latest and the sh -c loop that calls
convert.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
src/site/markdown/claude-integration.md.vmsrc/site/markdown/guides/cli-reference.md.vmsrc/site/markdown/guides/converting-formats.md.vmsrc/site/markdown/guides/validating-oscal.md.vm
🚧 Files skipped from review as they are similar to previous changes (2)
- src/site/markdown/claude-integration.md.vm
- src/site/markdown/guides/validating-oscal.md.vm
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2024-12-12T00:15:45.005Z
Learnt from: aj-stein-gsa
Repo: metaschema-framework/oscal-server PR: 44
File: .oscal/component.oscal.yaml:2-2
Timestamp: 2024-12-12T00:15:45.005Z
Learning: When reviewing OSCAL content in YAML format, validate general content quality aspects like UUID uniqueness across entities, in addition to OSCAL-specific validations.
Applied to files:
src/site/markdown/guides/converting-formats.md.vm
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Code
🔇 Additional comments (4)
src/site/markdown/guides/converting-formats.md.vm (2)
19-20: Verify whetherconvertactually “validates” vs “parses and fails if invalid”.
If it doesn’t run a full validation pass, consider softening this sentence to avoid over-promising behavior.
126-149: Nice use of#[[/]]#around shell snippets that contain$expansions.
This should prevent Velocity from trying to interpolate${...}/$1.src/site/markdown/guides/cli-reference.md.vm (2)
242-276: Verify container tags (latest,x.y.z,develop) and usage match what’s actually published.
Ifdevelopisn’t a published tag (or means something else), this section will mislead.
1-284: Structure and scannability look solid (tables + consistent sections).
| ## Global Options | ||
|
|
||
| These options work with any command and control the general behavior of the CLI: | ||
|
|
||
| | Option | Description | | ||
| |:-------|:------------| | ||
| | `--help`, `-h` | Show help for any command | | ||
| | `--version`, `-V` | Show version information | | ||
| | `--show-stack-trace` | Show detailed error information | | ||
| | `--quiet`, `-q` | Suppress non-essential output | | ||
|
|
||
| ## Commands | ||
|
|
||
| ### validate | ||
|
|
||
| Validate OSCAL documents for well-formedness and schema compliance. | ||
|
|
||
| ```bash | ||
| oscal-cli validate [options] <file> | ||
| ``` | ||
|
|
||
| **Arguments:** | ||
|
|
||
| | Argument | Description | | ||
| |:---------|:------------| | ||
| | `<file>` | Path or URL to OSCAL document | | ||
|
|
||
| **Options:** | ||
|
|
||
| | Option | Description | | ||
| |:-------|:------------| | ||
| | `--as=<format>` | Force input format: `xml`, `json`, `yaml` | | ||
|
|
||
| **Examples:** | ||
|
|
||
| ```bash | ||
| # Validate a JSON file | ||
| oscal-cli validate ssp.json | ||
|
|
||
| # Validate with explicit format | ||
| oscal-cli validate --as=json document.txt | ||
|
|
||
| # Validate remote file | ||
| oscal-cli validate https://example.com/catalog.json | ||
|
|
||
| # Validate with detailed errors | ||
| oscal-cli validate --show-stack-trace ssp.json | ||
| ``` | ||
|
|
||
| **Exit Codes:** | ||
|
|
||
| | Code | Meaning | | ||
| |:-----|:--------| | ||
| | 0 | Validation passed | | ||
| | 1 | Validation failed | | ||
| | 2 | Invalid arguments | | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
git ls-files | head -20Repository: metaschema-framework/oscal-cli
Length of output: 632
🏁 Script executed:
# Find the oscal-cli tool or related CLI implementation
find . -type f -name "*cli*" | grep -E "\.(py|java|sh|gradle|maven)" | head -20Repository: metaschema-framework/oscal-cli
Length of output: 56
🏁 Script executed:
# Check repository structure
ls -laRepository: metaschema-framework/oscal-cli
Length of output: 1487
🏁 Script executed:
# Explore src structure
find src -type f -name "*.java" | grep -i cli | head -20Repository: metaschema-framework/oscal-cli
Length of output: 1905
🏁 Script executed:
# Check if there's a built CLI in target/
ls -la target/ 2>/dev/null || echo "No target directory yet"Repository: metaschema-framework/oscal-cli
Length of output: 97
🏁 Script executed:
# Look for the main CLI file
find . -name "*.java" -type f | xargs grep -l "class.*Cli\|main.*String.*args" | head -10Repository: metaschema-framework/oscal-cli
Length of output: 217
🏁 Script executed:
# Check pom.xml for build info and executable configuration
head -100 pom.xmlRepository: metaschema-framework/oscal-cli
Length of output: 3552
🏁 Script executed:
# Read the main CLI file
cat -n src/main/java/dev/metaschema/oscal/tools/cli/core/CLI.java | head -150Repository: metaschema-framework/oscal-cli
Length of output: 4723
🏁 Script executed:
# Read ValidateCommand to check exit codes and options
cat -n src/main/java/dev/metaschema/oscal/tools/cli/core/commands/ValidateCommand.java | head -200Repository: metaschema-framework/oscal-cli
Length of output: 2647
🏁 Script executed:
# Look for shell-completion and metapath commands
find src/main/java -type f -name "*ShellCompletion*" -o -name "*Metapath*"Repository: metaschema-framework/oscal-cli
Length of output: 56
🏁 Script executed:
# Read the abstract validation command to see options and exit codes
cat -n src/main/java/dev/metaschema/oscal/tools/cli/core/commands/AbstractOscalValidationCommand.java | head -300Repository: metaschema-framework/oscal-cli
Length of output: 4959
🏁 Script executed:
# Search for metapath command
find src -type f -name "*.java" | xargs grep -l "metapath\|Metapath" | head -10Repository: metaschema-framework/oscal-cli
Length of output: 312
🏁 Script executed:
# Check what the ResolveCommand is actually called
cat -n src/main/java/dev/metaschema/oscal/tools/cli/core/commands/ResolveCommand.java | head -100Repository: metaschema-framework/oscal-cli
Length of output: 718
🏁 Script executed:
# Search for shell-completion command
find . -type f -name "*.java" | xargs grep -l "shell-completion\|ShellCompletion" | head -10Repository: metaschema-framework/oscal-cli
Length of output: 211
🏁 Script executed:
# Check the documentation file being reviewed to see what it claims
head -100 src/site/markdown/guides/cli-reference.md.vmRepository: metaschema-framework/oscal-cli
Length of output: 2272
🏁 Script executed:
# Search more comprehensively for metapath
rg "metapath" --type javaRepository: metaschema-framework/oscal-cli
Length of output: 2886
🏁 Script executed:
# Look for exit code constants
find src -type f -name "*.java" | xargs grep -i "exit.*code\|ExitCode" | grep -E "0|1|2" | head -20Repository: metaschema-framework/oscal-cli
Length of output: 56
🏁 Script executed:
# Check AbstractResolveCommand for resolve-profile options
cat -n src/main/java/dev/metaschema/oscal/tools/cli/core/commands/AbstractResolveCommand.java | head -150Repository: metaschema-framework/oscal-cli
Length of output: 6359
🏁 Script executed:
# Search for exit codes in metaschema framework or this project
find src -type f -name "*.java" | xargs grep -h "ExitCode\." | grep -E "(OK|ERROR|PROCESSING|INVALID|IO)" | sort -u | head -20Repository: metaschema-framework/oscal-cli
Length of output: 1246
🏁 Script executed:
# Look for the metaschema command to understand metapath structure
cat -n src/main/java/dev/metaschema/oscal/tools/cli/core/commands/metaschema/MetaschemaCommand.java | head -100Repository: metaschema-framework/oscal-cli
Length of output: 1125
🏁 Script executed:
# Check test file to see what commands are expected
cat -n src/test/java/dev/metaschema/oscal/tools/cli/core/CLITest.java | grep -A 2 -B 2 "metapath\|validate\|convert\|resolve"Repository: metaschema-framework/oscal-cli
Length of output: 7280
🏁 Script executed:
# Check AbstractConvertCommand for options
cat -n src/main/java/dev/metaschema/oscal/tools/cli/core/commands/AbstractOscalConvertCommand.java | head -150Repository: metaschema-framework/oscal-cli
Length of output: 3217
🏁 Script executed:
# Search for ExitCode enum definition in metaschema-java dependency
# First check if there are local references or if we need to look at dependencies
find . -type f -name "ExitCode.java"Repository: metaschema-framework/oscal-cli
Length of output: 56
🏁 Script executed:
# Check if there's a pom.xml that shows dependency versions
grep -A 5 "metaschema-java" pom.xml || grep -A 5 "metaschema" pom.xml | head -30Repository: metaschema-framework/oscal-cli
Length of output: 985
🏁 Script executed:
# Look at actual test to understand exit codes
grep -B 5 -A 5 "ExitCode\." src/test/java/dev/metaschema/oscal/tools/cli/core/CLITest.java | head -60Repository: metaschema-framework/oscal-cli
Length of output: 2754
🏁 Script executed:
# Check what other commands exist beyond what's documented
cat -n src/site/markdown/guides/cli-reference.md.vm | wc -lRepository: metaschema-framework/oscal-cli
Length of output: 77
🏁 Script executed:
# Read more of the documentation file
sed -n '1,284p' src/site/markdown/guides/cli-reference.md.vm | tail -150Repository: metaschema-framework/oscal-cli
Length of output: 3654
🏁 Script executed:
# Try to find ExitCode mapping in metaschema CLI processor
# Search for status code assignments
rg "getStatusCode\|statusCode.*=" --type java | head -20Repository: metaschema-framework/oscal-cli
Length of output: 56
🏁 Script executed:
# Check metaschema commands to understand metapath structure
rg "metapath\|Metapath" -A 5 -B 5 --type java | head -60Repository: metaschema-framework/oscal-cli
Length of output: 56
🏁 Script executed:
# Look for docker or container registry info
find . -name "Dockerfile*" -o -name "*.yml" -o -name "*.yaml" | grep -v ".git" | head -10Repository: metaschema-framework/oscal-cli
Length of output: 570
🏁 Script executed:
# Check for container registry configuration
cat Dockerfile.ci 2>/dev/null | head -50
cat Dockerfile.local 2>/dev/null | head -50Repository: metaschema-framework/oscal-cli
Length of output: 2670
🏁 Script executed:
# Check workflows for docker image publishing
find .github/workflows -type f -name "*.yml" -o -name "*.yaml" | xargs grep -l "docker\|container\|image" 2>/dev/nullRepository: metaschema-framework/oscal-cli
Length of output: 173
🏁 Script executed:
# Look at container workflow for published tags
cat .github/workflows/container.yml | head -100Repository: metaschema-framework/oscal-cli
Length of output: 3669
🏁 Script executed:
# Search for metaschema commands definition
find . -path "*/metaschema-framework/*" -prune -o -type f -name "*.java" -print | xargs grep -l "class MetaschemaCommands" 2>/dev/null || echo "Not found locally, checking imports"Repository: metaschema-framework/oscal-cli
Length of output: 109
🏁 Script executed:
# Check what metaschema imports say about available commands
rg "MetaschemaCommands" --type java -A 10 | head -50Repository: metaschema-framework/oscal-cli
Length of output: 5945
🏁 Script executed:
# Look for all command classes and their names
find src/main/java -type f -name "*Command.java" | xargs grep -h "getName\|COMMAND.*=" | head -40Repository: metaschema-framework/oscal-cli
Length of output: 882
🏁 Script executed:
# Check what the docker metadata action produces for branches
rg "develop\|type=ref,event=branch" .github/workflows/container.ymlRepository: metaschema-framework/oscal-cli
Length of output: 56
🏁 Script executed:
# Search for exit code numeric values - they must be mapped somewhere
rg "OK|FAIL|PROCESSING_ERROR|IO_ERROR|INVALID_ARGUMENTS|RUNTIME_ERROR" --type java | grep -E "=|getStatusCode" | head -20Repository: metaschema-framework/oscal-cli
Length of output: 56
🏁 Script executed:
# Check if MetaschemaCommands.COMMANDS includes metapath as a subcommand
# Since it's from metaschema-java, let's look at what commands are registered
cat -n src/main/java/dev/metaschema/oscal/tools/cli/core/commands/ListAllowedValuesCommand.java | head -50Repository: metaschema-framework/oscal-cli
Length of output: 2608
🏁 Script executed:
# Look at the test more carefully - does it show metapath as top-level or nested?
grep -B 5 -A 5 "metapath" src/test/java/dev/metaschema/oscal/tools/cli/core/CLITest.javaRepository: metaschema-framework/oscal-cli
Length of output: 317
🏁 Script executed:
# Check the entire lines around docker tag configuration
sed -n '38,45p' .github/workflows/container.ymlRepository: metaschema-framework/oscal-cli
Length of output: 437
🏁 Script executed:
# Determine exit code mapping - search for any constants or numeric values
rg "statusCode.*=|status.*code" --type java src/main/java | head -30Repository: metaschema-framework/oscal-cli
Length of output: 56
🏁 Script executed:
# Check if there's documentation about exit codes in README or other docs
find . -name "README*" -o -name "*.md" | head -5 | xargs grep -i "exit.*code" 2>/dev/null | head -10Repository: metaschema-framework/oscal-cli
Length of output: 56
🏁 Script executed:
# Most importantly, check the test to confirm metapath structure
grep -B 10 -A 10 "metapath.*eval\|metapath.*list" src/test/java/dev/metaschema/oscal/tools/cli/core/CLITest.javaRepository: metaschema-framework/oscal-cli
Length of output: 803
🏁 Script executed:
# Verify by checking if there are any direct metapath command implementations (not under metaschema)
find src/main/java -type f -name "*Metapath*Command*.java" -o -name "*metapath*Command*.java"Repository: metaschema-framework/oscal-cli
Length of output: 56
🏁 Script executed:
# Confirm the metapath command structure one more time
grep -r "metapath" src/test/java/dev/metaschema/oscal/tools/cli/core/CLITest.java | grep -E "new String\[\]|Arguments.of"Repository: metaschema-framework/oscal-cli
Length of output: 183
Move the metapath command under metaschema parent command.
The test suite confirms metapath is a subcommand of metaschema, not a top-level command. Update the documentation to show oscal-cli metaschema metapath eval instead of oscal-cli metapath eval. Examples in this section need the same correction.
Also verify the exit codes (0/1/2) match the actual ExitCode enum values (OK/FAIL/INVALID_ARGUMENTS) in the metaschema framework, as the numeric mapping is not visible in this codebase.
🤖 Prompt for AI Agents
In @src/site/markdown/guides/cli-reference.md.vm around lines 5 - 61, Update the
docs to reflect that the metapath command is a subcommand of metaschema: change
any top-level usage like "oscal-cli metapath eval" to "oscal-cli metaschema
metapath eval" (including all examples and headings) and group the metapath
documentation under the metaschema command section; also update the Exit Codes
table to reference the actual ExitCode enum names (OK / FAIL /
INVALID_ARGUMENTS) and ensure the numeric mappings (0 / 1 / 2) shown correspond
to those enum values in the metaschema framework.
There was a problem hiding this comment.
Easier said than done, @coderabbitai.
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check the CLI.java file to see how commands are registered
echo "=== CLI command registration ==="
cat src/main/java/dev/metaschema/oscal/tools/cli/core/CLI.java | grep -A 30 "registerCommands\|addCommandHandler"
echo -e "\n=== Check if metapath is top-level or under metaschema ==="
# Look for how MetaschemaCommands is added
rg "MetaschemaCommands|metaschema|metapath" src/main/java/dev/metaschema/oscal/tools/cli/core/CLI.java -A 3 -B 3
echo -e "\n=== Check actual command structure in tests ==="
# Get the test cases showing command invocation
grep -A 2 -B 2 "metapath\|metaschema" src/test/java/dev/metaschema/oscal/tools/cli/core/CLITest.java | head -40
Length of output: 3880
@aj-stein, I understand! Let me help clarify and offer more specific guidance.
The code confirms that metapath is indeed a subcommand of metaschema. The test case shows it's invoked as ["metaschema", "metapath", "list-functions"], and MetaschemaCommand is registered as a top-level command handler.
What needs to change in the documentation:
Currently, the doc shows (around line 98+):
### metapath
#### metapath evalThis should be restructured to:
### metaschema
The metaschema command provides access to Metaschema-related operations.
#### metaschema metapath
##### metaschema metapath evalKey changes:
- Add a
### metaschemasection (if not already present) - Nest
metapathunder it as#### metaschema metapath - Update all examples from
oscal-cli metapath eval→oscal-cli metaschema metapath eval - Update command syntax from
metapath eval [options]→metaschema metapath eval [options]
Would you like me to help identify the specific line ranges that need updating, or would you prefer to make these changes yourself? I can also search for all occurrences of "metapath" in the file to ensure we catch everything.
🧠 Learnings used
Learnt from: david-waltermire
Repo: metaschema-framework/oscal-cli PR: 228
File: src/site/markdown/guides/validating-oscal.md.vm:0-0
Timestamp: 2026-01-10T23:52:01.344Z
Learning: In oscal-cli, the generic `validate` command uses the complete OSCAL schema (oscal-complete_schema.xsd/json) which includes all OSCAL document types including Mapping. Document types don't require dedicated command directories if they're supported through the generic validation path.
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to **/metapath/**/*.java : Metapath is an implementation of XPath 3.1. Use the XPath 3.1 specification (https://www.w3.org/TR/xpath-31/) and XPath Functions 3.1 (https://www.w3.org/TR/xpath-functions-31/) as authoritative reference when implementing new functions, fixing bugs, or understanding error handling. Raise clarification before making changes if implementation differs from spec.
There was a problem hiding this comment.
@coderabbitai The CLI commands documented are correct. The oscal-cli uses Apache Commons CLI for command parsing and supports the commands shown (validate, convert, resolve-profile, shell-completion). These are verified against the actual CLI implementation.
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
echo "=== Full CLI reference documentation ==="
cat src/site/markdown/guides/cli-reference.md.vm
echo -e "\n=== CLI command registration ==="
cat src/main/java/dev/metaschema/oscal/tools/cli/core/CLI.java
echo -e "\n=== Search for metapath command handler ==="
find src/main/java -name "*Metapath*Command*.java" -o -name "MetaschemaCommand*.java" | head -10
echo -e "\n=== Check how metaschema commands are structured ==="
rg "class.*Command.*extends.*\{" --type java -A 5 src/main/java/dev/metaschema/oscal/tools/cli/core/commands/metaschema/ | head -50
Length of output: 10823
🏁 Script executed:
#!/bin/bash
echo "=== MetaschemaCommand implementation ==="
cat src/main/java/dev/metaschema/oscal/tools/cli/core/commands/metaschema/MetaschemaCommand.java
echo -e "\n=== Check if metapath command classes exist ==="
find src/main/java -type f -name "*etapath*.java"
echo -e "\n=== Verify test invocations ==="
grep -B 2 -A 2 "metapath\|metaschema" src/test/java/dev/metaschema/oscal/tools/cli/core/CLITest.java
Length of output: 1544
@david-waltermire, thank you for the clarification! You're absolutely right that validate, convert, resolve-profile, and shell-completion are correct as top-level commands—I can confirm those are properly registered in CLI.java.
However, I'd like to clarify the specific concern about metapath. Based on the code analysis:
-
CLI registration (CLI.java):
MetaschemaCommandis registered as a parent command, but there's no separateMetapathCommandregistered at the top level. -
MetaschemaCommand implementation: It's an
AbstractParentCommandthat loads subcommands fromMetaschemaCommands.COMMANDS(from the metaschema-java framework):public MetaschemaCommand() { MetaschemaCommands.COMMANDS.forEach(this::addCommandHandler); }
-
Test evidence (CLITest.java): The test invokes metapath as:
new String[] { "metaschema", "metapath", "list-functions" }
-
Documentation (cli-reference.md.vm, line 143): Shows metapath as a top-level command:
### metapath ... oscal-cli metapath eval [options] -e <expression> <file>
Should the documentation show oscal-cli metaschema metapath eval instead of oscal-cli metapath eval? Or is there command aliasing that makes both work? I want to make sure the documentation accurately reflects the actual CLI usage.
🧠 Learnings used
Learnt from: david-waltermire
Repo: metaschema-framework/oscal-cli PR: 228
File: src/site/markdown/guides/validating-oscal.md.vm:0-0
Timestamp: 2026-01-10T23:52:11.139Z
Learning: In oscal-cli, the generic `validate` command uses the complete OSCAL schema (oscal-complete_schema.xsd/json) which includes all OSCAL document types including Mapping. Document types don't require dedicated command directories if they're supported through the generic validation path.
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to **/metapath/**/*.java : Metapath is an implementation of XPath 3.1. Use the XPath 3.1 specification (https://www.w3.org/TR/xpath-31/) and XPath Functions 3.1 (https://www.w3.org/TR/xpath-functions-31/) as authoritative reference when implementing new functions, fixing bugs, or understanding error handling. Raise clarification before making changes if implementation differs from spec.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java/dev/metaschema/core/datatype/package-info.java:52-52
Timestamp: 2026-01-05T18:03:33.537Z
Learning: In metaschema-framework/metaschema-java, CLAUDE.md is the canonical coding-guidelines document and now specifies dev.metaschema.* as the Java package convention (updated in PR #618).
Learnt from: david-waltermire
Repo: metaschema-framework/oscal-cli PR: 228
File: src/site/markdown/index.md.vm:0-0
Timestamp: 2026-01-11T15:57:01.784Z
Learning: In oscal-cli site documentation (src/site/markdown/index.md.vm), the CONTRIBUTING.md link intentionally references the `develop` branch (not HEAD or main) because CONTRIBUTING.md is maintained on develop and that's where contributions are made. This ensures users see the correct contribution guidelines.
- Add mkdir -p before shell completion install commands - Fix Quick Start with explicit VERSION variable - Escape Velocity tokens in CI snippets using #[[...]]# - Use branch-agnostic HEAD in CONTRIBUTING.md link
aj-stein
left a comment
aj-stein
left a comment
There was a problem hiding this comment.
Aside from heckling CodeRabbit, this PR is an amazing contribution, @david-waltermire, excellent work!
|
|
||
| ```bash | ||
| # macOS | ||
| export JAVA_HOME=$(/usr/libexec/java_home -v 17) |
There was a problem hiding this comment.
Non-blocking: Just a note I think java_home is specific to certain Java distributions or installation methods, because I do not have that with WSL2 and using the official Temurin release through asdf, so I am not sure it is universal.
| ## Global Options | ||
|
|
||
| These options work with any command and control the general behavior of the CLI: | ||
|
|
||
| | Option | Description | | ||
| |:-------|:------------| | ||
| | `--help`, `-h` | Show help for any command | | ||
| | `--version`, `-V` | Show version information | | ||
| | `--show-stack-trace` | Show detailed error information | | ||
| | `--quiet`, `-q` | Suppress non-essential output | | ||
|
|
||
| ## Commands | ||
|
|
||
| ### validate | ||
|
|
||
| Validate OSCAL documents for well-formedness and schema compliance. | ||
|
|
||
| ```bash | ||
| oscal-cli validate [options] <file> | ||
| ``` | ||
|
|
||
| **Arguments:** | ||
|
|
||
| | Argument | Description | | ||
| |:---------|:------------| | ||
| | `<file>` | Path or URL to OSCAL document | | ||
|
|
||
| **Options:** | ||
|
|
||
| | Option | Description | | ||
| |:-------|:------------| | ||
| | `--as=<format>` | Force input format: `xml`, `json`, `yaml` | | ||
|
|
||
| **Examples:** | ||
|
|
||
| ```bash | ||
| # Validate a JSON file | ||
| oscal-cli validate ssp.json | ||
|
|
||
| # Validate with explicit format | ||
| oscal-cli validate --as=json document.txt | ||
|
|
||
| # Validate remote file | ||
| oscal-cli validate https://example.com/catalog.json | ||
|
|
||
| # Validate with detailed errors | ||
| oscal-cli validate --show-stack-trace ssp.json | ||
| ``` | ||
|
|
||
| **Exit Codes:** | ||
|
|
||
| | Code | Meaning | | ||
| |:-----|:--------| | ||
| | 0 | Validation passed | | ||
| | 1 | Validation failed | | ||
| | 2 | Invalid arguments | | ||
|
|
There was a problem hiding this comment.
Easier said than done, @coderabbitai.
aj-stein
left a comment
aj-stein
left a comment
There was a problem hiding this comment.
Sorry seems I didn't approve with last one, just commented.
david-waltermire
merged commit 76ba935
into
metaschema-framework:develop
2 participants
Summary
Test plan
mvn sitebuilds without errorsSummary by CodeRabbit
Documentation
Style
Chores
Site
✏️ Tip: You can customize this high-level summary in your review settings.