Skip to content

Reject --with-comments without --json or document that it has no effect #2

Description

@irl-dan

Environment

  • Margin 0.4.0
  • macOS 26.2 (build 25C56)
  • Apple silicon
  • Package: Margin-0.4.0-macOS-arm64.pkg
  • Package SHA-256: cb85c8f4bda5fa2c43fb775214d9ff5241d2143cf88d34088c3ea2dc975119a5

Summary

The read usage permits --with-comments without --json.
The command accepts this form.
The flag has no effect on human-readable output.
A user can believe that the output contains comments when it does not.

Reproduction steps

  1. Create a Markdown file.
  2. Add one comment.
margin comments add brief.md \
  --quote "The queue is the source of truth." \
  -m "What guarantees ordering during replay?" \
  --actor-type software \
  --actor-name clean-room-reviewer
  1. Confirm that the comment exists.
margin comments validate brief.md --pretty
  1. Read the command help.
margin read --help
  1. Run the documented command form.
margin read brief.md --with-comments

Actual behavior

The command exits with status 0.
The output is identical to margin read brief.md.
The output does not contain the comment snapshot.
The usage line permits --with-comments without --json.
The option description states that the flag applies to JSON output.

Expected behavior

The CLI must prevent silent flag loss.
It should reject --with-comments unless --json is present.
As an alternative, the help and usage can require --json for this option.

Acceptance criteria

  • margin read FILE --with-comments does not succeed silently.
  • The error identifies the required --json option.
  • The usage line shows the valid option combination.
  • The same behavior applies to the show and cat aliases.
  • Automated tests cover the invalid option combination.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions