Optionally report help-url documentation in constraint validation output

[aj-stein-gsa]

User Story

Per discussion with @wandmagic a few days ago, it would be beneficial for metaschema-java to support, optionally and perhaps not provide it with default, to embed links to prop[@name="help-url"] content and encode it properly to make clickable links. That way, constraint violation output can be clicked on directly by developers when using the tool, separate of needing to load up SARIF when doing a quick development/debug loop cycle.

Note, per discussion with @wandmagic, we can do this strictly from SARIF output via oscal-cli, but this approach will make it more flexible and usable in a variety of different use cases.

Goals

• Make resolving error messages with CLI tooling fast and efficient
• Reduce the number of commands and steps need to retrieve the information during development, without need to open another file or tool

Dependencies

No response

Acceptance Criteria

• All website and readme documentation affected by the changes in this issue have been updated.
• A Pull Request (PR) is submitted that fully addresses the goals of this User Story. This issue is referenced in the PR.
• The CI-CD build process runs without any reported errors on the PR. This can be confirmed by reviewing that all checks have passed in the PR.

Revisions

No response

[wandmagic]

https://github.com/DefinitelyTyped/DefinitelyTyped/blob/4c8cf7d806e9fb71b42eb7b457313048a1ab88a7/types/sarif/index.d.ts#L1414 thankfully sarif has a helpuri in the spec for exactly this purpose

[david-waltermire]

The code for the help-uri is already in this library. See:

metaschema-java/databind-metaschema/src/main/java/gov/nist/secauto/metaschema/modules/sarif/SarifValidationHandler.java

Lines 570 to 573 in 964b845

	Set<String> helpUrls = constraint.getPropertyValues(SARIF_HELP_URL_KEY);
	if (!helpUrls.isEmpty()) {
	retval.setHelpUri(URI.create(helpUrls.stream().findFirst().get()));
	}

I am not sure what this issue is asking for and need some help understand better. Can you show what the library is doing that needs to be done differently, or not doing that needs to be added?

[aj-stein-gsa]

I am not sure what this issue is asking for and need some help understand better. Can you show what the library is doing that needs to be done differently, or not doing that needs to be added?

Separate of SARIF when metaschema-cli validate ... or metaschema-cli validate-content ... is executed, include the value of the help URL if defined with the constraint ID, Metapath target, and message. It is already in the SARIF output, but not in the stdout/stderr output in shell with clickable links.

[david-waltermire]

Ok. I understand now. I can adjust the logging to include the link in the stdout/stderr output. It is platform dependent if that link is clickable though.

[david-waltermire]

Right now the message format in metaschema-cli is:

[SEVERITY] [METAPATH] CONSTRAINT-ID: message

How should the help URL link be incorporated?

Maybe something like the following?

[SEVERITY] [METAPATH] CONSTRAINT-ID: message (HELP-URL)

[aj-stein-gsa]

Maybe something like the following?

[SEVERITY] [METAPATH] CONSTRAINT-ID: message (HELP-URL)

I like that approach, I am not sure if @wandmagic has a different opinion on it, but I am happy with that.

[wandmagic]

Maybe something like the following?
[SEVERITY] [METAPATH] CONSTRAINT-ID: message (HELP-URL)

I like that approach, I am not sure if @wandmagic has a different opinion on it, but I am happy with that.

yes this looks good