ref-agents 1.0.0__py3-none-any.whl

ref_agents/config/languages/csharp.yaml

@@ -0,0 +1,153 @@
+# C# Language Configuration for REF Agents
+# Used by debt_scanner, ai_pattern_detector, compliance tools
+
+language: csharp
+extensions: [".cs", ".csx"]
+parser: regex
+
+# Debt detection patterns
+debt_patterns:
+  todo_fixme:
+    description: "TODO/FIXME comments indicate incomplete work"
+    severity: medium
+    pattern: "//\\s*(TODO|FIXME|XXX|HACK|BUG)[\\s:]+(.+)"
+    suggestion: "Address the TODO or create a tracked issue"
+
+  async_void:
+    description: "async void swallows exceptions; callers cannot await or catch"
+    severity: critical
+    pattern: "async\\s+void\\s+\\w+\\s*\\([^)]*\\)"
+    suggestion: "Use async Task instead of async void (exception: event handlers with EventArgs parameter)"
+
+  task_result_wait:
+    description: ".Result and .Wait() block the thread and cause deadlocks in ASP.NET context"
+    severity: critical
+    pattern: "\\.Result\\b|\\.Wait\\(\\)"
+    suggestion: "Use await instead of .Result/.Wait()"
+
+  empty_catch:
+    description: "Empty catch blocks swallow exceptions silently"
+    severity: high
+    pattern: "catch\\s*(?:\\([^)]*\\))?\\s*\\{\\s*\\}"
+    suggestion: "Log or handle the exception; never swallow silently"
+
+  catch_exception:
+    description: "Catching generic Exception masks specific failures"
+    severity: high
+    pattern: "catch\\s*\\(\\s*Exception\\s+"
+    suggestion: "Catch specific exception types: IOException, InvalidOperationException, etc."
+
+  console_write:
+    description: "Console.Write* bypasses structured logging; no levels, rotation, or observability"
+    severity: high
+    pattern: "Console\\.(Write|WriteLine|Error)\\b"
+    suggestion: "Use ILogger<T> injected via DI: _logger.LogInformation(), _logger.LogError()"
+
+  hardcoded_credential:
+    description: "Hardcoded connection strings and passwords are a security vulnerability"
+    severity: critical
+    pattern: "(?i)(ConnectionString|Password|ApiKey|Secret)\\s*=\\s*\"[^\"]{4,}\""
+    suggestion: "Use IConfiguration / environment variables / Azure Key Vault / AWS Secrets Manager"
+
+  gc_collect:
+    description: "Explicit GC.Collect() degrades throughput and indicates a memory management problem"
+    severity: medium
+    pattern: "GC\\.Collect\\s*\\("
+    suggestion: "Remove GC.Collect(). Fix the root cause: IDisposable misuse or large object pinning"
+
+  pragma_warning_disable:
+    description: "#pragma warning disable without inline justification hides real issues"
+    severity: medium
+    pattern: "#pragma\\s+warning\\s+disable(?!\\s+\\d+\\s*//)"
+    suggestion: "Add an inline comment explaining why the warning is suppressed"
+
+  interface_no_i_prefix:
+    description: "Interface name missing 'I' prefix violates .NET naming convention"
+    severity: medium
+    pattern: "\\binterface\\s+(?!I)[A-Z]\\w*"
+    suggestion: "Rename interface to start with 'I' (e.g., IRepository, IService)"
+
+  private_field_no_underscore:
+    description: "Private field missing '_' prefix violates .NET naming convention"
+    severity: low
+    pattern: "private\\s+(?:readonly\\s+)?[\\w<>\\[\\]]+\\s+(?!_)[a-z]\\w*\\s*[;=]"
+    suggestion: "Prefix private fields with underscore: private readonly ILogger _logger"
+
+  magic_numbers:
+    description: "Magic numbers violate DRY and hurt maintainability"
+    severity: low
+    pattern: "(?<![\\w.])\\d{2,}(?![\\w.])"
+    suggestion: "Extract to named constants: private const int MaxRetries = 3"
+
+  missing_xml_doc:
+    description: "Public API missing XML documentation"
+    severity: medium
+    pattern: "^\\s*public\\s+(?!override\\s+string\\s+ToString)(?:(?:static|abstract|virtual|sealed|async|partial)\\s+)*(?!class|interface|struct|record|enum)[\\w<>\\[\\]]+\\s+\\w+\\s*\\("
+    suggestion: "Add XML doc: /// <summary>...</summary> with <param> and <returns>"
+
+# Deprecated API patterns
+deprecated_imports:
+  "System.Threading.Thread.Sleep": "Use Task.Delay with await for async code"
+  "System.Web.HttpContext": "Use Microsoft.AspNetCore.Http.IHttpContextAccessor"
+  "System.Web.Mvc": "Use Microsoft.AspNetCore.Mvc"
+  "System.Web.Http": "Use Microsoft.AspNetCore.Mvc"
+
+# Naming conventions (reference — enforced subset uses regex patterns above)
+naming:
+  generic_names:
+    - data
+    - result
+    - temp
+    - obj
+    - val
+    - item
+    - list
+    - map
+    - str
+    - num
+    - flag
+    - x
+    - y
+    - z
+
+  conventions:
+    classes: PascalCase
+    interfaces: PascalCase with I prefix (e.g. IRepository)
+    methods: PascalCase
+    properties: PascalCase
+    private_fields: _camelCase (underscore prefix)
+    local_variables: camelCase
+    constants: PascalCase (for public) or ALL_CAPS (for private static readonly)
+    namespaces: PascalCase.PascalCase
+
+# Quality thresholds
+thresholds:
+  complexity: 12
+  function_length: 50
+  nesting_depth: 3
+  file_length: 400
+  comment_ratio: 0.3
+  class_ratio: 0.3
+
+# File exclusions
+exclusions:
+  skip_analysis:
+    - "**/.git/**"
+    - "**/bin/**"
+    - "**/obj/**"
+    - "**/.vs/**"
+    - "**/Migrations/**"
+    - "**/.*/**"
+    - "**/packages/**"
+    - "**/node_modules/**"
+
+# AI anti-patterns
+anti_patterns:
+  god_class:
+    description: "Class with too many responsibilities"
+    max_methods: 20
+    max_fields: 15
+
+  copy_paste:
+    description: "Duplicated code blocks"
+    min_block_size: 5

