diff --git a/docs/context/README.md b/docs/context/README.md index 4c705f6..0833235 100644 --- a/docs/context/README.md +++ b/docs/context/README.md @@ -1,9 +1,9 @@
- - - LogicStamp + + + LogicStamp @@ -16,9 +16,8 @@ LogicStamp Context is a CLI that compiles TypeScript codebases into deterministic, diffable architectural contracts and dependency graphs - a compact, structured source of truth for AI coding workflows. -Watch mode. Strict, auditable diffs. Real-time breaking change detection. AST-based contract extraction. - -**Includes an MCP server. Works with Claude, Cursor, Copilot Chat, and any MCP-compatible agent.** +Includes watch mode, strict, auditable diffs, and real-time breaking change detection. +Use with [logicstamp-mcp](https://github.com/LogicStamp/logicstamp-mcp) to feed structured context into **Claude**, **Cursor**, and other MCP-compatible assistants.
@@ -46,13 +45,12 @@ Watch mode. Strict, auditable diffs. Real-time breaking change detection. AST-ba - [Watch Mode](#watch-mode) - [How it Works](#how-it-works) - [MCP Server](#mcp-server) -- [Example Output](#example-output) -- [Installation](#installation) - [Security](#security) - [Usage](#usage) - [Framework Support](#framework-support) - [Documentation](#documentation) - [Known Limitations](#known-limitations) +- [Benchmarks](#benchmarks) - [Requirements](#requirements) - [Need Help?](#need-help) - [License](#license) @@ -65,20 +63,20 @@ They hallucinate props, miss dependencies, and can’t detect when a breaking ch Example: your `Button` accepts `variant` and `disabled`, but the AI suggests `isLoading` because it saw that pattern elsewhere. Without a structured contract, there is no reliable source of truth. -**LogicStamp Context** compiles TypeScript into deterministic architectural contracts and dependency graphs - a machine-readable representation of your system that AI tools can consume instead of parsing raw implementation code. +**LogicStamp Context** derives that layer from your TypeScript - explicit interfaces and dependency structure for tools to consume instead of inferring from implementation. + +#### Key Capabilities: -These contracts: +- **Contracts, not raw source** - Props, hooks, routes, and dependency edges extracted for tools +- **Deterministic & diffable** - Same code → same bundles +- **Stays current** - Watch mode keeps context aligned with your codebase +- **MCP-ready** - Works with Claude, Cursor, and MCP-compatible assistants -- Stay in sync with your code (watch mode auto-regenerates) -- Expose interfaces (props, hooks, APIs) without implementation noise -- Are deterministic, diffable, and auditable -- Enable early detection of architectural drift and breaking changes +See the full list in [Features](#-features). ![LogicStamp MCP Workflow](./assets/logicstamp-workflow.gif) *Example workflow: `stamp context --strict-watch` generates context bundles that MCP-powered assistants use to explain component architecture (ThemeContext shown here).* -**Same code ⇒ same context output.** Contracts are diffable, so you can detect drift and breaking changes. - ``` TypeScript Code → Compilation → Deterministic Contracts → AI Assistant (.ts/.tsx) (ts-morph) (context.json bundles) (Claude, Cursor) @@ -88,9 +86,10 @@ TypeScript Code → Compilation → Deterministic Contracts → AI Assista ## Quick Start -**Try it in 30 seconds (no install required):** +No install required: + ```bash -npx logicstamp-context context +npx -y logicstamp-context@latest context ``` Scans your repo and writes `context.json` files + `context_main.json` for AI tools. @@ -99,14 +98,22 @@ Scans your repo and writes `context.json` files + `context_main.json` for AI too - 📁 `context.json` files - one per folder with components, preserving your directory structure - 📋 `context_main.json` - index file with project overview and folder metadata -**For a complete setup (recommended):** +### Installation + +For ongoing use, install the CLI globally: + ```bash npm install -g logicstamp-context +``` + +The `stamp` command is then available everywhere. Initialize and generate context: + +```bash stamp init # sets up .gitignore, scans for secrets stamp context ``` -> **ℹ️ Note:** With `npx`, run `npx logicstamp-context context`. After global install, use `stamp context`. +> **ℹ️ Note:** Without a global install, use `npx -y logicstamp-context@latest context`. After `npm install -g logicstamp-context`, use `stamp context`. 📋 **For detailed setup instructions, see the [Getting Started Guide](https://logicstamp.dev/docs/getting-started).** @@ -114,17 +121,18 @@ stamp context | Without LogicStamp Context | With LogicStamp Context | |-------------------|-----------------| -| AI parses 200 lines of implementation to infer a component's interface | AI reads a 20-line interface 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 Context extracts what matters and discards the noise. +**Key insight:** AI assistants don’t need your implementation - they need your *interfaces*. +LogicStamp extracts what matters and discards the noise. ### What "Structured" Means -Instead of shipping raw source code to AI: +Instead of sending raw source code to AI: ```typescript // Raw: AI must parse and infer @@ -152,8 +160,12 @@ LogicStamp Context generates: Pre-parsed. Categorized. Stable. The AI reads contracts, not implementations. +On disk, each folder’s `context.json` is a **LogicStampBundle**: contracts live under `graph.nodes`, with `graph.edges` for dependencies. **`context_main.json`** indexes folders and metadata. **Full JSON shape:** [docs/reference/schema.md](docs/reference/schema.md). + ## ⚡ Features +**Under the hood:** the TypeScript compiler API (via ts-morph). **Analysis-only** - it describes your codebase and emits context files. It does not transform or refactor your source. + **Core:** - **Deterministic contracts** - Same input = same output, auditable in version control - **Watch mode** - Auto-regenerate on file changes with incremental rebuilds @@ -173,6 +185,14 @@ Pre-parsed. Categorized. Stable. The AI reads contracts, not implementations. - Security-first: automatic secret detection and sanitization - Zero config required - sensible defaults, works out of the box +### How it fits your stack + +- **Works alongside `tsc`** - Focuses on contract structure and change detection, not type-checking. Use `tsc --noEmit` for compiler errors. `compare --strict` and `--strict-watch` flag **contract-level** breaking changes. +- **Beyond `.d.ts`** - Adds semantic contracts, dependency graphs, and diffable hashes (`semanticHash`, `bundleHash`) alongside declaration surfaces. +- **Context, not control** - Feeds structured context to assistants. Decisions stay with you. + +📋 **For detailed behavior, CLI options, and workflows, see the [Usage guide](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/guides/usage.md).** + ## Watch Mode

@@ -213,7 +233,7 @@ The status block only appears when violations change (not on every file change), *Example terminal output showing violations and session status.* -> ℹ️ **Note:** Strict Watch currently detects breaking changes at the source. Next step: a symbol-level import/export reverse index to trace which consumer files will break. +> ℹ️ **Note:** Strict Watch currently detects breaking changes at the source. Next step: a symbol-level import/export reverse index to trace which consumer files will break. See [docs/cli/watch.md](docs/cli/watch.md) for complete documentation. ### One-time Comparison @@ -246,42 +266,9 @@ The compilation pipeline: 5. **Emit** - Outputs `context.json` bundles per folder 6. **Index** - Generates `context_main.json` with metadata and statistics -**Why AST-based compilation matters:** LogicStamp leverages the full TypeScript compiler (via ts-morph) for deterministic, type-aware contract extraction. Prop types, hooks, and composition patterns are resolved structurally - not inferred from text or retrieval. - One command. No build step required. -> **💡Tip:** Use `stamp context` for basic contracts. Use `stamp context style` when you need style metadata (Tailwind classes, SCSS selectors, layout patterns). Use `--style-mode lean` (default) for compact output or `--style-mode full` for detailed arrays. - -

-📋 What LogicStamp Context Is (and Isn't) - -**LogicStamp Context IS:** - -✅ **A context compiler** - Uses the TypeScript compiler API (via ts-morph) to compile source code into deterministic architectural contracts. - -✅ **Deterministic** - Same input always produces the same output. Contracts are auditable and diffable. - -✅ **Local execution** - 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 compiles contracts from static source code; 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. - -
+> **💡 Tip:** Use `stamp context` for basic contracts. Use `stamp context style` when you need style metadata (Tailwind classes, SCSS selectors, layout patterns). Use `--style-mode lean` (default) for compact output or `--style-mode full` for detailed arrays. ## MCP Server @@ -297,48 +284,6 @@ Then configure your AI assistant to use the LogicStamp MCP Server. 📋 **See [MCP Getting Started Guide](https://logicstamp.dev/docs/mcp/getting-started)** for setup instructions. -## Example Output - -LogicStamp Context generates structured JSON bundles organized by folder: - -```json -{ - "type": "LogicStampBundle", - "entryId": "src/components/Button.tsx", - "graph": { - "nodes": [ - { - "entryId": "src/components/Button.tsx", - "contract": { - "kind": "react:component", - "interface": { - "props": { - "variant": { "type": "literal-union", "literals": ["primary", "secondary"] }, - "onClick": { "type": "function", "signature": "() => void" } - } - }, - "composition": { - "hooks": ["useState"], - "components": ["./Icon"] - } - } - } - ], - "edges": [["src/components/Button.tsx", "./Icon"]] - } -} -``` - -📋 **See [docs/schema.md](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/schema.md)** for complete format documentation. - -## Installation - -```bash -npm install -g logicstamp-context -``` - -After installation, the `stamp` command is available globally. - ## Security **Automatic Secret Protection** @@ -403,34 +348,42 @@ stamp context clean [path] # Remove generated files | **React** | Full | Components, hooks, props, styles | | **Next.js** | Full | App Router roles, segment paths, metadata | | **Vue 3** | Partial | Composition API (TS/TSX only, not .vue SFC) | -| **Express.js** | Full | Routes, middleware, API signatures | +| **Express.js** | Full | Routes, API signatures (middleware not extracted. see [limitations](docs/reference/limitations.md)) | | **NestJS** | Full | Controllers, decorators, API signatures | -| **UI Libraries** | Full | Material UI, ShadCN, Radix, Tailwind, Styled Components, SCSS, Chakra UI, Ant Design (component usage, props, composition; not raw CSS) | +| **UI Libraries** | Full | Material UI, ShadCN, Radix, Tailwind, Styled Components, CSS/SCSS (modules & imports), Chakra UI, Ant Design | -> **ℹ️ Note:** LogicStamp Context analyzes `.ts` and `.tsx` files only. JavaScript files are not analyzed. +> ℹ️ **Note:** LogicStamp Context analyzes `.ts` and `.tsx` files only (JavaScript is not analyzed). Styling (Tailwind, SCSS, CSS Modules, UI libraries) is extracted as **structured style metadata**, not raw CSS. See the [Style command](docs/cli/style.md). ## Documentation **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) -- [Monorepo Support](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/monorepo.md) -- [Output Schema](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/schema.md) -- [UIF Contracts](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/uif_contracts.md) +- [Usage Guide](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/guides/usage.md) +- [Monorepo Support](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/guides/monorepo.md) +- [Output Schema](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/reference/schema.md) +- [UIF Contracts](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/reference/uif-contracts.md) - [Watch Mode](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/cli/watch.md) -- [Troubleshooting](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/usage.md#troubleshooting) +- [Troubleshooting](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/guides/usage.md#troubleshooting) ## Known Limitations 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. +📋 **See [docs/reference/limitations.md](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/reference/limitations.md)** for the full list. + +## Benchmarks + +You can compare bundle token costs across modes on your repo with `stamp context --compare-modes` (see [compare modes](https://github.com/LogicStamp/logicstamp-context/blob/main/docs/cli/compare-modes.md)). + +**Formal benchmarks** are on the [roadmap](https://github.com/LogicStamp/logicstamp-context/blob/main/ROADMAP.md#performance--optimization): +- CLI/runtime baselines +- LLM evaluations (with vs without LogicStamp context) ## Requirements -- Node.js >= 20 -- TypeScript codebase (React, Next.js, Vue (TS/TSX), Express, or NestJS) +- **Node.js** >= 20 +- **TypeScript codebase** - `.ts` / `.tsx` only (JavaScript is not yet analyzed). Frameworks, UI libraries, and limits: **[Framework support](#framework-support)**. ## Need Help? @@ -457,4 +410,4 @@ Issues and PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. This project follows a [Code of Conduct](CODE_OF_CONDUCT.md). -**Links:** [Website](https://logicstamp.dev) · [GitHub](https://github.com/LogicStamp/logicstamp-context) · [MCP Server](https://github.com/LogicStamp/logicstamp-mcp) · [Changelog](https://github.com/LogicStamp/logicstamp-context/blob/main/CHANGELOG.md) +**Links:** [Website](https://logicstamp.dev) · [GitHub](https://github.com/LogicStamp/logicstamp-context) · [MCP Server](https://github.com/LogicStamp/logicstamp-mcp) · [Changelog](https://github.com/LogicStamp/logicstamp-context/blob/main/CHANGELOG.md) \ No newline at end of file diff --git a/docs/context/ROADMAP.md b/docs/context/ROADMAP.md index 24eb11f..ac20464 100644 --- a/docs/context/ROADMAP.md +++ b/docs/context/ROADMAP.md @@ -1,693 +1,170 @@ -# LogicStamp Context Roadmap +# Roadmap -This roadmap outlines the planned features, improvements, and known limitations for LogicStamp Context. It's organized into bug fixes, framework expansion, and future enhancements. +Planned features, improvements, and known limitations. See [CHANGELOG.md](CHANGELOG.md) for release notes. ## Current Status -**Current Version:** v0.8.0 (Beta) +**Version:** v0.8.5 (Beta) -For detailed release notes and completed features, see [CHANGELOG.md](CHANGELOG.md). - -Recent major milestones include: -- ✅ `--strict` flag for compare command (v0.8.0) - Shared violation detection, exit code 1 on breaking changes -- ✅ Clean command removes TOON format files (v0.8.0) - Aligns with gitignore and TOON support -- ✅ Git baseline comparison (v0.7.2) - Compare against any git ref with `--baseline git:` -- ✅ Full contract comparison (v0.7.2) - State, variables, API signatures, prop/emit type changes -- ✅ Strict watch mode enhancements (v0.7.1) - Session status tracking, automatic watch enablement, enhanced summaries -- ✅ Developer experience improvements (v0.7.1) - Normalized path display, `--verbose` flag, watch mode file organization -- ✅ Lean style mode default (v0.7.0) -- ✅ Runtime schema validation and security hardening (v0.6.0) -- ✅ Strict watch mode for breaking change detection (v0.5.0) -- ✅ Watch mode with incremental rebuilds (v0.4.1) -- ✅ Backend framework support (Express.js, NestJS) (v0.4.0) -- ✅ Complete CSS-in-JS library support (v0.5.1) +Recent milestones: +- **Watch lock, file lock, secrets, compare fixes (v0.8.5)** - Watch: synchronous `isRegenerating` flag and queued change processing instead of a promise-based lock race. File lock: exclusive write helper with cleanup on failed write/close; Windows PID liveness via `tasklist` (with safe fallbacks) instead of `process.kill(pid, 0)`. Secret scanner: case-insensitive AWS/GitHub/PEM patterns. skip invalid match indices before snippets. Compare: `exportKind` treats `exports.named` as named only when it is a non-empty array +- **CLI packaging, paths, and token summary (v0.8.4)** - `logicstamp-context` registered as npm bin (fixes `npx logicstamp-context`). centralized `normalizeEntryId` / `toForwardSlashes` across CLI, watch, pack loader, and AST; `stamp context` summary shows the current mode’s exact token count vs raw source with savings % (use `--compare-modes` for full breakdown). tag-based npm publish via GitHub Actions and updated contributing/release docs +- **Secret scanner & watch reliability (v0.8.3)** - Long-line skip and regex optimizations in secret detection. watch logging, full rebuild fallback after incremental errors, async/error hardening +- **Documentation layout, watch perf, path boundaries (v0.8.2)** - Core docs under `docs/guides/` and `docs/reference/` with link updates; style/framework docs aligned with CLI; watch mode avoids `Array.from` on the contract map (direct `Map` iteration per change); centralized `isPathWithinRoot` for pack loader and hash-lock +- **CLI argument validation and robustness fixes (v0.8.1)** - Numeric arg validation for `--depth`/`--max-nodes`, safe compare normalization, token savings bounds +- **`--strict` flag for compare (v0.8.0)** - Exit code 1 on breaking changes +- **Git baseline comparison (v0.7.2)** - `--baseline git:` for drift detection +- **Full contract comparison (v0.7.2)** - State, variables, API signatures, prop/emit types +- **Strict watch enhancements (v0.7.1)** - Session tracking, `--strict-watch`, `--verbose` +- **Watch mode (v0.4.1)** - Incremental rebuilds, change detection +- **Backend support (v0.4.0)** - Express.js, NestJS --- -## Bug Fixes & Accuracy Improvements - -These items address core accuracy and completeness issues that impact the reliability of generated context files. +## Bug Fixes & Accuracy ### High Priority -#### 1. Emit Detection Accuracy -**Status:** ✅ **Fixed in v0.3.7** - -Emit detection now correctly distinguishes between internal handlers and component public API emits. Only handlers that are part of the component's Props interface/type are included in the `emits` object. - -**What Works:** -- ✅ Only extracts event handlers that exist in Props interfaces/types -- ✅ Filters out internal handlers (e.g., `onClick={() => setMenuOpen(!menuOpen)}`) -- ✅ Filters out inline handlers that are not props -- ✅ Uses prop type signatures when available for accurate event signatures -- ✅ Falls back to AST-based arrow function parsing only when prop signature is unavailable -- ✅ Uses `hasOwnProperty` check to avoid inherited prototype properties -- ✅ Always includes prop-based handlers even if no initializer or signature available (uses default) - -**Impact:** Internal handlers are no longer incorrectly listed as emits, making it easier for AI assistants to understand what events a component actually exposes. - -**Related:** See [docs/limitations.md](docs/limitations.md#fixedresolved-features) for detailed information. - ---- - -#### 2. Dynamic Class Parsing -**Status:** ✅ Phase 1 Complete (v0.3.9), 🟡 Phase 2 Planned - -Resolve variable-based classes within template literals. Phase 1 is complete, handling same-file variable resolution. - -**Current Behavior:** -- ✅ Extracts static Tailwind classes -- ✅ Extracts static segments from template literals -- ✅ Phase 1: Resolves const/let variables, object properties, and conditional expressions -- ❌ Phase 2: Does not resolve object lookups with variables, cross-file references, or function calls - -**Phase 1 Implementation (v0.3.9 - ✅ Complete):** -- ✅ Resolve const/let declarations with string literals: `const base = 'px-4 py-2'` → extracts classes from variable -- ✅ Resolve object property access: `variants.primary` → extracts classes from object property value -- ✅ Handle conditional expressions in template literals: `${isActive ? 'bg-blue-500' : 'bg-gray-500'}` → extracts both branches -- **Coverage**: ~70-80% of common dynamic class patterns - -**Phase 2 Implementation (Future Release):** -- Resolve object lookups with variables: `variants[variant]` → requires resolving index variable first -- Cross-file references: `import { baseClasses } from './styles'` → requires import resolution and cross-file analysis -- Function calls returning class strings: `getClasses('primary')` → requires function body analysis -- **Coverage**: Additional ~15-20% of edge cases -- **Estimated Effort**: 8+ hours - -**Impact:** Dynamic class construction from variables results in incomplete style metadata. Phase 1 addresses the most common patterns, Phase 2 will handle advanced edge cases. - -**Related:** See [docs/limitations.md](docs/limitations.md#dynamic-class-parsing) for detailed code evidence and implementation phases. - ---- +| Item | Status | Notes | +|------|--------|-------| +| **Emit Detection** | ✅ v0.3.7 | Only extracts prop-based handlers. See [limitations.md](docs/reference/limitations.md#fixed--resolved) | +| **Dynamic Class Parsing** | ✅ Phase 1 (v0.3.9), 🟡 Phase 2 planned | ~70-80% coverage. Phase 2: object lookups, cross-file refs. See [limitations.md](docs/reference/limitations.md#dynamic-class-parsing) | ### Medium Priority -#### 3. CSS-in-JS Support Completeness -**Status:** ✅ **Complete in v0.5.1** - -Complete support for all major CSS-in-JS libraries. - -**Currently Supported:** -- ✅ styled-components -- ✅ Emotion (@emotion/styled) -- ✅ Material UI (@mui/material) -- ✅ ShadCN/UI -- ✅ Radix UI -- ✅ Framer Motion -- ✅ Styled JSX -- ✅ Chakra UI ✅ **v0.5.1** -- ✅ Ant Design ✅ **v0.5.1** - -**Impact:** All major CSS-in-JS libraries are now supported. Complete coverage for popular component libraries. - ---- - -#### 4. Enhanced Third-Party Component Info -**Status:** 🟡 Phase 1 Complete, Phase 2 Pending - -Include package names, versions, and prop types for third-party components. - -**Current Behavior:** -- ✅ Basic "missing" info for unresolved dependencies -- ✅ Package names extracted from import statements (Phase 1) -- ✅ Version info from `package.json` (Phase 1) -- ❌ No prop type information (Phase 2) - -**Phase 1 Implementation (Complete):** -- ✅ Extract package names from import statements (handles scoped packages, subpath imports) -- ✅ Include version info from `package.json` (checks dependencies, devDependencies, peerDependencies) -- ✅ Caching for efficient package.json reads -- ✅ Graceful handling of missing package.json or packages - -**Phase 2 Implementation (Planned):** -- Extract prop types from TypeScript declaration files (`.d.ts`) in `node_modules` -- Handle different package structures and re-exports -- Support generic types and type aliases -- Fallback gracefully when type definitions are missing or incomplete - -**Impact:** Phase 1 provides immediate value with package names and versions. Phase 2 will add prop type information for better understanding of external component APIs. - ---- - -#### 5. TypeScript Type Extraction -**Status:** 🟡 Partially Complete - -Capture full type definitions including generics and complex unions/intersections. - -**Currently Supported:** -- ✅ Basic types (`string`, `number`, `boolean`) -- ✅ Literal unions (`"primary" | "secondary"`) -- ✅ Function types (`() => void`) - -**Missing:** -- ❌ Generics (e.g., `ListProps`) -- ❌ Complex unions/intersections (e.g., `A & B`, `A | B | C` where not string literals) -- ❌ Generic type parameters - -**Impact:** Limited type information for complex types in contracts. - -**Related:** See [docs/limitations.md](docs/limitations.md#typescript-types-incomplete) for detailed code evidence. - ---- - -#### 6. Project-Level Insights -**Status:** 🔴 Not Started - -Add cross-folder relationships and project-wide statistics to `context_main.json`. - -**Current Behavior:** -- ✅ Folder index with token estimates -- ✅ Component lists per folder -- ❌ No cross-folder relationships -- ❌ No project-wide statistics - -**Planned Implementation:** -- Cross-folder dependency analysis -- Project-wide component counts -- Aggregate style metadata statistics -- Architecture pattern detection - -**Impact:** Limited project-level insights in main index file. - ---- +| Item | Status | Notes | +|------|--------|-------| +| **CSS-in-JS** | ✅ v0.5.1 | All major libs: styled-components, Emotion, MUI, ShadCN, Radix, Framer, Chakra, Ant Design | +| **Third-Party Info** | 🟡 Phase 1 done | Package names + versions. Phase 2: prop types from `.d.ts` | +| **TypeScript Types** | 🟡 Partial | Missing: generics, complex unions/intersections. See [limitations.md](docs/reference/limitations.md#typescript-types) | +| **Project-Level Insights** | 🔴 Not started | Cross-folder relationships, project-wide stats in `context_main.json` | ### Low Priority -#### 7. Test File Analysis -**Status:** 🔴 Not Started - -Extract test structure, test cases, and testing patterns. - -**Current Behavior:** -- ✅ Test files explicitly excluded from context compilation -- ❌ No test analysis at all - -**Note:** This is intentional by design - test files are excluded to keep context bundles focused on production code. - -**Planned Implementation (if requested):** -- Optional flag to include test files -- Test structure extraction -- Test case and utility detection -- Testing strategy patterns - -**Impact:** No test understanding in context files (by design). - ---- - -#### 8. Comment Extraction -**Status:** 🟡 Partial - -Include regular comments (not just JSDoc). - -**Currently Supported:** -- ✅ JSDoc comments (in header mode) - -**Missing:** -- ❌ Regular comments (`//`, `/* */`) -- ❌ TODO notes - -**Impact:** Loses some documentation context from comments. - ---- - -#### 9. Runtime Behavior Hints -**Status:** 🔴 Not Started - -Add static analysis hints about runtime behavior. - -**Note:** This is expected limitation for static analysis tools - we can't execute code. - -**Potential Implementation:** -- Side effect detection -- State mutation patterns -- Effect dependency analysis - -**Impact:** No runtime insights (expected for static analysis). +| Item | Status | Notes | +|------|--------|-------| +| **Test File Analysis** | 🔴 Not started | Excluded by design. Optional flag if requested. | +| **Comment Extraction** | 🟡 Partial | JSDoc only. Missing: `//`, `/* */`, TODOs | +| **Runtime Behavior Hints** | 🔴 Not started | Expected limitation (static analysis) | --- ## Framework Expansion -These items expand LogicStamp Context to support additional languages, frameworks, and development workflows. - ### Near-Term -#### 1. Backend Framework Support -**Status:** ✅ **Complete in v0.4.0** - -Backend framework support has been fully implemented! LogicStamp Context now extracts API routes, HTTP methods, request/response types, and framework-specific metadata for Node.js backend frameworks. - -**What Works (v0.4.0):** -- ✅ Framework detection (Express.js, NestJS) -- ✅ Route path extraction (`/api/users`, `/users/:id`) -- ✅ HTTP method detection (GET, POST, PUT, DELETE, PATCH, ALL) -- ✅ Framework-specific metadata (Express routes, NestJS controllers) -- ✅ API signature extraction (request/response types, parameters) -- ✅ Route parameter detection (e.g., `/users/:id` → `params: ['id']`) -- ✅ Controller class detection and base path extraction (NestJS) -- ✅ Language-specific metadata (decorators, annotations, class names) -- ✅ New contract kind: `node:api` for backend API routes/handlers - -**Supported Frameworks:** -- **Express.js** - Route extraction from `app.get()`, `router.post()`, etc. -- **NestJS** - Controller extraction with decorators (`@Controller`, `@Get`, `@Post`, etc.) - -**Future Frameworks:** -- Fastify, Koa, Hapi (Phase 2+) - -**Impact:** AI assistants can now understand backend API structure, endpoints, and request/response contracts. Backend files are automatically detected and skip frontend extraction, optimizing performance and accuracy. - ---- - -#### 2. JavaScript & JSX Support -**Status:** 🔴 Not Started - -Add support for JavaScript (`.js`) and JSX (`.jsx`) files in addition to TypeScript. - -**Current Behavior:** -- ✅ Only TypeScript files (`.ts`, `.tsx`) are analyzed -- ❌ JavaScript files (`.js`, `.jsx`) are ignored - -**Planned Implementation:** -- Extend AST parser to handle JavaScript syntax -- Support JSDoc type annotations for type inference -- Handle JavaScript-specific patterns (CommonJS, ES modules) -- Maintain same contract structure for JS/JSX files - -**Impact:** Enables LogicStamp Context to work with JavaScript codebases that haven't migrated to TypeScript yet. - -**Priority:** High - ---- - -#### 3. Watch Mode -**Status:** ✅ **Complete (v0.4.1)** - Enhanced in v0.7.1 - -Automatic context regeneration when source files change. - -**What Works (v0.4.1):** -- `stamp context --watch` command -- File system watcher for `.ts`, `.tsx` files (and `.css`, `.scss` with `--include-style`) -- Incremental updates (only regenerates affected bundles) -- Debouncing (500ms) to batch multiple file changes -- Change detection showing what changed (props, hooks, state, events, components, functions) -- Debug mode (`--debug`) showing hash changes -- Status file (`.logicstamp/context_watch-status.json`) for tooling integration (always enabled) -- Log file (`--log-file`) for structured change logs (`.logicstamp/context_watch-mode-logs.json`) - opt-in for change notifications -- `watch-fast` profile for lighter style extraction - -**Enhancements (v0.7.1):** -- ✅ Session status tracking for strict watch mode (cumulative errors/warnings, resolved count, active violations) -- ✅ `--strict-watch` automatically enables watch mode (simplified usage: `stamp context --strict-watch`) -- ✅ Enhanced session summary with contextual emoji and proper pluralization -- ✅ Normalized path display across all commands (relative paths when possible) -- ✅ `--verbose` flag for detailed bundle output (per-file checkmarks) -- ✅ Improved watch mode file organization and module structure - -**Impact:** Improves developer experience by automatically keeping context files in sync with code changes. Enhanced strict watch mode provides better visibility into breaking changes during development. - -**Priority:** ~~Medium~~ Complete - ---- +| Item | Status | Notes | +|------|--------|-------| +| **Backend Support** | ✅ v0.4.0 | Express, NestJS. Routes, HTTP methods, API signatures. Future: Fastify, Koa, Hapi. | +| **JavaScript & JSX** | 🔴 Not started | Add `.js`/`.jsx`. JSDoc type inference. **High priority** | +| **Watch Mode** | ✅ v0.4.1 | Incremental rebuilds, debouncing, status file, `--strict-watch`. See [watch.md](docs/cli/watch.md) | ### Future -#### 4. Complete Vue.js Support -**Status:** 🟡 Partially Complete - -Add full support for Vue Single File Components (`.vue` files). - -**Current Behavior:** -- ✅ Vue 3 Composition API support for `.ts`/`.tsx` files -- ✅ Vue components and composables detection -- ✅ Props and emits extraction from JSX/TSX -- ❌ Vue Single File Components (`.vue` files) not supported - -**Planned Implementation:** -- Parse `.vue` SFC files (template, script, style blocks) -- Extract template syntax (directives, bindings, slots) -- Extract script setup and composition API usage -- Extract scoped styles and CSS modules from style blocks -- Support both Options API and Composition API - -**Impact:** Enables full Vue.js codebase analysis, including projects using `.vue` SFC files. - -**Priority:** High - ---- - -#### 5. Svelte Support -**Status:** 🔴 Not Started - -Add support for Svelte components (`.svelte` files). - -**Planned Implementation:** -- Parse Svelte component files -- Extract props, reactive statements, and stores -- Extract template syntax and bindings -- Extract scoped styles -- Support SvelteKit routing and layouts - -**Impact:** Expands framework support to include Svelte-based projects. - -**Priority:** Medium - ---- - -#### 6. Python Support -**Status:** 🔴 Planned - -Add support for Python codebases (experimental). - -**Prerequisites:** -- Conditional schema by language (in development) -- JS/JSX support (for multi-language feedback) - -**Planned Implementation:** -- Parse Python AST using `ast` module -- Extract function signatures, classes, and modules -- Extract type hints and docstrings -- Support popular frameworks (FastAPI, Django, Flask) -- Generate Python-specific contracts with `python:function` or `python:class` kind -- Use `languageSpecific.decorators` for framework decorators (e.g., `@app.get`, `@app.post`) - -**Impact:** Expands LogicStamp Context beyond JavaScript/TypeScript ecosystems. - -**Priority:** Medium (Depends on conditional schema stabilization) - ---- - -#### 7. Java Support -**Status:** 🔴 Planned - -Add support for Java codebases (experimental). - -**Prerequisites:** -- Conditional schema by language (in development) -- JS/JSX support (for multi-language feedback) - -**Planned Implementation:** -- Parse Java source files -- Extract class definitions, methods, and interfaces -- Extract annotations and Javadoc -- Support Spring Boot and other popular frameworks -- Generate Java-specific contracts with `java:class` kind -- Use `languageSpecific.annotations` for framework annotations (e.g., `@RestController`, `@GetMapping`) -- Use `languageSpecific.classes` and `languageSpecific.methods` for class/method extraction - -**Impact:** Expands LogicStamp Context to enterprise Java codebases. - -**Priority:** Medium (Depends on conditional schema stabilization) +| Item | Status | Notes | +|------|--------|-------| +| **Vue SFC** | 🟡 Partial | Vue 3 TS/TSX done. Missing: `.vue` file parsing. **High** | +| **Svelte** | 🔴 Not started | `.svelte` files. **Medium** | +| **Python** | 🔴 Planned | Depends on conditional schema. FastAPI, Django, Flask. **Medium** | +| **Java** | 🔴 Planned | Depends on conditional schema. Spring Boot. **Medium** | --- ## Future Enhancements -These are longer-term features and improvements planned for future releases. - ### Comparison & Drift Detection -#### Git Baseline for Compare -**Status:** ✅ **Complete in v0.7.2** - -Git-based baseline support for context comparison, enabling meaningful drift detection against known reference points. - -**What Works (v0.7.2):** -- ✅ `--baseline git:` option to compare against any local git ref -- ✅ Uses git worktrees for clean isolation during comparison -- ✅ Generates context for both baseline and current code, then compares -- ✅ Automatic cleanup of worktrees and temp directories -- ✅ Works with branches, tags, and commit hashes - -**Current Behavior:** -- ✅ Watch mode compares against previous state (rolling baseline) -- ✅ `stamp context compare` compares disk files vs freshly generated -- ✅ `stamp context compare --baseline git:main` compares against git ref - -**How It Works:** -Context files are gitignored by design - they don't exist in git history. Git baseline generates context at two points and compares them: - -``` -stamp context compare --baseline git:main - -1. Validate git repo and resolve ref -2. Create git worktree at ref → temp/worktree/ -3. Generate context for baseline → .logicstamp/compare/baseline/ -4. Generate context for current working tree → .logicstamp/compare/current/ -5. Compare baseline vs current -6. Report drift -7. Cleanup worktree and temp directories -``` - -**Implementation Details:** -- Uses `git worktree` for clean isolation (avoids disrupting working directory) -- Context stored in `.logicstamp/compare/` (already gitignored) -- Worktrees stored in system temp directory -- Automatic cleanup on success or failure - -**Hash Behavior in Git Baseline Comparisons:** +**Git Baseline** ✅ v0.7.2 — Compare against any git ref: `stamp context compare --baseline git:main`. Uses worktrees; generates context at baseline + current, then compares. Hash-only changes filtered in git mode (TS resolution differences). Works with branches, tags, commits. Limitations: local refs only, no caching. See [compare.md](docs/cli/compare.md) for hash behavior, use cases, and full details. -Semantic hashes track meaningful structural and logical changes to components (props, emits, state, imports, hooks, functions, components). In git baseline mode, hash behavior differs from regular comparisons: +**Enhanced Compare** ✅ v0.7.2 — Full contract comparison: state, variables, API signatures, prop/emit type changes. Matches watch mode behavior. -- **Hash-only changes are filtered**: When only the semantic hash differs (with no changes to imports, hooks, functions, components, props, emits, or exports), the hash change is ignored to prevent false positives -- **Hash changes with other changes are reported**: When the hash differs AND there are other structural changes, the hash is still reported to provide context -- **Why filter hash-only?** TypeScript project resolution can produce slightly different AST structures between worktree and working directory contexts (different absolute paths, module resolution contexts, or TypeScript compiler state) even for functionally identical code. Filtering hash-only changes ensures deterministic structural comparison while preserving hash information when there are real changes. +**Compare export classification** ✅ v0.8.5 — `exportKind` classifies `named` exports only when `exports.named` is a non-empty array; malformed shapes map to `none` instead of a false `named` match. -**Hash Behavior in Other Comparison Modes:** +### Schema & Architecture -- **Regular comparison modes** (single-file, multi-file, auto-mode): All hash changes are reported, as both sides are generated from the same environment context -- **Watch mode**: Hashes are used for incremental rebuild detection and bundle hashing +**Conditional Schema by Language** 🔴 Planned — Make `UIFContract` schema conditional on `kind` (e.g., `style` only for frontend, `apiSignature` required for backend). Prerequisite for Python/Java. Depends on JS/JSX support first. **High priority**. -**Why Hashes Are Still Needed:** +### Performance & Optimization -Even though hash-only changes are filtered in git baseline mode, semantic hashes are still computed and used because: -- Context for real changes: When there ARE other changes, the hash provides context about what changed -- Regular comparisons: In non-git-baseline comparisons, hashes are always reported -- Watch mode: Hashes drive incremental rebuild detection -- Bundle hashing: Bundle-level hashes depend on component semantic hashes -- Contract integrity: Hashes are part of the contract structure +- **Context summary token display** ✅ v0.8.4 — Summary uses the current mode’s measured token count only (no blended heuristics), compares to raw source with savings %, and points to [`--compare-modes`](docs/cli/compare-modes.md) for per-mode detail. -The filtering only suppresses hash-only noise in git baseline mode—hashes still provide value when there are real structural changes. +- **Formal benchmarks** 🔴 Planned — **Today:** [`stamp context --compare-modes`](docs/cli/compare-modes.md) already compares bundle token costs across modes on **your** repo (optional `context_compare_modes.json` with `--stats`). **Planned** work adds **published** baselines and methodology: fixed reference corpora, reproducible tables, CI or scheduled runs, and assistant-side task evals. Two tracks where possible: + - **Tool / runtime** — Cold/warm `stamp context`, watch incremental cost, memory, scaling with repo size. + - **LLM / workflow (with vs without LogicStamp)** — The main question: **do models do better when given LogicStamp bundles than when they only see raw source (or minimal repo context)?** Planned evals hold tasks and prompts fixed, vary only the context channel (bundles vs baseline), and report metrics such as task success, prop/API factual accuracy, tokens to a correct answer, and hallucination rate. Complements per-repo token comparison from `--compare-modes`; extends the docs with **published** numbers others can reproduce on reference corpora. -**Use Cases:** -- PR review: `stamp context compare --baseline git:main` -- CI integration: `stamp context compare --baseline git:origin/main` -- Release validation: `stamp context compare --baseline git:v1.0.0` -- Pre-commit: `stamp context compare --baseline git:HEAD` +- **Incremental watch optimization** ✅ v0.8.2 + - Avoid unnecessary array allocations during incremental rebuilds + - Direct `Map` iteration for contract lookups reduces per-change overhead + - Improves performance for large codebases in watch mode -**Limitations:** -- Only works with local refs (must `git fetch` first for remote branches) -- No caching yet (regenerates on every run) +### Security & Reliability -**Future Enhancements:** -- ~~`--fail-on-breaking` flag~~ → Implemented as `--strict` in v0.8.0 -- Baseline caching when ref hasn't changed (optimization) -- Remote ref auto-fetch option +- **Path traversal protection hardening** ✅ v0.8.2 + - Centralized `isPathWithinRoot` for consistent project boundary enforcement + - Prevents file access outside project root in pack loader and hash-lock flows + - Aligns validation across `loadContract`, `readSourceCode`, and related fs operations -**Impact:** Enables meaningful drift detection against stable reference points, making CI integration straightforward. +- **Path normalization consistency** ✅ v0.8.4 + - Standardizes `normalizeEntryId` and `toForwardSlashes` across CLI, watch mode, pack loader, and AST handling + - `displayPath()` delegates to `toForwardSlashes()` (bundle diff still uses `normalizeName()` where appropriate) ---- +- **Secret detection performance & safety** ✅ v0.8.3 + - Skips very long lines (1000+ characters) to avoid pathological regex cost + - Fewer per-line `RegExp` allocations; simplified overlapping patterns (`api[_-]?key`, etc.) -#### Enhanced Compare Command -**Status:** ✅ **Complete in v0.7.2** +- **Secret detection consistency** ✅ v0.8.5 + - Case-insensitive matching for AWS-style keys, GitHub token prefixes, and PEM private-key headers (aligned with other patterns) + - Skip recording a match when `match.index` or full match text is invalid before building snippets -Full contract comparison support for all contract fields, aligning compare command behavior with watch mode. +- **Watch mode error handling** ✅ v0.8.3 + - Clearer logging for context load/read failures (respects `--quiet`) + - Full rebuild fallback after incremental errors to restore consistent state + - Hardened async/error paths to avoid masked failures and unhandled rejections -**What Works (v0.7.2):** -- ✅ State comparison - Detects added/removed/changed state variables with type information -- ✅ Variables comparison - Detects added/removed module-level variables -- ✅ API signature comparison - Detects changes to backend API parameters, return types, request/response types -- ✅ Prop/emit type change detection - Detects when prop/emit types change (not just added/removed) -- ✅ New delta types: `state`, `variables`, `apiSignature`, `propsChanged`, `emitsChanged` +- **Watch mode regeneration lock** ✅ v0.8.5 + - Synchronous `isRegenerating` flag replaces promise-based lock to avoid races when multiple callers process the same file changes + - `while` loop drains changes that arrive during regeneration -**Prop/Emit Type Changes:** -- Displays type changes as: `~ propName: "string" → "number"` -- Only detected in direct file comparisons (not in git baseline mode due to TypeScript resolution differences) -- Aligns with watch mode behavior +- **File lock robustness** ✅ v0.8.5 + - `writeLockFileExclusive()` removes empty or partial `.lock` files if write or close fails after exclusive create + - Windows: use `tasklist` to detect whether the lock PID still exists; treat current process as alive; indeterminate `tasklist` output does not drop valid locks (fixes lost updates under heavy concurrent waiters, e.g. `appendWatchLog`) -**Impact:** Compare command now provides comprehensive drift detection across all contract fields, matching watch mode capabilities for consistent behavior. +- ✅ Incremental bundle caching (watch mode) +- **Style verbosity reduction** 🔴 — Less verbose style for nested components with `depth=2`; planned `--full-style` flag for full extraction (distinct from `--style-mode full`). ~30-40% token reduction. +- **Output size optimization** — Further token reduction ---- +### Configuration & DX -### Schema & Architecture - -#### Conditional Schema by Language -**Status:** 🔴 Planned - -Make the UIFContract schema conditional based on the `kind` field, ensuring that language-specific fields are only present when relevant and properly validated. - -**Current Behavior:** -- ✅ Flat schema with all fields optional or empty by default -- ✅ Works for all languages (React, Vue, Backend) but allows invalid combinations -- ⚠️ No validation that `style` shouldn't exist on backend contracts -- ⚠️ No validation that `hooks` should be empty for backend contracts -- ⚠️ No validation that `apiSignature` is required for backend contracts - -**Why This Matters:** -The current schema is language-agnostic but allows invalid field combinations. For example, a `node:api` contract could theoretically have `style` metadata or `hooks`, which doesn't make sense. While the tool doesn't generate these invalid combinations, the schema doesn't enforce correctness. - -**Planned Implementation:** - -**1. TypeScript Discriminated Unions:** -```typescript -// React-specific contract -type ReactUIFContract = BaseUIFContract & { - kind: 'react:component' | 'react:hook'; - composition: { - hooks: string[]; // Required for React - components: string[]; // Required for React - // ... - }; - interface: { - props: Record; // Required for React - emits: Record; // Required for React - // ... - }; - style?: StyleMetadata; // Only for frontend - nextjs?: NextJSMetadata; // Only for Next.js -}; - -// Backend API contract -type BackendUIFContract = BaseUIFContract & { - kind: 'node:api' | 'python:function' | 'java:class'; - composition: { - hooks: []; // Must be empty for backend - components: []; // Must be empty for backend - languageSpecific?: LanguageSpecificVersion; // Required for Python/Java - // ... - }; - interface: { - props: {}; // Must be empty for backend - emits: {}; // Must be empty for backend - apiSignature: ApiSignature; // Required for backend - }; - // No style, no nextjs -}; - -// Union type -export type UIFContract = ReactUIFContract | BackendUIFContract | VueUIFContract | ...; -``` - -**2. JSON Schema Conditional Validation:** -- Use `if/then/else` or `oneOf` patterns based on `kind` pattern matching -- Enforce that `style` only exists for frontend contracts (`react:*`, `vue:*`) -- Enforce that `nextjs` only exists for React contracts -- Enforce that `apiSignature` is required for backend contracts (`node:*`, `python:*`, `java:*`) -- Enforce that `hooks` and `components` are empty arrays for backend contracts -- Enforce that `props` and `emits` are empty objects for backend contracts - -**3. Runtime Validation:** -- Update validation logic to check field combinations based on `kind` -- Provide clear error messages for invalid combinations -- Add warnings during contract building for invalid field usage - -**4. Backward Compatibility:** -- Provide migration guide for existing contracts -- Support reading old flat schema format (with warnings) -- Auto-migrate contracts when possible (add defaults, remove invalid fields) - -**Rationale:** -- **Breaking change** - Schema structure changes require migration, better to do in a dedicated minor version series -- **Prerequisite for Python/Java** - Conditional schema must be in place before adding Python and Java support -- **Better timing** - After gathering feedback from multi-language usage (JS/JSX support) -- **Iterative development** - Allows for multiple releases to refine and stabilize the schema -- **Migration support** - Proper migration tooling and documentation across releases - -**Dependencies:** -- Must be completed before Python/Java support -- JS/JSX support should be completed first to gather multi-language feedback - -**Implementation Phases:** -- Conditional schema development, testing, and refinement with migration support -- Schema stabilization and finalization -- Python/Java support added once schema is stable - -**Impact:** -- **Type Safety:** Better TypeScript type checking prevents invalid contracts at compile time -- **Validation:** JSON Schema validation catches invalid field combinations -- **Clarity:** Clearer contract structure makes it obvious what fields are valid for each language -- **Future-proofing:** Easier to add new languages with their own field requirements -- **Enables Python/Java:** Required foundation for adding Python and Java support - -**Priority:** High (Prerequisite for Python/Java support) - -**Note:** Conditional schema will go through a development and stabilization phase. Python and Java support will be added once the schema is stable. - ---- - -### Performance & Optimization -- ✅ **Incremental bundle caching** - Only regenerate changed bundles (implemented in watch mode v0.4.1) -- **Output size optimization** - Further reduce token counts while maintaining accuracy -- **Style metadata verbosity reduction** - Reduce style extraction verbosity for nested components (depth >= 1) when using `depth=2`: - - **Default behavior (less verbose)**: For nested components, reduce Tailwind classes (15 → 5 per category), component library lists (20-30 → 5-10), remove SCSS/CSS details (selectors/properties), simplify layout/visual metadata - - **Full extraction preserved**: Entry components (depth 0) always get full extraction; use `--full-style` flag to restore current behavior (full extraction for all components) - - **Impact**: ~30-40% reduction in style metadata tokens with depth=2, while maintaining full detail for entry components - - **Backward compatible**: Existing context files remain valid; old behavior available via `--full-style` flag - - **Status**: 🔴 Planned - -### Configuration & Extensibility -- **Custom profile configuration and overrides** - User-defined profiles beyond preset options -- **Additional output formats** - More format options for different AI workflow patterns - -### Developer Experience -- ✅ **Normalized path display** (v0.7.1) - Consistent relative path formatting across all commands -- ✅ **Verbose output flag** (v0.7.1) - `--verbose` flag for detailed per-file bundle output -- ✅ **Watch mode improvements** (v0.7.1) - Enhanced strict watch session tracking and simplified usage -- **Integration examples** - Examples for popular AI assistants (Cursor, Claude Desktop, GitHub Copilot Chat) -- **Advanced debugging tools** - Better diagnostics and troubleshooting capabilities +- ✅ Normalized paths, `--verbose` (v0.7.1) +- **npm CLI entry (`npx`)** ✅ v0.8.4 — `package.json` `bin` maps `logicstamp-context` to the same CLI as `stamp`, so `npx logicstamp-context` works reliably. +- **Release & publish workflow** ✅ v0.8.4 — Tag-based npm publishing in GitHub Actions; contributing guidelines aligned with the new release process. +- **Custom profiles** — User-defined beyond presets +- **Integration examples** — Cursor, Claude, Copilot +- **Debugging tools** — Better diagnostics --- ## Known Limitations -For a complete list of current limitations with code evidence and detailed explanations, see [docs/limitations.md](docs/limitations.md). - -### Summary of Current Limitations +See [docs/reference/limitations.md](docs/reference/limitations.md) for full details with code evidence. -**Active Accuracy Issues:** -- 🟡 Dynamic class expressions partially resolved (Phase 1 complete in v0.3.9, Phase 2 planned for advanced patterns) +**Summary:** Dynamic classes Phase 1 done (~70-80%); TypeScript generics/complex unions missing; third-party prop types missing (names/versions done); no project-level insights; JSDoc only for comments; test files excluded by design. -**Active Coverage Gaps:** -- ❌ TypeScript types incomplete (generics, complex unions/intersections) -- ⚠️ Third-party component prop types missing (package names and versions included in v0.3.8) -- ❌ Project-level insights missing (cross-folder relationships, project-wide statistics) -- ⚠️ Comments only in header mode (JSDoc only) -- ⚠️ Test files excluded (by design) - -**Overall Assessment:** -- **~95%** - Component Contracts (Props, state, hooks detection) ✅ Hook parameters now included -- **~100%** - Imports Detection (Imports tracked correctly) -- **~90-95%** - Style Metadata (Static classes ~100%, dynamic classes Phase 1 complete ~70-80% of patterns, CSS-in-JS 9/9 major libraries supported ✅ v0.5.1) +**Coverage:** ~95% component contracts, ~100% imports, ~90-95% style metadata. --- ## Contributing -We welcome contributions! If you'd like to work on any of these roadmap items: - -1. Check [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines -2. Open an issue to discuss your approach -3. Submit a pull request with your implementation +1. See [CONTRIBUTING.md](CONTRIBUTING.md) +2. Open an issue to discuss +3. Submit a PR -**Priority Areas for Contributors:** - -**Bug Fixes:** -- Dynamic class parsing - Phase 1 complete (v0.3.9), Phase 2 planned for advanced patterns -- ✅ CSS-in-JS library support - Chakra UI and Ant Design support added (v0.5.1) -- Enhanced third-party component info (Phase 2) - Include prop types (package names and versions completed in v0.3.8) - -**Framework Expansion:** -- ✅ Backend framework support - Extract API routes, HTTP methods, and framework metadata (Express, NestJS) (v0.4.0) -- JavaScript & JSX support - Add `.js`/`.jsx` file analysis -- Complete Vue.js support - Add `.vue` SFC file parsing -- ✅ Watch mode - Automatic context regeneration on file changes (v0.4.1) +**Priority areas:** Dynamic class Phase 2, JS/JSX support, third-party prop types, Vue SFC parsing. --- ## Feedback -Have suggestions for the roadmap? We'd love to hear from you: - -- **Open an issue** → https://github.com/LogicStamp/logicstamp-context/issues -- **Join our roadmap** → https://logicstamp.dev/roadmap - +- **Issues:** https://github.com/LogicStamp/logicstamp-context/issues +- **Roadmap:** https://logicstamp.dev/roadmap diff --git a/docs/context/SCHEMA_VALIDATION.md b/docs/context/SCHEMA_VALIDATION.md index 3aff106..2f339c7 100644 --- a/docs/context/SCHEMA_VALIDATION.md +++ b/docs/context/SCHEMA_VALIDATION.md @@ -133,7 +133,7 @@ The schema completeness test runs as part of the test suite. To ensure schema st - **Deprecated fields**: Fields marked `@deprecated` in TypeScript (e.g., `entryPathAbs`, `entryPathRel`, `os`) may not be in the schema if they're no longer generated. This is intentional for backward compatibility - old files with these fields may still exist. -- **Conditional validation**: The schema doesn't currently validate language-specific field combinations (e.g., `style` shouldn't exist on `node:api` contracts). This is planned for v0.8.x (see ROADMAP.md). +- **Conditional validation**: The schema doesn't currently validate language-specific field combinations (e.g., `style` shouldn't exist on `node:api` contracts). This is planned for a future release (see [ROADMAP.md](../ROADMAP.md)). - **Style mode variants**: The schema supports both `lean` and `full` style modes. Lean mode uses count fields (e.g., `selectorCount`, `componentCount`), while full mode uses arrays (e.g., `selectors`, `components`). Both formats are valid and should be tested separately. diff --git a/docs/context/cli/compare-modes.md b/docs/context/cli/compare-modes.md index e9765b3..4062ba9 100644 --- a/docs/context/cli/compare-modes.md +++ b/docs/context/cli/compare-modes.md @@ -1,6 +1,6 @@ # Mode Comparison Guide -Compare token costs across all context compilation modes to choose the right one for your workflow. +Compare token costs across context modes. ```bash stamp context --compare-modes @@ -8,22 +8,22 @@ stamp context --compare-modes ## Overview -Four modes balance information vs token cost: +Four modes balance detail vs tokens: -- **none** - Contracts only (props, state, hooks, dependencies), no source code -- **header** - Contracts plus JSDoc headers and function signatures -- **header+style** - Header mode plus style metadata (Tailwind, SCSS, Material UI, animations, layout) -- **full** - Everything including complete source code - -The comparison shows token costs for all modes so you can see the tradeoffs. +- **none** - Contracts only (props, state, hooks, dependencies), no source +- **header** - Contracts plus JSDoc headers and signatures +- **header+style** - Header plus style metadata (Tailwind, SCSS, MUI, layout, motion) +- **full** - Contracts plus complete embedded source ## Output Format -The output shows three things: +**1. Token estimation** — Which tokenizers ran, or character fallback. + +**2. Comparison vs raw source** — See [baselines](#what-the-two-baselines-mean). Negative % means summed header bundles exceed one copy of all source files, but a **single** root’s bundle is often still far smaller than raw because the row totals **every** root, not the one bundle you attach in chat. -**1. Token estimation method** - Shows which tokenizers are being used, or if it's falling back to approximations +**3. Mode breakdown** — Each mode vs **full** (same bundle set): how much smaller than maximum. -**2. Comparison vs raw source** - Savings compared to including all source files directly: +Example tables: ``` Comparison: @@ -34,10 +34,6 @@ The output shows three things: Header+style | 170,466 | 184,864 | 38% ``` -Header mode saves ~70% by extracting contracts and signatures without implementation code. Header+style saves ~38% but adds visual context. Full mode actually costs more than raw source (~30% overhead) due to contract structure. - -**3. Mode breakdown** - All modes compared to the maximum (full): - ``` Mode breakdown: Mode | Tokens GPT-4o | Tokens Claude | Savings vs Full Context @@ -50,130 +46,73 @@ Header mode saves ~70% by extracting contracts and signatures without implementa ## Token Estimation -By default, the tool uses character-based approximations (~4 chars/token for GPT-4o, ~4.5 for Claude). These are usually within 10-15% of actual counts, which is fine for most cases. - -For accurate counts, LogicStamp includes `@dqbd/tiktoken` (GPT-4) and `@anthropic-ai/tokenizer` (Claude) as optional dependencies. npm installs them automatically when you install `logicstamp-context`. If that works, you get exact token counts. If it fails (normal for optional deps), it falls back to approximation. - -You only need to install tokenizers manually if: -- You need exact counts (not approximations) -- AND automatic installation failed +Defaults use ~4 chars/token (GPT-4o) and ~4.5 (Claude). Optional deps `@dqbd/tiktoken` and `@anthropic-ai/tokenizer` give exact counts when install succeeds. ```bash npm install @dqbd/tiktoken @anthropic-ai/tokenizer ``` -Accurate counts matter for production deployments, tight budgets, or comparing tools. For development, approximations are usually fine. +## What the two baselines mean -## Mode Selection Guide +**Raw source** — Every project `.ts` / `.tsx` (tests excluded), each file **once**, joined. No JSON bundles. + +**Header / header+style (first table)** — Tokens for **all root bundles**, formatted and concatenated. Anything imported by many roots is repeated; bundle JSON adds overhead. So the table can show header **above** raw on large multi-root graphs, even when **one** feature bundle is still cheap. In chat you usually send one bundle—that is **not** the same as this summed row. -**none** - Maximum compression (~18% of raw source) -- Contracts only, no code or style -- Good for: CI/CD validation, dependency analysis, architecture reviews -- Skip if: You need implementation details or visual context +**Tailwind + header+style** — Style extraction expands utilities into structured text, so that row often grows vs raw more than on SCSS-heavy repos (in addition to duplication above). -**header** - Balanced compression (~30% of raw source) *recommended default* -- Contracts + JSDoc headers + function signatures -- Good for: Most AI chat workflows, code review, understanding interfaces -- This is what most people need 90% of the time +## Mode Selection Guide -**header+style** - Visual context (~62% of raw source) -- Everything from header + style metadata (Tailwind, SCSS, animations, layout patterns) -- Good for: UI/UX discussions, design system work, frontend generation -- Adds ~13% token overhead vs header mode +**~N% vs raw** below = rough when summed header output beats one pass over all files ([above](#what-the-two-baselines-mean)). -**full** - Complete context (~130% of raw source) -- Everything including full source code -- Good for: Deep reviews, complex refactoring, bug investigation -- Note: Costs more than raw source due to contract structure overhead +**none** — ~18% of raw in typical cases. CI, graphs, no UI detail. +**header** — ~30% when totals beat raw. Default for most chat/review. +**header+style** — ~62% when totals beat raw; Tailwind pushes it up. UI and design-system work. +**full** — ~130% vs one file pass; contracts + full source. Deep refactors, bugs. ## Example Workflows -**Budget planning:** ```bash stamp context --compare-modes stamp context --include-code header --max-nodes 50 ``` -**Style cost analysis:** ```bash stamp context --compare-modes -stamp context style # only if budget allows -``` - -**Production optimization:** -```bash -stamp context --compare-modes | tee token-analysis.txt -stamp context --include-code none --profile ci-strict +stamp context style # if budget allows ``` -**Multi-repo comparison:** ```bash -for repo in api web mobile; do - echo "=== $repo ===" - cd $repo && stamp context --compare-modes --quiet && cd .. -done +stamp context --compare-modes --stats # writes context_compare_modes.json ``` -**MCP integration:** -```bash -stamp context --compare-modes --stats -# Creates context_compare_modes.json with structured data for MCP servers -``` - -## Understanding the Numbers - -**Savings vs Raw Source:** Shows how much you save compared to just concatenating all source files. Higher is better. Header mode typically saves ~70%, header+style saves ~38%. Full mode actually costs more (~30% overhead) due to contract structure. - -**Savings vs Full Context:** Shows efficiency compared to the maximum mode. Header saves ~77%, header+style saves ~52%. - -**GPT-4o vs Claude:** Token counts differ slightly (usually 5-10%) because each model tokenizes differently. Both estimates are shown so you can plan for either. - -**Accuracy:** Approximations are usually within 10-15% and fine for planning. Tokenizers give exact counts but require installation. - ## Common Questions -**Why are my numbers different from raw file sizes?** -Token counts ≠ character counts. Tokenizers split text into semantic units—common words are 1 token, rare words are multiple, code symbols vary, whitespace compresses. +**Why don’t tokens match file size?** Tokens ≠ bytes; tokenizers split code and prose unevenly. -**Should I always use accurate tokenizers?** -Use approximations for development/prototyping. Use tokenizers for production, tight budgets, or comparing tools. +**When are tokenizers worth it?** Tight budgets, production gates, comparing tools. Approximations are fine for day-to-day. -**How much overhead do contracts add?** -In `full` mode, contracts add ~30% overhead vs raw source due to JSON structure and metadata. The overhead is worth it for structured dependency graphs and better AI comprehension, but `header` mode avoids most of it while still giving you what you need. +**`full` overhead?** JSON + metadata on top of embedded source; `header` avoids most of that. -**Why do the savings percentages seem generous?** -"Savings vs raw source" compares against simple file concatenation. Header mode saves 70% because it extracts contracts and signatures without implementation code. Full mode actually costs more than raw source (~30% overhead) due to contract structure. The real win: header mode gives you 90% of what you need at 30% of the cost. +### Why can Header show more tokens than Raw source? -**Can I compare specific folders?** -Yes: -```bash -stamp context ./src/components --compare-modes -``` +[What the two baselines mean](#what-the-two-baselines-mean) — raw is one copy of each file; the header row is **every root bundle** summed. -**Does --compare-modes write files?** -No, it's analysis-only by default. It generates contracts in memory, computes estimates, and displays tables. Use `stamp context` (without the flag) to actually generate context files. +**Folder scope?** `stamp context ./src/components --compare-modes` -With `--stats`, it writes `context_compare_modes.json` for MCP integration: -```bash -stamp context --compare-modes --stats -``` +**Writes files?** No, unless `--stats` (JSON). Normal `stamp context` writes bundles. ## Performance -Takes 2-3x longer than normal generation because it regenerates contracts with and without style for accurate comparison. Uses in-memory processing (no disk writes). Typical execution: 5-15 seconds for medium projects (50-150 files). +~2–3× normal run; in-memory, no bundle files unless `--stats`. ## Related Commands -- [`stamp context`](context.md) - Generate context files -- [`stamp context style`](style.md) - Generate context with style metadata -- [`stamp context compare`](compare.md) - Compare context changes over time -- [`stamp context validate`](validate.md) - Validate schema compliance +- [`stamp context`](context.md) +- [`stamp context style`](style.md) +- [`stamp context compare`](compare.md) +- [`stamp context validate`](validate.md) ## Tips -- Run `--compare-modes` before committing to a mode -- Use approximations in dev, tokenizers in production -- Default to `header` mode—it covers most use cases -- Add `header+style` only when you need visual context -- Reserve `full` mode for deep implementation work -- Check costs regularly as your codebase grows +- Default **header**; add **header+style** only for UI-heavy prompts. +- Re-run as the repo grows. diff --git a/docs/context/cli/context.md b/docs/context/cli/context.md index 7403953..2043284 100644 --- a/docs/context/cli/context.md +++ b/docs/context/cli/context.md @@ -13,7 +13,7 @@ stamp context [path] [options] **Setup:** `stamp context` respects preferences saved in `.logicstamp/config.json` and never prompts. On first run (no config), it defaults to skipping both `.gitignore` and `LLM_CONTEXT.md` setup for CI-friendly behavior. Use [`stamp init`](init.md) to configure these options (non-interactive by default; use `--no-secure` for interactive mode). -**File Exclusion:** `stamp context` respects `.stampignore` and excludes those files from context compilation. You'll see how many files were excluded (unless using `--quiet`). Use `stamp ignore ` to add files to `.stampignore`. `.stampignore` is completely optional and independent of security scanning. See [stampignore.md](../stampignore.md) for details. +**File Exclusion:** `stamp context` respects `.stampignore` and excludes those files from context compilation. You'll see how many files were excluded (unless using `--quiet`). Use `stamp ignore ` to add files to `.stampignore`. `.stampignore` is completely optional and independent of security scanning. See [stampignore.md](../reference/stampignore.md) for details. **Secret Sanitization:** If a security report (`stamp_security_report.json`) exists, `stamp context` automatically replaces detected secrets with `"PRIVATE_DATA"` in the generated JSON files. **Your source code files are never modified** - only the generated context files contain sanitized values. See [security-scan.md](security-scan.md) for details. @@ -187,9 +187,9 @@ Example `.stampignore`: } ``` -`.stampignore` is completely optional and can be created manually. It's independent of security scanning. See [stampignore.md](../stampignore.md) for complete documentation. +`.stampignore` is completely optional and can be created manually. It's independent of security scanning. See [stampignore.md](../reference/stampignore.md) for complete documentation. -For complete documentation on `.stampignore` file format, see [stampignore.md](../stampignore.md). +For complete documentation on `.stampignore` file format, see [stampignore.md](../reference/stampignore.md). ## Secret Sanitization @@ -205,8 +205,8 @@ When generating context files, LogicStamp automatically sanitizes secrets if a s Source code: ```typescript -const apiKey = 'sk_live_1234567890abcdef'; -const password = 'mySecretPassword123'; +const apiKey = 'PLACEHOLDER_KEY_1234567890abcdef'; +const password = 'FAKE_PASSWORD_FOR_DOCS_12345678'; ``` Generated `context.json`: diff --git a/docs/context/cli/ignore.md b/docs/context/cli/ignore.md index 7020d16..a065149 100644 --- a/docs/context/cli/ignore.md +++ b/docs/context/cli/ignore.md @@ -181,7 +181,7 @@ This ensures consistent formatting regardless of how you specify paths. - `src/**/*.test.ts` - Matches all `.test.ts` files under `src/` - `config/*.json` - Matches all `.json` files directly in `config/` -See [stampignore.md](../stampignore.md) for more details on glob pattern syntax. +See [stampignore.md](../reference/stampignore.md) for more details on glob pattern syntax. ## Best Practices @@ -193,7 +193,7 @@ See [stampignore.md](../stampignore.md) for more details on glob pattern syntax. ## See Also -- [stampignore.md](../stampignore.md) - Complete `.stampignore` file format and usage guide +- [stampignore.md](../reference/stampignore.md) - Complete `.stampignore` file format and usage guide - [context.md](context.md) - How `.stampignore` affects context compilation - [security-scan.md](security-scan.md) - Security scanning to detect secrets in your codebase diff --git a/docs/context/cli/security-scan.md b/docs/context/cli/security-scan.md index 9ace464..85938e6 100644 --- a/docs/context/cli/security-scan.md +++ b/docs/context/cli/security-scan.md @@ -12,6 +12,58 @@ The security scan helps prevent accidentally exposing sensitive credentials by: - Generating detailed reports of detected secrets - Integrating with the `stamp init` command for automated security checks +The scan is useful regardless of `stamp context --include-code` mode (CI and source hygiene). **Leaking implementation secrets into generated context files** is mainly a risk when using **`--include-code full`**. the following section explains how reports connect to `stamp context`. + +## Automatic Secret Sanitization in Context Generation + +When you run `stamp context` or `stamp context style`, LogicStamp automatically sanitizes secrets in the generated JSON files if a security report exists. + +**How it works:** + +1. If `stamp_security_report.json` exists in your project root, it's automatically loaded +2. When generating context JSON files, any secrets detected in the security report are replaced with `"PRIVATE_DATA"` in the generated files +3. **Your source code files are never modified** - only the generated JSON files contain sanitized values + +**Example:** + +If your source code contains: +```typescript +const apiKey = 'PLACEHOLDER_KEY_1234567890abcdef'; +``` + +The generated `context.json` will contain: +```json +{ + "code": "const apiKey = 'PRIVATE_DATA';" +} +``` + +**Important notes:** + +- ✅ **Source files are never modified** - your actual code remains unchanged +- ✅ **Automatic** - happens automatically when a security report exists +- ✅ **Safe** - secrets are replaced only in generated JSON files, never in source code +- ✅ **Sanitization runs whenever a report exists** — any secret text that *does* appear in generated output is replaced. in practice, **raw source (and typical inline secrets) only appear when using `--include-code full`** + +**Code inclusion modes and credentials:** + +- **`none` mode**: No code is included, so credentials cannot appear in bundles +- **`header` mode**: Only JSDoc `@uif` metadata blocks are included (not implementation code), so credentials in your source code will not appear in bundles +- **`header+style` mode**: Same as `header` mode (only metadata), plus style information in contracts (not code), so credentials will not appear in bundles +- **`full` mode**: Full source code is included, so credentials could appear unless sanitized. Sanitization automatically replaces detected secrets with `"PRIVATE_DATA"` when a security report exists + +**Even if credentials exist in your source files (which they shouldn't), they can only be included in generated bundles when using `--include-code full` mode. The other modes (`none`, `header`, `header+style`) only include metadata and contracts, not actual implementation code where credentials would typically be found.** + +**When sanitization happens:** + +- `stamp context` - Secrets are sanitized in generated context files +- `stamp context style` - Secrets are sanitized in generated context files (same behavior) +- If no security report exists, code is included as-is (no sanitization) + +This ensures that sensitive credentials never appear in your context JSON files, even if they exist in your source code. + +--- + ## Usage ### Basic Scan @@ -202,54 +254,6 @@ Useful for: - CI/CD pipelines that need automated security validation - Ensuring security best practices are followed from project initialization -## Automatic Secret Sanitization in Context Generation - -When you run `stamp context` or `stamp context style`, LogicStamp automatically sanitizes secrets in the generated JSON files if a security report exists. - -**How it works:** - -1. If `stamp_security_report.json` exists in your project root, it's automatically loaded -2. When generating context JSON files, any secrets detected in the security report are replaced with `"PRIVATE_DATA"` in the generated files -3. **Your source code files are never modified** - only the generated JSON files contain sanitized values - -**Example:** - -If your source code contains: -```typescript -const apiKey = 'sk_live_1234567890abcdef'; -``` - -The generated `context.json` will contain: -```json -{ - "code": "const apiKey = 'PRIVATE_DATA';" -} -``` - -**Important notes:** - -- ✅ **Source files are never modified** - your actual code remains unchanged -- ✅ **Automatic** - happens automatically when a security report exists -- ✅ **Safe** - secrets are replaced only in generated JSON files, never in source code -- ✅ **Works with all code inclusion modes** - applies to both `--include-code header` and `--include-code full` - -**Code inclusion modes and credentials:** - -- **`none` mode**: No code is included, so credentials cannot appear in bundles -- **`header` mode**: Only JSDoc `@uif` metadata blocks are included (not implementation code), so credentials in your source code will not appear in bundles -- **`header+style` mode**: Same as `header` mode (only metadata), plus style information in contracts (not code), so credentials will not appear in bundles -- **`full` mode**: Full source code is included, so credentials could appear unless sanitized. Sanitization automatically replaces detected secrets with `"PRIVATE_DATA"` when a security report exists - -**Even if credentials exist in your source files (which they shouldn't), they can only be included in generated bundles when using `--include-code full` mode. The other modes (`none`, `header`, `header+style`) only include metadata and contracts, not actual implementation code where credentials would typically be found.** - -**When sanitization happens:** - -- `stamp context` - Secrets are sanitized in generated context files -- `stamp context style` - Secrets are sanitized in generated context files (same behavior) -- If no security report exists, code is included as-is (no sanitization) - -This ensures that sensitive credentials never appear in your context JSON files, even if they exist in your source code. - ## Exit Codes - **0**: No secrets found @@ -313,6 +317,7 @@ stamp security --hard-reset --force - Pattern-based detection (may have false positives or miss some formats) - Only scans TypeScript, JavaScript, and JSON files +- Lines longer than 1000 characters are skipped during pattern matching (performance and safety). secrets confined to such lines may not be detected or sanitized - Files larger than 10MB are skipped (you'll see a warning) - Doesn't detect encrypted secrets or secrets in environment-specific files - Static analysis only (can't detect secrets passed at runtime) @@ -341,6 +346,6 @@ If legitimate secrets aren't being detected: ## See Also - [Security Policy](../../SECURITY.md) - Complete security policy, best practices, and handling of sensitive information -- [.stampignore Format](../stampignore.md) - Documentation on `.stampignore` file format (optional, independent of security scan) +- [.stampignore Format](../reference/stampignore.md) - Documentation on `.stampignore` file format (optional, independent of security scan) - [`stamp context`](./context.md) - Generate context diff --git a/docs/context/cli/style.md b/docs/context/cli/style.md index da733f3..a40554b 100644 --- a/docs/context/cli/style.md +++ b/docs/context/cli/style.md @@ -10,7 +10,7 @@ stamp context style [path] [options] **Note:** The `stamp context style` command is equivalent to `stamp context --include-style`. Both syntaxes produce identical output. -**File Exclusion:** `stamp context style` respects `.stampignore`, just like `stamp context`. `.stampignore` is completely optional and independent of security scanning. See [stampignore.md](../stampignore.md) for details. +**File Exclusion:** `stamp context style` respects `.stampignore`, just like `stamp context`. `.stampignore` is completely optional and independent of security scanning. See [stampignore.md](../reference/stampignore.md) for details. ## Overview @@ -261,14 +261,14 @@ stamp context --include-style ## Style Mode: Lean vs Full -The `--style-mode` flag controls how style metadata is formatted in the output: +The `--style-mode` flag controls how style metadata is formatted in the output. **Both modes extract the same data**; the difference is how much is included in the output. -- **`lean` (default)** – Compact format with counts and flags: +- **`lean` (default)** – Compact format: drops arrays, keeps counts and flags: - Tailwind: `classCount` instead of full class arrays - Component libraries: Top N components with counts - More token-efficient, suitable for most use cases -- **`full`** – Verbose format with arrays and detailed information: +- **`full`** – Verbose format: keeps all extracted data (arrays of classes, selectors, components, etc.): - Tailwind: Full arrays of classes in each category - Component libraries: Complete component lists with all details - More comprehensive, useful for detailed design analysis diff --git a/docs/context/cli/watch.md b/docs/context/cli/watch.md index b200b63..4047782 100644 --- a/docs/context/cli/watch.md +++ b/docs/context/cli/watch.md @@ -50,6 +50,20 @@ Watch mode maintains a cache of contracts, AST data, and style metadata. When a This makes rebuilds significantly faster than full regeneration. +### Errors and recovery + +If an **incremental** rebuild throws (parse error, I/O, etc.), watch mode: + +1. Logs the error (and appends to the watch log when `--log-file` is set). +2. Runs a **full** `stamp context` rebuild (same as the non-watch command) and reloads output from disk. +3. **Re-initializes the watch cache** when that succeeds so later edits use incremental rebuilds again. + +If step 2 or 3 fails, the in-memory cache is cleared. each subsequent change triggers a full rebuild until one completes successfully. + +**Diff / strict-watch baseline:** The snapshot used for “what changed” and for strict violations is normally fixed for the session (from the first successful load). After a **successful recovery**, that baseline is updated to match the recovered output so comparisons stay aligned with what is on disk. Strict-watch **session counters** (errors/warnings detected, resolved count, etc.) are **not** reset by recovery. + +**Corrupted or missing context files:** When the context index or a folder context file cannot be read or parsed, watch mode emits a warning (suppressed when `--quiet` is set), except a missing main index before any output exists (`ENOENT`), which still returns empty bundles without a warning. + ### Change Detection Watch mode detects and displays what changed in your components (informational): @@ -310,7 +324,7 @@ When violations are detected, strict watch mode creates a structured JSON report } ``` -**State-based semantics (v0.5.5+):** The violations report shows **current** violations relative to the baseline (state when watch mode started), not cumulative history: +**State-based semantics (v0.5.5+):** The violations report shows **current** violations relative to the **baseline** snapshot used for diffs (normally from the first successful rebuild in the session; updated after [successful error recovery](#errors-and-recovery)), not cumulative history: - `cumulativeViolations/Errors/Warnings` reflect the current state, not a running total - **File lifecycle**: The file is created when violations are detected and automatically deleted when all violations are resolved (reverted back to baseline) - This works like `git diff` - only shows what's currently different from baseline diff --git a/docs/context/frameworks/express.md b/docs/context/frameworks/express.md index 8aeab2b..0fbbd5b 100644 --- a/docs/context/frameworks/express.md +++ b/docs/context/frameworks/express.md @@ -90,6 +90,18 @@ LogicStamp categorizes Express files into different kinds: - **`node:api`** - Express route files with route definitions - **`ts:module`** - TypeScript modules/utilities (non-route files) +## Routes and `tsc` + +TypeScript validates handler types, not whether clients still call the correct URL. If you only change the path and keep the same handler, types often stay valid: + +```typescript +router.get('/users', listUsers); +// → +router.get('/user', listUsers); +``` + +That is still an HTTP breaking change for callers. LogicStamp includes **path**, **method**, and **handler** in extracted routes, which feed **`semanticHash`**, so **`stamp context compare`** can surface the drift. For **strict** violations vs informational API deltas, see [API signature handling](../cli/strict-modes.md#api-signature-handling). + ## Express-Specific Features ### Route Extraction @@ -606,7 +618,7 @@ app.get('/users', getUsers); - [NestJS Support](./nestjs.md) - NestJS framework features - [TypeScript Support](./typescript.md) - TypeScript-specific features - [CLI Reference](../cli/context.md) - Command-line usage -- [Contract Schema](../schema.md) - UIFContract format +- [Contract Schema](../reference/schema.md) - UIFContract format ## Express Ecosystem Support diff --git a/docs/context/frameworks/nestjs.md b/docs/context/frameworks/nestjs.md index abdc90d..20ed481 100644 --- a/docs/context/frameworks/nestjs.md +++ b/docs/context/frameworks/nestjs.md @@ -194,6 +194,10 @@ LogicStamp categorizes NestJS files into different kinds: - **`node:api`** - NestJS controller files with route definitions - **`ts:module`** - TypeScript modules/utilities (non-controller files) +## Routes and `tsc` + +The same idea applies as with Express: changing **`@Controller('users')`** to **`@Controller('user')`**, or a route segment on **`@Get()` / `@Post()`**, can leave **method signatures and DTO types** unchanged so **`tsc` stays quiet**, while the **public HTTP surface** changes. Those paths feed the extracted contract and **`semanticHash`**, so **`stamp context compare`** can show the change. **Strict** violation rules for HTTP are narrower; see [API signature handling](../cli/strict-modes.md#api-signature-handling). + ## NestJS-Specific Features ### Controller Detection @@ -821,7 +825,7 @@ export class PostsController { } // ❌ Not extracted - [Express.js Support](./express.md) - Express.js framework features - [TypeScript Support](./typescript.md) - TypeScript-specific features - [CLI Reference](../cli/context.md) - Command-line usage -- [Contract Schema](../schema.md) - UIFContract format +- [Contract Schema](../reference/schema.md) - UIFContract format ## NestJS Ecosystem Support diff --git a/docs/context/frameworks/nextjs.md b/docs/context/frameworks/nextjs.md index 61c64be..1ba5adb 100644 --- a/docs/context/frameworks/nextjs.md +++ b/docs/context/frameworks/nextjs.md @@ -4,18 +4,17 @@ LogicStamp Context provides enhanced support for Next.js applications, automatic ## Next.js Detection -LogicStamp automatically identifies Next.js projects by: +LogicStamp scans TypeScript and TSX files anywhere in the project, including Next.js folders. -- **File structure**: Detects `app/`, `pages/`, and `src/app/` directories -- **Next.js imports**: Detects imports from `next`, `next/link`, `next/router`, etc. -- **Route files**: Identifies page and layout files based on Next.js conventions -- **API routes**: Detects API route handlers in `pages/api/` or `app/api/` +- **Imports**: `next`, `next/link`, `next/router`, etc. appear in extracted import lists like any other module. +- **App Router metadata** (`isInAppDir`, `routeRole`, `segmentPath`, and `metadata` / `generateMetadata` handling) is only produced for files under an App Router tree: path contains `app/` or `src/app/` as a directory segment (see **App Router** below). This is path-based, not import-based. +- **Pages Router** (`pages/`, `pages/api/`): files are still analyzed as React or TypeScript modules, but they do **not** receive those App Router fields. Filename conventions like `pages/index.tsx` do not map to `routeRole: 'page'` or a computed `segmentPath` in the contract. ## What Gets Extracted ### App Router (Next.js 13+) -LogicStamp detects and extracts App Router patterns: +For files under `app/` or `src/app/`, LogicStamp fills the `nextjs` metadata object where applicable: ``` app/ @@ -29,49 +28,58 @@ app/ route.ts → API route ``` -**Detected metadata:** -- `isInAppDir: true` - File is in `/app/` directory -- `directive: 'client' | 'server'` - 'use client' or 'use server' directive -- `routeRole: 'page' | 'layout' | 'loading' | 'error' | 'not-found' | 'template' | 'default' | 'route'` - Route role based on filename -- `segmentPath: string` - Route path derived from file structure (e.g., `/blog/[slug]`, `/api/users`) -- `metadata` - Metadata exports (static and/or dynamic) +**Detected metadata (App Router paths only):** +- `isInAppDir: true` - File is under `app/` or `src/app/` +- `directive: 'client' | 'server'` - `'use client'` or `'use server'` at the top of the file (before imports) +- `routeRole: 'page' | 'layout' | 'loading' | 'error' | 'not-found' | 'template' | 'default' | 'route'` - Derived from the **basename** of the file (`page.tsx` → `page`, `layout.tsx` → `layout`, etc.) +- `segmentPath: string` - Route path derived from the directory under `app/` (e.g., `/blog/[slug]`, `/api/users`); route groups `(folder)` are stripped +- `metadata` - `export const metadata` and/or `export function generateMetadata` (static keys when parsable; dynamic flag when `generateMetadata` exists) ### Pages Router (Next.js 12 and earlier) -LogicStamp also supports the Pages Router: +Files under `pages/` and `pages/api/` are parsed like any other `.ts` / `.tsx` source: components, hooks, props, exports, etc. + +**`nextjs` metadata for Pages Router paths:** +- **`directive`**: Still detected if `'use client'` or `'use server'` appears at the top of the file (same rule as App Router). +- **`isInAppDir`, `routeRole`, `segmentPath`, `metadata`**: Not populated for `pages/` paths, because those fields are implemented for the App Router directory layout only. +- **Routing**: URL structure, dynamic segments, `pages/api` routes, and data-fetching helpers (`getServerSideProps`, `getStaticProps`, `getStaticPaths`) are **not** inferred or extracted as Next-specific metadata. ``` pages/ - index.tsx → Home page (/) - about.tsx → About page (/about) - blog/ - [slug].tsx → Dynamic route (/blog/:slug) - api/ - users.ts → API route (/api/users) + index.tsx → Analyzed as a React/TS module (not `routeRole: 'page'`) + about.tsx → Same + blog/[slug].tsx → Same (no extracted segment path in `nextjs`) + api/users.ts → Same (no App Router-style `segmentPath`) ``` -**Detected metadata:** -- `isInAppDir: true` - File is in `/app/` directory (if applicable) -- `directive: 'client' | 'server'` - 'use client' or 'use server' directive (if present) -- Note: Route paths, dynamic routes, API routes, and `getServerSideProps`/`getStaticProps`/`getStaticPaths` are not extracted, only directory location and directives are detected - ### Next.js Components #### Pages +**App Router — `app/page.tsx` (or `src/app/page.tsx`):** + ```tsx -// app/page.tsx or pages/index.tsx export default function HomePage() { return
Home
; } ``` -**Detected as:** `react:component` with Next.js metadata: -- `isInAppDir: true` - File is in `/app/` directory -- `routeRole: 'page'` - Detected from `page.tsx` filename -- `segmentPath: '/'` - Root route path (or nested path like `/blog/[slug]`) +**Detected as:** `react:component` with `nextjs` metadata including: +- `isInAppDir: true` +- `routeRole: 'page'` (filename is `page.tsx`) +- `segmentPath: '/'` at the app root, or e.g. `/blog/[slug]` for `app/blog/[slug]/page.tsx` -**Note:** All React components (including pages) are classified as `react:component`. Next.js-specific information is stored in the `nextjs` metadata field, not as a separate component kind. +**Pages Router — `pages/index.tsx`:** + +```tsx +export default function HomePage() { + return
Home
; +} +``` + +**Detected as:** `react:component` (when it matches React rules). The basename is `index`, not `page`, so **`routeRole` is not set**. **`isInAppDir`** and **`segmentPath`** are not set for `pages/` paths. Optional: `directive` if you add `'use client'` / `'use server'` at the top. + +**Note:** All React components (including pages) use the kind `react:component`. Next.js-specific information is stored in the `nextjs` field when present, not as a separate component kind. #### Layouts @@ -110,18 +118,20 @@ export async function POST(request: Request) { } ``` -**Detected as:** `react:component` or `ts:module` (based on content) with Next.js metadata: -- `isInAppDir: true` - File is in `/app/api/` directory -- `routeRole: 'route'` - Detected from `route.ts` or `route.tsx` filename -- `segmentPath: '/api/users'` - API route path +**Detected as:** `react:component` or `ts:module` (based on content). For **`app/api/.../route.ts`** under the App Router, `nextjs` can include: +- `isInAppDir: true` +- `routeRole: 'route'` (basename `route`) +- `segmentPath` such as `/api/users` -**Note:** API routes are classified based on their content (React components vs TypeScript modules). Next.js-specific information is stored in the `nextjs` metadata field. +**Pages Router** handlers under `pages/api/` do **not** get `isInAppDir`, `routeRole`, or `segmentPath` from this logic. + +**Note:** Next.js-specific information is stored in the `nextjs` metadata field when the file path is under `app/` or `src/app/`. ## Next.js-Specific Features ### Route Roles -LogicStamp detects route roles based on special Next.js filenames: +Under **`app/`** or **`src/app/`**, LogicStamp detects route roles from special filenames: | Filename | Route Role | Description | |----------|-----------|-------------| @@ -134,6 +144,8 @@ LogicStamp detects route roles based on special Next.js filenames: | `default.tsx` | `default` | Default parallel route | | `route.ts` | `route` | API route handler | +These roles are **not** assigned from `pages/` filenames (e.g. `pages/index.tsx` does not produce `routeRole: 'page'`). + ### Segment Paths LogicStamp extracts route paths from file structure: @@ -318,35 +330,35 @@ stamp context ./app ## Next.js Project Structure -LogicStamp respects Next.js conventions: +Typical layouts LogicStamp can scan (subject to your include patterns and ignore rules): ``` my-nextjs-app/ - app/ # App Router (Next.js 13+) + app/ # App Router — `nextjs` routing metadata filled here layout.tsx page.tsx components/ Button.tsx - pages/ # Pages Router (if used) + pages/ # Pages Router — TS/TSX analysis only; no App Router `nextjs` fields index.tsx api/ users.ts - public/ # Static assets (ignored) - node_modules/ # Dependencies (ignored) + public/ # Static assets (usually ignored) + node_modules/ # Dependencies (usually ignored) ``` ## Best Practices -1. **Use App Router**: LogicStamp has better support for App Router patterns +1. **App Router metadata**: Rich `nextjs` routing metadata is only filled for files under `app/` or `src/app/` 2. **Type your routes**: Type route params and search params for better extraction 3. **Organize components**: Keep components in `components/` directory 4. **API routes**: Use TypeScript for API route handlers ## Limitations -- Middleware files are detected but not fully analyzed -- `getServerSideProps` and `getStaticProps` are identified but their return types may not be fully extracted -- Dynamic imports in routes are tracked but not resolved +- **`middleware.ts`**: Not specially detected or summarized as a Next.js entry type. +- **Pages Router**: No contract fields for URL patterns, `getServerSideProps` / `getStaticProps` / `getStaticPaths`, or `pages/api` route paths in the `nextjs` object (those files are still parsed as normal TS/TSX). +- **Dynamic `import()`**: May appear in imports or code shape like other patterns; dynamic targets are not resolved to modules. ## Related Documentation diff --git a/docs/context/frameworks/typescript.md b/docs/context/frameworks/typescript.md index 8214f21..4469f3d 100644 --- a/docs/context/frameworks/typescript.md +++ b/docs/context/frameworks/typescript.md @@ -2,14 +2,18 @@ LogicStamp Context is built with TypeScript in mind and provides comprehensive support for TypeScript features, type extraction, and type-safe patterns. +**Works alongside `tsc`:** LogicStamp uses the TypeScript compiler API (via ts-morph) to **extract** contracts. It complements **`tsc --noEmit`** (or equivalent) in CI—extraction does **not** mirror your full-project **`tsconfig`** typecheck. **Strict** compare/watch modes detect **contract** breaking changes vs a baseline, not every TS error. See [Known limitations](../reference/limitations.md#typescript-compiler-tsc). + +**Extends beyond `.d.ts` surfaces:** `.d.ts` files describe type surfaces for consumers. LogicStamp adds semantic contracts, dependency graphs (`graph.nodes`/`graph.edges`), and diffable change hashes (`semanticHash`/`bundleHash`) for LLM workflows. Prop types from third-party `.d.ts` in `node_modules` are [partially supported](../reference/limitations.md#third-party-components) (Phase 2 pending). + ## TypeScript Detection LogicStamp automatically works with TypeScript projects: - **File extensions**: `.ts` and `.tsx` files -- **TypeScript configuration**: Reads `tsconfig.json` for compiler options -- **Type system**: Uses TypeScript's AST for accurate type extraction -- **Type definitions**: Extracts interfaces, types, and type aliases +- **Parsing**: Each file is loaded with `ts-morph` using fixed compiler options (ESNext target, JSX enabled for `.tsx`). Your repo’s **`tsconfig.json` is not loaded** for this per-file project, so workspace settings like `paths`, `baseUrl`, `strict`, or custom `jsx` mode are not applied automatically during extraction. +- **Type system**: Uses TypeScript’s AST (and the type checker within that isolated project) for extraction +- **Type definitions**: Extracts interfaces, types, and type aliases from the parsed source ## What Gets Extracted @@ -213,26 +217,14 @@ stamp context stamp context --include-code full ``` -## TypeScript Configuration +## TypeScript configuration -LogicStamp respects your `tsconfig.json`: +LogicStamp does **not** currently merge your project’s `tsconfig.json` into the parser `Project`. That means: -```json -{ - "compilerOptions": { - "jsx": "react-jsx", - "target": "ES2020", - "module": "ESNext", - "strict": true - } -} -``` +- **`compilerOptions.paths` / `baseUrl`**: Path aliases may not resolve the same way they do under `tsc`; prefer relative imports in files you care about if resolution matters for extracted types. +- **Strictness and JSX**: Extraction uses a built-in option set, not your repo’s `strict` or `jsx` compiler choice. -**Respected settings:** -- JSX mode -- Target and module settings -- Path mappings (`paths` in `tsconfig.json`) -- Base URL +Your `tsconfig.json` remains important for building and editing the app; it just is not the source of truth for how LogicStamp configures `ts-morph` today. ## Best Practices @@ -248,10 +240,11 @@ LogicStamp respects your `tsconfig.json`: - Type-level computations are not executed - Some advanced TypeScript features may have limited extraction - Circular type references may not be fully resolved +- Project `tsconfig` options (including path aliases) are not applied to the extraction `Project` unless behavior changes in a future release ## Related Documentation - [React Support](./react.md) - TypeScript with React - [Next.js Support](./nextjs.md) - TypeScript with Next.js -- [UIF Contracts](../uif_contracts.md) - Component contract types +- [UIF Contracts](../reference/uif-contracts.md) - Component contract types diff --git a/docs/context/monorepo.md b/docs/context/guides/monorepo.md similarity index 100% rename from docs/context/monorepo.md rename to docs/context/guides/monorepo.md diff --git a/docs/context/usage.md b/docs/context/guides/usage.md similarity index 100% rename from docs/context/usage.md rename to docs/context/guides/usage.md diff --git a/docs/context/limitations.md b/docs/context/limitations.md deleted file mode 100644 index 0f54f9a..0000000 --- a/docs/context/limitations.md +++ /dev/null @@ -1,884 +0,0 @@ -# Known Limitations - -Things that don't work perfectly yet. We're working on improving these areas. - -## ⚠️ Breaking Changes - -### v0.7.0 - Style Mode Default Changed - -**Breaking Change:** The default output mode for `stamp context style` is now `--style-mode lean` instead of `full`. This provides smaller, faster bundles by default. Use `--style-mode full` to restore the previous behavior. - -See [CHANGELOG.md](../CHANGELOG.md#070---2026-03-03) for details. - -## Overview - -LogicStamp Context is pretty accurate overall—around 90% of the time it gets things right. Component structure, props, state, hooks, and imports are usually detected correctly, but there are a few areas where things can be incomplete or a bit off. - -- **~95%** - Component Contracts (Props, state, hooks detection) -- **~100%** - Imports Detection (Imports tracked correctly) -- **~90-95%** - Style Metadata (Static classes ~100%, dynamic classes Phase 1 complete ~70-80% of patterns, CSS-in-JS 9/9 major libraries supported ✅ v0.5.1) - ---- - -# Fixed/Resolved Limitations - -These items have been implemented and are no longer limitations. - -## Hook Parameter Detection - -**Status:** ✅ **Fixed in v0.3.6** - -Hook parameter detection is now fully implemented! We can extract function signatures for custom React hooks and include their parameters in the contract. - -**What Works:** -- ✅ Extracts parameters from exported hook function declarations -- ✅ Extracts parameters from exported arrow function hooks -- ✅ Extracts parameters from default exported hooks -- ✅ Captures parameter types (from type annotations, default values, or TypeScript type checker) -- ✅ Handles optional parameters (with `?` or default values) -- ✅ Stores parameters in `logic.props` field for hooks -- ✅ Works even when Props interfaces exist in the same file -- ✅ Props take priority on conflicts - -**Example** - -**Source Code:** -```typescript -export function useTypewriter(text: string, speed = 30, pause = 800) { - const [displayedText, setDisplayedText] = useState('') - // ... implementation - return displayedText -} -``` - -**Context Output:** -```json -{ - "composition": { - "hooks": ["useTypewriter"] - }, - "interface": { - "props": { - "text": "string", - "speed": { "type": "number", "optional": true }, - "pause": { "type": "number", "optional": true } - } - } -} -``` - -## Hook Classification - -**Status:** ✅ **Fixed in v0.3.1** - -Custom hooks are now correctly classified as `react:hook` instead of `react:component`. The detection logic checks if the main export (default or named) is a function starting with "use" and has no JSX elements. - -**Example** - -**Source Code:** -```typescript -function useTypewriter(text: string, speed = 30) { - const [displayedText, setDisplayedText] = useState('') - // ... hook implementation - return displayedText -} -``` - -**Context Output (Correct):** -```json -{ - "kind": "react:hook" -} -``` - -## Emit Detection Accuracy - -**Status:** ✅ **Fixed in v0.3.7** - -Emit detection now correctly distinguishes between internal handlers and component public API emits. Only handlers that are part of the component's Props interface/type are included in the `emits` object. - -**What Works:** -- ✅ Only extracts event handlers that exist in Props interfaces/types -- ✅ Filters out internal handlers (e.g., `onClick={() => setMenuOpen(!menuOpen)}`) -- ✅ Filters out inline handlers that are not props -- ✅ Uses prop type signatures when available for accurate event signatures -- ✅ Falls back to AST-based arrow function parsing only when prop signature is unavailable -- ✅ Uses `hasOwnProperty` check to avoid inherited prototype properties -- ✅ Always includes prop-based handlers even if no initializer or signature available (uses default) - -**Example** - -**Source Code:** -```typescript -function Header() { - const [menuOpen, setMenuOpen] = useState(false); - - return ( - - ); -} -``` - -**Context Output (Correct):** -```json -{ - "logic": { - "emits": {} - } -} -``` - -**Source Code (with Props):** -```typescript -interface ButtonProps { - onClick?: () => void; -} - -function Button({ onClick }: ButtonProps) { - return ; -} -``` - -**Context Output (Correct):** -```json -{ - "logic": { - "emits": { - "onClick": { - "type": "function", - "signature": "() => void" - } - } - } -} -``` - ---- - -# Active Limitations - -These are current limitations that still need to be addressed. - -## Dynamic Class Parsing - -**Issue** - -Style extraction works great for static Tailwind classes and template literals. Static segments within template literals are extracted (e.g., `` className={`base static-class`} `` will extract `"base"` and `"static-class"`). However, dynamic expressions within `${}` are partially resolved (Phase 1) or not resolved (Phase 2). - -**Phase 1 Status:** ✅ **Complete (v0.3.9)** - -**What Works (Phase 1):** -- ✅ Const/let declarations: `const base = 'px-4 py-2'` → extracts `px-4`, `py-2` -- ✅ Object property access: `variants.primary` → extracts classes from property value -- ✅ Conditional expressions: `${isActive ? 'bg-blue-500' : 'bg-gray-500'}` → extracts both branches - -**What Doesn't Work (Phase 2 - Future):** -- ❌ Object lookups with variables: `variants[variant]` → index variable not resolved -- ❌ Cross-file references: `import { baseClasses } from './styles'` → imports not analyzed -- ❌ Function calls: `getClasses('primary')` → function bodies not analyzed - -**Example (Phase 1 - Works):** - -**Source Code:** -```typescript -function Button({ variant }: { variant: 'primary' | 'secondary' }) { - const base = 'px-4 py-2 rounded-lg font-semibold' - const variants = { - primary: 'bg-blue-600 hover:bg-blue-700 text-white', - secondary: 'bg-gray-200 hover:bg-gray-300 text-gray-900' - } - const isActive = true; - - return ( - - ) -} -``` - -**Context Output (After Phase 1):** -```json -{ - "style": { - "styleSources": { - "tailwind": { - "categories": { - "spacing": ["px-4", "py-2"], - "borders": ["rounded-lg"], - "typography": ["font-semibold"], - "colors": ["bg-blue-600", "hover:bg-blue-700", "text-white"], - "effects": ["ring-2"] - } - } - } - } -} -``` - -**Example (Phase 2 - Still Doesn't Work):** - -**Source Code:** -```typescript -function Button({ variant }: { variant: 'primary' | 'secondary' }) { - const variants = { - primary: 'bg-blue-600 hover:bg-blue-700 text-white', - secondary: 'bg-gray-200 hover:bg-gray-300 text-gray-900' - } - - return ( - - ) -} -``` - -**Context Output (After Phase 1):** -```json -{ - "style": { - "styleSources": { - "tailwind": { - "categories": {} - } - } - } -} -``` - -**Impact:** Phase 1 addresses ~70-80% of common dynamic class patterns. Phase 2 will handle advanced edge cases like object lookups with variables and cross-file references. If you build classes from variables using object lookups or imports, the style metadata will still be incomplete until Phase 2. - -## Next.js Framework Limitations - -**Status:** 🟡 **Partially Complete** - -Next.js support includes basic detection of App Router patterns, directives, and directory structure, but many Next.js-specific features are not yet extracted. - -**What Works:** -- ✅ `'use client'` and `'use server'` directive detection -- ✅ App Router directory detection (`isInAppDir: true` for files in `/app/` directory) -- ✅ Next.js import tracking (`next/link`, `next/image`, `next/navigation`, etc.) -- ✅ Basic component detection (pages, layouts, API routes as React components) -- ✅ **Route role detection** - Automatically detects route roles (`page`, `layout`, `loading`, `error`, `not-found`, `template`, `default`, `route`) ✅ **v0.3.10** -- ✅ **Segment path extraction** - Extracts route paths from file structure (e.g., `/blog/[slug]`) ✅ **v0.3.10** -- ✅ **Metadata export extraction** - Extracts static metadata (`export const metadata = {...}`) and detects dynamic metadata (`export function generateMetadata()`) ✅ **v0.3.10** - -**What Doesn't Work:** -- ❌ Layout hierarchy: Parent-child layout relationships not extracted -- ❌ Data fetching patterns: `getServerSideProps`, `getStaticProps`, `getStaticPaths` return types not fully extracted -- ❌ Route handlers: API route handlers (`GET`, `POST`, etc.) detected but request/response types not extracted -- ❌ Loading/error boundaries: `loading.tsx` and `error.tsx` files detected but boundary relationships not extracted -- ❌ Middleware: Middleware files detected but not fully analyzed -- ❌ Dynamic imports: `next/dynamic` imports tracked but component resolution not analyzed -- ❌ Route groups: `(group)` route groups not distinguished from regular routes -- ❌ Parallel routes: `@slot` parallel routes not detected - -**Example:** - -**Source Code:** -```typescript -// app/blog/[slug]/page.tsx -export async function generateStaticParams() { - return [{ slug: 'post-1' }, { slug: 'post-2' }]; -} - -export const metadata = { - title: 'Blog Post', - description: 'A blog post' -}; - -export default function BlogPost({ params }: { params: { slug: string } }) { - return
Post: {params.slug}
; -} -``` - -**Context Output (v0.3.10):** -```json -{ - "kind": "react:component", - "nextjs": { - "isInAppDir": true, - "directive": undefined, - "routeRole": "page", - "segmentPath": "/blog/[slug]", - "metadata": { - "static": { - "title": "Blog Post", - "description": "A blog post" - } - } - } -} -``` - -**Missing:** -- `generateStaticParams` function not extracted -- Dynamic route parameter (`params.slug`) type not extracted from route structure - -**Impact:** Next.js projects are detected and route roles, segment paths, and metadata exports are now extracted (v0.3.10). However, data fetching patterns, layout hierarchy, and some advanced routing features are not yet extracted. This limits understanding of some Next.js-specific architecture patterns. - -**Priority:** Medium - -**Related:** See [docs/frameworks/nextjs.md](../frameworks/nextjs.md) for complete Next.js documentation and current feature coverage. - -## Summary of Active Limitations - -**What works really well:** -- ✅ Component structure and props -- ✅ State variables and hooks (including hook parameters) -- ✅ Import tracking -- ✅ Static style metadata -- ✅ Dependency graphs -- ✅ Inline style extraction (property names and values) -- ✅ Styled JSX CSS extraction - -**Active areas for improvement:** -- 🟡 Dynamic style extraction (Phase 1 complete in v0.3.9, Phase 2 planned for advanced patterns) -- ❌ TypeScript type extraction (generics, complex unions/intersections) -- ⚠️ Third-party component prop types (package names and versions now included in v0.3.8) -- ❌ Project-level insights (cross-folder relationships) -- 🟡 Next.js framework features (route roles, segment paths, and metadata exports now supported in v0.3.10; data fetching patterns still missing) -- ✅ Backend framework support (Express.js, NestJS) - Complete in v0.4.0 -- ✅ CSS-in-JS completeness - All major libraries supported including Chakra UI and Ant Design (v0.5.1) - -**Bottom line:** We're hitting around 90% accuracy overall. Solid foundation, but there's definitely room to improve. These issues are on our roadmap. - ---- - -# Feature Completeness & Coverage - -This section documents what's currently captured in context files versus what's missing or incomplete. This is separate from accuracy issues above—here we're tracking feature coverage, not detection correctness. - -## What's Captured - -### 1. Component Contracts (UIFContract) - -- **Component kind**: `react:component`, `react:hook`, `vue:component`, `vue:composable`, `ts:module`, `node:cli`, `node:api` ✅ **v0.4.0** -- **Props**: Types and signatures -- **State variables**: With types -- **Hooks used**: Listed in `composition.hooks` -- **Functions**: Signatures captured -- **Imports and dependencies**: Tracked -- **Exports**: Default/named exports -- **Next.js metadata**: Client directive, app dir detection - -### 2. Style Metadata (when `--style` flag is used) - -- **Tailwind classes**: Categorized by: - - Borders, colors, effects, spacing, sizing - - Layout (flex/grid), typography, transitions - - Breakpoints detected (sm, md, lg, xl) - - Class counts per component -- **CSS modules**: File paths and selectors/properties -- **Inline styles**: Property names and literal values extracted ✅ **v0.3.5** -- **Styled JSX**: CSS content, selectors, properties, global attribute ✅ **v0.3.5** -- **Layout patterns**: Flex vs grid, column configs -- **Visual metadata**: Color palettes, spacing patterns, typography scales -- **Animation metadata**: Library type, animation types -- **Style mode variants**: `lean` (default in v0.7.0) and `full` modes for token optimization ✅ **v0.7.0** - -### 3. Project Structure - -- **Folder hierarchy**: With `isRoot` flags -- **Token estimates**: Per folder/component -- **Bundle counts**: And positions -- **Component lists**: Per folder - -### 4. Versioning and Hashing - -- **Semantic hashes**: `uif:` prefixes -- **File hashes**: For change detection -- **Bundle hashes**: `uifb:` prefixes -- **Schema versioning**: Tracked - -### 5. Metadata - -- **Created timestamps**: When context was generated -- **OS detection**: Platform info (e.g., `win32`) -- **Source tool version**: `logicstamp-context@0.7.0` -- **Missing dependencies**: Tracked in `missing` array - -## What's Missing or Incomplete - -### 1. Dynamic Class Parsing - -**Status:** ✅ **Phase 1 Complete** (v0.3.9), 🟡 Phase 2 Planned - -The `extractClassesFromExpression()` function in `src/extractors/styling/tailwind.ts` now resolves Phase 1 dynamic expressions (variables, object properties, conditionals) within template literals. Phase 2 (object lookups with variables, cross-file references, function calls) is planned for a future release. - -**Location**: `src/extractors/styling/tailwind.ts` (lines 135-210) - -**Impact**: Phase 1 handles ~70-80% of common dynamic class patterns. Phase 2 will handle advanced edge cases like object lookups with variables (`variants[variant]`), cross-file references, and function calls. - -**Priority**: High (Phase 1 complete), Medium (Phase 2) - -**Implementation Phases:** - -**Phase 1 (v0.3.9 - ✅ Complete):** -- ✅ Resolve const/let declarations with string literals: `const base = 'px-4 py-2'` → extracts `px-4`, `py-2` -- ✅ Resolve object property access: `variants.primary` → extracts classes from object property value -- ✅ Handle conditional expressions in template literals: `${isActive ? 'bg-blue-500' : 'bg-gray-500'}` → extracts both branches -- **Coverage**: ~70-80% of common dynamic class patterns - -**Phase 2 (Future Release):** -- ❌ Object lookups with variables: `variants[variant]` → requires resolving index variable first -- ❌ Cross-file references: `import { baseClasses } from './styles'` → requires import resolution -- ❌ Function calls returning class strings: `getClasses('primary')` → requires function body analysis -- **Coverage**: Additional ~15-20% of edge cases - -**Current Limitations After Phase 1:** -- Object lookups with dynamic keys (`variants[variant]`) are not resolved -- Classes imported from other files are not resolved -- Function calls that return class strings are not analyzed -- Complex nested expressions may not be fully resolved - -### 2. CSS-in-JS Support - -**Status:** ✅ **Complete in v0.5.1** - -**Supported**: -- styled-components (component names, theme usage, css prop) -- Emotion (@emotion/styled) -- Material UI (@mui/material) - components, packages, features -- Ant Design (antd) - components, packages, features (theme, ConfigProvider, form, locale, icons) -- Chakra UI (@chakra-ui/*) - components, packages, features (theme, color mode, responsive props, system props) -- ShadCN/UI - components, variants, sizes -- Radix UI - primitives, patterns, accessibility -- Framer Motion - components, variants, animation features -- Styled JSX - CSS content extraction, selectors, properties, global attribute detection ✅ **v0.3.5** -- Chakra UI - components, packages, theme, color mode, responsive props, system props ✅ **v0.5.1** -- Ant Design - components, packages, theme, ConfigProvider, Form, locale, icons ✅ **v0.5.1** - -**Impact**: All major CSS-in-JS libraries are now supported. Complete coverage for popular component libraries. - -### 3. Third-Party Components Minimal Info - -**Status:** ⚠️ **Partially resolved - Phase 1 complete, Phase 2 pending** - -**Issue**: Third-party components now include package names and versions (Phase 1 - ✅ Fixed in v0.3.8), but prop types are still missing (Phase 2 - ❌ Still unresolved). - -**What Works (Phase 1 - v0.3.8):** -- ✅ Package name extraction from import specifiers (handles scoped packages, subpath imports) -- ✅ Version lookup from `package.json` (checks dependencies, devDependencies, peerDependencies) -- ✅ Package name and version fields added to missing dependency objects - -**Example (After v0.3.8):** -```json -"missing": [ - { - "name": "@mui/material", - "reason": "external package", - "referencedBy": "src/components/Dashboard.tsx", - "packageName": "@mui/material", - "version": "^5.15.0" - } -] -``` - -**Still Missing (Phase 2):** -- ❌ Prop types for third-party components -- ❌ Component API signatures from third-party packages - -**Impact**: Better understanding of external dependencies (package names and versions), but still limited API information for third-party components. - -**Location**: -- Phase 1 implementation: `src/core/pack/collector.ts` - Package name extraction and version lookup -- Phase 2 (pending): Prop type extraction from third-party packages - -**Note on Missing Dependency Reasons**: The codebase uses two different reason strings for missing dependencies: -- `"No contract found (third-party or not scanned)"` - Used when a dependency cannot be resolved (third-party components, external packages, or dependencies outside the scan path) -- `"Component not found in manifest"` - Used when the entryId itself is not found in the manifest (typically for the root component being processed) - -**Priority**: Medium (Phase 1 complete, Phase 2 pending) - -### 4. TypeScript Types Incomplete - -**Status:** ❌ **Partially resolved - still incomplete** - -**Location**: `src/core/astParser/extractors/propTypeNormalizer.ts` (`normalizePropType()` function) - -**Verified Implementation**: -- ✅ Captures prop types as strings (`"string"`, `"number"`) -- ✅ Captures literal unions via regex: `"primary" | "secondary"` → `{ type: 'literal-union', literals: ['primary', 'secondary'] }` -- ✅ Captures function types: `() => void` → `{ type: 'function', signature: '() => void' }` -- ❌ Does NOT handle generics (e.g., `ListProps`) -- ❌ Does NOT handle complex unions/intersections (e.g., `A & B`, `A | B | C` where not string literals) -- ❌ Does NOT extract generic type parameters - -**Code Evidence** (v0.3.6): `normalizePropType()` in `propTypeNormalizer.ts` only has regex for literal unions and function detection. No AST-based type analysis for generics or complex types. - -**Impact**: Limited type information for complex types - -**Priority**: Medium - -### 5. Context main.json Limitations - -**Status:** ❌ **Still unresolved** - -**Location**: `src/cli/commands/context/fileWriter.ts` (lines 206-285) - -**Missing**: Cross-folder relationships, project-wide statistics - -**Only**: Folder index with token estimates - -**Impact**: Limited project-level insights - -**Priority**: Medium - -### 6. Code Content Not Captured - -**Missing**: Actual source code (by design for token efficiency) - -**Only**: Contracts, JSDoc headers (in header mode) - -**Impact**: Can't see implementation details without reading source - -**Note**: This is intentional for token efficiency, but worth documenting. - -**Priority**: Low - -### 7. Route Extraction Edge Cases - -**Status:** ⚠️ **Minor edge case** - -Route extraction may miss routes in edge cases where JSX attribute values have unusual formatting that doesn't match standard patterns. - -**Location**: `src/core/astParser/extractors/eventExtractor.ts` (`extractJsxRoutes()` function) - -**Current Behavior**: -- ✅ Extracts routes from standard JSX attributes: `path="/home"`, `href="/about"` -- ✅ Extracts routes from JSX expressions: `path={"/home"}` -- ✅ Handles JSX-specific literal nodes that aren't standard StringLiteral -- ⚠️ May miss routes if `initializer.getText()` returns text with braces (e.g., `{"\/x"}`) that don't match the quoted string pattern - -**Impact**: Edge case that may occur with unusual JSX attribute formatting or JSX-specific node types that differ across ts-morph versions. Most common route patterns are correctly extracted. - -**Priority**: Low - -**Note**: The route extractor intentionally avoids false positives by only matching quoted strings in JSX attributes. This means it won't extract routes from variables like `{route}` or function calls like `router.push("/x")`, which is the desired behavior for a low-noise extractor. The trade-off is that some edge cases with unusual formatting may be missed. - -### 8. Comments/JSDoc Only in Header Mode - -**Missing**: Regular comments, TODO notes - -**Only**: JSDoc in header mode - -**Impact**: Loses documentation context - -**Priority**: Low - -### 9. Test Files Excluded - -**Issue**: Test files are completely excluded from context compilation. - -**Current behavior**: Test files (`.test.ts`, `.test.tsx`, `.spec.ts`, `.spec.tsx`) are explicitly filtered out during file scanning and never analyzed. - -**Missing**: Test structure, test cases, test coverage information, test utilities, and test helpers are not included in context bundles. - -**Impact**: No test understanding - AI assistants cannot see test files, test patterns, or testing strategies used in the codebase. - -**Priority**: Low - -**Note**: This is intentional by design - test files are excluded to keep context bundles focused on production code. If test analysis is needed, it would require a separate feature or flag to include test files. - -### 10. Next.js Framework Features - -**Status:** 🟡 **Partially Complete** - -**Current Behavior:** -- ✅ Basic Next.js detection (`'use client'`/`'use server'` directives, App Router directory detection) -- ✅ Next.js import tracking -- ✅ **Metadata exports** (`export const metadata = {...}`) extracted ✅ **v0.3.10** -- ✅ **Route paths, dynamic routes, route segments** extracted ✅ **v0.3.10** -- ✅ **Route role detection** (page, layout, loading, error, not-found, template, default, route) ✅ **v0.3.10** -- ❌ Layout hierarchy and relationships not extracted -- ❌ Data fetching patterns (`getServerSideProps`, `getStaticProps`, `getStaticPaths`) not fully extracted -- ❌ Route handlers (API routes) detected but request/response types not extracted -- ❌ Loading/error boundaries detected but relationships not extracted -- ❌ Middleware files detected but not fully analyzed -- ❌ Dynamic imports tracked but component resolution not analyzed - -**Impact**: Next.js projects are detected and route roles, segment paths, and metadata exports are now extracted (v0.3.10). However, layout hierarchy, data fetching patterns, and some advanced App Router features are still not extracted. This limits understanding of some Next.js-specific architecture patterns. - -**Location**: `src/core/astParser/detectors.ts` (`extractNextJsMetadata()` function) - -**Priority**: Medium - -**Related**: See [Next.js Framework Limitations](#nextjs-framework-limitations) above for detailed information and examples. - -### 11. Backend Framework Features - -**Status:** ✅ **Complete (v0.4.0)** - -Backend framework support has been fully implemented for Express.js and NestJS. - -**What Works (v0.4.0):** -- ✅ Express.js route extraction (`app.get()`, `router.post()`, etc.) -- ✅ NestJS controller extraction (`@Controller`, `@Get`, `@Post`, etc.) -- ✅ HTTP method detection (GET, POST, PUT, DELETE, PATCH, ALL) -- ✅ Route path extraction with parameter detection (`/users/:id` → `params: ['id']`) -- ✅ API signature extraction (request/response types, parameters) -- ✅ Framework-specific metadata (decorators, annotations, class names) -- ✅ Automatic framework detection (skips frontend extraction for backend files) - -**What Doesn't Work:** -- ❌ Middleware/guard/interceptor detection (not yet extracted) -- ❌ Request validation schemas (not extracted from decorators like `@Body()`, `@Query()`) -- ❌ Response transformation logic (not analyzed) -- ❌ Other Node.js frameworks (Fastify, Koa, Hapi) not yet supported - -**Impact**: Backend API routes and controllers are now fully extracted, enabling AI assistants to understand backend API structure and endpoints. Middleware and advanced framework features are not yet extracted. - -**Priority**: Low (core features complete, advanced features pending) - -### 12. Runtime Behavior - -**Missing**: Runtime props, state changes, side effects - -**Only**: Static analysis - -**Impact**: No runtime insights - -**Note**: This is expected for static analysis tools. - -**Priority**: Low - -### 13. Watch Mode - -**Status:** ✅ **Complete (v0.4.1, enhanced in v0.5.4 and v0.5.5)** - -Watch mode has been fully implemented for automatic context regeneration. - -**What Works:** -- ✅ `stamp context --watch` command -- ✅ File system watcher for `.ts`, `.tsx` files -- ✅ Style file watching (`.css`, `.scss`, `.module.css`, `.module.scss`) with `--include-style` -- ✅ Incremental rebuilds (only regenerates affected bundles) -- ✅ Debouncing (500ms) to batch rapid file changes -- ✅ Change detection showing what changed (props, hooks, state, events, components, functions) -- ✅ Debug mode (`--debug`) showing semantic/file/bundle hash changes -- ✅ Status files for tooling integration (`.logicstamp/context_watch-status.json`) -- ✅ Watch logs with `--log-file` (`.logicstamp/context_watch-mode-logs.json`) - append-based event history -- ✅ Graceful shutdown on Ctrl+C, SIGTERM, SIGHUP (v0.5.4) -- ✅ Centralized cleanup registry ensures no orphaned resources (v0.5.4) -- ✅ `watch-fast` profile for lighter style extraction - -**What Doesn't Work:** -- ❌ JavaScript files (`.js`, `.jsx`) are not watched -- ❌ Configurable watch patterns/exclusions (uses fixed defaults) -- ❌ Hot reload integration (manual browser refresh still needed) - -**Recent Improvements (v0.7.0):** -- ✅ Style cache optimization - Incremental rebuilds reuse cached style metadata when available -- ✅ Style error resilience - Style extraction failures don't block watch mode rebuilds -- ✅ Style mode variants - Cache supports both `lean` and `full` style modes - -**Impact**: Improves developer experience by automatically keeping context files in sync with code changes during development. - -**Priority**: ~~Medium~~ Complete - -### 14. Strict Watch Mode - -**Status:** ✅ **Complete (v0.5.5)** - -Strict watch mode (`--strict-watch`) tracks breaking changes during development with state-based diffing. - -**What Works:** -- ✅ Detects breaking changes: removed props, events, functions, contracts -- ✅ Detects warnings: changed prop types, removed state/variables -- ✅ State-based diffing like `git diff` (v0.5.5) - violations show current state vs baseline -- ✅ Revert detection - when breaking changes are reverted, violations file is automatically deleted -- ✅ Violations report file (`.logicstamp/strict_watch_violations.json`) - only exists when violations are present; deleted when all resolved - -**What Doesn't Work:** -- ❌ Missing dependencies are not tracked as violations (they're expected for third-party packages) - -**State-Based Diffing Limitations (v0.5.5):** -- ⚠️ **Baseline is session-scoped** - The baseline is set when watch mode starts and never updates. In long-running sessions with many file additions/deletions, comparing to a stale baseline could be misleading. -- ⚠️ **Empty baseline edge case** - If watch mode starts with no bundles (new project), all changes show as "added" relative to the empty baseline. - -**Recent Improvements (v0.5.5):** -- ✅ Missing dependencies excluded - Third-party packages no longer reported as violations (expected behavior) -- ✅ Revert detection - When breaking changes are reverted to baseline, violations file is automatically deleted - -**Impact**: Helps catch breaking API changes during development before they affect consumers. - -**Priority**: ~~Medium~~ Complete - ---- - -# Fixed/Resolved Features - -These items were previously limitations but have been fixed. For detailed release notes, see the [CHANGELOG](../CHANGELOG.md). - -## Recent Fixes (v0.7.x) - -| Version | Fix | Description | -|---------|-----|-------------| -| v0.7.2 | Git baseline comparison | `--baseline git:` option enables comparing current working tree against any local git ref (branch, tag, commit) | -| v0.7.2 | State/variables comparison | Compare command detects state and module-level variable changes | -| v0.7.2 | API signature comparison | Compare command detects backend API parameter, return type, and request/response type changes | -| v0.7.2 | Prop/emit type changes | Compare command detects when prop/emit types change (not just added/removed); only in direct file comparison mode | -| v0.7.2 | Hash-only filtering | Git baseline mode filters out hash-only differences to prevent false positives from TypeScript resolution differences | -| v0.7.2 | Symmetric file exclusion | Both baseline and current context generation use working directory's `.stampignore` for consistent file scanning | -| v0.7.2 | Git-ignored file filtering | Git-ignored files automatically filtered from comparison results in git baseline mode | -| v0.7.2 | Hash determinism | Fixed null handling and normalized nested objects/arrays for consistent hashing | -| v0.7.2 | Additions as growth | Added components/folders treated as growth (PASS), not drift; only removals/modifications trigger DRIFT | -| v0.7.0 | Style mode default | Default `stamp context style` output is now `--style-mode lean` (breaking change) | -| v0.7.0 | Security awareness | `stamp context` warns when no security report is found | -| v0.7.0 | Watch style cache | Incremental watch mode reuses cached style metadata, reducing redundant extraction | -| v0.7.0 | Style error logging | Style extraction failures in watch mode now log errors when `LOGICSTAMP_DEBUG=1` | -| v0.7.0 | File lock consistency | Added delay after stale lock removal for improved filesystem consistency on Windows | - -## Git Baseline Comparison - -**Status:** ✅ **Complete in v0.7.2** - -Git-based baseline support for context comparison, enabling meaningful drift detection against known reference points. - -**What Works (v0.7.2):** -- ✅ `--baseline git:` option to compare against any local git ref (branch, tag, commit) -- ✅ Uses git worktrees for clean isolation during comparison -- ✅ Generates context for both baseline and current code, then compares -- ✅ Automatic cleanup of worktrees and temp directories -- ✅ Hash-only change filtering to prevent false positives from TypeScript resolution differences -- ✅ Symmetric file exclusion using working directory's `.stampignore` for consistent comparison - -**How It Works:** -Context files are gitignored by design - they don't exist in git history. Git baseline generates context at two points and compares them: - -``` -stamp context compare --baseline git:main - -1. Validate git repo and resolve ref -2. Create git worktree at ref → temp/worktree/ -3. Generate context for baseline → .logicstamp/compare/baseline/ -4. Generate context for current working tree → .logicstamp/compare/current/ -5. Compare baseline vs current -6. Report drift -7. Cleanup worktree and temp directories -``` - -**Hash Behavior:** -- **Hash-only changes are filtered**: When only the semantic hash differs (with no changes to imports, hooks, functions, components, props, emits, or exports), the hash change is ignored to prevent false positives -- **Hash changes with other changes are reported**: When the hash differs AND there are other structural changes, the hash is still reported to provide context -- **Why filter hash-only?** TypeScript project resolution can produce slightly different AST structures between worktree and working directory contexts (different absolute paths, module resolution contexts, or TypeScript compiler state) even for functionally identical code. Filtering hash-only changes ensures deterministic structural comparison while preserving hash information when there are real changes. - -**Prop/Emit Type Changes:** -- **Type changes skipped in git baseline mode**: Prop and emit type changes (e.g., `string` → `number`) are only detected in direct file comparison mode, not in git baseline mode -- **Added/removed always detected**: Added and removed props/emits are detected in all modes -- **Why skip type changes?** TypeScript resolution can produce different type representations between worktree and working directory (e.g., `"string"` vs `{ type: "string" }`), causing false positives - -**Determinism:** -✅ **The workflow is deterministic for detecting meaningful changes.** Even when semantic hashes differ between worktree and working directory (due to TypeScript resolution differences), the comparison will always produce the same result (PASS or DRIFT) for identical code. Hash-only differences are filtered out to ensure deterministic results, while hash changes that occur alongside other structural changes are still reported. - -**Use Cases:** -- PR review: `stamp context compare --baseline git:main` -- CI integration: `stamp context compare --baseline git:origin/main` -- Release validation: `stamp context compare --baseline git:v1.0.0` -- Pre-commit: `stamp context compare --baseline git:HEAD` - -**Impact:** Enables meaningful drift detection against stable reference points, making CI integration straightforward. Hash-only filtering prevents false positives while preserving hash information for real structural changes. - -**Related:** See [docs/cli/compare.md](../cli/compare.md) for complete documentation on git baseline comparison and hash behavior. - -## Recent Fixes (v0.6.x) - -| Version | Fix | Description | -|---------|-----|-------------| -| v0.6.0 | Schema validation | UIFContract files validated via AJV during load; invalid contracts rejected with detailed errors | -| v0.6.0 | Path traversal protection | Enforced strict project-root boundaries across internal file utilities | -| v0.6.0 | Node.js requirement | Bumped to >=20 (required by dependency and security updates) | - -## Recent Fixes (v0.5.x) - -| Version | Fix | Description | -|---------|-----|-------------| -| v0.5.5 | Strict watch diffing | State-based diffing shows current state vs baseline (not cumulative history) | -| v0.5.5 | Config race condition | File locking prevents TOCTOU race conditions in config updates | -| v0.5.5 | Atomic file writes | Config and status files use temp file + rename pattern to prevent corruption | -| v0.5.5 | Watch cleanup | Watch status file properly deleted on exit (Windows/Cursor compatibility) | -| v0.5.4 | Graceful shutdown | Centralized cleanup registry ensures watch mode resources are cleaned up on any exit | -| v0.5.4 | Empty bundle handling | `--compare-modes` now reports errors when all bundle generations fail | -| v0.5.4 | Debug logging | Manifest building logs unresolved dependencies when `LOGICSTAMP_DEBUG=1` | -| v0.5.4 | Error handling | Extracted duplicate error handling code into shared utilities | -| v0.5.3 | Race condition fix | Sanitization stats no longer corrupted during concurrent file processing | -| v0.5.3 | Memory leak fix | Security report cache has 5-minute TTL; tokenizer cache can be cleared | -| v0.5.3 | Windows paths | Dependency resolution works correctly with Windows backslash paths | -| v0.5.3 | O(n²) → O(n) | Dependency collection uses index-based iteration for large codebases | -| v0.5.3 | Type safety | Replaced unsafe `as any` casts with proper ts-morph type guards | -| v0.5.1 | CSS-in-JS | Complete support for all major libraries (Chakra UI, Ant Design added) | - -## Earlier Fixes (v0.3.x - v0.4.x) - -| Version | Fix | Description | -|---------|-----|-------------| -| v0.4.1 | Watch mode | Full watch mode with incremental rebuilds and change detection | -| v0.4.0 | Backend support | Express.js and NestJS route/controller extraction | -| v0.3.10 | Next.js routes | Route roles, segment paths, and metadata exports | -| v0.3.9 | Dynamic Tailwind | Phase 1: Variables, object properties, conditionals in template literals | -| v0.3.8 | Third-party info | Package names and versions in missing dependencies | -| v0.3.7 | Emit accuracy | Only extracts handlers from Props interface (filters internal handlers) | -| v0.3.6 | Hook parameters | Full parameter extraction for custom React hooks | -| v0.3.5 | Styled JSX | CSS extraction from `