ref-agents 1.0.0__py3-none-any.whl

ref_agents/config/ai_patterns.yaml

@@ -0,0 +1,101 @@
+# AI Anti-Pattern Detection Configuration
+# Used by ai_pattern_detector.py
+#
+# Customize thresholds and enable/disable specific patterns.
+
+# Patterns to check (comment out to disable)
+enabled_patterns:
+  - over_abstraction
+  - unused_params
+  - generic_naming
+  - verbose_comments
+  - copy_paste_blocks
+
+# Detection thresholds
+thresholds:
+  # Max ratio of classes to functions (0.5 = 1 class per 2 functions)
+  class_to_function_ratio: 0.5
+
+  # Max ratio of comment lines to code lines
+  comment_to_code_ratio: 0.4
+
+  # Hash similarity threshold for copy-paste detection (0.0-1.0)
+  similarity_threshold: 0.85
+
+  # Minimum lines to consider a block for copy-paste analysis
+  min_block_size: 5
+
+# Variable/function names considered too generic
+generic_names:
+  - data
+  - result
+  - temp
+  - tmp
+  - handler
+  - manager
+  - helper
+  - utils
+  - misc
+  - stuff
+  - thing
+  - obj
+  - val
+  - var
+  - foo
+  - bar
+  - baz
+  - item
+  - elem
+  - info
+
+# Severity levels for each pattern type
+severity_weights:
+  over_abstraction: MEDIUM
+  unused_params: LOW
+  generic_naming: LOW
+  verbose_comments: LOW
+  copy_paste_blocks: HIGH
+
+# STORY-TQ-001 M1a: structural test-smell detection.
+# Detector activates when file path matches one of test_path_globs.
+# Findings emit through the standard PatternFinding channel.
+# Phase-transition gate + Critical routing land in M1b.
+test_smells:
+  enabled: true
+  # POSIX globs. Match against project-relative path.
+  test_path_globs:
+    - "tests/**/*.py"
+    - "test_*.py"
+    - "*_test.py"
+  # Files under these names skipped per FR-16.
+  excluded_filenames:
+    - "conftest.py"
+    - "__init__.py"
+  # Substring patterns; any match disqualifies file.
+  excluded_path_substrings:
+    - "/fixtures/"
+    # STORY-TQ-003 M3b: generated smoke tests use `assert x is not None` by design.
+    - "/tests/generated/"
+  patterns:
+    no_assertions:
+      enabled: true
+      severity: HIGH
+    trivial_assertion:
+      enabled: true
+      severity: HIGH
+    mock_called_only:
+      enabled: true
+      severity: HIGH
+    uut_mocked:
+      enabled: true
+      severity: HIGH
+    swallowed_exception:
+      enabled: true
+      severity: HIGH
+    not_none_only:
+      enabled: true
+      # Demoted MEDIUM → LOW (2026-05-25 tune). Baseline showed 35 findings
+      # mostly on legitimate `assert x is None` contract assertions
+      # (e.g. `_detect_old_framework_version` returns None for no signal).
+      # Rule is informational — useful for grep, not blocking.
+      severity: LOW

ref_agents/config/frameworks/angular.yaml

