feat(python-setup): link setup failures to remediation docs (#2125)

## What

When `environments setup-local` fails, the extension already surfaces
the failing phase, the error code, and a friendly per-code message. But
only two codes (uv-missing and a blocked package index) pointed the user
at documentation — every other failure left them with no next step.

This adds a documentation link per error code, reusing the existing
`PythonSetupErrorAction` shape:

- A sparse `DOC_LINKS` map in `errorMessages.ts` keyed by error code.
- `getPythonSetupErrorAction` returns the mapped link as the failure
popup's button for `E_MANAGER_UNSUPPORTED`, `E_PYTHON_INSTALL`,
`E_PROVISION` (dependency conflict), `E_NO_TARGET`, `E_RESOLVE`, and
`E_ENV_UNSUPPORTED`, on top of the existing uv-missing and blocked-index
cases.
- `formatSetupFailureDetail` spells the same link into the **output
channel**, so it stays reachable after the notification is dismissed.

Codes with no reliably-helpful page (`E_USAGE`, `E_NOT_WRITABLE`,
`E_WRITE`, `E_MERGE`, `E_VALIDATE`, `E_FETCH`) deliberately stay
message-only rather than link to a page that could misdirect.

### Link mapping

| Error code | Link |
| --- | --- |
| `E_UV_MISSING` | uv installation *(existing)* |
| `E_PROVISION` (blocked index) | uv index configuration *(existing)* |
| `E_MANAGER_UNSUPPORTED` | uv projects |
| `E_PYTHON_INSTALL` | uv install Python |
| `E_PROVISION` (dependency conflict) | uv resolution |
| `E_NO_TARGET`, `E_RESOLVE` | VS Code extension — configure compute |
| `E_ENV_UNSUPPORTED` | Databricks Runtime release notes |

## Testing

- `yarn test:unit` — all python-setup / `errorMessages` / orchestrator
tests pass.
- `eslint` + `prettier` clean on the changed files.
- All documentation URLs were fetched and confirmed to resolve.

This pull request and its description were written by Isaac.

Author: rugpanov

packages/databricks-vscode/src/python-setup/controllers/PythonSetupEnvironmentSetup.test.ts

@@ -13,11 +13,9 @@ import {
     SUCCESS_REAL_RUN,
     SUCCESS_REAL_RUN_WITH_WARNINGS,
     ERROR_NO_TARGET,
+    ERROR_USAGE,
 } from "../models/fixtures/setupLocalResults";
-import {
-    PythonSetupErrorAction,
-    UV_INSTALL_DOCS_URL,
-} from "../utils/errorMessages";
+import {PythonSetupErrorAction} from "../utils/errorMessages";
 import {SetupLocalInvocation} from "../utils/setupLocalArgs";
 import {
     PythonSetupAttempt,
@@ -374,11 +372,11 @@ describe("PythonSetupEnvironmentSetup.setup", () => {
         expect(shown).to.have.length(1);
         expect(shown[0].action).to.deep.equal({
             label: "Install uv",
-            url: UV_INSTALL_DOCS_URL,
+            url: "https://docs.astral.sh/uv/getting-started/installation/",
         });
     });
 
-    it("passes no remediation action for failures other than uv-missing", async () => {
+    it("offers the mapped documentation action for a doc-linked failure", async () => {
         const shown: {action?: PythonSetupErrorAction}[] = [];
         const setup = new PythonSetupEnvironmentSetup(
             makeDeps({
@@ -391,6 +389,27 @@ describe("PythonSetupEnvironmentSetup.setup", () => {
 
         await setup.setup();
 
+        expect(shown).to.have.length(1);
+        expect(shown[0].action).to.deep.equal({
+            label: "Configure compute",
+            url: "https://docs.databricks.com/aws/en/dev-tools/vscode-ext/configure#cluster",
+        });
+    });
+
+    it("passes no remediation action for a message-only failure", async () => {
+        // E_USAGE has no doc that reliably helps, so it surfaces the message alone.
+        const shown: {action?: PythonSetupErrorAction}[] = [];
+        const setup = new PythonSetupEnvironmentSetup(
+            makeDeps({
+                cli: makeCli({resolve: ERROR_USAGE}),
+                showError: async (_message, _detail, action) => {
+                    shown.push({action});
+                },
+            })
+        );
+
+        await setup.setup();
+
         expect(shown).to.have.length(1);
         expect(shown[0].action).to.equal(undefined);
     });

packages/databricks-vscode/src/python-setup/utils/errorMessages.test.ts

@@ -4,8 +4,6 @@ import {
     getPythonSetupErrorAction,
     getPythonSetupErrorMessage,
     isIndexUnreachableFailure,
-    UV_INDEX_DOCS_URL,
-    UV_INSTALL_DOCS_URL,
 } from "./errorMessages";
 import {
     PythonSetupResult,
@@ -265,7 +263,7 @@ describe("getPythonSetupErrorAction", () => {
         );
         expect(action).to.deep.equal({
             label: "Install uv",
-            url: UV_INSTALL_DOCS_URL,
+            url: "https://docs.astral.sh/uv/getting-started/installation/",
         });
     });
 
@@ -275,16 +273,98 @@ describe("getPythonSetupErrorAction", () => {
         );
         expect(action).to.deep.equal({
             label: "Configure package index",
-            url: UV_INDEX_DOCS_URL,
+            url: "https://docs.astral.sh/uv/configuration/indexes/",
         });
     });
 
-    it("offers no action for an ordinary E_PROVISION conflict", () => {
-        expect(getPythonSetupErrorAction(failure("E_PROVISION"))).to.equal(
-            undefined
+    it("points an ordinary E_PROVISION conflict at the uv resolution docs", () => {
+        // A genuine dependency conflict (no connectivity symptom) is distinct from
+        // a blocked index: it links to uv's resolution guide, not the index docs.
+        expect(getPythonSetupErrorAction(failure("E_PROVISION"))).to.deep.equal(
+            {
+                label: "Resolve dependency conflicts",
+                url: "https://docs.astral.sh/uv/concepts/resolution/",
+            }
         );
     });
 
+    it("points E_MANAGER_UNSUPPORTED at the uv projects docs", () => {
+        expect(
+            getPythonSetupErrorAction(
+                failure("E_MANAGER_UNSUPPORTED", {failurePhase: "preflight"})
+            )
+        ).to.deep.equal({
+            label: "Set up a uv project",
+            url: "https://docs.astral.sh/uv/concepts/projects/",
+        });
+    });
+
+    it("points E_PYTHON_INSTALL at the uv install-Python docs", () => {
+        expect(
+            getPythonSetupErrorAction(failure("E_PYTHON_INSTALL"))
+        ).to.deep.equal({
+            label: "Install a Python version",
+            url: "https://docs.astral.sh/uv/guides/install-python/",
+        });
+    });
+
+    it("points E_NO_TARGET at the compute-selection section of the configure docs", () => {
+        expect(
+            getPythonSetupErrorAction(
+                failure("E_NO_TARGET", {failurePhase: "resolve"})
+            )
+        ).to.deep.equal({
+            label: "Configure compute",
+            url: "https://docs.databricks.com/aws/en/dev-tools/vscode-ext/configure#cluster",
+        });
+    });
+
+    it("points E_RESOLVE at the compute-selection section of the configure docs", () => {
+        expect(
+            getPythonSetupErrorAction(
+                failure("E_RESOLVE", {failurePhase: "resolve"})
+            )
+        ).to.deep.equal({
+            label: "Configure compute",
+            url: "https://docs.databricks.com/aws/en/dev-tools/vscode-ext/configure#cluster",
+        });
+    });
+
+    it("points E_ENV_UNSUPPORTED at the Databricks runtime release notes", () => {
+        expect(
+            getPythonSetupErrorAction(
+                failure("E_ENV_UNSUPPORTED", {failurePhase: "fetch"})
+            )
+        ).to.deep.equal({
+            label: "Databricks Runtime versions",
+            url: "https://docs.databricks.com/aws/en/release-notes/runtime/",
+        });
+    });
+
+    it("offers no action for E_FETCH (deliberately message-only)", () => {
+        // A generic network/cache failure has no single doc that reliably helps,
+        // so we avoid pointing the user at an unclear page.
+        expect(
+            getPythonSetupErrorAction(
+                failure("E_FETCH", {failurePhase: "fetch"})
+            )
+        ).to.equal(undefined);
+    });
+
+    it("offers no action for codes with no clear remediation doc", () => {
+        for (const code of [
+            "E_USAGE",
+            "E_NOT_WRITABLE",
+            "E_WRITE",
+            "E_MERGE",
+            "E_VALIDATE",
+        ] as const) {
+            expect(getPythonSetupErrorAction(failure(code)), code).to.equal(
+                undefined
+            );
+        }
+    });
+
     it("offers no action when the result carries no error", () => {
         const ok = failure("E_UV_MISSING");
         ok.error = null;
@@ -359,6 +439,30 @@ describe("formatSetupFailureDetail", () => {
         );
         expect(detail).to.not.contain("UV_INDEX_URL");
     });
+
+    it("appends the documentation link and its label for a code that has one", () => {
+        const detail = formatSetupFailureDetail(
+            failure("E_NO_TARGET", {failurePhase: "resolve"})
+        );
+        expect(detail).to.contain(
+            "https://docs.databricks.com/aws/en/dev-tools/vscode-ext/configure#cluster"
+        );
+        expect(detail).to.contain("Configure compute");
+    });
+
+    it("appends the uv index docs link for a blocked index", () => {
+        const detail = formatSetupFailureDetail(
+            failure("E_PROVISION", {message: INDEX_UNREACHABLE_CLI_MSG})
+        );
+        expect(detail).to.contain(
+            "https://docs.astral.sh/uv/configuration/indexes/"
+        );
+    });
+
+    it("adds no documentation link for a message-only code", () => {
+        const detail = formatSetupFailureDetail(failure("E_USAGE"));
+        expect(detail).to.not.contain("https://");
+    });
 });
 
 describe("isIndexUnreachableFailure", () => {

packages/databricks-vscode/src/python-setup/utils/errorMessages.ts

@@ -41,6 +41,33 @@ export const UV_INSTALL_DOCS_URL =
 export const UV_INDEX_DOCS_URL =
     "https://docs.astral.sh/uv/configuration/indexes/";
 
+/** uv's project overview — for E_MANAGER_UNSUPPORTED (no uv project present). */
+export const UV_PROJECTS_DOCS_URL =
+    "https://docs.astral.sh/uv/concepts/projects/";
+
+/** uv's Python-version guide — for E_PYTHON_INSTALL. */
+export const UV_PYTHON_INSTALL_DOCS_URL =
+    "https://docs.astral.sh/uv/guides/install-python/";
+
+/** uv's resolution concept page — for a genuine E_PROVISION dependency conflict. */
+export const UV_RESOLUTION_DOCS_URL =
+    "https://docs.astral.sh/uv/concepts/resolution/";
+
+/**
+ * Databricks VS Code extension "configure your project" guide, anchored at the
+ * "Select compute for running code and jobs" section — for E_NO_TARGET /
+ * E_RESOLVE, where the fix is picking a valid cluster or serverless compute in
+ * the Configuration view. `#cluster` is that section's curated, stable anchor
+ * (a Databricks-authored `db-defined-anchor`), preferred over the auto-generated
+ * heading slug, which would break if the heading text changed.
+ */
+export const DATABRICKS_CONFIGURE_DOCS_URL =
+    "https://docs.databricks.com/aws/en/dev-tools/vscode-ext/configure#cluster";
+
+/** Databricks Runtime release notes (supported versions) — for E_ENV_UNSUPPORTED. */
+export const DATABRICKS_RUNTIME_DOCS_URL =
+    "https://docs.databricks.com/aws/en/release-notes/runtime/";
+
 /**
  * "Cannot reach the host" phrases in uv's error text (matched case-insensitively).
  * TLS-interception and proxy-auth (407) are deliberately left out: they need a
@@ -173,20 +200,67 @@ export function getPythonSetupErrorMessage(result: PythonSetupResult): string {
 }
 
 /**
- * The remediation button, if any: a blocked index → uv's index-config docs, or
- * `E_UV_MISSING` → uv's install docs. Other codes are actionable from the message
- * and logs alone.
+ * Documentation link per error code, surfaced both as the failure popup's
+ * remediation button and — via {@link formatSetupFailureDetail} — in the output
+ * channel. Sparse by design: codes whose fix no single page reliably explains
+ * (E_USAGE, E_NOT_WRITABLE, E_WRITE, E_MERGE, E_VALIDATE, E_FETCH) are absent and
+ * get the message alone rather than a link that might misdirect.
+ *
+ * `E_UV_MISSING` lives here so every code-keyed link takes one path; the
+ * blocked-index variant of `E_PROVISION` cannot — it is told apart by the CLI's
+ * message, not its code — so it is resolved ahead of this map (see below).
+ */
+/* eslint-disable @typescript-eslint/naming-convention */
+const DOC_LINKS: Partial<Record<PythonSetupErrorCode, PythonSetupErrorAction>> =
+    {
+        E_UV_MISSING: {label: "Install uv", url: UV_INSTALL_DOCS_URL},
+        E_MANAGER_UNSUPPORTED: {
+            label: "Set up a uv project",
+            url: UV_PROJECTS_DOCS_URL,
+        },
+        E_PYTHON_INSTALL: {
+            label: "Install a Python version",
+            url: UV_PYTHON_INSTALL_DOCS_URL,
+        },
+        E_PROVISION: {
+            label: "Resolve dependency conflicts",
+            url: UV_RESOLUTION_DOCS_URL,
+        },
+        E_NO_TARGET: {
+            label: "Configure compute",
+            url: DATABRICKS_CONFIGURE_DOCS_URL,
+        },
+        E_RESOLVE: {
+            label: "Configure compute",
+            url: DATABRICKS_CONFIGURE_DOCS_URL,
+        },
+        E_ENV_UNSUPPORTED: {
+            label: "Databricks Runtime versions",
+            url: DATABRICKS_RUNTIME_DOCS_URL,
+        },
+    };
+/* eslint-enable @typescript-eslint/naming-convention */
+
+/**
+ * The remediation button / doc link for a failure, if any. A blocked index maps
+ * to uv's index-config docs; every other link is keyed by error code via
+ * {@link DOC_LINKS}. Codes absent from the map (e.g. E_USAGE, E_FETCH) are
+ * actionable from the message and logs alone.
  */
 export function getPythonSetupErrorAction(
     result: PythonSetupResult
 ): PythonSetupErrorAction | undefined {
+    const err = result.error;
+    if (!err) {
+        return undefined;
+    }
+    // A blocked package index arrives as E_PROVISION and is distinguished by the
+    // CLI's message, not its code — so resolve it before the code-keyed map,
+    // ahead of E_PROVISION's generic dependency-conflict link.
     if (isIndexUnreachableFailure(result)) {
         return {label: "Configure package index", url: UV_INDEX_DOCS_URL};
     }
-    if (result.error?.code === "E_UV_MISSING") {
-        return {label: "Install uv", url: UV_INSTALL_DOCS_URL};
-    }
-    return undefined;
+    return DOC_LINKS[err.code];
 }
 
 /**
@@ -241,6 +315,12 @@ export function formatSetupFailureDetail(
             "     Use index-url (not extra-index-url) so pypi.org is replaced, not merely supplemented."
         );
     }
+    // The same doc link the popup offers as a button, spelled out here so the URL
+    // is reachable from the log even after the notification is dismissed.
+    const action = getPythonSetupErrorAction(result);
+    if (action) {
+        lines.push("", `${action.label}: ${action.url}`);
+    }
     // Bracket with blank lines so the block stands apart from any streamed CLI
     // output already in the channel.
     return `\n${lines.join("\n")}\n`;