Labels

Labels transform auto-generated identifiers into meaningful, human-readable names for communities and processes.

What are Labels?

When noodlbox analyzes your code, it automatically generates identifiers for communities and processes. Labels provide human-readable alternatives:

The Labels File

Labels are stored in .noodlbox/labels.json in your repository root:

{
  "version": "1.0",
  "repository": "owner/my-app",
  "generated_at": "2024-12-15T10:30:00Z",
  "communities": {
    "abc123": {
      "label": "Authentication System",
      "description": "Handles user login, token validation, and session management"
    },
    "def456": {
      "label": "Payment Processing",
      "description": "Processes payments, handles refunds, manages payment methods"
    }
  },
  "processes": {
    "proc_001": {
      "label": "User Login Flow",
      "description": "Validates credentials, creates session, returns auth token"
    },
    "proc_002": {
      "label": "Checkout Process",
      "description": "Validates cart, processes payment, creates order"
    }
  }
}

Creating Labels

Labels are created manually by adding a .noodlbox/labels.json file to your repository. Here's how to create effective labels:

Label Guidelines

Community Labels

Labels describe the module's purpose based on:

• Common theme in symbol names
• Domain/business function
• File path patterns (e.g., src/auth/ suggests "Authentication")

Examples:

• login, logout, validateToken → "Authentication System"
• processPayment, refund, chargeCard → "Payment Processing"
• User, Profile, updateAccount → "User Management"

Process Labels

Labels describe the execution flow based on:

• Entry point symbol name
• Terminal action (what the process achieves)
• Domain context

Examples:

• handleLogin → validateToken → createSession → "User Login Flow"
• addToCart → checkout → processPayment → "Order Checkout Process"
• sendEmail → formatTemplate → deliverMessage → "Email Notification Dispatch"

Where Labels are Used

CLI Commands

noodl list       # Shows community labels
noodl status     # Includes label statistics

MCP Resources

@noodlbox:map://owner/my-repo

Returns community labels instead of IDs in the overview.

Impact Analysis

The noodlbox_detect_impact MCP tool uses labels for:

• Process names in impact reports
• Community names in cross-module analysis

Editing Labels

Edit .noodlbox/labels.json to:

• Add labels for new communities/processes
• Update labels with domain-specific terminology
• Expand descriptions

{
  "communities": {
    "abc123": {
      "label": "OAuth 2.0 Authentication",
      "description": "Implements OAuth 2.0 flow with PKCE for mobile clients"
    }
  }
}

Best Practices

Label Naming

• Be specific: "User Authentication" > "Auth"
• Describe function: "Payment Processing" > "Payments Module"
• Use domain terms: Match terminology your team uses

Descriptions

• Summarize in one sentence
• Focus on what the code does, not how
• Include key responsibilities

Version Control

Commit .noodlbox/labels.json to your repository:

• Shared across team members
• Evolves with your codebase
• Documents architectural understanding

Related

• Communities - Understanding code communities
• Processes - Execution flow tracing
• Claude Code Plugin - Commands for working with labels