mcp-udacity-commit 1.0.2 → 1.2.1

package/README.md

@@ -48,8 +48,10 @@ claude mcp add udacity-commit -- node "$(pwd)/build/index.js"
 | Primitive | Name | Purpose |
 | --- | --- | --- |
 | Resource | `udacity://commit-styleguide` | The style-guide rules, as markdown |
+| Resource | `udacity://branch-naming` | The companion `type/kebab-case` branch-naming rules, as markdown |
 | Tool | `validate_commit_message` | Checks a message against every rule (type, ≤50-char subject, capitalization, no trailing period, blank line, ≤72-char body wrap) |
 | Tool | `format_commit_message` | Builds a compliant message from `type` + `subject` + optional `body`/`footer` |
+| Tool | `validate_branch_name` | Checks a branch name against the companion `type/kebab-case` convention (e.g. `feat/add-dark-mode`); `release/*` is a typed branch with a version-style description (`release/1.2.0`), and base branches like `main` are exempt |
 
 ## Example
 
@@ -78,6 +80,17 @@ Resolves: #142
   • Subject must not end with a period.
 ```
 
+`validate_branch_name` enforces the companion `type/kebab-case` convention:
+
+```text
+"feat/add-dark-mode"     →  ✅ Compliant branch name.
+"release/1.2.0"          →  ✅ Compliant branch name.
+"Feature/Add_Dark_Mode"  →  ❌ Not compliant.
+  • Unknown type "Feature". Use one of: feat, fix, docs, style, refactor, test, chore, release.
+  • Description must be lowercase kebab-case. Got: "Add_Dark_Mode".
+"main"                   →  ✅ (base branch — feature-branch rules don't apply)
+```
+
 ## Develop
 
 ```bash

package/build/index.js

@@ -2,8 +2,8 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { STYLE_GUIDE, validate, formatMessage } from "./lint.js";
-const VERSION = "1.0.2";
+import { STYLE_GUIDE, BRANCH_GUIDE, validate, formatMessage, validateBranch } from "./lint.js";
+const VERSION = "1.2.1";
 export function createServer() {
     const server = new McpServer({ name: "udacity-commit", version: VERSION });
     server.registerResource("styleguide", "udacity://commit-styleguide", {
@@ -11,6 +11,11 @@ export function createServer() {
         description: "The commit-message rules (types, subject, body, footer).",
         mimeType: "text/markdown",
     }, async (uri) => ({ contents: [{ uri: uri.href, text: STYLE_GUIDE }] }));
+    server.registerResource("branch-naming", "udacity://branch-naming", {
+        title: "Branch Naming (companion convention)",
+        description: "type/kebab-case branch-naming rules that pair with the commit style.",
+        mimeType: "text/markdown",
+    }, async (uri) => ({ contents: [{ uri: uri.href, text: BRANCH_GUIDE }] }));
     server.registerTool("validate_commit_message", {
         title: "Validate a commit message",
         description: "Check a commit message against the Udacity Git Commit Message Style Guide. " +
@@ -22,16 +27,16 @@ export function createServer() {
             warnings: z.array(z.string()),
         },
     }, async ({ message }) => {
-        const r = validate(message);
+        const report = validate(message);
         const text = [
-            r.valid ? "✅ Compliant with the Udacity style guide." : "❌ Not compliant.",
-            ...r.problems.map((p) => `  • ${p}`),
-            ...r.warnings.map((w) => `  ⚠ ${w}`),
+            report.valid ? "✅ Compliant with the Udacity style guide." : "❌ Not compliant.",
+            ...report.problems.map((problem) => `  • ${problem}`),
+            ...report.warnings.map((warning) => `  ⚠ ${warning}`),
         ].join("\n");
         const structuredContent = {
-            valid: r.valid,
-            problems: r.problems,
-            warnings: r.warnings,
+            valid: report.valid,
+            problems: report.problems,
+            warnings: report.warnings,
         };
         return { content: [{ type: "text", text }], structuredContent };
     });
@@ -69,13 +74,38 @@ export function createServer() {
             structuredContent,
         };
     });
+    server.registerTool("validate_branch_name", {
+        title: "Validate a git branch name",
+        description: "Check a git branch name against the companion type/kebab-case convention " +
+            '(e.g. "feat/add-dark-mode"). Returns whether it is compliant plus any problems ' +
+            "(violations) and warnings (hints). Base branches like main/master are exempt.",
+        inputSchema: { name: z.string().describe('The branch name to check, e.g. "feat/add-dark-mode"') },
+        outputSchema: {
+            valid: z.boolean(),
+            problems: z.array(z.string()),
+            warnings: z.array(z.string()),
+        },
+    }, async ({ name }) => {
+        const report = validateBranch(name);
+        const text = [
+            report.valid ? "✅ Compliant branch name." : "❌ Not compliant.",
+            ...report.problems.map((problem) => `  • ${problem}`),
+            ...report.warnings.map((warning) => `  ⚠ ${warning}`),
+        ].join("\n");
+        const structuredContent = {
+            valid: report.valid,
+            problems: report.problems,
+            warnings: report.warnings,
+        };
+        return { content: [{ type: "text", text }], structuredContent };
+    });
     return server;
 }
 async function main() {
     const server = createServer();
     await server.connect(new StdioServerTransport());
 }
