Skip to content

Commit 711bf9d

Browse files
Coding-MeetCoding-Meet
committed
Reposition Library Insight landing page copy and clean up repo refs
1 parent 6387c28 commit 711bf9d

8 files changed

Lines changed: 1784 additions & 732 deletions

File tree

‎.agents/skills/library-insight/scripts/install-cli.sh‎

100644100755
File mode changed.

‎README.md‎

Lines changed: 45 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,25 @@
11
# Library Insight 🔍
22

3-
Library Insight is a command-line tool that analyzes Java and Kotlin libraries (JAR/AAR) to inspect, extract, and index their complete public API surface from compiled bytecode and Kotlin metadata.
3+
AI coding assistants often guess Java/Kotlin library APIs from old docs, latest web examples, or a different version than the one installed in your project. That leads to missing methods, deprecated usage, wrong signatures, and wasted debugging time.
44

5-
Instead of requiring source code, the tool reads compiled `.class` structures (using ASM) and `@Metadata` annotations (using `kotlin-metadata-jvm`) to construct an accurate public API index.
5+
Library Insight fixes that by scanning the exact JAR/AAR, Gradle output, or Maven version you use. It reads compiled `.class` structures (using ASM) and Kotlin `@Metadata` annotations (using `kotlin-metadata-jvm`) to build a searchable, version-correct public API index.
66

7-
This is incredibly useful for:
7+
Use it when you need to:
88

9-
- Documentation generation
10-
- API compatibility verification (checking for breaking changes)
11-
- IDE extensions and indexing engines
12-
- Context generators supplying AI assistants with exact signatures
9+
- Know how to implement a library after adding it to a project.
10+
- Check which classes, methods, constructors, and properties exist in your installed version.
11+
- Stop AI from using examples from a newer, older, or undocumented version.
12+
- Find deprecated APIs and compare versions before rewriting code.
13+
- Give AI assistants exact signatures without dumping huge documentation files into context.
14+
15+
> **Core idea:** AI should code against the library version you actually use, not the version it remembers from the web.
1316
1417
---
1518

1619
## Key Features
1720

1821
- **Multi-Format Support**: Reads JARs, AARs (including nested JARs), directories, and Gradle build outputs.
22+
- **Version-Correct API Lookup**: Scans the exact artifact you point it at, so AI agents and developers see the real public API for that dependency version.
1923
- **Deep Metadata Extraction**:
2024
- **Classes/Interfaces/Objects**: Modifiers, companion objects, data/value flags, annotation markers, nested declarations, interfaces, inheritance.
2125
- **Constructors & Methods**: Visibility, parameter names, default arguments, return types, generic signatures/bounds, extension receivers, operators, infixes, inline, and suspend keywords.
@@ -27,6 +31,22 @@ This is incredibly useful for:
2731

2832
---
2933

34+
## Why This Exists
35+
36+
When you add a dependency, the first question is simple: "How do I use this version correctly?"
37+
38+
In real projects, that answer is often messy:
39+
40+
- AI may write code for the latest release while your project uses an older version.
41+
- AI may copy an old blog post where the method name no longer exists.
42+
- Official docs may be incomplete or not updated for the release you installed.
43+
- Deprecated methods may still appear in examples, while the replacement is hidden in release notes or source comments.
44+
- Huge generated docs waste AI context and make one class hard to find.
45+
46+
Library Insight turns the compiled library itself into the source of truth. Scan the dependency, then use `search`, `explain`, `diff`, or `ai-export` to give humans and AI agents exact, version-aware API information.
47+
48+
---
49+
3050
## Architecture & Modular Design
3151

3252
Library Insight follows **Clean Architecture** principles. Below is the modular dependency flow:
@@ -122,7 +142,9 @@ The executable binary will be generated at:
122142

123143
## AI Agent Skill Integration
124144

125-
Library Insight bundles a Custom AI Agent Skill (`SKILL.md`) that teaches AI assistants (like Claude, Gemini, Cursor, Copilot, Junie, etc.) how to execute scan and query commands automatically.
145+
Library Insight bundles a Custom AI Agent Skill (`SKILL.md`) that teaches AI assistants (like Claude, Gemini, Cursor, Copilot, Junie, etc.) to verify real dependency APIs before writing code.
146+
147+
The skill is designed around one rule: do not guess from web examples when the installed library version can be scanned directly. Agents should use `search`, `explain`, `diff`, and `ai-export` to confirm what exists in the actual artifact.
126148

127149
### 1. Global Auto-Integration
128150

@@ -158,16 +180,22 @@ This creates `.agents/skills/library-insight/SKILL.md` in the project root, enab
158180
> `library-insight <command> [options]`
159181
160182
> [!IMPORTANT]
183+
> **AI Agent Accuracy Rule:**
184+
> If you are an AI assistant, do not assume the library API from memory, latest web docs, or random examples. First scan or query the exact library version used by the project whenever possible.
185+
>
161186
> **AI Agent Token Optimization Rule:**
162-
> If you are an AI assistant (such as Cursor, Gemini, Claude, etc.), **DO NOT** read the entire raw `build/library-insight-index.json` or generated `API_REFERENCE.md` files directly using file-viewing tools. Doing so will bloat your context window and exceed token limits.
163-
> Instead, you **MUST** use the dedicated CLI query subcommands to lookup only the class details or signatures you need:
187+
> Do **not** read the entire raw `build/library-insight-index.json` or generated `API_REFERENCE.md` files directly using file-viewing tools. Doing so will bloat your context window and exceed token limits.
188+
> Instead, use the dedicated CLI query subcommands to lookup only the class details or signatures you need:
164189
> - Use **`library-insight search <query>`** to locate packages or classes.
165190
> - Use **`library-insight explain <class>`** to inspect full signatures and docs.
191+
> - Use **`library-insight diff <old> <new>`** before upgrading or replacing deprecated APIs.
166192
167193
### 1. Scan Library
168194

169195
Scan a JAR, AAR, local directory, or Maven coordinate.
170196

197+
Use this first when you need to know how a dependency should be implemented in the exact version your project uses.
198+
171199
> [!TIP]
172200
> **Offline-First & Smart Caching:**
173201
> - **Gradle Cache Lookup**: Before downloading from repositories over the network, `library-insight` scans your machine's Gradle cache (`~/.gradle/caches/modules-2/files-2.1/`). If the dependency coordinate has already been downloaded by Gradle/Android Studio, it is referenced directly without performing any disk copies—saving space and enabling fully offline scanning!
@@ -194,6 +222,8 @@ Saved API index to: /Users/meet/AndroidStudioProjects/Library-Insight/build/libr
194222

195223
Search for packages, classes, methods, or properties in the saved index.
196224

225+
Use this when you know part of a class or method name and need to find the matching API in the scanned version.
226+
197227
```bash
198228
# Search for Retrofit class matching patterns
199229
library-insight search Retrofit
@@ -210,6 +240,8 @@ Found 2 matching classes:
210240

211241
Print detailed structural details (modifiers, superclass, constructors, properties, methods, and documentation) about a specific class.
212242

243+
Use this before writing code that calls a class, especially when AI examples disagree with your installed dependency version.
244+
213245
```bash
214246
# Get full API structure of Retrofit class
215247
library-insight explain Retrofit
@@ -244,6 +276,8 @@ Exported MARKDOWN to: /Users/meet/AndroidStudioProjects/Library-Insight/build/AP
244276

245277
Compare two library archives directly to check for changes and potential breaking changes.
246278

279+
Use this when a method is deprecated, removed, renamed, or behaving differently between versions.
280+
247281
```bash
248282
# Detect breaking changes between Retrofit 2.9.0 and 2.11.0
249283
library-insight diff retrofit-2.9.0.jar retrofit-2.11.0.jar
@@ -270,7 +304,7 @@ Breaking Changes Found: NO
270304

271305
Generate a compact, token-efficient split context folder structure (`build/ai-context/` by default) containing individual class JSON files optimized for LLM prompts.
272306

273-
This solves the problem of massive single files (like `API_REFERENCE.md`) by splitting package namespaces and classes into separate, tiny files. AI agents (Cursor, Claude, Gemini) can read `metadata.json` first, and then load only the specific class JSON files they need, reducing token usage by over 95%.
307+
This solves two problems at once: AI gets exact APIs from the scanned dependency version, and it avoids massive single files like `API_REFERENCE.md`. Agents can read `metadata.json` first, then load only the specific class JSON files they need, reducing token usage by over 95%.
274308

275309
```bash
276310
library-insight ai-export

