mirror of https://github.com/Egonex-AI/Understand-Anything.git synced 2026-06-22 10:58:03 +08:00

Files

T

Lum1104 c6f5409111 fix(dashboard): preserve sidebar composition + restore slide-up code viewer

Two issues from review of #108:

1. Sidebar exclusivity regression — replacing the entire sidebar with the
   CodeViewer when codeViewerOpen hid NodeInfo / LearnPanel / ProjectOverview
   while reading source. Same pattern that was rejected in #50. Restore the
   slide-up bottom overlay (per CLAUDE.md), keep sidebar tabs always visible,
   and revert the <aside> overflow-hidden change so long content can scroll.

2. Cross-graph mismatch (Codex P1) — FileExplorer always builds its tree from
   the structural graph and emits structural node IDs, but CodeViewer resolved
   IDs against the domain graph in domain mode, yielding "No file selected".
   Fall back to the structural graph when the active graph misses, so the
   Files tab works regardless of viewMode.

Also update CLAUDE.md to describe the Files tab + modal expand behavior so
future Claude sessions don't re-introduce the slide-up regression.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-01 17:28:08 +08:00

5.4 KiB

Raw Blame History

Understand Anything

Project Overview

An open-source tool combining LLM intelligence + static analysis to produce interactive dashboards for understanding codebases.

Prerequisites

Node.js >= 22 (developed on v24)
pnpm >= 10 (pinned via packageManager field in root package.json)

Architecture

Monorepo with pnpm workspaces
understand-anything-plugin/ — Claude Code plugin containing all source code:
- packages/core — Shared analysis engine (types, persistence, tree-sitter, search, schema, tours, plugins)
- packages/dashboard — React + TypeScript web dashboard (React Flow, Zustand, TailwindCSS v4)
- src/ — Skill TypeScript source for /understand-chat, /understand-diff, /understand-explain, /understand-onboard
- skills/ — Skill definitions (/understand, /understand-dashboard, etc.)
- agents/ — Agent definitions (project-scanner, file-analyzer, architecture-analyzer, tour-builder, graph-reviewer)

Dashboard

Dark luxury theme: deep blacks (#0a0a0a), gold/amber accents (#d4a574), DM Serif Display typography
Graph-first layout: 75% graph + 360px right sidebar
No ChatPanel or Monaco Editor
Sidebar tabs: Info (ProjectOverview default → NodeInfo when node selected → LearnPanel in Learn persona, composing) and Files (FileExplorer tree built from the structural graph)
Code viewer: prism-react-renderer source viewer that slides up from the bottom on file node click; an expand button promotes it into a full-screen modal. Source content is fetched from the dev server's /file-content.json endpoint, gated by access token + a graph-derived path allowlist
Schema validation on graph load with error banner

Agent Pipeline

Agents write intermediate results to .understand-anything/intermediate/ on disk (not returned to context)
Agent models: all set to inherit for cross-platform compatibility (Claude Code, Cursor, opencode, etc.)
/understand auto-triggers /understand-dashboard after completion
Intermediate files cleaned up after graph assembly

Key Commands

pnpm install — Install all dependencies
pnpm --filter @understand-anything/core build — Build the core package
pnpm --filter @understand-anything/core test — Run core tests
pnpm --filter @understand-anything/skill build — Build the plugin package
pnpm --filter @understand-anything/skill test — Run plugin tests
pnpm --filter @understand-anything/dashboard build — Build the dashboard
pnpm dev:dashboard — Start dashboard dev server
pnpm lint — Run ESLint across the project

Conventions

TypeScript strict mode everywhere
Vitest for testing
ESM modules ("type": "module")
Knowledge graph JSON lives in .understand-anything/ directory of analyzed projects
Core uses subpath exports (./search, ./types, ./schema) to avoid pulling Node.js modules into browser

Gotchas

tree-sitter: Uses web-tree-sitter (WASM) instead of native tree-sitter — native bindings fail on darwin/arm64 + Node 24
Dashboard imports: Dashboard must only import from core's browser-safe subpath exports (./search, ./types, ./schema), never the main entry point which pulls in Node.js modules

Scripts

scripts/generate-large-graph.mjs — Generates a fake knowledge graph for performance testing (e.g. large-graph layout). Writes to .understand-anything/knowledge-graph.json. Usage: node scripts/generate-large-graph.mjs [nodeCount] (default: 3000 nodes). Not part of the production pipeline.

Versioning

When pushing to remote, bump the version in all five of these files (keep them in sync):

understand-anything-plugin/package.json → "version" field
understand-anything-plugin/.claude-plugin/plugin.json → "version" field
.claude-plugin/plugin.json → "version" field
.cursor-plugin/plugin.json → "version" field
.copilot-plugin/plugin.json → "version" field

Note: .claude-plugin/marketplace.json does not carry a version — the plugins[] entry only supports name and source, and adding other fields causes marketplace schema validation failures.

Testing Local Plugin Changes

Claude Code caches installed plugins at ~/.claude/plugins/cache/understand-anything/understand-anything/<version>/. Symlinks don't work because Claude's Search/Glob tools can't follow them. To test local changes:

Build the packages:

pnpm --filter @understand-anything/core build
pnpm --filter @understand-anything/skill build

Find the installed version (must match what the marketplace currently serves):
```
ls ~/.claude/plugins/cache/understand-anything/understand-anything/
```

Copy your local plugin into the cache, replacing <VERSION> with the version from step 2:

rm -rf ~/.claude/plugins/cache/understand-anything/understand-anything/<VERSION>
cp -R ./understand-anything-plugin ~/.claude/plugins/cache/understand-anything/understand-anything/<VERSION>

Start a fresh Claude Code session (existing sessions cache the old prompts in context).
Run /understand --full in the target project to verify.

Re-sync after further changes:

pnpm --filter @understand-anything/core build && \
cp -R ./understand-anything-plugin/* ~/.claude/plugins/cache/understand-anything/understand-anything/<VERSION>/

To revert to upstream: Uninstall and reinstall the plugin from the marketplace — it repopulates the cache from the upstream repo.

5.4 KiB Raw Blame History