Scopes

Scopes provides named, workspace-level visibility profiles for the VS Code Explorer.

Scope configuration

The small manifest selects the active scope:

// .vscode/scopes.json
{
  "version": 3,
  "enabled": true,
  "active": "backend"
}

Each editable scope has its own stable, lowercase ID and definition file:

// .vscode/scopes/backend.json
{
  "name": "Backend",
  "rules": [
    { "pattern": "app/**", "visibility": "include" },
    { "pattern": "routes/**", "visibility": "include" },
    { "pattern": "resources/views/**", "visibility": "include" }
  ]
}

Project Files is a virtual, immutable scope. It includes the whole workspace and has no definition file. Renaming a custom scope changes its display name without changing its ID or filename.

Everything is excluded when no rule matches. Matching rules use CSS-like specificity: exact paths beat globs, deeper literal paths beat broader paths, fewer wildcards win after literal specificity, and a later rule wins an exact tie. An exact folder exclusion cascades through its descendants unless a more-specific descendant rule overrides it; an ordinary folder inclusion remains non-recursive. This allows a specific included subfolder or file to reopen part of a broader excluded parent while preserving the distinction between Include and Include All.

The extension resolves the workspace and converts the result to owned files.exclude entries in .vscode/settings.json. Existing user entries are preserved. Extension-owned patterns are recorded in the committed .vscode/scopes.state.json file. Scope metadata (.vscode/scopes, .vscode/scopes/**, .vscode/scopes.json, and .vscode/scopes.state.json) is always hidden globally as extension-owned configuration.

Compiled resolutions are cached locally under .vscode/scopes/.cache/. Cache entries are keyed by the resolver version, scope rules, workspace structure, and filesystem case sensitivity. The cache directory is ignored by Git; stale or corrupt entries are safely rebuilt.

Version 1 and 2 monolithic configurations are intentionally not migrated. A non-version-3 manifest is reported and left untouched.

Live updates and apply behavior

Scopes watches the manifest, individual definitions, generated state, workspace settings, and workspace file/folder creation, deletion, and rename events. Metadata and cache files are excluded from the workspace model to avoid watcher loops.

Pre-existing user-owned files.exclude rules remain global across every scope. Matching tree items are shown in red. Right-click a tree item to add a global exclusion or remove the matching user-owned global rule. Scope-generated exclusions remain visually distinct and are never presented as user-owned global rules.

The tree distinguishes why an item is hidden: unmatched items use a light neutral colour for the default-hidden baseline, explicit scope exclusions use a darker neutral colour, and global exclusions remain red with the highest visual priority. Included items are green and structurally mixed folders are yellow.

The manager previews rule edits immediately. Explorer changes occur only after Apply succeeds. While a scope is being applied, both the manager and Explorer scope list show an applying state. Definition, settings, state, and manifest writes are treated as one apply transaction and restored if a write fails.

Commands

• Scopes: Enable For Workspace
• Scopes: Select Scope
• Scopes: Create Scope
• Scopes: Rename Scope
• Scopes: Duplicate Scope
• Scopes: Delete Scope
• Scopes: Reset To Project Files
• Scopes: Refresh Active Scope
• Scopes: Open Scope Manager

Development

npm install
npm run compile
npm test

npm run watch rebuilds both the extension host and webview bundles.

License

Scopes is licensed under the GNU Affero General Public License v3.0 only. See LICENSE.