SWAT+ Dataset Selector

A VS Code extension for SWAT+ (Soil & Water Assessment Tool) development. It lets you select dataset folders, cross-index the model's many interlinked input files, navigate foreign keys with IDE-grade Go to Definition / hover / diagnostics, launch debug and run sessions against the active dataset, and explore inputs and outputs as tables, graphs, and notebooks.

Looking for a compact technical overview? See SPEC.md for the full specification sheet (platform, architecture, modules, commands, and tooling).

What This Repo Contains

This repository is the VS Code extension itself plus the tooling that generates its SWAT+ schema. It is a two-layer project:

• TypeScript extension (src/) — the VS Code extension host, webview panels (dataset selector sidebar, table viewers, dependency graph, output DataFrame explorer), and the language features (foreign-key definition/hover/diagnostics providers) that power navigation across SWAT+ input files.
• Python scripts (scripts/) — schema extraction from the swatplus-editor project, pandas-based indexing, and output→DataFrame conversion. These are invoked by the extension and can also be run standalone.
• Schema (resources/schema/) — the machine-readable schema the extension indexes and validates against, built from the SWAT+ Fortran source by Tamandua and rebuilt from your own checkout when one is in the workspace (how).
• Documentation (docs/) — deep-dive guides on indexing, schema, and file/FK relationships.

Features

• Select Dataset Folder: Browse to any SWAT+ dataset folder and make it active.
• Recent Datasets: Reopen recently used datasets from the sidebar.
• Dataset Folder Listing: Show datasets from a configured parent folder such as workdata/.
• Quick Debug Launch: Start debugging with the selected dataset as the working directory.
• Output Exploration: Open .csv / .out / .txt output files as DataFrames and generate Jupyter notebooks from them.
• Data Quality: Run a preflight report of unresolved references and orphan rows, plus an input-file checker for headers, column counts, data types, and required (non-nullable) values left empty or null — with each warning annotated by the column's documented meaning and units.
• Seamless Integration: Works with CMake Tools and gdb debugger configurations.
• Ask your dataset: Chat with @swat in the VS Code chat panel ("describe HRU 81", "which HRUs use this soil?"), run SWAT+: Describe Entity / SWAT+: Search Dataset in the editor, or expose the dataset to an external agent (Claude Code/Desktop) via a bundled MCP server — all backed by the same engine.
• Schema from SWAT+ source: which columns SWAT+ reads from each input file, in order, derived from the Fortran by Tamandua — so it follows your code and branch — with column names from your files' own headers and file links from the swatplus-editor schema. See Schema built from SWAT+ source.
• Enhanced Indexing: Pandas-backed indexing system with FK navigation, hover info, and validation.
  • Handles hierarchical files (soils.sol, plant.ini, management.sch)
  • Parses decision tables (*.dtl)
  • Supports Go to Definition for foreign keys
  • Shows hover tooltips with file purpose and FK targets
  • Shows column documentation on hover — meaning, units, type, the declaring source line, and the SWAT+ variable and statement that read it — straight from the Fortran via Tamandua
  • "Show SWAT+ names" in the table viewer shows the Fortran name under each column, and marks columns SWAT+ never reads
  • Warns on unresolved references
  • Builds a reverse index for incoming references

Documentation

• Schema Built from SWAT+ Source - How the schema follows your SWAT+ code, and what it checks
• Enhanced Indexing Guide - Complete guide to the indexing system
• Schema Enhancement - How markdown documentation enhances FK and pointer detection
• Extension File Schema - Detailed schema for SWAT+ files
• Dependency Analysis - Comprehensive FK and file relationships
• Input Schema Relationships Guide - Where to find FK and file pointer relationships
• Quick Reference - Quick lookup for common patterns
• Troubleshooting Guide - Solutions for common issues

Quick Start

