VS Code Extension

VS Code Extension

The Bino Reports VS Code extension provides schema-aware YAML editing, navigation, validation, preview, and dependency graph exploration for Bino report manifests.

NOTE: Screenshot placeholders are included below. Replace them with real images when you have them.

Bino Explorer

Browse all Bino manifests in your workspace, grouped by kind (ReportArtefact, DataSource, DataSet, LayoutPage, etc.), with inline children for layouts and quick navigation.

Smart Editing

Get completions, go-to-definition, and hover information for datasets, datasources, layouts, and more, all powered by the bino CLI.

Validation & Preview

Validate your workspace, see problems inline, and run the preview server directly from VS Code.

Graph Navigation

Explore dependencies and dependents ("What uses this?") using the manifest dependency graph, with click-to-open navigation.

Beyond YAML editing, the extension also ships a schema-driven Designer webview, a DataSource creation Wizard, a Tree/Table Editor, and PRQL editing support — see sections 9–12 below.

Architecture

• bino lsp — a real Language Server Protocol process, started automatically over stdio, provides live diagnostics, completion, hover, go-to-definition, find-references, rename, and quick-fixes.
• bino daemon — an optional persistent background process (enabled by default, see bino.daemon.enabled) that both the LSP and the extension's data/preview/build features share, so indexing, validation, and DuckDB column introspection stay warm across requests instead of paying a cold-start cost on every call.
• When the daemon is unavailable, the extension automatically falls back to invoking discrete bino lsp-helper <subcommand> CLI calls for indexing and data introspection.

---

1. Prerequisites

Before installing the extension, make sure you have:

• VS Code 1.85.0 or newer
• Bino CLI installed and on your PATH (or a known location)
• RedHat YAML extension (redhat.vscode-yaml) installed

---

2. Installation

2.1 From the Marketplace

You can install the extension directly from the VS Code Marketplace.

Alternatively:

1. Open the Extensions view in VS Code.
2. Search for "Bino Reports".
3. Click Install.

Once installed, the extension activates automatically when you open a YAML file or the Bino Reports explorer view.

2.2 From a .vsix (local build)

If you are working from this repository and packaging the extension yourself:

cd vscode-bino
npm install
npm install -g @vscode/vsce
vsce package --allow-missing-repository

code --install-extension ./vscode-bino-0.1.0.vsix

Then reload VS Code:

Cmd+Shift+P → "Developer: Reload Window"

To uninstall a locally installed build:

code --uninstall-extension bino.vscode-bino

---

3. First-Time Setup

3.1 Check your setup

Run the Bino: Check Setup command:

1. Press Cmd+Shift+P / Ctrl+Shift+P.
2. Run "Bino: Check Setup".

This command verifies:

• Whether the bino CLI can be found.
• Whether required subcommands (like lsp-helper and validate) are available.
• Basic version and environment information.

If something is wrong, the command shows a detailed message.

---

4. Bino Views

The Bino Reports activity bar container (click the Bino icon in the Activity Bar) holds four views:

• Documents (binoDocuments) — all indexed manifests, grouped by kind.
• Preview & Build (binoPreview) — preview/build/validate/graph action buttons.
• Scaffolding (binoActions) — shortcuts to the Add * commands, grouped by category.
• Environment (binoEnvironment) — CLI/project info, diagnostics counts, and settings shortcuts.

What you see in Documents:

• Documents grouped by kind (ReportArtefact, DataSource, DataSet, LayoutPage, LayoutCard, Table, Text, etc.).
• Count badges on each kind group.
• Icons that reflect the manifest kind (database for DataSource, table for DataSet, PDF icon for ReportArtefact, etc.).
• Inline children for layouts (LayoutPage, LayoutCard) – nested Text/Table/Chart components.

Screenshot placeholder:

![VS Code Bino Explorer placeholder](../assets/vscode-bino-explorer-placeholder.png)

4.1 Interactions

• Click a document to open it.
  • If the document has problems, the editor jumps to the first diagnostic.
  • Otherwise, it jumps to the start of that YAML document (supports multi-doc files).
• Click an inline child (component) to open the parent file and focus the correct line.
• Refresh / Validate:
  • Use the toolbar buttons at the top of the Bino Explorer:
    • Refresh Index – bino.refreshIndex
    • Validate Workspace – bino.validateWorkspace

4.2 Context Menu

Right-click on a document in the Bino Explorer to access:

