refactor(compiler): extract assembleQuery helper and modularize services (#27)

- Extract MAX_RESULTS_LIMIT constant in compiler (used in 2 sites)
- Extract assembleQuery() helper to centralize query-tail assembly
- Extract count-assets service from stats route
- Extract validate-slots service from search-factory
- Reduces function size and improves testability

Signed-off-by: Carlo van Driesten <carlo.van-driesten@bmw.de>

Author: jdsika

apps/api/src/routes/stats.ts

@@ -1,9 +1,8 @@
-import { extractErrorMessage, internalError } from '@ontology-search/core/errors'
+import { internalError } from '@ontology-search/core/errors'
 import { REQUEST_ID_HEADER, RequestLogger } from '@ontology-search/core/logging'
-import { buildDomainRegistry } from '@ontology-search/ontology/domain-registry'
-import { compileCountQuery, getAssetDomains, getInitializedStore } from '@ontology-search/search'
 import { Hono } from 'hono'
 
+import { countAssets } from '../services/count-assets.js'
 import type { AppEnv } from '../types.js'
 
 export const statsRoutes = new Hono<AppEnv>()
@@ -14,38 +13,11 @@ statsRoutes.get('/', async (c) => {
 
   try {
     logger.info('Stats request started')
-    const store = await getInitializedStore()
-    const registry = await buildDomainRegistry()
-    const assetDomains = await getAssetDomains()
-
-    const counts: Record<string, number> = {}
-    let totalAssets = 0
-
-    for (const domainName of registry.domainNames) {
-      if (!assetDomains.has(domainName)) continue
-      try {
-        const query = await compileCountQuery(domainName)
-        const result = await store.query(query)
-        const count = parseInt(result.results.bindings[0]?.['count']?.value ?? '0', 10)
-        if (count > 0) {
-          counts[domainName] = count
-          totalAssets += count
-        }
-      } catch (error) {
-        // intentional: degraded response — one failing domain count should
-        // not block the entire /stats response; the domain is simply omitted.
-        // Surface WHY in the log so operators can investigate (was the SPARQL
-        // malformed, the store unreachable, a timeout, …).
-        logger.warn('Skipped domain count', {
-          domain: domainName,
-          error: extractErrorMessage(error),
-        })
-      }
-    }
+    const { counts, totalAssets, availableDomains } = await countAssets(logger)
 
     logger.info('Stats request completed', { totalAssets, domainCount: Object.keys(counts).length })
 
-    return c.json({ totalAssets, domains: counts, availableDomains: registry.domainNames }, 200, {
+    return c.json({ totalAssets, domains: counts, availableDomains }, 200, {
       [REQUEST_ID_HEADER]: requestId,
     })
   } catch (error) {

apps/api/src/search-factory.ts

@@ -8,25 +8,23 @@
  * Tests construct SearchService directly with mock dependencies.
  */
 import { generateStructuredSearch } from '@ontology-search/llm'
-import { validateRangesAgainstShacl, validateSlotsAgainstShacl } from '@ontology-search/llm'
-import { ShaclValidator } from '@ontology-search/ontology/shacl-validator'
 import type {
   NlSearchOptions,
   RefineOptions,
   RefineResult,
   SearchResult,
-  SearchSlots,
 } from '@ontology-search/search'
 import {
   compileAllCountQueries,
   compileSlots,
-  extractVocabulary,
   getInitializedStore,
   type SearchDependencies,
   SearchService,
 } from '@ontology-search/search'
 import { enforceSparqlPolicy } from '@ontology-search/sparql/policy'
 
+import { validateSlots } from './services/validate-slots.js'
+
 let instance: SearchService | null = null
 
 /**
@@ -41,30 +39,7 @@ export async function getSearchService(): Promise<SearchService> {
     compileSlots,
     compileCountQueries: compileAllCountQueries,
     enforcePolicy: enforceSparqlPolicy,
-    validateSlots: async (slots: SearchSlots): Promise<SearchSlots> => {
-      // Defense-in-depth gate for /refine: run the same SHACL validator the
-      // LLM agent uses, then re-emit the slots with any violating values
-      // dropped. The compiler will see only ontology-valid filters/location.
-      const shacl = await ShaclValidator.fromWorkspace()
-      const store = await getInitializedStore()
-      const vocabulary = await extractVocabulary(store)
-      const result = await validateSlotsAgainstShacl(
-        slots.filters ?? {},
-        slots.location,
-        slots.license,
-        shacl,
-        vocabulary
-      )
-      // Drop ranges with property names not in the schema (e.g. `numberLanes`).
-      const rangeResult = validateRangesAgainstShacl(slots.ranges ?? {}, shacl)
-      return {
-        ...slots,
-        filters: result.filters,
-        ranges: rangeResult.ranges,
-        location: result.location,
-        license: result.license,
-      }
-    },
+    validateSlots,
   }
 
   instance = new SearchService(deps)

apps/api/src/services/count-assets.ts

@@ -0,0 +1,55 @@
+/**
+ * Count-assets service — tallies assets per domain via SPARQL COUNT queries.
+ *
+ * Extracted from the /stats route to keep route handlers as pure
+ * request/response plumbing (SRP) and enable independent unit testing.
+ */
+import { extractErrorMessage } from '@ontology-search/core/errors'
+import type { RequestLogger } from '@ontology-search/core/logging'
+import { buildDomainRegistry } from '@ontology-search/ontology/domain-registry'
+import { compileCountQuery, getAssetDomains, getInitializedStore } from '@ontology-search/search'
+
+export interface AssetCounts {
+  counts: Record<string, number>
+  totalAssets: number
+  availableDomains: string[]
+}
+
+/**
+ * Count assets per domain by compiling and executing a COUNT query for each.
+ *
+ * Tolerates per-domain failures (degraded response) so a single broken
+ * domain cannot block the whole /stats response. The logger receives a
+ * structured `warn` for each skipped domain that names the failing
+ * domain AND surfaces the underlying error message — operators need
+ * both to diagnose whether the SPARQL was malformed, the store was
+ * unreachable, a timeout fired, etc.
+ */
+export async function countAssets(logger: RequestLogger): Promise<AssetCounts> {
+  const store = await getInitializedStore()
+  const registry = await buildDomainRegistry()
+  const assetDomains = await getAssetDomains()
+
+  const counts: Record<string, number> = {}
+  let totalAssets = 0
+
+  for (const domainName of registry.domainNames) {
+    if (!assetDomains.has(domainName)) continue
+    try {
+      const query = await compileCountQuery(domainName)
+      const result = await store.query(query)
+      const count = parseInt(result.results.bindings[0]?.['count']?.value ?? '0', 10)
+      if (count > 0) {
+        counts[domainName] = count
+        totalAssets += count
+      }
+    } catch (error) {
+      logger.warn('Skipped domain count', {
+        domain: domainName,
+        error: extractErrorMessage(error),
+      })
+    }
+  }
+
+  return { counts, totalAssets, availableDomains: registry.domainNames }
+}

apps/api/src/services/validate-slots.ts

@@ -0,0 +1,44 @@
+/**
+ * Slot validation service — SHACL-based defense-in-depth for /refine.
+ *
+ * Runs the same SHACL validator the LLM agent uses, then re-emits slots
+ * with any violating values dropped. The compiler only sees ontology-valid
+ * filters and ranges.
+ *
+ * Extracted from search-factory for readability — the validation logic
+ * is wiring-level (not a reusable service), but substantial enough to
+ * warrant its own module.
+ */
+import { validateRangesAgainstShacl, validateSlotsAgainstShacl } from '@ontology-search/llm'
+import { ShaclValidator } from '@ontology-search/ontology/shacl-validator'
+import type { SearchSlots } from '@ontology-search/search'
+import { extractVocabulary, getInitializedStore } from '@ontology-search/search'
+
+/**
+ * Validate search slots against SHACL constraints.
+ * Returns cleaned slots with invalid values removed.
+ */
+export async function validateSlots(slots: SearchSlots): Promise<SearchSlots> {
+  const shacl = await ShaclValidator.fromWorkspace()
+  const store = await getInitializedStore()
+  const vocabulary = await extractVocabulary(store)
+
+  const result = await validateSlotsAgainstShacl(
+    slots.filters ?? {},
+    slots.location,
+    slots.license,
+    shacl,
+    vocabulary
+  )
+
+  // Drop ranges with property names not in the schema
+  const rangeResult = validateRangesAgainstShacl(slots.ranges ?? {}, shacl)
+
+  return {
+    ...slots,
+    filters: result.filters,
+    ranges: rangeResult.ranges,
+    location: result.location,
+    license: result.license,
+  }
+}

packages/search/src/compiler.ts

@@ -69,6 +69,33 @@ export function escapeSparqlLiteral(value: string): string {
     .replace(/\t/g, '\\t')
 }
 
+/**
+ * Assemble a complete SPARQL SELECT query from its constituent parts.
+ * Centralizes the query-tail pattern used by both single-domain and
+ * cross-domain compilation. The LIMIT defaults to the operator-tunable
+ * `SPARQL_DEFAULT_LIMIT` config field; the policy gate enforces the
+ * separate `SPARQL_MAX_LIMIT` ceiling (the Zod schema rejects configs
+ * where the default would exceed the ceiling).
+ */
+function assembleQuery(
+  prefixes: string,
+  selectVars: string[] | Set<string>,
+  patterns: string[],
+  optionals: string[],
+  filters: string[],
+  limit: number = getConfig().SPARQL_DEFAULT_LIMIT
+): string {
+  const vars = selectVars instanceof Set ? [...selectVars] : selectVars
+  const selectClause = `SELECT ${vars.join(' ')}`
+  const whereBody = [...patterns, ...optionals, ...filters].join('\n  ')
+
+  return `${prefixes}
+${selectClause} WHERE {
+  ${whereBody}
+}
+LIMIT ${limit}`
+}
+
 /** Cached compiler vocabulary (ontology doesn't change at runtime) */
 let cachedCompilerVocab: CompilerVocab | null = null
 
@@ -280,14 +307,7 @@ export async function compileSlots(slots: SearchSlots): Promise<string> {
   }
 
   // Build the query
-  const selectClause = `SELECT ${[...selectVars].join(' ')}`
-  const whereBody = [...patterns, ...optionals, ...filters].join('\n  ')
-
-  return `${prefixes}
-${selectClause} WHERE {
-  ${whereBody}
-}
-LIMIT ${getConfig().SPARQL_DEFAULT_LIMIT}`
+  return assembleQuery(prefixes, selectVars, patterns, optionals, filters)
 }
 
 /**
@@ -404,14 +424,7 @@ function compileCrossDomainQuery(
   }
 
   // Build the query
-  const selectClause = `SELECT ${selectVars.join(' ')}`
-  const whereBody = [...patterns, ...optionals, ...filters].join('\n  ')
-
-  return `${prefixes}
-${selectClause} WHERE {
-  ${whereBody}
-}
-LIMIT ${getConfig().SPARQL_DEFAULT_LIMIT}`
+  return assembleQuery(prefixes, selectVars, patterns, optionals, filters)
 }
 
 /**