# project-type-keeper

> ProjectTypeKeeper is a type context management tool. It scans and organizes TypeScript interfaces, classes, enums, and backend entity definitions in the project to form an updatable type graph. When generating code or developing features, it provides accurate related types to ensure consistent naming and structure, reducing duplicate types and context gaps.

- Author: xielin
- Repository: HJ-uncle/project-type-keeper
- Version: 20260123112446
- Stars: 3
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/HJ-uncle/project-type-keeper
- Web: https://mule.run/skillshub/@@HJ-uncle/project-type-keeper~project-type-keeper:20260123112446

---

---
name: project-type-keeper
description: ProjectTypeKeeper is a type context management tool. It scans and organizes TypeScript interfaces, classes, enums, and backend entity definitions in the project to form an updatable type graph. When generating code or developing features, it provides accurate related types to ensure consistent naming and structure, reducing duplicate types and context gaps.
---

# Global Entity Management Skill (ProjectTypeKeeper)

[中文文档](./SKILL_CN.md)

Resolves issues of duplicate definitions, inconsistent naming, and structural gaps caused by missing type context in project development. This Skill organizes the project's type system (Entities, DTOs, Enums, Interfaces) into a retrievable dynamic knowledge base, ensuring consistency and accuracy in code generation.

## Workflows

### 1. Discovery & Search
**Trigger**: "Find User type" or "What is the structure of Order?"
- **Action**: The Agent executes `search.py` to query the type knowledge base.
- **Output**: Returns file paths, line numbers, and code snippets of matching types.

### 2. Integration & Reuse
**Trigger**: "Create OrderDTO reusing User definition"
- **Action**:
    1. Search for existing "User" types to understand the core entity structure.
    2. Generate new DTO code that aligns with existing field naming and types.
- **Benefit**: Ensures `userId` vs `user_id` consistency across the project.

### 3. Consistency Check
**Trigger**: "Check if ProductInventory exists"
- **Action**: Search for "ProductInventory" to prevent creating a duplicate class.
- **Benefit**: Reduces code redundancy.

## Supported Stacks

| Language | Framework/Lib | Recognition Pattern |
|----------|---------------|---------------------|
| **TypeScript** | Native, NestJS | `interface`, `type`, `@Entity class`, `@Schema class` |
| **Java** | Spring Boot | `@Entity`, `class`, `interface` |
| **Python** | Django, Flask, Pydantic | `models.Model`, `db.Model`, `BaseModel`, `@dataclass` |
| **Go** | Native | `type StructName struct`, `interface` |
| **Ruby** | Rails | `class < ApplicationRecord` |
| **PHP** | Laravel | `class extends Model` |

## Scripts

| Script | Purpose |
|--------|---------|
| `scripts/search.py` | **Entry Point**. CLI for querying the type index. Supports JSON output. |
| `scripts/core.py` | **Core Logic**. Implements BM25 ranking and caching mechanism. |
| `scripts/scanner.py` | **Scanner**. Parallel file scanning engine with regex pattern matching. |

## Type Priority Levels

| Level | Category | Criticality | Scope |
|-------|----------|-------------|-------|
| 1 | **Core Entities** | CRITICAL | Core business objects, database mapping (`@Entity`) |
| 2 | **Shared DTOs** | HIGH | Data Transfer Objects for cross-service/module interaction |
| 3 | **Global Enums** | HIGH | Global status codes, type definitions |
| 4 | **API Interfaces** | MEDIUM | Frontend API request/response definitions |
| 5 | **Utility Types** | LOW | Local utility types, helper generics |

## Quick Reference

### 1. Core Entities (CRITICAL)
- **Uniqueness**: Each business concept should have only one authoritative entity definition in the system.
- **Naming**: Use singular nouns, e.g., `User`, `ProductOrder`.
- **Fields**: Include complete comments, clarify `nullable` attributes.

### 2. Shared DTOs (HIGH)
- **Explicit Suffix**: Add suffixes based on usage, e.g., `CreateUserDTO`, `UserResponseVO`.
- **Flattening**: Minimize nesting for easier serialization.
- **Validation**: Include validation annotations like `@NotNull`, `@Size`.

## Configuration (.type-keeperrc)

Place this JSON file in your project root to control scanning behavior:

```json
{
  "scanPaths": [
    "src/types/**/*.ts",
    "backend/models/**/*.py"
  ],
  "ignorePatterns": [
    "**/tests/**",
    "**/generated/**"
  ]
}
```