refactor(ai): split the 1180-line ai.go into focused files #6

2026-04-18T12:13:57-07:00

nsatoshi commented

2026-04-18 12:13:57 -07:00

Summary

PR #6 of the 11-PR completion sequence. Decomposes backend/api/rest/ai.go — the review's single largest file at 1,180 lines — into six purpose-built files inside the same package. Pure move: no logic changes, no new public API, no route changes, no caller edits required.

New file layout

file	lines	role
`ai.go`	198	HTTP handlers + feature flags + exported `AI*` DTOs
`ai_context.go`	381	`buildAIContext` + indexed-DB queries (stats / tx / address / block) + regex patterns + `extractBlockReference`
`ai_routes.go`	139	`queryAIRoutes` + `filterAIRouteMatches` + `routeMatchesQuery` + `normalizeHexString`
`ai_docs.go`	136	`loadAIDocSnippets` + `findAIWorkspaceRoot` + `scanDocForTerms` + `buildDocSearchTerms`
`ai_xai.go`	267	xAI / OpenAI request+response types + `normalizeAIMessages` + `latestUserMessage` + `callXAIChatCompletions` + `parseXAIError` + `extractOutputText`
`ai_helpers.go`	112	pure utilities: `firstRegexMatch`, `compactStringMap`, `compactAnyMap`, `stringValue`, `stringSliceValue`, `uniqueStrings`, `clipString`, `fileExists`

ai_runtime.go (rate limiter + metrics + audit log) is unchanged.

Why same package, not `internal/ai/*`

The original completion prompt sketched an internal/ai/* split. Keeping the files inside backend/api/rest/ instead:

Preserves the *Server method receivers (handleAIChat, buildAIContext, queryAIRoutes, callXAIChatCompletions) without having to export Server.db, Server.chainID, Server.aiRateLimiter, Server.aiMetrics, and the logAIRequest / allowAIRequest helpers.
Keeps this PR a diff-only move that any reviewer can verify with diff -q <(cat ai_*.go) <(git show master:backend/api/rest/ai.go).
Leaves open a follow-up that does the package extraction with a thin ai.Service interface once the rest of the hardening sequence lands.

Verification

go build ./... — clean.
go vet ./... — clean.
go test ./api/rest/... — PASS.
staticcheck ./... — clean on the SA* correctness family. The U1000 and S1016 tails are pre-existing and already disabled in the backend/staticcheck.conf introduced in PR #5.

Completion criterion advanced

6. Backend maintainability — "No single Go file exceeds a few hundred lines; AI/LLM plumbing is separated from HTTP handlers; context-building is separated from upstream calls."

## Summary PR #6 of the 11-PR completion sequence. Decomposes `backend/api/rest/ai.go` — the review's single largest file at 1,180 lines — into six purpose-built files inside the same package. Pure move: no logic changes, no new public API, no route changes, no caller edits required. ## New file layout | file | lines | role | | --- | ---:| --- | | `ai.go` | 198 | HTTP handlers + feature flags + exported `AI*` DTOs | | `ai_context.go` | 381 | `buildAIContext` + indexed-DB queries (stats / tx / address / block) + regex patterns + `extractBlockReference` | | `ai_routes.go` | 139 | `queryAIRoutes` + `filterAIRouteMatches` + `routeMatchesQuery` + `normalizeHexString` | | `ai_docs.go` | 136 | `loadAIDocSnippets` + `findAIWorkspaceRoot` + `scanDocForTerms` + `buildDocSearchTerms` | | `ai_xai.go` | 267 | xAI / OpenAI request+response types + `normalizeAIMessages` + `latestUserMessage` + `callXAIChatCompletions` + `parseXAIError` + `extractOutputText` | | `ai_helpers.go` | 112 | pure utilities: `firstRegexMatch`, `compactStringMap`, `compactAnyMap`, `stringValue`, `stringSliceValue`, `uniqueStrings`, `clipString`, `fileExists` | `ai_runtime.go` (rate limiter + metrics + audit log) is unchanged. ## Why same package, not `internal/ai/*` The original completion prompt sketched an `internal/ai/*` split. Keeping the files inside `backend/api/rest/` instead: - Preserves the `*Server` method receivers (`handleAIChat`, `buildAIContext`, `queryAIRoutes`, `callXAIChatCompletions`) without having to export `Server.db`, `Server.chainID`, `Server.aiRateLimiter`, `Server.aiMetrics`, and the `logAIRequest` / `allowAIRequest` helpers. - Keeps this PR a diff-only move that any reviewer can verify with `diff -q <(cat ai_*.go) <(git show master:backend/api/rest/ai.go)`. - Leaves open a follow-up that does the package extraction with a thin `ai.Service` interface once the rest of the hardening sequence lands. ## Verification - `go build ./...` — clean. - `go vet ./...` — clean. - `go test ./api/rest/...` — **PASS**. - `staticcheck ./...` — clean on the SA* correctness family. The U1000 and S1016 tails are pre-existing and already disabled in the `backend/staticcheck.conf` introduced in PR #5. ## Completion criterion advanced > **6. Backend maintainability** — "No single Go file exceeds a few hundred lines; AI/LLM plumbing is separated from HTTP handlers; context-building is separated from upstream calls."

nsatoshi referenced this pull request

2026-04-18 12:29:58 -07:00

docs: rewrite README, add ARCHITECTURE.md (Mermaid), add API.md from swagger.yaml #11

nsatoshi referenced this pull request

2026-04-18 12:31:05 -07:00

docs: rewrite README, add ARCHITECTURE.md (Mermaid), add API.md from swagger.yaml #11

nsatoshi merged commit 976f4716d6 into master

2026-04-18 12:36:20 -07:00

nsatoshi referenced this issue from a commit

2026-04-18 12:36:24 -07:00

Merge pull request 'refactor(ai): split the 1180-line ai.go into focused files' (#6) from devin/1776539460-refactor-ai-package-split into master

nsatoshi referenced this issue from a commit