@@ -0,0 +1,104 @@
+# Angular Framework Configuration for REF Agents
+# Extends: typescript.yaml
+
+framework: angular
+base_language: typescript
+
+# Angular-specific debt patterns
+debt_patterns:
+  subscribe_without_unsubscribe:
+    description: "Observable subscriptions should be unsubscribed"
+    severity: high
+    pattern: "\\.subscribe\\("
+    suggestion: "Use async pipe, takeUntil, or unsubscribe in ngOnDestroy"
+
+  any_in_template:
+    description: "Using $any() in templates bypasses type checking"
+    severity: high
+    pattern: "\\$any\\("
+    suggestion: "Fix the type error properly"
+
+  direct_dom_access:
+    description: "Direct DOM access bypasses Angular"
+    severity: high
+    pattern: "document\\.(getElementById|querySelector)"
+    suggestion: "Use ViewChild, Renderer2, or ElementRef"
+
+  missing_trackby:
+    description: "ngFor without trackBy causes performance issues"
+    severity: medium
+    pattern: "\\*ngFor(?!.*trackBy)"
+    suggestion: "Add trackBy function for lists"
+
+  component_too_large:
+    description: "Component has too much logic"
+    severity: medium
+    pattern: "@Component"
+    suggestion: "Split into smaller components or services"
+
+  hardcoded_strings:
+    description: "Hardcoded strings block internationalization and localization"
+    severity: medium
+    pattern: ">\\s*[A-Z][a-z]+.*<"
+    suggestion: "Use Angular i18n or ngx-translate"
+
+  deprecated_http:
+    description: "Using deprecated Http module"
+    severity: high
+    pattern: "import.*from\\s*['\"]@angular/http['\"]"
+    suggestion: "Use HttpClient from @angular/common/http"
+
+  rxjs_compat:
+    description: "Using rxjs-compat (legacy)"
+    severity: medium
+    pattern: "from\\s*['\"]rxjs-compat"
+    suggestion: "Migrate to modern rxjs imports"
+
+  manual_change_detection:
+    description: "Manual change detection often indicates design issues"
+    severity: medium
+    pattern: "ChangeDetectorRef|detectChanges\\(\\)"
+    suggestion: "Use OnPush strategy with async pipe for better performance"
+
+# Angular naming conventions
+naming:
+  generic_names:
+    - data
+    - result
+    - temp
+    - handler
+    - service
+    - component
+    - item
+    - val
+
+  conventions:
+    components: PascalCase + Component suffix
+    services: PascalCase + Service suffix
+    modules: PascalCase + Module suffix
+    directives: camelCase + Directive suffix
+    pipes: camelCase + Pipe suffix
+    files: kebab-case
+
+# Angular-specific thresholds (production-grade)
+thresholds:
+  complexity: 10          # Lower than backend - templates add complexity
+  function_length: 50     # Single responsibility
+  nesting_depth: 3        # Readable code
+  file_length: 300        # Encourages component extraction
+  component_methods: 7    # Components should be focused
+  injected_services: 4    # >4 deps = too many responsibilities
+
+# Angular anti-patterns
+anti_patterns:
+  fat_component:
+    description: "Component with too much business logic"
+    max_methods: 10
+
+  service_in_component:
+    description: "Business logic should be in services"
+    suggestion: "Move logic to injectable service"
+
+  memory_leak:
+    description: "Subscriptions not cleaned up"
+    suggestion: "Use takeUntil pattern or async pipe"

ref_agents/config/frameworks/aspnet.yaml

@@ -0,0 +1,84 @@
+# ASP.NET Core Framework Configuration for REF Agents
+# Extends: csharp.yaml
+
+framework: aspnet
+base_language: csharp
+
+# ASP.NET Core-specific debt patterns
+debt_patterns:
+  missing_cancellation_token:
+    description: "Async action methods without CancellationToken cannot be cancelled by the client"
+    severity: medium
+    pattern: "public\\s+async\\s+Task<.*>\\s+\\w+\\s*\\([^)]*\\)(?![^{]*CancellationToken)"
+    suggestion: "Add CancellationToken cancellationToken = default to async action parameters"
+
+  controller_business_logic:
+    description: "Business logic in controllers violates separation of concerns"
+    severity: high
+    pattern: "\\[(?:HttpGet|HttpPost|HttpPut|HttpDelete|HttpPatch)\\][^}]{300,}"
+    suggestion: "Extract business logic to a service class injected via constructor DI"
+
+  missing_api_controller_attribute:
+    description: "API controllers without [ApiController] lose automatic model validation and problem details"
+    severity: medium
+    pattern: "\\[Route\\(.*\\)\\]\\s*public\\s+class\\s+\\w+Controller(?!.*\\[ApiController\\])"
+    suggestion: "Add [ApiController] attribute above [Route] on all API controllers"
+
+  direct_http_client_instantiation:
+    description: "new HttpClient() bypasses IHttpClientFactory and leaks sockets"
+    severity: high
+    pattern: "new\\s+HttpClient\\s*\\("
+    suggestion: "Inject IHttpClientFactory and use CreateClient() or use typed clients"
+
+  synchronous_io_in_action:
+    description: "Synchronous IO in action methods blocks thread pool threads"
+    severity: high
+    pattern: "public\\s+(?!async)\\s*\\w+\\s+\\w+\\s*\\([^)]*\\)(?=.*Stream|.*File|.*Http)"
+    suggestion: "Make action method async and use async IO APIs"
+
+  hardcoded_cors_wildcard:
+    description: "Wildcard CORS policy is a security risk in production"
+    severity: critical
+    pattern: "\\.AllowAnyOrigin\\(\\)"
+    suggestion: "Specify explicit origins via WithOrigins() for production environments"
+
+  response_caching_on_authenticated:
+    description: "Response caching on authenticated endpoints may leak data across users"
+    severity: high
+    pattern: "\\[ResponseCache\\].*\\[Authorize\\]|\\[Authorize\\].*\\[ResponseCache\\]"
+    suggestion: "Do not cache responses on authenticated endpoints; use private cache-control"
+
+  missing_authorize_attribute:
+    description: "API controller actions without [Authorize] or [AllowAnonymous] may be unintentionally public"
+    severity: medium
+    pattern: "\\[Http(?:Get|Post|Put|Delete|Patch)\\]\\s*public(?!.*\\[Authorize\\]|.*\\[AllowAnonymous\\])"
+    suggestion: "Add [Authorize] or explicit [AllowAnonymous] to all action methods"
+
+# ASP.NET Core naming conventions
+naming:
+  conventions:
+    controllers: PascalCase + Controller suffix
+    services: PascalCase + Service suffix
+    interfaces: I prefix + PascalCase
+    dtos: PascalCase + Request/Response/Dto suffix
+    validators: PascalCase + Validator suffix
+    middleware: PascalCase + Middleware suffix
+
+# ASP.NET Core thresholds
+thresholds:
+  complexity: 10
+  function_length: 40
+  nesting_depth: 3
+  file_length: 300
+  controller_actions: 7
+
+# ASP.NET Core anti-patterns
+anti_patterns:
+  fat_controller:
+    description: "Controller with too many actions or direct data access"
+    max_methods: 8
+
+  service_locator:
+    description: "Resolving services from IServiceProvider manually (service locator anti-pattern)"
+    pattern: "serviceProvider\\.GetService|serviceProvider\\.GetRequiredService"
+    suggestion: "Use constructor injection instead"

