Commands

Each block below is the exact --help text of the binary this page was generated from, so a flag documented here is a flag the tool has, and a flag that is missing here does not exist.

ocomment with no command is ocomment check, and a command with no path is the current directory. Findings, patches, listings, and every machine format go to standard output; the run summary and every note go to standard error, so ocomment diff src > fix.patch keeps the patch clean.

check exits 0 when nothing removable was found, 1 when removable comments were reported or a diff was printed, and 2 for an invalid source, configuration, plugin, or I/O failure.

The Policy and Output option groups are global. Every command that can act on them accepts them, which is why the same two groups appear under most of the blocks below. ocomment man renders the same material as a manual page.

Contents

• ocomment
• ocomment check
• ocomment fix
• ocomment diff
• ocomment scan
• ocomment strip
• ocomment lsp
• ocomment init
• ocomment config
• ocomment languages
• ocomment profiles
• ocomment plugin
• ocomment plugin add
• ocomment plugin remove
• ocomment plugin list
• ocomment plugin update
• ocomment plugin verify
• ocomment plugin new
• ocomment completions
• ocomment coverage
• ocomment tags
• ocomment ratchet
• ocomment hook
• ocomment selftest
• ocomment doctor
• ocomment man

ocomment

$ ocomment --help
OComment scans source bytes without requiring UTF-8 and reports or removes comment tokens. The default policy removes ordinary comments and keeps the ones something else depends on: documentation, licence notices, tool and language directives, shebangs and encoding lines. Rewrites are prepared and committed as one rollback-backed transaction.

Usage: ocomment [OPTIONS] [PATH]...
       ocomment <COMMAND>

Commands:
  check        Report removable comments (default command)
  fix          Remove comments in place through an atomic, rollback-backed transaction
  diff         Print a unified diff of the changes fix would make
  scan         List every comment with its kind, disposition and byte span
  strip        Read source on stdin and write the stripped result to stdout
  lsp          Run the LSP 3.18 server over stdio
  init         Write a starter .ocomment.toml or Lefthook configuration
  config       Show, locate, explain, or export the resolved configuration
  languages    List built-in languages, extensions, and dialects
  profiles     List the declarative profiles that read files no built-in language does
  plugin       Manage sandboxed WASM scanner plugins
  completions  Generate shell completions
  coverage     Report which files a walk scanned and which it passed over, and why
  tags         Count the tags this tree's comments open with, against the ones it allows
  ratchet      Check the tree against its ledger, or record the tree in one
  hook         Answer an agent editing hook in the host's own protocol
  selftest     Re-run the shared corpus against this binary and report any disagreement
  doctor       Diagnose the environment (config, git, plugins, tools)
  man          Render the roff manual page to stdout
  help         Print this message or the help of the given subcommand(s)

Arguments:
  [PATH]...
          Files or directories to check; `-` reads standard input (default: current directory)

Options:
      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

EXIT STATUS
  0  Nothing removable was found and every requested change was applied.
  1  Removable comments were reported, a diff was printed, `--tidy` left a
     removal for you, or a staged fix rewrote the index.
  2  Invalid source, configuration, plugin, or I/O failure.

FILES
  .ocomment.toml   Project configuration, merged over the user file.
  .ocommentignore  Extra ignore patterns honoured by repository walks.
  .ocomment.lock   Pinned digests of the installed WASM scanner plugins.
  $XDG_CONFIG_HOME/ocomment/config.toml
                   User configuration, merged over the built-in defaults.

EXAMPLES
  ocomment
      Check the current directory and report removable comments.
  ocomment fix --policy all --layout compact src
      Remove every comment under src and close the gaps it leaves.
  ocomment fix --tidy --staged
      Reflow what the style rules decide and leave every removal to you.
  ocomment strip --language rust < before.rs > after.rs
      Strip one file from standard input to standard output.

SEE ALSO
  The complete schemas and guides are available in the OComment repository.

ocomment check

$ ocomment check --help
Report removable comments (default command)

Usage: ocomment check [OPTIONS] [PATH]...

Arguments:
  [PATH]...
          Files or directories to process; `-` reads standard input (default: current directory)

