Skip to content

LogicStamp/logicstamp-context

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

63 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

LogicStamp Context

LogicStamp Fox Mascot

Version Beta License Node CI

A tiny CLI that compiles your React/TypeScript codebase into machine-readable context bundles for AI and CI. Fast, deterministic, zero-config.

Quick Start

npm install -g logicstamp-context
cd your-project
stamp context

That's it! LogicStamp Context will scan your project and generate context.json files organized by folder, plus a context_main.json index file. Share these files with AI assistants for instant codebase understanding.

Note: This is a beta release (v0.1.0). We're actively improving the tool based on user feedback. If you encounter any issues or have suggestions, please open an issue on GitHub.

What is this?

LogicStamp Context is a lightweight tool that scans your React/TypeScript codebase and generates structured context bundles optimized for AI tools like Claude, ChatGPT, and other LLMs.

No setup, no configuration, no pre-compilation required. Just point it at your code and get instant, AI-ready documentation.

Installation

npm install -g logicstamp-context

After installation, the stamp command will be available globally.

Note: "Global CLI" means the tool is installed globally on your system (via npm install -g), making the stamp command available from any directory in your terminal, not just within a specific project folder.

  • Local install: npm install logicstamp-context β†’ only available in that project
  • Global install: npm install -g logicstamp-context β†’ available everywhere via stamp command

What's New in v0.1.0

πŸŽ‰ Token Cost Optimization

  • Automatic token estimates for GPT-4o-mini and Claude
  • Mode comparison showing savings (none/header/full)
  • --compare-modes flag for detailed token analysis

πŸ” Multi-File Context Drift Detection

  • New compare command with multi-file support
  • Compares all context files using context_main.json as index
  • Detects ADDED folders, ORPHANED folders, per-folder DRIFT, and PASS status
  • Three-tier output: folder summary β†’ component summary β†’ detailed changes
  • --clean-orphaned flag to automatically remove stale context files
  • CI-friendly exit codes and per-folder token delta stats

βš›οΈ Next.js App Router Support

  • Detects 'use client' and 'use server' directives
  • Identifies files in Next.js App Router (/app directory)
  • Adds metadata to contracts for framework-aware analysis

βœ… Enhanced Component Detection

  • Fixed React component detection for HTML-only JSX
  • Improved dependency resolution (relative paths prioritized)
  • Better handling of cross-directory component references

πŸ›‘οΈ CI/CD Improvements

  • --strict-missing flag for dependency validation
  • Enhanced --stats output with mode estimates
  • JSON output optimized for CI parsing

Quick Start

# Install globally
npm i -g logicstamp-context

# Generate context.json (llm-chat profile)
stamp context

# Preview stats without writing files
stamp context --dry-run --stats

# Compare token costs across modes
stamp context --compare-modes

# Generate minimal API documentation
stamp context --include-code none --format pretty --out docs/api.json

# Compare all context files for drift (multi-file mode)
stamp context compare

# Auto-approve and update all drifted files (like jest -u)
stamp context compare --approve

# Compare with per-folder token stats
stamp context compare --stats

# Compare two specific context files
stamp context compare old.json new.json --stats

# Validate generated context
stamp context validate context.json

# Clean all context artifacts (dry run)
stamp context clean

# Actually delete all context files
stamp context clean --all --yes

Why? Generate AI-ready context from your React/TS codebase in seconds with built-in token cost optimization.

What does it generate?

LogicStamp Context analyzes your React components and outputs a structured JSON file containing:

  • Component structure: variables, hooks, components, functions
  • Logic signatures: props, events, state types
  • Dependency graph: how components relate to each other
  • Code snippets: headers or full source (configurable)
  • Semantic hashes: for tracking changes
  • Next.js metadata: App Router directives and file location (when applicable)

This output is designed to be easily understood by AI assistants, helping them provide better suggestions and understand your codebase architecture.

Next.js App Router Support

LogicStamp Context automatically detects and annotates Next.js App Router components:

Detected Features

  • 'use client' directive - Marks Client Components
  • 'use server' directive - Marks Server Actions
  • App Router location - Identifies files in /app directory

Example Contract Output

{
  "type": "UIFContract",
  "kind": "react:component",
  "entryId": "app/dashboard/page.tsx",
  "nextjs": {
    "directive": "client",
    "isInAppDir": true
  }
}

