Merge pull request #8 from Coding-Meet/release/v1.3.0

Add local source scanning support for version 1.3.0

Author: Coding-Meet

.agents/skills/library-insight/SKILL.md

@@ -1,41 +1,163 @@
 ---
 name: library-insight
-description: JVM API Explorer & MCP Server that indexes public APIs, visualizes dependency graphs, audits version deprecations, and extracts JVM archive signatures (JAR/AAR) or Maven coordinates for AI context.
+description: JVM API Explorer & MCP Server that indexes public APIs from compiled libraries (JAR/AAR) or local Java/Kotlin source code, enabling API exploration, dependency analysis, migration reports, and AI-ready context generation.
 ---
 
 # Library Insight Agent Skill
 
-Use this skill when you need to understand, inspect, or build AI prompts for external JVM libraries (Java/Kotlin JAR or AAR files) or public Maven dependency coordinates.
+Use this skill when you need to understand, inspect, or build AI prompts for:
 
-This tool extracts all classes, interfaces, methods, properties, and Javadoc/KDoc comments from bytecode and sources, creating an indexed database and a split AI-friendly directory structure.
+- External JVM libraries (Java/Kotlin JAR or AAR files)
+- Maven Central dependencies
+- Local Java or Kotlin source code projects
+
+Library Insight analyzes both compiled JVM libraries and local source code to build a searchable API index. It extracts public APIs, type information, documentation, source metadata, and Kotlin-specific language features, allowing AI agents to work with the exact code being used instead of relying on outdated documentation or web examples.
 
 > [!IMPORTANT]
 > **AI Agent Token Optimization Rule:**
-> **DO NOT** read the entire `build/library-insight-index.json` or `API_REFERENCE.md` files directly using file-viewing tools. They contain massive raw dumps of the entire library surface which will exhaust your context window.
-> Instead, you **MUST** use the CLI query subcommands to interactively look up only the specific information you need:
-> - Use **`library-insight search <query>`** to find packages or classes.
-> - Use **`library-insight explain <class>`** to print the public API signature and Javadocs of a specific class.
-> - Use **`library-insight diff <old> <new>`** to compare versions.
-> - Use **`library-insight audit`** to check project dependency API deprecations recursively.
-> - Use **`library-insight migrate <old> <new>`** to get a migration advisor report with replacement suggestions.
-> - Use **`library-insight search-central <query>`** to search Maven Central.
-> - Use **`library-insight dependency-graph <coord>`** to visualize dependency trees.
-> - Use **`library-insight semver <old> <new>`** to lint Semantic Versioning API compliance.
-> - Use **`library-insight mcp`** to communicate as a Model Context Protocol (MCP) server.
-> - Use **`library-insight dsl-report [--package <pkg>]`** to generate a Kotlin DSL surface report (type aliases, `@DslMarker` scopes, extension functions, lambda receivers, reified functions).
-> - Use **`library-insight examples <class>`** to generate typical usage code examples from bytecode signatures.
-> - Use **`library-insight health`** to generate a Package Health & API Complexity Report.
-> - Use **`library-insight dependency-check`** to audit all transitive classpath dependencies for runtime conflicts.
-> - Use **`library-insight callgraph <class.method>`** to trace internal library method invocation call graphs recursively.
 >
-> **MCP Integration Rule:**
-> If an MCP server is already configured and available (e.g., in Cursor, Claude Desktop, or another IDE with MCP support), **prefer the MCP server over shelling out to the CLI**. The MCP server exposes `scan_library`, `search_symbols`, and `explain_class` tools natively without subprocess overhead.
+> **DO NOT** read the entire `build/library-insight-index.json` or generated `API_REFERENCE.md` files directly using file-viewing tools. These files can be extremely large and will quickly exhaust the available context window.
+>
+> Instead, interact with the indexed database using the CLI query commands so that only the required symbols are loaded into context.
+>
+> **Indexing**
+>
+> - Use **`library-insight scan <jar|aar|directory|maven-coordinate>`** to index compiled JVM libraries.
+> - Use **`library-insight scan-source <directory>`** to index a local Java/Kotlin source project without compilation.
+>
+> **Querying**
+>
+> - Use **`library-insight search <query>`** to locate packages, classes, methods, or properties.
+> - Use **`library-insight explain <class>`** to inspect a class, including signatures, documentation, imports, and source locations when available.
+> - Use **`library-insight examples <class>`** to generate typical usage examples.
+>
+> **Analysis**
+>
+> - Use **`library-insight diff <old> <new>`** to compare two library versions.
+> - Use **`library-insight migrate <old> <new>`** to generate a migration report with replacement suggestions.
+> - Use **`library-insight audit`** to audit project dependency APIs recursively.
+> - Use **`library-insight dependency-check`** to detect runtime linkage and ABI conflicts across transitive dependencies.
+> - Use **`library-insight dependency-graph <coordinate>`** to visualize dependency trees.
+> - Use **`library-insight semver <old> <new>`** to validate Semantic Versioning API compatibility.
+> - Use **`library-insight health`** to generate package health and API complexity reports.
+> - Use **`library-insight dsl-report [--package <pkg>]`** to inspect Kotlin DSL surfaces, including `@DslMarker` scopes, type aliases, extension functions, lambda receivers, and inline reified functions.
+> - Use **`library-insight callgraph <class.method>`** to recursively trace internal library method invocation call graphs.
+>
+> **AI Context**
+>
+> - Use **`library-insight ai-export`** to generate a token-optimized AI context package.
+> - Use **`library-insight export`** to export the indexed API as JSON or Markdown documentation.
+>
+> **Important**
+>
+> Both **`scan`** and **`scan-source`** generate the same API index format. Once an index has been created, existing commands such as **`search`**, **`explain`**, **`export`**, and **`ai-export`** work identically regardless of whether the data originated from compiled bytecode or local source code.
+
+> [!NOTE]
+> **What Library Insight extracts**
+>
+> Depending on the input, Library Insight indexes:
+>
+> - Packages
+> - Classes
+> - Interfaces
+> - Enums
+> - Java Records
+> - Kotlin Objects
+> - Companion Objects
+> - Constructors
+> - Methods
+> - Properties and Fields
+> - Generic type parameters
+> - Nullability information
+> - Modifiers
+> - Annotations
+> - Package imports
+> - Source locations (`file:line`)
+> - Javadoc
+> - KDoc
+> - Kotlin metadata (`@Metadata`)
+> - Data classes
+> - Value classes
+> - Sealed classes and interfaces
+> - Extension functions
+> - Kotlin DSL constructs
+
+> [!TIP]
+> **MCP Integration Rule**
+>
+> If an MCP server is already configured (for example in Cursor, Claude Desktop, VS Code, Windsurf, or another MCP-compatible IDE), prefer using the MCP server instead of invoking the CLI through subprocesses.
+>
+> The MCP server provides native tools for indexing libraries or source projects, searching indexed symbols, explaining APIs, and serving AI context with lower overhead than repeatedly executing CLI commands.
+
+## Typical Workflows
+
+### Analyze a compiled library
+
+```bash
+library-insight scan my-library.jar
+
+library-insight search Retrofit
+
+library-insight explain retrofit2.Retrofit
+
+library-insight ai-export
+```
+
+### Analyze a local source project
+
+```bash
+library-insight scan-source app/src/main
+
+library-insight search LoginRepository
+
+library-insight explain LoginRepository
+
+library-insight ai-export
+```
+
+### Compare two versions
+
+```bash
+library-insight diff old.jar new.jar
+
+library-insight migrate old.jar new.jar
+
+library-insight semver old.jar new.jar
+```
 
 ## Command Reference
 
-The command line tool `library-insight` can be executed globally by:
-* Installing via installer script: `curl -fsSL https://raw.githubusercontent.com/Coding-Meet/Library-Insight/main/install.sh | bash`
-* Running local build: `~/.library-insight/bin/library-insight` (linked globally as `library-insight`)
+The `library-insight` CLI can be executed globally by:
+
+- Installing using the installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Coding-Meet/Library-Insight/main/install.sh | bash
+```
+
+- Running the locally installed binary:
+
+```bash
+library-insight
+```
+
+or
+
+```bash
+~/.library-insight/bin/library-insight
+```
+
+## Additional Guidance for AI Agents
+
+When answering questions about a library or project:
+
+1. Index the target if it has not already been indexed.
+2. Search before explaining.
+3. Explain only the symbols relevant to the user's request.
+4. Avoid loading the full index into context.
+5. Prefer focused symbol lookups over large exports.
+6. Generate AI context (`ai-export`) only when broad project understanding is required.
+7. When an MCP server is available, prefer MCP tools over spawning CLI processes.
 
 ### 1. `scan` — Scan a Library
 
@@ -97,9 +219,13 @@ library-insight search "anno:Keep" --db custom-index.json
 **Example output:**
 
 ```
-Found 2 matching classes:
-  - retrofit2.Retrofit
-  - retrofit2.Retrofit$Builder
+Found 2 matches for 'Retrofit':
+--------------------------------------------------
+[CLASS]     class retrofit2.Retrofit
+           Source: src/main/java/retrofit2/Retrofit.java:18
+[CLASS]     class retrofit2.Retrofit$Builder
+           Source: src/main/java/retrofit2/Retrofit.java:82
+--------------------------------------------------
 ```
 
 ---
@@ -125,13 +251,32 @@ library-insight explain HtmlBuilder --db custom-index.json
 **Example output:**
 
 ```
-Class: retrofit2.Retrofit (public class)
-  Constructors:
-    + public constructor(okhttp3.Call$Factory, ...)
-  Methods:
-    + public fun <T> create(java.lang.Class<T>): T
-    + public fun baseUrl(): okhttp3.HttpUrl
-    + public fun callFactory(): okhttp3.Call$Factory
+==================================================
+ CLASS EXPLAIN REPORT
+==================================================
+Class:       com.meet.sample.HtmlBuilder
+Package:     com.meet.sample
+Kind:        class
+Visibility:  public
+Source:      sample/src/main/kotlin/com/meet/sample/SampleLibrary.kt:25
+Annotations: @HtmlDsl
+==================================================
+
+Imports:
+  - kotlin.text.*
+  - retrofit2.Retrofit
+
+Properties:
+  - private val children: Any (sample/src/main/kotlin/com/meet/sample/SampleLibrary.kt:27)
+
+Methods:
+  // /** Adds a paragraph element to the HTML output. */
+  - public fun p(text: String): Unit (sample/src/main/kotlin/com/meet/sample/SampleLibrary.kt:29)
+  // /** Adds a heading element. */
+  - public fun h1(text: String): Unit (sample/src/main/kotlin/com/meet/sample/SampleLibrary.kt:32)
+  // /** Adds a nested div block. */
+  - public fun div(block: HtmlBuilder.() -> Unit): Unit (sample/src/main/kotlin/com/meet/sample/SampleLibrary.kt:35)
+  - public fun build(): String (sample/src/main/kotlin/com/meet/sample/SampleLibrary.kt:41)
 ```
 
 ---
@@ -223,17 +368,21 @@ library-insight export json
 ```
 
 **Positional Arguments:**
+
 - `[output-file]`: Optional target output file path to write export content to. If not specified, defaults to `build/API_REFERENCE.md` or `build/library-insight-index.json`. Use `-` to print to stdout.
 
 **Optional Parameters:**
+
 - `--db <file>`: Index database JSON file path to read from (default: `build/library-insight-index.json`)
 
 **Example with options:**
+
 ```bash
 library-insight export markdown API_REFERENCE.md --db custom-index.json
 ```
 
 **Example output:**
+
 ```
 Exported MARKDOWN to: build/API_REFERENCE.md
 ```
@@ -249,17 +398,21 @@ library-insight ai-export
 ```
 
 **Positional Arguments:**
+
 - `[output-dir]`: Optional target output directory to save AI context files (default: `build/ai-context/`)
 
 **Optional Parameters:**
+
 - `--db <file>`: Index database JSON file path to read from (default: `build/library-insight-index.json`)
 
 **Example with options:**
+
 ```bash
 library-insight ai-export custom-ai-context/ --db custom-index.json
 ```
 
 **Example output:**
+
 ```
 Generated compact LLM context directory structure at: build/ai-context
 ```
@@ -307,6 +460,7 @@ library-insight search-central clikt
 ```
 
 **Example output:**
+
 ```
 Searching Maven Central for 'clikt'...
 
@@ -380,6 +534,7 @@ library-insight mcp --db /path/to/project/custom-index.json
 ```
 
 **Example output (JSON-RPC tools list response):**
+
 ```json
 {
   "jsonrpc": "2.0",
@@ -389,12 +544,18 @@ library-insight mcp --db /path/to/project/custom-index.json
       {
         "name": "scan_library",
         "description": "Scans a Java/Kotlin library and creates an API index.",
-        "inputSchema": { "type": "object", "properties": { "pathOrCoordinate": { "type": "string" } } }
+        "inputSchema": {
+          "type": "object",
+          "properties": { "pathOrCoordinate": { "type": "string" } }
+        }
       },
       {
         "name": "search_symbols",
         "description": "Search for symbols in the active library index.",
-        "inputSchema": { "type": "object", "properties": { "query": { "type": "string" } } }
+        "inputSchema": {
+          "type": "object",
+          "properties": { "query": { "type": "string" } }
+        }
       }
     ]
   }
@@ -414,6 +575,7 @@ library-insight init
 ```
 
 **Example output:**
+
 ```
 Initializing Library Insight agent environment...
 Creating directory: .agents/skills/library-insight/
@@ -437,6 +599,7 @@ library-insight skills list
 ```
 
 **Example output (skills list):**
+
 ```
 Workspace AI Agent Skills:
   - [Installed] library-insight
@@ -453,6 +616,7 @@ library-insight clear-cache
 ```
 
 **Example output:**
+
 ```
 Clearing local cache at: ~/.library-insight/cache...
 Cache cleared successfully. Deleted 12.4 MB.
@@ -738,3 +902,41 @@ library-insight callgraph AppConfigBuilder.database --db custom-index.json
 └── com.meet.sample.DatabaseConfigBuilder.<init>()
 ==================================================
 ```
+
+---
+
+### 22. `scan-source` — Local Source Directory Scanner
+
+Scan a local raw source directory containing Kotlin (`.kt`) and Java (`.java`) files to build an API index database.
+
+```bash
+library-insight scan-source sample/src/main/kotlin
+```
+
+**Optional Parameters:**
+
+- `--db <file>`: Target index database JSON file path to write to (default: `build/library-insight-index.json`)
+- `--lib-name <name>`: Override the library name tag in the generated index
+- `--lib-version <version>`: Override the version tag in the generated index
+
+**Example with options:**
+
+```bash
+library-insight scan-source src/main/kotlin --db build/my-app-index.json --lib-name MyApp --lib-version 1.0.0
+```
+
+**Example output:**
+
+```
+Scanning source directory: /Users/meet/AndroidStudioProjects/Library-Insight/sample/src/main/kotlin
+
+Detected:
+  • Kotlin files : 1
+  • Java files   : 0
+
+Scan complete!
+Found 15 classes across 3 packages.
+
+Saved API index to:
+/Users/meet/AndroidStudioProjects/Library-Insight/build/library-insight-index.json
+```