fiber_audit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 77fa4ea6790d065dbe69e5cbda2b0753dc2d1c1baa1983717fd00e3bab37b8c8
+  data.tar.gz: 5fd00521ad7ff862aede23b0f9abe9e9f126be7b967e2a3f2e364c9ffc5191c6
+SHA512:
+  metadata.gz: 1849f2cf6a7abc30f3cf20c95689c2b5e8a32574908c472f5d685fa05267aabaaefdfc65a6e31f249ce03c7175d458c57eccd0bb945194dadd58cd89bff38fd9
+  data.tar.gz: fa902948a9e4d517b77cd4bf33dc50b1082f4ba69d8ea406262101e6baef5c583aa256208ba72eca0d9985b3668d868d7252bec4de24efd118fd0d9c4d9c3411

data/.fiber-audit.example.yml

@@ -0,0 +1,33 @@
+# FiberAudit v0.1 static-analysis configuration
+static:
+  # Globs are evaluated from the detected project root.
+  include:
+    - app/**/*.rb
+    - lib/**/*.rb
+    - config/**/*.rb
+  exclude:
+    - vendor/**/*
+    - tmp/**/*
+    - node_modules/**/*
+    - db/schema.rb
+
+  # Optional YAML suppressions. Every entry must include a reason.
+  # suppressions_path: .fiber-audit-suppressions.yml
+
+rules:
+  # Disable an individual rule.
+  FA1007:
+    enabled: false
+
+  # Override severity before the execution-context ceiling is applied.
+  FA1003:
+    severity: low
+
+report:
+  # Reserved output formats supported by v0.1. The CLI emits one format per run.
+  formats:
+    - text
+    - json
+
+  # critical, high, medium, low, or info. Default low hides info findings.
+  min_severity: low

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 0.1.0 (2026-08-02)
+
+First static-only release of FiberAudit. Requires Ruby 3.3 or newer.
+
+### Added
+
+- Rubydex-backed semantic indexing behind a FiberAudit-owned adapter.
+- Prism call-site extraction with conservative receiver inference and stable,
+  project-relative fingerprints.
+- Rails-aware execution contexts for requests, middleware, callbacks, views,
+  jobs, WebSockets, boot, tests, and Rake tasks.
+- Seven static rules:
+  - FA1001 blocking subprocess operations
+  - FA1002 thread waits
+  - FA1003 thread-oriented synchronization
+  - FA1004 thread-local state
+  - FA1005 explicit `IO.select`
+  - FA1006 direct sockets
+  - FA1007 synchronous request-path HTTP
+- Deterministic text and JSON reports using schema version 1.0.
+- Inline and YAML suppressions with mandatory reasons.
+- Project detection, per-rule configuration, minimum-severity filtering, and
+  CI-friendly exit codes.
+- `static`, `list-rules`, `explain`, and `version` CLI commands.
+
+### Scope
+
+Version 0.1.0 does not perform runtime analysis and never emits unconditional
+`PASS`. Every report states that PASS cannot be granted without runtime
+coverage.

data/README.md