1. Install the extension from the marketplace or build it from source.
2. Reload VS Code with Developer: Reload Window.
3. Open a SWAT+ project.
4. Click Set Up This Workspace in the sidebar (or run the command of the same name) to install Tamandua and wire up both its MCP server and this extension's own into .vscode/mcp.json and .mcp.json, plus a debug launch config if the Fortran ifx/GNU Debug extension is installed. Optional — everything below still works without it.
5. Select a dataset from the SWAT+ Dataset sidebar or run SWAT+: Select Dataset Folder.
6. Run SWAT+: Build Inputs Index.
7. Ctrl+Click foreign keys or filenames to navigate.

After pulling updates, reload VS Code so the latest extension bundle is active.

Commands

Setup

• SWAT+: Set Up This Workspace - Installs Tamandua via pip, wires up its MCP server and this extension's own bundled one (.vscode/mcp.json and .mcp.json), and hands off to the Fortran ifx/GNU Debug extension for a debug launch config and its MCP entry if that extension is installed.

Dataset

• SWAT+: Select Dataset Folder - Browse and select a dataset folder.
• SWAT+: Select Dataset and Debug - Browse for a dataset folder and launch debug immediately.
• SWAT+: Debug with Selected Dataset - Launch debug with the current dataset.
• SWAT+: Switch Dataset - Open a quick pick with recent datasets and dataset-folder entries.
• SWAT+: Reveal Dataset Folder in Explorer - Open the configured dataset folder in Explorer.
• Use as SWAT+ Dataset - Set the selected Explorer folder as the active dataset.

Index

• SWAT+: Build Inputs Index - Build an index of all SWAT+ input files in the selected dataset.
• SWAT+: Rebuild Inputs Index - Rebuild the current dataset index.
• SWAT+: Load Cached Index - Load a cached index from the dataset folder.
• SWAT+: Export Index to JSON - Export the current index to a JSON file.

Navigation & views

• SWAT+: Show FK References - List incoming references to the current row.
• SWAT+: View Tables - Open the multi-table viewer.
• SWAT+: Edit / Create Schema - Open the schema editor.
• SWAT+: Rebuild Schema from SWAT+ Source - Rebuild the schema from the SWAT+ checkout now, and show what it was built from.
• SWAT+: Show Dependency Graph - Open a graph of table-to-table dependencies.
• SWAT+: Describe Entity - Describe an entity (e.g. hru 81) — its columns, connections, and references.
• SWAT+: Search Dataset - Find rows by column predicate (e.g. slope > 0.1) or list unreferenced (orphan) rows.

Data quality

• SWAT+: Run Data Quality Preflight - Generate a markdown report with unresolved references and potential orphan rows.
• SWAT+: Check Input Files - Validate input file headers, column counts, and data types.

HRU subsets

Creating a reduced TxtInOut folder for selected HRUs is no longer part of this extension. It lives in its own extension, SWAT+ HRU Subset (hru-subset/ in this repository), which has the same panel (HRU IDs, keep routing, the tracked SWAT+ workarounds), an HRU picker table and a preview of the feeder HRUs a subset will add. It can use the dataset selected here: it asks this extension for it through swat-dataset-selector.getDatasetFolder.

Outputs

• SWAT+: Generate Output Notebooks - Generate Jupyter notebooks for output files.
• SWAT+: Explore Output File - Open an output file (.csv / .out / .txt) as a DataFrame.

Usage

Method 1: Select and Debug

1. Open the Command Palette.
2. Run SWAT+: Select Dataset and Debug.
3. Choose your dataset folder.
4. The debug session starts with that folder as the working directory.

Method 2: Select First, Debug Later

1. Open the Command Palette.
2. Run SWAT+: Select Dataset Folder.
3. Choose your dataset folder.
4. Later, run SWAT+: Debug with Selected Dataset.

Method 3: Use the Dataset Selector View

1. Open the SWAT+ Dataset view in the activity bar.
2. Select a dataset from Recent Datasets or Dataset Folder.
3. Use Debug to launch a debug session.
4. Use Build Index to index the selected dataset.

Within the view, the Inputs and Outputs lists each have a filter box — type part of a file name to narrow the list, Esc to clear. The category checkboxes narrow the inputs list by kind and combine with the filter. Pin a dataset in Recent Datasets with the star to keep it at the top of the list.

