feat(cli): Refactor help output

[ayo6706]

This PR overhauls the CLI help output to match the clean, structured style, while also refactoring how versioning and descriptions are handled in the codebase.

Key Changes:

Enhanced Help Output: The vectorlint --help output now features a clear layout with a tagline, an extended description, and a "Getting Started" section. The options and commands lists remain dynamic to ensure they stay in sync with the code.

Summary by CodeRabbit

• New Features

  • CLI now exposes a formal version and expanded multi-line description/help; invoking with no arguments shows help automatically.
  • Scoring output adds max, weighted, and normalized score metrics (and their max values).

• Bug Fixes

  • Fixed CLI --config option parsing.

• Changes

  • Removed the --debug-json CLI option and eliminated verbose full-JSON debug logging across providers.
  • validate command option renamed from --evals to --rules.

• Tests

  • Updated tests for provider-type usage and removed debug-json test paths.

• Documentation

  • README wording refined for evaluation focus.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Centralized CLI version/description constants; removed the --debug-json CLI option and all provider-level debugJson plumbing/logging; renamed validate option --evals → --rules; fixed --config option declaration; extended JSON score output with additional numeric score fields.

Changes

Cohort / File(s)	Summary
CLI entry & commands src/index.ts, src/cli/commands.ts, src/cli/validate-command.ts	Use CLI_VERSION / CLI_DESCRIPTION; removed --debug-json option; fixed --config declaration quoting; renamed validate option --evals → --rules; adjust help/usage text.
Constants & schemas src/config/constants.ts, src/schemas/cli-schemas.ts	Add CLI_VERSION, CLI_DESCRIPTION, and PACKAGE_JSON_SCHEMA; remove debugJson and evals from CLI schemas; add rules in validate schema.
Providers & factory src/providers/*provider.ts, src/providers/provider-factory.ts	Remove debugJson from provider config interfaces and ProviderOptions; eliminate conditional JSON-debug logging in Anthropic, AzureOpenAI, Gemini, and OpenAI providers; stop propagating debugJson from factory.
Output formatting src/output/json-formatter.ts	Replace package.json parsing with CLI_VERSION import; extend exported ScoreComponent with numeric fields: maxScore, weightedScore, weightedMaxScore, normalizedScore, normalizedMaxScore.
Tests tests/*	Remove tests and fixtures exercising debugJson; update tests to use exported ProviderType enum and adapt to renamed validate option and removed debug logging.
Docs README.md	Minor wording change describing the tool's evaluation focus.

Sequence Diagram(s)

(omitted — changes do not introduce a new multi-component control flow)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• oshorefueled
• hurshore

"I nibble at the code all day and night,
Quieted the JSON, made version bright,
Rules renamed and scores grew more true,
Help now pops when flags are few,
A rabbit’s cheer for tidy code and light! 🥕"

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(cli): Refactor help output' accurately summarizes the main objective of the PR, which is to enhance and restructure the CLI help output.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 44fab51 and 9d12c4d.

📒 Files selected for processing (2)

• README.md
• src/config/constants.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/config/constants.ts

🔇 Additional comments (1)

README.md (1)

3-3: LGTM! Clear and specific description.

The refined description effectively communicates VectorLint's core value proposition by naming the specific types of issues it catches (terminology, technical accuracy, and style), which helps users immediately understand its use case.

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/schemas/cli-schemas.ts (1)

8-8: Consider removing debugJson from schema after CLI option removal.

The --debug-json CLI option was removed, but the debugJson field remains in the schema. While the default(false) prevents breakage, keeping unused fields creates maintenance confusion.

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2f5fe6c and 7d04244.

📒 Files selected for processing (5)

• src/cli/commands.ts
• src/config/constants.ts
• src/index.ts
• src/output/json-formatter.ts
• src/schemas/cli-schemas.ts

🧰 Additional context used

📓 Path-based instructions (2)

src/**/*.ts

📄 CodeRabbit inference engine (AGENTS.md)

src/**/*.ts: Use TypeScript ESM with explicit imports and narrow types
Use 2-space indentation; avoid trailing whitespace
Maintain strict TypeScript with no any; use unknown + schema validation for external data
Use custom error types with proper inheritance; catch blocks use unknown type