-main().catch((err) => {
-    console.error(err);
+main().catch((error) => {
+    console.error(error);
     process.exit(1);
 });

package/build/lint.js

@@ -10,6 +10,13 @@
  */
 export const SUBJECT_MAX = 50;
 export const BODY_WRAP = 72;
+export const BRANCH_MAX = 50;
+/**
+ * Long-lived / protected branches that are exempt from the feature-branch
+ * `type/description` rule. `release/*` is NOT here — it is validated as a
+ * typed branch with a version-style description (e.g. `release/1.2.0`).
+ */
+export const BASE_BRANCHES = new Set(["main", "master", "dev", "develop", "trunk"]);
 export const TYPES = {
     feat: "A new feature",
     fix: "A bug fix",
@@ -19,6 +26,12 @@ export const TYPES = {
     test: "Adding tests, refactoring tests; no production code change",
     chore: "Updating build tasks, package configs, etc; no production code change",
 };
+/**
+ * Types allowed as a branch prefix: the commit types plus `release`, which is
+ * a branch-only type (release branches are named, not committed). `release`
+ * takes a version-style description; every other type takes kebab-case.
+ */
+export const BRANCH_TYPES = [...Object.keys(TYPES), "release"];
 /** Footer keywords recognized for issue-reference validation. */
 export const FOOTER_KEYS = ["Resolves", "Closes", "Fixes", "Fix", "See also", "Refs", "Ref"];
 /**
@@ -65,7 +78,7 @@ A commit message has three parts separated by blank lines: **subject**, optional
 
 ## Types
 ${Object.entries(TYPES)
-    .map(([t, d]) => `- **${t}**: ${d}`)
+    .map(([typeName, typeDescription]) => `- **${typeName}**: ${typeDescription}`)
     .join("\n")}
 
 ## Subject
@@ -86,15 +99,41 @@ ${Object.entries(TYPES)
 
 _Lengths are counted in Unicode code points._
 `;
+export const BRANCH_GUIDE = `# Branch naming (companion convention)
+
+Not part of the official Udacity *commit-message* guide, but a natural
+companion: name feature branches after the change they carry, reusing the
+same commit \`type\` set.
+
+    type/kebab-case-description
+
+## Rules
+- \`type/\` prefix — one of: ${BRANCH_TYPES.join(", ")}
+- A single \`/\` separates the type from the description
+- Description is **kebab-case**: lowercase letters and digits joined by single
+  hyphens (\`feat/add-dark-mode\`, not \`feat/Add_Dark_Mode\`)
+- \`release/\` branches take a **version-style** description instead: lowercase
+  words/digits joined by dots or hyphens (\`release/1.2.0\`, \`release/2024-q1\`)
+- No spaces, underscores, uppercase, or leading/trailing/double hyphens
+- Keep it short — ${BRANCH_MAX} characters or fewer (a hint, not a hard limit)
+
+## Examples
+- \`feat/add-dark-mode\`
+- \`fix/duplicate-auth-refresh\`
+- \`chore/bump-deps\`
+- \`release/1.2.0\`
+
+Base branches (${[...BASE_BRANCHES].join(", ")}) are exempt.
+`;
 /** Length in Unicode code points (not UTF-16 code units). */
-export function width(s) {
-    return [...s].length;
+export function width(text) {
+    return [...text].length;
 }
 /** Uppercase the first code point of a string (astral-safe). */
-function capitalizeFirst(s) {
-    const chars = [...s];
+function capitalizeFirst(text) {
+    const chars = [...text];
     if (chars.length === 0)
-        return s;
+        return text;
     return chars[0].toUpperCase() + chars.slice(1).join("");
 }
 /**
@@ -148,23 +187,23 @@ export function validate(message) {
         lines.pop();
     const rawSubject = lines[0] ?? "";
     const subject = rawSubject.replace(/\s+$/, "");
-    const m = subject.match(/^(\w+): (.*)$/);
-    if (!m) {
+    const subjectMatch = subject.match(/^(\w+): (.*)$/);
+    if (!subjectMatch) {
         problems.push(`Subject must follow "type: Subject". Got: "${subject}".`);
     }
     else {
-        const [, type, rest] = m;
+        const [, type, subjectText] = subjectMatch;
         if (!TYPES[type]) {
             problems.push(`Unknown type "${type}". Use one of: ${Object.keys(TYPES).join(", ")}.`);
         }
-        if (!rest) {
+        if (!subjectText) {
             problems.push("Subject text is empty after the type.");
         }
         else {
-            if (/^\p{Ll}/u.test(rest)) {
-                problems.push(`Subject should begin with a capital letter (got "${[...rest][0]}").`);
+            if (/^\p{Ll}/u.test(subjectText)) {
+                problems.push(`Subject should begin with a capital letter (got "${[...subjectText][0]}").`);
             }
-            const firstWord = rest.split(/\s+/)[0];
+            const firstWord = subjectText.split(/\s+/)[0];
             if (NON_IMPERATIVE.has(firstWord.toLowerCase())) {
                 warnings.push(`"${firstWord}" looks past-tense/gerund — use the imperative mood ("Add", not "Added").`);
             }
@@ -180,15 +219,15 @@ export function validate(message) {
     if (lines.length > 1 && lines[1].trim() !== "") {
         problems.push("Leave a blank line between the subject and the body.");
     }
-    for (let i = 2; i < lines.length; i++) {
-        const line = lines[i];
+    for (let lineIndex = 2; lineIndex < lines.length; lineIndex++) {
+        const line = lines[lineIndex];
         if (width(line) > BODY_WRAP) {
-            problems.push(`Line ${i + 1} is ${width(line)} chars; wrap body/footer at ${BODY_WRAP}.`);
+            problems.push(`Line ${lineIndex + 1} is ${width(line)} chars; wrap body/footer at ${BODY_WRAP}.`);
         }
-        const fm = line.match(/^([A-Za-z][A-Za-z ]*?):\s*(.*)$/);
-        if (fm && FOOTER_KEYS.some((k) => k.toLowerCase() === fm[1].toLowerCase())) {
-            if (!/#\d+/.test(fm[2])) {
-                warnings.push(`Footer "${fm[1]}" should reference an issue, e.g. "${fm[1]}: #123".`);
+        const footerMatch = line.match(/^([A-Za-z][A-Za-z ]*?):\s*(.*)$/);
+        if (footerMatch && FOOTER_KEYS.some((footerKey) => footerKey.toLowerCase() === footerMatch[1].toLowerCase())) {
+            if (!/#\d+/.test(footerMatch[2])) {
+                warnings.push(`Footer "${footerMatch[1]}" should reference an issue, e.g. "${footerMatch[1]}: #123".`);
             }
         }
     }
@@ -209,3 +248,71 @@ export function formatMessage(input) {
     const message = parts.join("\n");
     return { message, report: validate(message) };
 }
+/** Kebab-case: lowercase words (letters/digits) joined by single hyphens. */
+const KEBAB = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/**
+ * Version-style (for `release/` branches): lowercase words/digits joined by
+ * dots or hyphens, so `1.2.0`, `2.0.0-rc1`, and `2024-q1` all pass.
+ */
+const RELEASE_DESC = /^[a-z0-9]+([.-][a-z0-9]+)*$/;
+/**
+ * Validate a git branch name against the companion `type/kebab-case`
+ * convention. Base/long-lived branches (main, master, dev, develop, trunk)
+ * are accepted as-is with a note. `release/` is a typed branch and takes a
+ * version-style description (e.g. `release/1.2.0`).
+ */
+export function validateBranch(name) {
+    const problems = [];
+    const warnings = [];
+    const branch = name.trim();
+    if (!branch) {
+        return { valid: false, problems: ["Branch name is empty."], warnings };
+    }
+    if (branch !== name) {
+        problems.push("Branch name has leading/trailing whitespace.");
+    }
+    // Base / long-lived branches are exempt from the feature-branch rule.
+    // (`release/*` is NOT exempt — it is validated as a typed branch below.)
+    if (BASE_BRANCHES.has(branch)) {
+        warnings.push(`"${branch}" is a base branch — feature-branch naming rules don't apply.`);
+        return { valid: problems.length === 0, problems, warnings };
+    }
+    const slashIndex = branch.indexOf("/");
+    if (slashIndex === -1) {
+        problems.push(`Branch must follow "type/description". Got: "${branch}".`);
+        return { valid: false, problems, warnings };
+    }
+    const type = branch.slice(0, slashIndex);
+    const description = branch.slice(slashIndex + 1);
+    if (!BRANCH_TYPES.includes(type)) {
+        problems.push(`Unknown type "${type}". Use one of: ${BRANCH_TYPES.join(", ")}.`);
+    }
+    // `release/` takes a version-style description; every other type is kebab-case.
+    const isRelease = type === "release";
+    const pattern = isRelease ? RELEASE_DESC : KEBAB;
+    if (!description) {
+        problems.push("Description after the type is empty.");
+    }
+    else if (description.includes("/")) {
+        problems.push(`Use a single "/" after the type; the description must not contain "/". Got: "${description}".`);
+    }
+    else if (!pattern.test(description)) {
+        // Give the most specific reason we can, else a general shape message.
+        if (/[A-Z]/.test(description)) {
+            problems.push(`Description must be lowercase ${isRelease ? "version-style (e.g. 1.2.0)" : "kebab-case"}. Got: "${description}".`);
+        }
+        else if (/[_ ]/.test(description)) {
+            problems.push("Use hyphens, not spaces or underscores, to separate words.");
+        }
+        else if (isRelease) {
+            problems.push(`Release description must be version-style: lowercase words/digits joined by dots or hyphens (e.g. "1.2.0", "2024-q1"). Got: "${description}".`);
+        }
+        else {
+            problems.push(`Description must be kebab-case: lowercase words joined by single hyphens. Got: "${description}".`);
+        }
+    }
+    if (width(branch) > BRANCH_MAX) {
+        warnings.push(`Branch name is ${width(branch)} chars; keep it ${BRANCH_MAX} or fewer.`);
+    }
+    return { valid: problems.length === 0, problems, warnings };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-udacity-commit",
-  "version": "1.0.2",
+  "version": "1.2.1",
   "description": "MCP server that validates and formats git commit messages per the Udacity Git Commit Message Style Guide.",
   "type": "module",
   "license": "MIT",