If input files change on disk after indexing, the view shows an Index out of date banner with a one-click Rebuild.

Method 4: Configure the Dataset Folder

1. Open the SWAT+ Dataset view.
2. In the Dataset Folder section, click the folder button.
3. Choose the parent directory that contains your dataset folders.
4. Select a dataset from that list.

Repository Layout

src/                 TypeScript extension source (~30 files)
  extension.ts         Entry point: activation and command registration
  indexer.ts           Cross-file input index, FK resolution, reverse index
  swatWebviewProvider  Dataset Selector sidebar webview
  *TableViewerPanel    Table / single-table data viewers
  fk*Provider          Foreign-key definition, hover, and diagnostics providers
  output*              Output DataFrame explorer and notebook generation
  test/                Mocha test suites
scripts/             Python tooling (schema extraction, pandas indexing, outputs)
resources/schema/    SWAT+ schema JSON: built from source (generated), editor, metadata
docs/                Deep-dive guides on indexing, schema, and FK relationships
esbuild.js           Bundler config (produces dist/extension.js)

How It Works

The extension launches a debug session with:

• Type: cppdbg
• Working Directory: The selected dataset folder
• Program: Resolved by CMake Tools via ${command:cmake.launchTargetPath}
• Environment: Includes the CMake launch target directory in PATH

This avoids manually editing launch.json whenever you want to debug against a different dataset.

SWAT+ Schema Extraction

The schema is built from SWAT+ source (see docs/SCHEMA_FROM_SOURCE.md). The swatplus-editor extraction below still supplies its file links and the tables the source does not cover; it discovers model classes from the swatplus-editor repository.

Quick Start

git clone https://github.com/swat-model/swatplus-editor.git /tmp/swatplus-editor
python3 scripts/extract_all_models.py

The generated schema is written to resources/schema/swatplus-editor-schema-full.json.

What Gets Extracted

• Table definitions
• Column metadata
• Foreign key relationships
• Primary keys

Update When SWAT Editor Changes

cd /tmp/swatplus-editor
git pull
python3 scripts/extract_all_models.py

Requirements

• VS Code ^1.106.1
• Jupyter extension (ms-toolsai.jupyter) — a required extension dependency
• CMake Tools extension for ${command:cmake.launchTargetPath}
• C/C++ extension for gdb debugging
• Properly configured CMake project
• Python 3.6+ with pandas>=2.2.0 for schema extraction and indexing

Extension Settings

• swatplus.datasetDirectory: Parent directory that contains SWAT+ dataset folders. Defaults to workdata.
• swatplus.schemaDirectories: Additional directories to scan for SWAT+ schema JSON files.
• swatplus.schemaFromSource: Build the schema from the SWAT+ source with Tamandua (default on). Off, or without Tamandua, the schema shipped with the extension (SWAT+ 62.0.0) is used.
• swatplus.sourceDirectory: SWAT+ checkout to build the schema from. Empty: the first workspace folder containing SWAT+ Fortran.
• swatplus.openTablesAfterIndex: What to do with the table viewers after an index build — prompt (default, offers to open them), always (opens them automatically), or never.
• swatplus.debugLogging: Log extension and sidebar activity to the developer console. Off by default; enable when diagnosing sidebar or navigation issues.

Development

Built with TypeScript, bundled with esbuild, and linted with ESLint.

npm install            # install dependencies
npm run compile        # type-check, lint, and bundle
npm run watch          # rebuild on change
npm run test           # run the VS Code test suite
npm run package        # production build (used for packaging the .vsix)

Press F5 in VS Code to launch an Extension Development Host with the extension loaded. See vsc-extension-quickstart.md for more.

Known Issues

• Ensure CMake Tools is configured before using debug commands.
• The debug configuration assumes gdb is available on your system.

Release Notes

0.0.1

Initial release of SWAT+ Dataset Selector

• Browse and select dataset folders
• Launch debug sessions with selected datasets
• Integration with CMake Tools and gdb