feat: rename --container scan flag to --image (keep --container alias)

[bomly-guy]

What & why

--image is the more accurate, conventional term for scanning container images (matching docker, syft, grype). This renames the primary surface to --image everywhere a user touches it, while keeping every old "container" form working as a backwards-compatible alias — so existing scripts, CI, config files, env vars, and MCP clients keep working unchanged.

Surfaces renamed (all four), with aliases kept

Surface	Primary (new)	Alias kept (deprecated)
CLI flag	--image	--container (hidden from --help)
Env var	BOMLY_IMAGE	BOMLY_CONTAINER
YAML key	target.image	target.container
MCP arg	image	container

Implementation notes for reviewers

• Deprecation notice routing. I deliberately did not use cobra's MarkDeprecated: it prints via OutOrStderr(), which returns the out writer when one is set, so it can corrupt machine-readable --json/--format output for existing --container users. Instead the flag is MarkHidden and a one-line notice is emitted to cmd.ErrOrStderr() from PersistentPreRunE (warnDeprecatedContainerFlag). Verified bomly scan --container alpine:3.20 --json writes the warning to stderr and clean JSON to stdout.
• Env alias. New generic envalias struct tag (internal/config/load.go) lets BOMLY_CONTAINER fall back to canonical BOMLY_IMAGE (primary wins).
• YAML alias. A deprecated target.container leaf resolves to the same Image field; field order makes the canonical target.image win when both are present. KnownFields(true) still accepts both keys.
• Concept names left intact. sdk.ExecutionTargetContainerImage (value "container-image", appears in JSON/SBOM output + goldens) and internal helper names are unchanged — they accurately describe the concept and avoid golden churn.
• Regenerated docs/CONFIG_REFERENCE.md and component docs via make generate.

Tests

• Added unit tests for env-var and YAML alias resolution + precedence (internal/config/load_test.go).
• Kept one smoke test (container-scan-debian) and one root-cmd diff test on --container as backwards-compat guards; switched the rest to --image.
• make build, make test (full suite), and make lint (0 issues) pass. Smoke tests (make smoke) need network and were not run; goldens are unaffected since the flag name doesn't appear in output.

Release

feat: → minor bump. New flag is additive; no breaking change (all old forms still work).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Container image scanning and diffing now use --image as the primary flag.
  • --container remains available as a deprecated alias for compatibility.

• Bug Fixes

  • Updated command validation so container image targets follow the new flag consistently.
  • Improved error messages and help examples to match current usage.

• Documentation

  • Refreshed getting started, scan targets, troubleshooting, and use-case examples to show --image throughout.

[coderabbitai]

Warning

Review limit reached

@bomly-guy, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 12 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: f7a6d6c7-7545-48ba-8097-90ad11b106f3

📥 Commits

Reviewing files that changed from the base of the PR and between 19e86c9 and e49e414.

⛔ Files ignored due to path filters (1)

• docs/CONFIG_REFERENCE.md is excluded by !docs/CONFIG_REFERENCE.md

📒 Files selected for processing (27)

• README.md
• docs/DETECTORS.md
• docs/GETTING_STARTED.md
• docs/SCAN_TARGETS.md
• docs/TROUBLESHOOTING.md
• docs/USE_CASES.md
• docs/detectors/ecosystems/sbom/sbom.md
• internal/cli/cmd_progress.go
• internal/cli/diff_cmd.go
• internal/cli/diff_resolve.go
• internal/cli/mcp_cmd.go
• internal/cli/opts/flag_options.go
• internal/cli/opts/options.go
• internal/cli/opts/options_test.go
• internal/cli/root_cmd.go
• internal/cli/root_cmd_test.go
• internal/cli/scan_cmd.go
• internal/config/config.go
• internal/config/load.go
• internal/config/load_test.go
• internal/mcp/server.go
• internal/mcp/tool_diff.go
• internal/mcp/tool_scan.go
• internal/support/component_docs.go
• internal/support/prose/detectors/sbom.md
• test/smoke/audit_test.go
• test/smoke/container_test.go

📝 Walkthrough

Walkthrough

The PR switches container-image scanning and diffing from --container to --image across CLI config, validation, MCP requests, docs, and smoke tests. The deprecated --container alias remains supported and now emits a warning.

Changes

Container image flag migration

Layer / File(s)	Summary
Config and flag surface internal/config/config.go, internal/config/load.go, internal/cli/opts/flag_options.go, internal/config/load_test.go	Resolved.Image replaces Resolved.Container, BOMLY_IMAGE becomes primary with BOMLY_CONTAINER as an alias, and --image/hidden --container bind to the same target field.
Target resolution and diff routing internal/cli/opts/options.go, internal/cli/opts/options_test.go, internal/cli/cmd_progress.go, internal/cli/diff_cmd.go, internal/cli/diff_resolve.go	Execution-target validation, progress labels, and diff resolution now branch on Image and report --image in the related errors.
Root warning and examples internal/cli/root_cmd.go, internal/cli/root_cmd_test.go, internal/cli/scan_cmd.go	The root command prints a deprecation warning for explicit --container, and the scan/help examples now show --image.
MCP request contract internal/mcp/server.go, internal/mcp/tool_scan.go, internal/mcp/tool_diff.go, internal/cli/mcp_cmd.go	MCP scan/diff requests and tool arguments use image, with container retained as a fallback alias when building overrides and requests.
Docs and smoke coverage README.md, docs/*, internal/support/*, test/smoke/*	User-facing examples, generated detector docs, troubleshooting text, and smoke tests switch container-image invocations and exclusivity wording to --image.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant newRootCmd
  participant warnDeprecatedContainerFlag
  participant cmd.ErrOrStderr
  participant resolveExecutionTarget
  User->>newRootCmd: run bomly with --container or --image
  newRootCmd->>warnDeprecatedContainerFlag: inspect hidden container flag
  warnDeprecatedContainerFlag->>cmd.ErrOrStderr: write deprecation warning
  newRootCmd->>resolveExecutionTarget: resolve target from ResolvedConfig.Image
  resolveExecutionTarget-->>User: return container-image execution target

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• bomly-dev/bomly-cli#201: Shares the internal/cli/diff_cmd.go and internal/cli/diff_resolve.go path, so it may overlap with diff-command review context.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 41.94% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	Title clearly summarizes the main change: renaming the scan flag to --image while keeping --container as a deprecated alias.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/laughing-shaw-69b7b8

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Bomly Diff Summary

Compared 1d53d67d34d988fabd2e69d68dbaa7092583f480 to e49e414179ec23a848770bd4695190dcdedc7a60.

Overview

Status	Manifests	Dependencies	Findings	Duration
✅ Pass	+0 / ~0 / -0	+0 / ~0 / -0	0 introduced / 0 persisted / 0 resolved	1m 0s

Dependency Changes

✅ No dependency changes.

Vulnerabilities

✅ No vulnerability changes.

License Changes

✅ No license changes.

Project Posture

✅ No project posture changes (--matchers +scorecard was not selected).

Policy Findings

✅ No policy differences were identified.