Files:

• src/index.ts
• src/cli/commands.ts
• src/schemas/cli-schemas.ts
• src/config/constants.ts
• src/output/json-formatter.ts

src/output/**/*.ts

📄 CodeRabbit inference engine (AGENTS.md)

IDs should be shown as PromptId.CriterionId in output

Files:

• src/output/json-formatter.ts

🧠 Learnings (1)

📚 Learning: 2025-12-28T19:43:51.189Z

Learnt from: CR
Repo: TRocket-Labs/vectorlint PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T19:43:51.189Z
Learning: Applies to src/boundaries/**/*.ts : Use Zod schemas for boundary validation of all external data (files, CLI, env, APIs) at system boundaries

Applied to files:

• src/schemas/cli-schemas.ts

🧬 Code graph analysis (4)

src/index.ts (1)

src/config/constants.ts (2)

• CLI_VERSION (9-9)
• CLI_DESCRIPTION (17-28)

src/cli/commands.ts (1)

src/config/constants.ts (1)

• DEFAULT_CONFIG_FILENAME (12-12)

src/config/constants.ts (1)

src/schemas/cli-schemas.ts (1)

• PACKAGE_JSON_SCHEMA (20-22)

src/output/json-formatter.ts (1)

src/config/constants.ts (1)

• CLI_VERSION (9-9)

🔇 Additional comments (12)

src/cli/commands.ts (2)

30-30: LGTM! Improved consistency using constant.

The config option now correctly references DEFAULT_CONFIG_FILENAME for consistent messaging.

---

77-77: The debugJson field and its corresponding CLI option are actively used and correctly implemented. The field is defined in the CLI schema (src/schemas/cli-schemas.ts line 8) with a default value of false, properly typed as part of CliOptions, and actively consumed by all providers (AnthropicProvider, OpenAIProvider, GeminiProvider, and AzureOpenAIProvider) for JSON response logging. The code at line 77 correctly passes this field to the provider. No changes are needed.

Likely an incorrect or invalid review comment.

src/schemas/cli-schemas.ts (1)

20-22: LGTM! Schema correctly validates package.json structure.

The schema appropriately validates the package.json structure for version extraction used by CLI_VERSION.

src/config/constants.ts (3)

9-9: LGTM! Version derivation with validation.

Using PACKAGE_JSON_SCHEMA.parse() ensures the version is validated at module load time, providing fail-fast behavior for invalid package.json structure.

---

17-28: LGTM! Clear and helpful CLI description.

The description provides good onboarding information. The template literal references GLOBAL_CONFIG_DIR and GLOBAL_CONFIG_FILE defined earlier in the file, which works correctly since template literals are evaluated at runtime.

---

1-2: The imports are correctly configured. resolveJsonModule is enabled in tsconfig.json, package.json exists at the expected path, and PACKAGE_JSON_SCHEMA is properly exported from the schemas module via src/schemas/index.ts.

src/index.ts (3)

11-11: LGTM! Centralized CLI metadata.

Importing CLI_VERSION and CLI_DESCRIPTION from constants establishes a single source of truth for CLI metadata, improving maintainability.

---

68-73: LGTM! Improved CLI help output.

The enhanced help configuration provides:

• Version sourced from package.json
• Clear tagline and practical usage examples
• Comprehensive description with getting started instructions

These changes significantly improve user experience.

---

81-85: LGTM! Smart no-argument handling.

The logic correctly detects when no arguments are provided (process.argv.length === 2) and automatically displays help using a synthetic argv. This provides a better user experience than showing an error.

src/output/json-formatter.ts (3)

2-2: LGTM! Consistent versioning approach.

Importing CLI_VERSION eliminates duplicate package.json parsing and ensures consistent version information across the codebase.

---

81-81: LGTM! Centralized version in metadata.

Using CLI_VERSION for the metadata version ensures consistency with the CLI version displayed in help output.

---

6-10: No action required—all ScoreComponent fields are properly populated.

The five new numeric fields are explicitly initialized at all creation sites in src/cli/orchestrator.ts with appropriate values (default 0, 4, or 10; or calculated values). No undefined values are present in the JSON output.