ref_agents/config/languages/java.yaml

@@ -0,0 +1,188 @@
+# Java Language Configuration for REF Agents
+
+language: java
+extensions: [".java"]
+parser: regex
+
+# Debt detection patterns
+debt_patterns:
+  todo_fixme:
+    description: "TODO/FIXME comments indicate incomplete work"
+    severity: medium
+    pattern: "//\\s*(TODO|FIXME|XXX|HACK|BUG)[\\s:]+(.+)"
+    suggestion: "Address the TODO or create a tracked issue"
+
+  empty_catch:
+    description: "Empty catch blocks swallow exceptions"
+    severity: high
+    pattern: "catch\\s*\\([^)]+\\)\\s*\\{\\s*\\}"
+    suggestion: "Log or handle the exception"
+
+  catch_exception:
+    description: "Catching generic Exception masks bugs and catches RuntimeExceptions"
+    severity: high
+    pattern: "catch\\s*\\(\\s*Exception\\s+"
+    suggestion: "Catch specific exceptions: IOException, SQLException, etc."
+
+  catch_throwable:
+    description: "Catching Throwable includes Errors"
+    severity: high
+    pattern: "catch\\s*\\(\\s*Throwable\\s+"
+    suggestion: "Catch Exception, not Throwable"
+
+  system_out:
+    description: "System.out bypasses logging, no levels/rotation/structured output"
+    severity: high
+    pattern: "System\\.(out|err)\\.(print|println)\\("
+    suggestion: "Use SLF4J: logger.info(), logger.error()"
+
+  printStackTrace:
+    description: "printStackTrace sends to stderr"
+    severity: medium
+    pattern: "\\.printStackTrace\\(\\)"
+    suggestion: "Use logger.error with exception"
+
+  raw_types:
+    description: "Raw types bypass generics type safety"
+    severity: medium
+    pattern: "\\b(List|Map|Set|Collection)\\s+\\w+\\s*="
+    suggestion: "Use parameterized types: List<String>"
+
+  string_concat_loop:
+    description: "String concatenation in loops is inefficient"
+    severity: medium
+    pattern: "for.*\\+.*String|while.*\\+.*String"
+    suggestion: "Use StringBuilder"
+
+  public_fields:
+    description: "Public fields break encapsulation"
+    severity: medium
+    pattern: "public\\s+(?!static|final|class|interface|enum)\\w+\\s+\\w+\\s*;"
+    suggestion: "Use private fields with getters/setters"
+
+  magic_numbers:
+    description: "Magic numbers violate DRY and hurt maintainability"
+    severity: medium
+    pattern: "(?<!\\d)[0-9]{2,}(?!\\d)"
+    suggestion: "Extract to named constants (e.g., private static final int MAX_RETRIES = 3)"
+
+  missing_javadoc:
+    description: "Public APIs must be documented for maintainability"
+    severity: medium
+    pattern: "public\\s+(?!class)\\w+.*\\{"
+    suggestion: "Add Javadoc with @param, @return, @throws"
+
+  # Code Quality Patterns
+  unused_import:
+    description: "Unused imports clutter code"
+    severity: low
+    pattern: "^import\\s+.*;"
+    suggestion: "Remove unused imports (IDE can auto-remove)"
+
+  null_pointer_risk:
+    description: "Potential null pointer dereference"
+    severity: high
+    pattern: "\\w+\\.\\w+\\(\\).*\\.\\w+|\\w+\\[.*\\]\\.\\w+"
+    suggestion: "Add null checks or use Optional"
+
+  missing_override:
+    description: "Method overrides without @Override annotation"
+    severity: medium
+    pattern: "public\\s+\\w+\\s+\\w+\\s*\\([^)]*\\)"
+    suggestion: "Add @Override annotation for clarity"
+
+  equals_without_hashcode:
+    description: "Class overrides equals() but not hashCode()"
+    severity: high
+    pattern: "public\\s+boolean\\s+equals"
+    suggestion: "Override hashCode() when overriding equals()"
+
+  final_mutable_collections:
+    description: "Final collections can still be modified"
+    severity: medium
+    pattern: "final\\s+(List|Map|Set|Collection)"
+    suggestion: "Use Collections.unmodifiableList() or ImmutableList"
+
+  string_concatenation:
+    description: "String concatenation in loops is inefficient"
+    severity: medium
+    pattern: "for\\s*\\(.*\\+.*String|while\\s*\\(.*\\+.*String"
+    suggestion: "Use StringBuilder for multiple concatenations"
+
+  magic_string:
+    description: "Magic strings should be constants"
+    severity: medium
+    pattern: "['\"][A-Z_]{3,}['\"]"
+    suggestion: "Extract to named constants"
+
+# Deprecated patterns
+deprecated_imports:
+  "java.util.Date": "Use java.time.LocalDate/LocalDateTime"
+  "java.util.Calendar": "Use java.time API"
+  "java.util.Vector": "Use ArrayList or CopyOnWriteArrayList"
+  "java.util.Hashtable": "Use HashMap or ConcurrentHashMap"
+  "java.util.Stack": "Use Deque (ArrayDeque)"
+  "java.util.StringTokenizer": "Use String.split or Scanner"
+  "sun.misc.BASE64": "Use java.util.Base64"
+
+# Naming conventions
+naming:
+  generic_names:
+    - data
+    - result
+    - temp
+    - obj
+    - val
+    - item
+    - list
+    - map
+    - str
+    - num
+    - flag
+    - x
+    - y
+    - z
+
+  conventions:
+    classes: PascalCase
+    interfaces: PascalCase
+    methods: camelCase
+    variables: camelCase
+    constants: UPPER_SNAKE_CASE
+    packages: lowercase
+
+# Quality thresholds (production-grade)
+thresholds:
+  complexity: 12          # Maintainable, testable code
+  function_length: 50     # Single responsibility
+  nesting_depth: 3        # Readable code
+  file_length: 400        # Encourages class extraction
+  comment_ratio: 0.3
+  class_ratio: 0.3
+
+# File exclusions
+exclusions:
+  # Skip entire analysis (autogenerated, vendor, coverage, hidden dirs, data files)
+  skip_analysis:
+    - "**/.git/**"
+    - "**/target/**"
+    - "**/build/**"
+    - "**/.gradle/**"
+    - "**/.mvn/**"
+    - "**/.*/**"  # Hidden directories
+    - "**/*.json"  # JSON files excluded from complexity checks
+    - "**/vendor/**"
+    - "**/vendors/**"
+    - "**/third-party/**"
+    - "**/third_party/**"
+
+# AI anti-patterns
+anti_patterns:
+  god_class:
+    description: "Class with too many responsibilities"
+    max_methods: 20
+    max_fields: 15
+
+  copy_paste:
+    description: "Duplicated code blocks"
+    min_block_size: 5

ref_agents/config/languages/javascript.yaml

@@ -0,0 +1,172 @@
+# JavaScript Language Configuration for REF Agents
+
+language: javascript
+extensions: [".js", ".jsx", ".mjs", ".cjs"]
+parser: regex
+
+# Debt detection patterns
+debt_patterns:
+  todo_fixme:
+    description: "TODO/FIXME comments indicate incomplete work"
+    severity: medium
+    pattern: "//\\s*(TODO|FIXME|XXX|HACK|BUG)[\\s:]+(.+)"
+    suggestion: "Address the TODO or create a tracked issue"
+
+  var_usage:
+    description: "Using var instead of let/const"
+    severity: medium
+    pattern: "\\bvar\\s+\\w+"
+    suggestion: "Use const for constants, let for variables"
+
+  console_log:
+    description: "console.log leaks to production, use structured logging"
+    severity: high
+    pattern: "console\\.(log|debug|info|warn|error)\\("
+    suggestion: "Use structured logging library (e.g., pino, winston)"
+
+  empty_catch:
+    description: "Empty catch blocks swallow errors"
+    severity: high
+    pattern: "catch\\s*\\([^)]*\\)\\s*\\{\\s*\\}"
+    suggestion: "Handle or log the error"
+
+  eval_usage:
+    description: "eval() is a security risk"
+    severity: critical
+    pattern: "\\beval\\s*\\("
+    suggestion: "Use safer alternatives like JSON.parse"
+
+  document_write:
+    description: "document.write is deprecated"
+    severity: high
+    pattern: "document\\.write\\("
+    suggestion: "Use DOM manipulation methods"
+
+  innerhtml_assignment:
+    description: "innerHTML can cause XSS vulnerabilities"
+    severity: high
+    pattern: "\\.innerHTML\\s*="
+    suggestion: "Use textContent or sanitize input"
+
+  sync_xhr:
+    description: "Synchronous XHR blocks the main thread"
+    severity: high
+    pattern: "XMLHttpRequest.*false\\s*\\)"
+    suggestion: "Use async requests or fetch API"
+
+  # Code Quality Patterns
+  unused_import:
+    description: "Unused imports increase bundle size"
+    severity: low
+    pattern: "^import\\s+.*from|require\\s*\\(['\"].*['\"]\\)"
+    suggestion: "Remove unused imports"
+
+  missing_async_await:
+    description: "Promise not awaited"
+    severity: high
+    pattern: "Promise\\s*\\.(then|catch)\\s*\\("
+    suggestion: "Use async/await for better error handling"
+
+  direct_mutation:
+    description: "Direct state mutation in React/Redux"
+    severity: critical
+    pattern: "\\.(push|pop|shift|unshift|splice|sort|reverse)\\s*\\(|\\w+\\s*=\\s*\\w+\\["
+    suggestion: "Use immutable patterns (spread, map, filter)"
+
+  loose_equality:
+    description: "Using == instead of === loses type safety"
+    severity: medium
+    pattern: "\\s==\\s"
+    suggestion: "Use === for strict equality"
+
+  typeof_undefined:
+    description: "typeof undefined is unnecessary"
+    severity: low
+    pattern: "typeof\\s+\\w+\\s*===\\s*['\"]undefined['\"]"
+    suggestion: "Use !== undefined or optional chaining"
+
+  with_statement:
+    description: "with statement is deprecated and error-prone"
+    severity: high
+    pattern: "\\bwith\\s*\\("
+    suggestion: "Use explicit variable references"
+
+# Deprecated patterns
+deprecated_imports:
+  "jquery": "Consider using vanilla JS or modern frameworks"
+  "underscore": "Use native array methods or lodash-es"
+  "moment": "Use date-fns or dayjs"
+
+# Naming conventions
+naming:
+  generic_names:
+    - data
+    - result
+    - temp
+    - handler
+    - callback
+    - cb
+    - fn
+    - val
+    - obj
+    - arr
+    - x
+    - y
+    - z
+
+  conventions:
+    functions: camelCase
+    classes: PascalCase
+    constants: UPPER_SNAKE_CASE
+    variables: camelCase
+
+# Quality thresholds
+thresholds:
+  complexity: 15
+  function_length: 80
+  nesting_depth: 4
+  file_length: 400
+  comment_ratio: 0.3
+  class_ratio: 0.5
+
+# File exclusions (autogenerated, vendor, coverage, hidden dirs)
+exclusions:
+  # Skip entire analysis (autogenerated, vendor, coverage, hidden dirs)
+  skip_analysis:
+    - "**/node_modules/**"
+    - "**/.next/**"
+    - "**/.nuxt/**"
+    - "**/.cache/**"
+    - "**/.git/**"
+    - "**/coverage/**"
+    - "**/dist/**"
+    - "**/build/**"
+    - "**/.dist/**"
+    - "**/.build/**"
+    - "**/.*/**"  # Hidden directories (e.g., .vscode, .idea)
+    - "**/*.generated.js"
+    - "**/*.generated.jsx"
+    - "**/*.auto.js"
+    - "**/*.auto.jsx"
+    - "**/*.json"  # JSON files excluded from complexity checks
+    - "**/vendor/**"
+    - "**/vendors/**"
+    - "**/third-party/**"
+    - "**/third_party/**"
+
+  # Skip file-level complexity check only (still analyze per-function)
+  file_complexity:
+    - "*.test.js"
+    - "*.test.jsx"
+    - "*.spec.js"
+    - "*.spec.jsx"
+
+# AI anti-patterns
+anti_patterns:
+  callback_hell:
+    description: "Deeply nested callbacks"
+    max_depth: 3
+
+  copy_paste:
+    description: "Duplicated code blocks"
+    min_block_size: 5

