Skip to content

Allow setting output file path for sequence-diagram[-diff] - #2433

Open
dividedmind wants to merge 3 commits into
mainfrom
fix/sequence-diagram-output
Open

dividedmind wants to merge 3 commits into
mainfrom
fix/sequence-diagram-output

Conversation

@dividedmind

Copy link
Copy Markdown
Collaborator
  • Fix an issue where an unknown flag for the CLI wouldn't prevent execution.
  • Allow specifying output file path in sequence-diagram[-diff] commands.

Fixes #2431

The CLI's custom yargs failure handler printed the usage and the error,
then returned. yargs takes a returning failure handler to mean the
failure is handled, and goes on to run the command. Strict mode would
report an unknown option such as `-o`, and the command then ran anyway
and ignored it, which is easy to miss.

Throw from the handler instead to stop yargs before the command runs,
and catch the error at the top level so it doesn't surface as a crash.
Exiting the process there instead would cut off the usage text when
stdout is a pipe.

Assisted-by: Claude:claude-opus-5-5
@dividedmind
dividedmind requested review from kgilpin and a balanced review from Copilot November 16, 2026 16:38
@dividedmind dividedmind self-assigned this Nov 16, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The implicit JSON sidecar can overwrite the source AppMap recording before PNG rendering, silently destroying the input even when the requested image path is different.

1 open issue
What changed in this PR

Adds explicit output filenames to the sequence-diagram CLI commands, allowing base and head diagrams to share a directory without sharing a filename. It also stops commands from running after argument validation fails.

Changes:

  • Adds --output / -o, mutually exclusive with --output-dir.
  • Supports named outputs for single AppMaps and file-to-file diffs, including parent-directory creation.
  • Adds tests for named outputs, invalid input combinations, and unknown CLI options.
File Description
packages/​cli/​tests/​unit/​sequenceDiagramDiff.spec.ts Tests named diffs, default filenames, and directory restrictions.
packages/​cli/​tests/​unit/​sequenceDiagram.spec.ts Tests named diagram output and multiple-input rejection.
packages/​cli/​tests/​unit/​cliValidation.spec.ts Checks that unknown options prevent execution.
packages/​cli/​src/​cmds/​sequenceDiagramHandler.ts Handles named outputs and derived PNG sidecar paths.
packages/​cli/​src/​cmds/​sequenceDiagramDiffHandler.ts Writes named diffs and rejects named output for directory comparisons.
packages/​cli/​src/​cmds/​sequenceDiagramDiff.ts Defines the diff output option and conflict.
packages/​cli/​src/​cmds/​sequenceDiagram.ts Defines the diagram output option and conflict.
packages/​cli/​src/​cli.ts Stops dispatch when argument validation fails.

Review effort: Balanced

sequence-diagram named its output after the input AppMap, so diagrams
of the same test recorded on two revisions overwrote each other unless
each went to its own --output-dir. --output (-o) names the file
instead, for a single AppMap. For PNG output, the intermediate JSON
diagram goes to a temporary directory: written beside the PNG, it
could overwrite another file, such as the input AppMap when the PNG is
named recording.appmap.png.

Assisted-by: Claude:claude-opus-5-5
sequence-diagram-diff always wrote diff.<ext> into --output-dir, so
each diff needed a directory of its own. --output (-o) names the file
instead when comparing two diagram files; it is rejected when
comparing directories, which produce a diff per diagram.

--output-dir loses its yargs default of '.', which would otherwise
conflict with every --output; the handler falls back to '.' itself.
Also await writing the diff, which the handler didn't, so the file is
there once the command resolves.

Assisted-by: Claude:claude-opus-5-5
@dividedmind
dividedmind force-pushed the fix/sequence-diagram-output branch from bf104ba to 5d31a5e Compare November 16, 2026 17:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

CLI: sequence-diagram has no output-file flag, so two recordings of the same test overwrite each other

2 participants