Benefits for AI Analysis

  • Framework-aware suggestions - AI knows which APIs are available (client vs server)
  • Better refactoring - AI understands boundaries between client/server code
  • Accurate recommendations - AI won't suggest client-only hooks in Server Components

Supported Scenarios

βœ… Client Components with 'use client' βœ… Server Actions with 'use server' βœ… Server Components in /app directory (no directive) βœ… Regular components outside /app (no metadata)

Note: The nextjs field is only added when relevant, keeping contracts clean for non-Next.js projects.

Usage

stamp --version                    # Show version number
stamp --help                       # Show help
stamp init [path] [options]
stamp context [path] [options]
stamp context compare <old.json> <new.json> [options]
stamp context validate [file] [options]
stamp context clean [path] [options]

Commands

  • stamp init [path] - Initialize LogicStamp in a project by creating or updating .gitignore with patterns for context files (context.json, context_*.json, .logicstamp/, etc.), generating LLM_CONTEXT.md in the project root, and saving preferences to .logicstamp/config.json. Optional - the stamp context command includes smart detection and will prompt you interactively on first run.

    See docs/cli/INIT.md for detailed documentation.

  • stamp context [path] - Scans a directory and writes AI-ready context files organized by folder. Generates multiple context.json files (one per folder containing components) plus a context_main.json index file at the output root. Shows token estimates and mode comparison in output. Automatically validates the generated context before writing. On first run (interactive mode), prompts to add .gitignore patterns and generate LLM_CONTEXT.md, saving your preferences - subsequent runs respect your choices.

    See docs/cli/CONTEXT.md for detailed documentation.

  • stamp context compare [options] - Compares all context files (multi-file mode) or two specific files to detect drift. In multi-file mode, uses context_main.json as index to compare all folder context files and detect ADDED/ORPHANED folders, per-folder DRIFT, and unchanged files (PASS). Shows three-tier output: folder summary, component summary, and detailed changes. Supports --approve for auto-updates (Jest-style), --clean-orphaned to remove stale files, and --stats for per-folder token deltas. Exits with code 1 if drift is detected (CI-friendly).

    See docs/cli/COMPARE.md for detailed documentation.

  • stamp context validate [file] - Checks an existing context file for schema and structural issues before sharing it with an AI or committing it to a repo. When no file is specified it looks for context.json in the current directory.

    See docs/cli/VALIDATE.md for detailed documentation.

  • stamp context clean [path] - Removes all generated context artifacts (context_main.json, all folder context.json files, and .logicstamp/ directory if present). Safe by default (dry run), requires --all --yes to actually delete. Useful for resetting context files or cleaning before switching branches.

    See docs/cli/CLEAN.md for detailed documentation.

Arguments & Options (init command)

  • [path] - Target directory to initialize (default: current directory)
  • --skip-gitignore - Skip .gitignore setup
  • --help, -h - Show help message

See docs/cli/INIT.md for detailed documentation.

Arguments (context command)

  • [path] - Directory to scan (default: current directory)

Options (context command)

Option Alias Description Default
--depth <n> -d Dependency traversal depth 1
--include-code <mode> -c Code inclusion: none|header|full header
--format <format> -f Output format: json|pretty|ndjson json
--out <file> -o Output directory or file path. If a .json file is specified, its directory is used as the output directory. Otherwise, the path is used as the output directory. context.json (creates output directory)
--max-nodes <n> -m Maximum nodes per bundle 100
--profile <profile> Profile preset (see below) llm-chat
--strict -s Fail on missing dependencies false
--strict-missing Exit with error code 1 if any missing dependencies found (CI-friendly) false
--predict-behavior Include experimental behavior predictions in contracts false
--dry-run Skip writing output; show on-screen summary only false
--stats Emit single-line JSON stats with token estimates (intended for CI) false
--compare-modes Show detailed token comparison table across modes (none/header/full) false
--skip-gitignore Skip .gitignore setup (never prompt or modify) false
--quiet -q Suppress verbose output (show only errors) false
--help -h Show help message

Options (compare command)

Option Description Default
--stats Show token count statistics and delta false
--approve Auto-approve updates (non-interactive, CI-safe) false
--clean-orphaned Auto-delete orphaned files with --approve false
--quiet -q Suppress verbose output (show only diffs)
--help, -h Show help message

Options (validate command)

  • [file] – Optional path to a generated context.json file to validate. Defaults to ./context.json. You can validate individual folder context files or the main index file.
  • --quiet | -q – Suppress verbose output (show only errors)
  • Exits with code 0 on success, 1 on invalid structure or read/parse errors.
  • Prints bundle counts, node totals, and highlights schema mismatches.