ref_agents/config/frameworks/ef_core.yaml

@@ -0,0 +1,81 @@
+# Entity Framework Core Framework Configuration for REF Agents
+# Extends: csharp.yaml
+
+framework: ef_core
+base_language: csharp
+
+# EF Core-specific debt patterns
+debt_patterns:
+  missing_as_no_tracking:
+    description: "Read-only queries without AsNoTracking() load change tracker overhead unnecessarily"
+    severity: medium
+    pattern: "\\.Where\\(|\\.\\.FirstOrDefault\\(|\\.ToList\\(|\\.ToListAsync\\("
+    suggestion: "Add .AsNoTracking() for read-only queries: _context.Orders.AsNoTracking().Where(...)"
+
+  from_sql_raw_interpolation:
+    description: "String interpolation in FromSqlRaw/ExecuteSqlRaw is a SQL injection vulnerability"
+    severity: critical
+    pattern: "FromSqlRaw\\s*\\(\\s*\\$\"|ExecuteSqlRaw\\s*\\(\\s*\\$\""
+    suggestion: "Use FromSqlInterpolated() or parameterized queries with SqlParameter"
+
+  lazy_loading_n_plus_one:
+    description: "Navigation property access without explicit Include() triggers N+1 lazy-loading queries"
+    severity: high
+    pattern: "\\.virtual\\s+\\w+|LazyLoadingEnabled\\s*=\\s*true"
+    suggestion: "Use .Include() / .ThenInclude() for eager loading or projection with .Select()"
+
+  synchronous_db_call:
+    description: "Synchronous EF Core methods block thread pool threads under load"
+    severity: high
+    pattern: "\\.SaveChanges\\(\\)(?!Async)|\\.ToList\\(\\)(?!\\s*;//\\s*acceptable)"
+    suggestion: "Use async variants: SaveChangesAsync(), ToListAsync(), FirstOrDefaultAsync()"
+
+  context_per_request_violation:
+    description: "DbContext instantiated directly instead of via DI — breaks scoped lifetime"
+    severity: high
+    pattern: "new\\s+\\w+DbContext\\s*\\(|new\\s+\\w+Context\\s*\\("
+    suggestion: "Inject DbContext via constructor DI; register with AddDbContext<T>() as Scoped"
+
+  missing_index_hint:
+    description: "Queries on unindexed foreign key columns degrade at scale"
+    severity: medium
+    pattern: "\\.Where\\([^)]*Id\\s*==|\\[ForeignKey\\]"
+    suggestion: "Ensure foreign key columns have database indexes via HasIndex() in OnModelCreating"
+
+  unbounded_include:
+    description: "Include() without projection loads entire related collection into memory"
+    severity: medium
+    pattern: "\\.Include\\([^)]+\\)\\.Include\\([^)]+\\)\\.Include\\("
+    suggestion: "Use .Select() projection to load only required fields from related entities"
+
+  hardcoded_connection_string:
+    description: "Connection string in DbContext OnConfiguring instead of DI configuration"
+    severity: critical
+    pattern: "optionsBuilder\\.UseSqlServer\\s*\\(\\s*\"[^\"]{10,}\""
+    suggestion: "Read connection string from IConfiguration; configure in Program.cs AddDbContext"
+
+# EF Core naming conventions
+naming:
+  conventions:
+    db_context: PascalCase + Context suffix (e.g. ApplicationDbContext)
+    entities: PascalCase, singular noun
+    migrations: auto-generated, do not rename
+    repositories: PascalCase + Repository suffix
+
+# EF Core thresholds
+thresholds:
+  complexity: 12
+  function_length: 50
+  nesting_depth: 3
+  file_length: 400
+
+# EF Core anti-patterns
+anti_patterns:
+  repository_over_context:
+    description: "Repository wrapping DbContext adds abstraction with no benefit for simple CRUD"
+    suggestion: "Use DbContext directly in services for simple cases; add repositories only for complex query encapsulation"
+
+  generic_repository:
+    description: "Generic Repository<T> forces all entities through the same interface"
+    pattern: "class.*Repository<T>|IRepository<T>"
+    suggestion: "Use specific repositories or query objects for complex queries"

ref_agents/config/frameworks/react.yaml

@@ -0,0 +1,111 @@
+# React Framework Configuration for REF Agents
+# Extends: typescript.yaml or javascript.yaml
+
+framework: react
+base_language: typescript  # or javascript
+
+# React-specific debt patterns
+debt_patterns:
+  missing_key_prop:
+    description: "List items should have unique key props"
+    severity: high
+    pattern: "map\\s*\\([^)]+\\)\\s*=>\\s*<(?!.*key=)"
+    suggestion: "Add key prop to list items"
+
+  inline_styles:
+    description: "Inline styles block theming, caching, and responsive design"
+    severity: medium
+    pattern: "style=\\{\\{"
+    suggestion: "Use CSS modules, styled-components, or Tailwind"
+
+  direct_dom_manipulation:
+    description: "Direct DOM manipulation bypasses React"
+    severity: high
+    pattern: "document\\.(getElementById|querySelector|getElementsBy)"
+    suggestion: "Use refs and React state"
+
+  missing_dependency:
+    description: "useEffect missing dependencies"
+    severity: high
+    pattern: "useEffect\\([^,]+,\\s*\\[\\s*\\]\\)"
+    suggestion: "Add all dependencies or use useCallback/useMemo"
+
+  state_mutation:
+    description: "Direct state mutation"
+    severity: critical
+    pattern: "this\\.state\\.\\w+\\s*="
+    suggestion: "Use setState or useState setter"
+
+  prop_drilling:
+    description: "Props passed through many components"
+    severity: medium
+    pattern: "props\\.\\w+.*props\\.\\w+"
+    suggestion: "Use Context API or state management"
+
+  anonymous_function_prop:
+    description: "Anonymous functions cause unnecessary re-renders on every parent render"
+    severity: medium
+    pattern: "on\\w+=\\{\\([^)]*\\)\\s*=>"
+    suggestion: "Extract to useCallback for stable references"
+
+  missing_error_boundary:
+    description: "Error boundaries catch rendering errors"
+    severity: medium
+    pattern: "class.*extends.*Component(?!.*componentDidCatch)"
+    suggestion: "Add error boundary for graceful error handling"
+
+  deprecated_lifecycle:
+    description: "Deprecated lifecycle methods"
+    severity: high
+    pattern: "componentWillMount|componentWillReceiveProps|componentWillUpdate"
+    suggestion: "Use componentDidMount, getDerivedStateFromProps, getSnapshotBeforeUpdate"
+
+# React naming conventions
+naming:
+  generic_names:
+    - data
+    - result
+    - temp
+    - handler
+    - state
+    - props
+    - item
+    - val
+
+  conventions:
+    components: PascalCase
+    hooks: camelCase (use prefix)
+    utils: camelCase
+    constants: UPPER_SNAKE_CASE
+    files: PascalCase for components
+
+# React-specific thresholds (production-grade)
+thresholds:
+  complexity: 10          # Lower than backend - JSX adds visual complexity
+  function_length: 50     # Components should be focused and testable
+  nesting_depth: 3
+  file_length: 200        # Encourages component extraction
+  component_props: 5      # >5 props = prop drilling smell
+  hooks_per_component: 4  # >4 hooks = component doing too much
+
+# React anti-patterns (production-grade)
+anti_patterns:
+  prop_drilling:
+    description: "Props passed through too many levels"
+    max_levels: 2
+    severity: medium
+
+  large_component:
+    description: "Component is too large - split into smaller, testable units"
+    max_lines: 100  # Stricter than before
+    severity: medium
+
+  too_many_hooks:
+    description: "Too many hooks = component doing too much"
+    max_hooks: 4
+    severity: medium
+
+  too_many_props:
+    description: "Too many props indicates component needs decomposition"
+    max_props: 5
+    severity: medium

