How to Contribute to the Lum1104/Understand-Anything Project and Run Tests Locally

To contribute to Understand-Anything, fork the repository, install dependencies with pnpm install, build the core engine with pnpm --filter @understand-anything/core build, and run tests using pnpm test or workspace-specific filters.

The Understand-Anything project is an open-source monorepo that helps developers visualize and understand complex codebases through AI-powered knowledge graphs. Whether you want to fix bugs, add new skills, or improve the React dashboard, this guide walks you through the complete setup process to contribute to the Lum1104/Understand-Anything project and validate your changes with the local test suite.

Project Structure Overview

Understand-Anything uses pnpm workspaces to organize a monorepo architecture. The source code lives under understand-anything-plugin/ and is logically separated into four distinct layers.

Core Engine

The core engine resides in understand-anything-plugin/packages/core. This package parses source files, builds the knowledge graph, and exposes type-safe APIs through sub-path exports like ./search, ./types, and ./schema. The dashboard consumes these browser-safe exports to render the graph visualization.

Dashboard UI

The dashboard package at understand-anything-plugin/packages/dashboard is a React + Vite application featuring React Flow for graph visualization, Zustand for state management, and Tailwind v4 for styling. It loads the generated graph from .understand-anything/knowledge-graph.json and displays it in a dark-luxury theme.

Plugin & Skills Layer

The plugin layer in understand-anything-plugin/src contains the glue code that exposes commands such as /understand, /understand-dashboard, and /understand-chat to various AI coding platforms. Key entry points include understand-chat.ts and onboard-builder.ts.

AI Agents

The agents are defined in understand-anything-plugin/agents/*.md as prompt files. These drive the multi-agent pipeline including the project-scanner, file-analyzer, and architecture-analyzer agents.

Prerequisites and Initial Setup

Before contributing, ensure your environment meets the version requirements specified in the root package.json.

System Requirements

• Node.js ≥ 22
• pnpm ≥ 10 (pinned via the packageManager field)

Fork and Clone

Follow the detailed steps in the CONTRIBUTING.md guide, then clone your fork:

git clone https://github.com/YOUR_USERNAME/Understand-Anything.git
cd Understand-Anything

Install Dependencies

Run the following command to resolve all workspace packages:

pnpm install

This installs dependencies for the core, dashboard, and plugin packages simultaneously.

Building the Workspace

You must build the core engine before running tests or launching the dashboard, as the dashboard depends on the compiled browser-safe exports.

pnpm --filter @understand-anything/core build

This command compiles the TypeScript sources in understand-anything-plugin/packages/core/src and generates the distribution files required by the dashboard.

How to Run Tests Locally

The project uses Vitest for testing. Tests are co-located with source code in __tests__/ directories and use the standard describe, it, and expect API.

Running Core Tests

To execute only the core engine tests:

pnpm --filter @understand-anything/core test

Running Skill Tests

To test the plugin and skills layer:

pnpm --filter @understand-anything/skill test

Running the Full Test Suite

For a complete validation across all workspaces:

pnpm test

This executes the entire test suite as defined in the root workspace configuration.

Test File Locations and Structure

Test files live in __tests__/ directories adjacent to the code they cover. For example, understand-anything-plugin/src/__tests__/context-builder.test.ts contains tests for the context builder utility.

Here is a minimal test example from the source:

import { describe, it, expect } from 'vitest';
import { buildContext } from '../context-builder';

describe('Context Builder', () => {
  it('produces a valid graph node for a simple file', async () => {
    const ctx = await buildContext(['src/example.ts']);
    expect(ctx.nodes).toContainEqual(
      expect.objectContaining({ type: 'function', name: 'myFunction' })
    );
  });
});

Development Workflow for Contributors

Follow these steps to ensure your contribution meets the project standards.

Branch Naming and Commits

Create a descriptive branch for your changes:

git checkout -b feat/add-search-component

Follow the conventional commit format using prefixes like feat:, fix:, docs:, and refactor:.

Code Style Guidelines

Maintain consistency with the existing codebase:

• Use 2-space indentation
• Follow ESLint rules enforced in the workspace
• Avoid any types; adhere to the TypeScript strict guidelines detailed in CONTRIBUTING.md

Submitting Your Pull Request

Before submitting:

1. Add tests covering new behavior and edge cases
2. Run the full test suite with pnpm test
3. Verify linting with pnpm lint
4. Confirm builds pass with pnpm build
5. Fill out the PR checklist regarding code style, tests, and documentation

The GitHub Actions workflow in .github/workflows/ci.yml runs these same checks when you open a PR.

Local Dashboard Development (Optional)

To view your changes in the interactive UI after building the core:

pnpm dev:dashboard

This starts the Vite development server for the dashboard package, loading the knowledge graph from your local .understand-anything/knowledge-graph.json file.

Summary

• Understand-Anything is a pnpm workspace monorepo with core, dashboard, and plugin packages.
• Prerequisites are Node.js ≥ 22 and pnpm ≥ 10.
• Build the core with pnpm --filter @understand-anything/core build before testing.
• Run tests using pnpm --filter @understand-anything/core test, pnpm --filter @understand-anything/skill test, or pnpm test for the full suite.
• Tests are located in __tests__/ directories using the Vitest framework.
• Follow conventional commits and avoid any types to pass CI checks.

Frequently Asked Questions

What Node.js version is required to contribute to Understand-Anything?

The project requires Node.js version 22 or higher, as specified in the root package.json and CONTRIBUTING.md files. Using older versions may cause compatibility issues with the pnpm workspace structure.

How do I run only the dashboard tests?

Currently, the dashboard package focuses on UI development, while core logic tests reside in the core and skill packages. Run pnpm --filter @understand-anything/core test for engine tests and pnpm --filter @understand-anything/skill test for plugin logic. The dashboard itself is validated through the build process and manual testing via pnpm dev:dashboard.

Where are the test files located in the Understand-Anything repository?

Test files follow a co-location pattern, residing in __tests__/ directories next to their source files. For example, tests for the context builder are found at understand-anything-plugin/src/__tests__/context-builder.test.ts, while core engine tests live in understand-anything-plugin/packages/core/src/__tests__/.

What commit convention does the project follow?

Contributors must use conventional commits with prefixes like feat: for features, fix: for bug fixes, docs: for documentation, and refactor: for code restructuring. This standard is enforced to maintain a clean git history and enable automated changelog generation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}