trueref/docs/CODE_STYLE.md

Code Style

Last Updated: 2026-03-26T23:52:10.000Z

Language And Tooling

• Language: TypeScript with strict mode enabled in tsconfig.json
• Framework conventions: SvelteKit route files and server modules
• Formatter: Prettier
• Linter: ESLint flat config with JavaScript, TypeScript, and Svelte recommended presets
• Test style: Vitest for server and browser-facing tests

Naming Conventions

The codebase uses descriptive PascalCase for classes, interfaces, and domain model types.

Examples:

• RepositoryService
• HybridSearchService
• EmbeddingService
• SearchResultMapper
• RepositoryEntity
• RawSnippetRow

Functions, variables, and exported helpers use camelCase.

Examples:

• initializeDatabase
• recoverStaleJobs
• parseCodeFile
• selectSnippetsWithinBudget
• createMcpServer

Database tables and persisted columns use snake_case, matching SQLite conventions.

Examples from schema.ts:

• repository_versions
• total_snippets
• source_url
• indexed_at

Constants use UPPER_SNAKE_CASE when they represent configuration or shared immutable values.

Examples:

• EMBEDDING_CONFIG_KEY
• DEFAULT_TOKEN_BUDGET
• BOUNDARY_PATTERNS
• CORS_HEADERS

Indentation And Formatting

• Tabs are the project-wide indentation style
• Single quotes are preferred
• Trailing commas are disabled
• Print width is 100
• Svelte files are formatted with the Svelte parser and Tailwind-aware class sorting

These settings are enforced in .prettierrc.

Import Patterns

The project favors ES module syntax everywhere.

Observed patterns:

• Node built-ins use node: specifiers, for example import { parseArgs } from 'node:util'
• Internal modules often use the SvelteKit $lib alias
• Many TypeScript server modules include .js on relative runtime imports to align with emitted ESM paths
• Type-only imports are used where appropriate

Examples:

import type { RequestHandler } from './$types';
import { getClient } from '$lib/server/db/client';
import { IndexingPipeline } from './indexing.pipeline.js';
import { parseArgs } from 'node:util';

Comments And Docstrings

The codebase uses structured block comments more often than inline comments. Files commonly start with a short header describing the feature or subsystem, and larger modules use banner separators to divide helper sections, public types, and exported behavior.

Representative style:

/**
 * SearchService — FTS5-backed full-text search over snippets and repositories.
 *
 * Implements keyword search using SQLite's built-in BM25 ranking.
 */

Inline comments are used sparingly and usually explain behavior that is runtime-specific, such as fallback logic, recovery semantics, or SQL limitations.

Code Examples

Representative function declaration style:

export function recoverStaleJobs(db: Database.Database): void {
	db.prepare(
		`UPDATE indexing_jobs
	 SET status      = 'failed',
		 error       = 'Server restarted while job was running',
		 completed_at = unixepoch()
	 WHERE status = 'running'`
	).run();
}

Representative interface style:

export interface AddRepositoryInput {
	source: 'github' | 'local';
	sourceUrl: string;
	title?: string;
	description?: string;
	branch?: string;
	githubToken?: string;
}

Representative object-literal and configuration style:

export default defineConfig({
	plugins: [tailwindcss(), sveltekit()],
	test: {
		expect: { requireAssertions: true }
	}
});

Linting Configuration

eslint.config.js defines a flat-config stack with:

• @eslint/js recommended rules
• typescript-eslint recommended rules
• eslint-plugin-svelte recommended rules
• prettier compatibility presets
• shared browser and node globals
• no-undef explicitly disabled for TypeScript files
• Svelte parserOptions configured with projectService and svelteConfig

This indicates the project expects type-aware linting for Svelte and TypeScript rather than relying on formatting-only enforcement.

Style Summary

The dominant style is pragmatic server-side TypeScript: explicit types, small interfaces for inputs/options, banner-commented modules, thin route handlers, and class-based services around synchronous SQLite access. Naming is consistent, import usage is modern ESM, and formatting is standardized through Prettier rather than ad hoc conventions.