[Feature]: Introduce a Unique PR Identity & Smart Labeling System

[Rishiraj-Pathak-27]

Problem Description

Currently, PR labels and titles are not fully standardized, making it difficult to quickly identify:

PR type
Related module
Review complexity
Feature vs bug fix
Ownership and tracking

As the repository grows, this can reduce review efficiency and make PR management harder.

Proposed Solution

Introduce a unique PR identity and smart labeling system for all pull requests.

Suggested PR Title Format

[KDM-MODULE-TYPE-ID] Short Description

Examples

[KDM-CONFIG-FIX-106] Add reconfiguration detection
[KDM-UI-FEAT-120] Improve onboarding flow
[KDM-LOGGER-REFACTOR-112] Replace console.error with logger

---

Suggested Module Prefixes

Module | Prefix -- | -- Config | CONFIG CLI | CLI UI | UI Auth | AUTH Logger | LOGGER Tests | TEST Docs | DOCS

---

Additional Improvements

Auto-labeling using GitHub Actions

Example:

FIX → auto apply 🐞 bug-fix
FEAT → auto apply ✨ feature

Review Complexity Labels

🟢 easy-review
🟡 medium-review
🔴 complex-review

PR Size Labels

Automatically assign:

XS / S / M / L / XL

based on lines changed.

---

Benefits

• Gives every PR a unique identity
• Improves repository organization
• Makes reviews faster and cleaner
• Easier filtering and searching
• Better scalability for contributors and maintainers
• Creates a more professional open-source workflow

---

Expected Outcome

A cleaner, scalable, and visually organized PR workflow with standardized naming and smart labels across the repository.

Alternatives Considered

No response

Additional Context

No response

Would you like to work on this feature?

• Yes, I would like to work on this feature!

[utkarsh232005]

@Rishiraj-Pathak-27 thankyou so much for creating this it will help to maintain the future prs organized and can be more easy to review for the maintainers

[utkarsh232005]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Summary

• Extend the existing pr-labeler.cjs script rather than creating new workflows, maintaining the established automation pattern
• Centralize all label definitions and thresholds in kdm-automation.json for single-source-of-truth configuration
• Detect modules automatically via file paths rather than requiring strict title format compliance, reducing contributor friction
• Use a composite heuristic for complexity that considers files, lines, and module spread to give reviewers actionable guidance

Design Choices

Design Choice 1: PR Size Thresholds

Options Considered:

1. Conservative thresholds: XS (<10), S (<50), M (<200), L (<500), XL (500+)
2. Aggressive thresholds: XS (<25), S (<100), M (<250), L (<500), XL (500+)

Chosen Option: 1

Rationale: Conservative thresholds align with common open-source conventions and encourage smaller, reviewable PRs.

Design Choice 2: Review Complexity Calculation

Options Considered:

1. Base complexity on total lines changed (simple proxy)
2. Base complexity on number of files changed combined with line count
3. Base complexity on modules touched (multi-module = complex)

Chosen Option: 2

Rationale: Combining file count with line count provides a more accurate complexity signal—many small files across modules indicates higher cognitive load than one large file.

Design Choice 3: Module Detection Strategy

Options Considered:

1. Parse module from PR title only (requires contributors to follow format)
2. Detect module from file paths only (automatic, no title requirement)
3. Hybrid: prefer title if present, fallback to file path detection

Chosen Option: 2

Rationale: File path detection is fully automatic and doesn't require contributor compliance. Title format remains a recommendation, not a requirement.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Extend Label Configuration

Define all new label categories in the central automation config so they are available to scripts and documented in one place.

Task 1: Add PR Label Categories to Automation Config

Add new label category definitions to .github/kdm-automation.json covering type, size, module, and complexity labels.

• Add a prLabels object with four sub-categories: type, size, module, and complexity
• Type labels: type: bug-fix (for FIX), type: feature (for FEAT), type: refactor (for REFACTOR)
• Size labels: size: XS, size: S, size: M, size: L, size: XL with threshold values
• Module labels: module: config, module: cli, module: ui, module: auth, module: logger, module: test, module: docs, plus additional modules for docker, k8s, minikube, monitor to match the actual codebase structure
• Complexity labels: review: easy, review: medium, review: complex with calculation thresholds

Task 2: Define Module-to-Path Mappings

Add file path patterns to module mappings in the config to enable automatic module detection.

• Create a modulePaths mapping object within the new prLabels section
• Map src/commands/** → CLI, src/ui/** → UI, src/utils/config.ts → CONFIG, src/utils/logger.ts → LOGGER
• Map src/__tests__/** → TEST, docs/** → DOCS
• Map src/docker/** → DOCKER, src/kubernetes/** → K8S, src/minikube/** → MINIKUBE, src/monitor/** → MONITOR
• Map src/utils/version-check.ts and remaining src/ files to a fallback or CLI module

🤖 Prompt for AI agents

Extend `.github/kdm-automation.json` to include all new PR label category
definitions and module-to-path mappings.

- Add a top-level `prLabels` object with four sub-categories:
- `type`: Define entries for `type: bug-fix` (maps to FIX), `type: feature`
(maps to FEAT), and `type: refactor` (maps to REFACTOR)
- `size`: Define entries for `size: XS`, `size: S`, `size: M`, `size: L`, `size:
XL`, each with their respective line-change threshold values (XS <10, S <50, M
<200, L <500, XL ≥500)
- `module`: Define entries for `module: config`, `module: cli`, `module: ui`,
`module: auth`, `module: logger`, `module: test`, `module: docs`, `module:
docker`, `module: k8s`, `module: minikube`, `module: monitor`
- `complexity`: Define entries for `review: easy`, `review: medium`, `review:
complex` with their respective calculation thresholds (easy <15, medium <40,
complex ≥40)
- Within `prLabels`, also add a `modulePaths` mapping object:
  - `src/commands/**` → CLI
  - `src/ui/**` → UI
  - `src/utils/config.ts` → CONFIG
  - `src/utils/logger.ts` → LOGGER
  - `src/__tests__/**` → TEST
  - `docs/**` → DOCS
  - `src/docker/**` → DOCKER
  - `src/kubernetes/**` → K8S
  - `src/minikube/**` → MINIKUBE
  - `src/monitor/**` → MONITOR
- `src/utils/version-check.ts` and remaining `src/` files → fallback or CLI
module

Phase 2: Implement Smart PR Labeling Logic

Extend the existing labeler script to parse title, calculate size, detect modules, and compute complexity.

Task 1: Add Title-Based Type Label Detection

Extend .github/scripts/pr-labeler.cjs to parse the PR title and apply type labels.

• Read context.payload.pull_request.title from the event payload
• Match TYPE keyword from title using pattern matching (e.g., contains -FIX- or starts with fix: or fix()
• Support flexible detection: match [KDM-...-FIX-...], conventional commits (fix:, feat:), or plain keywords
• Map detected type to corresponding label: FIX → type: bug-fix, FEAT → type: feature, REFACTOR → type: refactor
• Add matched type label to the labelsToAdd Set

Task 2: Implement Size-Based Labeling

Add logic to calculate PR size and apply appropriate size label.

• Use github.rest.pulls.get to fetch PR-level additions and deletions totals (more accurate than summing files, handles >100 files)
• Calculate total changes as additions + deletions
• Apply thresholds from config: XS (<10), S (<50), M (<200), L (<500), XL (≥500)
• Add single size label to labelsToAdd; ensure only one size label is applied per PR

Task 3: Implement Module Detection from File Paths

Add logic to detect which modules are touched and apply module labels.

• Load module-to-path mappings from kdm-automation.json via the helpers
• Iterate through changed files from github.rest.pulls.listFiles
• Match each file path against module patterns; collect all matched modules
• Apply a module label for each unique module detected (PRs may touch multiple modules)
• Consider adding a multi-module indicator label if more than 2 modules are touched

Task 4: Implement Complexity Calculation

Add heuristic-based complexity scoring and apply complexity labels.

• Calculate complexity score based on: file count, line changes, and modules touched
• Suggested heuristic: score = (files × 2) + (lines / 50) + (modules × 5)
• Apply thresholds: easy (<15), medium (<40), complex (≥40)
• Add single complexity label: review: easy, review: medium, or review: complex
• Tune thresholds based on repository's typical PR sizes if needed

Task 5: Refactor to Use Shared Helpers

Optionally migrate the labeler script to use the established helper patterns for consistency.

• Import buildBotContext and addLabels from ./helpers/api.cjs
• Import config loading from ./helpers/config-loader.cjs to read label definitions
• Replace direct github.rest.issues.addLabels call with the helper's addLabels function
• Benefit: gains input validation, structured error handling, and consistent logging

🤖 Prompt for AI agents

Extend `.github/scripts/pr-labeler.cjs` to implement four new labeling
capabilities: title-based type detection, size-based labeling, module detection
from file paths, and complexity calculation. Also refactor the script to use
shared helpers.

**Title-Based Type Label Detection:**
- Read `context.payload.pull_request.title` from the event payload
- Use pattern matching to detect TYPE keyword, supporting:
  - KDM title format: `[KDM-...-FIX-...]`
  - Conventional commits: `fix:`, `feat:`, `fix(`, `feat(`
  - Plain keywords
- Map detected type to label: FIX → `type: bug-fix`, FEAT → `type: feature`,
REFACTOR → `type: refactor`
- Add matched type label to the `labelsToAdd` Set

**Size-Based Labeling:**
- Call `github.rest.pulls.get` to fetch `additions` and `deletions` totals
- Compute total changes as `additions + deletions`
- Apply size thresholds from config (XS <10, S <50, M <200, L <500, XL ≥500)
- Add exactly one size label to `labelsToAdd`

**Module Detection from File Paths:**
- Load `modulePaths` mappings from `kdm-automation.json` via helpers
- Retrieve changed files via `github.rest.pulls.listFiles`
- Match each file path against module patterns and collect all unique matched
modules
- Add one module label per unique module detected
- If more than 2 modules are touched, also add a `multi-module` indicator label

**Complexity Calculation:**
- Compute: `score = (files × 2) + (lines / 50) + (modules × 5)`
- Apply thresholds: easy (<15), medium (<40), complex (≥40)
- Add exactly one complexity label: `review: easy`, `review: medium`, or
`review: complex`

**Refactor to Use Shared Helpers:**
- Import `buildBotContext` and `addLabels` from `./helpers/api.cjs`
- Import config loading from `./helpers/config-loader.cjs`
- Replace direct `github.rest.issues.addLabels` call with the helper's
`addLabels` function

Phase 3: Ensure Labels Exist in Repository

Create the actual GitHub labels that the automation will apply.

Task 1: Document Required Labels

Create or update documentation listing all labels that must exist in the repository.

• Add a section to CONTRIBUTING.md or create .github/LABELS.md documenting the label system
• List all type labels with descriptions and suggested colors
• List all size labels with their thresholds
• List all module labels with their file path associations
• List all complexity labels with explanation of the heuristic

Task 2: Create GitHub Labels

Ensure all required labels exist in the repository with consistent naming and colors.

• Type labels: type: bug-fix (red), type: feature (green), type: refactor (blue)
• Size labels: size: XS through size: XL (gradient from light to dark, e.g., grays or blues)
• Module labels: module: cli, module: ui, module: config, etc. (consistent color family, e.g., purples)
• Complexity labels: review: easy (green), review: medium (yellow), review: complex (red)
• This can be done manually via GitHub UI or via a setup script if preferred

🤖 Prompt for AI agents

Create documentation for the label system and define all required GitHub labels
for the repository.

**Documentation:**
- Add a section to `CONTRIBUTING.md` or create `.github/LABELS.md`
- Document all label categories:
  - Type labels with descriptions and suggested colors
  - Size labels with their line-change thresholds
  - Module labels with their associated file path patterns
- Complexity labels with an explanation of the heuristic (`score = (files × 2) +
(lines / 50) + (modules × 5)`)

**GitHub Labels (to be created manually or via a setup script):**
- Type labels: `type: bug-fix` (red), `type: feature` (green), `type: refactor`
(blue)
- Size labels: `size: XS` through `size: XL` using a light-to-dark gradient
(e.g., grays or blues)
- Module labels: `module: cli`, `module: ui`, `module: config`, `module: auth`,
`module: logger`, `module: test`, `module: docs`, `module: docker`, `module:
k8s`, `module: minikube`, `module: monitor` — consistent color family (e.g.,
purples)
- Complexity labels: `review: easy` (green), `review: medium` (yellow), `review:
complex` (red)

Research

The project is a Kubernetes/Docker monitoring CLI (kdm-cli) with comprehensive GitHub automation in .github/. PR labeling is handled by .github/workflows/labeler.yml which invokes .github/scripts/pr-labeler.cjs via actions/github-script. The script currently labels PRs based solely on file paths (docs/** → documentation, src/** → frontend, .github/workflows/** → ci/cd). Central automation configuration lives in .github/kdm-automation.json, which defines label taxonomies and is consumed by helper scripts in .github/scripts/helpers/. The src/ directory maps to modules: src/commands/ → CLI, src/ui/ → UI, src/utils/config.ts → CONFIG, src/utils/logger.ts → LOGGER, src/__tests__/ → TEST, and docs/ → DOCS.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Extend `.github/kdm-automation.json` to include all new PR label category
definitions and module-to-path mappings.

- Add a top-level `prLabels` object with four sub-categories:
- `type`: Define entries for `type: bug-fix` (maps to FIX), `type: feature`
(maps to FEAT), and `type: refactor` (maps to REFACTOR)
- `size`: Define entries for `size: XS`, `size: S`, `size: M`, `size: L`, `size:
XL`, each with their respective line-change threshold values (XS <10, S <50, M
<200, L <500, XL ≥500)
- `module`: Define entries for `module: config`, `module: cli`, `module: ui`,
`module: auth`, `module: logger`, `module: test`, `module: docs`, `module:
docker`, `module: k8s`, `module: minikube`, `module: monitor`
- `complexity`: Define entries for `review: easy`, `review: medium`, `review:
complex` with their respective calculation thresholds (easy <15, medium <40,
complex ≥40)
- Within `prLabels`, also add a `modulePaths` mapping object:
  - `src/commands/**` → CLI
  - `src/ui/**` → UI
  - `src/utils/config.ts` → CONFIG
  - `src/utils/logger.ts` → LOGGER
  - `src/__tests__/**` → TEST
  - `docs/**` → DOCS
  - `src/docker/**` → DOCKER
  - `src/kubernetes/**` → K8S
  - `src/minikube/**` → MINIKUBE
  - `src/monitor/**` → MONITOR
- `src/utils/version-check.ts` and remaining `src/` files → fallback or CLI
module
===============================================================================

Task: 2

Extend `.github/scripts/pr-labeler.cjs` to implement four new labeling
capabilities: title-based type detection, size-based labeling, module detection
from file paths, and complexity calculation. Also refactor the script to use
shared helpers.

**Title-Based Type Label Detection:**
- Read `context.payload.pull_request.title` from the event payload
- Use pattern matching to detect TYPE keyword, supporting:
  - KDM title format: `[KDM-...-FIX-...]`
  - Conventional commits: `fix:`, `feat:`, `fix(`, `feat(`
  - Plain keywords
- Map detected type to label: FIX → `type: bug-fix`, FEAT → `type: feature`,
REFACTOR → `type: refactor`
- Add matched type label to the `labelsToAdd` Set

**Size-Based Labeling:**
- Call `github.rest.pulls.get` to fetch `additions` and `deletions` totals
- Compute total changes as `additions + deletions`
- Apply size thresholds from config (XS <10, S <50, M <200, L <500, XL ≥500)
- Add exactly one size label to `labelsToAdd`

**Module Detection from File Paths:**
- Load `modulePaths` mappings from `kdm-automation.json` via helpers
- Retrieve changed files via `github.rest.pulls.listFiles`
- Match each file path against module patterns and collect all unique matched
modules
- Add one module label per unique module detected
- If more than 2 modules are touched, also add a `multi-module` indicator label

**Complexity Calculation:**
- Compute: `score = (files × 2) + (lines / 50) + (modules × 5)`
- Apply thresholds: easy (<15), medium (<40), complex (≥40)
- Add exactly one complexity label: `review: easy`, `review: medium`, or
`review: complex`

**Refactor to Use Shared Helpers:**
- Import `buildBotContext` and `addLabels` from `./helpers/api.cjs`
- Import config loading from `./helpers/config-loader.cjs`
- Replace direct `github.rest.issues.addLabels` call with the helper's
`addLabels` function
===============================================================================

Task: 3

Create documentation for the label system and define all required GitHub labels
for the repository.

**Documentation:**
- Add a section to `CONTRIBUTING.md` or create `.github/LABELS.md`
- Document all label categories:
  - Type labels with descriptions and suggested colors
  - Size labels with their line-change thresholds
  - Module labels with their associated file path patterns
- Complexity labels with an explanation of the heuristic (`score = (files × 2) +
(lines / 50) + (modules × 5)`)

**GitHub Labels (to be created manually or via a setup script):**
- Type labels: `type: bug-fix` (red), `type: feature` (green), `type: refactor`
(blue)
- Size labels: `size: XS` through `size: XL` using a light-to-dark gradient
(e.g., grays or blues)
- Module labels: `module: cli`, `module: ui`, `module: config`, `module: auth`,
`module: logger`, `module: test`, `module: docs`, `module: docker`, `module:
k8s`, `module: minikube`, `module: monitor` — consistent color family (e.g.,
purples)
- Complexity labels: `review: easy` (green), `review: medium` (yellow), `review:
complex` (red)

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[Rishiraj-Pathak-27]

Your Welcome @utkarsh232005