feat(cat): validate segments with Go service

[cungminh2710]

What changed

• Call the Go segment-validation service from the CAT editor.
• Enable format, length, and all supported QA checks.
• Debounce live validation by 300 ms and cancel stale requests.
• Preserve local glossary checks and surface service failures without blocking edits.
• Add API contract and debounce tests.
• Document the integration design.

How to test

• vp test src/components/cat/project-file/project-file-cat-validation.test.ts src/components/cat/workspace/use-cat-workspace-controller.test.tsx
• vp check --fix
• vp test — blocked by PostgreSQL being unavailable on port 5432 (ECONNREFUSED).

Checklist

• I ran relevant checks locally (make fmt, make lint, make test)
• I updated docs, comments, or examples when needed
• This PR is scoped and ready for review

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hyperlocalise	Ignored		Jul 5, 2026 2:35am

[greptile-apps]

Greptile Summary

This PR wires the CAT editor's format/QA checks through the Go segment-validation service, replacing the previous synchronous client-side validateSegmentFormat call with an async HTTP call to /api/go-svc/v1/validate/segment. It adds 300 ms debouncing for live edits, abort-signal propagation for cancelled/superseded requests, and a fallback "Validation unavailable" advisory check on service failure.

• New fetchCatSegmentValidation module sends source text, target text, source path, optional maxLength, and all QA modes to the Go service; validates the response with Zod; and maps errors to a typed Result<CatFormatCheck[], CatSegmentValidationError>.
• runSegmentChecks + scheduleSegmentChecks in the workspace controller replace the old direct validation call with a debounced/aborting pattern; the selection-change effect now calls runSegmentChecks directly (clearing any pending debounce timer) instead of going through the heavier runSegmentReview path.
• Abort signals are now threaded through validateFormat into fetchCatSegmentValidation → fetch, covering both the debounced edit path and the AI-review path.

Confidence Score: 5/5

Safe to merge; the abort/debounce plumbing is correct and both previously flagged bugs are resolved.

The two defects identified in prior review rounds — the pending debounce timer not being cancelled on direct segment validation, and the missing abort signal in the AI-review path — are both addressed here. The new Go-service client validates responses with Zod, handles network failures non-blockingly, and correctly threads abort signals through every async boundary in the hot path. The only remaining note is a real-timer wait in one test that could be made deterministic with fake timers, which does not affect runtime behaviour.

The debounce cancellation test in use-cat-workspace-controller.test.tsx uses a real 350 ms wait and would benefit from fake timers.

Important Files Changed

Filename	Overview
apps/hyperlocalise-web/src/components/cat/project-file/project-file-cat-validation.ts	New module: Zod-validated HTTP client for the Go segment-validation service; correctly handles abort, service errors, and malformed responses via Result type.
apps/hyperlocalise-web/src/components/cat/project-file/project-file-cat-validation.test.ts	Good coverage of happy path, abort, malformed response, and maxLength omission; abort test relies on real timers — see inline comment.
apps/hyperlocalise-web/src/components/cat/workspace/use-cat-workspace-controller.ts	Debounce/abort wiring looks correct; previous P1s (stale timeout, missing signal in AI path) are both addressed; the debounce cancellation integration test uses a real 350 ms wait.
apps/hyperlocalise-web/src/components/cat/project-file/project-file-cat-workspace.tsx	validateFormat callback correctly delegates to the Go service, surfaces failures as advisory checks, and merges local glossary results.
apps/hyperlocalise-web/src/components/cat/shared/dependencies.ts	Type-level addition of optional signal to validateFormat interface; backward compatible.
apps/hyperlocalise-web/src/components/cat/workspace/use-cat-workspace-controller.test.tsx	New debounce and AI-review abort tests are well-structured; the 350 ms real-timer wait in the cancellation test could be replaced with fake timers.
docs/adr/2026-07-05-cat-segment-validation-service-design.md	ADR accurately reflects the implementation: same-origin routing, WorkOS cookie auth, advisory failure mode, 300 ms debounce.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant User
    participant Editor as CAT Editor
    participant Controller as useWorkspaceController
    participant Workspace as ProjectFileCatWorkspace
    participant GoSvc as Go Segment Service

    User->>Editor: Select segment
    Editor->>Controller: selectedSegmentId changes
    Controller->>Controller: runSegmentChecks(segment, targetText)
    Controller->>Workspace: "validateFormat(segment, value, glossary, {signal})"
    Workspace->>GoSvc: POST /api/go-svc/v1/validate/segment
    GoSvc-->>Workspace: "{ checks: [...] }"
    Workspace-->>Controller: CatFormatCheck[]
    Controller->>Editor: setFormatChecks(segmentId, checks)

    User->>Editor: Rapid keystrokes
    Editor->>Controller: scheduleSegmentChecks (debounced 300ms)
    Note over Controller: Prior request aborted immediately
    Controller->>Controller: runSegmentChecks(segment, latestValue)
    Controller->>Workspace: "validateFormat(segment, latestValue, glossary, {signal})"
    Workspace->>GoSvc: POST /api/go-svc/v1/validate/segment
    GoSvc-->>Workspace: "{ checks: [...] }"
    Workspace-->>Controller: CatFormatCheck[]
    Controller->>Editor: setFormatChecks(segmentId, checks)

    User->>Editor: Review with AI
    Editor->>Controller: "runSegmentReview(segmentId, {includeAi:true})"
    Note over Controller: Clears timer, aborts old AC, creates new AC
    Controller->>GoSvc: generateAiRecommendation(...)
    GoSvc-->>Controller: recommendation
    Controller->>Workspace: "validateFormat(segment, text, glossary, {signal: AC.signal})"
    Workspace->>GoSvc: POST /api/go-svc/v1/validate/segment
    GoSvc-->>Workspace: "{ checks: [...] }"
    Workspace-->>Controller: CatFormatCheck[]
    Controller->>Editor: setFormatChecks + mergeIntelligence

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant User
    participant Editor as CAT Editor
    participant Controller as useWorkspaceController
    participant Workspace as ProjectFileCatWorkspace
    participant GoSvc as Go Segment Service

    User->>Editor: Select segment
    Editor->>Controller: selectedSegmentId changes
    Controller->>Controller: runSegmentChecks(segment, targetText)
    Controller->>Workspace: "validateFormat(segment, value, glossary, {signal})"
    Workspace->>GoSvc: POST /api/go-svc/v1/validate/segment
    GoSvc-->>Workspace: "{ checks: [...] }"
    Workspace-->>Controller: CatFormatCheck[]
    Controller->>Editor: setFormatChecks(segmentId, checks)

    User->>Editor: Rapid keystrokes
    Editor->>Controller: scheduleSegmentChecks (debounced 300ms)
    Note over Controller: Prior request aborted immediately
    Controller->>Controller: runSegmentChecks(segment, latestValue)
    Controller->>Workspace: "validateFormat(segment, latestValue, glossary, {signal})"
    Workspace->>GoSvc: POST /api/go-svc/v1/validate/segment
    GoSvc-->>Workspace: "{ checks: [...] }"
    Workspace-->>Controller: CatFormatCheck[]
    Controller->>Editor: setFormatChecks(segmentId, checks)

    User->>Editor: Review with AI
    Editor->>Controller: "runSegmentReview(segmentId, {includeAi:true})"
    Note over Controller: Clears timer, aborts old AC, creates new AC
    Controller->>GoSvc: generateAiRecommendation(...)
    GoSvc-->>Controller: recommendation
    Controller->>Workspace: "validateFormat(segment, text, glossary, {signal: AC.signal})"
    Workspace->>GoSvc: POST /api/go-svc/v1/validate/segment
    GoSvc-->>Workspace: "{ checks: [...] }"
    Workspace-->>Controller: CatFormatCheck[]
    Controller->>Editor: setFormatChecks + mergeIntelligence

Loading

_{Reviews (2): Last reviewed commit: "feedback" | Re-trigger Greptile}

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.