79 Commits

• fix: PHP namespace block extraction, C/C++ language split, and Lua config

  - Handle block-scoped PHP namespaces (`namespace Foo { class Bar {} }`)
    by recursing into compound_statement bodies in PhpExtractor
  - Separate C (.c/.h) from C++ (.cpp/.cc/.hpp) into distinct language
    configs so .c/.h files resolve to language "c" instead of "cpp"
  - Add Lua language config so .lua files resolve to "lua" instead of
    "unknown" after the EXTENSION_LANGUAGE map was replaced by LanguageRegistry
  - Update TreeSitterPlugin JSDoc to reflect all 10 supported languages
  
  Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

  Lum1104 · 2026-04-16 14:40:24 +08:00
  a2907ec76f
• feat: export LanguageExtractor type and builtinExtractors from core package

  Completes the language extractor architecture — 10 languages with
  tree-sitter support (TS, JS, Python, Go, Rust, Java, Ruby, PHP, C/C++, C#).
  
  Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

  Lum1104 · 2026-04-15 19:27:33 +08:00
  11d2e95720
• feat: create extractor index with builtinExtractors, wire all 9 extractors into TreeSitterPlugin

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

  Lum1104 · 2026-04-15 19:20:42 +08:00
  4ff04b251e
• feat: add CSharpExtractor for tree-sitter C# structural analysis

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

  Lum1104 · 2026-04-15 19:19:24 +08:00
  3e4f7b6c02
• feat: add CppExtractor for tree-sitter C/C++ structural analysis

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

  Lum1104 · 2026-04-15 19:13:59 +08:00
  48e1daa838
• feat: add PhpExtractor for tree-sitter PHP structural analysis

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

  Lum1104 · 2026-04-15 19:08:51 +08:00
  4eb35b0437
• 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>

  Lum1104 · 2026-04-15 19:02:52 +08:00
  dc8dd7dd77
• feat: add JavaExtractor for tree-sitter Java structural analysis

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

  Lum1104 · 2026-04-15 18:42:55 +08:00
  6e500cbfdf
• feat: add RustExtractor for tree-sitter Rust structural analysis

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

  Lum1104 · 2026-04-15 18:38:26 +08:00
  a1fb9585d3
• 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>

  Lum1104 · 2026-04-15 18:33:18 +08:00
  f18cad61d5
• 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>

  Lum1104 · 2026-04-15 18:28:38 +08:00
  398f5b15b0
• feat: add tree-sitter grammar deps and treeSitter configs for 10 languages

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

  Lum1104 · 2026-04-15 18:22:51 +08:00
  2ad0563878
• feat: add extractCallGraph to PluginRegistry, derive DEFAULT_PLUGIN_CONFIG from configs

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

  Lum1104 · 2026-04-15 18:20:31 +08:00
  9376375c8c
• 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>

  Lum1104 · 2026-04-15 18:17:09 +08:00
  ab011ff856
• feat: add LanguageExtractor interface and shared base utilities

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

  Lum1104 · 2026-04-15 18:12:07 +08:00
  4f954907ec
• 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>

  Lum1104 · 2026-04-15 17:30:38 +08:00
  6cba6de658
• 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.

  Nikola Chetelyazov · 2026-04-13 09:56:12 +03:00
  d11a9bb1c9
• 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.

  Nikola Chetelyazov · 2026-04-13 09:52:13 +03:00
  45b98716ec
• 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.

  Nikola Chetelyazov · 2026-04-13 09:49:47 +03:00
  e82235e1df
• 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.

  Nikola Chetelyazov · 2026-04-13 09:47:16 +03:00
  ef0c65aa17
• 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.

  Nikola Chetelyazov · 2026-04-13 09:44:17 +03:00
  5593af76ca
• 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.

  Nikola Chetelyazov · 2026-04-13 09:41:12 +03:00
  6c55ee303a
• 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.

  Nikola Chetelyazov · 2026-04-13 09:35:55 +03:00
  82b1d06777
• 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.

  Nikola Chetelyazov · 2026-04-13 09:33:18 +03:00
  a89555d369
• 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.

  Nikola Chetelyazov · 2026-04-13 09:28:02 +03:00
  c96a14c541
• 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>

  Lum1104 · 2026-04-12 11:39:31 +08:00
  6ef1a21315
• Merge branch 'main' into feat/understandignore
  Lum1104 · 2026-04-12 11:34:10 +08:00
  bc311c80ad
• 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>

  Lum1104 · 2026-04-12 11:09:41 +08:00
  2fc85e68c3
• 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>

  Lum1104 · 2026-04-10 11:51:59 +08:00
  d3de6dc1fd
• feat(core): export IgnoreFilter and IgnoreGenerator from core index
  Lum1104 · 2026-04-10 11:36:53 +08:00
  4201cbcb9e
• feat(core): add IgnoreGenerator for starter .understandignore file creation

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

  Lum1104 · 2026-04-10 11:36:23 +08:00
  6f8270fb37
• feat(core): add IgnoreFilter module with .understandignore parsing and tests

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

  Lum1104 · 2026-04-10 11:33:10 +08:00
  5e86254b77
• chore(core): add ignore package for .understandignore support
  Lum1104 · 2026-04-10 11:30:52 +08:00
  07b02d18ae
• 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>

  Lum1104 · 2026-04-02 21:20:33 +08:00
  9d1abd0a30
• fix: address all code review issues from both reviewers

  - Fix race condition: setGraph no longer wipes domainGraph on parallel fetch
  - Remove workflow/action aliases that conflicted with pipeline type
  - Remove duplicate onNodeDoubleClick handler in DomainGraphView
  - Add clearActiveDomain store action (replaces direct setState call)
  - Remove auto-switch to domain viewMode in setDomainGraph
  - Add DomainMetaSchema Zod validation for domainMeta fields
  - Add Array.isArray guards for domainMeta collections in NodeInfo
  - Remove as-any cast in getDomainMeta (use typed domainMeta directly)
  - Add "domain" filter category for domain/flow/step nodes
  - Keep flow discriminator in step ID normalization to prevent collisions
  - Update SKILL.md Phase 2 to use tool-based scanning (no missing script)
  - Update EDGE_LABELS comment to reflect 29 edge types
  - Bump version to 2.1.0 in all 4 required files
  
  Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

  Lum1104 · 2026-04-02 14:52:34 +08:00
  7d3c049422
• fix(core): improve step ID normalization and add missing test coverage

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

  Lum1104 · 2026-04-02 11:51:12 +08:00
  005758b922
• fix(core): remove dead import and unnecessary type cast in domain persistence test

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

  Lum1104 · 2026-04-02 11:43:23 +08:00
  9693e1efee
• feat(core): add domain/flow/step prefixes to node ID normalization

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

  Lum1104 · 2026-04-02 11:40:36 +08:00
  d89d7f6e93
• feat(core): add saveDomainGraph/loadDomainGraph persistence functions

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

  Lum1104 · 2026-04-02 11:29:26 +08:00
  fe01ee0f85
• feat(core): add domain/flow/step node types and domain edge types for business domain knowledge

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

  Lum1104 · 2026-04-02 11:08:52 +08:00
  37e56d62b3
• Merge pull request #65 from fishinakleinbottle/fix/normalization-for-generated-graph

  fix(core): deterministic node ID normalization for parallel batch output

  Yuxiang Lin · 2026-04-01 21:12:45 +08:00
  efd4c483ec
• fix(core): handle all 13 node types, edge cross-variant resolution, and dropped edge traceability

  - Add all 13 node types (including non-code) to VALID_PREFIXES and TYPE_TO_PREFIX
    to prevent valid IDs like config:tsconfig.json from being stripped
  - Add fallback normalizeNodeId on edge endpoints not found in idMap, fixing
    silent relationship loss when edges use different malformed variants than nodes
  - Add DroppedEdge interface with source, target, type, and reason fields so
    callers can surface exactly which edges were lost and why
  - Use honest Record<string, unknown>[] return types instead of unsafe type casts
  - Align SKILL.md complexity aliases with COMPLEXITY_STRING_MAP
  - Add 5 new tests for non-code types, cross-variant edges, dropped edge detail,
    and validateGraph integration
  
  Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

  Lum1104 · 2026-04-01 21:10:43 +08:00
  6f443fbc14
• fix(core): add deterministic normalization for parallel batch analyzer output

  Parallel file-analyzer subagents can produce inconsistent node IDs
  (project-name prefixed, double-prefixed, bare paths) and invalid
  complexity values. Phase 3 ASSEMBLE now normalizes these deterministically
  before merging, preventing cascading edge drops and dashboard load failures.
  
  - Add normalize-graph.ts with normalizeNodeId, normalizeComplexity,
    and normalizeBatchOutput utilities
  - Rewrite SKILL.md Phase 3 with 6-step normalization sequence
  - Strengthen file-analyzer prompt with ID format warnings
  - Add 32 normalization tests and 2 schema boundary tests

  Sreeram · 2026-03-31 16:34:04 +05:30
  60c2ead398
• fix: address comprehensive code review findings for PR #51

  Fix all issues from the 5-agent parallel code review of universal file
  type support:
  
  - Parser error handling: add console.warn in JSON/YAML catch blocks,
    warn on unbalanced braces in Protobuf/Terraform parsers
  - Parser correctness: filter .PHONY special targets in Makefile parser,
    handle opening brace on next line in Shell parser, fix per-stage
    EXPOSE port assignment in Dockerfile parser
  - Graph builder: use nodeType-based ID prefix instead of hardcoded
    "file:", warn on unknown definition kinds, detect duplicate node IDs
  - Type safety: export NodeType alias, add ServiceInfo.lineRange, type
    dashboard color maps as Record<NodeType,...>, refactor
    getDirectionalLabel to Record<EdgeType,...>, consolidate NodeCategory
  - Schema: add StrictLanguageConfigSchema with extensions/filenames
    refinement, fix Infrastructure/Schema-Data category comments
  - Agent prompts: fix Jenkinsfile language ID (groovy → jenkinsfile),
    fix css.md edge type (configures → related), remove shell.md
    Makefile cross-reference
  - Tests: 20+ new edge case tests across parsers, graph builder,
    language registry, and plugin registry
  - Documentation: add JSDoc to all 12 parser classes
  
  Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

  Lum1104 · 2026-03-28 21:55:20 +08:00
  4d2cb32232
• fix: address code review findings for universal file type support

  - Expand persona filter in GraphView.tsx to show all 9 file-level node
    types (file, config, document, service, table, endpoint, pipeline,
    schema, resource) instead of only "file", fixing invisible nodes
  - Add serves, provisions, and routes edge types with creation criteria
    to file-analyzer-prompt.md
  - Fix related edge weight from 0.3 to 0.5 to match SKILL.md default
  - Add filenames to openapiConfig for proper filename-based detection
  - Add TODO comments to kubernetesConfig and jsonSchemaConfig explaining
    content-based detection limitations
  - Clarify that module/concept types are reserved for higher-level agents
  - Update language-registry tests for 38 built-in configs
  
  Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

  Lum1104 · 2026-03-28 19:14:00 +08:00
  71468e8082
• feat(core): export new types and parsers from core

  Export all 12 non-code parsers (MarkdownParser, YAMLConfigParser,
  JSONConfigParser, TOMLParser, EnvParser, DockerfileParser, SQLParser,
  GraphQLParser, ProtobufParser, TerraformParser, MakefileParser,
  ShellParser) and the registerAllParsers() helper from core index.
  
  New type exports (SectionInfo, DefinitionInfo, ServiceInfo, etc.)
  are already covered by the existing `export * from "./types.js"`.
  
  Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

  Lum1104 · 2026-03-28 18:40:55 +08:00
  db572231f8
• feat(core): add non-code file support to GraphBuilder

  Add addNonCodeFile() and addNonCodeFileWithAnalysis() methods that create
  graph nodes with the appropriate non-code types (document, config, service,
  table, endpoint, pipeline, schema, resource).
  
  addNonCodeFileWithAnalysis() creates child nodes for definitions, services,
  endpoints, steps, and resources with "contains" edges to the parent file.
  
  Add mapKindToNodeType() helper for mapping definition kinds to node types.
  Extend EXTENSION_LANGUAGE map with all non-code file extensions.
  
  Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

  Lum1104 · 2026-03-28 18:40:04 +08:00
  2bb107e2d9
• feat(core): add 12 custom parsers for non-code file types

  Add regex/parser-based analyzers for: Markdown, YAML, JSON, TOML, Env,
  Dockerfile, SQL, GraphQL, Protobuf, Terraform, Makefile, Shell.
  
  Each implements AnalyzerPlugin with analyzeFile() and optional
  extractReferences(). Uses `yaml` npm package for YAML parsing,
  built-in JSON.parse for JSON, regex for all others.
  
  Add registerAllParsers() helper to register all parsers at once.
  Add comprehensive test suite with 35 tests covering all parsers.
  
  Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

  Lum1104 · 2026-03-28 18:38:25 +08:00
  3fd688ac37
• feat(core): add 26 non-code language configs with filename-based detection

  Add LanguageConfig files for: markdown, yaml, json, toml, env, xml,
  dockerfile, sql, graphql, protobuf, terraform, github-actions, makefile,
  shell, html, css, openapi, kubernetes, docker-compose, json-schema, csv,
  restructuredtext, powershell, batch, jenkinsfile, plaintext.
  
  Add filenames? field to LanguageConfigSchema for filename-based detection
  (Dockerfile, Makefile, Jenkinsfile, docker-compose.yml, .env variants).
  
  Update LanguageRegistry.getForFile() to check filename matches first
  (more specific) before falling back to extension-based lookup.
  
  Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

  Lum1104 · 2026-03-28 18:34:16 +08:00
  c76b0a1f2d
• feat(core): make resolveImports optional on AnalyzerPlugin

  Update PluginRegistry.resolveImports() to check for plugin.resolveImports
  existence before calling it. Non-code plugins (e.g., markdown, dockerfile)
  don't need import resolution, so this method is now optional.
  
  Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

  Lum1104 · 2026-03-28 18:31:00 +08:00
  9eb220c492