tlc-claude-code 1.7.0 → 1.8.0

package/server/lib/shame/shame-registry.js

@@ -0,0 +1,224 @@
+/**
+ * Wall of Shame Registry
+ *
+ * Document bugs with root causes, creating a project-level learning registry.
+ * Gate rules can be suggested from shame entries to prevent recurrence.
+ *
+ * @module shame/shame-registry
+ */
+
+const path = require('path');
+const defaultFs = require('fs').promises;
+const crypto = require('crypto');
+
+/** Shame file path relative to project root */
+const SHAME_FILE = '.tlc/shame.json';
+
+/** Valid shame categories */
+const SHAME_CATEGORIES = [
+  'architecture',
+  'type-safety',
+  'duplication',
+  'docker',
+  'security',
+  'data-loss',
+];
+
+/** Gate rule suggestions per category */
+const RULE_SUGGESTIONS = {
+  'architecture': [
+    { rule: 'single-writer', description: 'Enforce single-writer pattern — one service per DB table' },
+    { rule: 'no-raw-api', description: 'Use API helper instead of raw fetch/axios calls' },
+    { rule: 'no-flat-folders', description: 'Organize code by entity, not by type' },
+  ],
+  'type-safety': [
+    { rule: 'tsc-noEmit', description: 'Run tsc --noEmit before push to catch type errors' },
+    { rule: 'zod-coerce-date', description: 'Use z.coerce.date() instead of z.date() for API schemas' },
+    { rule: 'no-any', description: 'Disallow explicit any types' },
+  ],
+  'duplication': [
+    { rule: 'no-duplicate-logic', description: 'Extract shared logic to common utility modules' },
+    { rule: 'single-source-of-truth', description: 'Constants and config in one place' },
+  ],
+  'docker': [
+    { rule: 'volume-names', description: 'All Docker volumes must have explicit name: property' },
+    { rule: 'no-external-volumes', description: 'Do not use external: true in volumes' },
+    { rule: 'no-dangerous-commands', description: 'Block docker system prune in scripts' },
+  ],
+  'security': [
+    { rule: 'no-hardcoded-secrets', description: 'Never hardcode API keys, passwords, or tokens' },
+    { rule: 'input-validation', description: 'Validate all external input at API boundaries' },
+    { rule: 'no-eval', description: 'Never use eval() or Function() constructor' },
+  ],
+  'data-loss': [
+    { rule: 'backup-before-migrate', description: 'Require backup before destructive migrations' },
+    { rule: 'soft-delete', description: 'Prefer soft-delete over hard-delete for user data' },
+    { rule: 'transaction-wrap', description: 'Wrap multi-step DB operations in transactions' },
+  ],
+};
+
+/**
+ * Add a new shame entry to the entries array
+ * @param {Array} entries - Current entries
+ * @param {Object} data - Entry data
+ * @param {string} data.title - Bug title
+ * @param {string} data.rootCause - Root cause description
+ * @param {string} data.category - Category from SHAME_CATEGORIES
+ * @param {string} data.fix - How it was fixed
+ * @param {string} data.lesson - Lesson learned
+ * @returns {Object} The new entry with id and timestamp
+ */
+function addEntry(entries, data) {
+  const entry = {
+    id: crypto.randomBytes(4).toString('hex'),
+    title: data.title,
+    rootCause: data.rootCause,
+    category: data.category,
+    fix: data.fix,
+    lesson: data.lesson,
+    timestamp: new Date().toISOString(),
+  };
+
+  entries.push(entry);
+  return entry;
+}
+
+/**
+ * Load entries from .tlc/shame.json
+ * @param {string} projectPath - Path to project root
+ * @param {Object} options - Injectable dependencies
+ * @param {Object} options.fs - File system module
+ * @returns {Promise<Array>} Loaded entries
+ */
+async function loadEntries(projectPath, options = {}) {
+  const fsModule = options.fs || defaultFs;
+  const filePath = path.join(projectPath, SHAME_FILE);
+
+  try {
+    const content = await fsModule.readFile(filePath, 'utf-8');
+    const parsed = JSON.parse(content);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Save entries to .tlc/shame.json
+ * @param {string} projectPath - Path to project root
+ * @param {Array} entries - Entries to save
+ * @param {Object} options - Injectable dependencies
+ * @param {Object} options.fs - File system module
+ * @returns {Promise<void>}
+ */
+async function saveEntries(projectPath, entries, options = {}) {
+  const fsModule = options.fs || defaultFs;
+  const filePath = path.join(projectPath, SHAME_FILE);
+  const dirPath = path.dirname(filePath);
+
+  await fsModule.mkdir(dirPath, { recursive: true });
+  await fsModule.writeFile(filePath, JSON.stringify(entries, null, 2));
+}
+
+/**
+ * Validate a category
+ * @param {string} category - Category to validate
+ * @returns {Object} { valid: boolean, category: string }
+ */
+function categorizeEntry(category) {
+  const valid = SHAME_CATEGORIES.includes(category);
+  return { valid, category };
+}
+
+/**
+ * Generate a markdown report grouped by category
+ * @param {Array} entries - Shame entries
+ * @returns {string} Markdown report
+ */
+function generateReport(entries) {
+  if (entries.length === 0) {
+    return '# Wall of Shame\n\nNo entries yet.\n';
+  }
+
+  // Group by category
+  const groups = {};
+  for (const entry of entries) {
+    const cat = entry.category || 'uncategorized';
+    if (!groups[cat]) groups[cat] = [];
+    groups[cat].push(entry);
+  }
+
+  let report = '# Wall of Shame\n\n';
+  report += `Total entries: ${entries.length}\n\n`;
+
+  for (const [category, categoryEntries] of Object.entries(groups)) {
+    report += `## ${category}\n\n`;
+
+    for (const entry of categoryEntries) {
+      report += `### ${entry.title}\n\n`;
+      report += `- **Root Cause:** ${entry.rootCause}\n`;
+      report += `- **Fix:** ${entry.fix}\n`;
+      report += `- **Lesson:** ${entry.lesson}\n`;
+      report += `- **Date:** ${entry.timestamp}\n\n`;
+    }
+  }
+
+  return report;
+}
+
+/**
+ * Suggest gate rules based on shame category
+ * @param {string} category - Shame category
+ * @returns {Array<{rule: string, description: string}>} Suggested rules
+ */
+function suggestGateRules(category) {
+  return RULE_SUGGESTIONS[category] || [];
+}
+
+/**
+ * Track recurrence counts per category
+ * @param {Array} entries - All shame entries
+ * @returns {Object} Category → count mapping
+ */
+function trackRecurrence(entries) {
+  const counts = {};
+  for (const entry of entries) {
+    const cat = entry.category || 'uncategorized';
+    counts[cat] = (counts[cat] || 0) + 1;
+  }
+  return counts;
+}
+
+/**
+ * Create a shame registry instance with dependencies
+ * @param {Object} deps - Injectable dependencies
+ * @param {Object} deps.fs - File system module
+ * @returns {Object} Registry instance
+ */
+function createShameRegistry(deps = {}) {
+  let entries = [];
+
+  return {
+    add: (data) => addEntry(entries, data),
+    load: async (projectPath) => {
+      entries = await loadEntries(projectPath, deps);
+      return entries;
+    },
+    save: (projectPath) => saveEntries(projectPath, entries, deps),
+    report: () => generateReport(entries),
+    suggest: (category) => suggestGateRules(category),
+    recurrence: () => trackRecurrence(entries),
+  };
+}
+
+module.exports = {
+  createShameRegistry,
+  addEntry,
+  loadEntries,
+  saveEntries,
+  categorizeEntry,
+  generateReport,
+  suggestGateRules,
+  trackRecurrence,
+  SHAME_CATEGORIES,
+};

package/server/lib/shame/shame-registry.test.js

@@ -0,0 +1,202 @@
+/**
+ * Wall of Shame Registry Tests
+ *
+ * Document bugs with root causes, creating a project-level learning registry.
+ */
+import { describe, it, expect, vi } from 'vitest';
+
+const {
+  createShameRegistry,
+  addEntry,
+  loadEntries,
+  saveEntries,
+  categorizeEntry,
+  generateReport,
+  suggestGateRules,
+  trackRecurrence,
+  SHAME_CATEGORIES,
+} = require('./shame-registry.js');
+
+describe('Wall of Shame Registry', () => {
+  describe('addEntry', () => {
+    it('adds shame entry with all fields', () => {
+      const entries = [];
+      const entry = addEntry(entries, {
+        title: 'API returns 500 on empty body',
+        rootCause: 'No input validation on POST handler',
+        category: 'architecture',
+        fix: 'Added Zod schema validation middleware',
+        lesson: 'Always validate input at API boundaries',
+      });
+
+      expect(entry.title).toBe('API returns 500 on empty body');
+      expect(entry.rootCause).toBeDefined();
+      expect(entry.category).toBe('architecture');
+      expect(entry.fix).toBeDefined();
+      expect(entry.lesson).toBeDefined();
+    });
+
+    it('entry includes timestamp and ID', () => {
+      const entries = [];
+      const entry = addEntry(entries, {
+        title: 'Test bug',
+        rootCause: 'Reason',
+        category: 'type-safety',
+        fix: 'Fixed it',
+        lesson: 'Learned something',
+      });
+
+      expect(entry.id).toBeDefined();
+      expect(entry.timestamp).toBeDefined();
+      expect(typeof entry.id).toBe('string');
+    });
+  });
+
+  describe('loadEntries', () => {
+    it('loads entries from file', async () => {
+      const mockFs = {
+        readFile: vi.fn().mockResolvedValue(JSON.stringify([
+          { id: '1', title: 'Bug A', category: 'architecture' },
+          { id: '2', title: 'Bug B', category: 'security' },
+        ])),
+      };
+
+      const entries = await loadEntries('/project', { fs: mockFs });
+      expect(entries).toHaveLength(2);
+      expect(entries[0].title).toBe('Bug A');
+    });
+
+    it('handles empty registry', async () => {
+      const mockFs = {
+        readFile: vi.fn().mockRejectedValue(new Error('ENOENT')),
+      };
+
+      const entries = await loadEntries('/project', { fs: mockFs });
+      expect(entries).toHaveLength(0);
+    });
+
+    it('handles malformed file gracefully', async () => {
+      const mockFs = {
+        readFile: vi.fn().mockResolvedValue('not json {{{'),
+      };
+
+      const entries = await loadEntries('/project', { fs: mockFs });
+      expect(entries).toHaveLength(0);
+    });
+  });
+
+  describe('saveEntries', () => {
+    it('saves entries to file', async () => {
+      const mockFs = {
+        mkdir: vi.fn().mockResolvedValue(undefined),
+        writeFile: vi.fn().mockResolvedValue(undefined),
+      };
+
+      const entries = [
+        { id: '1', title: 'Bug', category: 'architecture' },
+      ];
+
+      await saveEntries('/project', entries, { fs: mockFs });
+
+      expect(mockFs.writeFile).toHaveBeenCalledWith(
+        expect.stringContaining('shame.json'),
+        expect.any(String)
+      );
+    });
+  });
+
+  describe('categorizeEntry', () => {
+    it('categorizes entries correctly', () => {
+      expect(SHAME_CATEGORIES).toContain('architecture');
+      expect(SHAME_CATEGORIES).toContain('type-safety');
+      expect(SHAME_CATEGORIES).toContain('duplication');
+      expect(SHAME_CATEGORIES).toContain('docker');
+      expect(SHAME_CATEGORIES).toContain('security');
+      expect(SHAME_CATEGORIES).toContain('data-loss');
+    });
+
+    it('validates category is in allowed list', () => {
+      const result = categorizeEntry('architecture');
+      expect(result.valid).toBe(true);
+
+      const invalid = categorizeEntry('invalid-category');
+      expect(invalid.valid).toBe(false);
+    });
+  });
+
+  describe('generateReport', () => {
+    it('generates markdown report', () => {
+      const entries = [
+        { id: '1', title: 'Bug A', rootCause: 'Cause A', category: 'architecture', fix: 'Fix A', lesson: 'Lesson A', timestamp: '2024-01-01' },
+        { id: '2', title: 'Bug B', rootCause: 'Cause B', category: 'security', fix: 'Fix B', lesson: 'Lesson B', timestamp: '2024-01-02' },
+      ];
+
+      const report = generateReport(entries);
+      expect(report).toContain('Bug A');
+      expect(report).toContain('Bug B');
+      expect(report).toContain('architecture');
+      expect(report).toContain('security');
+    });
+
+    it('report groups by category', () => {
+      const entries = [
+        { id: '1', title: 'Bug A', category: 'architecture', rootCause: 'r', fix: 'f', lesson: 'l', timestamp: '2024-01-01' },
+        { id: '2', title: 'Bug B', category: 'architecture', rootCause: 'r', fix: 'f', lesson: 'l', timestamp: '2024-01-02' },
+        { id: '3', title: 'Bug C', category: 'security', rootCause: 'r', fix: 'f', lesson: 'l', timestamp: '2024-01-03' },
+      ];
+
+      const report = generateReport(entries);
+      // architecture section should come before its entries
+      const archIndex = report.indexOf('architecture');
+      const bugAIndex = report.indexOf('Bug A');
+      const secIndex = report.indexOf('security');
+      expect(archIndex).toBeLessThan(bugAIndex);
+      expect(archIndex).toBeLessThan(secIndex);
+    });
+  });
+
+  describe('suggestGateRules', () => {
+    it('suggests gate rules for architecture category', () => {
+      const rules = suggestGateRules('architecture');
+      expect(rules.length).toBeGreaterThan(0);
+      expect(rules[0]).toMatchObject({
+        rule: expect.any(String),
+        description: expect.any(String),
+      });
+    });
+
+    it('suggests gate rules for type-safety category', () => {
+      const rules = suggestGateRules('type-safety');
+      expect(rules.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('trackRecurrence', () => {
+    it('tracks recurrence count per category', () => {
+      const entries = [
+        { id: '1', category: 'architecture' },
+        { id: '2', category: 'architecture' },
+        { id: '3', category: 'security' },
+        { id: '4', category: 'architecture' },
+      ];
+
+      const recurrence = trackRecurrence(entries);
+      expect(recurrence.architecture).toBe(3);
+      expect(recurrence.security).toBe(1);
+    });
+  });
+
+  describe('createShameRegistry', () => {
+    it('creates registry with injectable dependencies', () => {
+      const registry = createShameRegistry({
+        fs: { readFile: vi.fn(), writeFile: vi.fn(), mkdir: vi.fn() },
+      });
+
+      expect(registry).toBeDefined();
+      expect(registry.add).toBeDefined();
+      expect(registry.load).toBeDefined();
+      expect(registry.save).toBeDefined();
+      expect(registry.report).toBeDefined();
+    });
+  });
+});

package/server/lib/standards/cleanup-dry-run.js

@@ -0,0 +1,254 @@
+/**
+ * Cleanup Dry-Run Mode
+ *
+ * Preview what /tlc:cleanup would change without making
+ * any modifications. Returns a structured report of planned changes.
+ *
+ * @module standards/cleanup-dry-run
+ */
+
+const path = require('path');
+
+/** Flat folders that should be reorganized */
+const FLAT_FOLDERS = ['services', 'interfaces', 'controllers'];
+
+/**
+ * List files that would be moved from flat folders to entity structure
+ * @param {string} projectPath - Path to project root
+ * @param {Object} options - Injectable dependencies
+ * @param {Function} options.glob - Glob function
+ * @returns {Promise<Array>} Files with source, destination, reason
+ */
+async function listFilesToMove(projectPath, options = {}) {
+  const { glob } = options;
+  const results = [];
+
+  for (const folder of FLAT_FOLDERS) {
+    const pattern = `src/${folder}/*.*`;
+    const files = await glob(pattern, { cwd: projectPath });
+
+    for (const file of files) {
+      const fileName = path.basename(file);
+      // Derive entity name from file (e.g., userService.js → user)
+      const entity = fileName
+        .replace(/\.(js|ts|jsx|tsx)$/, '')
+        .replace(/(Service|Controller|Interface)$/i, '')
+        .toLowerCase();
+
+      results.push({
+        source: file,
+        destination: `src/${entity}/${fileName}`,
+        reason: `Move from flat ${folder}/ to entity-based structure`,
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * List hardcoded URLs/ports that would be extracted to env vars
+ * @param {string} projectPath - Path to project root
+ * @param {Object} options - Injectable dependencies
+ * @param {Function} options.glob - Glob function
+ * @param {Function} options.readFile - File reader
+ * @returns {Promise<Array>} Hardcoded values with suggested env vars
+ */
+async function listHardcodedUrls(projectPath, options = {}) {
+  const { glob, readFile } = options;
+  const results = [];
+
+  const pattern = 'src/**/*.{js,ts,jsx,tsx}';
+  const files = await glob(pattern, { cwd: projectPath });
+
+  for (const file of files) {
+    const filePath = path.join(projectPath, file);
+    const content = await readFile(filePath);
+
+    // Check URLs
+    const urlPattern = /['"`](https?:\/\/[^'"`]+)['"`]/g;
+    let match;
+    while ((match = urlPattern.exec(content)) !== null) {
+      results.push({
+        file,
+        value: match[1],
+        type: 'url',
+        suggestedEnvVar: generateEnvVarName(match[1], 'url'),
+      });
+    }
+
+    // Check ports
+    const portPattern = /\b(?:const|let|var)\s+port\s*=\s*(\d+)/g;
+    while ((match = portPattern.exec(content)) !== null) {
+      results.push({
+        file,
+        value: match[1],
+        type: 'port',
+        suggestedEnvVar: 'PORT',
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Generate env var name from a value
+ * @param {string} value - The value
+ * @param {string} type - Type (url, port)
+ * @returns {string} Suggested env var name
+ */
+function generateEnvVarName(value, type) {
+  if (type === 'port') return 'PORT';
+  try {
+    const url = new URL(value);
+    const host = url.hostname.replace(/[^a-zA-Z0-9]/g, '_').toUpperCase();
+    return host === 'LOCALHOST' ? 'API_URL' : `${host}_URL`;
+  } catch {
+    return 'API_URL';
+  }
+}
+
+/**
+ * List inline interfaces that would be extracted
+ * @param {string} projectPath - Path to project root
+ * @param {Object} options - Injectable dependencies
+ * @param {Function} options.glob - Glob function
+ * @param {Function} options.readFile - File reader
+ * @returns {Promise<Array>} Interfaces with file, name, target path
+ */
+async function listInterfacesToExtract(projectPath, options = {}) {
+  const { glob, readFile } = options;
+  const results = [];
+
+  const pattern = '**/*.service.ts';
+  const files = await glob(pattern, { cwd: projectPath });
+
+  for (const file of files) {
+    const filePath = path.join(projectPath, file);
+    const content = await readFile(filePath);
+
+    const interfacePattern = /\binterface\s+(\w+)\s*\{/g;
+    let match;
+    while ((match = interfacePattern.exec(content)) !== null) {
+      const entity = path.basename(file, '.service.ts');
+      results.push({
+        file,
+        interfaceName: match[1],
+        targetPath: `src/${entity}/types/${entity}.types.ts`,
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * List exported functions missing JSDoc
+ * @param {string} projectPath - Path to project root
+ * @param {Object} options - Injectable dependencies
+ * @param {Function} options.glob - Glob function
+ * @param {Function} options.readFile - File reader
+ * @returns {Promise<Array>} Functions needing JSDoc
+ */
+async function listFunctionsNeedingJsDoc(projectPath, options = {}) {
+  const { glob, readFile } = options;
+  const results = [];
+
+  const pattern = 'src/**/*.{js,ts}';
+  const files = await glob(pattern, { cwd: projectPath });
+
+  for (const file of files) {
+    const filePath = path.join(projectPath, file);
+    const content = await readFile(filePath);
+    const lines = content.split('\n');
+
+    for (let i = 0; i < lines.length; i++) {
+      const exportMatch = lines[i].match(/export\s+function\s+(\w+)/);
+      if (!exportMatch) continue;
+
+      // Check if previous non-empty line is end of JSDoc
+      let hasJsDoc = false;
+      for (let j = i - 1; j >= 0; j--) {
+        const prev = lines[j].trim();
+        if (prev === '') continue;
+        if (prev.endsWith('*/')) {
+          hasJsDoc = true;
+        }
+        break;
+      }
+
+      if (!hasJsDoc) {
+        results.push({
+          file,
+          functionName: exportMatch[1],
+          line: i + 1,
+        });
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Generate planned commit messages based on planned changes
+ * @param {Object} plan - Cleanup plan
+ * @returns {string[]} Commit messages
+ */
+function planCommitMessages(plan) {
+  const commits = [];
+
+  if (plan.filesToMove.length > 0) {
+    commits.push(`refactor(cleanup): migrate ${plan.filesToMove.length} files from flat folders to entity structure`);
+  }
+  if (plan.hardcodedUrls.length > 0) {
+    commits.push(`refactor(cleanup): extract ${plan.hardcodedUrls.length} hardcoded URLs/ports to environment variables`);
+  }
+  if (plan.interfacesToExtract.length > 0) {
+    commits.push(`refactor(cleanup): extract ${plan.interfacesToExtract.length} inline interfaces to type files`);
+  }
+  if (plan.functionsNeedingJsDoc.length > 0) {
+    commits.push(`docs(cleanup): add JSDoc to ${plan.functionsNeedingJsDoc.length} exported functions`);
+  }
+
+  return commits;
+}
+
+/**
+ * Plan cleanup without executing — dry-run mode
+ * @param {string} projectPath - Path to project root
+ * @param {Object} options - Injectable dependencies (no writeFile, no exec)
+ * @param {Function} options.glob - Glob function
+ * @param {Function} options.readFile - File reader
+ * @returns {Promise<Object>} Structured cleanup plan
+ */
+async function planCleanup(projectPath, options = {}) {
+  const { glob, readFile } = options;
+
+  const filesToMove = await listFilesToMove(projectPath, { glob });
+  const hardcodedUrls = await listHardcodedUrls(projectPath, { glob, readFile });
+  const interfacesToExtract = await listInterfacesToExtract(projectPath, { glob, readFile });
+  const functionsNeedingJsDoc = await listFunctionsNeedingJsDoc(projectPath, { glob, readFile });
+
+  const plan = {
+    filesToMove,
+    hardcodedUrls,
+    interfacesToExtract,
+    functionsNeedingJsDoc,
+    plannedCommits: [],
+  };
+
+  plan.plannedCommits = planCommitMessages(plan);
+
+  return plan;
+}
+
+module.exports = {
+  planCleanup,
+  listFilesToMove,
+  listHardcodedUrls,
+  listInterfacesToExtract,
+  listFunctionsNeedingJsDoc,
+  planCommitMessages,
+};