Multi provider projects

[vb-dbrks]

Summary

• Add Python virtual environment and interpreter docs to the Docusaurus site for end users installing schemaxpy
• Fix scope parameter mismatch across all command Protocol interfaces and repository adapters to match WorkspaceRepository.get_environment_config

Motivation / Context

• Issue: N/A
• Context: Users installing schemaxpy via pip/uv need guidance on venv setup and IDE interpreter selection. The scope param was added to WorkspaceRepository.get_environment_config for v5 multi-target support but the Protocol definitions and adapter
  implementations in command files were never updated to match.
• Scope: Docs (Docusaurus site) + Python SDK command layer type safety

Type of Change

• Feature
• Bug fix
• Refactor
• Performance improvement
• Documentation
• Test-only
• Build/CI
• Breaking change

What Changed

• docs/schemax/docs/guide/setup.mdx: Added :::tip admonition after CLI install step covering venv creation with uv, conda/mamba, and standard venv, plus Python interpreter selection in VS Code/Cursor
• docs/schemax/docs/reference/faq.mdx: Added FAQ entry for "schemax command not found / IDE can't resolve imports" with troubleshooting steps
• commands/diff.py: Added scope: str | None = None to _WorkspaceRepoPort Protocol and _DiffWorkspaceRepository adapter, passing it through to WorkspaceRepository
• commands/sql.py: Same fix for _WorkspaceRepoPort Protocol and _SqlWorkspaceRepository adapter
• commands/apply.py: Same fix for _WorkspaceRepoPort Protocol and _ApplyWorkspaceRepository adapter
• commands/rollback.py: Same fix for _WorkspaceRepoPort Protocol and _RollbackWorkspaceRepository adapter
• commands/import_assets.py: Same fix for _WorkspaceRepoPort Protocol and _ImportWorkspaceRepository adapter

Provider / Surface Area Impact

Affected Surfaces

• CLI
• Python SDK
• VSCode Extension UI
• SQL generation
• State differ/reducer
• Storage/project schema
• Integration tests
• Docs

Providers

• Provider-agnostic/core
• Unity Catalog
• Other: ______

Behavior Changes

Before

• No venv/interpreter guidance in the Docusaurus docs site
• Protocol interfaces and adapters for get_environment_config in diff, sql, apply, rollback, and import_assets commands were missing the scope parameter, breaking type safety against WorkspaceRepository

After

• Users see a venv tip in setup.mdx and a troubleshooting FAQ entry in faq.mdx
• All command-layer Protocols and adapters accept and pass through scope: str | None = None, matching the WorkspaceRepository signature

Examples

# Docusaurus build passes
cd docs/schemax && npm run build

# All unit tests pass
cd packages/python-sdk && python -m pytest tests/unit/test_diff_command.py tests/unit/test_sql_command.py tests/unit/test_apply_command.py tests/unit/test_rollback_command.py -x -q
# 35 passed in 0.19s

# mypy passes on changed files (only pre-existing no-any-return on apply.py:509)
python -m mypy src/schemax/commands/diff.py src/schemax/commands/sql.py src/schemax/commands/apply.py src/schemax/commands/rollback.py src/schemax/commands/import_assets.py

Backward Compatibility

- No backward compatibility concerns
- Backward compatible
- Breaking (details below)

Breaking Change Details (if any)

- Impact: N/A — scope defaults to None, so all existing callers are unaffected
- Migration path: N/A
- Rollback strategy: N/A

Data / State / Migration Notes

- No data/state schema changes
- Data/state schema changed (describe)
- Migration required: [ ] Yes [x] No
- Manual steps required: [ ] Yes [x] No

Details:
- No changes to project.json, changelog, or snapshot formats

Testing

Automated

- make all passed
- Unit tests added/updated
- Integration tests added/updated
- Live/integration env-gated tests validated (if applicable)

Manual

1. cd docs/schemax && npm run build — verify Docusaurus builds successfully
2. cd packages/python-sdk && python -m pytest tests/unit/ -x -q — verify all unit tests pass
3. python -m mypy src/schemax/commands/{diff,sql,apply,rollback,import_assets}.py — verify type safety

Test Evidence

# Docusaurus
[SUCCESS] Generated static files in "build".

# Tests
35 passed in 0.19s

# Mypy (only pre-existing error, unrelated)
src/schemax/commands/apply.py:509: error: Returning Any from function declared to return "list[Any]"  [no-any-return]
Found 1 error in 1 file (checked 5 source files)

Observability / UX

- New Docusaurus tip admonition is visually distinct and non-intrusive
- FAQ entry uses clear step-by-step troubleshooting format

Security / Privacy / Compliance

- No security impact
- Security-relevant changes (describe)
- Secrets/credentials handling reviewed
- PII/data governance impact reviewed

Details:
- Documentation and type signature alignment only

Performance Considerations

- No material perf impact
- Perf improved
- Perf risk introduced (mitigation below)

Details:
- N/A

Risks & Mitigations

┌──────────────────────────────────────────────────────────┬──────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                           Risk                           │ Severity │                                                                Mitigation                                                                │
├──────────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Test fakes in unit tests still don't include scope param │ Low      │ Existing tests pass since scope defaults to None; fakes use duck typing. Will be caught by mypy if tests are annotated against Protocol. │
└──────────────────────────────────────────────────────────┴──────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Follow-ups / Out of Scope

- Update test fakes to include scope parameter for full Protocol compliance
- Wire scope through from CLI to get_environment_config call sites when v5 multi-target is implemented
- Pre-existing mypy no-any-return on apply.py:509 should be fixed separately

Checklist

- Code follows project architecture (provider-extensible, no hardcoded provider leakage in core)
- SOLID/SRP/DRY considerations applied
- Errors are deterministic; warnings are intentional and actionable
- Docs/comments updated where needed
- No unrelated changes included
- Reviewer notes added for tricky areas

Reviewer Notes

- Focus areas: Verify the 5 Protocol + adapter pairs all match WorkspaceRepository.get_environment_config signature; verify Docusaurus tip renders correctly
- Known limitations: scope is plumbed but not yet used (deleted at entry points with del scope); test fakes don't enforce Protocol conformance at runtime
- Suggested test paths: npm run build in docs/schemax, make all in packages/python-sdk

[Copilot]

Pull request overview

This PR advances SchemaX “multi provider projects” by introducing a v5 multi-target project schema (with v4 → v5 auto-migration), updating the VS Code extension/webview to read target-scoped config, and aligning CLI/SDK interfaces around a scope concept while also adding end-user venv/interpreter documentation.

Changes:

• Add v5 project schema support (targets/defaultTarget) with transparent v4 → v5 migration across the Python SDK and VS Code extension storage layers.
• Introduce Operation.scope and add --scope CLI options + repository/service signatures to support target scoping.
• Update VS Code extension interpreter resolution to prefer the Python extension API and add target-specific settings UI + docs/version bumps.

Reviewed changes

Copilot reviewed 73 out of 75 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
packages/vscode-extension/tests/unit/pythonBackendClient.test.ts	Updates unit tests for Python extension API interpreter resolution and PATH fallbacks.
packages/vscode-extension/src/webview/styles.css	Adds styling for target tabs in the settings UI.
packages/vscode-extension/src/webview/state/useDesignerStore.ts	Adds activeTarget and includes scope on emitted operations.
packages/vscode-extension/src/webview/models/unity.ts	Adds v5 target schema types and a default-target accessor helper.
packages/vscode-extension/src/webview/components/settings/UnityTargetSettings.tsx	New Unity-specific per-target settings panel (env mappings, managed scope, etc.).
packages/vscode-extension/src/webview/components/Sidebar.tsx	Switches tooltip environment source to default target config.
packages/vscode-extension/src/webview/components/ImportAssetsPanel.tsx	Reads environment names from default target config.
packages/vscode-extension/src/webview/components/EnvironmentSummary.tsx	Reads environments from default target config.
packages/vscode-extension/src/storage-v4.ts	Implements v5 project schema + v4→v5 migration + target helpers (still named storage-v4).
packages/vscode-extension/src/extension.ts	Updates extension pipeline to use v5 targets and injects a logger into PythonBackendClient.
packages/vscode-extension/src/contracts/workspace.ts	Adds optional scope field to operations contract.
packages/vscode-extension/src/backend/pythonBackendClient.ts	Uses @vscode/python-extension API to resolve interpreter; adds diagnostic logging.
packages/vscode-extension/package.json	Bumps extension version and adds @vscode/python-extension dependency.
packages/vscode-extension/TESTING-UI.md	Removes UI testing guide documentation file.
packages/vscode-extension/CHANGELOG.md	Adds 0.2.11 release entry for extension changes.
packages/python-sdk/tests/unit/test_workspace_repository.py	Updates v5 project schema assertions.
packages/python-sdk/tests/unit/test_storage_v5.py	Adds unit tests for v5 schema and v4→v5 migration.
packages/python-sdk/tests/unit/test_storage_v4.py	Updates legacy storage tests to reflect v5 outputs.
packages/python-sdk/tests/unit/test_sql_parser_extended.py	Adds extended unit coverage for SQL parser internals.
packages/python-sdk/tests/unit/test_sql_command.py	Expands SQL command unit tests and helper coverage.
packages/python-sdk/tests/unit/test_rollback_extended.py	Adds rollback unit coverage for internal helpers and edge cases.
packages/python-sdk/tests/unit/test_hierarchy_classes.py	Adds tests for hierarchy model helpers.
packages/python-sdk/tests/unit/test_exceptions.py	Adds tests for provider exception classes.
packages/python-sdk/tests/unit/test_diff_command.py	Updates diff command tests for v5 project schema.
packages/python-sdk/tests/unit/test_cli_commands.py	Updates CLI tests/stubs for scope and v5 schema.
packages/python-sdk/tests/unit/test_bundle_command.py	Updates bundle tests to use v5 targets/defaultTarget.
packages/python-sdk/tests/unit/test_batching.py	Adds tests for batching operations by type.
packages/python-sdk/tests/unit/test_base_sql_generator.py	Adds extensive unit tests for BaseSQLGenerator internals.
packages/python-sdk/tests/integration/test_workflows_e2e.py	Updates integration workflow to mutate v5 env config via targets.
packages/python-sdk/tests/integration/test_workflows.py	Updates workflow integration tests for v5 schema usage.
packages/python-sdk/tests/integration/test_version_utilities.py	Updates storage/version utility tests for v5 schema.
packages/python-sdk/tests/integration/test_validate_error_paths.py	Adds validate integration tests for error/warning paths and JSON envelopes.
packages/python-sdk/tests/integration/test_state_reducer_edges.py	Adds integration coverage for state reducer edge-case ops.
packages/python-sdk/tests/integration/test_sql_gen_objects.py	Adds integration coverage for SQL generation across many object types.
packages/python-sdk/tests/integration/test_sql_gen_locations.py	Adds integration coverage for managed/external location resolution.
packages/python-sdk/tests/integration/test_sql_gen_batched.py	Adds integration coverage for batched SQL generation paths.
packages/python-sdk/tests/integration/test_sql_error_paths.py	Adds SQL command integration tests for error paths and edge cases.
packages/python-sdk/tests/integration/test_live_e2e_command_matrix.py	Updates live test helper to v5 target env access.
packages/python-sdk/tests/integration/test_diff_error_paths.py	Adds diff integration tests for error paths and show-sql/details.
packages/python-sdk/tests/integration/test_command_error_paths.py	Updates apply error-path integration test to v5 schema env mapping.
packages/python-sdk/tests/integration/test_cli_coverage_gaps.py	Adds broad integration tests to close CLI coverage gaps.
packages/python-sdk/tests/integration/test_cli_command_paths.py	Updates CLI integration tests for v5 schema environment config.
packages/python-sdk/tests/integration/test_bundle_integration.py	Updates bundle integration test to mutate v5 target environments.
packages/python-sdk/tests/integration/live_helpers.py	Updates integration helpers to edit v5 env config under targets.
packages/python-sdk/tests/conftest.py	Updates fixture docstring to reference v5 initialization.
packages/python-sdk/src/schemax/version.py	Bumps SDK version to 0.2.11.
packages/python-sdk/src/schemax/providers/base/operations.py	Adds scope to Operation model and create_operation helper.
packages/python-sdk/src/schemax/core/workspace_repository.py	Adds scope plumbing and exposes get_target_config wrapper.
packages/python-sdk/src/schemax/core/storage.py	Implements v5 schema, v4→v5 migration, and target config accessors.
packages/python-sdk/src/schemax/core/init.py	Exports get_target_config.
packages/python-sdk/src/schemax/commands/validate.py	Adds scope parameter to validate command boundary (currently discarded).
packages/python-sdk/src/schemax/commands/sql.py	Adds scope parameter to SQL command boundary (currently discarded).
packages/python-sdk/src/schemax/commands/rollback.py	Updates repository protocol to accept scope for env config.
packages/python-sdk/src/schemax/commands/import_assets.py	Updates repository protocol to accept scope for env config.
packages/python-sdk/src/schemax/commands/diff.py	Resolves provider ID from v5 target config.
packages/python-sdk/src/schemax/commands/bundle.py	Reads environments from resolved target config.
packages/python-sdk/src/schemax/commands/apply.py	Adds scope parameter to apply boundary (currently discarded).
packages/python-sdk/src/schemax/cli.py	Adds --scope options and includes v5 project fields in workspace-state payload.
packages/python-sdk/src/schemax/application/services.py	Plumbs scope through service layer API.
packages/python-sdk/src/schemax/init.py	Resolves provider via target config for diff helpers.
packages/python-sdk/pyproject.toml	Bumps Python package version to 0.2.11.
packages/python-sdk/CHANGELOG.md	Adds 0.2.11 release notes for v5 schema + scope flag.
package.json	Bumps monorepo version to 0.2.11.
package-lock.json	Updates lockfile versions and adds new dependency entry.
docs/schemax/package.json	Bumps docs site version to 0.2.11.
docs/schemax/docs/reference/release-notes.mdx	Adds 0.2.11 coordinated release notes.
docs/schemax/docs/reference/faq.mdx	Adds FAQ entry for missing CLI/IDE import resolution (venv/interpreter).
docs/schemax/docs/guide/setup.mdx	Adds venv creation + interpreter selection tip.
docs/schemax/docs/guide/databricks-asset-bundles.mdx	Updates version references for 0.2.11.
contracts/cli-envelopes/runtime_info.success.json	Updates runtime-info fixture to CLI version 0.2.11.

Comments suppressed due to low confidence (2)

packages/vscode-extension/src/webview/models/unity.ts:208

• The type claims “v4 compat” via optional provider, but targets and defaultTarget are required. A true v4-shaped payload (with only provider) would not satisfy this interface. Either make targets/defaultTarget optional (and handle both shapes) or update the comment to reflect that v5 shape is required in the webview payload.
  packages/vscode-extension/src/webview/components/ImportAssetsPanel.tsx:123
• getDefaultTargetConfig(project) can throw (and will do so during render) if defaultTarget is missing or the target isn’t present, which would crash the Import Assets panel. Consider resolving the target config once with a safe fallback (e.g., empty env list) rather than calling a throwing helper directly in render-time state initialization.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

Copilot reviewed 73 out of 75 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.