Skip to content

Add findings-to-fixes documentation - #19

Merged
dsoumis merged 3 commits into
web-servers:mainfrom
milansamuel609:feat/findings-to-fixes
Aug 12, 2026
Merged

Add findings-to-fixes documentation#19
dsoumis merged 3 commits into
web-servers:mainfrom
milansamuel609:feat/findings-to-fixes

Conversation

@milansamuel609

@milansamuel609 milansamuel609 commented Aug 6, 2026

Copy link
Copy Markdown
Collaborator

Hi @dsoumis,

This PR adds the Findings-to-Fixes documentation for jws-diag.

Summary

The guide includes:

  • An overview of the validation workflow and severity levels.
  • Instructions for running validation in both the default human-readable format and JSON format.
  • Example validation outputs for both human-readable and JSON formats.
  • A complete mapping of all implemented validation rules to their:
    • Category
    • Severity
    • Description
    • Source file
    • Recommended resolution
  • Guidance for verifying that reported findings have been resolved.
  • Documentation describing how validation results are included in the generated support bundle (validation-results.json).
  • Additional notes covering runtime-dependent findings and the read-only behavior of the validation engine.

Verification

  • Verified that the document renders correctly on GitHub (headings, tables, and code blocks).
  • Verified that all command examples and example outputs are consistent with the current implementation.

Clarification

I have a couple of questions regarding the documentation:

  • Since the jws-diag bundle command is now implemented, would you prefer a dedicated guide for it (similar to the Findings-to-Fixes Guide), or is the current level of documentation sufficient?

  • Would you also recommend adding references to the documentation in the project's README.md, or would you prefer to keep the README.md minimal?

Comment thread docs/findings-to-fixes.md
@milansamuel609

Copy link
Copy Markdown
Collaborator Author

Hi @dsoumis,

Along with the exit codes table, I also made a few additional documentation improvements around the validation output.

  • Added explanations for the human-readable and JSON output formats, including what the findings, summary, and exitCode fields represent.
  • Also documented the severity levels and their meanings.

@dsoumis
dsoumis merged commit 76f9d1d into web-servers:main Aug 12, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants