Merge pull request #9 from Coding-Meet/release/v1.4.0

Add Kotlin Multiplatform support and update documentation

Author: Coding-Meet

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

@@ -1,17 +1,18 @@
 ---
 name: library-insight
-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.
+description: API Explorer & MCP Server for Java, Kotlin & KMP that indexes public APIs from compiled libraries (JAR/AAR), Kotlin Multiplatform libraries (KLib), 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)
+- Java and Kotlin libraries (JAR/AAR files)
+- Kotlin Multiplatform libraries (KLib 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.
+Library Insight analyzes compiled libraries (JVM artifacts and Kotlin Multiplatform 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:**
@@ -22,7 +23,7 @@ Library Insight analyzes both compiled JVM libraries and local source code to bu
 >
 > **Indexing**
 >
-> - Use **`library-insight scan <jar|aar|directory|maven-coordinate>`** to index compiled JVM libraries.
+> - Use **`library-insight scan <jar|aar|klib|directory|maven-coordinate>`** to index compiled libraries.
 > - Use **`library-insight scan-source <directory>`** to index a local Java/Kotlin source project without compilation.
 >
 > **Querying**

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

@@ -2,9 +2,9 @@
 
 # Library Insight 🔍
 
-### JVM API Explorer & MCP Server
+### API Explorer & MCP Server for Java, Kotlin & KMP
 
-Analyze Java & Kotlin libraries and source code with a standalone CLI or integrate directly into AI IDEs via MCP.
+Analyze Java and Kotlin libraries, JVM artifacts, Kotlin Multiplatform libraries, and local source code with a standalone CLI or integrate directly into AI IDEs via MCP.
 
 AI coding assistants often guess Java/Kotlin APIs from outdated documentation, web examples, or a different version than the one used in your project. That leads to missing methods, deprecated usage, incorrect signatures, and wasted debugging time.
 
@@ -26,6 +26,7 @@ The complete documentation, architecture diagrams, command reference, and integr
 <!-- --8<-- [start:features] -->
 
 - **MCP Server**: Connect Cursor, Claude Desktop, or any MCP-compatible IDE to query APIs directly.
+- **Kotlin Multiplatform (KMP) Support**: Resolve coordinates from Gradle Module Metadata (`.module` JSON), parse Native `.klib` metadata files, and merge platform variant API targets (`common`, `jvm`, `ios`, `js`, `wasm`).
 - **Local Source Code Scanner (`scan-source`)**: Analyze Kotlin and Java source projects without compilation, preserving KDoc/Javadoc, imports, and declaration source locations (`file:line`).
 - **Version-Correct API Lookup**: Build an API index from the exact JAR, AAR, Maven dependency, Gradle output, or source code used by your project to prevent AI hallucinations.
 - **Deep Metadata Extraction**: Extract classes, constructors, methods, properties, nullability, generics, annotations, modifiers, and source metadata.
@@ -85,28 +86,14 @@ For setup instructions in Cursor or Claude Desktop, see the [MCP Integration Gui
 
 <!-- --8<-- [start:roadmap] -->
 
-We plan to expand Library Insight with deep source-level analysis capabilities, a three-layer clean architecture, and unified Kotlin Multiplatform (KMP) support:
+We plan to expand Library Insight with deep source-level analysis capabilities:
 
 ### 🔍 Source Analysis Engine (Planned)
 
 - **References Engine**: Build a symbol-to-usage index to locate references for any class, method, or property across the codebase (e.g. `library-insight references LoginRepository`).
 - **Implementations**: Query all interface implementations or subclass declarations (e.g. `library-insight implementations Repository` -> `RoomRepository`, `NetworkRepository`).
 - **Hierarchy**: Render the visual inheritance tree for any base class or interface (e.g. `library-insight hierarchy BaseViewModel`).
 - **Source Call Graph**: Trace internal method execution paths using raw source file declaration locations.
-
-### 🏗️ Clean Architectural Layers
-
-To simplify maintenance, we are partitioning the codebase into three clean layers:
-
-1. **Scanner Layer** (`scan`, `scan-source`) — Processes raw inputs (bytecode, sources, metadata) and compiles them.
-2. **Unified Database** — Serves as the single serialization schema and repository index.
-3. **Analysis & Tooling Layer** (`search`, `explain`, `references`, `implementations`, `hierarchy`, `callgraph`, `ai-export`, `export`) — Consumes the database and provides rich diagnostic tools.
-
-### 📦 Kotlin Multiplatform (KMP) Support
-
-- **KLib Metadata Reader**: Parse `.klib` metadata to extract signatures for iOS/Native, JS, and Wasm targets directly (bypassing JVM bytecode dependencies).
-- **Platform-Aware Indexing**: Store platform target markers (`common`, `jvm`, `ios`, `js`, `wasm`) in the database schema.
-- **KMP Coordinate Resolution**: Auto-resolve platform split coordinates (e.g. `ktor-client-core-iosarm64`) from the root KMP library Maven coordinate.
 <!-- --8<-- [end:roadmap] -->
 
 ---
@@ -157,8 +144,8 @@ mkdocs gh-deploy --force
 Release and publish a new version tag to GitHub:
 
 ```bash
-git tag v1.3.0
-git push origin v1.3.0
+git tag v1.4.0
+git push origin v1.4.0
 ```
 
 ### 5. Demos

README.md

@@ -5,7 +5,7 @@ plugins {
 
 allprojects {
     group = "com.meet.libraryinsight"
-    version = "1.3.0"
+    version = "1.4.0"
 
     repositories {
         mavenCentral()
@@ -61,52 +61,56 @@ tasks.register("setupGitHooks") {
 tasks.register("generateAgentSkill") {
     dependsOn("setupGitHooks")
     group = "documentation"
-    description = "Generates .agents/skills/library-insight/SKILL.md from docs/cli.md and a template."
+    description = "Generates .agents/skills/library-insight/SKILL.md from split docs/cli/*.md and a template."
 
-    val cliFile = file("docs/cli.md")
+    val cliDir = file("docs/cli")
     val templateFile = file(".agents/skills/library-insight/SKILL.template.md")
     val outputFile = file(".agents/skills/library-insight/SKILL.md")
 
-    inputs.file(cliFile)
+    val scannersFile = file("docs/cli/scanners.md")
+    val explorerFile = file("docs/cli/explorer.md")
+    val analysisFile = file("docs/cli/analysis.md")
+    val versioningFile = file("docs/cli/versioning.md")
+    val dependenciesFile = file("docs/cli/dependencies.md")
+    val aiIntegrationFile = file("docs/cli/ai-integration.md")
+
+    inputs.dir(cliDir)
     inputs.file(templateFile)
     outputs.file(outputFile)
 
     doLast {
-        if (!cliFile.exists()) {
-            throw GradleException("docs/cli.md does not exist")
+        if (!cliDir.exists() || !cliDir.isDirectory) {
+            throw GradleException("docs/cli directory does not exist")
         }
         if (!templateFile.exists()) {
             throw GradleException("SKILL.template.md does not exist")
         }
 
-        val cliContent = cliFile.readText()
-        val startMarker = "<!-- --8<-- [start:commands] -->"
-        val endMarker = "<!-- --8<-- [end:commands] -->"
-        
-        val startIndex = cliContent.indexOf(startMarker)
-        val endIndex = cliContent.indexOf(endMarker)
-
-        if (startIndex == -1 || endIndex == -1 || startIndex >= endIndex) {
-            throw GradleException("Could not find start/end command markers in docs/cli.md")
-        }
-
-        val commandsSection = cliContent.substring(startIndex + startMarker.length, endIndex).trim()
-
-        // Shift headers: ## to ### (to fit in SKILL.md under ## Command Reference)
-        val shiftedCommands = commandsSection.lines().joinToString("\n") { line ->
-            if (line.startsWith("## ")) {
-                "### " + line.substring(3)
-            } else if (line.startsWith("### ")) {
-                "#### " + line.substring(4)
-            } else {
-                line
+        // Ordered categories/files
+        val categoryFiles = listOf(
+            "Scanners & Indexing" to scannersFile,
+            "API Explorer & Lookup" to explorerFile,
+            "Analysis & Diagnostics" to analysisFile,
+            "Versioning & Migration" to versioningFile,
+            "Maven & Dependency Resolution" to dependenciesFile,
+            "AI Context & Integration" to aiIntegrationFile
+        )
+
+        val commandsSection = buildString {
+            categoryFiles.forEachIndexed { index, (catTitle, file) ->
+                if (!file.exists()) {
+                    throw GradleException("${file.name} does not exist")
+                }
+                file.readLines().forEach { line ->
+                    append(line + "\n")
+                }
             }
-        }
+        }.trim()
 
         val templateContent = templateFile.readText()
-        val finalContent = templateContent.replace("{{COMMAND_REFERENCE}}", shiftedCommands)
+        val finalContent = templateContent.replace("{{COMMAND_REFERENCE}}", commandsSection)
         outputFile.writeText(finalContent)
-        logger.lifecycle("Successfully generated ${outputFile.path} from docs/cli.md")
+        logger.lifecycle("Successfully generated ${outputFile.path} from split CLI docs")
     }
 }
 

build.gradle.kts

@@ -268,10 +268,23 @@ echo ""
 library-insight doctor
 echo ""
 
+# ------------------------------------------------------------------
+# 23. KMP SCAN & EXPLAIN
+# Resolve target platforms and print platform indicators
+# ------------------------------------------------------------------
+echo ">> 23. KMP SCAN & EXPLAIN - Resolve KMP targets and merge API indexes"
+echo "   library-insight scan io.ktor:ktor-client-core:3.0.0 --db build/ktor-index.json"
+library-insight scan io.ktor:ktor-client-core:3.0.0 --db build/ktor-index.json > /dev/null
+echo "   library-insight explain io.ktor.client.HttpClient --db build/ktor-index.json"
+echo ""
+library-insight explain io.ktor.client.HttpClient --db build/ktor-index.json | head -n 35
+echo ""
+
 # Cleanup
 rm -rf "$DEMO_WORKSPACE"
+rm -f build/ktor-index.json
 
 echo "$SEPARATOR"
-echo " All 22 commands completed successfully!"
+echo " All 23 commands completed successfully!"
 echo "$SEPARATOR"
 echo ""

demo.sh

@@ -10,20 +10,20 @@ The skill is designed around one core rule: **do not guess from web examples whe
 
 When you install the CLI globally via the recommended shell installer (`install.sh`), the script automatically copies the agent skill file into your user profile configurations:
 
-*   `~/.cursor/skills/library-insight`
-*   `~/.gemini/config/skills/library-insight`
-*   `~/.claude/skills/library-insight`
-*   `~/.agents/skills/library-insight`
-*   `~/.copilot/skills/library-insight`
-*   `~/.junie/skills/library-insight`
+- `~/.cursor/skills/library-insight`
+- `~/.gemini/config/skills/library-insight`
+- `~/.claude/skills/library-insight`
+- `~/.agents/skills/library-insight`
+- `~/.copilot/skills/library-insight`
+- `~/.junie/skills/library-insight`
 
 Any active AI agent running on your computer will instantly discover and utilize the `library-insight` command tree when you ask a question.
 
 ---
 
 ## 2. Project Workspace Scoping
 
-If you want to install the skill scoped *only* to your current project directory (so that any developer working in the repository gets the skill context), run the following command in the project root:
+If you want to install the skill scoped _only_ to your current project directory (so that any developer working in the repository gets the skill context), run the following command in the project root:
 
 ```bash
 library-insight init

docs/ai-agents.md

@@ -50,21 +50,22 @@ graph TD
 
 ### Module Responsibilities
 
-*   `library-insight-common`: Low-level utility classes for ZIP/JAR/AAR archives extraction, Ktor asynchronous HTTP engines, and directory operations.
-*   `library-insight-model`: Contains immutable Kotlin serialization structures representing the public API schema (`LibraryApiIndex`).
-*   `library-insight-parser`: Performs raw Java bytecode parsing using the **ASM** library, extracting class fields, methods, generic signatures, and structures.
-*   `library-insight-kotlin`: Reads and parses compiled Kotlin Metadata header annotations (`@Metadata` via `kotlin-metadata-jvm`) to enrich signatures with Kotlin properties, nullability flags, and suspend keywords.
-*   `library-insight-search`: The query/search engine that matches search keywords against compiled packages, classes, constructors, methods, and variables.
-*   `library-insight-export`: Exporters that format API indices into target representations: **JSON**, **Markdown** reference documentation, and token-optimized **AI Context** pages.
-*   `library-insight-core`: The main orchestration hub. It coordinates the parsing, metadata enrichment, search routines, and calculates API differences/compatibility alerts.
-*   `library-insight-cli`: Command Line Interface definitions using **Clikt** mapping option/argument configurations.
+- `library-insight-common`: Low-level utility classes for ZIP/JAR/AAR archives extraction, Ktor asynchronous HTTP engines, and directory operations.
+- `library-insight-model`: Contains immutable Kotlin serialization structures representing the public API schema (`LibraryApiIndex`).
+- `library-insight-parser`: Performs raw Java bytecode parsing using the **ASM** library, extracting class fields, methods, generic signatures, and structures.
+- `library-insight-kotlin`: Reads and parses compiled Kotlin Metadata header annotations (`@Metadata` via `kotlin-metadata-jvm`) to enrich signatures with Kotlin properties, nullability flags, and suspend keywords.
+- `library-insight-search`: The query/search engine that matches search keywords against compiled packages, classes, constructors, methods, and variables.
+- `library-insight-export`: Exporters that format API indices into target representations: **JSON**, **Markdown** reference documentation, and token-optimized **AI Context** pages.
+- `library-insight-core`: The main orchestration hub. It coordinates the parsing, metadata enrichment, search routines, and calculates API differences/compatibility alerts.
+- `library-insight-cli`: Command Line Interface definitions using **Clikt** mapping option/argument configurations.
 
 ## Unified API Indexing Pipelines
 
-Library Insight exposes two different parsing pipelines depending on the target input:
+Library Insight exposes three different parsing pipelines depending on the target input:
 
 1. **Bytecode Scan Pipeline (`scan` command)**: Extracts signatures from compiled `.class` files (inside JAR/AAR/Maven artifacts) using the ASM library, enriched by `kotlin-metadata-jvm`.
-2. **Source Scan Pipeline (`scan-source` command)**: Extracts signatures directly from raw Java (`.java`) and Kotlin (`.kt`) source project files using JavaParser and Kotlin PSI compiler APIs.
+2. **Kotlin Multiplatform (KMP) Scan Pipeline (`scan` command)**: Resolves Maven coordinates, inspects Gradle Module Metadata (`.module` JSON), extracts platform targets from Kotlin Native `.klib` metadata files, and merges platform variants (`common`, `jvm`, `ios`, `js`, `wasm`) into a unified index.
+3. **Source Scan Pipeline (`scan-source` command)**: Extracts signatures directly from raw Java (`.java`) and Kotlin (`.kt`) source project files using JavaParser and Kotlin PSI compiler APIs.
 
 Both pipelines converge into the same unified `LibraryApiIndex` schema, allowing existing downstream search, explain, and export subcommands to function identically without separate workflows.