Options:
      --staged
          Read and update Git index blobs rather than treating the working tree as the source

      --index-only
          With `--staged`, do not attempt a uniquely mappable working-tree update

      --base <REV>
          Check only the working-tree files that differ from this revision's merge base with HEAD

      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment fix

$ ocomment fix --help
Remove comments in place through an atomic, rollback-backed transaction

Usage: ocomment fix [OPTIONS] [PATH]...

Arguments:
  [PATH]...
          Files or directories to rewrite (default: current directory)

Options:
      --staged
          Read and update Git index blobs rather than treating the working tree as the source

      --index-only
          With `--staged`, do not attempt a uniquely mappable working-tree update

      --base <REV>
          Check only the working-tree files that differ from this revision's merge base with HEAD

      --dry-run
          Print the patch `fix` would apply and write nothing

      --tidy
          Apply what the style rules rewrote and leave every removal to you.
          
          The removals are still reported and the run still exits 1 for them; what changes is that none of them reaches the file. This is the half a machine can finish on its own, which is what makes it the half a commit hook may run unattended.

  -i, --interactive
          Ask about each comment in turn and remove only the accepted ones.
          
          The index has no working-tree line to show a hunk from, `--dry-run` writes nothing whatever the answers were, and `-q` asks for a run with no commentary at all. None of the three can also be a conversation.

      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment diff

$ ocomment diff --help
Print a unified diff of the changes fix would make

Usage: ocomment diff [OPTIONS] [PATH]...

Arguments:
  [PATH]...
          Files or directories to process; `-` reads standard input (default: current directory)

Options:
      --staged
          Read and update Git index blobs rather than treating the working tree as the source

      --index-only
          With `--staged`, do not attempt a uniquely mappable working-tree update

      --base <REV>
          Check only the working-tree files that differ from this revision's merge base with HEAD

      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment scan

$ ocomment scan --help
List every comment with its kind, disposition and byte span

Usage: ocomment scan [OPTIONS] [PATH]...

Arguments:
  [PATH]...
          Files or directories to process; `-` reads standard input (default: current directory)

Options:
      --staged
          Read and update Git index blobs rather than treating the working tree as the source

      --index-only
          With `--staged`, do not attempt a uniquely mappable working-tree update

      --base <REV>
          Check only the working-tree files that differ from this revision's merge base with HEAD

      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment strip

$ ocomment strip --help
Read source on stdin and write the stripped result to stdout

Usage: ocomment strip [OPTIONS]

Options:
      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment lsp

$ ocomment lsp --help
Run the LSP 3.18 server over stdio

Usage: ocomment lsp [OPTIONS]

Options:
      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment init

$ ocomment init --help
Write a starter .ocomment.toml or Lefthook configuration

Usage: ocomment init [OPTIONS] [KIND]

Arguments:
  [KIND]
          Which starter file to write
          
          [default: config]
          [possible values: config, lefthook]

Options:
      --tidy
          For the Lefthook hook, run `fix --tidy` instead of `check`.
          
          The hook writes what the style rules settle and leaves every removal reported and unapplied, which is the shape a gate on every commit wants.

      --fix
          For the Lefthook hook, run `fix` instead of `check`.
          
          The removals too, including the comments above them that were worth keeping. `--tidy` is the one that writes nothing a reader would have wanted back.

      --force
          Replace the file if it already exists

      --stdout
          Print the template to standard output and write no file

      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment config

$ ocomment config --help
Show, locate, explain, or export the resolved configuration

Usage: ocomment config [OPTIONS] [ACTION]

Arguments:
  [ACTION]
          Which view of the resolved configuration to print
          
          [default: show]
          [possible values: show, locate, explain, schema]

Options:
      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment languages

$ ocomment languages --help
List built-in languages, extensions, and dialects

Usage: ocomment languages [OPTIONS]

Options:
      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment profiles

$ ocomment profiles --help
List the declarative profiles that read files no built-in language does

Usage: ocomment profiles [OPTIONS]

Options:
      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment plugin

$ ocomment plugin --help
Manage sandboxed WASM scanner plugins

