Known Limitations

Known Limitations

Things that don't work perfectly yet. We're working on improving these areas.

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

Hook Parameter Detection

✅ Fixed in v0.3.6

Hook parameter detection now correctly extracts function signatures from custom React hooks, including parameter types, default values, and optional parameters. Works even when Props interfaces exist in the same file.

What Works

Extracts function signatures with parameter types
Captures default parameter values
Handles optional parameters
Works with Props interfaces in the same file

Example

function useTypewriter(text: string, speed = 30, pause = 800) {
  const [displayedText, setDisplayedText] = useState('')
  // ... implementation
  return displayedText
}

Emit Detection Accuracy

✅ 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

Example

function Header() {
  const [menuOpen, setMenuOpen] = useState(false)
  
  return (
    <button onClick={() => setMenuOpen(!menuOpen)}>
      Toggle Menu
    </button>
  )
}

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 template literal placeholders are not resolved. If you're storing classes in variables or building them from variables, those dynamic parts won't show up in the style metadata.

Example

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'
  }
  
  return (
    <button className={`${base} ${variants[variant]}`}>
      Click me
    </button>
  )
}

Status: 🟡 Phase 1 complete in v0.3.9 - Static segments within template literals are now extracted. Phase 2 (advanced patterns like object lookups with variables) is planned.

Impact: Static parts of template literals are extracted, but dynamic expressions (variables, function calls, etc.) within template literal placeholders are not resolved. If you build classes from variables using object lookups, the style metadata will be incomplete until Phase 2.

Hook Classification

✅ 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

function useTypewriter(text: string, speed = 30) {
  const [displayedText, setDisplayedText] = useState('')
  // ... hook implementation
  return displayedText
}

Summary

What works really well:

Component structure and props

State variables and hooks

Import tracking

Static style metadata

Dependency graphs

Areas for improvement:

~~Hook function signatures (parameters not captured)~~ ✅ Fixed in v0.3.6
~~Emit detection accuracy (internal handlers vs. actual emits)~~ ✅ Fixed in v0.3.7
Dynamic style extraction (variable-based classes within template literals)

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
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

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.5.2 (current), 0.5.1, 0.5.0, 0.4.1, 0.4.0, 0.3.10
Missing dependencies: Tracked in missing array

What's Missing or Incomplete

1. Inline Style Objects Extraction

✅ Fixed in v0.3.5

Status: ✅ Fixed in v0.3.5 (Verified)

Location: src/core/styleExtractor/styleExtractor.ts (lines 88-191)

Verified Implementation: The extractInlineStyles() function extracts both properties AND values:

✅ Extracts property names from object literals
✅ Extracts literal values for strings, numbers, booleans, null, and template literals
✅ Returns { properties: string[], values?: Record<string, string> }

Example:

style={{ animationDelay: '2s', color: 'blue', padding: '1rem' }}

Note: Dynamic values (variables, function calls) are detected as properties but their values are not extracted (static analysis limitation).

2. CSS-in-JS Partially Supported

Medium

Supported: styled-components (component names, theme usage, css prop), Emotion (@emotion/styled), Material UI (@mui/material) - components, packages, features, 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

Status: ✅ Complete in v0.5.1 - All major CSS-in-JS libraries supported including Chakra UI and Ant Design

Impact: Most major CSS-in-JS libraries are supported, but some smaller libraries and inline style values are not fully extracted.

3. Edge Relationships (Status: Implemented)

Resolved

Status: Dependency graph edges ARE built and populated.

Implementation: The buildEdges() function in src/core/pack/builder.ts creates edges between components based on their dependencies. Edges are included in bundle output.

Note: If edges appear empty in your output, this may be due to: components having no dependencies, dependencies not being resolved (missing from manifest), or dependencies being filtered as internal components.

4. Third-Party Components Minimal Info

Medium

Issue: Third-party components only show basic "missing" info without details.

Example:

"missing": [
  {
    "name": "ChevronRight",
    "reason": "No contract found (third-party or not scanned)"
  }
]

Missing: Package names, versions, prop types for third-party components
Impact: Limited understanding of external dependencies

5. Code Content Not Captured

Low

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.

6. TypeScript Types Incomplete

Medium

Captured: Prop types as strings ("string", "number")

Missing: Full TypeScript type definitions, generics, unions, intersections
Impact: Limited type information for complex types

7. Comments/JSDoc Only in Header Mode

Low

Missing: Regular comments, TODO notes

Only: JSDoc in header mode
Impact: Loses documentation context

8. Test Files Excluded

Low

Issue: Test files are completely excluded from context generation.

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.
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.

9. Runtime Behavior

Low

Missing: Runtime props, state changes, side effects

Only: Static analysis
Impact: No runtime insights
Note: This is expected for static analysis tools.

10. Styled JSX CSS Extraction

