This roadmap outlines the planned features, improvements, and known limitations for LogicStamp Context. It's organized into bug fixes, framework expansion, and future enhancements.
Current Version: v0.7.2 (Beta)
For detailed release notes and completed features, see CHANGELOG.md.
Recent major milestones include:
- ✅ Git baseline comparison (v0.7.2) - Compare against any git ref with
--baseline git:<ref> - ✅ 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,
--verboseflag, 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)
These items address core accuracy and completeness issues that impact the reliability of generated context files.
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
hasOwnPropertycheck 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 for detailed information.
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 for detailed code evidence and implementation phases.
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.
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) innode_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.
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<T>) - ❌ Complex unions/intersections (e.g.,
A & B,A | B | Cwhere not string literals) - ❌ Generic type parameters
Impact: Limited type information for complex types in contracts.
Related: See docs/limitations.md for detailed code evidence.
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.
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).
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.
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).
These items expand LogicStamp Context to support additional languages, frameworks, and development workflows.
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:apifor 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.
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
Status: ✅ Complete (v0.4.1) - Enhanced in v0.7.1
Automatic context regeneration when source files change.
What Works (v0.4.1):
stamp context --watchcommand- File system watcher for
.ts,.tsxfiles (and.css,.scsswith--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-fastprofile for lighter style extraction
Enhancements (v0.7.1):
- ✅ Session status tracking for strict watch mode (cumulative errors/warnings, resolved count, active violations)
- ✅
--strict-watchautomatically 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)
- ✅
--verboseflag 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
Status: 🟡 Partially Complete
Add full support for Vue Single File Components (.vue files).
Current Behavior:
- ✅ Vue 3 Composition API support for
.ts/.tsxfiles - ✅ Vue components and composables detection
- ✅ Props and emits extraction from JSX/TSX
- ❌ Vue Single File Components (
.vuefiles) not supported
Planned Implementation:
- Parse
.vueSFC 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
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
Status: 🔴 Planned for v0.9.x
Add support for Python codebases (experimental).
Prerequisites:
- ✅ Conditional schema by language (v0.8.x development, v0.9.x stabilization)
- ✅ JS/JSX support (for multi-language feedback)
Planned Implementation:
- Parse Python AST using
astmodule - Extract function signatures, classes, and modules
- Extract type hints and docstrings
- Support popular frameworks (FastAPI, Django, Flask)
- Generate Python-specific contracts with
python:functionorpython:classkind - Use
languageSpecific.decoratorsfor framework decorators (e.g.,@app.get,@app.post)
Impact: Expands LogicStamp Context beyond JavaScript/TypeScript ecosystems.
Priority: Medium (Targeted for v0.9.x release candidate, depends on conditional schema stabilization)
Status: 🔴 Planned for v0.9.x
Add support for Java codebases (experimental).
Prerequisites:
- ✅ Conditional schema by language (v0.8.x development, v0.9.x stabilization)
- ✅ 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:classkind - Use
languageSpecific.annotationsfor framework annotations (e.g.,@RestController,@GetMapping) - Use
languageSpecific.classesandlanguageSpecific.methodsfor class/method extraction
Impact: Expands LogicStamp Context to enterprise Java codebases.
Priority: Medium (Targeted for v0.9.x release candidate, depends on conditional schema stabilization)
These are longer-term features and improvements planned for future releases.
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:<ref>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 comparecompares disk files vs freshly generated - ✅
stamp context compare --baseline git:maincompares 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 worktreefor 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:
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:
- 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.
Hash Behavior in Other Comparison Modes:
- 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
Why Hashes Are Still Needed:
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
The filtering only suppresses hash-only noise in git baseline mode—hashes still provide value when there are real structural changes.
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
Limitations:
- Only works with local refs (must
git fetchfirst for remote branches) - No caching yet (regenerates on every run)
Future Enhancements:
--fail-on-breakingflag forstamp context compare(exit non-zero on breaking changes)- Baseline caching when ref hasn't changed (optimization)
- Remote ref auto-fetch option
Impact: Enables meaningful drift detection against stable reference points, making CI integration straightforward.
Status: ✅ Complete in v0.7.2
Full contract comparison support for all contract fields, aligning compare command behavior with watch mode.
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
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
Impact: Compare command now provides comprehensive drift detection across all contract fields, matching watch mode capabilities for consistent behavior.
Status: 🔴 Planned for v0.8.x
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 thatstyleshouldn't exist on backend contracts⚠️ No validation thathooksshould be empty for backend contracts⚠️ No validation thatapiSignatureis 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 (v0.8.x):
1. TypeScript Discriminated Unions:
// 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<string, PropType>; // Required for React
emits: Record<string, EventType>; // 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/elseoroneOfpatterns based onkindpattern matching - Enforce that
styleonly exists for frontend contracts (react:*,vue:*) - Enforce that
nextjsonly exists for React contracts - Enforce that
apiSignatureis required for backend contracts (node:*,python:*,java:*) - Enforce that
hooksandcomponentsare empty arrays for backend contracts - Enforce that
propsandemitsare 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)
Why v0.8.x:
- Breaking change - Schema structure changes require migration, better to do in minor version series
- Prerequisite for Python/Java - Conditional schema must be in place before adding Python and Java support in v1.0.0
- Better timing - After gathering feedback from multi-language usage (JS/JSX support)
- Iterative development - v0.8.x allows for multiple releases to refine and stabilize the schema
- Migration support - Can provide proper migration tooling and documentation across v0.8.x releases
Dependencies:
- Must be completed before Python/Java support (v1.0.0)
- JS/JSX support should be completed first to gather multi-language feedback
Implementation Timeline:
- v0.8.x: Conditional schema development, testing, and refinement with migration support
- v0.9.x: Schema stabilization and finalization + Python/Java support (release candidate phase)
- v1.0.0: Stable release with multi-language support fully tested and validated
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 (Planned for v0.8.x, prerequisite for Python/Java support in v0.9.x)
Note: Conditional schema is planned for v0.8.x development series, with stabilization in v0.9.x release candidate phase. Python and Java support will be added in v0.9.x to allow testing alongside the schema before the stable v1.0.0 release.
- ✅ 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-styleflag 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-styleflag - Status: 🔴 Planned
- Custom profile configuration and overrides - User-defined profiles beyond preset options
- Additional output formats - More format options for different AI workflow patterns
- ✅ Normalized path display (v0.7.1) - Consistent relative path formatting across all commands
- ✅ Verbose output flag (v0.7.1) -
--verboseflag 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
For a complete list of current limitations with code evidence and detailed explanations, see docs/limitations.md.
Active Accuracy Issues:
- 🟡 Dynamic class expressions partially resolved (Phase 1 complete in v0.3.9, Phase 2 planned for advanced patterns)
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)
We welcome contributions! If you'd like to work on any of these roadmap items:
- Check CONTRIBUTING.md for guidelines
- Open an issue to discuss your approach
- Submit a pull request with your implementation
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/.jsxfile analysis - Complete Vue.js support - Add
.vueSFC file parsing - ✅ Watch mode - Automatic context regeneration on file changes (v0.4.1)
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