• Go to First Problem – jumps to the first diagnostic in that file.
• Show Graph (Dependencies & Dependents) – opens a QuickPick built from the dependency graph.
• Show Dependencies – shows what this document depends on.
• Show Dependents (What Uses This?) – shows what uses this document.

---

5. Smart Editing Features

5.1 Autocompletion

The extension provides completions in YAML files for:

• dataset: / dependencies: – suggests DataSet names and $DataSource references.
• source: – suggests DataSource names.
• secret: – suggests ConnectionSecret names.
• signingProfile: – suggests SigningProfile names.
• selectedStyle: – suggests defined ComponentStyle names.
• kind: fields – suggests all known Bino kinds.
• Scenario/variance references – suggests column names based on the referenced dataset/datasource.
• Inside query:/prql: blocks – suggests real DuckDB column names from the bound source.

Completion, hover, diagnostics, and navigation are all served by the bino lsp Language Server — a real LSP process, not the older CLI-subprocess model.

Screenshot placeholder:

![VS Code completion placeholder](../assets/vscode-bino-completion-placeholder.png)

5.2 Go to Definition, Find References, Rename

Ctrl/Cmd+Click (or F12) on:

• dataset: / dependencies: values → jumps to the DataSet or DataSource.
• source: → DataSource.
• secret: → ConnectionSecret.
• signingProfile: → SigningProfile.
• selectedStyle: → ComponentStyle.
• page: / layoutPages: entries → LayoutPage.
• ref: (layout children) → the referenced component, resolved via its sibling kind.

Shift+F12 (Find All References) and F2 (Rename Symbol) work on any metadata.name and update every reference site across the workspace. Quick fixes (💡) are offered for a missing ${VAR} in .env, a missing required schema field, or a dangling reference (scaffolds the missing manifest).

Definitions/references are resolved from a live workspace name index and support multi-document YAML and unsaved edits.

5.3 Hover Information

Hover over dataset/datasource references to see:

• The kind (DataSet or DataSource).
• A preview of available columns.

Columns are introspected live via DuckDB (through the bino daemon when running) with caching (configurable TTL).

Screenshot placeholder:

![VS Code hover placeholder](../assets/vscode-bino-hover-placeholder.png)

---

6. Validation

Live diagnostics are pushed continuously by the bino lsp Language Server as you type (schema errors, engine-constraint violations) and, on every disk change, project-wide (lint findings, missing ${VAR} environment variables) — no manual step is required.

6.1 Manual Validation

Use the Bino: Validate Workspace command or the toolbar button in the Bino Views for an explicit, on-demand re-check — useful right after installing or when the daemon isn't running.

• Reports schema and configuration errors as VS Code diagnostics.
• Problems appear in the Problems panel and inline in the editor.

6.2 Validate on Save

bino.validateOnSave (default: true) is a fallback for when the bino daemon isn't running: it re-runs a workspace validation pass on save. When the daemon is connected, it already pushes fresh diagnostics on every file change, so this setting has no additional effect.

6.3 Diagnostics in the Explorer

• Document items show badges when there are diagnostics.
• The Go to First Problem context menu item jumps directly to the first issue.

Screenshot placeholder:

![VS Code validation placeholder](../assets/vscode-bino-validation-placeholder.png)

---

7. Preview and Build

7.1 Preview Server

The extension integrates with the bino preview command via a Preview Manager:

• Start: Bino: Start Preview (bino.startPreview)
• Stop: Bino: Stop Preview (bino.stopPreview)
• Restart: Bino: Restart Preview (bino.restartPreview)
• Open in browser: Bino: Open Preview in Browser (bino.openPreviewInBrowser)

A status item in the VS Code status bar shows the preview state (stopped/starting/running/error).

7.2 Preview Menu

Run Bino: Preview Menu (bino.previewMenu) to get a QuickPick of preview-related actions.

7.3 Build Command

Run Bino: Build Report (bino.build) to execute bino build from within VS Code.

Screenshot placeholder:

![VS Code preview placeholder](../assets/vscode-bino-preview-placeholder.png)

---

8. Dependency Graph Navigation

The extension queries the manifest dependency graph (via the bino daemon, falling back to bino lsp-helper graph-deps) to show dependencies and dependents as a QuickPick list. For a plain-text tree/flat view instead, run Bino: Show Graph (Tree) / Bino: Show Graph (Flat), which runs bino graph in the integrated terminal.

8.1 Opening the Graph

In the Bino Explorer:

1. Right-click any document (DataSet, DataSource, LayoutPage, ReportArtefact, etc.).
2. Choose one of:
   • Show Graph (Dependencies & Dependents)
   • Show Dependencies
   • Show Dependents (What Uses This?)

The extension runs a graph query for the selected node and opens a QuickPick listing related nodes.

8.2 Reading the QuickPick

Each entry shows:

• Label: kind: name with an icon.
• Description: relative file path.
• Detail: relationship to the root node:
  • ↓ dependency – this node is a dependency (what the root uses).
  • ↑ dependent – this node depends on the root (what uses the root).
  • ↕ both – this node is both dependent and dependency.

Selecting an item:

• Opens the corresponding file.
• Attempts to jump to the correct document position based on the workspace index.

Screenshot placeholder:

![VS Code graph placeholder](../assets/vscode-bino-graph-placeholder.png)

---

9. Designer

Run Bino: Open Designer (or right-click a rendered component and choose Open in Designer) to edit a Table/Chart/Text/Tree/Grid manifest through a schema-driven property form instead of raw YAML.

• Fields are generated from the merged JSON schema for the manifest's kind.
• IBCS-specific fields (scenario, variance, stack, aggregate, edges) get purpose-built pickers instead of free-text input.
• A dataset/column picker is wired to live DuckDB column introspection.
• Edits are applied as scoped YAML patches (via the same authoring path as quick-fixes and the Add-Element flow), so the rest of the file — comments, formatting, unrelated fields — is left untouched.

---

10. DataSource Wizard

Run Bino: New DataSource from File… (also available by right-clicking a .csv/.tsv/.xlsx/.xls/.parquet file in the Explorer) or Bino: New DataSource from Database… to scaffold a new DataSource + DataSet pair.

The wizard:

1. Introspects the source (sampling up to bino.wizard.sampleRowLimit rows).
2. Shows detected columns and inferred types.
3. Lets you pick which columns to include and preview the generated query.
4. Scaffolds the DataSource and DataSet manifests into the workspace.

---

11. Tree/Table Editor & Rows Preview

• Bino: Open Tree Editor (button in the editor title bar for Tree-kind manifests) opens a spreadsheet-like grid/property editor for hierarchical Tree documents, instead of editing nested YAML by hand.
• Bino: Preview Rows (100 rows) — also available as a CodeLens directly above DataSource/DataSet manifests — opens a webview showing a live 100-row data sample for that source.

---

12. PRQL Support

When editing a query:/prql: block written in PRQL instead of SQL:

• The block gets syntax highlighting.
• Bino: Open PRQL Editor opens the block in a dedicated editor.
• Bino: Open PRQL SQL Preview shows the SQL DuckDB will actually run.

Installing the optional PRQL VS Code extension adds richer PRQL-native editing on top of this.

---

13. Configuration Reference

All settings live under the Bino Reports section in VS Code Settings.

Setting	Type	Default	Description
bino.binPath	string	""	Path to the bino CLI executable. If not set, uses bino from PATH.
bino.columnCacheTTL	number	60000	Column cache TTL (ms) for hover/completion column lookups.
bino.validateOnSave	boolean	true	Fallback validation on save when the daemon isn't running (see 6.2).
bino.previewPort	number	3000	Port number for the bino preview server.
bino.daemon.enabled	boolean	true	Enable the persistent background daemon for faster indexing/validation/data.
bino.wizard.sampleRowLimit	number	100	Max sample rows the DataSource wizard fetches when introspecting a source.

Example configuration:

{
  "bino.columnCacheTTL": 120000,
  "bino.validateOnSave": true,
  "bino.previewPort": 3100,
  "bino.daemon.enabled": true
}

---

14. Troubleshooting

14.1 Bino CLI Not Found

• Symptom: Setup check fails, commands log errors like bino: command not found.
• Fix:
  • Ensure the CLI is installed and on your PATH.

14.2 No Completions or Hovers

• Confirm the file contains apiVersion: bino.bi/v1alpha1 and a recognized kind:.
• Check the Bino Reports output channel for bino lsp startup errors.
• Run Bino: Restart Daemon, or reload the window, to restart the language server.

14.3 Validation Errors

• Open the Problems panel to see details.
• Use Go to First Problem from the Bino Explorer context menu for a document.

14.4 Debug Logs

• Open the Bino Reports output channel:
  • View → Output, then select Bino Reports from the dropdown.
• All CLI invocations and errors from the indexer are logged here.

---

This page is a living document. As the VS Code extension grows (new commands, graph views, or additional editor integrations), update this page to keep it in sync with the implementation.