Profiles

Profiles are preset configurations optimized for different use cases:

llm-chat (default)

Balanced mode for AI chat interfaces

  • Depth: 1
  • Code: headers only
  • Max nodes: 100
  • Behavioral predictions: disabled by default (enable with --predict-behavior)

llm-safe

Conservative mode for token-limited contexts

  • Depth: 1
  • Code: headers only
  • Max nodes: 30
  • Behavioral predictions: disabled by default (enable with --predict-behavior)

ci-strict

Strict validation mode for CI/CD

  • Code: none
  • Strict dependencies enabled
  • Behavioral predictions: not applicable (metadata-only mode)

Behavioral Predictions

The --predict-behavior flag enables experimental behavioral analysis that adds predicted component behaviors to the contract output. These predictions include:

  • Form validation patterns
  • Side effect management (useEffect)
  • Data fetching/mutation patterns
  • Memoization usage
  • Context consumption
  • Ref usage for DOM access
  • Loading/error state handling

Note: Behavioral predictions are disabled by default in all profiles to minimize token usage. Enable them explicitly when you need richer semantic information about component behavior.

Example:

# Enable predictions with the default profile
stamp context --predict-behavior

# Enable predictions with a specific profile
stamp context --profile llm-safe --predict-behavior

Token Optimization

LogicStamp Context includes built-in token cost analysis and optimization features:

Automatic Token Estimates

Every context generation shows token costs for both GPT-4o-mini and Claude:

πŸ“ Token Estimates (header mode):
   GPT-4o-mini: 13,895 | Full code: ~39,141 (~65% savings)
   Claude:      12,351 | Full code: ~34,792 (~65% savings)

πŸ“Š Mode Comparison:
   none:       ~8,337 tokens
   header:     ~13,895 tokens
   full:       ~39,141 tokens

This helps you:

  • Understand costs at a glance
  • Choose the right mode for your budget
  • See savings compared to including full source code

Mode Comparison Table

Use --compare-modes for a detailed comparison:

stamp context --compare-modes

Output:

πŸ“Š Mode Comparison

Mode     | Tokens GPT-4o | Tokens Claude | Savings vs Full
---------|---------------|---------------|------------------
none     |         8,337 |         7,411 | 79%
header   |        13,895 |        12,351 | 65%
full     |        39,141 |        34,792 | 0%

When to use each mode:

  • none - API documentation, CI validation (no code snippets)
  • header - AI chat, code review (JSDoc headers + contracts)
  • full - Deep analysis, debugging (complete source code)

Stats for CI/CD

Use --stats to get machine-readable token data:

stamp context --stats

Output JSON includes:

{
  "tokensGPT4": 13895,
  "tokensClaude": 12351,
  "modeEstimates": {
    "none": {"gpt4": 8337, "claude": 7411},
    "header": {"gpt4": 13895, "claude": 12351},
    "full": {"gpt4": 39141, "claude": 34792}
  },
  "savingsGPT4": "65",
  "savingsClaude": "65"
}

Context Drift Detection

The compare command helps you track changes between context versions:

Basic Comparison

stamp context compare old.json new.json

Output:

βœ… PASS

# or if changes detected:

⚠️  DRIFT

Added components: 2
  + src/components/NewButton.tsx
  + src/utils/helpers.ts

Removed components: 1
  - src/components/OldButton.tsx

Changed components: 3
  ~ src/components/Card.tsx
    Ξ” imports, hooks
  ~ src/App.tsx
    Ξ” hash

With Token Stats

stamp context compare old.json new.json --stats

Shows token cost changes:

Token Stats:
  Old: 8,484 (GPT-4o-mini) | 7,542 (Claude)
  New: 9,125 (GPT-4o-mini) | 8,111 (Claude)
  Ξ” +641 (+7.56%)

Exit Codes

  • 0 - No drift (PASS)
  • 1 - Drift detected or error

Perfect for CI/CD validation:

# In your CI pipeline
stamp context compare base.json pr.json || echo "Context drift detected!"

Examples

Basic usage

# Generate context for entire project
stamp context