Usage: ocomment plugin [OPTIONS] <COMMAND>

Commands:
  add     Install a plugin and pin its digest in .ocomment.lock
  remove  Uninstall a plugin and drop its lock entry
  list    List the installed plugins and their pinned digests
  update  Re-fetch plugins and refresh their pinned digests
  verify  Check installed plugins against their pinned digests
  new     Scaffold a new plugin crate from the scanner WIT world
  help    Print this message or the help of the given subcommand(s)

Options:
      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment plugin add

$ ocomment plugin add --help
Install a plugin and pin its digest in .ocomment.lock

Usage: ocomment plugin add [OPTIONS] <SOURCE>

Arguments:
  <SOURCE>
          Path or URL of the WASM component to install

Options:
      --name <NAME>
          Name to register the plugin under (default: the file stem)

      --sha256 <HEX>
          Expected SHA-256 digest of the component, verified before install

      --identity <IDENTITY>
          Publisher identity recorded alongside the pinned digest

      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment plugin remove

$ ocomment plugin remove --help
Uninstall a plugin and drop its lock entry

Usage: ocomment plugin remove [OPTIONS] <NAME>

Arguments:
  <NAME>
          Name of the plugin to remove

Options:
      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment plugin list

$ ocomment plugin list --help
List the installed plugins and their pinned digests

Usage: ocomment plugin list [OPTIONS]

Options:
      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment plugin update

$ ocomment plugin update --help
Re-fetch plugins and refresh their pinned digests

Usage: ocomment plugin update [OPTIONS] [NAME]

Arguments:
  [NAME]
          Name of the plugin to update (default: all of them)

Options:
      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment plugin verify

$ ocomment plugin verify --help
Check installed plugins against their pinned digests

Usage: ocomment plugin verify [OPTIONS] [NAME]

Arguments:
  [NAME]
          Name of the plugin to verify (default: all of them)

Options:
      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment plugin new

$ ocomment plugin new --help
Scaffold a new plugin crate from the scanner WIT world

Usage: ocomment plugin new [OPTIONS] <PATH>

Arguments:
  <PATH>
          Directory to create the plugin crate in

Options:
      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment completions

$ ocomment completions --help
Generate shell completions

Usage: ocomment completions [OPTIONS] <SHELL>

Arguments:
  <SHELL>
          Shell whose completion script is written to stdout
          
          [possible values: bash, elvish, fish, powershell, zsh]

Options:
      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment coverage

$ ocomment coverage --help
Report which files a walk scanned and which it passed over, and why

Usage: ocomment coverage [OPTIONS] [PATH]...

Arguments:
  [PATH]...
          Files or directories to process; `-` reads standard input (default: current directory)

Options:
      --staged
          Read and update Git index blobs rather than treating the working tree as the source

      --index-only
          With `--staged`, do not attempt a uniquely mappable working-tree update

      --base <REV>
          Check only the working-tree files that differ from this revision's merge base with HEAD

      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment tags

$ ocomment tags --help
Count the tags this tree's comments open with, against the ones it allows

Usage: ocomment tags [OPTIONS] [PATH]...

Arguments:
  [PATH]...
          Files or directories to process; `-` reads standard input (default: current directory)

Options:
      --staged
          Read and update Git index blobs rather than treating the working tree as the source

      --index-only
          With `--staged`, do not attempt a uniquely mappable working-tree update

      --base <REV>
          Check only the working-tree files that differ from this revision's merge base with HEAD

      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment ratchet

$ ocomment ratchet --help
Check the tree against its ledger, or record the tree in one

Usage: ocomment ratchet [OPTIONS] [PATH]...

Arguments:
  [PATH]...
          Files or directories to process; `-` reads standard input (default: current directory)

Options:
      --update
          Rewrite the ledger to match the tree, rather than checking against it

      --staged
          Read and update Git index blobs rather than treating the working tree as the source

      --index-only
          With `--staged`, do not attempt a uniquely mappable working-tree update

      --base <REV>
          Check only the working-tree files that differ from this revision's merge base with HEAD

      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment hook

$ ocomment hook --help
Answer an agent editing hook in the host's own protocol

