fchek 1.0.0

package/lib/convention.js

@@ -0,0 +1,526 @@
+'use strict';
+
+/**
+ * convention.js — scan project for coding conventions
+ *
+ * Extracts "the rules of this project" automatically:
+ *   - error handling patterns
+ *   - naming conventions
+ *   - test locations and naming
+ *   - import style
+ *   - async patterns
+ *   - logging style
+ *
+ * Gives AI agents the project's actual patterns so new code fits in.
+ */
+
+const path   = require('path');
+const fs     = require('fs');
+const { output, ok, fail } = require('./output');
+
+const HELP = `
+fchek convention <project_dir>
+
+Scan a project and extract its coding conventions.
+Call this at the start of a task so new code matches existing patterns.
+
+Detects:
+  - Error handling style (try/except, Result<>, custom exceptions...)
+  - Naming conventions (snake_case, camelCase, PascalCase...)
+  - Test file locations and naming patterns
+  - Import/require style
+  - Async patterns (async/await, callbacks, promises...)
+  - Logging style (print, console.log, log crate, tracing...)
+  - Config/env loading patterns
+
+Examples:
+  fchek convention .
+  fchek convention src/
+`.trim();
+
+const IGNORED_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'target', '__pycache__', '.venv', 'vendor']);
+
+function readFile(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch { return ''; }
+}
+
+const EXT_GROUPS = {
+  python:     ['.py'],
+  javascript: ['.js', '.mjs', '.cjs', '.jsx'],
+  typescript: ['.ts', '.tsx'],
+  rust:       ['.rs'],
+  c:          ['.c', '.cpp', '.cc', '.h', '.hpp'],
+  go:         ['.go'],
+  csharp:     ['.cs'],
+};
+
+function collectFiles(dir, exts) {
+  const results = [];
+  function walk(d) {
+    let entries;
+    try { entries = fs.readdirSync(d); } catch { return; }
+    for (const name of entries) {
+      if (IGNORED_DIRS.has(name) || name.startsWith('.')) continue;
+      const full = path.join(d, name);
+      const stat = fs.statSync(full);
+      if (stat.isDirectory()) walk(full);
+      else if (exts.includes(path.extname(name).toLowerCase())) results.push(full);
+    }
+  }
+  walk(dir);
+  return results;
+}
+
+function detectLangs(dir) {
+  const found = [];
+  for (const [lang, exts] of Object.entries(EXT_GROUPS)) {
+    if (collectFiles(dir, exts).length > 0) found.push(lang);
+  }
+  return found;
+}
+
+// ─── Counters / scorers ───────────────────────────────────────────────────────
+
+function countMatches(lines, patterns) {
+  const counts = {};
+  for (const { name, regex } of patterns) {
+    counts[name] = lines.filter(l => regex.test(l)).length;
+  }
+  return counts;
+}
+
+function topN(obj, n) {
+  return Object.entries(obj)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, n)
+    .filter(([, v]) => v > 0)
+    .map(([k, v]) => ({ pattern: k, occurrences: v }));
+}
+
+// ─── Python conventions ───────────────────────────────────────────────────────
+
+function analyzePython(files) {
+  let lines = [];
+  let testFiles = [];
+  let allNames = { snake: 0, camel: 0, pascal: 0 };
+
+  for (const f of files) {
+    const content = readFile(f);
+    lines.push(...content.split('\n'));
+    if (path.basename(f).startsWith('test_') || path.basename(f).endsWith('_test.py')) {
+      testFiles.push(f);
+    }
+  }
+
+  const errorHandling = countMatches(lines, [
+    { name: 'try/except',            regex: /^\s*try:/ },
+    { name: 'raise Exception',       regex: /raise\s+\w*Exception/ },
+    { name: 'raise custom',          regex: /raise\s+[A-Z]\w+Error/ },
+    { name: 'except broad (bare)',   regex: /except\s*:/ },
+    { name: 'logging.error',         regex: /logging\.(error|exception|warning)/ },
+  ]);
+
+  const asyncPatterns = countMatches(lines, [
+    { name: 'async def',      regex: /async\s+def/ },
+    { name: 'await',          regex: /\bawait\b/ },
+    { name: 'asyncio.run',    regex: /asyncio\.run/ },
+    { name: 'ThreadPoolExecutor', regex: /ThreadPoolExecutor/ },
+  ]);
+
+  const importStyle = countMatches(lines, [
+    { name: 'from X import Y',  regex: /^from\s+\w/ },
+    { name: 'import X',         regex: /^import\s+\w/ },
+    { name: 'relative import',  regex: /^from\s+\./ },
+  ]);
+
+  const logging = countMatches(lines, [
+    { name: 'print()',           regex: /\bprint\s*\(/ },
+    { name: 'logging module',    regex: /\blogging\.\w+\(/ },
+    { name: 'loguru',            regex: /\blogger\.\w+\(/ },
+    { name: 'structlog',         regex: /\bstructlog\b/ },
+  ]);
+
+  // Naming: count function names
+  for (const line of lines) {
+    const m = line.match(/def\s+([a-zA-Z_]\w*)/);
+    if (!m) continue;
+    const name = m[1];
+    if (/^[a-z][a-z0-9_]*$/.test(name)) allNames.snake++;
+    else if (/^[a-z][a-zA-Z0-9]+$/.test(name)) allNames.camel++;
+    else if (/^[A-Z][a-zA-Z0-9]+$/.test(name)) allNames.pascal++;
+  }
+
+  const namingStyle = Object.entries(allNames).sort((a, b) => b[1] - a[1])[0]?.[0] || 'snake_case';
+
+  return {
+    lang: 'python',
+    test_files: testFiles.length,
+    test_locations: testFiles.slice(0, 5).map(f => path.relative(process.cwd(), f)),
+    naming_style: namingStyle,
+    error_handling:  topN(errorHandling, 3),
+    async_patterns:  topN(asyncPatterns, 3),
+    import_style:    topN(importStyle, 2),
+    logging_style:   topN(logging, 2),
+  };
+}
+
+// ─── JavaScript/TypeScript conventions ───────────────────────────────────────
+
+function analyzeJs(files) {
+  let lines = [];
+  let testFiles = [];
+
+  for (const f of files) {
+    const content = readFile(f);
+    lines.push(...content.split('\n'));
+    const base = path.basename(f);
+    if (base.includes('.test.') || base.includes('.spec.') || f.includes('__tests__')) {
+      testFiles.push(f);
+    }
+  }
+
+  const errorHandling = countMatches(lines, [
+    { name: 'try/catch',         regex: /\btry\s*\{/ },
+    { name: 'Promise.catch',     regex: /\.catch\s*\(/ },
+    { name: 'custom Error class',regex: /class\s+\w+Error\s+extends/ },
+    { name: 'Result pattern',    regex: /\{\s*ok\s*:|success\s*:/ },
+    { name: 'console.error',     regex: /console\.error/ },
+  ]);
+
+  const asyncPatterns = countMatches(lines, [
+    { name: 'async/await',       regex: /\basync\s+function|\basync\s+\(/ },
+    { name: 'Promise chain',     regex: /\.then\s*\(/ },
+    { name: 'callback style',    regex: /function\s*\(err,?\s*\w*\)/ },
+  ]);
+
+  const importStyle = countMatches(lines, [
+    { name: 'ES modules (import)', regex: /^import\s+/ },
+    { name: 'CommonJS (require)',  regex: /require\s*\(/ },
+  ]);
+
+  const logging = countMatches(lines, [
+    { name: 'console.log',  regex: /console\.log\s*\(/ },
+    { name: 'console.info', regex: /console\.info\s*\(/ },
+    { name: 'winston/pino', regex: /\b(?:winston|pino|logger)\.\w+\(/ },
+    { name: 'debug module', regex: /\bdebug\s*\(/ },
+  ]);
+
+  // Naming conventions
+  const funcNames = { camel: 0, pascal: 0, snake: 0 };
+  for (const line of lines) {
+    const m = line.match(/function\s+([a-zA-Z_]\w*)|const\s+([a-zA-Z_]\w*)\s*=/);
+    const name = m?.[1] || m?.[2];
+    if (!name) continue;
+    if (/^[a-z][a-zA-Z0-9]+$/.test(name)) funcNames.camel++;
+    else if (/^[A-Z][a-zA-Z0-9]+$/.test(name)) funcNames.pascal++;
+    else if (/^[a-z][a-z0-9_]+$/.test(name)) funcNames.snake++;
+  }
+  const namingStyle = Object.entries(funcNames).sort((a, b) => b[1] - a[1])[0]?.[0] || 'camelCase';
+
+  return {
+    lang: testFiles.some(f => f.endsWith('.ts') || f.endsWith('.tsx')) ? 'typescript' : 'javascript',
+    test_files:    testFiles.length,
+    test_locations: testFiles.slice(0, 5).map(f => path.relative(process.cwd(), f)),
+    naming_style:  namingStyle,
+    error_handling:  topN(errorHandling, 3),
+    async_patterns:  topN(asyncPatterns, 2),
+    import_style:    topN(importStyle, 1),
+    logging_style:   topN(logging, 2),
+  };
+}
+
+// ─── Rust conventions ─────────────────────────────────────────────────────────
+
+function analyzeRust(files) {
+  let lines = [];
+  let testFiles = [];
+
+  for (const f of files) {
+    const content = readFile(f);
+    lines.push(...content.split('\n'));
+    if (f.includes('/tests/') || content.includes('#[cfg(test)]')) testFiles.push(f);
+  }
+
+  const errorHandling = countMatches(lines, [
+    { name: 'Result<T, E>',       regex: /Result</ },
+    { name: '? operator',         regex: /\?\s*;|\?\s*$/ },
+    { name: 'unwrap()',            regex: /\.unwrap\s*\(\s*\)/ },
+    { name: 'expect()',            regex: /\.expect\s*\(/ },
+    { name: 'custom Error enum',  regex: /enum\s+\w+Error/ },
+    { name: 'anyhow/thiserror',   regex: /anyhow|thiserror/ },
+    { name: 'panic!()',            regex: /\bpanic!\s*\(/ },
+  ]);
+
+  const asyncPatterns = countMatches(lines, [
+    { name: 'async fn',          regex: /\basync\s+fn/ },
+    { name: 'tokio',             regex: /\btokio\b/ },
+    { name: 'async-std',         regex: /async_std/ },
+  ]);
+
+  const logging = countMatches(lines, [
+    { name: 'println!()',  regex: /\bprintln!\s*\(/ },
+    { name: 'log crate',   regex: /\b(?:info|warn|error|debug)!\s*\(/ },
+    { name: 'tracing',     regex: /\btracing::/ },
+    { name: 'eprintln!()', regex: /\beprintln!\s*\(/ },
+  ]);
+
+  const unwrapCount = errorHandling['unwrap()'] || 0;
+  const resultCount = errorHandling['Result<T, E>'] || 0;
+  const errorStyle  = unwrapCount > resultCount ? 'unwrap-heavy (consider ? operator)'
+    : resultCount > 0 ? 'Result<T,E> with ? operator' : 'panic-based';
+
+  return {
+    lang: 'rust',
+    test_files: testFiles.length,
+    test_locations: testFiles.slice(0, 5).map(f => path.relative(process.cwd(), f)),
+    naming_style: 'snake_case (Rust standard)',
+    error_handling:  topN(errorHandling, 4),
+    error_style_summary: errorStyle,
+    async_patterns:  topN(asyncPatterns, 2),
+    logging_style:   topN(logging, 2),
+  };
+}
+
+// ─── C/C++ conventions ────────────────────────────────────────────────────────
+
+function analyzeC(files) {
+  let lines = [];
+  let testFiles = [];
+
+  for (const f of files) {
+    const content = readFile(f);
+    lines.push(...content.split('\n'));
+    const base = path.basename(f).toLowerCase();
+    if (base.startsWith('test_') || base.includes('_test.') || f.includes('/test') || f.includes('\\test')) {
+      testFiles.push(f);
+    }
+  }
+
+  const errorHandling = countMatches(lines, [
+    { name: 'return error code',  regex: /\breturn\s+(-?\d+|NULL|nullptr|EXIT_FAILURE|false)\s*;/ },
+    { name: 'errno',              regex: /\berrno\b/ },
+    { name: 'throw (C++)',        regex: /\bthrow\s+/ },
+    { name: 'try/catch (C++)',    regex: /\btry\s*\{/ },
+    { name: 'assert()',           regex: /\bassert\s*\(/ },
+    { name: 'exit()',             regex: /\bexit\s*\(/ },
+    { name: 'perror()',           regex: /\bperror\s*\(/ },
+  ]);
+
+  const logging = countMatches(lines, [
+    { name: 'printf',    regex: /\bprintf\s*\(/ },
+    { name: 'fprintf',   regex: /\bfprintf\s*\(/ },
+    { name: 'std::cout', regex: /std::cout\s*<</ },
+    { name: 'spdlog',    regex: /\bspdlog::/ },
+  ]);
+
+  const naming = { snake: 0, camel: 0, pascal: 0 };
+  for (const line of lines) {
+    const m = line.match(/^(?:static\s+|inline\s+)?(?:[\w:*&<>]+\s+)+([a-zA-Z_]\w*)\s*\([^;]*\)\s*\{?\s*$/);
+    const name = m?.[1];
+    if (!name || ['if', 'for', 'while', 'switch', 'return', 'main'].includes(name)) continue;
+    if (/^[a-z][a-z0-9_]+$/.test(name))  naming.snake++;
+    else if (/^[a-z][a-zA-Z0-9]+$/.test(name)) naming.camel++;
+    else if (/^[A-Z][a-zA-Z0-9]+$/.test(name)) naming.pascal++;
+  }
+  const namingStyle = Object.entries(naming).sort((a, b) => b[1] - a[1])[0]?.[0] || 'snake_case';
+
+  const isCpp = files.some(f => ['.cpp', '.cc', '.hpp'].includes(path.extname(f).toLowerCase()));
+
+  return {
+    lang: isCpp ? 'cpp' : 'c',
+    test_files:     testFiles.length,
+    test_locations: testFiles.slice(0, 5).map(f => path.relative(process.cwd(), f)),
+    naming_style:   namingStyle,
+    error_handling: topN(errorHandling, 4),
+    logging_style:  topN(logging, 2),
+    note: isCpp ? 'C++ project (exceptions detected)' : 'C project (error codes style)',
+  };
+}
+
+// ─── Go conventions ───────────────────────────────────────────────────────────
+
+function analyzeGo(files) {
+  let lines = [];
+  let testFiles = [];
+
+  for (const f of files) {
+    const content = readFile(f);
+    lines.push(...content.split('\n'));
+    if (path.basename(f).endsWith('_test.go')) testFiles.push(f);
+  }
+
+  const errorHandling = countMatches(lines, [
+    { name: 'if err != nil',  regex: /if\s+err\s*!=\s*nil/ },
+    { name: 'panic()',        regex: /\bpanic\s*\(/ },
+    { name: 'return err',     regex: /\breturn\s+.*\berr\b/ },
+    { name: 'log.Fatal',      regex: /log\.Fatal/ },
+    { name: 'errors.New',     regex: /errors\.New/ },
+    { name: 'fmt.Errorf',     regex: /fmt\.Errorf/ },
+    { name: 'errors.As/Is',   regex: /errors\.(As|Is)\s*\(/ },
+  ]);
+
+  const asyncPatterns = countMatches(lines, [
+    { name: 'goroutine (go keyword)', regex: /\bgo\s+\w+\s*\(/ },
+    { name: 'channel',                regex: /\bmake\s*\(\s*chan\b/ },
+    { name: 'select statement',       regex: /\bselect\s*\{/ },
+    { name: 'sync.WaitGroup',         regex: /sync\.WaitGroup/ },
+    { name: 'context.Context',        regex: /context\.Context/ },
+  ]);
+
+  const logging = countMatches(lines, [
+    { name: 'fmt.Println',  regex: /fmt\.Print/ },
+    { name: 'log package',  regex: /\blog\.\w+\(/ },
+    { name: 'zap',          regex: /\bzap\b/ },
+    { name: 'logrus',       regex: /\blogrus\b/ },
+    { name: 'slog (Go1.21)',regex: /\bslog\.\w+\(/ },
+  ]);
+
+  return {
+    lang: 'go',
+    test_files:     testFiles.length,
+    test_locations: testFiles.slice(0, 5).map(f => path.relative(process.cwd(), f)),
+    naming_style:   'camelCase for unexported, PascalCase for exported (Go standard)',
+    error_handling: topN(errorHandling, 4),
+    async_patterns: topN(asyncPatterns, 3),
+    logging_style:  topN(logging, 2),
+  };
+}
+
+// ─── General project structure ────────────────────────────────────────────────
+
+// ─── C# conventions ───────────────────────────────────────────────────────────
+
+function analyzeCSharp(files) {
+  let lines = [];
+  let testFiles = [];
+
+  for (const f of files) {
+    const content = readFile(f);
+    lines.push(...content.split('\n'));
+    const base = path.basename(f).toLowerCase();
+    if (base.includes('test') || base.includes('spec') || f.includes('Tests')) {
+      testFiles.push(f);
+    }
+  }
+
+  const errorHandling = countMatches(lines, [
+    { name: 'try/catch',            regex: /\btry\s*\{/ },
+    { name: 'throw exception',      regex: /\bthrow\s+new\s+\w+Exception/ },
+    { name: 'custom exception',     regex: /class\s+\w+Exception\s*:/ },
+    { name: 'Result pattern',       regex: /\bResult[<(]/ },
+    { name: 'Task.FromException',   regex: /Task\.FromException/ },
+    { name: 'ArgumentException',    regex: /\bArgumentException\b/ },
+  ]);
+
+  const asyncPatterns = countMatches(lines, [
+    { name: 'async/await',   regex: /\basync\s+Task|\basync\s+void/ },
+    { name: 'await',         regex: /\bawait\b/ },
+    { name: 'Task<T>',       regex: /Task<\w+>/ },
+    { name: 'CancellationToken', regex: /CancellationToken/ },
+  ]);
+
+  const logging = countMatches(lines, [
+    { name: 'ILogger',         regex: /\bILogger\w*\b/ },
+    { name: 'Console.Write',   regex: /Console\.(Write|WriteLine)\s*\(/ },
+    { name: 'Serilog',         regex: /\bSerilog\b|Log\.(Information|Warning|Error|Debug)\s*\(/ },
+    { name: 'NLog',            regex: /\bNLog\b|logger\.(Info|Warn|Error|Debug)\s*\(/ },
+    { name: 'Debug.WriteLine', regex: /Debug\.WriteLine\s*\(/ },
+  ]);
+
+  const naming = { pascal: 0, camel: 0 };
+  for (const line of lines) {
+    // Method names
+    const m = line.match(/\b(public|private|protected|internal)\s+(?:static\s+)?(?:async\s+)?(?:[\w<>?\[\]]+\s+)+([A-Z][a-zA-Z0-9]*)\s*\(/);
+    if (m) naming.pascal++;
+    const m2 = line.match(/\b(private|protected)\s+(?:readonly\s+)?(?:[\w<>?\[\]]+\s+)+(_?[a-z][a-zA-Z0-9]*)\s*[=;{]/);
+    if (m2) naming.camel++;
+  }
+
+  // Detect framework
+  const allLines = lines.join('\n');
+  const framework =
+    /\bMicrosoft\.AspNetCore\b/.test(allLines) ? 'ASP.NET Core' :
+    /\bSystem\.Windows\b|\bWPF\b|\.xaml\b/i.test(allLines) ? 'WPF' :
+    /\bXamarin\b|\bMAUI\b/.test(allLines) ? 'MAUI/Xamarin' :
+    /\bUnityEngine\b/.test(allLines) ? 'Unity' :
+    /\bBlazor\b/.test(allLines) ? 'Blazor' :
+    'Unknown';
+
+  return {
+    lang: 'csharp',
+    framework,
+    test_files:     testFiles.length,
+    test_locations: testFiles.slice(0, 5).map(f => path.relative(process.cwd(), f)),
+    naming_style:   'PascalCase for public members, camelCase/_camelCase for private fields (C# standard)',
+    error_handling: topN(errorHandling, 4),
+    async_patterns: topN(asyncPatterns, 3),
+    logging_style:  topN(logging, 2),
+    note: `Framework detected: ${framework}. For deeper analysis use Roslyn analyzers / dotnet-format / SonarAnalyzer.`,
+  };
+}
+
+function analyzeStructure(dir) {
+  const hasDir = (d) => fs.existsSync(path.join(dir, d));
+  const hasFile = (f) => fs.existsSync(path.join(dir, f));
+
+  const structure = {
+    has_tests_dir:  hasDir('tests') || hasDir('test') || hasDir('spec'),
+    has_src_dir:    hasDir('src'),
+    has_docs_dir:   hasDir('docs') || hasDir('doc'),
+    has_ci:         hasDir('.github/workflows') || hasFile('.travis.yml') || hasFile('.gitlab-ci.yml'),
+    has_linter_config: hasFile('.eslintrc') || hasFile('.eslintrc.js') || hasFile('ruff.toml')
+      || hasFile('.flake8') || hasFile('pyproject.toml') || hasFile('.clang-format'),
+    has_env_example: hasFile('.env.example') || hasFile('.env.sample'),
+    has_docker:      hasFile('Dockerfile') || hasFile('docker-compose.yml'),
+    config_files: [],
+  };
+
+  for (const f of ['.env.example', 'pyproject.toml', 'Cargo.toml', 'package.json', 'go.mod', 'CMakeLists.txt']) {
+    if (hasFile(f)) structure.config_files.push(f);
+  }
+
+  return structure;
+}
+
+// ─── Entry point ─────────────────────────────────────────────────────────────
+
+async function run(args) {
+  if (args.length === 0 || args[0] === '--help') { console.log(HELP); return; }
+
+  const target = args[0];
+  if (!fs.existsSync(target)) return output(fail(`Not found: ${target}`));
+
+  const dir  = path.resolve(fs.statSync(target).isDirectory() ? target : path.dirname(target));
+  const langs = detectLangs(dir);
+
+  if (langs.length === 0) {
+    return output(fail(`No supported source files found in: ${target}`));
+  }
+
+  const results = [];
+  const structure = analyzeStructure(dir);
+
+  for (const lang of langs) {
+    const exts  = EXT_GROUPS[lang];
+    const files = collectFiles(dir, exts);
+    if (!files.length) continue;
+
+    if (lang === 'python')                                   results.push(analyzePython(files));
+    else if (lang === 'javascript' || lang === 'typescript') results.push(analyzeJs(files));
+    else if (lang === 'rust')                                results.push(analyzeRust(files));
+    else if (lang === 'c')                                   results.push(analyzeC(files));
+    else if (lang === 'go')                                  results.push(analyzeGo(files));
+    else if (lang === 'csharp')                              results.push(analyzeCSharp(files));
+  }
+
+  output(ok({
+    project:    dir,
+    languages:  langs,
+    structure,
+    conventions: results,
+    summary: `Project uses: ${langs.join(', ')}. ` +
+      results.map(r => `${r.lang}: naming=${r.naming_style || 'n/a'}`).join('; '),
+  }));
+}
+
+module.exports = { run };