[issues/52] Phase 2: Toast Classification

[couimet]

Summary

Replaces the single "navigated to" info toast with context-aware feedback based on clamping status from Phase 1. When a RangeLink points beyond file boundaries and positions are silently adjusted, users now see a warning toast with a human-readable explanation of what was clamped. Exact navigation continues to show the existing info toast.

Changes

• Added WARN_NAVIGATION_CLAMPED message code with localized template including {clampingSummary} parameter
• Added formatClampingSummary utility that aggregates per-position clamping flags into localized descriptions ("line exceeded file length", "column exceeded line length", "line and column exceeded bounds")
• All summary strings go through the i18n system (MessageCode + messages.en.ts + formatMessage)
• Calling formatClampingSummary with no clamping flags throws UNEXPECTED_CODE_PATH rather than silently returning a nonsensical value
• Navigation handler now conditionally shows warning vs info toast based on the anyClamping flag computed in Phase 1

Test Plan

• All 1648 existing tests pass (86 suites)
• 8 new tests for formatClampingSummary covering: line-only, character-only, both, cross-position aggregation, and UNEXPECTED_CODE_PATH throw
• 3 clamping tests in RangeLinkNavigationHandler.test.ts updated to verify toast type (warning vs info) and exact message content
• Compile and lint clean

Related

• Closes Phase 2: Toast Classification #52
• Parent: Enhanced Navigation Feedback #47 (Enhanced Navigation Feedback)
• Stacked on: Phase 1: Clamping Detection #51 (Phase 1: Clamping Detection)
• Next: Phase 3: Settings & Configuration #54 (Phase 3: Settings & Configuration)

Summary by CodeRabbit

• New Features
  • Enhanced navigation feedback: When navigating to positions beyond file boundaries, the extension now displays warning notifications instead of silently adjusting to valid positions. The warnings detail which boundaries were exceeded (line length, column width, or both), providing transparency about navigation adjustments made by the extension.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5b2ea24e-17d3-48ab-b545-187a5b6b8ba6

📥 Commits

Reviewing files that changed from the base of the PR and between abb70fb and 3bc9c32.

📒 Files selected for processing (8)

• packages/rangelink-vscode-extension/CHANGELOG.md
• packages/rangelink-vscode-extension/src/__tests__/navigation/RangeLinkNavigationHandler.test.ts
• packages/rangelink-vscode-extension/src/__tests__/utils/formatClampingSummary.test.ts
• packages/rangelink-vscode-extension/src/i18n/messages.en.ts
• packages/rangelink-vscode-extension/src/navigation/RangeLinkNavigationHandler.ts
• packages/rangelink-vscode-extension/src/types/MessageCode.ts
• packages/rangelink-vscode-extension/src/utils/formatClampingSummary.ts
• packages/rangelink-vscode-extension/src/utils/index.ts

---

Walkthrough

The PR adds user-facing toast notifications when navigation targets are clamped to file boundaries. When a link targets positions outside file extent, users now see warning toasts indicating what clamped (line, column, or both) instead of silent clamping. Exact navigation shows an info toast with the target range.

Changes

Cohort / File(s)	Summary
Message Types & Localization src/types/MessageCode.ts, src/i18n/messages.en.ts	Added four new MessageCode enum members (WARN_NAVIGATION_CLAMPED, WARN_NAVIGATION_CLAMPED_SUMMARY_*) and corresponding English message templates for warning and summary variants.
Clamping Summary Utility src/utils/formatClampingSummary.ts, src/utils/index.ts	New utility function that determines which axes (line/column) were clamped and returns localized summary text; throws on unexpected no-clamping state.
Navigation Handler src/navigation/RangeLinkNavigationHandler.ts	Modified post-navigation feedback to conditionally emit warning toast when clamping detected or info toast for exact navigation, using formatted clamping summary.
Test Coverage src/__tests__/utils/formatClampingSummary.test.ts, src/__tests__/navigation/RangeLinkNavigationHandler.test.ts	New test suite for utility function covering all clamping combinations and error case; updated navigation handler tests to assert correct toast type and message calls.
Documentation CHANGELOG.md	Documented new navigation clamping feedback feature in Unreleased section.

Sequence Diagram

sequenceDiagram
    actor User
    participant Handler as RangeLinkNavigationHandler
    participant Converter as Position Converter
    participant Formatter as formatClampingSummary
    participant i18n as Localization
    participant Adapter as VS Code Adapter

    User->>Handler: navigateToLink(range)
    Handler->>Converter: Convert & clamp to bounds
    Converter-->>Handler: ConvertedPosition (with clamp flags)
    
    alt Any clamping detected
        Handler->>Formatter: formatClampingSummary(start, end)
        Formatter->>i18n: formatMessage(CLAMPED_SUMMARY_*)
        i18n-->>Formatter: Localized summary text
        Formatter-->>Handler: "line exceeded file length"
        Handler->>Adapter: showWarningMessage("RangeLink: Navigated to ... (clamped: ...)")
        Adapter-->>User: ⚠️ Warning toast
    else Exact navigation (no clamping)
        Handler->>i18n: formatMessage(INFO_NAVIGATION_SUCCESS)
        i18n-->>Handler: Localized position string
        Handler->>Adapter: showInformationMessage("RangeLink: Navigated to ... @ L-C")
        Adapter-->>User: ℹ️ Info toast
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• Phase 2: Toast Classification #52: Phase 2: Toast Classification — Directly implements the phase 2 goal of showing contextual toast notifications based on clamping status, with info toasts for exact navigation and warning toasts with specific clamping details for partial navigation.

Possibly related PRs

• [issues/51] Phase 1: Clamping Detection #479 — This PR builds directly on clamping detection logic introduced in #479 by converting detected clamping flags into user-facing warning feedback with formatted summaries.

Poem

🐰 A tunnel through the code we've traced,
Now warnings guide each clamped space—
No silent bounds, just clear delight,
Toast messages set users right! 🍞✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title '[issues/52] Phase 2: Toast Classification' directly matches the linked issue and accurately describes the primary change: implementing context-aware toast notifications based on clamping detection.
Linked Issues check	✅ Passed	The PR fully implements all coding requirements from issue #52: info toasts for exact navigation, warning toasts for clamped navigation with specific clamping summaries, integration with the navigation handler using Phase 1 clamping flags, and comprehensive tests verifying toast type and message content.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to issue #52 requirements: new message codes and i18n entries for toast content, formatClampingSummary utility for localized clamping descriptions, navigation handler integration, and test coverage. No unrelated modifications detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issues/52

📝 Coding Plan

• Generate coding plan for human review comments

---

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.}

[github-actions]

⚠️ QA Coverage Gap Detected

The PR introduces new navigation feedback when links point beyond file boundaries, including warning messages and information toasts. This requires new test cases to verify the correct behavior of these notifications.

Suggested test cases:

• Navigation Feedback: Verify warning message when link points beyond file boundaries (manual — Requires verification of warning toast notifications which cannot be automated.)
• Navigation Feedback: Verify information toast when position is within bounds (manual — Requires verification of information toast notifications which cannot be automated.)

---

_{Generated by QA Gap Check (GPT-4o-mini via GitHub Models)}