ref_agents/config/languages/python.yaml

@@ -0,0 +1,153 @@
+# Python Language Configuration for REF Agents
+# Used by debt_scanner, ai_pattern_detector, compliance tools
+
+language: python
+extensions: [".py", ".pyw", ".pyi"]
+parser: ast
+
+# Debt detection patterns
+debt_patterns:
+  todo_fixme:
+    description: "TODO/FIXME comments indicate incomplete work"
+    severity: medium
+    pattern: "#\\s*(TODO|FIXME|XXX|HACK|BUG)[\\s:]+(.+)"
+    suggestion: "Address the TODO or create a tracked issue"
+
+  bare_except:
+    description: "Bare except catches all exceptions including system exits"
+    severity: critical
+    ast_node: ExceptHandler
+    condition: "node.type is None"
+    suggestion: "Use specific exception types"
+
+  broad_except:
+    description: "except Exception is too broad"
+    severity: high
+    ast_node: ExceptHandler
+    condition: "node.type.id == 'Exception'"
+    suggestion: "Catch specific exceptions like ValueError, TypeError"
+
+  missing_type_hints:
+    description: "Type hints enable static analysis and catch bugs at dev time"
+    severity: high
+    ast_node: FunctionDef
+    condition: "no return type or missing arg types"
+    suggestion: "Add type hints: def func(arg: Type) -> ReturnType"
+
+  missing_docstring:
+    description: "Public APIs must be documented for maintainability"
+    severity: medium
+    ast_node: FunctionDef
+    condition: "not private and no docstring"
+    suggestion: "Add Google/Numpy style docstring with Args/Returns/Raises"
+
+  high_complexity:
+    description: "Function has too many branches"
+    severity: high
+    ast_node: FunctionDef
+    condition: "complexity > threshold"
+    suggestion: "Refactor into smaller functions"
+
+  long_function:
+    description: "Function exceeds line limit"
+    severity: medium
+    ast_node: FunctionDef
+    condition: "lines > threshold"
+    suggestion: "Break into smaller focused functions"
+
+  deep_nesting:
+    description: "Code is nested too deeply"
+    severity: medium
+    ast_node: FunctionDef
+    condition: "nesting > threshold"
+    suggestion: "Use early returns or extract methods"
+
+# Deprecated imports
+deprecated_imports:
+  distutils: "Use setuptools or build instead"
+  imp: "Use importlib instead"
+  optparse: "Use argparse instead"
+  formatter: "Removed in Python 3.10"
+  parser: "Use ast instead"
+  symbol: "Use ast instead"
+  asynchat: "Use asyncio instead"
+  asyncore: "Use asyncio instead"
+  smtpd: "Use aiosmtpd instead"
+  cgi: "Use modern web frameworks"
+  cgitb: "Use proper error handling"
+
+# Naming conventions
+naming:
+  generic_names:
+    - data
+    - result
+    - temp
+    - tmp
+    - handler
+    - manager
+    - helper
+    - utils
+    - misc
+    - stuff
+    - thing
+    - obj
+    - val
+    - var
+    - foo
+    - bar
+    - baz
+    - item
+    - elem
+    - info
+    - x
+    - y
+    - z
+
+  conventions:
+    functions: snake_case
+    classes: PascalCase
+    constants: UPPER_SNAKE_CASE
+    modules: snake_case
+    variables: snake_case
+
+# Quality thresholds (production-grade)
+thresholds:
+  complexity: 12          # Maintainable, testable code
+  function_length: 50     # Single responsibility
+  nesting_depth: 3        # Readable, avoid arrow anti-pattern
+  file_length: 300        # Encourages module extraction
+  comment_ratio: 0.4
+  class_ratio: 0.5
+
+# File exclusions
+exclusions:
+  # Skip entire analysis (autogenerated, vendor, coverage, hidden dirs, data files)
+  skip_analysis:
+    - "**/node_modules/**"
+    - "**/.git/**"
+    - "**/__pycache__/**"
+    - "**/.venv/**"
+    - "**/venv/**"
+    - "**/dist/**"
+    - "**/build/**"
+    - "**/coverage/**"
+    - "**/.*/**"  # Hidden directories
+    - "**/*.json"  # JSON files excluded from complexity checks
+    - "**/vendor/**"
+    - "**/vendors/**"
+    - "**/third-party/**"
+    - "**/third_party/**"
+
+# AI anti-patterns
+anti_patterns:
+  over_abstraction:
+    description: "Too many classes relative to functions"
+    threshold: 0.5
+
+  copy_paste:
+    description: "Duplicated code blocks"
+    min_block_size: 5
+
+  verbose_comments:
+    description: "Excessive comments"
+    max_ratio: 0.4