feat(gateway): chat routes through the LLM gateway with tier-tagged request priority, plus enforced ast-grep lint gates for Java and frontend

[WilliamAGH]

Summary

Chat traffic moves from GitHub Models / OpenAI direct to the LLM gateway's data-plane channel (https://api.llm-gateway.iocloudhost.net/v1, model alias gpt-5.4), with every request tagged by priority tier so live chat is never starved behind batch jobs. The PR also lands a ~55-rule ast-grep lint gate for both Java and frontend code at pre-push, and the error-handling fixes those rules required. Embeddings intentionally stay on popos-sf7 to avoid invalidating the Qdrant vector collection.

Changes

Features

• Live chat requests carry queue priority through the gateway: streaming chat and the Spring AI chat client send X-Tier: production-z (configurable via LLM_GATEWAY_TIER), so they land in the gateway's reserved live tier instead of the zero-reservation default (OpenAIStreamingService.createClient, spring.ai.openai.chat.options.http-headers in application.properties)
• Embedding/backfill traffic self-identifies as batch work: the OpenAI-compatible embedding client sends X-Tier: batch — inert against today's sf7-direct endpoint, load-bearing if embeddings ever route through the gateway queue (OpenAiCompatibleEmbeddingClient)
• Operators can cut over to the gateway by copy-paste: .env.example documents LLM_PRIMARY_PROVIDER=openai, LLM_GATEWAY_TIER, and the gateway base-URL/model/key shape (.env.example)

Code Quality