@@ -0,0 +1,150 @@
+# FiberAudit
+
+FiberAudit audits Ruby and Rails code for operations that can block the thread
+running a Fiber scheduler. Version 0.1.0 performs static analysis only.
+
+> **Static-only disclaimer:** This is a static-only audit. PASS cannot be
+> granted without runtime coverage.
+
+## Requirements and installation
+
+FiberAudit v0.1.0 supports Ruby 3.3 and 3.4.
+
+```sh
+gem install fiber_audit
+```
+
+Or add it to a bundle and run `bundle install`:
+
+```ruby
+gem "fiber_audit", require: false
+```
+
+## Quick start
+
+Run from a project directory or any directory beneath it:
+
+```sh
+fiber-audit static
+```
+
+FiberAudit walks upward to find the nearest `Gemfile`, `gems.rb`, or
+`config/application.rb`. It loads `.fiber-audit.yml` from that root when the
+file exists.
+
+```text
+fiber-audit static [--format text|json] [--config PATH] [--out PATH]
+                   [--min-severity LEVEL] [--no-color]
+fiber-audit list-rules
+fiber-audit explain FA1001
+fiber-audit version
+```
+
+Output defaults to text on a TTY and JSON when piped. `--out PATH` defaults to
+JSON, writes only the report to that file, and prints a one-line confirmation.
+Explicit `--format` always wins.
+
+## Shipped rules
+
+| ID | Detects | Default severity |
+|---|---|---|
+| FA1001 | Blocking subprocess operations | high |
+| FA1002 | `Thread#join` and `Thread#value` | high |
+| FA1003 | Thread-oriented synchronization | medium |
+| FA1004 | Thread-local state access | high/medium |
+| FA1005 | Explicit `IO.select`/`Kernel.select` | medium |
+| FA1006 | Direct socket construction | medium |
+| FA1007 | Synchronous HTTP in request-like contexts | high |
+
+Use `fiber-audit explain <RULE_ID>` for exact targets and remediation.
+
+## Configuration
+
+Copy `.fiber-audit.example.yml` to `.fiber-audit.yml` in the project root.
+Paths and globs are rooted at the detected project. An explicit `--config`
+path is resolved from the directory where the command was invoked.
+
+```yaml
+static:
+  include:
+    - app/**/*.rb
+    - lib/**/*.rb
+    - config/**/*.rb
+  exclude:
+    - vendor/**/*
+    - tmp/**/*
+    - db/schema.rb
+  suppressions_path: .fiber-audit-suppressions.yml
+
+rules:
+  FA1007:
+    enabled: false
+  FA1003:
+    severity: low
+
+report:
+  formats: [text, json]
+  min_severity: low
+```
+
+`--min-severity` overrides `report.min_severity` for one run. Severity ordering
+is `critical`, `high`, `medium`, `low`, `info`; findings below the threshold
+are omitted and do not affect the exit code. The default `low` threshold keeps
+informational findings silent.
+
+## Suppressions
+
+Every suppression requires a non-empty reason. Directive-looking text inside
+strings, heredocs, or regular expressions is ignored.
+
+Suppress one line:
+
+```ruby
+system(command) # fiber-audit:disable FA1001 -- trusted maintenance command
+```
+
+Suppress a block:
+
+```ruby
+# fiber-audit:disable FA1003 -- protected legacy boundary
+mutex.synchronize { update_record }
+# fiber-audit:enable FA1003
+```
+
+A separate YAML file can suppress by rule and optionally by symbol or
+operation. Point `static.suppressions_path` at the file:
+
+```yaml
+suppressions:
+  - rule: FA1001
+    symbol: Reports::Generator#call
+    operation: Open3.capture3
+    reason: isolated worker process with an external timeout
+```
+
+Missing reasons and invalid configuration return exit code 2.
+
+## Static statuses
+
+- `FAIL` — at least one critical or high finding.
+- `REVIEW` — a medium finding, or a non-informational low/unknown-confidence
+  finding.
+- `PASS_WITH_WARNINGS` — only low or informational findings.
+- `NO_FINDINGS` — no findings at the configured threshold.
+
+FiberAudit never emits unconditional `PASS` in v0.1.0.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | No active finding at or above the configured threshold |
+| 1 | One or more active findings at or above the threshold |
+| 2 | Invalid options, configuration, analysis, or report output |
+| 3 | Reserved; never emitted by v0.1.0 |
+
+Source parse errors are included in report data while analysis continues on
+other files.
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for implementation boundaries and the
+future runtime-analysis architecture.

data/bin/fiber-audit

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'fiber_audit/cli'
+exit FiberAudit::CLI.start(ARGV)

data/lib/fiber_audit/audit.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative 'errors'
+require_relative 'findings/severity'
+require_relative 'findings/confidence'
+require_relative 'findings/location'
+require_relative 'findings/evidence'
+require_relative 'findings/finding'
+require_relative 'findings/collection'
+require_relative 'suppressions/parser'
+require_relative 'suppressions/store'
+require_relative 'execution_context'
+require_relative 'static/semantic_index'
+require_relative 'static/call_site'
+require_relative 'static/call_site_extractor'
+require_relative 'static/execution_context_resolver'
+require_relative 'static/rules/built_ins'
+
+module FiberAudit
+  # Wave R4 WP-7: Audit coordinator.
+  #
+  # Orchestrates the complete static analysis workflow:
+  #   1. Expand/clean root
+  #   2. Resolve target files (include/exclude globs, Ruby only, sorted, deduped)
+  #   3. Build SemanticIndex(root:)
+  #   4. Extract call sites with absolute paths (unchanged)
+  #   5. Copy call sites and parse errors to root-relative paths (portable)
+  #   6. Resolve execution contexts on root-relative call sites
+  #   7. Parse inline suppressions with root-relative paths
+  #   8. Parse YAML suppressions (relative to root unless absolute)
+  #   9. Run enabled rules via Collection publication
+  #  10. Apply suppressions and min_severity filter
+  #  11. Determine status and build immutable Result
+  #
+  class Audit
+    Coverage = Data.define(:analysed_files, :total_call_sites, :rules_run)
+    Result = Data.define(:findings, :suppressed, :parse_errors, :coverage, :status)
+
+    # Status constants
+    STATUS_FAIL                 = 'FAIL'
+    STATUS_REVIEW               = 'REVIEW'
+    STATUS_PASS_WITH_WARNINGS   = 'PASS_WITH_WARNINGS'
+    STATUS_NO_FINDINGS          = 'NO_FINDINGS'
+
+    def initialize(configuration:, root:)
+      @configuration = configuration
+      expanded_root = Pathname.new(root).expand_path.cleanpath
+      raise ArgumentError, "audit root is not a directory: #{expanded_root}" unless expanded_root.directory?
+
+      @root = expanded_root.realpath
+      freeze
+    end
+
+    attr_reader :root
+
+    def call
+      pipeline = run_pipeline
+      active, suppressed = pipeline.fetch(:store).apply(pipeline.fetch(:findings))
+      filtered_active = filter_by_severity(active)
+      filtered_suppressed = filter_by_severity(suppressed)
+
+      build_result(pipeline, filtered_active, filtered_suppressed)
+    end
+
+    private
+
+    # ── File resolution ──────────────────────────────────────────────
+
+    # Resolve files using include/exclude globs.
+    # Returns sorted, deduplicated array of absolute paths to regular .rb files.
+    def resolve_files
+      included = expand_include_globs
+      excluded = expand_exclude_globs
+
+      excluded_lookup = excluded.to_h { |file| [file, true] }
+
+      included
+        .reject { |file| excluded_lookup.key?(File.expand_path(file)) }
+        .select { |file| inside_root?(file) }
+        .map { |file| File.expand_path(file) }
+        .uniq
+        .sort
+    end
+
+    def expand_include_globs
+      @configuration.static_include.flat_map do |pattern|
+        Dir.glob(File.join(@root.to_s, pattern))
+           .select { |f| File.file?(f) && f.end_with?('.rb') }
+      end
+    end
+
+    def expand_exclude_globs
+      @configuration.static_exclude.flat_map do |pattern|
+        Dir.glob(File.join(@root.to_s, pattern)).map { |file| File.expand_path(file) }
+      end
+    end
+
+    def inside_root?(path)
+      expanded = File.expand_path(path)
+      expanded == @root.to_s || expanded.start_with?("#{@root}#{File::SEPARATOR}")
+    end
+
+    def run_pipeline
+      files = resolve_files
+      semantic_index = build_semantic_index
+      extraction = extract_call_sites(files, semantic_index)
+      call_sites = relativize_call_sites(extraction.call_sites)
+      context_resolver = build_context_resolver(semantic_index)
+      enabled_rules = build_enabled_rules(semantic_index, context_resolver)
+
+      {
+        files: files,
+        extraction: extraction,
+        parse_errors: relativize_parse_errors(extraction.parse_errors),
+        store: build_suppression_store(files),
+        enabled_rules: enabled_rules,
+        findings: run_rules(enabled_rules, context_resolver.resolve_all(call_sites: call_sites))
+      }
+    end
+
+    def build_result(pipeline, active, suppressed)
+      coverage = Coverage.new(
+        analysed_files: pipeline.fetch(:files).size,
+        total_call_sites: pipeline.fetch(:extraction).call_sites.size,
+        rules_run: pipeline.fetch(:enabled_rules).size
+      )
+
+      Result.new(
+        findings: active.dup.freeze,
+        suppressed: suppressed.dup.freeze,
+        parse_errors: pipeline.fetch(:parse_errors).dup.freeze,
+        coverage: coverage,
+        status: determine_status(active)
+      )
+    end
+
+    # ── Semantic index ───────────────────────────────────────────────
+
+    def build_semantic_index
+      Static::SemanticIndex.new(root: @root.to_s).build
+    end
+
+    # ── Call site extraction ─────────────────────────────────────────
+
+    # CallSiteExtractor receives absolute file paths exactly unchanged.
+    def extract_call_sites(files, semantic_index)
+      Static::CallSiteExtractor.new(
+        files: files,
+        semantic_index: semantic_index
+      ).call
+    end
+
+    # ── Path relativization ──────────────────────────────────────────
+
+    # Copy call sites to immutable root-relative paths (inside-root only).
+    def relativize_call_sites(call_sites)
+      call_sites.map do |cs|
+        rel_path = to_root_relative(cs.path)
+        cs.class.new(
+          path: rel_path,
+          line: cs.line,
+          column: cs.column,
+          receiver_source: cs.receiver_source,
+          receiver_constant: cs.receiver_constant,
+          method_name: cs.method_name,
+          arguments: cs.arguments,
+          enclosing_symbol: cs.enclosing_symbol,
+          nesting: cs.nesting,
+          execution_context: cs.execution_context,
+          resolution: cs.resolution,
+          confidence: cs.confidence
+        )
+      end
+    end
+
+    # Copy parse errors to immutable root-relative paths (inside-root only).
+    def relativize_parse_errors(parse_errors)
+      parse_errors.map do |pe|
+        rel_path = to_root_relative(pe.path)
+        Static::CallSiteExtractor::ParseError.new(
+          path: rel_path,
+          message: pe.message,
+          line: pe.line
+        )
+      end
+    end
+
+    # Convert absolute path to root-relative, inside-root only.
+    def to_root_relative(absolute_path)
+      return absolute_path unless absolute_path
+
+      root_str = @root.to_s
+      if absolute_path == root_str || absolute_path.start_with?("#{root_str}/")
+        Pathname.new(absolute_path).relative_path_from(@root).to_s
+      else
+        absolute_path
+      end
+    end
+
+    # ── Context resolution ───────────────────────────────────────────
+
+    def build_context_resolver(semantic_index)
+      Static::ExecutionContextResolver.new(workspace: semantic_index)
+    end
+
+    # ── Suppressions ─────────────────────────────────────────────────
+
+    def build_suppression_store(files)
+      Suppressions::Store.new(
+        inline_suppressions: parse_inline_suppressions(files),
+        yaml_suppressions: parse_yaml_suppressions
+      )
+    end
+
+    # Parse inline suppressions with root-relative path while reading absolute file.
+    def parse_inline_suppressions(files)
+      files.flat_map do |absolute_path|
+        content = File.read(absolute_path)
+        relative_path = to_root_relative(absolute_path)
+        Suppressions::Parser.parse_inline(relative_path, content)
+      end
+    end
+
+    # YAML suppressions path relative to root unless absolute.
+    def parse_yaml_suppressions
+      suppressions_path = @configuration.suppressions_path
+      return [] unless suppressions_path
+
+      yaml_path = if Pathname.new(suppressions_path).absolute?
+                    suppressions_path
+                  else
+                    File.join(@root.to_s, suppressions_path)
+                  end
+
+      Suppressions::Parser.parse_yaml(yaml_path)
+    end
+
+    # ── Rules ────────────────────────────────────────────────────────
+
+    def build_enabled_rules(semantic_index, context_resolver)
+      registry = Static::Rules::BuiltIns.registry(
+        workspace: semantic_index,
+        context_resolver: context_resolver
+      )
+      registry.enabled_for(@configuration)
+    end
+
+    # Run all enabled rules; collect findings via Collection publication.
+    def run_rules(enabled_rules, call_sites)
+      findings = enabled_rules.flat_map { |rule| rule.analyze(call_sites: call_sites) }
+      Collection.new(findings).to_a
+    end
+
+    # ── Severity filtering ───────────────────────────────────────────
+
+    def filter_by_severity(findings)
+      min_index = Severity.index(@configuration.min_severity)
+      findings.select { |f| Severity.index(f.severity) <= min_index }
+    end
+
+    # ── Status determination ─────────────────────────────────────────
+
+    # FAIL:                any critical or high severity
+    # REVIEW:              any medium, or low with unknown confidence
+    # PASS_WITH_WARNINGS:  nonempty low/info remainder
+    # NO_FINDINGS:         empty findings
+    # Never PASS.
+    def determine_status(findings)
+      return STATUS_NO_FINDINGS if findings.empty?
+
+      severities = findings.map(&:severity)
+
+      return STATUS_FAIL if severities.any? { |s| %i[critical high].include?(s) }
+      return STATUS_REVIEW if severities.include?(:medium)
+      return STATUS_REVIEW if findings.any? { |finding| review_confidence?(finding) }
+
+      has_low_or_info = findings.any? { |finding| %i[low info].include?(finding.severity) }
+      return STATUS_PASS_WITH_WARNINGS if has_low_or_info
+
+      STATUS_NO_FINDINGS
+    end
+
+    def review_confidence?(finding)
+      finding.severity != :info && %i[low unknown].include?(finding.confidence)
+    end
+  end
+end