ref_agents/config/frameworks/spring_boot.yaml

@@ -0,0 +1,117 @@
+# Spring Boot Framework Configuration for REF Agents
+# Extends: java.yaml
+
+framework: spring_boot
+base_language: java
+
+# Spring Boot-specific debt patterns
+debt_patterns:
+  field_injection:
+    description: "Field injection hides dependencies, breaks immutability, makes testing hard"
+    severity: high
+    pattern: "@Autowired\\s+private"
+    suggestion: "Use constructor injection (Spring auto-wires single constructor)"
+
+  missing_transactional:
+    description: "Data modification without transaction risks partial writes"
+    severity: high
+    pattern: "@Service(?!.*@Transactional)"
+    suggestion: "Add @Transactional to service class or methods"
+
+  entity_in_controller:
+    description: "Exposing JPA entities in API responses"
+    severity: high
+    pattern: "@RestController.*@Entity|ResponseEntity<.*Entity>"
+    suggestion: "Use DTOs for API responses"
+
+  n_plus_one:
+    description: "Potential N+1 query problem"
+    severity: high
+    pattern: "@OneToMany(?!.*fetch.*EAGER|.*@BatchSize)"
+    suggestion: "Use @BatchSize, JOIN FETCH, or EntityGraph"
+
+  missing_validation:
+    description: "Unvalidated input is security risk and causes unclear errors"
+    severity: high
+    pattern: "@RequestBody(?!.*@Valid)"
+    suggestion: "Add @Valid annotation for request validation"
+
+  hardcoded_credentials:
+    description: "Credentials should be externalized"
+    severity: critical
+    pattern: "password\\s*=\\s*['\"][^'\"]+['\"]"
+    suggestion: "Use @Value or ConfigurationProperties"
+
+  missing_exception_handler:
+    description: "Controllers should have exception handling"
+    severity: medium
+    pattern: "@RestController(?!.*@ExceptionHandler|@ControllerAdvice)"
+    suggestion: "Add @ControllerAdvice for global exception handling"
+
+  deprecated_web_security:
+    description: "WebSecurityConfigurerAdapter is deprecated"
+    severity: high
+    pattern: "extends\\s+WebSecurityConfigurerAdapter"
+    suggestion: "Use SecurityFilterChain bean"
+
+  blocking_in_reactive:
+    description: "Blocking calls in reactive pipeline"
+    severity: high
+    pattern: "\\.block\\(\\)|Mono\\.just.*\\.subscribe"
+    suggestion: "Use reactive operators throughout"
+
+  circular_dependency:
+    description: "Circular dependency between beans"
+    severity: high
+    pattern: "@Lazy.*@Autowired|@Autowired.*@Lazy"
+    suggestion: "Refactor to remove circular dependency"
+
+  sql_injection:
+    description: "Potential SQL injection"
+    severity: critical
+    pattern: "createQuery\\(.*\\+|createNativeQuery\\(.*\\+"
+    suggestion: "Use parameterized queries or JPA Criteria"
+
+# Spring naming conventions
+naming:
+  generic_names:
+    - data
+    - result
+    - response
+    - request
+    - entity
+    - dto
+    - service
+    - repository
+
+  conventions:
+    controllers: PascalCase + Controller suffix
+    services: PascalCase + Service suffix
+    repositories: PascalCase + Repository suffix
+    entities: PascalCase
+    dtos: PascalCase + DTO/Request/Response suffix
+    config: PascalCase + Config suffix
+
+# Spring-specific thresholds (production-grade)
+thresholds:
+  complexity: 12          # Maintainable, testable code
+  function_length: 50     # Single responsibility
+  nesting_depth: 3        # Readable code
+  file_length: 300        # Single responsibility
+  controller_methods: 7   # REST resources should be focused
+  service_dependencies: 4 # >4 deps = too many responsibilities
+
+# Spring anti-patterns
+anti_patterns:
+  god_service:
+    description: "Service with too many responsibilities"
+    max_methods: 15
+    max_dependencies: 5
+
+  anemic_domain:
+    description: "Entities with only getters/setters"
+    suggestion: "Add domain logic to entities"
+
+  transaction_boundary:
+    description: "Transaction spanning multiple services"
+    suggestion: "Review transaction boundaries"