• ~55 ast-grep rules now gate naming, silent-catch, jOOQ/SQL, and Zod contracts at pre-push: Java rules live in config/ast-grep/ (single owner), frontend rules in frontend/rules/ast-grep/ (single owner per [SS1a]); replaces config/prek.toml with lefthook wiring (.config/lefthook.yml, both sgconfig.yml)
• The @RequestBody-requires-@Valid rule actually fires now: the original pattern was not a parseable Java AST node and matched nothing; rewritten on kind: formal_parameter so it catches both annotation orders and @RequestBody(required = false), and its file scope now includes the real web/ controllers — surfacing 5 existing unvalidated request bodies as warnings (config/ast-grep/java-requestbody-requires-valid.yml)
• Controller-discipline rules scan the real controller package: collection-assembly and mutable-collection rules now include **/web/*.java alongside the clean-architecture roots (java-controller-no-collection-assembly.yml, java-controller-no-mutable-collection-init.yml)
• Lint messages point at rules that exist in this repo: dead cross-repo doc paths (back-end/docs/api-contracts/...) replaced with AGENTS.md tags [TY1]/[CS1g]/[ND1e]/[ND1f] (frontend/rules/ast-grep/*)

Bug Fixes

• make hooks fails fast when lefthook is missing: previously it printed a skip notice and exited 0, letting commits proceed without gates despite [GT1a]; now exits 1 with the install command (Makefile via require_cmd)
• Malformed CSRF cookie no longer fails silently: a bad percent-encoded XSRF-TOKEN value logs a warning before the request proceeds tokenless (csrf.ts readCookie)
• Catch blocks keep their null/false contracts but stop returning from inside catch, keeping error logs adjacent to failures per [RC1a] (csrf.ts readApiErrorResponse/refreshCsrfToken, sse.ts tryParseJson)

Required environment variable updates (not in this PR — .env is gitignored)

Variable	New value	Why
OPENAI_BASE_URL	https://api.llm-gateway.iocloudhost.net/v1	gateway data-plane channel
OPENAI_API_KEY	gateway lgw-* client key	replaces the sk-svcacct-* direct key
OPENAI_MODEL	gpt-5.4	gateway alias → OpenAI Responses (direct)
LLM_PRIMARY_PROVIDER	openai	default github_models would skip the gateway
GITHUB_TOKEN	unset/commented	spring.ai.openai.api-key prefers it and would send it to the gateway (401)
REMOTE_EMBEDDING_*	unchanged	sf7 serves the 8b embedding model; a dimension change would invalidate Qdrant

Code changes required for the gateway cutover

None — the streaming service's OpenAI Responses API passes through the gateway natively, and OpenAiSdkUrlNormalizer already handles the /v1 suffix. Verified live: POST /v1/responses with gpt-5.4 returns status: completed through the gateway.

Breaking Changes

None

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Summary by CodeRabbit

Release Notes

• New Features

  • Added LLM gateway tier configuration support for optimized request routing.
  • Expanded OpenAI-compatible provider configuration with optional provider preference settings.

• Documentation

  • Updated development setup guide for new git hook workflow.
  • Added comprehensive code quality and architecture guidelines in agent rules.

• Chores

  • Migrated git hook management tooling for improved reliability.
  • Enhanced static code analysis rules across backend and frontend to enforce architectural boundaries and type safety.

Walkthrough

This PR comprehensively upgrades development infrastructure and code quality enforcement across the Java backend and TypeScript frontend. It replaces prek with lefthook for Git hooks, adds LLM gateway tier routing via X-Tier headers, expands AGENTS.md development policies, and introduces 50+ new AST-Grep linting rules to enforce patterns around collections, concurrency, type safety, Zod validation, and naming conventions. Frontend error handling for CSRF and SSE improves error logging and recovery.

Changes

Git Hooks and Configuration Infrastructure

Layer / File(s)	Summary
Git Hooks Migration to Lefthook .config/lefthook.yml, Makefile, config/prek.toml, docs/development.md	Migrate from prek to lefthook for Git hook management, updating configuration files, Makefile targets, and development documentation.
LLM Gateway Tier Configuration and Routing .env.example, src/main/java/.../OpenAIStreamingService.java, src/main/java/.../OpenAiCompatibleEmbeddingClient.java, src/main/resources/application.properties	Add LLM gateway tier support with X-Tier headers for request prioritization across chat and embedding clients.
Development Policy Rules Expansion AGENTS.md	Expand AGENTS.md with new mandatory rules for epistemic humility ([ZA1g]), Git workflow ([GT1m]), clean code ([CC1e], [CC1f]), single semantic owner ([SS1a–SS1h]), root-cause resolution ([RC1g]), and verification loops ([VR1d], [VR1e]).
AST-Grep Language Configuration config/sgconfig.yml, frontend/config/sgconfig.yml	Configure language globs for AST-Grep to properly recognize TypeScript/TSX and Java files across rule sets.

Java Linting Rules

Layer / File(s)	Summary
Controller Layer Rules config/ast-grep/java-controller-no-*.yml	Enforce controller-specific patterns: ban mutable collection instantiation and detect list/set/map accumulation in loops.
Database Concurrency and Persistence Boundaries config/ast-grep/java-database-concurrency-boundaries.yml	Enforce database layer isolation: prevent environment-based config reads, disallow direct virtual-thread executors in persistence, and restrict semaphore construction.
jOOQ and SQL Safety Rules config/ast-grep/java-jooq-*.yml, config/ast-grep/java-sql-*.yml	Enforce jOOQ best practices: ban raw qualified columns, flag stringly-typed Record.get calls, prevent unqualified PostgreSQL extension functions and trigram operators.
Query Patterns and Code Quality config/ast-grep/java-no-loop-query-patterns.yml, config/ast-grep/java-no-magic-literals*.yml, config/ast-grep/java-no-legacy-code.yml	Flag N+1 query patterns in loops, detect magic literals in indices and comparisons, and identify legacy code terminology.
Test and Argument Validation config/ast-grep/java-test-*.yml, config/ast-grep/java-null-arg-train-warning.yml, config/ast-grep/java-requestbody-requires-valid.yml	Enforce test code patterns, flag null argument trains in fixtures, and ensure @RequestBody parameters include @Valid annotations.
Web Layer Boundary Enforcement config/ast-grep/java-web-boundary-threading-cache-jooq.yml	Isolate web layer: prohibit manual parallelism, @Async annotations, caching annotations, direct jOOQ usage, and restrict virtual-thread executor creation.

Frontend TypeScript/TSX Linting Rules

Layer / File(s)	Summary
Type Naming and Interface Conventions frontend/rules/ast-grep/ban-i-prefix-interface.yml, frontend/rules/ast-grep/domain-types-in-schemas.yml, frontend/rules/ast-grep/no-anemic-type-alias.yml, frontend/rules/ast-grep/types-are-not-schemas.yml, frontend/rules/ast-grep/constants-file-uppercase.yml	Enforce TypeScript naming conventions: ban I-prefix interfaces, flag domain type suffixes, detect anemic aliases, and ban Schema-suffixed types.
Zod Schema and Validation frontend/rules/ast-grep/no-zod-*.yml, frontend/rules/ast-grep/no-double-zod-validation.yml, frontend/rules/ast-grep/schema-types-only-infer.yml	Enforce Zod patterns: ban loose types, flag ZodTypeAny, prevent double validation, and require schema-types-only-infer pattern.
Type Safety and Unknown Bans frontend/rules/ast-grep/no-core-*.yml, frontend/rules/ast-grep/no-explicit-any.yml, frontend/rules/ast-grep/no-record-string-unknown.yml	Ban Record<string, unknown>, unknown[], explicit any types, and unsafe double casts; enforce strict type boundaries.
Code Pattern Enforcement frontend/rules/ast-grep/no-generic-variable-names.yml, frontend/rules/ast-grep/no-magic-literals.yml, frontend/rules/ast-grep/no-legacy-code.yml, frontend/rules/ast-grep/no-catch-return-fallback.yml, frontend/rules/ast-grep/warn-broken-contract-union.yml	Enforce code patterns: ban generic variable names, magic literals, legacy terminology, silent catch fallbacks, and broken contract unions.
Module and Import/Export Rules frontend/rules/ast-grep/no-barrel-files.yml, frontend/rules/ast-grep/no-reexports.yml, frontend/rules/ast-grep/no-test-mock-files-outside-mocks.yml, frontend/rules/ast-grep/no-logic-in-schemas.yml	Enforce module patterns: ban barrel files, re-exports, test mocks outside mocks, and logic in schema files.
External Data Handling and Parsing frontend/rules/ast-grep/prefer-safe-parse.yml, frontend/rules/ast-grep/no-unsafe-casts.yml	Prefer safeParse over parse and detect unsafe casts on JSON.parse/response.json().
Frontend Error Handling Improvements frontend/src/lib/services/csrf.ts, frontend/src/lib/services/sse.ts	Improve CSRF and SSE error handling: log malformed percent-encoding, use promise-chain JSON parsing, and exit after catch blocks.

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly Related PRs

• WilliamAGH/java-chat#6: Modifies frontend/src/lib/services/sse.ts with changes to tryParseJson's JSON-parse failure behavior, similar to this PR's error handling improvements.

Suggested Labels

documentation, enhancement, java, refactor

---

🚀 A thousand linting rules march in,
Git hooks trade their old coat in,
Types grow strict, null fades away,
Gateway tiers route the light of day.
Ah, such sweet safety! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main changes: routing chat through an LLM gateway with tier tagging and adding ~55 ast-grep lint rules for Java and frontend.
Description check	✅ Passed	The description comprehensively covers the changeset including features, code quality improvements, bug fixes, environment variable updates, and breaking changes assessment.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:379f631254

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR updates developer/operator documentation and local tooling to route chat requests through the LLM gateway (OpenAI-compatible provider) and strengthens guardrails via an expanded ast-grep ruleset, alongside a few frontend error-handling/logging fixes (CSRF + SSE JSON parsing).

Changes:

• Switch local git hook management from prek to lefthook (Makefile/docs + new .config/lefthook.yml; removes config/prek.toml).
• Expand ast-grep rulesets/config for both backend + frontend and standardize TS parsing via language: tsx + languageGlobs.
• Improve frontend robustness: warn on malformed CSRF cookie decoding; avoid returning from inside catch blocks while keeping existing null/false contracts.

Reviewed changes

Copilot reviewed 88 out of 88 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
Makefile	Switch make hooks to install lefthook hooks.
frontend/src/lib/services/sse.ts	Refactor JSON parse helper to avoid returning inside catch.
frontend/src/lib/services/csrf.ts	Add warning for malformed CSRF cookie; refactor catch/return flow.
frontend/rules/ast-grep/warn-broken-contract-union.yml	New frontend rule: flag primitive+object union schemas.
frontend/rules/ast-grep/types-are-not-schemas.yml	New frontend rule: forbid *Schema type/interface names.
frontend/rules/ast-grep/schema-types-only-infer.yml	New frontend rule: require z.infer-derived exports in schema dirs.
frontend/rules/ast-grep/require-pascal-case-types.yml	Update TS language handling for PascalCase type rule.
frontend/rules/ast-grep/prefer-safe-parse.yml	New frontend rule: prefer Zod safeParse over parse.
frontend/rules/ast-grep/no-zod-type-any.yml	New frontend rule: prohibit ZodTypeAny.
frontend/rules/ast-grep/no-zod-loose-types.yml	New frontend rule: prohibit z.json, z.looseObject, .passthrough().
frontend/rules/ast-grep/no-unsafe-casts.yml	New frontend rule: prohibit unsafe casts at trust boundaries.
frontend/rules/ast-grep/no-test-mock-files-outside-mocks.yml	New frontend rule: enforce mocks under __tests__/__mocks__.
frontend/rules/ast-grep/no-silent-catch.yml	New frontend rule: forbid silent catch default returns (with exceptions).
frontend/rules/ast-grep/no-reexports.yml	New frontend rule: forbid re-exports/barrels.
frontend/rules/ast-grep/no-record-string-unknown.yml	New frontend rule: forbid Record<string, unknown> bags.
frontend/rules/ast-grep/no-magic-literals.yml	New frontend rule: flag magic numeric literals (warn).
frontend/rules/ast-grep/no-logic-in-schemas.yml	New frontend rule: keep src/schemas/** declaration-only.
frontend/rules/ast-grep/no-legacy-code.yml	New frontend rule: warn on “Legacy/Deprecated/Old” identifiers.
frontend/rules/ast-grep/no-generic-variable-names.yml	New frontend rule: forbid generic variable name data.
frontend/rules/ast-grep/no-explicit-any.yml	New frontend rule: forbid explicit any.
frontend/rules/ast-grep/no-double-zod-validation.yml	New frontend rule: prohibit validating same payload twice.
frontend/rules/ast-grep/no-domain-record-cast.yml	New frontend rule: warn on as Record<string, ...> casts.
frontend/rules/ast-grep/no-default-unknown-generic.yml	New frontend rule: forbid default generic = unknown.
frontend/rules/ast-grep/no-core-unknown-array.yml	New frontend rule: forbid unknown[] bags in core boundary code.
frontend/rules/ast-grep/no-core-record-unknown.yml	New frontend rule: forbid Record<string, unknown> in core boundary code.
frontend/rules/ast-grep/no-catch-return-fallback.yml	New frontend rule: forbid returning fallbacks from catch.
frontend/rules/ast-grep/no-barrel-files.yml	New frontend rule: forbid index.ts(x) barrels.
frontend/rules/ast-grep/no-anemic-type-alias.yml	New frontend rule: warn on pure renaming type aliases.
frontend/rules/ast-grep/domain-types-in-schemas.yml	New frontend rule: warn on banned generic suffixes (DTO/Data/etc.).
frontend/rules/ast-grep/constants-file-uppercase.yml	New frontend rule: constants must use UPPER_SNAKE_CASE.
frontend/rules/ast-grep/ban-i-prefix-interface.yml	Strengthen interface naming rule; switch to tsx.
frontend/rules/ast-grep/ban-generic-type-suffixes.yml	Switch type suffix rule to tsx.
frontend/config/sgconfig.yml	Add languageGlobs so ts/tsx are scanned as tsx.
docs/development.md	Document lefthook-based hook installation.
config/sgconfig.yml	Add languageGlobs so ts/tsx are scanned as tsx.
config/prek.toml	Remove prek hook configuration (deleted).
config/ast-grep/warn-broken-contract-union.yml	New shared rule: flag primitive+object union schemas.
config/ast-grep/types-are-not-schemas.yml	New shared rule: forbid *Schema type/interface names.
config/ast-grep/schema-types-only-infer.yml	New shared rule: require z.infer-derived exports in schema dirs.
config/ast-grep/require-pascal-case-types.yml	New shared rule: PascalCase type/interface/enum names.
config/ast-grep/prefer-safe-parse.yml	New shared rule: prefer Zod safeParse over parse.
config/ast-grep/no-zod-type-any.yml	New shared rule: prohibit ZodTypeAny.
config/ast-grep/no-zod-loose-types.yml	New shared rule: prohibit z.json, z.looseObject, .passthrough().
config/ast-grep/no-unsafe-casts.yml	New shared rule: prohibit unsafe casts at trust boundaries.
config/ast-grep/no-test-mock-files-outside-mocks.yml	New shared rule: enforce mocks under __tests__/__mocks__.
config/ast-grep/no-silent-catch.yml	New shared rule: forbid silent catch default returns (with exceptions).
config/ast-grep/no-reexports.yml	New shared rule: forbid re-exports/barrels.
config/ast-grep/no-record-string-unknown.yml	New shared rule: forbid Record<string, unknown> bags.
config/ast-grep/no-magic-literals.yml	New shared rule: flag magic numeric literals (warn).
config/ast-grep/no-logic-in-schemas.yml	New shared rule: keep src/schemas/** declaration-only.
config/ast-grep/no-legacy-code.yml	New shared rule: warn on “Legacy/Deprecated/Old” identifiers.
config/ast-grep/no-generic-variable-names.yml	New shared rule: forbid generic variable name data.
config/ast-grep/no-explicit-any.yml	New shared rule: forbid explicit any.
config/ast-grep/no-double-zod-validation.yml	New shared rule: prohibit validating same payload twice.
config/ast-grep/no-domain-record-cast.yml	New shared rule: warn on as Record<string, ...> casts.
config/ast-grep/no-default-unknown-generic.yml	New shared rule: forbid default generic = unknown.
config/ast-grep/no-core-unknown-array.yml	New shared rule: forbid unknown[] bags.
config/ast-grep/no-core-record-unknown.yml	New shared rule: forbid Record<string, unknown> bags.
config/ast-grep/no-catch-return-fallback.yml	New shared rule: forbid returning fallbacks from catch.
config/ast-grep/no-barrel-files.yml	New shared rule: forbid index.ts(x) barrels.
config/ast-grep/no-anemic-type-alias.yml	New shared rule: warn on pure renaming type aliases.
config/ast-grep/java-web-boundary-threading-cache-jooq.yml	New Java web-layer boundary rules (threads/cache/jOOQ) + allowlist.
config/ast-grep/java-testcontainer-postgres-version.yml	New Java test rule: enforce Postgres 17 image version.
config/ast-grep/java-testcontainer-no-dockerhub-postgres.yml	New Java test rule: require ECR Public mirror (no Docker Hub).
config/ast-grep/java-test-presence-only-grouped-field.yml	New Java test rule: warn on presence-only grouped subfield assertions.
config/ast-grep/java-test-no-pageable-response-assertions.yml	New Java test rule: forbid pageable object assertions.
config/ast-grep/java-test-fixture-null-arg-train.yml	New Java test fixture rule: forbid null-arg trains.
config/ast-grep/java-sql-unqualified-trigram-operator.yml	New Java rule: require schema-qualified trigram operator usage.
config/ast-grep/java-sql-unqualified-extension-functions.yml	New Java rule: require schema-qualified extension function calls.
config/ast-grep/java-sql-no-runtime-to-tsvector.yml	New Java rule: forbid runtime to_tsvector(...) in SQL strings.
config/ast-grep/java-requestbody-requires-valid.yml	Update rule: require @Valid with @RequestBody.
config/ast-grep/java-null-arg-train-warning.yml	New Java warning: detect 3+ consecutive null arguments.
config/ast-grep/java-no-magic-literals.yml	New Java warning: detect magic numeric literals in comparisons.
config/ast-grep/java-no-magic-literals-index.yml	New Java warning: detect magic numeric literals in .get(n) indexing.
config/ast-grep/java-no-loop-query-patterns.yml	New Java rule: block loop-contained port/DSL queries (N+1).
config/ast-grep/java-no-legacy-code.yml	New Java warning: “Legacy/Deprecated/Old” identifiers in main code.
config/ast-grep/java-jooq-advisory-stringly-typed-record-get.yml	New Java advisory: flag stringly-typed record.get(...).
config/ast-grep/java-jooq-advisory-raw-sql-qualified-column.yml	New Java advisory: flag raw SQL qualified column string literals.
config/ast-grep/java-database-concurrency-boundaries.yml	New Java rules: typed DB config ownership + persistence fan-out limits.
config/ast-grep/java-controller-no-mutable-collection-init.yml	New Java warning: controllers shouldn’t instantiate mutable collections.
config/ast-grep/java-controller-no-collection-assembly.yml	New Java warning: controllers shouldn’t build collections in loops.
config/ast-grep/domain-types-in-schemas.yml	New shared rule: warn on banned generic suffixes (DTO/Data/etc.).
config/ast-grep/constants-file-uppercase.yml	New shared rule: constants must use UPPER_SNAKE_CASE.
config/ast-grep/ban-i-prefix-interface.yml	New shared rule: ban I* interface prefix.
config/ast-grep/ban-generic-type-suffixes.yml	New shared rule: ban generic type suffixes (Data/Info/etc.).
AGENTS.md	Update repo guidance (lefthook note, new clean-code/SSO bullets).
.env.example	Document OpenAI-compatible gateway configuration hints.
.config/lefthook.yml	New lefthook configuration for pre-commit + pre-push gates.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.