tlc-claude-code 2.2.1 → 2.3.0

package/server/lib/skill-validator.js

@@ -0,0 +1,165 @@
+/**
+ * Skill Validator — Tier 1 (Static)
+ *
+ * Parses skill .md files and validates that referenced commands,
+ * modules, and skills actually exist. Fast, free, static analysis.
+ */
+
+const path = require('path');
+const realFs = require('fs');
+
+/**
+ * Extract module require references from code blocks in markdown content.
+ * Finds `require('./lib/...')` and `require('./server/lib/...')` patterns
+ * inside fenced code blocks only.
+ *
+ * @param {string} content - Markdown content to parse
+ * @returns {string[]} Array of module paths found in code blocks
+ */
+function extractModuleRefs(content) {
+  if (!content) return [];
+
+  const codeBlockRegex = /```(?:\w+)?\n([\s\S]*?)```/g;
+  const requireRegex = /require\(['"](\.\/(lib|server\/lib)\/[^'"]+)['"]\)/g;
+  const refs = new Set();
+
+  let blockMatch;
+  while ((blockMatch = codeBlockRegex.exec(content)) !== null) {
+    const blockContent = blockMatch[1];
+    let reqMatch;
+    while ((reqMatch = requireRegex.exec(blockContent)) !== null) {
+      refs.add(reqMatch[1]);
+    }
+  }
+
+  return [...refs];
+}
+
+/**
+ * Extract skill references from content.
+ * Finds `/tlc:...` and `Skill(skill="tlc:...")` patterns.
+ *
+ * @param {string} content - Content to parse
+ * @returns {string[]} Array of skill names (e.g., ['tlc:build', 'tlc:review'])
+ */
+function extractSkillRefs(content) {
+  if (!content) return [];
+
+  const refs = new Set();
+
+  // Match /tlc:name patterns (word chars plus hyphens)
+  const slashRegex = /\/tlc:([\w-]+)/g;
+  let match;
+  while ((match = slashRegex.exec(content)) !== null) {
+    refs.add(`tlc:${match[1]}`);
+  }
+
+  // Match Skill(skill="tlc:name") or Skill(skill='tlc:name')
+  const skillCallRegex = /Skill\(skill=["']tlc:([\w-]+)["']\)/g;
+  while ((match = skillCallRegex.exec(content)) !== null) {
+    refs.add(`tlc:${match[1]}`);
+  }
+
+  return [...refs];
+}
+
+/**
+ * Validate that referenced module files exist on disk.
+ *
+ * @param {string[]} refs - Array of module paths from extractModuleRefs
+ * @param {string} projectDir - Project root directory
+ * @param {Object} options - Options
+ * @param {Object} [options.fs] - Filesystem implementation (for testability)
+ * @returns {Array<{type: string, ref: string}>} Array of validation errors
+ */
+function validateModuleRefs(refs, projectDir, options = {}) {
+  if (!refs || refs.length === 0) return [];
+
+  const fsImpl = options.fs || realFs;
+  const errors = [];
+
+  for (const ref of refs) {
+    // Skill docs use paths like require('./lib/...') which resolve relative to server/
+    // Try both project root and server/ subdirectory
+    const candidates = [
+      path.resolve(projectDir, ref),
+      path.resolve(projectDir, 'server', ref),
+    ];
+
+    const found = candidates.some((absPath) => {
+      const absPathJs = absPath.endsWith('.js') ? absPath : `${absPath}.js`;
+      return fsImpl.existsSync(absPath) || fsImpl.existsSync(absPathJs);
+    });
+
+    if (!found) {
+      errors.push({ type: 'missing-module', ref });
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate that referenced skill files exist on disk.
+ * Maps `tlc:build` to `build.md` in the skill directory.
+ *
+ * @param {string[]} refs - Array of skill names from extractSkillRefs
+ * @param {string} skillDir - Directory containing skill .md files
+ * @param {Object} options - Options
+ * @param {Object} [options.fs] - Filesystem implementation (for testability)
+ * @returns {Array<{type: string, ref: string}>} Array of validation errors
+ */
+function validateSkillRefs(refs, skillDir, options = {}) {
+  if (!refs || refs.length === 0) return [];
+
+  const fsImpl = options.fs || realFs;
+  const errors = [];
+
+  for (const ref of refs) {
+    // tlc:build -> build.md
+    const name = ref.replace(/^tlc:/, '');
+    const filePath = path.join(skillDir, `${name}.md`);
+
+    if (!fsImpl.existsSync(filePath)) {
+      errors.push({ type: 'missing-skill', ref });
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate a skill markdown file by running all static checks.
+ *
+ * @param {string} content - Skill file markdown content
+ * @param {Object} options - Validation options
+ * @param {string} options.projectDir - Project root directory
+ * @param {string} options.skillDir - Directory containing skill .md files
+ * @param {Object} [options.fs] - Filesystem implementation (for testability)
+ * @returns {{valid: boolean, errors: Array<{type: string, ref: string}>}} Validation result
+ */
+function validateSkill(content, options = {}) {
+  if (!content) return { valid: true, errors: [] };
+  if (!options.projectDir || !options.skillDir) {
+    return { valid: false, errors: [{ type: 'config', ref: 'projectDir and skillDir are required' }] };
+  }
+
+  const { projectDir, skillDir, fs: fsImpl } = options;
+  const fsOpt = fsImpl ? { fs: fsImpl } : {};
+
+  const moduleRefs = extractModuleRefs(content);
+  const skillRefs = extractSkillRefs(content);
+
+  const moduleErrors = validateModuleRefs(moduleRefs, projectDir, fsOpt);
+  const skillErrors = validateSkillRefs(skillRefs, skillDir, fsOpt);
+
+  const errors = [...moduleErrors, ...skillErrors];
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+
+module.exports = { extractModuleRefs, extractSkillRefs, validateModuleRefs, validateSkillRefs, validateSkill };

package/server/lib/skill-validator.test.js

@@ -0,0 +1,289 @@
+/**
+ * Skill Validator Tests
+ *
+ * Static analysis for skill .md files — validates that referenced
+ * commands, modules, and skills actually exist.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  extractModuleRefs,
+  extractSkillRefs,
+  validateModuleRefs,
+  validateSkillRefs,
+  validateSkill,
+} from './skill-validator.js';
+
+describe('skill-validator', () => {
+  describe('extractModuleRefs', () => {
+    it('extracts require from code block', () => {
+      const content = "```js\nrequire('./lib/foo');\n```";
+      expect(extractModuleRefs(content)).toEqual(['./lib/foo']);
+    });
+
+    it('returns empty array when no code blocks', () => {
+      expect(extractModuleRefs('no code blocks here')).toEqual([]);
+    });
+
+    it('extracts multiple requires from code blocks', () => {
+      const content = [
+        '```js',
+        "const a = require('./lib/foo');",
+        "const b = require('./lib/bar');",
+        '```',
+        '',
+        'Some text in between.',
+        '',
+        '```js',
+        "const c = require('./server/lib/baz');",
+        '```',
+      ].join('\n');
+      expect(extractModuleRefs(content)).toEqual([
+        './lib/foo',
+        './lib/bar',
+        './server/lib/baz',
+      ]);
+    });
+
+    it('ignores requires outside code blocks', () => {
+      const content = "require('./lib/should-not-match');\nSome text.";
+      expect(extractModuleRefs(content)).toEqual([]);
+    });
+
+    it('handles code blocks with language specifiers', () => {
+      const content = "```javascript\nrequire('./lib/utils');\n```";
+      expect(extractModuleRefs(content)).toEqual(['./lib/utils']);
+    });
+
+    it('returns empty array for empty string', () => {
+      expect(extractModuleRefs('')).toEqual([]);
+    });
+
+    it('deduplicates repeated refs', () => {
+      const content = [
+        '```js',
+        "require('./lib/foo');",
+        "require('./lib/foo');",
+        '```',
+      ].join('\n');
+      expect(extractModuleRefs(content)).toEqual(['./lib/foo']);
+    });
+  });
+
+  describe('extractSkillRefs', () => {
+    it('extracts /tlc: skill references', () => {
+      expect(extractSkillRefs('Run /tlc:build to start')).toEqual([
+        'tlc:build',
+      ]);
+    });
+
+    it('extracts Skill() call references', () => {
+      expect(extractSkillRefs('Skill(skill="tlc:review")')).toEqual([
+        'tlc:review',
+      ]);
+    });
+
+    it('returns empty array when no skills referenced', () => {
+      expect(extractSkillRefs('no skills here')).toEqual([]);
+    });
+
+    it('extracts multiple skill references', () => {
+      const content =
+        'Use /tlc:build then /tlc:review. Also Skill(skill="tlc:plan").';
+      const refs = extractSkillRefs(content);
+      expect(refs).toContain('tlc:build');
+      expect(refs).toContain('tlc:review');
+      expect(refs).toContain('tlc:plan');
+      expect(refs).toHaveLength(3);
+    });
+
+    it('deduplicates repeated skill refs', () => {
+      const content = 'Run /tlc:build and /tlc:build again';
+      expect(extractSkillRefs(content)).toEqual(['tlc:build']);
+    });
+
+    it('returns empty array for empty string', () => {
+      expect(extractSkillRefs('')).toEqual([]);
+    });
+
+    it('handles single-quoted Skill() calls', () => {
+      expect(extractSkillRefs("Skill(skill='tlc:deploy')")).toEqual([
+        'tlc:deploy',
+      ]);
+    });
+  });
+
+  describe('validateModuleRefs', () => {
+    it('returns no errors when files exist', () => {
+      const mockFs = {
+        existsSync: () => true,
+      };
+      const errors = validateModuleRefs(['./lib/foo'], '/project', {
+        fs: mockFs,
+      });
+      expect(errors).toEqual([]);
+    });
+
+    it('returns error when file is missing', () => {
+      const mockFs = {
+        existsSync: () => false,
+      };
+      const errors = validateModuleRefs(['./lib/foo'], '/project', {
+        fs: mockFs,
+      });
+      expect(errors).toEqual([
+        { type: 'missing-module', ref: './lib/foo' },
+      ]);
+    });
+
+    it('checks with .js extension fallback', () => {
+      const checked = [];
+      const mockFs = {
+        existsSync: (p) => {
+          checked.push(p);
+          return false;
+        },
+      };
+      validateModuleRefs(['./lib/foo'], '/project', { fs: mockFs });
+      // Should check both with and without .js
+      expect(checked.some((p) => p.endsWith('foo'))).toBe(true);
+      expect(checked.some((p) => p.endsWith('foo.js'))).toBe(true);
+    });
+
+    it('returns no errors for empty refs', () => {
+      const errors = validateModuleRefs([], '/project', {
+        fs: { existsSync: () => false },
+      });
+      expect(errors).toEqual([]);
+    });
+
+    it('reports multiple missing modules', () => {
+      const mockFs = { existsSync: () => false };
+      const errors = validateModuleRefs(
+        ['./lib/a', './lib/b'],
+        '/project',
+        { fs: mockFs }
+      );
+      expect(errors).toHaveLength(2);
+      expect(errors[0].ref).toBe('./lib/a');
+      expect(errors[1].ref).toBe('./lib/b');
+    });
+  });
+
+  describe('validateSkillRefs', () => {
+    it('returns no errors when skill files exist', () => {
+      const mockFs = {
+        existsSync: () => true,
+      };
+      const errors = validateSkillRefs(['tlc:build'], '/skills', {
+        fs: mockFs,
+      });
+      expect(errors).toEqual([]);
+    });
+
+    it('returns error when skill file is missing', () => {
+      const mockFs = {
+        existsSync: () => false,
+      };
+      const errors = validateSkillRefs(['tlc:build'], '/skills', {
+        fs: mockFs,
+      });
+      expect(errors).toEqual([
+        { type: 'missing-skill', ref: 'tlc:build' },
+      ]);
+    });
+
+    it('maps skill name to correct file path', () => {
+      const checked = [];
+      const mockFs = {
+        existsSync: (p) => {
+          checked.push(p);
+          return true;
+        },
+      };
+      validateSkillRefs(['tlc:build'], '/skills', { fs: mockFs });
+      expect(checked[0]).toMatch(/build\.md$/);
+    });
+
+    it('returns no errors for empty refs', () => {
+      const errors = validateSkillRefs([], '/skills', {
+        fs: { existsSync: () => false },
+      });
+      expect(errors).toEqual([]);
+    });
+  });
+
+  describe('validateSkill', () => {
+    it('returns valid for clean content', () => {
+      const result = validateSkill('Just plain text, no refs.', {
+        projectDir: '/project',
+        skillDir: '/skills',
+        fs: { existsSync: () => true },
+      });
+      expect(result).toEqual({ valid: true, errors: [] });
+    });
+
+    it('returns invalid with errors for broken module refs', () => {
+      const content = "```js\nrequire('./lib/nonexistent');\n```";
+      const result = validateSkill(content, {
+        projectDir: '/project',
+        skillDir: '/skills',
+        fs: { existsSync: () => false },
+      });
+      expect(result.valid).toBe(false);
+      expect(result.errors).toHaveLength(1);
+      expect(result.errors[0]).toEqual({
+        type: 'missing-module',
+        ref: './lib/nonexistent',
+      });
+    });
+
+    it('returns invalid with errors for broken skill refs', () => {
+      const content = 'Run /tlc:nonexistent to start.';
+      const result = validateSkill(content, {
+        projectDir: '/project',
+        skillDir: '/skills',
+        fs: { existsSync: () => false },
+      });
+      expect(result.valid).toBe(false);
+      expect(result.errors).toHaveLength(1);
+      expect(result.errors[0]).toEqual({
+        type: 'missing-skill',
+        ref: 'tlc:nonexistent',
+      });
+    });
+
+    it('aggregates both module and skill errors', () => {
+      const content = [
+        '```js',
+        "require('./lib/missing');",
+        '```',
+        'Use /tlc:fake to run.',
+      ].join('\n');
+      const result = validateSkill(content, {
+        projectDir: '/project',
+        skillDir: '/skills',
+        fs: { existsSync: () => false },
+      });
+      expect(result.valid).toBe(false);
+      expect(result.errors).toHaveLength(2);
+      expect(result.errors.find((e) => e.type === 'missing-module')).toBeTruthy();
+      expect(result.errors.find((e) => e.type === 'missing-skill')).toBeTruthy();
+    });
+
+    it('returns valid when all refs exist', () => {
+      const content = [
+        '```js',
+        "require('./lib/real');",
+        '```',
+        'Use /tlc:build to run.',
+      ].join('\n');
+      const result = validateSkill(content, {
+        projectDir: '/project',
+        skillDir: '/skills',
+        fs: { existsSync: () => true },
+      });
+      expect(result).toEqual({ valid: true, errors: [] });
+    });
+  });
+});

package/server/lib/standards/standards-injector.js

@@ -66,6 +66,12 @@ This project follows TLC (Test-Led Coding) standards. See [CODING-STANDARDS.md](
 2. No hardcoded URLs or config - Use environment variables
 3. No magic strings - Define constants in \`constants/\` folder
 4. JSDoc required on all public members
+5. No direct \`process.env\` - All config through a validated config module
+6. Ownership checks on every data-access endpoint - Auth alone is not enough
+7. Never expose secrets in responses - API keys and tokens are write-only
+8. Hash sensitive data at rest - OTPs, reset tokens, session secrets
+9. Escape all HTML output - No raw interpolation of user values
+10. Use DI - Never manually instantiate services with \`new\`
 
 See [CODING-STANDARDS.md](./CODING-STANDARDS.md) for complete standards.
 `;

package/server/lib/test-selector.js

@@ -0,0 +1,127 @@
+/**
+ * Diff-Based Test Selection
+ * Map test files to their source dependencies and select only affected tests
+ * when source files change.
+ */
+
+/**
+ * Parse `// @depends path/to/file.js` comments from test file content.
+ * Supports multiple @depends lines and comma-separated paths on a single line.
+ *
+ * @param {string} testContent - The raw content of a test file
+ * @returns {string[]} Array of dependency paths extracted from @depends comments
+ */
+function parseDependsComment(testContent) {
+  if (!testContent) return [];
+
+  const results = [];
+  const lines = testContent.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    // Only match lines that start with a comment marker
+    if (!trimmed.startsWith('//')) continue;
+
+    const match = trimmed.match(/^\/\/\s*@depends\s+(.+)$/);
+    if (!match) continue;
+
+    const pathsPart = match[1];
+    const paths = pathsPart.split(',').map((p) => p.trim()).filter(Boolean);
+    results.push(...paths);
+  }
+
+  return results;
+}
+
+/**
+ * Read each test file and extract @depends comments to build a mapping
+ * from test files to their source dependencies.
+ *
+ * @param {string[]} testFiles - Array of test file paths
+ * @param {object} options - Options object
+ * @param {function} options.readFile - Async function to read file contents (path) => string
+ * @returns {Promise<Map<string, string[]>>} Map from test file path to dependency paths
+ */
+async function buildTestMap(testFiles, options = {}) {
+  if (!testFiles || testFiles.length === 0) return new Map();
+
+  const { readFile } = options;
+  if (!readFile) {
+    throw new Error('options.readFile is required');
+  }
+
+  const map = new Map();
+
+  for (const testFile of testFiles) {
+    try {
+      const content = await readFile(testFile);
+      const deps = parseDependsComment(content);
+      map.set(testFile, deps);
+    } catch {
+      // If we can't read the file, treat as no-depends (conservative)
+      map.set(testFile, []);
+    }
+  }
+
+  return map;
+}
+
+/**
+ * Given a list of changed source files and a test map, return the test files
+ * whose dependencies include any changed file. Tests with no @depends
+ * annotation are always included (conservative approach).
+ *
+ * @param {string[]} changedFiles - Array of changed source file paths
+ * @param {Map<string, string[]>} testMap - Map from test file to dependency paths
+ * @returns {string[]} Array of affected test file paths
+ */
+function getAffectedTests(changedFiles, testMap) {
+  if (!testMap || testMap.size === 0) return [];
+  if (!changedFiles || !Array.isArray(changedFiles)) {
+    // Conservative fallback: run ALL tests when diff is unavailable
+    return [...testMap.keys()];
+  }
+
+  const changedSet = new Set(changedFiles);
+  const affected = [];
+
+  for (const [testFile, deps] of testMap) {
+    // Always include test files that were themselves changed in the diff
+    if (changedSet.has(testFile)) {
+      affected.push(testFile);
+      continue;
+    }
+
+    // No @depends means always include (conservative)
+    if (deps.length === 0) {
+      affected.push(testFile);
+      continue;
+    }
+
+    // Include if any dependency is in the changed set
+    const isAffected = deps.some((dep) => changedSet.has(dep));
+    if (isAffected) {
+      affected.push(testFile);
+    }
+  }
+
+  return affected;
+}
+
+/**
+ * Format a human-readable summary of test selection results.
+ *
+ * @param {number} affected - Number of affected (selected) tests
+ * @param {number} total - Total number of tests
+ * @returns {string} Human-readable selection summary
+ */
+function formatSelection(affected, total) {
+  if (affected === total) {
+    return `Running all ${total} tests`;
+  }
+
+  const skipped = total - affected;
+  return `Running ${affected} of ${total} tests (${skipped} skipped — dependencies unchanged)`;
+}
+
+module.exports = { parseDependsComment, buildTestMap, getAffectedTests, formatSelection };