code-tree-graph 0.1.2

package/README.md

@@ -0,0 +1,295 @@
+<p align="center">
+    <img width="300px" src="https://i.imgur.com/jg49HQ8.png" />
+<p align="center">
+    <a href="https://discord.gg/SJdBqBz3tV">
+        <img src="https://img.shields.io/discord/1110227955554209923.svg?label=Chat&logo=Discord&colorB=7289da&style=flat"
+            alt="Join Discord" />
+    </a>
+     <a href="https://github.com/OpenSourceAGI/appdemo-dev-tools/discussions">
+     <img alt="GitHub Stars" src="https://img.shields.io/github/stars/OpenSourceAGI/appdemo-dev-tools" /></a>
+    <a href="https://github.com/OpenSourceAGI/appdemo-dev-tools/discussions">
+    <img alt="GitHub Discussions"
+        src="https://img.shields.io/github/discussions/OpenSourceAGI/appdemo-dev-tools" />
+    </a>
+<br />
+    <a href="https://github.com/OpenSourceAGI/appdemo-dev-tools/pulse" alt="Activity">
+        <img src="https://img.shields.io/github/commit-activity/m/OpenSourceAGI/appdemo-dev-tools" />
+    </a>
+    <img src="https://img.shields.io/github/last-commit/OpenSourceAGI/appdemo-dev-tools.svg" alt="GitHub last commit" />
+<br />
+    <img src="https://img.shields.io/badge/Next.js-16-black" alt="Next.js" />
+    <a href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request">
+        <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg"
+            alt="PRs Welcome" />
+    </a>
+    <a href="https://codespaces.new/OpenSourceAGI/appdemo-dev-tools">
+    <img src="https://github.com/codespaces/badge.svg" width="150" height="20" />
+    </a>
+</p>
+
+# code-graph
+
+Interactive code dependency graph and file tree visualization components for [Fumadocs](https://fumadocs.vercel.app/) + Next.js. Drop them into any MDX page to generate live, navigable views of your codebase — no external service required.
+
+**What's included:**
+- **`DependencyGraph`** — Mermaid flowchart built from full AST analysis, with pan/zoom, search, hover tooltips, and remote repo ZIP support
+- **`FileTreeView`** — searchable, filterable file table with export/import/JSDoc metadata and GitHub deep links
+- **`TypeTable`** — collapsible property tables for type documentation
+- **AST engine** — TypeScript/JS parser extracting imports, exports, functions, types, and signatures
+
+---
+
+## Installation
+
+```bash
+npm install code-graph
+```
+
+Import the CSS once in your app root (e.g. `app/layout.tsx`):
+
+```ts
+import "code-graph/dist/index.css";
+```
+
+### Peer dependencies
+
+```bash
+npm install react react-dom next fumadocs-core
+```
+
+---
+
+## Components
+
+### DependencyGraph
+
+Server component. Scans directories with the AST engine and renders an interactive Mermaid flowchart.
+
+```tsx
+import { DependencyGraph } from "code-graph";
+
+export default function Page() {
+  return (
+    <DependencyGraph
+      paths={["../packages/core", "../packages/utils"]}
+      ignore={["node_modules", "dist", "*.test.ts"]}
+      ignoreFile="../.treeignore"
+      showLegend={true}
+      showNpmImports={false}
+      showTypes={false}
+      showPrivateFunctions={false}
+      showExportedFunctions={false}
+    />
+  );
+}
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `paths` | `string[]` | required | Directories to analyze (absolute or relative to `cwd`) |
+| `descriptions` | `Record<string, string>` | `{}` | Manual descriptions keyed by relative path |
+| `ignore` | `string[]` | `[]` | File/folder names or patterns to exclude |
+| `ignoreFile` | `string` | — | Path to a `.treeignore` file (gitignore-style) |
+| `showLegend` | `boolean` | `true` | Show toggle control buttons |
+| `showNpmImports` | `boolean` | `false` | Display external npm dependency nodes |
+| `showTypes` | `boolean` | `false` | Display type definition nodes |
+| `showPrivateFunctions` | `boolean` | `false` | Display internal (non-exported) function nodes |
+| `showExportedFunctions` | `boolean` | `false` | Display exported function nodes |
+| `instructions` | `React.ReactNode` | built-in help | Custom help panel content |
+
+**Features:**
+- Color-coded nodes: entry points (green), core modules (blue), types (purple), utils (gray), npm deps (orange)
+- Pan & zoom with drag and Ctrl+scroll
+- Click a node to scroll to its file tree entry
+- Hover tooltips with JSDoc, exports, and signatures
+- Real-time search with node highlight
+- Toggle visibility of npm / types / private / exported nodes
+- Remote repo analysis: paste a GitHub URL or ZIP to analyze any repo without cloning
+
+---
+
+### FileTreeView
+
+Server component. Generates a filterable table of your file tree with code-analysis metadata.
+
+```tsx
+import { FileTreeView } from "code-graph";
+
+export default function Page() {
+  return (
+    <FileTreeView
+      paths={["../packages/my-lib"]}
+      ghBase="https://github.com/user/repo/tree/master/packages/my-lib"
+      descriptions={{
+        "my-lib": "Core library",
+        "my-lib/index.ts": "Main entry point",
+      }}
+      ignore={["node_modules", "dist"]}
+      inferDescriptions={true}
+      defaultImportFilter="all"
+      defaultInternalFilter="all"
+      defaultExportFilter="functions"
+      defaultCollapseDepth={4}
+    />
+  );
+}
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `paths` | `string[]` | required | Directories or files to scan |
+| `ghBase` | `string` | required | GitHub base URL for file deep-links |
+| `descriptions` | `Record<string, string>` | `{}` | Manual descriptions keyed by relative path |
+| `ignore` | `string[]` | `[]` | File/folder names or patterns to exclude |
+| `ignoreFile` | `string` | — | Path to a `.treeignore` file |
+| `inferDescriptions` | `boolean` | `true` | Auto-extract descriptions from leading JSDoc/comments |
+| `defaultImportFilter` | `"all" \| "local" \| "npm"` | — | Initial import filter |
+| `defaultInternalFilter` | `"all" \| "declared-types" \| "exported-types" \| "functions" \| "classes"` | — | Initial internals filter |
+| `defaultExportFilter` | `"all" \| "functions" \| "classes" \| "constants"` | — | Initial export filter |
+| `defaultCollapseDepth` | `number` | — | Initial tree collapse depth |
+
+**Features:**
+- Fuzzy search (Fuse.js) across names, imports, exports, JSDoc, and signatures
+- 3 independent filter dropdowns (imports, types/internals, exports)
+- Sort by import / type / export count
+- Collapse depth slider
+- Rich badge tooltips with Markdown-parsed descriptions, signatures, and type properties
+- Clickable file badges linking to GitHub source lines
+- `package.json` detection with dependency listing
+
+---
+
+### TypeTable
+
+Client component for rendering collapsible type/property tables in documentation pages.
+
+```tsx
+import { TypeTable } from "code-graph";
+
+export default function Page() {
+  return (
+    <TypeTable
+      type={{
+        name: { type: "string", description: "The node name", required: true },
+        children: { type: "TypeNode[]", description: "Nested children", required: false },
+      }}
+    />
+  );
+}
+```
+
+---
+
+## Programmatic API
+
+The AST engine is available as a standalone Node.js API:
+
+```ts
+import {
+  generateFileTree,
+  analyzeFileContent,
+  parseIgnoreFile,
+} from "code-graph";
+```
+
+### `generateFileTree`
+
+Scans a directory and returns a tree of [`FileTreeNode`](#filetreenode) objects.
+
+```ts
+const tree = generateFileTree(
+  "/absolute/path/to/src",
+  { "index.ts": "Main entry" }, // descriptions
+  new Set(["node_modules", "dist"]), // ignorePatterns
+  true // inferDescriptions from JSDoc
+);
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `packagesDir` | `string` | required | Root directory to scan |
+| `descriptions` | `Record<string, string>` | `{}` | Manual descriptions by relative path |
+| `ignorePatterns` | `Set<string>` | `new Set()` | File/folder names to skip |
+| `inferDescriptions` | `boolean` | `false` | Extract descriptions from source comments |
+
+### `analyzeFileContent`
+
+Analyzes source text in memory — no filesystem read needed.
+
+```ts
+import { analyzeFileContent } from "code-graph";
+
+const analysis = analyzeFileContent("index.ts", sourceText);
+// { localImports, npmImports, exports, functions, types, ... }
+```
+
+### `parseIgnoreFile`
+
+Parses a `.gitignore`-style file into a `Set<string>` of patterns.
+
+```ts
+import { parseIgnoreFile } from "code-graph";
+
+const patterns = parseIgnoreFile("/path/to/.treeignore");
+const tree = generateFileTree("/path/to/src", {}, patterns);
+```
+
+---
+
+## Types
+
+### `FileTreeNode`
+
+```ts
+interface FileTreeNode {
+  name: string;
+  type: "file" | "folder";
+  path: string;             // relative to scanned root
+  description?: string;
+  analysis?: FileAnalysis;
+  children?: FileTreeNode[];
+  packageDependencies?: string[];  // from package.json
+  packageExports?: AnalysisItem[];
+}
+```
+
+### `FileAnalysis`
+
+```ts
+interface FileAnalysis {
+  localImports: string[];
+  localImportSymbols: { source: string; valueNames: string[]; typeNames: string[] }[];
+  npmImports: string[];
+  exports: AnalysisItem[];
+  functions: AnalysisItem[];
+  types: AnalysisItem[];
+}
+```
+
+### `AnalysisItem`
+
+```ts
+interface AnalysisItem {
+  name: string;
+  kind?: "function" | "class" | "constant" | "type";
+  line?: number;
+  jsdoc?: string;
+  signature?: string;
+  properties?: TypeProperty[];
+}
+```
+
+---
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `@typescript-eslint/typescript-estree` | AST parsing for TS/JS |
+| `mermaid` | Graph rendering |
+| `fuse.js` | Fuzzy search |
+| `jszip` | Remote ZIP repo analysis |
+| `marked` | JSDoc → Markdown in tooltips |
+| `@radix-ui/react-tooltip` | Badge tooltips |
+| `lucide-react` | Icons |
+| `svg-toolbelt` | SVG pan/zoom |

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "code-tree-graph",
+  "version": "0.1.2",
+  "description": "Code dependency graph and file tree visualization components",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./dist/index.css": "./dist/index.css"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch"
+  },
+  "dependencies": {
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "@typescript-eslint/typescript-estree": "^8.56.1",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "fuse.js": "^7.1.0",
+    "jszip": "^3.10.1",
+    "lucide-react": "^0.555.0",
+    "marked": "^17.0.4",
+    "mermaid": "^11.12.3",
+    "svg-toolbelt": "^0.6.1",
+    "tailwind-merge": "^3.5.0",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.4",
+    "vite": "^6.3.5",
+    "vite-plugin-dts": "^4.5.4"
+  },
+  "peerDependencies": {
+    "fumadocs-core": "*",
+    "next": "*",
+    "react": "*",
+    "react-dom": "*"
+  }
+}