@lucas-bur/pix 0.11.0 → 0.12.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

@@ -184,6 +184,32 @@ 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
 /** Config file or directory does not exist. Run pix init first. */
 var ConfigNotFoundError = class extends Data.TaggedError("ConfigNotFoundError") {};
@@ -315,13 +341,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 = [];
@@ -444,11 +463,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 +518,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 };
 	})
 }) {};
@@ -636,6 +650,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 +721,64 @@ 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, results, ctxLines, noContent) => Effect.gen(function* () {
+	yield* d.json(toJsonOutput(results, ctxLines, noContent));
+	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 results = yield* d.spinner("Searching...", QueryProject.queryProject(queryText, searchOptions));
+	yield* renderResults(d, noContent ? results : applyCharBudget(results, Option.getOrUndefined(maxCharacters)).results, ctxLines, noContent);
 }).pipe(Effect.catchTags({
 	ModelLoadError: reportError,
 	InferenceError: reportError,
@@ -695,20 +787,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* () {
@@ -822,13 +900,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 +939,19 @@ 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/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
@@ -879,7 +970,7 @@ const make$4 = Effect.gen(function* () {
 	});
 	const readConfig = () => Effect.gen(function* () {
 		const content = yield* fs.readFileString(CONFIG_PATH).pipe(Effect.mapError((cause) => {
-			if (isPlatformReason$1(cause, "NotFound")) return new ConfigNotFoundError({
+			if (isPlatformReason(cause, "NotFound")) return new ConfigNotFoundError({
 				message: "Config file not found. Run pix init first.",
 				path: CONFIG_PATH,
 				cause
@@ -914,10 +1005,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",
@@ -1208,10 +1296,44 @@ const make$1 = Effect.gen(function* () {
 const ScannerLive = Layer.effect(Scanner, make$1);
 //#endregion
 //#region src/services/vector-store.ts
+/**
+* Parse a single JSON line from chunks.jsonl and normalize context fields (old indexes may lack
+* them).
+*/
+const parseChunkLine = (line) => {
+	const raw = JSON.parse(line);
+	return {
+		file: typeof raw.file === "string" ? raw.file : "",
+		startLine: typeof raw.startLine === "number" ? raw.startLine : 0,
+		endLine: typeof raw.endLine === "number" ? raw.endLine : 0,
+		text: typeof raw.text === "string" ? raw.text : "",
+		contextBefore: typeof raw.contextBefore === "string" ? raw.contextBefore : null,
+		contextAfter: typeof raw.contextAfter === "string" ? raw.contextAfter : null
+	};
+};
+/** 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;
+/**
+* Serialize a Chunk to a JSON object for storage in chunks.jsonl. Always includes context fields
+* for schema consistency.
+*/
+const serializeChunk = (c) => ({
+	id: c.id,
+	idx: c.idx,
+	file: c.file,
+	startLine: c.startLine,
+	endLine: c.endLine,
+	text: c.text,
+	contextBefore: c.contextBefore,
+	contextAfter: c.contextAfter
+});
 /**
 * FileSystem adapter for VectorStore port. Reads from chunks.jsonl and vectors.bin to provide index
 * statistics.
@@ -1309,14 +1431,7 @@ 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 = chunks.map((c) => JSON.stringify(serializeChunk(c))).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 +1468,32 @@ 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 = chunks.map((c) => JSON.stringify(serializeChunk(c))).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 search = (query, options) => 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 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]);
+			const chunk = parseChunkLine(chunkLines[i]);
+			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,
@@ -1393,7 +1503,10 @@ const make = Effect.gen(function* () {
 			});
 		} catch {}
 		results.sort((a, b) => b.score - a.score);
-		return results.slice(0, topK);
+		const topK = options?.topK;
+		if (topK == null) return results;
+		const clamped = Math.max(0, Math.min(Math.floor(topK), results.length));
+		return results.slice(0, clamped);
 	});
 	const getStatus = () => Effect.gen(function* () {
 		const chunksExists = yield* withReadError(fs.exists(CHUNKS_FILE), "check chunks file");

package/package.json

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