@lucas-bur/pix 0.11.0 → 0.13.0

package/README.md

@@ -19,13 +19,13 @@ pix query "authentication middleware"
 
 ## Commands
 
-| Command              | Description                                 | JSON flag |
-| -------------------- | ------------------------------------------- | --------- |
-| `pix init`           | Create `.pix/config.json` with defaults     | `--json`  |
-| `pix index`          | Scan, chunk, embed, and store project files | `--json`  |
-| `pix query "<text>"` | Semantic search via cosine similarity       | `--json`  |
-| `pix status`         | Show index statistics                       | `--json`  |
-| `pix reset`          | Delete index files (chunks + vectors)       | `--json`  |
+| Command                      | Description                                                                                                                            | JSON flag |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------- |
+| `pix init`                   | Create `.pix/config.json` with defaults                                                                                                | `--json`  |
+| `pix index`                  | Scan, chunk, embed, and store project files                                                                                            | `--json`  |
+| `pix query "<text>" [flags]` | Semantic search via cosine similarity (`--top`, `--context-lines`, `--ignore-path`, `--only-path`, `--max-characters`, `--no-content`) | `--json`  |
+| `pix status`                 | Show index statistics                                                                                                                  | `--json`  |
+| `pix reset`                  | Delete index files (chunks + vectors)                                                                                                  | `--json`  |
 
 All commands support `--json` for structured output on stdout — ideal for piping to AI agents.
 

package/dist/index.mjs

@@ -2,12 +2,13 @@
 import { createRequire } from "node:module";
 import { Args, CliConfig, Command, Options } from "@effect/cli";
 import { NodeContext, NodeRuntime } from "@effect/platform-node";
-import { Clock, Context, Data, Effect, Exit, Layer, Option, Ref, Stream } from "effect";
+import { Clock, Context, Data, Effect, Exit, Layer, Option, Ref, Schema, Stream } from "effect";
 import * as Chunk from "effect/Chunk";
 import { styleText } from "node:util";
 import * as clack from "@clack/prompts";
 import { FileSystem } from "@effect/platform";
 import crypto from "node:crypto";
+import * as ParseResult from "effect/ParseResult";
 import { env } from "@huggingface/transformers";
 import ignore from "ignore";
 //#region src/domain/ports.ts
@@ -154,7 +155,26 @@ const JsonDisplay = { layer: Layer.succeed(Display, {
 }) };
 //#endregion
 //#region src/domain/config.ts
-var ConfigError = class extends Data.TaggedError("ConfigError") {};
+const EmbedderConfigSchema = Schema.Struct({
+	model: Schema.String,
+	device: Schema.Literal("auto", "cpu", "cuda", "dml", "coreml"),
+	dtype: Schema.Literal("fp32", "fp16", "q8"),
+	batchSize: Schema.Number
+});
+/**
+* Runtime schema for persisted project configuration. Defines the structure and validation rules
+* for `.pix/config.json`.
+*/
+const ConfigSchema = Schema.Struct({
+	schema: Schema.Literal("1"),
+	chunkLines: Schema.Number,
+	overlapLines: Schema.Number,
+	chunkConcurrency: Schema.optionalWith(Schema.Number, { exact: true }),
+	skipExtensions: Schema.Array(Schema.String),
+	ignoredPaths: Schema.Array(Schema.String),
+	ignoreGitignore: Schema.optionalWith(Schema.Boolean, { exact: true }),
+	embedder: EmbedderConfigSchema
+});
 const DEFAULT_CONFIG = {
 	schema: "1",
 	chunkLines: 60,
@@ -184,11 +204,41 @@ const DEFAULT_CONFIG = {
 	}
 };
 //#endregion
+//#region src/lib/extension.ts
+/** Extract the last path segment (filename) from a file path. Handles both `/` and `\\` separators. */
+const getFilename = (path) => {
+	const sepIndex = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+	return sepIndex >= 0 ? path.slice(sepIndex + 1) : path;
+};
+/**
+* Extract the lowercase extension (including dot) from a file path. Used for processor dispatch.
+* Strips the directory, then returns the part after the last dot. If no dot, returns the full
+* filename lowercased.
+*/
+const getExtension = (file) => {
+	const name = getFilename(file);
+	const dotIndex = name.lastIndexOf(".");
+	if (dotIndex === -1) return name.toLowerCase();
+	return name.slice(dotIndex).toLowerCase();
+};
+/**
+* Extract the extension from a filename (not full path). Returns `"(no extension)"` if no dot
+* exists. Used for display grouping of skipped files.
+*/
+const getFileExtension = (filename) => {
+	const dotIndex = filename.lastIndexOf(".");
+	return dotIndex >= 0 ? filename.slice(dotIndex) : "(no extension)";
+};
+//#endregion
 //#region src/domain/errors.ts
+/** Generic config I/O failure (read, write, encode). */
+var ConfigError = class extends Data.TaggedError("ConfigError") {};
 /** Config file or directory does not exist. Run pix init first. */
 var ConfigNotFoundError = class extends Data.TaggedError("ConfigNotFoundError") {};
 /** Config file exists but contains invalid JSON. */
 var ConfigMalformedError = class extends Data.TaggedError("ConfigMalformedError") {};
+/** Config failed schema validation — missing/invalid fields. */
+var ConfigValidationError = class extends Data.TaggedError("ConfigValidationError") {};
 /** Index files (chunks.jsonl, vectors.bin) do not exist. Run pix index first. */
 var NoIndexError = class extends Data.TaggedError("NoIndexError") {};
 /** Disk is full — write operation could not complete. */
@@ -206,6 +256,8 @@ var InferenceError = class extends Data.TaggedError("InferenceError") {};
 * via ScanResult.skipped.
 */
 var ScanFailed = class extends Data.TaggedError("ScanFailed") {};
+/** A chunk line in chunks.jsonl failed schema validation. */
+var ChunkValidationError = class extends Data.TaggedError("ChunkValidationError") {};
 /** File type is unsupported for text extraction. */
 var UnsupportedFormat = class extends Data.TaggedError("UnsupportedFormat") {};
 /** Text extraction failed for a supported file type. */
@@ -315,13 +367,6 @@ const deriveEffectiveConfig = (opts, config) => ({
 	ignoredPaths: opts.ignorePaths ? [...config.ignoredPaths ?? DEFAULT_CONFIG.ignoredPaths, ...opts.ignorePaths] : config.ignoredPaths ?? DEFAULT_CONFIG.ignoredPaths,
 	ignoreGitignore: opts.ignoreGitignore ?? config.ignoreGitignore ?? false
 });
-function getExtension(file) {
-	const lastSlash = file.lastIndexOf("/");
-	const name = lastSlash >= 0 ? file.slice(lastSlash + 1) : file;
-	const dotIndex = name.lastIndexOf(".");
-	if (dotIndex === -1) return name.toLowerCase();
-	return name.slice(dotIndex).toLowerCase();
-}
 const classifyFiles = (files, processorMap) => {
 	const knownFiles = [];
 	const skippedFiles = [];
@@ -386,7 +431,8 @@ var IndexProject = class extends Effect.Service()("IndexProject", {
 						chunks: 0,
 						files: 0,
 						totalLines: 0,
-						byteSize: 0
+						byteSize: 0,
+						validationErrors: []
 					},
 					durationMs: Date.now() - start
 				};
@@ -401,7 +447,8 @@ var IndexProject = class extends Effect.Service()("IndexProject", {
 						chunks: 0,
 						files: 0,
 						totalLines: 0,
-						byteSize: 0
+						byteSize: 0,
+						validationErrors: []
 					},
 					durationMs: Date.now() - start
 				};
@@ -435,7 +482,8 @@ var IndexProject = class extends Effect.Service()("IndexProject", {
 					chunks: stats.chunks,
 					files: stats.files,
 					totalLines: stats.totalLines,
-					byteSize: stats.byteSize
+					byteSize: stats.byteSize,
+					validationErrors: []
 				},
 				durationMs: Date.now() - start,
 				embedderFallback: fallbackInfo
@@ -444,11 +492,6 @@ var IndexProject = class extends Effect.Service()("IndexProject", {
 		return { index };
 	})
 }) {};