✅ Fixed in v0.3.5

Status: ✅ Fixed in v0.3.5 (Verified)

Location: src/core/styleExtractor/styledJsx.ts (lines 59-230)

Verified Implementation: The extractStyledJsx() function fully extracts CSS content:

✅ Extracts CSS from <style jsx> template literals
✅ Parses CSS using css-tree AST for selectors and properties
✅ Detects global attribute
✅ Returns { css: string, global?: boolean, selectors?: string[], properties?: string[] }

Example:

<style jsx global>{`
  body {
    margin: 0;
    font-family: sans-serif;
  }
  .container {
    padding: 1rem;
    color: blue;
  }
`}</style>

Features: Extracts full CSS content from template literals, parses CSS using AST (css-tree) for accurate selector/property extraction, detects global attribute, handles complex selectors, per-block parsing for resilience

11. Backend Framework Limitations (v0.4.0)

Medium

Status: ✅ Backend framework support added in v0.4.0 - Express.js and NestJS route detection and API signature extraction are now supported.

What Works: Route detection, HTTP method extraction, API signatures for named handlers, route parameters

Limitations:

Middleware extraction not supported (only HTTP method calls are extracted)
Route composition not fully tracked (nested routes with app.use() not resolved)
Dynamic route paths not extracted (only string literal paths)
Anonymous handlers don't have API signatures extracted

Impact: Core backend route detection works well, but advanced Express.js/NestJS patterns like middleware chains and dynamic route composition are not fully extracted.

12. Context main.json Limitations

Medium

Missing: Cross-folder relationships, project-wide statistics

Only: Folder index with token estimates
Impact: Limited project-level insights

Implementation Plan

High Priority

~~Hook parameter detection: Extract function signatures for custom hooks~~ ✅ Fixed in v0.3.6
~~Emit detection accuracy: Distinguish internal handlers from public API emits~~ ✅ Fixed in v0.3.7
Dynamic class parsing: Resolve variable-based classes within template literals
~~Extract inline style values: Parse style={ ... } objects and include properties~~ ✅ Fixed in v0.3.5
~~Parse styled-jsx: Extract CSS from <style jsx> blocks~~ ✅ Fixed in v0.3.5
~~Populate edges: Build actual dependency graph edges~~ ✅ Implemented

Medium Priority

~~CSS-in-JS support: Complete support for remaining libraries (Chakra UI, Ant Design)~~ ✅ Complete in v0.5.1
Enhanced third-party info: Include package names, versions, prop types
TypeScript type extraction: Capture full type definitions
Project-level insights: Add cross-folder analysis to context_main.json

Low Priority

Test file analysis: Extract test structure and cases
Comment extraction: Include regular comments (not just JSDoc)
Runtime hints: Add static analysis hints about runtime behavior

Overall Assessment

What's working well:

Component contracts are comprehensive

Style metadata (when enabled) is detailed and well-structured

Project structure indexing is solid

Versioning/hashing system is robust

What needs improvement:

Dynamic class resolution (variable-based classes within template literals) - Phase 1 complete in v0.3.9, Phase 2 planned

CSS-in-JS support completeness (remaining libraries like Chakra UI, Ant Design)

Third-party component info (package names, versions now in v0.3.8; prop types still missing)

TypeScript type extraction (generics, complex unions/intersections)

Backend framework limitations (Express.js/NestJS support added in v0.4.0; middleware extraction, route composition still limited)

Next.js framework features (route roles, segment paths, metadata exports added in v0.3.10; data fetching patterns still missing)

Context main.json enhancements (cross-folder relationships, project-wide statistics)

Next Steps

Explore the complete CLI documentation or review additional guides.

Installation & Quick Start What is LogicStamp?GitHub Repository

Overview

Component Contracts

Imports Detection

Style Metadata

Hook Parameter Detection

What Works

Example

Emit Detection Accuracy

What Works

Example

Dynamic Class Parsing

Issue

Example

Hook Classification

Example

Summary

Feature Completeness & Coverage

What's Captured

1. Component Contracts (UIFContract)

2. Style Metadata (when --style flag is used)

3. Project Structure

4. Versioning and Hashing

5. Metadata

What's Missing or Incomplete

1. Inline Style Objects Extraction

2. CSS-in-JS Partially Supported

3. Edge Relationships (Status: Implemented)

4. Third-Party Components Minimal Info

5. Code Content Not Captured

6. TypeScript Types Incomplete

7. Comments/JSDoc Only in Header Mode

8. Test Files Excluded

9. Runtime Behavior

10. Styled JSX CSS Extraction

11. Backend Framework Limitations (v0.4.0)

12. Context main.json Limitations

Implementation Plan

High Priority

Medium Priority

Low Priority

Overall Assessment

What's working well:

What needs improvement:

Next Steps

2. Style Metadata (when `--style` flag is used)