# CLI output:
# πŸ” Scanning /path/to/project...
# βš™οΈ  Analyzing components...
# πŸ”— Building dependency graph...
# πŸ“¦ Generating context...
# πŸ” Validating generated context...
# βœ… Validation passed
# πŸ“ Writing context files for 5 folders...
#    βœ“ context.json (2 bundles)
#    βœ“ src/context.json (3 bundles)
#    βœ“ src/components/context.json (5 bundles)
#    βœ“ src/utils/context.json (2 bundles)
#    βœ“ app/context.json (3 bundles)
# πŸ“ Writing main context index...
#    βœ“ context_main.json (index of 5 folders)
# βœ… 6 context files written successfully
#
# πŸ“Š Summary:
#    Total components: 15
#    Root components: 3
#    ...

Focused analysis

# Analyze only the src directory
stamp context ./src

# Analyze with custom output directory
stamp context --out ./output

# Or specify a .json file to use its directory
stamp context --out ./output/context.json  # Uses ./output as directory

Deep traversal

# Include 2 levels of dependencies
stamp context --depth 2

# Include full source code
stamp context --include-code full

Token cost analysis

# Show detailed mode comparison
stamp context --compare-modes

# Get JSON stats for CI
stamp context --stats

# See token costs for specific mode
stamp context --include-code none
stamp context --include-code full

Context comparison

# Basic drift detection
stamp context compare old.json new.json

# With token delta stats
stamp context compare base.json pr.json --stats

# In CI pipeline
stamp context compare base.json pr.json || exit 1

Clean context files

# Show what would be removed (dry run)
stamp context clean

# Actually delete all context artifacts
stamp context clean --all --yes

# Clean specific directory
stamp context clean ./output --all --yes

# Suppress verbose output (quiet mode)
stamp context --quiet
stamp context validate --quiet
stamp context compare --quiet
stamp context clean --all --yes --quiet

# Show version number
stamp --version

CI/CD validation

# Use llm-safe profile for smaller output
stamp context --profile llm-safe --out safe-context.json

# Strict mode: fail if any dependencies missing
stamp context --strict-missing

# Generate stats for CI monitoring
stamp context --stats > stats.json

# Validate generated context
stamp context validate context.json

Output Format

LogicStamp Context generates a folder-organized, multi-file output structure that maintains your project's directory hierarchy:

File Structure

The tool writes multiple context.json files, one per folder containing components, plus a context_main.json index file at the output root:

output/
β”œβ”€β”€ context_main.json          # Main index with folder metadata
β”œβ”€β”€ context.json               # Root folder bundles (if any)
β”œβ”€β”€ src/
β”‚   └── context.json          # Bundles from src/ folder
β”œβ”€β”€ src/components/
β”‚   └── context.json          # Bundles from src/components/
└── src/utils/
    └── context.json          # Bundles from src/utils/

Folder-Based Organization

Each folder's context.json contains bundles for components in that folder. This organization:

  • Matches your project structure - Easy to locate context for specific directories
  • Enables incremental updates - Only regenerate context for changed folders
  • Improves AI context loading - Load only relevant folder contexts
  • Maintains relative paths - Folder structure mirrors your project layout

Main Index File (context_main.json)

The context_main.json file serves as a directory index with:

{
  "type": "LogicStampIndex",
  "schemaVersion": "0.1",
  "projectRoot": ".",
  "projectRootResolved": "/absolute/path/to/project",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "summary": {
    "totalComponents": 42,
    "totalBundles": 15,
    "totalFolders": 5,
    "totalTokenEstimate": 13895
  },
  "folders": [
    {
      "path": "src/components",
      "contextFile": "src/components/context.json",
      "bundles": 3,
      "components": ["Button.tsx", "Card.tsx", "Modal.tsx"],
      "isRoot": false,
      "tokenEstimate": 5234
    },
    {
      "path": ".",
      "contextFile": "context.json",
      "bundles": 2,
      "components": ["App.tsx"],
      "isRoot": true,
      "rootLabel": "Project Root",
      "tokenEstimate": 2134
    }
  ],
  "meta": {
    "source": "logicstamp-context@0.1.0"
  }
}

Key fields in folder entries:

  • path - Relative path from project root
  • contextFile - Path to the folder's context.json file
  • bundles - Number of bundles in this folder
  • components - List of component files in this folder
  • isRoot - Whether this folder is an application entry point
  • rootLabel - Human-readable label for root folders (e.g., "Next.js App", "Project Root")
  • tokenEstimate - Estimated token count for this folder's context

Bundle Structure

