logicstamp-context

logicstamp-context

Structured context for AI coding assistants. Deterministic component contracts from TypeScript.

Stars: 55

Visit
 screenshot

LogicStamp Context is a static analyzer that extracts deterministic component contracts from TypeScript codebases, providing structured architectural context for AI coding assistants. It helps AI assistants understand architecture by extracting props, hooks, and dependencies without implementation noise. The tool works with React, Next.js, Vue, Express, and NestJS, and is compatible with various AI assistants like Claude, Cursor, and MCP agents. It offers features like watch mode for real-time updates, breaking change detection, and dependency graph creation. LogicStamp Context is a security-first tool that protects sensitive data, runs locally, and is non-opinionated about architectural decisions.

README:

LogicStamp

Structured context for AI coding assistants.

Make AI coding assistants understand your architecture, not just your code.
Extract deterministic component contracts from your TypeScript codebase.

Supports: React Β· Next.js Β· Vue (TS/TSX) Β· Express Β· NestJS

Works with Claude, Cursor, Copilot Chat, and any MCP-compatible agent.


LogicStamp Fox Mascot

Version Beta License Node CI


LogicStamp Context is a static analyzer that extracts deterministic component contracts from TypeScript codebases - giving AI assistants structured architectural context instead of raw source code.

πŸ“‘ Table of Contents

The Problem

AI coding assistants read your source code, but they don't understand it structurally. They hallucinate props that don't exist, miss dependencies, and can't tell when a breaking change affects downstream components.

For example: your Button component accepts variant and disabled - but the AI suggests isLoading because it saw that pattern elsewhere. No structured contract means no source of truth.

LogicStamp Context is a static analyzer that extracts deterministic component contracts from TypeScript - giving AI assistants structured architectural context instead of raw source code.

These contracts:

  • Stay in sync with your code (watch mode auto-regenerates)
  • Expose what matters (props, hooks, dependencies) without implementation noise
  • Work with any MCP-compatible AI assistant (Claude, Cursor, etc.)

LogicStamp MCP Workflow Context bundles generated and consumed across MCP-powered AI workflows.

Same code β‡’ same context output. Diff outputs to detect architectural drift.

TypeScript Code  β†’  AST Parsing  β†’  Deterministic Contracts  β†’  AI Assistant
   (.ts/.tsx)        (ts-morph)      (context.json bundles)      (Claude, Cursor)

Quick Start

Try it in 30 seconds (no install required):

npx logicstamp-context context

Scans your repo and writes context.json files + context_main.json for AI tools.

What you get:

  • πŸ“ 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):

npm install -g logicstamp-context
stamp init        # sets up .gitignore, scans for secrets
stamp context

ℹ️ Note: With npx, run npx logicstamp-context context. After global install, use stamp context.

πŸ“‹ For detailed setup instructions, see the Getting Started Guide.

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

What "Structured" Means

Instead of shipping raw source code to AI:

// Raw: AI must parse and infer
export const Button = ({ variant = 'primary', disabled, onClick, children }) => {
  const [isHovered, setIsHovered] = useState(false);
  // ... 150 more lines of implementation
}

LogicStamp Context generates:

{
  "kind": "react:component",
  "interface": {
    "props": {
      "variant": { "type": "literal-union", "literals": ["primary", "secondary"] },
      "disabled": { "type": "boolean" },
      "onClick": { "type": "function", "signature": "() => void" }
    }
  },
  "composition": { "hooks": ["useState"], "components": ["./Icon"] }
}

Pre-parsed. Categorized. Stable. The AI reads contracts, not implementations.

⚑ Features

Core:

  • Deterministic contracts - Same input = same output, auditable in version control
  • Watch mode - Auto-regenerate on file changes with incremental rebuilds
  • Breaking change detection - Strict watch mode catches removed props, events, functions in real-time
  • MCP-ready - AI agents consume context via standardized MCP interface

Analysis:

  • React/Next.js/Vue component extraction (props, hooks, state, deps)
  • Backend API extraction (Express.js, NestJS routes and controllers)
  • Dependency graphs (handles circular dependencies)
  • Style metadata extraction (Tailwind, SCSS, MUI, shadcn)
  • Next.js App Router detection (client/server, layouts, pages)

Developer experience:

  • Per-folder bundles matching your project structure
  • Accurate token estimates (GPT/Claude)
  • Security-first: automatic secret detection and sanitization
  • Zero config required - sensible defaults, works out of the box

Watch Mode

For development, run watch mode to keep context fresh as you code:

stamp context --watch                  # regenerate on changes
stamp context --watch --strict-watch   # also detect breaking changes

Strict watch catches breaking changes that affect consumers:

Violation Example
breaking_change_prop_removed Removed disabled prop from Button
breaking_change_event_removed Removed onSubmit callback
breaking_change_function_removed Deleted exported formatDate()
contract_removed Deleted entire component

One-time Comparison

Compare regenerated context against existing files:

stamp context compare            # detect changes
stamp context compare --approve  # update (like jest -u)

Useful for reviewing changes before committing or validating context is up-to-date.

⚠️ Note: Context files are gitignored by default. For CI-based drift detection, the --baseline git:<ref> option (e.g., --baseline git:main) is not yet implemented. Until automation is available, use the manual workflow: generate context from current code, checkout baseline branch, generate context from baseline, then compare. See the roadmap for planned automation.

How it Works

  1. Scan - Finds all .ts and .tsx files in your project
  2. Analyze - Parses components and APIs using TypeScript AST (Abstract Syntax Tree) via ts-morph
  3. Extract - Builds contracts with props, hooks, state, signatures
  4. Graph - Creates dependency graph showing relationships
  5. Bundle - Packages context optimized for AI workflows
  6. Organize - Groups by folder, writes context.json files
  7. Index - Creates context_main.json with metadata and statistics

Why AST parsing matters: Unlike text-based parsing (regex, string matching), AST parsing understands TypeScript's syntax structure, type information, and code semantics. This enables LogicStamp Context to accurately extract prop types, detect hooks, understand component composition, and handle complex patterns reliably - making contracts deterministic and trustworthy.

No pre-compilation needed. One command.

πŸ’‘Tip: Use stamp context for basic contracts. Use stamp context style when you need style metadata (Tailwind classes, SCSS selectors, layout patterns).

πŸ“‹ What LogicStamp Context Is (and Isn't)

LogicStamp Context IS:

βœ… An AST-based static analysis tool - Uses the TypeScript compiler API (via ts-morph) to extract component contracts, props, hooks, and dependencies in a deterministic, type-aware way.

βœ… A deterministic context generator - Produces structured architectural contract bundles for tooling and AI workflows.

βœ… Local and offline-first - Runs entirely on your machine (no cloud services, no network calls).

βœ… Framework-aware - Understands React, Next.js, Vue, Express, and NestJS patterns and extracts relevant metadata.

βœ… Non-opinionated - Describes what exists without enforcing patterns or architectural decisions.

LogicStamp Context IS NOT:

❌ A code generator - It never writes or modifies your source code.

❌ A documentation generator - It produces structured contracts, not documentation.

❌ A build or runtime tool - It analyzes static source code only; it does not execute or bundle your application.

❌ A linter, formatter, or testing framework - It does not check code quality or run tests.

❌ An AI behavior controller - It provides structured context; it does not alter AI responses.

❌ A replacement for reading code - It accelerates understanding without replacing engineering judgment.

MCP Server

For AI assistants with MCP support (Claude Desktop, Cursor, etc.):

npm install -g logicstamp-mcp

Then configure your AI assistant to use the LogicStamp MCP Server.

πŸ“‹ See MCP Getting Started Guide for setup instructions.

Example Output

LogicStamp Context generates structured JSON bundles organized by folder:

{
  "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 for complete format documentation.

Installation

npm install -g logicstamp-context

After installation, the stamp command is available globally.

Security

Automatic Secret Protection

LogicStamp Context protects sensitive data in generated context:

  • Security scanning by default - stamp init scans for secrets (API keys, passwords, tokens)
  • Automatic sanitization - Detected secrets replaced with "PRIVATE_DATA" in output
  • Manual exclusions - Use stamp ignore <file> to exclude files via .stampignore
  • Safe by default - Only metadata included. Credentials only appear in --include-code full mode

⚠️ Seeing "PRIVATE_DATA" in output? Review stamp_security_report.json, remove hardcoded secrets from source, use environment variables instead.

πŸ”’ See SECURITY.md for complete security documentation.

Usage

πŸ’» CLI Usage Reference
stamp --version                    # Show version
stamp --help                       # Show help
stamp init [path]                  # Initialize project (security scan by default)
stamp ignore <path>                # Add to .stampignore
stamp context [path]               # Generate context bundles
stamp context style [path]         # Generate with style metadata
stamp context --watch              # Watch mode
stamp context --watch --strict-watch  # Watch with breaking change detection
stamp context compare              # Detect changes vs existing context
stamp context validate [file]      # Validate context files
stamp context clean [path]         # Remove generated files

Common Options

Option Description
--depth <n> Dependency traversal depth (default: 2)
--include-code <mode> Code inclusion: none|header|full (default: header)
--include-style Extract style metadata (Tailwind, SCSS, animations)
--format <fmt> Output format: json|pretty|ndjson|toon (default: json)
--max-nodes <n> Maximum nodes per bundle (default: 100)
--profile <p> Preset: llm-chat, llm-safe, ci-strict, watch-fast
--compare-modes Show token cost comparison across all modes
--stats Emit JSON stats with token estimates
--out <path> Output directory
--quiet Suppress verbose output
--strict-missing Exit with error if any missing dependencies found (CI-friendly)
--debug Show detailed hash info (watch mode)
--log-file Write change logs to .logicstamp/ (watch mode)

πŸ“‹ See docs/cli/commands.md for complete reference.

Framework Support

Framework Support Level What's Extracted
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
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)

ℹ️ Note: LogicStamp Context analyzes .ts and .tsx files only. JavaScript files are not analyzed.

Documentation

Full documentation at logicstamp.dev/docs

Known Limitations

LogicStamp Context is in beta. Some edge cases are not fully supported.

πŸ“‹ See docs/limitations.md for the full list.

Requirements

  • Node.js >= 18.18.0 (Node 20+ recommended)
  • TypeScript codebase (React, Next.js, Vue (TS/TSX), Express, or NestJS)

Need Help?

License

MIT


Branding & Attribution

The LogicStamp Fox mascot and related brand assets are Β© 2025 Amit Levi. These assets may not be used for third-party branding without permission.

Contributing

Issues and PRs welcome! See CONTRIBUTING.md for guidelines.

This project follows a Code of Conduct.

Links: Website Β· GitHub Β· MCP Server Β· Changelog

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for logicstamp-context

Similar Open Source Tools

For similar tasks

For similar jobs