‎demo.sh‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
#!/bin/bash
2+
# ==========================================================================
3+
# Library Insight - All CLI Commands Demo Script
4+
# ==========================================================================
5+
# This script demonstrates every available library-insight CLI command.
6+
# Run it step by step or as a full walkthrough.
7+
#
8+
# Requirements:
9+
# - JDK 17+
10+
# - library-insight installed globally via: npm install -g library-insight
11+
#
12+
# Usage:
13+
# chmod +x demo.sh
14+
# ./demo.sh
15+
# ==========================================================================
16+
17+
set -e
18+
19+
SEPARATOR="=================================================="
20+
LIBRARY="com.squareup.retrofit2:retrofit:2.11.0"
21+
LIBRARY_OLD="com.squareup.retrofit2:retrofit:2.9.0"
22+
LIBRARY_NEW="com.squareup.retrofit2:retrofit:2.11.0"
23+
DEMO_WORKSPACE="/tmp/library-insight-demo-workspace-$$"
24+
25+
echo ""
26+
echo "$SEPARATOR"
27+
echo " LIBRARY INSIGHT - CLI COMMANDS DEMO"
28+
echo "$SEPARATOR"
29+
echo ""
30+
31+
# ------------------------------------------------------------------
32+
# 1. SCAN
33+
# Scan a Maven coordinate, local JAR, or AAR from Gradle cache
34+
# ------------------------------------------------------------------
35+
echo ">> [1/10] SCAN - Analyze library and build API index"
36+
echo " library-insight scan $LIBRARY"
37+
echo ""
38+
library-insight scan $LIBRARY
39+
echo ""
40+
41+
# ------------------------------------------------------------------
42+
# 2. SEARCH
43+
# Search for classes, interfaces, methods, or packages in the index
44+
# ------------------------------------------------------------------
45+
echo ">> [2/10] SEARCH - Find a class by name"
46+
echo " library-insight search Retrofit"
47+
echo ""
48+
library-insight search Retrofit
49+
echo ""
50+
51+
# ------------------------------------------------------------------
52+
# 3. EXPLAIN
53+
# Print detailed structure of a class (constructors, methods, javadoc)
54+
# ------------------------------------------------------------------
55+
echo ">> [3/10] EXPLAIN - Inspect class structure and method signatures"
56+
echo " library-insight explain Retrofit"
57+
echo ""
58+
library-insight explain Retrofit
59+
echo ""
60+
61+
# ------------------------------------------------------------------
62+
# 4. EXPORT MARKDOWN
63+
# Export the full API index to a readable Markdown reference sheet
64+
# (Warning: can be very large for big libraries - use ai-export for AI prompts)
65+
# ------------------------------------------------------------------
66+
echo ">> [4/10] EXPORT MARKDOWN - Save readable API reference to file"
67+
echo " library-insight export markdown"
68+
echo ""
69+
library-insight export markdown
70+
echo ""
71+
72+
# ------------------------------------------------------------------
73+
# 5. EXPORT JSON
74+
# Export the full API index to raw JSON format
75+
# ------------------------------------------------------------------
76+
echo ">> [5/10] EXPORT JSON - Save raw JSON index to file"
77+
echo " library-insight export json"
78+
echo ""
79+
library-insight export json
80+
echo ""
81+
82+
# ------------------------------------------------------------------
83+
# 6. DIFF
84+
# Compare two library JAR versions and detect breaking changes
85+
# ------------------------------------------------------------------
86+
echo ">> [6/10] DIFF - Compare two library versions for breaking changes"
87+
echo " library-insight diff $LIBRARY_OLD $LIBRARY_NEW"
88+
echo ""
89+
library-insight diff $LIBRARY_OLD $LIBRARY_NEW
90+
echo ""
91+
92+
# ------------------------------------------------------------------
93+
# 7. AI-EXPORT
94+
# Generate compact per-class JSON files for AI token-efficient context
95+
# Use this for AI prompts instead of loading the large API_REFERENCE.md
96+
# ------------------------------------------------------------------
97+
echo ">> [7/10] AI-EXPORT - Generate token-efficient AI context directory"
98+
echo " library-insight ai-export"
99+
echo ""
100+
library-insight ai-export
101+
echo ""
102+
103+
# ------------------------------------------------------------------
104+
# 8. INIT
105+
# Write a workspace-scoped SKILL.md so local AI agents can discover the CLI
106+
# ------------------------------------------------------------------
107+
echo ">> [8/10] INIT - Initialize AI agent skill for this workspace"
108+
echo " library-insight init"
109+
echo ""
110+
mkdir -p "$DEMO_WORKSPACE"
111+
(
112+
cd "$DEMO_WORKSPACE"
113+
library-insight init
114+
)
115+
echo ""
116+
117+
# ------------------------------------------------------------------
118+
# 9. SKILLS ADD
119+
# Install or update the agent SKILL.md in the current workspace
120+
# ------------------------------------------------------------------
121+
echo ">> [9/10] SKILLS ADD - Install AI agent skill to current workspace"
122+
echo " library-insight skills add"
123+
echo ""
124+
(
125+
cd "$DEMO_WORKSPACE"
126+
library-insight skills add
127+
library-insight skills list
128+
)
129+
echo ""
130+
131+
# ------------------------------------------------------------------
132+
# 10. CLEAR-CACHE
133+
# Delete all locally cached Maven artifacts to free up space
134+
# ------------------------------------------------------------------
135+
echo ">> [10/10] CLEAR-CACHE - Remove locally cached downloaded artifacts"
136+
echo " library-insight clear-cache"
137+
echo ""
138+
library-insight clear-cache
139+
echo ""
140+
141+
# ------------------------------------------------------------------
142+
# BONUS: DOCTOR
143+
# Run full diagnostic checks - Java, Node.js, caches, agent skill status
144+
# ------------------------------------------------------------------
145+
echo ">> [BONUS] DOCTOR - Run system diagnostics and check tool health"
146+
echo " library-insight doctor"
147+
echo ""
148+
library-insight doctor
149+
echo ""
150+
151+
echo "$SEPARATOR"
152+
echo " All commands completed successfully!"
153+
echo "$SEPARATOR"
154+
echo ""

0 commit comments

Comments
 (0)