Each folder's context.json contains an array of bundles (one bundle per entry point). Each bundle represents a root component plus its complete dependency graph, with all related components and their contracts included within that bundle. This per-root bundle design is optimized for how developers and LLMs workβ€”when you need help with a specific page or feature, the root bundle contains everything related to that feature in one self-contained unit.

πŸ“‹ Full Schema Reference: See schema/logicstamp.context.schema.json for the complete JSON Schema definition.

Example: src/components/context.json

[
  {
    "$schema": "https://logicstamp.dev/schemas/context/v0.1.json",
    "position": "1/3",
    "type": "LogicStampBundle",
    "schemaVersion": "0.1",
    "entryId": "src/components/Button.tsx",
    "depth": 1,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "bundleHash": "uifb:abc123...",
    "graph": {
      "nodes": [
        {
          "entryId": "src/components/Button.tsx",
          "contract": {
            "type": "UIFContract",
            "schemaVersion": "0.3",
            "kind": "react:component",
            "description": "Button - Interactive component",
            "version": {
              "variables": ["variant", "size"],
              "hooks": ["useState"],
              "components": [],
              "functions": ["handleClick"]
            },
            "logicSignature": {
              "props": {
                "onClick": { "type": "function", "signature": "() => void" },
                "variant": { "type": "literal-union", "literals": ["primary", "secondary"] }
              },
              "events": {},
              "state": {}
            },
            "nextjs": {
              "directive": "client",
              "isInAppDir": true
            }
          }
        }
      ],
      "edges": []
    },
    "meta": {
      "missing": [],
      "source": "logicstamp-context@0.1.0"
    }
  }
]

πŸ“‹ Full Schema Reference: See schema/logicstamp.context.schema.json for the complete JSON Schema definition.

Understanding the Meta Field

The meta section provides metadata about bundle generation and dependency resolution:

missing Array

Tracks dependencies that couldn't be resolved during analysis. An empty array [] means all dependencies were successfully found.

When dependencies are missing, each entry contains:

  • name - The import specifier that couldn't be resolved (e.g., "./MissingComponent")
  • reason - Why it couldn't be found (e.g., "file not found", "external package")
  • referencedBy - The component that tried to import it

Example with missing dependencies:

{
  "meta": {
    "missing": [
      {
        "name": "./components/DeletedComponent",
        "reason": "file not found",
        "referencedBy": "src/App.tsx"
      },
      {
        "name": "@external/ui-lib",
        "reason": "external package",
        "referencedBy": "src/components/Button.tsx"
      }
    ],
    "source": "logicstamp-context@0.1.0"
  }
}

Common reasons for missing dependencies:

  • file not found - Referenced file doesn't exist (deleted or moved)
  • external package - Third-party npm package (intentionally excluded)
  • outside scan path - File exists but outside the specified scan directory
  • circular dependency - Circular import detected and skipped
  • max depth exceeded - Dependency beyond --depth limit

Using --strict-missing for CI/CD:

# Exit with error code 1 if ANY missing dependencies found
stamp context --strict-missing

# Perfect for CI validation
stamp context --strict-missing || exit 1

source Field

Identifies the generator and version (e.g., "logicstamp-context@0.1.0"). Useful for:

  • Debugging context generation issues
  • Ensuring compatibility with consuming tools
  • Tracking which version generated historical contexts

Use Cases

AI-Assisted Development

Share context with Claude or ChatGPT to get:

  • Architecture suggestions
  • Refactoring recommendations
  • Bug fixes based on full component understanding

Documentation

Generate up-to-date component documentation automatically:

  • API contracts
  • Dependency trees
  • Component relationships

Code Review

Quickly understand component structure and dependencies:

  • Identify circular dependencies
  • Find unused components
  • Track component complexity

Troubleshooting

Handling Missing Dependencies

If your generated context shows missing dependencies in the meta.missing array:

1. External Packages (Expected)

{
  "name": "@mui/material",
  "reason": "external package"
}

Solution: This is normal. LogicStamp only analyzes your source code, not node_modules. External packages are intentionally excluded.

2. File Not Found (Action Required)

{
  "name": "./components/OldButton",
  "reason": "file not found",
  "referencedBy": "src/App.tsx"
}

Solutions:

  • Check if the file was deleted or moved
  • Update the import path in the referencing component
  • Use --strict-missing in CI to catch these issues early

3. Outside Scan Path

{
  "name": "../../shared/utils",
  "reason": "outside scan path"
}

Solutions:

  • Expand your scan path: stamp context ../ (parent directory)
  • Or scan from project root: stamp context . (from root)

