Implementation:TobikoData Sqlmesh Project Context

Knowledge Sources	TobikoData_Sqlmesh
Domains	Web_UI, State_Management, Testing
Last Updated	2026-02-07 20:00 GMT

Overview

State management store for SQLMesh project structure, file system navigation, and test execution results.

Description

The Project_Context module implements a Zustand store managing the SQLMesh project's file system structure, active file selections, artifact visibility ranges, and test execution results. It provides the ModelDirectory tree structure for navigating project files, methods for finding artifacts by path, and test result tracking with detailed failure information.

Usage

Use this context to access the project's file tree structure, track the currently selected file for editing, filter visible artifacts in the UI, and display test execution results with detailed error messages.

Code Reference

Source Location

Repository: TobikoData_Sqlmesh
File: web/client/src/context/project.ts

Signature

export interface Tests {
  ok: boolean
  time: number
  title: string
  total: string
  successful: number
  failures: number
  errors: number
  dialect: string
  traceback: string
  details: Array<{ message: string; details: string }>
  message?: string
}

interface ProjectStore {
  activeRange: ModelArtifact[]
  setActiveRange: (activeRange?: ModelArtifact[]) => void
  project: ModelDirectory
  setProject: (project?: ModelDirectory) => void
  tests?: Tests
  setTests: (tests?: Tests) => void
  files: Map<ID, ModelFile>
  setFiles: (files: ModelFile[]) => void
  selectedFile?: ModelFile
  setSelectedFile: (selectedFile?: ModelFile) => void
  findArtifactByPath: (path: string) => ModelArtifact | undefined
  refreshFiles: (files?: ModelFile[]) => void
  inActiveRange: (artifact: ModelArtifact) => boolean
}

export const useStoreProject = create<ProjectStore>()

Import

import { useStoreProject } from '~/context/project'

I/O Contract

Key State Properties

Name	Type	Description
project	ModelDirectory	Root directory of the SQLMesh project file tree
files	Map<ID, ModelFile>	All project files indexed by unique ID
selectedFile	ModelFile	Currently selected file for editing/viewing
activeRange	ModelArtifact[]	Filtered artifacts currently visible in UI
tests	Tests	Most recent test execution results

Key Methods

Name	Parameters	Description
setProject	ModelDirectory	Update entire project structure
setFiles	ModelFile[]	Update file registry
setSelectedFile	ModelFile	Select file for editing
setActiveRange	ModelArtifact[]	Filter visible artifacts
findArtifactByPath	path	Locate artifact by file path
inActiveRange	artifact	Check if artifact is visible
setTests	Tests	Update test execution results
refreshFiles	files	Refresh file list from project or provided array

Implementation Details

Project Structure

The ModelDirectory represents a hierarchical file system:

Directories: Contain subdirectories and files
Files: SQLMesh models, tests, audits, macros
Artifacts: Abstract base for all file system entries

Active Range Filtering

The activeRange allows filtering the project tree:

Used for search results display
Folder expansion states
Model dependency highlighting
File system navigation focus

Test Results

Test execution results include:

Summary metrics: Total, successful, failures, errors
Execution time: Test suite duration
Dialect: SQL engine used for testing
Detailed failures: Individual test messages with stack traces
Traceback: Full error context for debugging

File Registry

Files are indexed by ID for O(1) lookup:

Supports rapid file operations
Prevents duplicate file instances
Enables efficient file reference tracking

Usage Examples

import { useStoreProject } from '~/context/project'

function ProjectExplorer() {
  const {
    project,
    selectedFile,
    setSelectedFile,
    findArtifactByPath,
    activeRange,
    setActiveRange,
    tests
  } = useStoreProject()

  // Find artifact by path
  const artifact = findArtifactByPath('models/staging/users.sql')

  // Select file for editing
  if (artifact && artifact.isFile) {
    setSelectedFile(artifact as ModelFile)
  }

  // Filter visible artifacts (search results)
  const searchResults = project.allFiles.filter(f =>
    f.name.includes('users')
  )
  setActiveRange(searchResults)

  // Check if artifact is visible
  const isVisible = inActiveRange(artifact)

  // Display test results
  if (tests) {
    console.log(`Tests: ${tests.successful}/${tests.total}`)
    console.log(`Failures: ${tests.failures}`)
    tests.details.forEach(detail => {
      console.error(detail.message)
    })
  }

  return (
    <div>
      <h3>Selected: {selectedFile?.name}</h3>
      <p>Visible artifacts: {activeRange.length}</p>
    </div>
  )
}

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment