Devour/.desloppify/subagents/runs/20260224_101201/results/batch-6.raw.txt

{
  "batch": "Full Codebase Sweep",
  "batch_index": 6,
  "assessments": {
    "cross_module_architecture": 72.0,
    "error_consistency": 70.0,
    "abstraction_fitness": 68.0,
    "test_strategy": 64.0,
    "design_coherence": 69.0
  },
  "dimension_notes": {
    "cross_module_architecture": {
      "evidence": [
        "cmd/serve.go calls command handlers directly (runSync, scrapeOne) and mutates command-level globals (scrapeFormat/scrapeOutput/scrapeAllowEmpty and syncForce/syncRebuild/syncSource) before invoking them, coupling RPC transport to CLI flag state.",
        "Source-type detection logic exists in both internal/scraper/scraper.go:92 (DetectSourceType) and cmd/scrape.go:314 (detectSourceType), creating boundary drift for core classification behavior."
      ],
      "impact_scope": "subsystem",
      "fix_scope": "architectural_change",
      "confidence": "high"
    },
    "error_consistency": {
      "evidence": [
        "cmd/serve.go suppresses parse and subsystem errors via `_ = json.Unmarshal(...)` and `state, _ := projectstate.LoadSourceState(...)` / `idxStats, _ := engine.EnsureIndexed(...)`, while sibling paths return wrapped errors.",
        "Startup failure behavior differs across modules: cmd/root.go exits process with os.Exit(1), while internal/quality/plugins/go/plugin.go init() panics on registration failure."
      ],
      "impact_scope": "subsystem",
      "fix_scope": "multi_file_refactor",
      "confidence": "high"
    },
    "abstraction_fitness": {
      "evidence": [
        "Most external scraper implementations repeat near-identical transport/change-detection scaffolding (`fetchPage`, `DetectChanges`, `generateHash`) across files such as internal/scraper/external/reactdocs.go, tsdocs.go, godocs.go, rustdocs.go, and cloudflaredocs.go.",
        "This repeated wrapper structure adds maintenance indirection without policy variance (same HTTP GET + user-agent + status check + body read flow)."
      ],
      "impact_scope": "subsystem",
      "fix_scope": "architectural_change",
      "confidence": "high",
      "sub_axes": {
        "abstraction_leverage": 61.0,
        "indirection_cost": 43.0,
        "interface_honesty": 74.0
      }
    },
    "test_strategy": {
      "evidence": [
        "High-impact command flows lack direct tests: cmd/serve.go, cmd/sync.go, cmd/query.go, cmd/push.go, cmd/verify.go have no file-level tests while they orchestrate indexing/scraping/status behavior.",
        "Most external scrapers are untested at integration unit level (e.g., internal/scraper/external/{godocs,rustdocs,reactdocs,cloudflaredocs,nuxtdocs,...}.go) even though they include custom parsing-to-document mapping and network error handling."
      ],
      "impact_scope": "codebase",
      "fix_scope": "multi_file_refactor",
      "confidence": "high"
    },
    "design_coherence": {
      "evidence": [
        "cmd/serve.go:71-210 centralizes multiple unrelated workflows (query/status/scrape/ask/sync) in one switch, with request parsing, domain orchestration, and response formatting mixed in a single function.",
        "The same function also performs cross-command mutable state choreography (temporarily overriding scrape/sync globals), combining transport logic with command execution mechanics."
      ],
      "impact_scope": "module",
      "fix_scope": "multi_file_refactor",
      "confidence": "high"
    }
  },
  "findings": [
    {
      "dimension": "cross_module_architecture",
      "identifier": "rpc_cli_global_state_coupling",
      "summary": "RPC handlers mutate CLI global flags to execute workflows across command boundaries.",
      "related_files": [
        "cmd/serve.go",
        "cmd/scrape.go",
        "cmd/sync.go"
      ],
      "evidence": [
        "cmd/serve.go sets scrapeFormat/scrapeOutput/scrapeAllowEmpty before calling scrapeOne and restores afterward.",
        "cmd/serve.go sets syncForce/syncRebuild/syncSource before calling runSync and restores afterward."
      ],
      "suggestion": "Extract scrape/sync/query use-cases into stateless service functions (input structs + return structs), call them from both Cobra commands and RPC handlers, and remove shared mutable command globals from runtime execution paths.",
      "confidence": "high",
      "impact_scope": "subsystem",
      "fix_scope": "architectural_change"
    },
    {
      "dimension": "error_consistency",
      "identifier": "silent_error_drops_in_rpc_paths",
      "summary": "Several RPC paths ignore parse/index/state errors, producing inconsistent failure contracts.",
      "related_files": [
        "cmd/serve.go",
        "internal/search/engine.go",
        "internal/projectstate/state.go"
      ],
      "evidence": [
        "cmd/serve.go ignores JSON unmarshal errors for devour_query/devour_sync (`_ = json.Unmarshal(...)`).",
        "cmd/serve.go ignores errors from LoadSourceState and EnsureIndexed, yet reads fields from returned values.",
        "Other command paths generally propagate wrapped errors with `%w`."
      ],
      "suggestion": "Treat request decode, source-state load, and index-check failures uniformly: return explicit wrapped errors from each branch and avoid underscore-discarded errors in RPC handlers.",
      "confidence": "high",
      "impact_scope": "subsystem",
      "fix_scope": "single_edit"
    },
    {
      "dimension": "abstraction_fitness",
      "identifier": "external_scraper_transport_duplication",
      "summary": "External scrapers duplicate the same HTTP fetch/hash/change-detection boilerplate.",
      "related_files": [
        "internal/scraper/external/reactdocs.go",
        "internal/scraper/external/tsdocs.go",
        "internal/scraper/external/godocs.go",
        "internal/scraper/external/rustdocs.go",
        "internal/scraper/external/cloudflaredocs.go"
      ],
      "evidence": [
        "Each scraper reimplements equivalent `fetchPage` with identical request/header/response-body flow.",
        "Each scraper reimplements nearly identical `DetectChanges` and `generateHash` logic."
      ],
      "suggestion": "Introduce a shared base helper (e.g., `fetchPage`, `contentHash`, `detectChanges`) in internal/scraper/external/types.go or a dedicated internal transport module, then keep per-scraper files focused on parser-to-document mapping.",
      "confidence": "high",
      "impact_scope": "subsystem",
      "fix_scope": "multi_file_refactor"
    },
    {
      "dimension": "test_strategy",
      "identifier": "missing_tests_on_orchestration_and_adapters",
      "summary": "Critical orchestration commands and most external adapters have no direct tests.",
      "related_files": [
        "cmd/serve.go",
        "cmd/sync.go",
        "cmd/query.go",
        "internal/scraper/external/godocs.go",
        "internal/scraper/external/reactdocs.go"
      ],
      "evidence": [
        "No *_test.go peers for cmd/serve.go, cmd/sync.go, cmd/query.go despite high-risk orchestration behavior.",
        "Only one external scraper has direct tests while many adapter implementations contain custom mapping and error-path logic."
      ],
      "suggestion": "Add table-driven tests for RPC method branches and error propagation in cmd/serve.go, plus httptest-based adapter contract tests covering fetch failures, parser errors, and document mapping for each external scraper family.",
      "confidence": "high",
      "impact_scope": "codebase",
      "fix_scope": "multi_file_refactor"
    },
    {
      "dimension": "design_coherence",
      "identifier": "serve_handler_multi_responsibility_switch",
      "summary": "Single handler function mixes transport, parsing, orchestration, and mutable state management.",
      "related_files": [
        "cmd/serve.go",
        "cmd/scrape.go",
        "cmd/sync.go",
        "cmd/query.go"
      ],
      "evidence": [
        "handleServeMethod contains method routing plus per-method request schemas, domain calls, and response shaping in one body.",
        "The function coordinates temporary mutation of command globals to reuse CLI code paths."
      ],
      "suggestion": "Split each RPC method into dedicated handler functions (e.g., handleQueryRPC, handleScrapeRPC, handleSyncRPC) that depend on explicit service interfaces instead of command globals.",
      "confidence": "high",
      "impact_scope": "module",
      "fix_scope": "multi_file_refactor"
    }
  ]
}