4. Max Depth Exceeded

{
  "name": "./deeply/nested/component",
  "reason": "max depth exceeded"
}

Solutions:

  • Increase depth: stamp context --depth 2 or --depth 3
  • Note: Higher depth = more tokens consumed

5. Circular Dependencies

{
  "name": "./ComponentA",
  "reason": "circular dependency"
}

Solutions:

  • Refactor to break the circular import
  • Extract shared logic to a separate module
  • This is a code smell that should be addressed

Common Issues

Q: Why is my context.json huge?

  • Use --include-code none to exclude all source code (smallest)
  • Use --include-code header (default) for balanced output
  • Use --profile llm-safe for token-constrained scenarios
  • Check --compare-modes to see token savings

Q: Validation failed - what went wrong?

stamp context validate context.json
# Or validate the main index
stamp context validate context_main.json
  • Check for schema mismatches (outdated schema version)
  • Verify JSON is well-formed (no trailing commas, proper escaping)
  • Ensure all required fields are present
  • Each folder's context.json should be a valid bundle array
  • The context_main.json should have the LogicStampIndex structure

Q: How do I ignore certain directories?

  • LogicStamp respects .gitignore automatically
  • node_modules/ and common build directories are excluded by default
  • Scan specific directories: stamp context ./src

How it Works

  1. Scan: Finds all .ts and .tsx files in your project
  2. Analyze: Parses React components using TypeScript AST
  3. Extract: Builds component contracts with structure and signatures
  4. Graph: Creates dependency graph showing relationships
  5. Bundle: Packages context bundles optimized for AI consumption
  6. Organize: Groups bundles by folder and writes context.json files maintaining directory structure
  7. Index: Creates context_main.json index with folder metadata and summary statistics

All in one command, no pre-compilation needed!

Planned Orchestrator (@logicstamp/cli)

logicstamp-context is the primary CLI available today. A higher-level orchestrator package @logicstamp/cli is planned as an optional wrapper.

Feature logicstamp-context LogicStamp Orchestrator (planned)
Standalone βœ… Yes ❌ No (wraps underlying tools)
Pre-compilation required ❌ No βœ… Yes (for verification)
Context generation βœ… Yes βœ… Yes
UIF contracts per file βœ… Yes (embedded in bundles) βœ… Yes (as .uif.json sidecar files)
Contract compilation βœ… Built-in βœ… Separate command
Contract verification ❌ No βœ… Yes (planned)
Size Focused Orchestrator

TL;DR: Use stamp context (logicstamp-context) for AI context generation today. The future @logicstamp/cli orchestrator will provide optional higher-level workflows once it's released.

Future Roadmap

Next.js Enhancements (Planned)

The current Next.js support (v0.1) provides foundational directive and App Router detection. Future versions may include:

App Router Advanced Features

  • role detection - Identify page, layout, route, loading, error files
  • segmentPath extraction - Capture dynamic route segments (e.g., [id], [...slug])
  • Route dependency graph - Map App Router file relationships
  • Metadata exports - Detect generateMetadata, generateStaticParams

Server Actions & RPC

  • Server Action signature extraction from 'use server' blocks
  • Form action detection and validation
  • RPC call graph (client β†’ server action relationships)

Streaming & Suspense

  • Suspense boundary detection
  • Streaming component identification
  • Loading states and error boundaries

Example Future Contract

{
  "nextjs": {
    "directive": "client",
    "isInAppDir": true,
    "role": "page",
    "segmentPath": "dashboard/[userId]",
    "hasMetadata": true
  }
}

Note: These features will be added incrementally based on community feedback and real-world usage patterns. The current implementation prioritizes the 80/20 rule - maximum value with minimal complexity.

Other Planned Features

  • Vue.js Support - Extend to Vue 3 Composition API components
  • Svelte Support - Component analysis for Svelte files
  • Custom Contract Fields - User-defined metadata via config
  • Performance Metrics - Bundle size and render performance estimates

Requirements

  • Node.js >= 18.0.0
  • TypeScript/React codebase

License

MIT

Contributing

Issues and PRs welcome! This is an open-source project.

See CONTRIBUTING.md for detailed guidelines, including:

  • Branching strategy (feature β†’ main, no develop branch)
  • Branch naming conventions (feature/*, fix/*, docs/*)
  • Commit message format (Conventional Commits)
  • Development workflow and best practices

Links

#TEST: CI Workflow

About

Resources

License

Contributing

Security policy

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published