Add impact radius doc

docs/features/breaking-change-analysis.md

@@ -12,37 +12,103 @@ icon: octicons/diff-modified-24
 It's generally assumed that any modification to a model’s SQL will affect all downstream models. However, not all changes have the same level of impact. For example, formatting adjustments or the addition of a new column should not break downstream dependencies. Breaking change analysis helps you assess whether a change affects downstream models and, if so, to what extent.
 
 
+## Usage
+Use the [impact radius](./impact-radius.md#usage) view to analyze changed and see the impacted downstream.
+
 ## Categories of change
-Category | Downstream Impact | Examples
----|---|---
-Non-breaking change | No downstream models are affected |  New column, formatting SQL, adding comments
-Partial breaking change | Only downstream models referencing certain columns are affected | Removing, renaming, or modifying the definition of a column
-Breaking change | All downstream models are affected | Changing filter conditions (e.g. `WHERE`), sort order (`ORDER BY`), or other SQL logic
+### Non-breaking change
+
+No downstream models are affected. Common cases are adding new columns, comments, or formatting changes that don't alter logic.
+
+**Example: Add new columns**
+Adding a new column like status doesn't affect models that don't reference it.
+
+```diff
+select
+    user_id,
+    user_name,
+++  status,
+from
+    {{ ref("orders") }}
+
+```
+
+
+
+
+### Partial breaking change
+
+Only downstream models that reference specific columns are affected. Common cases are removing, renaming, or redefining a column.
+
+**Example: Removing a column**
+
+```diff
+select
+    user_id,
+--  status,
+    order_date,
+from
+    {{ ref("orders") }}
+```
+
+**Example: Renaming a column**
+
+```diff
+select
+    user_id,
+--  status
+++  order_status
+from
+    {{ ref("orders") }}
+```
+
+
+**Example: Redefining a column**
+```diff
+select
+    user_id,
+--  discount
+++  coalesce(discount, 0) as discount
+from
+    {{ ref("orders") }}
+```
 
-## Usage
 
-To enable **Breaking Change Analysis**, click the toggle on the  **Lineage** page. 
+### Breaking change
 
-All modified models display their change category directly on the node. Additionally, partial breaking changes are highlighted with a dashed orange border to indicate that they may not impact downstream models.
+All downstream models are affected. Common case are changes adding a filter condition or adding group by columns.
 
-=== "Disabled"
-
-    ![Breaking Change Analysis (disabled)](../assets/images/features/breaking-change-disabled.png){: .shadow}
+**Example: Adding a filter condition**
+This may reduce the number of rows, affecting all downstream logic that depends on the original row set.
 
-=== "Enabled"
-
-    ![Breaking Change Analysis](../assets/images/features/breaking-change.png){: .shadow}
+```diff
+select
+    user_id,
+    order_date
+from
+    {{ ref("orders") }}
+++ where status = 'completed'
+```
 
 
-## Column-Level Lineage
+**Example: Adding a GROUP BY column**
+Changes the granularity of the result set, which can break all dependent models.
 
-In models classified as **non-breaking** or **partial breaking** -  added, removed, or modified columns will be listed. Click on a column to open its [Column-Level Lineage](./column-level-lineage.md)
+```diff
+select
+    user_id,
+++  order_data,
+    count(*) as total_orders
+from
+    {{ ref("orders") }}
+-- group by user_id
+++ group by user_id, order_date
+```
 
-![Column-level lineage](../assets/images/features/breaking-change-lineage.png){: .shadow}
 
 ## Limitations
 
-The current implementation of breaking change analysis is still very conservative. As a result, a modified model may be classified as a breaking change when it is actually non breaking or partial breaking changes. Common cases include:
+Our breaking change analysis is intentionally conservative to prioritize safety. As a result, a modified model may be classified as a breaking change when it is actually non breaking or partial breaking changes. Common cases include:
 
 1. Logical equivalence in operations, such as changing `a + b` to `b + a`.
 1. Adding a `LEFT JOIN` to a table and selecting columns from it. This is often used to enrich the current model with additional dimension table data without affecting existing downstream tables.

docs/features/impact-radius.md

@@ -0,0 +1,82 @@
+---
+title: Impact Radius
+icon: material/adjust
+---
+
+**Impact Radius** helps you analyze changes and identify downstream impacts at the column level.
+
+While dbt provides a similar capability using the [state selector](https://docs.getdbt.com/reference/node-selection/methods#state) with `state:modified+` to identify modified nodes and their downstream dependencies, Recce goes further. By analyzing SQL code directly, Recce enables **fine-grained impact radius analysis**. It reveals how changes to specific columns can ripple through your data pipeline, helping you prioritize which models—and even which columns—deserve closer attention.
+
+
+=== "state:modified+"
+
+    ![Breaking Change Analysis (disabled)](../assets/images/features/impact-radius-legacy.png){: .shadow}
+
+=== "Impact Radius"
+
+    ![Breaking Change Analysis](../assets/images/features/impact-radius.png){: .shadow}
+
+
+
+## Usage
+
+### Show impact radius
+
+1. Click the **Impact Radius** button in the upper-left corner.
+
+    ![Impact Radius button highlighted](../assets/images/features/impact-radius-1.png){: .shadow}
+
+1. The impact radius will be displayed.
+
+    ![Impact radius displayed on screen](../assets/images/features/impact-radius-2.png){: .shadow}
+
+1. To exit impact radius view, click the close button in the upper-left corner.
+
+    ![Close button for exiting impact radius view](../assets/images/features/impact-radius-3.png){: .shadow}
+
+### Show impact radius for a single changed model
+
+1. Hover over a changed model, then click the **target icon** or right-click the model and click the **Show Impact Radius**
+
+    ![Target icon for showing impact radius of a single model](../assets/images/features/impact-radius-single-1.png){: .shadow}
+
+1. The impact radius for this model will be displayed.
+
+    ![Impact radius for a single model displayed on screen](../assets/images/features/impact-radius-single-2.png){: .shadow}
+
+1. To exit impact radius view, click the close button in the upper-left corner.
+
+    ![Close button for exiting single model impact radius view](../assets/images/features/impact-radius-single-3.png){: .shadow}
+
+
+## How it works
+
+Two core features power the impact radius analysis:
+
+**[Breaking Change Analysis](./breaking-change-analysis.md)** classifies modified models into three categories:
+
+- **Breaking changes**: Impact all downstream **models**
+- **Non-breaking changes**: Do not impact any downstream **models**
+- **Partial breaking changes**: Impact only downstream **models or columns** that depend on the modified columns
+
+**[Column-level lineage](./column-level-lineage.md)** analyzes your model's SQL to identify column-level dependencies:
+
+- Which upstream **columns** are used as filters or grouping keys. If those upstream **columns** change, the current **model** is impacted.
+- Which upstream **columns** a specific column references. If those upstream **columns** change, the specific **column** is impacted.
+
+## Putting It Together
+
+With the insights from the two features above, Recce determines the impact radius:
+
+1. If a model has a **breaking change**, include all downstream models in the impact radius.
+1. If a model has a **non-breaking change**, include only the downstream columns and models of newly added columns.
+1. If a model has a **partial breaking change**, include the downstream columns and models of added, removed, or modified columns.
+
+
+
+
+
+
+
+
+

mkdocs.yml

@@ -56,6 +56,7 @@ nav:
           - features/state-file.md
           - features/preset-checks.md
           - features/node-selection.md
+          - features/impact-radius.md
           - features/breaking-change-analysis.md
           - features/column-level-lineage.md
           - reference/configuration.md