-const getFilename = (path) => path.split("/").pop() ?? path;
-const getFileExtension = (filename) => {
-	const dotIndex = filename.lastIndexOf(".");
-	return dotIndex >= 0 ? filename.slice(dotIndex) : "(no extension)";
-};
 const groupByExtension = (entries) => {
 	const byExt = /* @__PURE__ */ new Map();
 	for (const s of entries) {
@@ -504,7 +547,7 @@ var QueryProject = class extends Effect.Service()("QueryProject", {
 	effect: Effect.gen(function* () {
 		const embedder = yield* Embedder;
 		const store = yield* VectorStore;
-		const queryProject = (queryText, topK) => embedder.embed(queryText).pipe(Effect.flatMap((embedding) => store.search(embedding, topK)));
+		const queryProject = (queryText, options) => embedder.embed(queryText).pipe(Effect.flatMap((embedding) => store.search(embedding, options)));
 		return { queryProject };
 	})
 }) {};
@@ -529,6 +572,8 @@ const errorCodes = {
 	ConfigError: "CONFIG_ERROR",
 	ConfigNotFoundError: "CONFIG_NOT_FOUND",
 	ConfigMalformedError: "CONFIG_MALFORMED",
+	ConfigValidationError: "CONFIG_VALIDATION_ERROR",
+	ChunkValidationError: "CHUNK_VALIDATION_ERROR",
 	NoIndexError: "NO_INDEX",
 	DiskFullError: "DISK_FULL",
 	StoreError: "STORE_ERROR",
@@ -636,6 +681,51 @@ const initCommand = Command.make("init", { json: Options.boolean("json").pipe(Op
 	DiskFullError: reportError
 })));
 //#endregion
+//#region src/lib/format.ts
+/** Format byte count as human-readable string (e.g. "1.5 MB") */
+const formatBytes = (bytes) => {
+	if (bytes === 0) return "0 B";
+	const units = [
+		"B",
+		"KB",
+		"MB",
+		"GB"
+	];
+	const i = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1);
+	return `${(bytes / 1024 ** i).toFixed(1)} ${units[i]}`;
+};
+/**
+* Apply a character budget to search results. Returns results in score order capped by the budget.
+* The last result may be truncated to fit the remaining budget. Character count includes file path,
+* line numbers, chunk text, and context lines.
+*/
+const applyCharBudget = (results, maxChars) => {
+	if (!maxChars || maxChars <= 0) return { results };
+	const budgeted = [];
+	let remaining = maxChars;
+	for (const result of results) {
+		const indicator = " [...]";
+		const metadata = `${result.file}:${result.startLine}-${result.endLine}\n`;
+		const chars = `${metadata}${result.text}${result.contextBefore ? `\n${result.contextBefore}` : ""}${result.contextAfter ? `\n${result.contextAfter}` : ""}`.length;
+		if (chars <= remaining) {
+			budgeted.push(result);
+			remaining -= chars;
+		} else {
+			const textBudget = remaining - metadata.length - 6;
+			if (textBudget <= 0) break;
+			const truncated = result.text.slice(0, textBudget);
+			budgeted.push({
+				...result,
+				text: `${truncated}${indicator}`,
+				contextBefore: null,
+				contextAfter: null
+			});
+			break;
+		}
+	}
+	return { results: budgeted };
+};
+//#endregion
 //#region src/commands/query.ts
 const DEFAULT_TOP_K = 5;
 const DEFAULT_CONTEXT_LINES = 0;
@@ -662,31 +752,72 @@ const formatResult = (result) => {
 	const contextAfter = result.contextAfter ? `\n${result.contextAfter}` : "";
 	return `${result.file}:${result.startLine}-${result.endLine} (score: ${result.score.toFixed(3)})${contextBefore}\n${result.text}${contextAfter}`;
 };
-const toJsonOutput = (results, ctxLines) => results.map((r) => ({
+/** Format a result as a lightweight location reference (no text content). */
+const formatLocation = (result) => `${result.file}:${result.startLine}-${result.endLine} (score: ${result.score.toFixed(3)})`;
+/** Build optional content fields for a single JSON output entry. */
+const buildContentFields = (r, ctxLines, noContent) => {
+	if (noContent) return {};
+	return {
+		text: r.text,
+		...ctxLines > 0 && r.contextBefore && { contextBefore: r.contextBefore },
+		...ctxLines > 0 && r.contextAfter && { contextAfter: r.contextAfter }
+	};
+};
+const toJsonOutput = (results, ctxLines, noContent = false) => results.map((r) => ({
 	score: r.score,
 	file: r.file,
 	startLine: r.startLine,
 	endLine: r.endLine,
-	text: r.text,
-	...ctxLines > 0 && r.contextBefore && { contextBefore: r.contextBefore },
-	...ctxLines > 0 && r.contextAfter && { contextAfter: r.contextAfter }
+	...buildContentFields(r, ctxLines, noContent)
 }));
-/** CLI command: pix query "<text>" [--top N] [--json] [--context-lines N] */
+/** Build SearchOptions from parsed CLI args, clamping topK. */
+const buildSearchOptions = (top, ignorePath, onlyPath) => {
+	const rawValue = Option.getOrElse(top, () => DEFAULT_TOP_K);
+	const clamped = clampTopK(rawValue);
+	return {
+		options: {
+			topK: clamped.value,
+			...ignorePath.length > 0 && { ignorePaths: [...ignorePath] },
+			...onlyPath.length > 0 && { onlyPaths: [...onlyPath] }
+		},
+		clamped: clamped.clamped,
+		rawValue
+	};
+};
+/** Render search results via Display — JSON + human-readable text. */
+const renderResults = (d, response, ctxLines, noContent) => Effect.gen(function* () {
+	const { results, validationErrors } = response;
+	yield* d.json({
+		results: toJsonOutput(results, ctxLines, noContent),
+		...validationErrors.length > 0 && { validationErrors }
+	});
+	if (results.length === 0) yield* d.log("No results found", "warn");
+	else for (const result of results) yield* d.text(noContent ? formatLocation(result) : formatResult(result));
+});
+/**
+* CLI command: pix query "<text>" [--top N] [--json] [--context-lines N] [--ignore-path P]
+* [--only-path P] [--max-characters N] [--no-content]
+*/
 const queryCommand = Command.make("query", {
 	queryText: Args.text({ name: "query" }),
 	top: Options.integer("top").pipe(Options.withDefault(DEFAULT_TOP_K), Options.optional),
 	json: Options.boolean("json").pipe(Options.withDefault(false)),
-	contextLines: Options.integer("context-lines").pipe(Options.withDefault(DEFAULT_CONTEXT_LINES), Options.optional)
-}, ({ queryText, top, contextLines }) => Effect.gen(function* () {
+	contextLines: Options.integer("context-lines").pipe(Options.withDefault(DEFAULT_CONTEXT_LINES), Options.optional),
+	ignorePath: Options.text("ignore-path").pipe(Options.repeated),
+	onlyPath: Options.text("only-path").pipe(Options.repeated),
+	maxCharacters: Options.integer("max-characters").pipe(Options.optional),
+	noContent: Options.boolean("no-content").pipe(Options.withDefault(false))
+}, ({ queryText, top, contextLines, ignorePath, onlyPath, maxCharacters, noContent }) => Effect.gen(function* () {
 	const d = yield* Display;
-	const topK = Option.getOrElse(top, () => DEFAULT_TOP_K);
 	const ctxLines = Option.getOrElse(contextLines, () => DEFAULT_CONTEXT_LINES);
-	const clamped = clampTopK(topK);
-	if (clamped.clamped) yield* d.log(`topK clamped from ${topK} to ${clamped.value}`, "warn");
-	const results = yield* d.spinner("Searching...", QueryProject.queryProject(queryText, clamped.value));
-	yield* d.json(toJsonOutput(results, ctxLines));
-	if (results.length === 0) yield* d.log("No results found", "warn");
-	else for (const result of results) yield* d.text(formatResult(result));
+	const { options: searchOptions, clamped, rawValue } = buildSearchOptions(top, ignorePath, onlyPath);
+	if (clamped) yield* d.log(`topK clamped from ${rawValue} to ${searchOptions.topK}`, "warn");
+	const searchResponse = yield* d.spinner("Searching...", QueryProject.queryProject(queryText, searchOptions));
+	const finalResults = noContent ? searchResponse.results : applyCharBudget(searchResponse.results, Option.getOrUndefined(maxCharacters)).results;
+	yield* renderResults(d, {
+		...searchResponse,
+		results: finalResults
+	}, ctxLines, noContent);
 }).pipe(Effect.catchTags({
 	ModelLoadError: reportError,
 	InferenceError: reportError,
@@ -695,20 +826,6 @@ const queryCommand = Command.make("query", {
 	NoIndexError: reportError
 })));
 //#endregion
-//#region src/lib/format.ts
-/** Format byte count as human-readable string (e.g. "1.5 MB") */
-const formatBytes = (bytes) => {
-	if (bytes === 0) return "0 B";
-	const units = [
-		"B",
-		"KB",
-		"MB",
-		"GB"
-	];
-	const i = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1);
-	return `${(bytes / 1024 ** i).toFixed(1)} ${units[i]}`;
-};
-//#endregion
 //#region src/commands/reset.ts
 /** CLI command: pix reset [--json] */
 const resetCommand = Command.make("reset", { json: Options.boolean("json").pipe(Options.withDefault(false)) }, () => Effect.gen(function* () {
@@ -747,6 +864,7 @@ const statusCommand = Command.make("status", { json: Options.boolean("json").pip
 	yield* d.log(`Total lines: ${result.totalLines.toLocaleString()}`, "info");
 	yield* d.log(`Index size: ${result.byteSize.toLocaleString()} bytes`, "info");
 	yield* d.log(`Last indexed: ${lastIndexStr}`, "info");
+	if (result.validationErrors.length > 0) yield* d.log(`Warnings: ${result.validationErrors[0].message}`, "warn");
 }).pipe(Effect.catchTags({ StoreError: reportError })));
 //#endregion
 //#region src/cli.ts
@@ -822,13 +940,19 @@ const buildChunks = (file, content, config) => {
 		const text = lines.slice(startLine - 1, endLine).join("\n");
 		if (text.length >= MIN_CHUNK_CHARS) {
 			const id = crypto.createHash("sha1").update(`${file}:${startLine}`).digest("hex").slice(0, 12);
+			const contextBeforeStart = Math.max(0, startLine - 1 - config.overlapLines);
+			const contextBefore = lines.slice(contextBeforeStart, startLine - 1).join("\n");
+			const contextAfterEnd = Math.min(lines.length, endLine + config.overlapLines);
+			const contextAfter = lines.slice(endLine, contextAfterEnd).join("\n");
 			chunks.push({
 				id,
 				idx,
 				file,
 				startLine,
 				endLine,
-				text
+				text,
+				contextBefore: contextBefore || null,
+				contextAfter: contextAfter || null
 			});
 			idx++;
 		}
@@ -855,12 +979,59 @@ const make$5 = Effect.gen(function* () {
 });
 const ChunkerLive = Layer.effect(Chunker, make$5);
 //#endregion
+//#region src/lib/platform-error.ts
+/**
+* Check if a platform error has a specific `reason` string (e.g. "BadResource" for disk full,
+* "NotFound" for missing files). Platform errors from @effect/platform include a `reason` property
+* that categorizes the failure.
+*/
+const isPlatformReason = (cause, reason) => typeof cause === "object" && cause !== null && "reason" in cause && String(cause.reason) === reason;
+//#endregion
+//#region src/lib/validation.ts
+const mergeMessages = (messages) => {
+	if (messages.length === 1) return messages[0];
+	const uniq = [...new Set(messages)];
+	if (uniq.every((m) => m.startsWith("Expected"))) {
+		const actualMatch = uniq[0].match(/actual (.+)$/);
+		const actual = actualMatch ? actualMatch[1] : "";
+		return `Expected ${uniq.map((m) => m.replace(/^Expected /, "").replace(/, actual .+$/, "")).join(" | ")}, actual ${actual}`;
+	}
+	return uniq.join("\n");
+};
+const formatSchemaErrors = (error) => {
+	const issues = ParseResult.ArrayFormatter.formatErrorSync(error);
+	const byPath = /* @__PURE__ */ new Map();
+	for (const issue of issues) {
+		const path = issue.path.join(".");
+		if (!byPath.has(path)) byPath.set(path, []);
+		byPath.get(path).push(issue.message);
+	}
+	return Array.from(byPath.entries()).map(([path, messages]) => ({
+		path,
+		message: mergeMessages(messages)
+	}));
+};
+const formatSchemaMessage = (error) => ParseResult.TreeFormatter.formatErrorSync(error);
+const isJsonSyntaxError = (error) => error.issue._tag === "Transformation" && error.issue.kind === "Transformation";
+const decodeJsonWithErrors = (schema, json) => Schema.decodeUnknown(Schema.parseJson(schema))(json).pipe(Effect.mapError((error) => {
+	const base = {
+		message: formatSchemaMessage(error),
+		errors: formatSchemaErrors(error)
+	};
+	return isJsonSyntaxError(error) ? {
+		...base,
+		_tag: "JsonSyntaxError"
+	} : {
+		...base,
+		_tag: "SchemaValidationError"
+	};
+}));
+//#endregion
 //#region src/services/config-store.ts
 const CONFIG_DIR = ".pix";
 const CONFIG_PATH = `${CONFIG_DIR}/config.json`;
-const isPlatformReason$1 = (cause, reason) => typeof cause === "object" && cause !== null && "reason" in cause && String(cause.reason) === reason;
 const mapConfigWriteError = (cause, path, action) => {
-	if (isPlatformReason$1(cause, "BadResource")) return new DiskFullError({
+	if (isPlatformReason(cause, "BadResource")) return new DiskFullError({
 		message: `Disk full: could not ${action}`,
 		path,
 		cause
@@ -873,13 +1044,17 @@ const mapConfigWriteError = (cause, path, action) => {
 const make$4 = Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const writeConfig = (config) => Effect.gen(function* () {
-		const configJson = JSON.stringify(config, null, 2);
+		const encodeJson = Schema.parseJson(ConfigSchema, { space: 2 });
+		const configJson = yield* Schema.encode(encodeJson)(config).pipe(Effect.mapError((e) => new ConfigError({
+			message: "Failed to encode config",
+			cause: e
+		})));
 		yield* fs.makeDirectory(CONFIG_DIR, { recursive: true }).pipe(Effect.mapError((cause) => mapConfigWriteError(cause, CONFIG_DIR, "create .pix directory")));
 		yield* fs.writeFileString(CONFIG_PATH, configJson).pipe(Effect.mapError((cause) => mapConfigWriteError(cause, CONFIG_PATH, "write config.json")));
 	});
 	const readConfig = () => Effect.gen(function* () {
-		const content = yield* fs.readFileString(CONFIG_PATH).pipe(Effect.mapError((cause) => {
-			if (isPlatformReason$1(cause, "NotFound")) return new ConfigNotFoundError({
+		return yield* decodeJsonWithErrors(ConfigSchema, yield* fs.readFileString(CONFIG_PATH).pipe(Effect.mapError((cause) => {
+			if (isPlatformReason(cause, "NotFound")) return new ConfigNotFoundError({
 				message: "Config file not found. Run pix init first.",
 				path: CONFIG_PATH,
 				cause
@@ -888,15 +1063,17 @@ const make$4 = Effect.gen(function* () {
 				message: "Failed to read config.json",
 				cause
 			});
-		}));
-		return yield* Effect.try({
-			try: () => JSON.parse(content),
-			catch: (error) => new ConfigMalformedError({
+		}))).pipe(Effect.mapError((err) => {
+			if (err._tag === "JsonSyntaxError") return new ConfigMalformedError({
 				message: "Invalid JSON in config.json",
 				path: CONFIG_PATH,
-				cause: error
-			})
-		});
+				cause: err
+			});
+			return new ConfigValidationError({
+				message: err.message,
+				errors: err.errors
+			});
+		}));
 	});
 	const configExists = () => Effect.gen(function* () {
 		return yield* fs.exists(CONFIG_PATH);
@@ -914,10 +1091,7 @@ const make$3 = Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const processorMap = buildProcessorMap([]);
 	const extract = (file) => {
-		const lastSlash = file.lastIndexOf("/");
-		const name = lastSlash >= 0 ? file.slice(lastSlash + 1) : file;
-		const dotIndex = name.lastIndexOf(".");
-		const ext = dotIndex === -1 ? name.toLowerCase() : name.slice(dotIndex).toLowerCase();
+		const ext = getExtension(file);
 		const processor = processorMap[ext];
 		if (!processor) return Effect.fail({
 			_tag: "UnsupportedFormat",
@@ -1207,11 +1381,46 @@ const make$1 = Effect.gen(function* () {
 });
 const ScannerLive = Layer.effect(Scanner, make$1);
 //#endregion
+//#region src/domain/chunk.ts
+/** Runtime schema for persisted/searchable chunk entries. */
+const ChunkSchema = Schema.Struct({
+	id: Schema.String,
+	idx: Schema.Number,
+	file: Schema.String,
+	startLine: Schema.Number,
+	endLine: Schema.Number,
+	text: Schema.String,
+	contextBefore: Schema.Union(Schema.String, Schema.Null),
+	contextAfter: Schema.Union(Schema.String, Schema.Null)
+});
+//#endregion
 //#region src/services/vector-store.ts
+const parseChunkLine = (line) => {
+	try {
+		return Option.some(Schema.decodeUnknownSync(Schema.parseJson(ChunkSchema))(line));
+	} catch {
+		return Option.none();
+	}
+};
+/** Compute dot-product similarity between a chunk vector and the query embedding. */
+const computeDotProduct = (chunkVector, query) => {
+	let dot = 0;
+	for (let j = 0; j < query.dims; j++) dot += chunkVector[j] * query.vector[j];
+	return dot;
+};
 const STORE_DIR = ".pix";
 const CHUNKS_FILE = `${STORE_DIR}/chunks.jsonl`;
 const VECTORS_FILE = `${STORE_DIR}/vectors.bin`;
-const isPlatformReason = (cause, reason) => typeof cause === "object" && cause !== null && "reason" in cause && String(cause.reason) === reason;
+/** Pre-built Schema instance for chunk encode/decode. */
+const parseJsonChunk = Schema.parseJson(ChunkSchema);
+/** Build ChunkValidationError array from malformed line count, or [] if none. */
+const buildChunkValidationErrors = (malformedLines) => malformedLines > 0 ? [new ChunkValidationError({
+	message: `Skipped ${malformedLines} malformed chunk line(s) in chunks.jsonl`,
+	errors: [{
+		path: "chunks.jsonl",
+		message: `${malformedLines} line(s) failed schema validation`
+	}]
+})] : [];
 /**
 * FileSystem adapter for VectorStore port. Reads from chunks.jsonl and vectors.bin to provide index
 * statistics.
@@ -1238,22 +1447,30 @@ const make = Effect.gen(function* () {
 	* Count total lines across all chunks in chunks.jsonl. Each line is a JSON object; the 'text'
 	* field contains the source code.
 	*/
-	const countTotalLines = (lines) => lines.reduce((sum, line) => {
-		try {
-			return sum + JSON.parse(line).text.split("\n").length;
-		} catch {
-			return sum;
-		}
-	}, 0);
-	/** Count unique files across all chunks in chunks.jsonl. */
-	const countUniqueFiles = (lines) => {
+	/** Count files, total lines, and malformed lines in a single pass. */
+	const countChunkStats = (lines) => {
 		const files = /* @__PURE__ */ new Set();
-		for (const line of lines) try {
-			const chunk = JSON.parse(line);
-			files.add(chunk.file);
-		} catch {}
-		return files;
+		let totalLines = 0;
+		let malformedLines = 0;
+		for (const line of lines) {
+			const chunk = parseChunkLine(line);
+			if (Option.isSome(chunk)) {
+				files.add(chunk.value.file);
+				totalLines += chunk.value.text.split("\n").length;
+			} else malformedLines++;
+		}
+		return {
+			files,
+			totalLines,
+			malformedLines
+		};
 	};
+	/** Check that index files exist; fail with NoIndexError if either is missing. */
+	const requireIndex = () => Effect.gen(function* () {
+		const chunksExists = yield* withReadError(fs.exists(CHUNKS_FILE), "check chunks file");
+		const vectorsExists = yield* withReadError(fs.exists(VECTORS_FILE), "check vectors file");
+		if (!chunksExists || !vectorsExists) return yield* new NoIndexError({ message: "No index found. Run pix index first." });
+	});
 	const toStoreError = (operation, path) => (cause) => {
 		if (isPlatformReason(cause, "BadResource")) return new DiskFullError({
 			message: `Disk full during ${operation}`,
@@ -1309,14 +1526,10 @@ const make = Effect.gen(function* () {
 		if (yield* withStoreError(fs.exists(vectorsTemp), "check vectors temp")) yield* withStoreError(fs.remove(vectorsTemp), "clean stale vectors temp", vectorsTemp);
 	});
 	const storeBatch = (chunks, embeddings) => Effect.gen(function* () {
-		const content = chunks.map((c) => JSON.stringify({
-			id: c.id,
-			idx: c.idx,
-			file: c.file,
-			startLine: c.startLine,
-			endLine: c.endLine,
-			text: c.text
-		})).join("\n") + "\n";
+		const content = (yield* Effect.forEach(chunks, (c) => Schema.encode(parseJsonChunk)(c).pipe(Effect.mapError((e) => new StoreError({
+			message: "Failed to encode chunk",
+			cause: e
+		}))))).join("\n") + "\n";
 		yield* withStoreError(fs.writeFile(chunksTemp, Buffer.from(content), { flag: "a" }), "append chunks", chunksTemp);
 		const buffer = serializeVectors(embeddings);
 		yield* withStoreError(fs.writeFile(vectorsTemp, buffer, { flag: "a" }), "append vectors", vectorsTemp);
@@ -1353,37 +1566,39 @@ const make = Effect.gen(function* () {
 	const store = (chunks, embeddings) => Effect.gen(function* () {
 		yield* ensureDirExists(STORE_DIR, ".pix directory");
 		const chunksTemp = `${CHUNKS_FILE}.tmp`;
-		const chunksLines = chunks.map((c) => JSON.stringify({
-			id: c.id,
-			idx: c.idx,
-			file: c.file,
-			startLine: c.startLine,
-			endLine: c.endLine,
-			text: c.text
-		}));
-		yield* withStoreError(fs.writeFileString(chunksTemp, chunksLines.join("\n")), "write chunks", chunksTemp);
+		const chunksJson = (yield* Effect.forEach(chunks, (c) => Schema.encode(parseJsonChunk)(c).pipe(Effect.mapError((e) => new StoreError({
+			message: "Failed to encode chunk",
+			cause: e
+		}))))).join("\n");
+		yield* withStoreError(fs.writeFileString(chunksTemp, chunksJson), "write chunks", chunksTemp);
 		yield* withStoreError(fs.rename(chunksTemp, CHUNKS_FILE), "commit chunks", CHUNKS_FILE);
 		const vectorsTemp = `${VECTORS_FILE}.tmp`;
 		const buffer = serializeVectors(embeddings);
 		yield* withStoreError(fs.writeFile(vectorsTemp, buffer), "write vectors", vectorsTemp);
 		yield* withStoreError(fs.rename(vectorsTemp, VECTORS_FILE), "commit vectors", VECTORS_FILE);
 	});
-	const search = (query, topK) => Effect.gen(function* () {
-		const chunksExists = yield* withReadError(fs.exists(CHUNKS_FILE), "check chunks file");
-		const vectorsExists = yield* withReadError(fs.exists(VECTORS_FILE), "check vectors file");
-		if (!chunksExists || !vectorsExists) return yield* new NoIndexError({ message: "No index found. Run pix index first." });
+	const search = (query, options) => Effect.gen(function* () {
+		yield* requireIndex();
 		const chunkLines = (yield* withReadError(fs.readFileString(CHUNKS_FILE), "read chunks", CHUNKS_FILE)).split("\n").filter((l) => l.trim().length > 0);
 		const vectorsBuffer = yield* withReadError(fs.readFile(VECTORS_FILE), "read vectors", VECTORS_FILE);
-		const vectors = new Float32Array(vectorsBuffer.buffer);
+		const vectors = new Float32Array(vectorsBuffer.buffer, vectorsBuffer.byteOffset, vectorsBuffer.byteLength / Float32Array.BYTES_PER_ELEMENT);
+		const ignoreIg = options?.ignorePaths?.length ? ignore().add([...options.ignorePaths]) : null;
+		const onlyIg = options?.onlyPaths?.length ? ignore().add([...options.onlyPaths]) : null;
 		const results = [];
-		for (let i = 0; i < chunkLines.length; i++) try {
-			const chunk = JSON.parse(chunkLines[i]);
+		let malformedLines = 0;
+		for (let i = 0; i < chunkLines.length; i++) {
+			const parsed = parseChunkLine(chunkLines[i]);
+			if (Option.isNone(parsed)) {
+				malformedLines++;
+				continue;
+			}
+			const chunk = parsed.value;
+			if (ignoreIg && ignoreIg.ignores(chunk.file)) continue;
+			if (onlyIg && !onlyIg.ignores(chunk.file)) continue;
 			const startIdx = i * query.dims;
-			const chunkVector = vectors.slice(startIdx, startIdx + query.dims);
-			let dotProduct = 0;
-			for (let j = 0; j < query.dims; j++) dotProduct += chunkVector[j] * query.vector[j];
+			const score = computeDotProduct(vectors.slice(startIdx, startIdx + query.dims), query);
 			results.push({
-				score: dotProduct,
+				score,
 				file: chunk.file,
 				startLine: chunk.startLine,
 				endLine: chunk.endLine,
@@ -1391,9 +1606,19 @@ const make = Effect.gen(function* () {
 				contextBefore: chunk.contextBefore,
 				contextAfter: chunk.contextAfter
 			});
-		} catch {}
+		}
+		const validationErrors = buildChunkValidationErrors(malformedLines);
 		results.sort((a, b) => b.score - a.score);
-		return results.slice(0, topK);
+		const topK = options?.topK;
+		if (topK == null) return {
+			results,
+			validationErrors
+		};
+		const clamped = Math.max(0, Math.min(Math.floor(topK), results.length));
+		return {
+			results: results.slice(0, clamped),
+			validationErrors
+		};
 	});
 	const getStatus = () => Effect.gen(function* () {
 		const chunksExists = yield* withReadError(fs.exists(CHUNKS_FILE), "check chunks file");
@@ -1404,13 +1629,15 @@ const make = Effect.gen(function* () {
 			model: "",
 			lastIndex: 0,
 			totalLines: 0,
-			byteSize: 0
+			byteSize: 0,
+			validationErrors: []
 		};
 		const lines = (yield* withReadError(fs.readFileString(CHUNKS_FILE), "read chunks", CHUNKS_FILE)).split("\n").filter((l) => l.trim().length > 0);
-		const chunks = lines.length;
-		const files = countUniqueFiles(lines).size;
+		const { files: uniqueFiles, totalLines, malformedLines } = countChunkStats(lines);
+		const chunks = lines.length - malformedLines;
+		const files = uniqueFiles.size;
 		const model = "";
-		const totalLines = countTotalLines(lines);
+		const validationErrors = buildChunkValidationErrors(malformedLines);
 		const vectorsStat = yield* withReadError(fs.stat(VECTORS_FILE), "stat vectors", VECTORS_FILE);
 		const byteSize = "size" in vectorsStat ? Number(vectorsStat.size) : 0;
 		return {
@@ -1419,7 +1646,8 @@ const make = Effect.gen(function* () {
 			model,
 			lastIndex: Option.map(vectorsStat?.mtime ?? Option.none(), (d) => d instanceof Date ? d.getTime() : 0).pipe(Option.getOrElse(() => 0)),
 			totalLines,
-			byteSize
+			byteSize,
+			validationErrors
 		};
 	});
 	const reset = () => Effect.gen(function* () {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucas-bur/pix",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Lightweight local semantic project indexer",
   "keywords": [
     "cli",