logicstamp-context 0.5.0 → 0.5.2

package/LLM_CONTEXT.md

@@ -94,7 +94,7 @@ The `context_main.json` file serves as a directory index:
     }
   ],
   "meta": {
-      "source": "logicstamp-context@0.5.0"
+      "source": "logicstamp-context@0.5.1"
   }
 }
 ```
@@ -117,7 +117,7 @@ Each folder's `context.json` contains an array of LogicStamp bundles. Each bundl
 - `graph.edges` lists dependency relationships between nodes (empty when analysis depth is 1).
 - `meta` section contains two critical fields:
   - `missing`: Array of unresolved dependencies. Each entry includes `name` (import path), `reason` (why it failed), and `referencedBy` (source component). Empty array indicates complete dependency resolution.
-  - `source`: Generator version string (e.g., `"logicstamp-context@0.5.0"`) for compatibility tracking.
+  - `source`: Generator version string (e.g., `"logicstamp-context@0.5.1"`) for compatibility tracking.
 - Example bundle skeleton:
 
 ```
@@ -322,6 +322,43 @@ Even when token counts are similar, structured data is **significantly faster to
 3. **Filter by `entryId`**: Within a folder's context file, filter bundles by `entryId` to focus on relevant modules.
 4. **Combine multiple folders**: When a task spans multiple folders, load the relevant folder context files and combine their bundles.
 
+### Finding Components: Root vs Dependencies
+
+LogicStamp organizes components into two categories:
+
+- **Root components** - Components that have their own bundles (listed in `context_main.json` under each folder's `components` array). These are entry points that are **not imported by any other components** in the project. Each root component gets its own bundle.
+- **Dependencies** - Components that are imported by root components. They appear in the importing component's bundle as nodes in `graph.nodes[]`, not as separate root bundles. A dependency can appear in multiple bundles if it's imported by multiple root components.
+
+**Workflow for finding a component:**
+
+1. **Check `context_main.json` first** - Look in the `folders[]` array for the component's file name in the `components` list. If found, it's a root component with its own bundle in that folder's `context.json`.
+2. **If not found as a root** - The component is likely a dependency. Find which root component(s) import it:
+   - Search for import statements in source code to identify importing components
+   - Check bundles in the same folder (dependencies are often in the same folder as their importing component)
+   - Search through bundle `graph.nodes[]` arrays to find which bundles include the dependency
+3. **Read the importing root's bundle** - The dependency's contract will be in `graph.nodes[]` of that bundle. Each bundle in a folder's `context.json` is an array - find the bundle whose `entryId` matches the importing root component.
+
+**Example:**
+
+```
+FAQ.tsx is imported by src/app/page.tsx
+→ FAQ is NOT listed in context_main.json folders[].components (not a root)
+→ FAQ IS in src/app/page.tsx bundle (as a dependency node in graph.nodes[])
+→ To access FAQ: 
+   1. Read src/app/context.json (array of bundles)
+   2. Find bundle with entryId: "src/app/page.tsx"
+   3. Look in that bundle's graph.nodes[] for FAQ.tsx contract
+```
+
+**Why this matters:**
+
+- Root components = own bundles (e.g., `Features.tsx`, `Stats.tsx` in `src/components/sections/context.json`)
+- Dependencies = included in importing root component's bundle graph (e.g., `FAQ.tsx` in `src/app/page.tsx` bundle)
+- This structure matches how developers think: pages/features are entry points, their dependencies are included automatically
+- A component can be a dependency in multiple bundles if imported by multiple root components
+
+**Common mistake:** Looking for a component as a root when it's actually a dependency. Always check `context_main.json` first to see if it's listed as a root component.
+
 ### Working with the Index
 
 - Use `context_main.json` to:

package/README.md

@@ -7,43 +7,43 @@
     </picture>
   </a>
 
-### Deterministic codebase context for AI assistants.
+### Deterministic architectural context for TypeScript codebases.
+
+  Understand your codebase through explicit component contracts and relationships.
 
   <small><em>TypeScript · React · Next.js · Vue (TS/TSX) · Express · NestJS</em></small>
-  <br/>
-  <br/>
 
-  **Structured component contracts for AI - props, hooks, dependencies extracted and organized.**
+  **Designed to work alongside Claude, Cursor, Copilot Chat, and MCP-based agents.**
 
   <br/>
   <a href="https://github.com/LogicStamp">
     <img src="./assets/logicstamp-fox.svg" alt="LogicStamp Fox Mascot" width="100" style="min-width: 80px;">
   </a>
 
-  [![Version](https://img.shields.io/badge/version-0.5.0-8b5cf6.svg)](https://www.npmjs.com/package/logicstamp-context)
+  [![Version](https://img.shields.io/badge/version-0.5.2-8b5cf6.svg)](https://www.npmjs.com/package/logicstamp-context)
   ![Beta](https://img.shields.io/badge/status-beta-orange.svg)
   [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
   ![Node](https://img.shields.io/badge/node-%3E%3D18.18.0-brightgreen.svg)
   [![CI](https://github.com/LogicStamp/logicstamp-context/workflows/CI/badge.svg)](https://github.com/LogicStamp/logicstamp-context/actions)
 
 </div>
+<br/>
 
-## The Problem
+<details>
+<summary><strong>📌 TL;DR</strong></summary>
 
-AI coding assistants read your source code but don't understand your architecture. They hallucinate prop names, invent dependencies, and miss breaking changes - because raw source code isn't structured context.
+**What it does:** Uses AST parsing to extract deterministic component contracts from your TypeScript codebase.
 
-**LogicStamp generates deterministic component contracts that:**
-- Stay in sync with your code (watch mode auto-regenerates)
-- Expose what matters (props, hooks, dependencies) without implementation noise
-- Work with any MCP-compatible AI assistant (Claude, Cursor, etc.)
+**What you get:** Structured JSON bundles (props, hooks, dependencies, APIs) optimized for AI consumption.
 
-![LogicStamp MCP Workflow](./assets/logicstamp-workflow.gif)
-*Context bundles generated and consumed across MCP-powered AI workflows.*
+**Why it matters:** Gives AI assistants explicit architectural context without reading implementations - prevents inferred prop names and missed dependencies by making contracts explicit.
+
+</details>
 
-<br/>
 <details>
 <summary><strong>📑 Table of Contents</strong></summary>
 
+- [The Problem](#the-problem)
 - [Quick Start](#quick-start)
 - [Drift Detection](#drift-detection)
 - [Why Structured Context?](#why-structured-context)
@@ -60,8 +60,32 @@ AI coding assistants read your source code but don't understand your architectur
 - [Known Limitations](#known-limitations)
 - [Requirements](#requirements)
 - [Need Help?](#need-help)
+- [License](#license)
 </details>
 
+## The Problem
+
+AI coding assistants can read your source code, but they lack explicit structural context. They often infer prop names, invent dependencies, and miss breaking changes - because raw source code isn't machine-structured context.
+
+**LogicStamp Context** is a compiler-like static analyzer that emits deterministic architectural contracts from your TypeScript source code.
+
+**LogicStamp Context generates deterministic component contracts that:**
+- Stay in sync with your code (watch mode auto-regenerates)
+- Expose what matters (props, hooks, dependencies) without implementation noise
+- Work with any MCP-compatible AI assistant (Claude, Cursor, etc.)
+
+![LogicStamp MCP Workflow](./assets/logicstamp-workflow.gif)
+*Context bundles generated and consumed across MCP-powered AI workflows.*
+
+**Same code ⇒ same context output.** Diff outputs to detect architectural drift.
+
+```
+TypeScript Code  →  AST Parsing  →  Deterministic Contracts  →  AI Assistant
+   (.ts/.tsx)        (ts-morph)      (context.json bundles)      (Claude, Cursor)
+```
+
+---
+
 ## Quick Start
 
 **Try it in 30 seconds (no install required):**
@@ -84,29 +108,34 @@ stamp context
 
 > **ℹ️ Note:** With `npx`, run `npx logicstamp-context context`. After global install, use `stamp context`.
 
+📋 **For detailed setup instructions, see the [Getting Started Guide](https://logicstamp.dev/docs/getting-started).**
+
 ## Drift Detection
 
-Compare regenerated context against existing context files:
+Compare regenerated context against existing context files (useful for one-time checks and CI workflows):
 
 ```bash
 stamp context compare          # detect changes
 stamp context compare --approve  # update (like jest -u)
 ```
 
-Useful during development to see what changed. Shows added/removed components, changed props, hooks, dependencies.
+Shows added/removed components, changed props, hooks, dependencies.
+
+> **💡 Tip:** If you're using [watch mode](#watch-mode), context files are automatically regenerated and changes are shown in real-time. Use `compare` for one-time checks or CI workflows.
 
-> **Note:** Context files are gitignored by default. For CI-based drift detection (comparing against git refs like `main` or `HEAD~1`), see the [roadmap](https://logicstamp.dev/roadmap) - this feature is planned for a future release.
+> ⚠️ **Note:** Context files are gitignored by default. For CI-based drift detection, the `--baseline git:<ref>` option (e.g., `--baseline git:main`) is **not yet implemented**. Until automation is available, use the manual workflow: generate context from current code, checkout baseline branch, generate context from baseline, then compare. See the [roadmap](https://logicstamp.dev/roadmap) for planned automation.
 
 ## Why Structured Context?
 
-| Without LogicStamp | With LogicStamp |
+| Without LogicStamp Context | With LogicStamp Context |
 |-------------------|-----------------|
-| AI reads 200 lines to understand a component | AI reads a 20-line contract |
+| AI parses 200 lines of implementation to infer a component's interface | AI reads a 20-line interface contract |
 | Props/hooks inferred (often wrong) | Props/hooks explicit and verified |
 | No way to know if context is stale | Watch mode catches changes in real-time |
 | Different prompts = different understanding | Deterministic: same code = same contract |
+| Manual context gathering: "Here's my Button component..." | Structured contracts: AI understands architecture automatically |
 
-**The key insight:** AI assistants don't need your implementation - they need your *interfaces*. LogicStamp extracts what matters and discards the noise.
+**The key insight:** AI assistants don't need your implementation - they need your *interfaces*. LogicStamp Context extracts what matters and discards the noise.
 
 ### What "Structured" Means
 
@@ -120,7 +149,7 @@ export const Button = ({ variant = 'primary', disabled, onClick, children }) =>
 }
 ```
 
-LogicStamp generates:
+LogicStamp Context generates:
 
 ```json
 {
@@ -136,7 +165,7 @@ LogicStamp generates:
 }
 ```
 
-Pre-parsed. Categorized. Deterministic. The AI reads contracts, not implementations.
+Pre-parsed. Categorized. Stable. The AI reads contracts, not implementations.
 
 ## ⚡ Features
 
@@ -149,7 +178,7 @@ Pre-parsed. Categorized. Deterministic. The AI reads contracts, not implementati
 **Analysis:**
 - React/Next.js/Vue component extraction (props, hooks, state, deps)
 - Backend API extraction (Express.js, NestJS routes and controllers)
-- Dependency graphs with cycle detection
+- Dependency graphs (handles circular dependencies)
 - Style metadata extraction (Tailwind, SCSS, MUI, shadcn)
 - Next.js App Router detection (client/server, layouts, pages)
 
@@ -175,9 +204,9 @@ Strict watch catches breaking changes that affect consumers:
 
 | Violation | Example |
 |-----------|---------|
-| `prop_removed` | Removed `disabled` prop from Button |
-| `event_removed` | Removed `onSubmit` callback |
-| `function_removed` | Deleted exported `formatDate()` |
+| `breaking_change_prop_removed` | Removed `disabled` prop from Button |
+| `breaking_change_event_removed` | Removed `onSubmit` callback |
+| `breaking_change_function_removed` | Deleted exported `formatDate()` |
 | `contract_removed` | Deleted entire component |
 
 **Recommended workflow:**
@@ -192,16 +221,49 @@ Context always fresh as you code
 ## How it Works
 
 1. **Scan** - Finds all `.ts` and `.tsx` files in your project
-2. **Analyze** - Parses components and APIs using TypeScript AST
+2. **Analyze** - Parses components and APIs using TypeScript AST (Abstract Syntax Tree) via `ts-morph`
 3. **Extract** - Builds contracts with props, hooks, state, signatures
 4. **Graph** - Creates dependency graph showing relationships
 5. **Bundle** - Packages context optimized for AI consumption
 6. **Organize** - Groups by folder, writes `context.json` files
 7. **Index** - Creates `context_main.json` with metadata and statistics
 
+**Why AST parsing matters:** Unlike text-based parsing (regex, string matching), AST parsing understands TypeScript's syntax structure, type information, and code semantics. This enables LogicStamp Context to accurately extract prop types, detect hooks, understand component composition, and handle complex patterns reliably - making contracts deterministic and trustworthy.
+
 No pre-compilation needed. One command.
 
-> **Tip:** Use `stamp context` for basic contracts. Use `stamp context style` when you need style metadata (Tailwind classes, SCSS selectors, layout patterns).
+> **💡Tip:** Use `stamp context` for basic contracts. Use `stamp context style` when you need style metadata (Tailwind classes, SCSS selectors, layout patterns).
+
+<details>
+<summary><strong>📋 What LogicStamp Context Is (and Isn't)</strong></summary>
+
+**LogicStamp Context IS:**
+
+✅ **An AST-based static analysis tool** - Uses the TypeScript compiler API (via ts-morph) to extract component contracts, props, hooks, and dependencies in a deterministic, type-aware way.
+
+✅ **A deterministic context generator** - Produces structured architectural contract bundles for tooling and AI workflows.
+
+✅ **Local and offline-first** - Runs entirely on your machine (no cloud services, no network calls).
+
+✅ **Framework-aware** - Understands React, Next.js, Vue, Express, and NestJS patterns and extracts relevant metadata.
+
+✅ **Non-opinionated** - Describes what exists without enforcing patterns or architectural decisions.
+
+**LogicStamp Context IS NOT:**
+
+❌ **A code generator** - It never writes or modifies your source code.
+
+❌ **A documentation generator** - It produces structured contracts, not documentation.
+
+❌ **A build or runtime tool** - It analyzes static source code only; it does not execute or bundle your application.
+
+❌ **A linter, formatter, or testing framework** - It does not check code quality or run tests.
+
+❌ **An AI behavior controller** - It provides structured context; it does not alter AI responses.
+
+❌ **A replacement for reading code** - It accelerates understanding without replacing engineering judgment.
+
+</details>
 
 ## MCP Server
 
@@ -217,7 +279,7 @@ Then configure your AI assistant to use the LogicStamp MCP Server.
 
 ## Example Output
 
-LogicStamp generates structured JSON bundles organized by folder:
+LogicStamp Context generates structured JSON bundles organized by folder:
 
 ```json
 {
@@ -261,12 +323,12 @@ After installation, the `stamp` command is available globally.
 
 **Automatic Secret Protection**
 
-LogicStamp protects sensitive data in generated context:
+LogicStamp Context protects sensitive data in generated context:
 
 - **Security scanning by default** - `stamp init` scans for secrets (API keys, passwords, tokens)
 - **Automatic sanitization** - Detected secrets replaced with `"PRIVATE_DATA"` in output
 - **Manual exclusions** - Use `stamp ignore <file>` to exclude files via `.stampignore`
-- **Safe by default** - Only metadata included; credentials only appear in `--include-code full` mode
+- **Safe by default** - Only metadata included. Credentials only appear in `--include-code full` mode
 
 > **⚠️ Seeing `"PRIVATE_DATA"` in output?** Review `stamp_security_report.json`, remove hardcoded secrets from source, use environment variables instead.
 
@@ -302,6 +364,7 @@ stamp context clean [path]         # Remove generated files
 | `--stats` | Emit JSON stats with token estimates |
 | `--out <path>` | Output directory |
 | `--quiet` | Suppress verbose output |
+| `--strict-missing` | Exit with error if any missing dependencies found (CI-friendly) |
 | `--debug` | Show detailed hash info (watch mode) |
 | `--log-file` | Write change logs to `.logicstamp/` (watch mode) |
 
@@ -316,13 +379,13 @@ stamp context clean [path]         # Remove generated files
 | **Vue 3** | Partial | Composition API (TS/TSX only, not .vue SFC) |
 | **Express.js** | Full | Routes, middleware, API signatures |
 | **NestJS** | Full | Controllers, decorators, API signatures |
-| **UI Libraries** | Full | Material UI, ShadCN, Radix, Tailwind, Styled Components, SCSS |
+| **UI Libraries** | Full | Material UI, ShadCN, Radix, Tailwind, Styled Components, SCSS, Chakra UI, Ant Design (component usage, props, composition; not raw CSS) |
 
-> **ℹ️ Note:** LogicStamp analyzes `.ts` and `.tsx` files only. JavaScript files are not analyzed.
+> **ℹ️ Note:** LogicStamp Context analyzes `.ts` and `.tsx` files only. JavaScript files are not analyzed.
 
 ## Documentation
 
-**[Full documentation at logicstamp.dev/docs](https://logicstamp.dev/docs)**
+**Full documentation at [logicstamp.dev/docs](https://logicstamp.dev/docs)**
 
 - [Getting Started Guide](https://logicstamp.dev/docs/getting-started)
 - [Usage Guide](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/usage.md)
@@ -334,7 +397,7 @@ stamp context clean [path]         # Remove generated files
 
 ## Known Limitations
 
-LogicStamp is in beta. Some edge cases are not fully supported.
+LogicStamp Context is in beta. Some edge cases are not fully supported.
 
 📋 **See [docs/limitations.md](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/limitations.md)** for the full list.
 
@@ -350,7 +413,7 @@ LogicStamp is in beta. Some edge cases are not fully supported.
 
 ## License
 
-MIT
+[MIT](LICENSE)
 
 ---
 

package/dist/extractors/styling/antd.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Ant Design extractor - Extracts Ant Design component library usage
+ */
+import { SourceFile } from 'ts-morph';
+/**
+ * Extract Ant Design usage from a source file
+ */
+export declare function extractAntDesign(source: SourceFile): {
+    components: string[];
+    packages: string[];
+    features: {
+        usesTheme?: boolean;
+        usesConfigProvider?: boolean;
+        usesForm?: boolean;
+        usesLocale?: boolean;
+        usesIcons?: boolean;
+    };
+};
+//# sourceMappingURL=antd.d.ts.map

package/dist/extractors/styling/antd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"antd.d.ts","sourceRoot":"","sources":["../../../src/extractors/styling/antd.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAA+D,MAAM,UAAU,CAAC;AAyBnG;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG;IACpD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE;QACR,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,CAAC;CACH,CA4TA"}