Commit Graph
198 Commits
Author SHA1 Message Date
Lum1104andClaude Opus 4.6 dc8dd7dd77 feat: add RubyExtractor for tree-sitter Ruby structural analysis
Handles methods, classes, modules, attr_* properties, require imports,
and call graph including bare identifier calls (no-arg method invocations).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 19:02:52 +08:00
Lum1104andClaude Opus 4.6 6e500cbfdf feat: add JavaExtractor for tree-sitter Java structural analysis
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 18:42:55 +08:00
Lum1104andClaude Opus 4.6 a1fb9585d3 feat: add RustExtractor for tree-sitter Rust structural analysis
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 18:38:26 +08:00
Lum1104andClaude Opus 4.6 f18cad61d5 feat: add GoExtractor for tree-sitter Go structural analysis
Implements the LanguageExtractor interface for Go, handling functions,
methods with receivers, structs, interfaces, imports, exports (via
capitalization convention), and call graph extraction. Includes 25 tests.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 18:33:18 +08:00
Lum1104andClaude Opus 4.6 398f5b15b0 feat: add PythonExtractor for tree-sitter Python structural analysis
Implements the LanguageExtractor interface for Python, extracting functions
(with type annotations, defaults, *args/**kwargs), classes (methods +
annotated properties), imports (plain, from, aliased, wildcard), exports
(top-level defs), and caller-callee call graphs. Includes 31 tests using
the real tree-sitter parser.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 18:28:38 +08:00
Lum1104andClaude Opus 4.6 2ad0563878 feat: add tree-sitter grammar deps and treeSitter configs for 10 languages
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 18:22:51 +08:00
Lum1104andClaude Opus 4.6 9376375c8c feat: add extractCallGraph to PluginRegistry, derive DEFAULT_PLUGIN_CONFIG from configs
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 18:20:31 +08:00
Lum1104andClaude Opus 4.6 ab011ff856 refactor: move TS/JS extraction logic to TypeScriptExtractor, dispatch via LanguageExtractor interface
Extract all TypeScript/JavaScript-specific AST extraction functions
(extractParams, extractReturnType, extractImportSpecifiers, processTopLevelNode,
extractFunction, extractClass, extractVariableDeclarations, extractImport,
processExportStatement, and call graph walking) from TreeSitterPlugin into the
new TypeScriptExtractor class. TreeSitterPlugin now dispatches to registered
LanguageExtractor instances, defaulting to TypeScriptExtractor for backward
compatibility. All 426 existing tests pass unchanged.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 18:17:09 +08:00
Lum1104andClaude Opus 4.6 4f954907ec feat: add LanguageExtractor interface and shared base utilities
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 18:12:07 +08:00
Lum1104andClaude Opus 4.6 6cba6de658 refactor: replace hardcoded EXTENSION_LANGUAGE map in GraphBuilder with LanguageRegistry
GraphBuilder maintained its own ~60-line extension-to-language mapping that
duplicated and could diverge from the canonical LanguageRegistry. Now delegates
language detection to LanguageRegistry.getForFile(), eliminating the duplication
and ensuring new language configs are automatically picked up everywhere.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 17:30:38 +08:00
JohnWongandClaude Opus 4.6 61a28c7d6c fix: include access token in auto-opened dashboard URL
CLI --open overrides server.open config, stripping the token. Remove
--open from CLI and set server.open to /?token= so the browser opens
with the access token already included.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-13 23:22:05 +08:00
Nikola Chetelyazov d11a9bb1c9 refactor: extract addChildNode helper to remove repeated boilerplate
All five child-node loops in addNonCodeFileWithAnalysis shared the same four-line pattern: dedup check, nodeIds.add, nodes.push, and a contains edge push. A private addChildNode helper centralises this so each loop only constructs the node object specific to its type.
2026-04-13 09:56:12 +03:00
Nikola Chetelyazov 45b98716ec fix: use localeCompare in languages sort for reliable alphabetical order
Default sort() uses Unicode code point ordering which can produce unexpected results for non-ASCII strings. localeCompare guarantees correct alphabetical ordering regardless of character set.
2026-04-13 09:52:13 +03:00
Nikola Chetelyazov e82235e1df refactor: return shallow copies of nodes and edges from build()
build() was returning direct references to the builder's internal arrays, allowing callers to mutate graph.nodes or graph.edges and corrupt the builder's state. Spreading into new arrays at build time prevents this at negligible cost.
2026-04-13 09:49:47 +03:00
Nikola Chetelyazov ef0c65aa17 refactor: deduplicate import and call edges via edgeKeys set
addImportEdge and addCallEdge previously pushed edges unconditionally, allowing duplicate relationships if multiple agents reported the same import or call. A shared edgeKeys set keyed on type|source|target silently skips any edge that has already been recorded.
2026-04-13 09:47:16 +03:00
Nikola Chetelyazov 5593af76ca refactor: extract endpoint label into variable to avoid duplicated template
The endpoint name template was evaluated twice — once for name and once for summary. A single const removes the duplication and resolves the nested template literal lint warning.
2026-04-13 09:44:17 +03:00
Nikola Chetelyazov 6c55ee303a refactor: return fileId from addNonCodeFile instead of recomputing it
addNonCodeFileWithAnalysis was reconstructing the fileId string independently of addNonCodeFile, creating a silent correctness risk if the ID construction logic ever changed. addNonCodeFile now returns the ID it used so the caller cannot go out of sync.
2026-04-13 09:41:12 +03:00
Nikola Chetelyazov 82b1d06777 refactor: extract basename helper to replace repeated split/pop pattern
The same filePath.split("/").pop() ?? filePath expression appeared three times across addFile, addFileWithAnalysis, and addNonCodeFile. A private static helper centralises the logic and makes call sites easier to read.
2026-04-13 09:35:55 +03:00
Nikola Chetelyazov a89555d369 refactor: promote nodeIds to class field to avoid O(n²) set rebuild
Previously addNonCodeFileWithAnalysis rebuilt a full Set from this.nodes on every call, making duplicate checks O(n) per file and O(n²) overall. Moving nodeIds to a class field and updating it incrementally at each insertion reduces duplicate detection to O(1) per check.
2026-04-13 09:33:18 +03:00
Nikola Chetelyazov c96a14c541 refactor: extract KIND_TO_NODE_TYPE as module-level constant in GraphBuilder
Previously the mapping object was recreated on every mapKindToNodeType call. Moving it to module level means it is allocated once at load time instead of once per definition node processed.
2026-04-13 09:28:02 +03:00
jiachenandClaude Opus 4.6 72953254d2 fix: add plugin manifest under understand-anything-plugin/.claude-plugin
marketplace.json declares plugins[0].source as ./understand-anything-plugin,
so Claude Code resolves the plugin manifest at
./understand-anything-plugin/.claude-plugin/plugin.json. That file did not
exist — only .claude-plugin/plugin.json at the repo root — causing
"Marketplace sync failed. Some plugins in this marketplace have validation
errors." when adding the marketplace via /plugin marketplace add.

Adds the manifest at the path the marketplace source expects, so marketplace
sync validates and the plugin can be installed. Version matches the current
root plugin.json (2.3.1).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-12 17:22:30 +08:00
Lum1104andClaude Opus 4.6 ca5e3b8e21 chore: bump version to 2.3.1
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-12 15:23:50 +08:00
Lum1104andClaude Opus 4.6 55fc2ac848 fix: sync Phase 0.5 inline script with .gitignore integration and header fix
The skill's inline Node.js generator was duplicated from core and missed
the .gitignore seeding and bin/ header fix. Updated the one-liner to read
.gitignore patterns, deduplicate against defaults with trailing-slash
normalization, and remove bin/ from the built-in defaults header comment.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-12 11:47:55 +08:00
Lum1104andClaude Opus 4.6 6ef1a21315 feat: seed .understandignore with .gitignore patterns on first generation
Read the project's .gitignore at starter-file generation time and include
non-default patterns as commented suggestions in .understandignore. Patterns
already covered by hardcoded defaults are deduplicated (with trailing-slash
normalization). This is a one-time inclusion — users can later remove patterns
for files they want analyzed without the filter re-reading .gitignore.

Also fixes the starter header listing bin/ as a built-in default when it is
intentionally excluded from DEFAULT_IGNORE_PATTERNS (bin/ is used by Node/Ruby
CLI launchers).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-12 11:39:31 +08:00
Lum1104 bc311c80ad Merge branch 'main' into feat/understandignore 2026-04-12 11:34:10 +08:00
Lum1104andClaude Opus 4.6 1d15851905 fix: highlight connected edges on node selection in knowledge view
Connected edges now highlight (thicker, full opacity) when a node is
selected/focused. Unconnected edges dim to near-invisible. Edge labels
only show on connected edges to reduce visual noise.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-12 11:24:17 +08:00
Lum1104andClaude Opus 4.6 7e41ba7a68 fix: address Codex review — stable layout, scoped infra filter, basename dedup
P1: Separate force layout computation from visual state updates so
clicking/searching/touring doesn't re-randomize node positions. Layout
only recomputes when the graph data or filters change.

P1: Restrict infrastructure-file skipping (index.md, log.md, etc.) to
the wiki root level only. Nested files like concepts/index.md are now
correctly treated as content articles.

P2: Track ambiguous bare basenames in the wikilink resolution map.
Duplicate basenames (e.g., a/foo.md and b/foo.md) are removed from
the flat lookup so [[foo]] doesn't silently resolve to the wrong page.

Also fixed: edge IDs now use stable source-target-type keys instead of
array indices for proper React reconciliation.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-12 11:21:24 +08:00
Lum1104andClaude Opus 4.6 2fc85e68c3 feat: add /understand-knowledge for Karpathy LLM wiki knowledge bases
Support the Karpathy LLM wiki pattern — a three-layer architecture
(raw sources + wiki markdown + schema) with wikilinks, index.md
categories, and append-only log.md.

Pipeline:
- parse-knowledge-base.py: deterministic extraction of articles,
  wikilinks, categories from index.md, source nodes from raw/
- article-analyzer agent: LLM-based entity/claim extraction and
  implicit relationship discovery (builds_on, contradicts, etc.)
- merge-knowledge-graph.py: combines scan + analysis with entity
  dedup, layer assignment from categories, tour generation

Dashboard:
- KnowledgeGraphView with d3-force layout (community clustering
  by index.md categories, degree-proportional sizing)
- 5 knowledge node types (article, entity, topic, claim, source)
- 6 knowledge edge types with visual styling
- KnowledgeNodeDetails sidebar (wikilinks, backlinks, preview)
- Auto-detect kind:"knowledge" → knowledge-only view mode

Core:
- 5 node types + 6 edge types added to NodeType/EdgeType unions
- KnowledgeMeta interface (wikilinks, backlinks, category, content)
- kind field on KnowledgeGraph for view mode detection
- Zod schemas + node/edge type aliases

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-12 11:09:41 +08:00
Lum1104andClaude Opus 4.6 d3de6dc1fd fix: address code review — remove bin/ from defaults, fix negation override flow
- Remove bin/ from DEFAULT_IGNORE_PATTERNS (Node/Ruby CLI launchers use bin/)
- .NET users can add bin/ to .understandignore manually
- Fix project-scanner Step 2.5 to re-filter from original file list when
  .understandignore exists, ensuring ! negation correctly overrides defaults

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-10 11:51:59 +08:00
Lum1104andClaude Opus 4.6 59a6f56bfe feat(skill): add Phase 0.5 for .understandignore setup and review pause
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-10 11:39:45 +08:00
Lum1104andClaude Opus 4.6 3e27a4a8d4 feat(agent): add .understandignore support and bin/obj exclusions to project-scanner
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-10 11:38:23 +08:00
Lum1104 4201cbcb9e feat(core): export IgnoreFilter and IgnoreGenerator from core index 2026-04-10 11:36:53 +08:00
Lum1104andClaude Opus 4.6 6f8270fb37 feat(core): add IgnoreGenerator for starter .understandignore file creation
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-10 11:36:23 +08:00
Lum1104andClaude Opus 4.6 5e86254b77 feat(core): add IgnoreFilter module with .understandignore parsing and tests
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-10 11:33:10 +08:00
Lum1104 07b02d18ae chore(core): add ignore package for .understandignore support 2026-04-10 11:30:52 +08:00
Lum1104andClaude Opus 4.6 1842541a93 fix: include access token in dashboard URL reported to user
The understand-dashboard skill now instructs agents to capture and
share the full tokenized URL from the Vite server output, so users
are not blocked by the token gate.

Bump version to 2.2.1.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-09 22:50:20 +08:00
Lum1104andClaude Opus 4.6 660f766783 fix: coerce edge weights to float before comparison in merge scripts
Prevents TypeError crash when LLM batches emit mixed weight types
(e.g. 0.8 vs "0.7") during edge deduplication.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-04 12:50:04 +08:00
Lum1104andClaude Opus 4.6 52050e40cb fix: address PR #71 review findings and bump version to 2.2.0
Fix all actionable code review items: add missing domain/flow/step node
types, fix batch numeric sorting, align gate thresholds, merge duplicate
tour steps instead of dropping, add Writing Results section to
assemble-reviewer, use skill-relative script paths, and add func→function
type mapping.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-04 12:28:20 +08:00
Lum1104andClaude Opus 4.6 b3683d62e2 feat: add graph merge scripts and improve agent pipeline reliability
Add Python scripts to merge knowledge graphs (closes #70) and move
mechanical normalization out of LLM context into deterministic scripts
with diagnostic reporting. Convert all agent definitions from dispatch
templates to self-contained system prompts to prevent instruction loss.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-04 11:56:58 +08:00
Lum1104andClaude Opus 4.6 d6a80224b6 feat: add live demo dashboard on GitHub Pages
Add a demo mode to the dashboard that fetches graph data from Supabase
Storage instead of the local Vite dev server, bypasses the token gate,
and deploys alongside the homepage at /Understand-Anything/demo/.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-03 11:49:00 +08:00
Lum1104andClaude Opus 4.6 63ee658478 fix(dashboard): auto-widen domain graph spacing for long edge labels
Instead of truncating cross_domain edge labels, compute ranksep from
the longest label length (~6px/char) so dagre spaces nodes further
apart. Also add label background for readability, and support
spacingOverrides parameter in applyDagreLayout.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-03 00:17:20 +08:00
Lum1104andClaude Opus 4.6 6d01c449c5 chore: update pnpm-lock.yaml
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-03 00:05:10 +08:00
Lum1104andClaude Opus 4.6 20eb483195 fix(dashboard): address 8 audit issues across dashboard components
1. Add infrastructure edge category to EDGE_CATEGORY_MAP for 8 missing
   edge types (deploys, serves, provisions, triggers, migrates, documents,
   routes, defines_schema) — previously unfiltered regardless of toggles

2. navigateToDomain now switches viewMode to "domain" — previously
   clicking flow buttons from structural mode was a silent no-op

3. ExportMenu JSON export for non-technical persona now keeps all
   file-level types — previously dropped config/document/service/etc.

4. ProjectOverview category breakdown now includes module/concept in
   Code and domain/flow/step in new Domain category

5. SearchBar type badge colors now cover all 16 node types — previously
   only 5 had colors, rest fell back to file color

6. PathFinder BFS now traverses edges bidirectionally — previously
   only followed forward direction, missing valid reverse paths

7. GraphView node filtering consolidated into single authoritative
   type set — previously fileLevelTypes and persona conditions were
   separate lists that could drift

8. SelectedNodeFitView delayed 100ms to run after layer-level fitView
   on search-click navigation — previously layer fit clobbered node fit

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-03 00:03:03 +08:00
Lum1104andClaude Opus 4.6 d52dd933ee fix(dashboard): show function/class nodes in layer detail view
Function and class nodes were invisible in the graph because they
are not directly assigned to layers (only file-level nodes are).
Expand layer membership by following `contains` edges from file nodes
in the active layer to include their child function/class nodes.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-02 23:56:34 +08:00
Lum1104andClaude Opus 4.6 fece84ac59 fix: address all 24 prompt engineering audit issues across 7 agents
knowledge-graph-guide.md (6 issues):
- Fix node types (5→16), edge types (18→29), tour schema (nodeId→nodeIds)
- Add domain graph documentation, jq examples, expand content

graph-reviewer.md (5 issues):
- Add domain node types (domain/flow/step) and edge types (contains_flow/flow_step/cross_domain)
- Relax layers/tour requirements for domain graphs
- Soften Check 8 (remove overly strict config/resource/endpoint checks)

domain-analyzer.md (6 issues):
- Add input format specification, output file path, writing results section
- Add critical constraints section with validation rules
- Fix flow_step weight scheme to stay within 0-1 range
- Change from "respond with JSON" to write-to-file pattern

file-analyzer.md (6 issues):
- Fix node type count description (13→accurate text)
- Recommend Node.js over bash for extraction scripts
- Replace "validate mentally" with actionable JSON validation instruction
- Clarify exports vs contains edge relationship
- Trim redundant tag guidance section
- Document why direction is always forward

architecture-analyzer.md (4 issues):
- Allow Python fallback for script language
- Clarify allEdges excludes sub-file edges
- Define "common prefix" algorithm for directory grouping
- Add layer count validation and empty group handling

tour-builder.md (2 issues):
- Fix BFS to start from code entry point, not README
- Allow Python fallback for script language

project-scanner.md (4 issues):
- Clarify exclusions match full directory segments, not substrings
- Stop excluding *.d.ts (may be hand-written)
- Add .env secret leak warning
- Document $PROJECT_ROOT variable, prefer Node.js

Cross-agent (3 issues):
- Consistent "prefer Node.js; fall back to Python" across all agents
- Schema type/count consistency across all agents
- Domain graph compatibility with graph-reviewer

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-02 23:14:29 +08:00
Lum1104andClaude Opus 4.6 2387649c1b fix: tone down function/class extraction constraint to avoid false mandate
The previous wording ("MUST have sub-nodes") implied every code file
must produce function nodes, which is wrong for files without significant
functions. Now correctly states: if significant functions exist in the
script output, you must create nodes for them.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-02 22:54:31 +08:00
Lum1104andClaude Opus 4.6 0c08a7853b chore: remove old prompt templates and update hook references
Delete the 5 prompt template files from skills/understand/ now that
they live in agents/. Update auto-update-prompt.md hook to reference
agent definitions instead of deleted prompt files.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-02 22:24:25 +08:00
Lum1104andClaude Opus 4.6 52a68e5bd4 refactor: move prompt templates to agent definitions for prompt integrity
Prompt templates (file-analyzer, project-scanner, architecture-analyzer,
tour-builder, graph-reviewer) were being compressed by the orchestrator
when dispatched as subagent prompts, causing function/class extraction
to be silently skipped. Moving them to agents/ ensures the framework
loads the full prompt without compression.

- Move 5 prompt templates from skills/understand/ to agents/
- Update SKILL.md to reference agent definitions instead of templates
- Set all agent models to `inherit` for cross-platform compatibility
- Update CLAUDE.md to reflect new agent model policy

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-02 22:21:55 +08:00
Lum1104andClaude Opus 4.6 9d1abd0a30 fix: address code review issues across domain feature
- Remove direction-inverting `implemented_by` alias (same pattern as fd0df15)
- Replace ambiguous `process` alias with `business_process`
- Fix duplicate React Flow edge IDs in DomainGraphView
- Fix navigateToDomain clearing selectedNodeId and losing history
- Preserve domain viewMode when structural graph loads after domain graph
- Add domain/flow/step to fileLevelTypes in GraphView
- Add domain edge category to EDGE_CATEGORY_MAP
- Extend COMPLEXITY_STRING_MAP with trivial/basic/mid/average/advanced
- Normalize string complexity values in normalizeBatchOutput (not just numeric)
- Infer node type from ID prefix in edge fallback normalization
- Include flow discriminator in bare-path step ID normalization
- Clean up domain-context.json intermediate file in SKILL.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-02 21:20:33 +08:00
Lum1104andClaude Opus 4.6 e682ec1829 feat(skills): add extract-domain-context.py for lightweight codebase scanning
Python preprocessing script for /understand-domain Phase 2 (standalone path).
Scans a project and produces a structured JSON context file containing:
- File tree (respects .gitignore)
- Entry points (HTTP routes, CLI commands, events, cron, handlers)
- File signatures (exports, imports, previews) prioritized by business logic
- Project metadata (package.json, README, etc.)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-02 15:24:30 +08:00