Usage: ocomment hook [OPTIONS] <SURFACE>

Arguments:
  <SURFACE>
          Which host's hook protocol is spoken on standard input and output

          Possible values:
          - claude-code: Claude Code's `PreToolUse` and `PostToolUse` hooks

Options:
      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment selftest

$ ocomment selftest --help
Re-run the shared corpus against this binary and report any disagreement

Usage: ocomment selftest [OPTIONS]

Options:
      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment doctor

$ ocomment doctor --help
Diagnose the environment (config, git, plugins, tools)

Usage: ocomment doctor [OPTIONS]

Options:
      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file

ocomment man

$ ocomment man --help
Render the roff manual page to stdout

Usage: ocomment man [OPTIONS]

Options:
      --config <FILE>
          Read this configuration file instead of discovering `.ocomment.toml`

  -h, --help
          Print help (see a summary with '-h')

Policy:
      --policy <POLICY>
          Which classes of comment the run is allowed to remove

          Possible values:
          - none:         Remove nothing. Every comment is kept, which is the mode for a repository that wants the style rules and not the removals
          - conservative: Remove ordinary comments; keep documentation, licence notices, directives, shebangs and encoding lines (was `legal`)
          - standard:     Like conservative, and remove documentation, licence and copyright comments too (was `safe`)
          - all:          Remove every comment except shebangs, encoding lines and the directives the language itself reads

      --layout <LAYOUT>
          How the bytes left behind by a removed comment are laid out

          Possible values:
          - lines:   Keep the line structure and separate tokens that would otherwise join
          - columns: Pad each removed comment so the following columns do not shift
          - compact: Drop lines that held only a removed comment, the whitespace it left behind, and any blank line the removal would otherwise have added to a run

      --language <LANGUAGE>
          Force this language instead of detecting it from path and contents

          Possible values:
          - rust:       Rust source files
          - ocaml:      OCaml implementation and interface files
          - c:          C source and header files
          - cpp:        C++ source and header files
          - go:         Go source files
          - java:       Java source files, including Unicode escape translation
          - javascript: JavaScript modules and scripts, including JSX
          - typescript: TypeScript modules and scripts, including TSX
          - python:     Python source and stub files
          - shell:      POSIX sh, Bash, and zsh scripts
          - html:       HTML documents, including nested script and style elements
          - css:        CSS stylesheets
          - jsonc:      JSON with comments, including JSON5
          - sql:        SQL for every supported database dialect
          - kotlin:     Kotlin source and script files
          - toml:       TOML documents, including the lock files written in it
          - lua:        Lua chunks and LuaRocks rockspecs
          - yaml:       YAML documents, including the tool configurations written in it
          - php:        PHP scripts and templates; the inline HTML around the tags is content
          - ruby:       Ruby scripts, gem manifests, and the project files named after their tool
          - zig:        Zig source files and Zig Object Notation data
          - r:          R scripts and the `.Rprofile` an R session sources at start-up
          - dart:       Dart source files, whose block comments nest
          - swift:      Swift source files, whose block comments nest and whose `#/../#` is a regex
          - csharp:     C# source and script files, whose `#` lines are preprocessor directives
          - scala:      Scala source and script files, whose block comments nest and whose XML literals are opaque
          - vue:        Vue single-file components, whose templates are HTML with `{{ ... }}` code
          - svelte:     Svelte components, whose templates are HTML with `{ ... }` code
          - markdown:   Markdown documents, whose fenced code blocks are scanned as their named languages
          - perl:       Perl scripts and modules, whose quote words and regexes hide a `#`

      --dialect <DIALECT>
          Force this dialect of the selected language

          Possible values:
          - standard:      The default lexical rules of the language
          - jsx:           JavaScript with JSX elements
          - tsx:           TypeScript with JSX elements
          - objective-c:   Objective-C extensions to C
          - objective-cpp: Objective-C++ extensions to C++
          - gnu-c:         GNU extensions to C
          - gnu-cpp:       GNU extensions to C++
          - cuda:          CUDA extensions to C++
          - posix-sh:      The POSIX shell command language
          - bash53:        Bash 5.3
          - zsh:           The Z shell
          - postgresql:    PostgreSQL, with dollar-quoted bodies
          - mysql:         MySQL, including its executable versioned comments
          - sqlite:        SQLite
          - t-sql:         Microsoft Transact-SQL
          - oracle:        Oracle SQL and PL/SQL
          - scss:          SCSS
          - sass:          The indentation-based Sass syntax

      --keep-kind <KIND>
          Comma-separated comment kinds to protect on top of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --remove-kind <KIND>
          Comma-separated comment kinds to remove regardless of the policy

          Possible values:
          - line:            An ordinary comment running to the end of the line
          - block:           An ordinary delimited comment
          - doc-line:        A documentation comment running to the end of the line
          - doc-block:       A delimited documentation comment
          - directive:       A tool or language directive such as a pragma or lint control
          - license:         A licence or copyright notice
          - html-comment:    A DOM-observable HTML comment
          - shebang:         The interpreter line starting an executable script
          - encoding:        A source encoding declaration
          - optimizer-hint:  A compiler or database optimizer hint
          - version-comment: A MySQL versioned comment that the server executes
          - load-bearing:    A directive the language or its build reads as part of the program, such as `//go:build`

      --include-generated
          Scan files another tool writes: lock files, recorded seeds, generated output

      --deny-skipped[=<REASON>]
          Fail when a file was passed over for one of these reasons, rather than noting it. With no reason given, the two that are holes rather than decisions: unknown-language and unreadable

          Possible values:
          - unknown-language:  Nothing here reads this kind of file: no built-in language claimed it, and no profile or plugin was routed to it
          - unreadable:        The file could not be read at all
          - too-large:         Past `[files] max_size`
          - binary:            A NUL byte in the first bytes read
          - language-disabled: Turned off by `[languages.<name>] enabled = false`

      --force-invalid
          Edit a file that failed to scan, outside the bytes the failure covers. What the scanner calls a comment inside them is a guess: the code under an unterminated block opener is reported as part of it and is not a comment

      --force-protected
          Remove protected comments: shebangs, encoding lines, and the directives the language or its build reads

Output:
      --format <FORMAT>
          Output encoding

          Possible values:
          - human:  Every finding on one line, in the `path:line:column:` stream a pipeline greps. Kept because a pipeline written against it should not have to be rewritten, and because one line per finding is the right shape for counting even when it is the wrong shape for deciding
          - review: The findings grouped by the decision each one asks for, with the edit beside it. The default everywhere, terminal or pipe
          - json
          - jsonl
          - sarif
          - github
          - agent:  The report as an instruction, for a reader that is going to act on it
          
          [default: review]

      --color <WHEN>
          When to colour terminal output
          
          [default: auto]
          [possible values: auto, always, never]

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks for reported paths
          
          [default: auto]
          [possible values: auto, always, never]

      --no-preview
          Omit the comment text from human `check` and `scan` lines and from the JSON formats

      --annotation-level <LEVEL>
          The level `--format github` annotates a removable comment at (default: the run's exit status)

          Possible values:
          - error:   Annotate as an error, which fails a job that checks annotations
          - warning: Annotate as a warning
          - notice:  Annotate as a notice, which GitHub folds away beside an error

      --explain
          List every comment `check` and `scan` met and name the rule and setting behind each one

      --source-map
          Include the byte-for-byte map from the output back to the source in the JSON formats

      --trace <WHEN>
          Record how the run reached its verdicts, on standard error

          Possible values:
          - off:   Record nothing, and collect nothing to record
          - human: One line per step, for a person reading a terminal
          - json:  One JSON object per line, against `spec/trace.schema.json`
          
          [default: off]

      --progress <WHEN>
          When to draw the live scanning counter on standard error
          
          [default: auto]
          [possible values: auto, always, never]

  -j, --jobs <N>
          How many threads the run uses to walk, read and scan; 0 chooses one per core

      --summary <FILE>
          Also write the end-of-run counts to this file, as one JSON object

  -q, --quiet
          Drop the run summary and notes; the command's product (findings, patch, listing) is still written

  -v, --verbose
          Trace what is scanned and summarize every comment kind and skipped file