@gmickel/gno 1.8.0 → 1.10.0

package/src/serve/routes/api.ts

@@ -35,6 +35,10 @@ import {
   removeCollection,
   updateCollection,
 } from "../../collection";
+import {
+  fingerprintContentTypeRules,
+  normalizeContentTypes,
+} from "../../config";
 import {
   buildCaptureReceipt,
   listCaptureDiskRelPaths,
@@ -82,7 +86,11 @@ import {
   validateTag,
 } from "../../core/tags";
 import { validateRelPath } from "../../core/validation";
-import { defaultSyncService, type SyncResult } from "../../ingestion";
+import {
+  defaultSyncService,
+  type SyncResult,
+  withContentTypeRules,
+} from "../../ingestion";
 import { updateFrontmatterTags } from "../../ingestion/frontmatter";
 import {
   getCollectionEffectiveModels,
@@ -96,6 +104,7 @@ import {
   generateGroundedAnswer,
   processAnswerResult,
 } from "../../pipeline/answer";
+import { diagnoseQueryTarget } from "../../pipeline/diagnose";
 import { searchHybrid } from "../../pipeline/hybrid";
 import { validateQueryModes } from "../../pipeline/query-modes";
 import { searchBm25 } from "../../pipeline/search";
@@ -188,6 +197,10 @@ export interface QueryRequestBody {
   tagsAny?: string;
 }
 
+export interface QueryDiagnoseRequestBody extends QueryRequestBody {
+  target?: string;
+}
+
 export interface AskRequestBody {
   query: string;
   limit?: number;
@@ -919,10 +932,17 @@ export async function handleCreateCollection(
     return errorResponse("RUNTIME", "Collection not found after add", 500);
   }
   const jobResult = startJob("add", async (): Promise<SyncResult> => {
-    const result = await defaultSyncService.syncCollection(collection, store, {
-      gitPull: body.gitPull,
-      runUpdateCmd: true,
-    });
+    const result = await defaultSyncService.syncCollection(
+      collection,
+      store,
+      withContentTypeRules(
+        {
+          gitPull: body.gitPull,
+          runUpdateCmd: true,
+        },
+        syncResult.config
+      )
+    );
     if (result.filesAdded > 0 || result.filesUpdated > 0) {
       if (ctxHolder.scheduler) {
         await ctxHolder.scheduler.triggerNow();
@@ -1214,10 +1234,17 @@ export async function handleSync(
 
   // Start background sync job
   const jobResult = startJob("sync", async (): Promise<SyncResult> => {
-    const result = await defaultSyncService.syncAll(collections, store, {
-      gitPull: body.gitPull,
-      runUpdateCmd: true,
-    });
+    const result = await defaultSyncService.syncAll(
+      collections,
+      store,
+      withContentTypeRules(
+        {
+          gitPull: body.gitPull,
+          runUpdateCmd: true,
+        },
+        ctxHolder.config
+      )
+    );
     if (result.totalFilesAdded > 0 || result.totalFilesUpdated > 0) {
       if (ctxHolder.scheduler) {
         await ctxHolder.scheduler.triggerNow();
@@ -1843,9 +1870,11 @@ export async function handleRenameDoc(
     const nextUri = `gno://${collection.name}/${nextRelPath}`;
     let warning: string | undefined;
     try {
-      await syncCollection(collection, store, {
-        runUpdateCmd: false,
-      });
+      await syncCollection(
+        collection,
+        store,
+        withContentTypeRules({ runUpdateCmd: false }, ctxHolder.config)
+      );
     } catch {
       warning =
         "File renamed on disk, but index refresh failed. Run Update All to reconcile the workspace.";
@@ -2063,9 +2092,11 @@ export async function handleTrashDoc(
     }
     let warning: string | undefined;
     try {
-      await syncCollection(collection, store, {
-        runUpdateCmd: false,
-      });
+      await syncCollection(
+        collection,
+        store,
+        withContentTypeRules({ runUpdateCmd: false }, ctxHolder.config)
+      );
     } catch {
       warning =
         "File moved to Trash, but index refresh failed. Run Update All to reconcile the workspace.";
@@ -2184,9 +2215,11 @@ export async function handleMoveDoc(
     await renameFilePath(fullPath, nextFullPath);
     let warning: string | undefined;
     try {
-      await defaultSyncService.syncCollection(collection, store, {
-        runUpdateCmd: false,
-      });
+      await defaultSyncService.syncCollection(
+        collection,
+        store,
+        withContentTypeRules({ runUpdateCmd: false }, ctxHolder.config)
+      );
     } catch {
       warning =
         "File moved on disk, but index refresh failed. Run Update All to reconcile the workspace.";
@@ -2305,9 +2338,11 @@ export async function handleDuplicateDoc(
     await copyFilePath(fullPath, nextFullPath);
     let warning: string | undefined;
     try {
-      await defaultSyncService.syncCollection(collection, store, {
-        runUpdateCmd: false,
-      });
+      await defaultSyncService.syncCollection(
+        collection,
+        store,
+        withContentTypeRules({ runUpdateCmd: false }, ctxHolder.config)
+      );
     } catch {
       warning =
         "File duplicated on disk, but index refresh failed. Run Update All to reconcile the workspace.";
@@ -2636,7 +2671,7 @@ export async function handleUpdateDoc(
         const result = await defaultSyncService.syncCollection(
           collection,
           store,
-          { runUpdateCmd: false }
+          withContentTypeRules({ runUpdateCmd: false }, ctxHolder.config)
         );
         // Notify scheduler after sync completes
         ctxHolder.scheduler?.notifySyncComplete([doc.docid]);
@@ -2904,7 +2939,7 @@ export async function handleCreateCapture(
       const result = await defaultSyncService.syncCollection(
         collection,
         store,
-        { runUpdateCmd: false }
+        withContentTypeRules({ runUpdateCmd: false }, ctxHolder.config)
       );
       ctxHolder.scheduler?.notifySyncComplete([plan.relPath]);
       ctxHolder.eventBus?.emit({
@@ -3140,7 +3175,7 @@ export async function handleCreateDoc(
       const result = await defaultSyncService.syncCollection(
         collection,
         store,
-        { runUpdateCmd: false }
+        withContentTypeRules({ runUpdateCmd: false }, ctxHolder.config)
       );
       // Notify scheduler after sync completes (use gnoUri as docid placeholder)
       // The sync will create a proper docid, but we don't have it here yet
@@ -3491,6 +3526,191 @@ export async function handleQuery(
   return jsonResponse(result.value);
 }
 
+/**
+ * POST /api/query/diagnose
+ * Body: { query, target, limit?, minScore?, collection?, lang?, queryModes?, noExpand?, noRerank?, graph? }
+ * Returns targeted retrieval diagnostics for one document.
+ */
+export async function handleQueryDiagnose(
+  ctx: ServerContext,
+  req: Request
+): Promise<Response> {
+  let body: QueryDiagnoseRequestBody;
+  try {
+    body = (await req.json()) as QueryDiagnoseRequestBody;
+  } catch {
+    return errorResponse("VALIDATION", "Invalid JSON body");
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return errorResponse("VALIDATION", "JSON body must be an object");
+  }
+
+  if (!body.query || typeof body.query !== "string") {
+    return errorResponse("VALIDATION", "Missing or invalid query");
+  }
+  if (!body.target || typeof body.target !== "string") {
+    return errorResponse("VALIDATION", "Missing or invalid target");
+  }
+
+  const rawQuery = body.query.trim();
+  const target = body.target.trim();
+  if (!rawQuery) {
+    return errorResponse("VALIDATION", "Query cannot be empty");
+  }
+  if (!target) {
+    return errorResponse("VALIDATION", "target cannot be empty");
+  }
+
+  if (
+    body.limit !== undefined &&
+    (typeof body.limit !== "number" || body.limit < 1)
+  ) {
+    return errorResponse("VALIDATION", "limit must be a positive integer");
+  }
+  if (
+    body.minScore !== undefined &&
+    (typeof body.minScore !== "number" ||
+      body.minScore < 0 ||
+      body.minScore > 1)
+  ) {
+    return errorResponse(
+      "VALIDATION",
+      "minScore must be a number between 0 and 1"
+    );
+  }
+  if (body.since !== undefined && typeof body.since !== "string") {
+    return errorResponse("VALIDATION", "since must be a string");
+  }
+  if (body.until !== undefined && typeof body.until !== "string") {
+    return errorResponse("VALIDATION", "until must be a string");
+  }
+  if (body.intent !== undefined && typeof body.intent !== "string") {
+    return errorResponse("VALIDATION", "intent must be a string");
+  }
+  if (body.exclude !== undefined && typeof body.exclude !== "string") {
+    return errorResponse(
+      "VALIDATION",
+      "exclude must be a comma-separated string"
+    );
+  }
+  if (
+    body.candidateLimit !== undefined &&
+    (typeof body.candidateLimit !== "number" || body.candidateLimit < 1)
+  ) {
+    return errorResponse(
+      "VALIDATION",
+      "candidateLimit must be a positive integer"
+    );
+  }
+  if (body.category !== undefined && typeof body.category !== "string") {
+    return errorResponse(
+      "VALIDATION",
+      "category must be a comma-separated string"
+    );
+  }
+  if (body.author !== undefined && typeof body.author !== "string") {
+    return errorResponse("VALIDATION", "author must be a string");
+  }
+
+  const { queryModes, error: queryModesError } = parseQueryModesInput(
+    body.queryModes
+  );
+  if (queryModesError) {
+    return queryModesError;
+  }
+
+  const {
+    query,
+    queryModes: normalizedQueryModes,
+    error: structuredQueryError,
+  } = normalizeStructuredQueryBody(rawQuery, queryModes);
+  if (structuredQueryError) {
+    return structuredQueryError;
+  }
+  const normalizedQuery = query ?? rawQuery;
+
+  let tagsAll: string[] | undefined;
+  let tagsAny: string[] | undefined;
+
+  if (body.tagsAll) {
+    try {
+      tagsAll = parseAndValidateTagFilter(body.tagsAll);
+    } catch (e) {
+      return errorResponse(
+        "VALIDATION",
+        e instanceof Error ? e.message : "Invalid tagsAll"
+      );
+    }
+  }
+
+  if (body.tagsAny) {
+    try {
+      tagsAny = parseAndValidateTagFilter(body.tagsAny);
+    } catch (e) {
+      return errorResponse(
+        "VALIDATION",
+        e instanceof Error ? e.message : "Invalid tagsAny"
+      );
+    }
+  }
+
+  const categories = body.category
+    ? parseCommaSeparatedValues(body.category)
+    : undefined;
+  const exclude = body.exclude
+    ? parseCommaSeparatedValues(body.exclude)
+    : undefined;
+  const author = body.author?.trim() || undefined;
+  const contentTypeRules = normalizeContentTypes(
+    ctx.config.contentTypes ?? []
+  ).rules;
+
+  const result = await diagnoseQueryTarget(
+    {
+      store: ctx.store,
+      config: ctx.config,
+      vectorIndex: ctx.vectorIndex,
+      embedPort: ctx.embedPort,
+      expandPort: ctx.expandPort,
+      rerankPort: ctx.rerankPort,
+    },
+    normalizedQuery,
+    {
+      target,
+      limit: Math.min(body.limit ?? 20, 50),
+      minScore: body.minScore,
+      collection: body.collection,
+      lang: body.lang,
+      intent: body.intent?.trim() || undefined,
+      candidateLimit:
+        body.candidateLimit !== undefined
+          ? Math.min(body.candidateLimit, 100)
+          : undefined,
+      exclude,
+      queryModes: normalizedQueryModes,
+      noExpand: body.noExpand,
+      noRerank: body.noRerank,
+      graph: body.graph === true,
+      noGraph: body.noGraph,
+      tagsAll,
+      tagsAny,
+      since: body.since,
+      until: body.until,
+      categories,
+      author,
+      contentTypeRules,
+      contentTypeRulesFingerprint:
+        fingerprintContentTypeRules(contentTypeRules),
+    }
+  );
+
+  if (!result.ok) {
+    return errorResponse("RUNTIME", result.error.message, 500);
+  }
+
+  return jsonResponse(result.value);
+}
+
 /**
  * POST /api/ask
  * Body: { query, limit?, collection?, lang?, maxAnswerTokens? }

package/src/serve/routes/graph.ts

@@ -4,8 +4,17 @@
  * @module src/serve/routes/graph
  */
 
+import type { Config } from "../../config/types";
 import type { SqliteAdapter } from "../../store/sqlite/adapter";
-import type { GetGraphOptions, GraphResult } from "../../store/types";
+import type {
+  GetGraphOptions,
+  GraphQueryDirection,
+  GraphQueryResult,
+  GraphResult,
+} from "../../store/types";
+
+import { normalizeContentTypes } from "../../config";
+import { diagnoseGraphQuery } from "../../core/graph-query";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
@@ -13,6 +22,21 @@ import type { GetGraphOptions, GraphResult } from "../../store/types";
 
 export interface GraphResponse extends GraphResult {}
 
+export interface GraphQueryResponse extends GraphQueryResult {}
+
+interface GraphQueryRequestBody {
+  doc?: string;
+  root?: string;
+  direction?: GraphQueryDirection;
+  edgeType?: string;
+  relation?: string;
+  maxDepth?: number;
+  depth?: number;
+  maxNodes?: number;
+  frontierLimit?: number;
+  visitedLimit?: number;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Helpers
 // ─────────────────────────────────────────────────────────────────────────────
@@ -67,6 +91,29 @@ function parseThreshold(
   return { ok: true, value: parsed };
 }
 
+function parseBodyPositiveInt(
+  name: string,
+  value: number | undefined,
+  defaultValue: number,
+  min: number,
+  max: number
+): ParseResult {
+  if (value === undefined) return { ok: true, value: defaultValue };
+  if (!Number.isFinite(value) || !Number.isInteger(value)) {
+    return {
+      ok: false,
+      message: `${name} must be an integer between ${min} and ${max}`,
+    };
+  }
+  if (value < min || value > max) {
+    return {
+      ok: false,
+      message: `${name} must be between ${min} and ${max}`,
+    };
+  }
+  return { ok: true, value };
+}
+
 /**
  * Parse boolean query param (true if "true" or "1", false otherwise).
  */
@@ -160,3 +207,128 @@ export async function handleGraph(
 
   return jsonResponse(result.value satisfies GraphResponse);
 }
+
+/**
+ * POST /api/graph/query
+ * Returns bounded typed-edge traversal from one resolved root document.
+ */
+export async function handleGraphQuery(
+  store: SqliteAdapter,
+  config: Config,
+  req: Request
+): Promise<Response> {
+  let body: GraphQueryRequestBody;
+  try {
+    body = (await req.json()) as GraphQueryRequestBody;
+  } catch {
+    return errorResponse("VALIDATION", "Invalid JSON body", 400);
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return errorResponse("VALIDATION", "JSON body must be an object", 400);
+  }
+
+  const docRef = body.doc ?? body.root;
+  if (!docRef || typeof docRef !== "string") {
+    return errorResponse("VALIDATION", "Missing or invalid doc", 400);
+  }
+  const rootRef = docRef.trim();
+  if (!rootRef) {
+    return errorResponse("VALIDATION", "doc cannot be empty", 400);
+  }
+
+  const direction = body.direction ?? "both";
+  if (!["out", "in", "both"].includes(direction)) {
+    return errorResponse(
+      "VALIDATION",
+      "direction must be 'out', 'in', or 'both'",
+      400
+    );
+  }
+
+  if (body.edgeType !== undefined && typeof body.edgeType !== "string") {
+    return errorResponse("VALIDATION", "edgeType must be a string", 400);
+  }
+  if (body.relation !== undefined && typeof body.relation !== "string") {
+    return errorResponse("VALIDATION", "relation must be a string", 400);
+  }
+  const edgeTypeValue = body.edgeType?.trim();
+  const relationValue = body.relation?.trim();
+  const edgeType = edgeTypeValue || relationValue || undefined;
+  if (
+    (body.edgeType !== undefined || body.relation !== undefined) &&
+    !edgeType
+  ) {
+    return errorResponse(
+      "VALIDATION",
+      "edgeType/relation cannot be empty",
+      400
+    );
+  }
+  if (edgeTypeValue && relationValue && edgeTypeValue !== relationValue) {
+    return errorResponse(
+      "VALIDATION",
+      "edgeType and relation are aliases and must match when both are provided",
+      400
+    );
+  }
+
+  const maxDepthResult = parseBodyPositiveInt(
+    "maxDepth",
+    body.maxDepth ?? body.depth,
+    2,
+    1,
+    6
+  );
+  if (!maxDepthResult.ok) {
+    return errorResponse("VALIDATION", maxDepthResult.message, 400);
+  }
+  const maxNodesResult = parseBodyPositiveInt(
+    "maxNodes",
+    body.maxNodes,
+    100,
+    1,
+    1000
+  );
+  if (!maxNodesResult.ok) {
+    return errorResponse("VALIDATION", maxNodesResult.message, 400);
+  }
+  const frontierLimitResult = parseBodyPositiveInt(
+    "frontierLimit",
+    body.frontierLimit,
+    100,
+    1,
+    1000
+  );
+  if (!frontierLimitResult.ok) {
+    return errorResponse("VALIDATION", frontierLimitResult.message, 400);
+  }
+  const visitedLimitResult = parseBodyPositiveInt(
+    "visitedLimit",
+    body.visitedLimit,
+    500,
+    1,
+    5000
+  );
+  if (!visitedLimitResult.ok) {
+    return errorResponse("VALIDATION", visitedLimitResult.message, 400);
+  }
+
+  const result = await diagnoseGraphQuery(store, rootRef, {
+    direction,
+    edgeType,
+    maxDepth: maxDepthResult.value,
+    maxNodes: maxNodesResult.value,
+    frontierLimit: frontierLimitResult.value,
+    visitedLimit: visitedLimitResult.value,
+    contentTypeRules: normalizeContentTypes(config.contentTypes ?? []).rules,
+  });
+  if (!result.success) {
+    return errorResponse(
+      result.isValidation ? "VALIDATION" : "RUNTIME",
+      result.error,
+      result.isValidation ? 400 : 500
+    );
+  }
+
+  return jsonResponse(result.data satisfies GraphQueryResponse);
+}

package/src/serve/server.ts

@@ -46,6 +46,7 @@ import {
   handlePublishExport,
   handlePresets,
   handleQuery,
+  handleQueryDiagnose,
   handleRefactorPlan,
   handleRenameDoc,
   handleRevealDoc,
@@ -58,7 +59,7 @@ import {
   handleUpdateCollection,
   handleUpdateDoc,
 } from "./routes/api";
-import { handleGraph } from "./routes/graph";
+import { handleGraph, handleGraphQuery } from "./routes/graph";
 import {
   handleDocBacklinks,
   handleDocLinks,
@@ -489,6 +490,17 @@ export async function startServer(
             );
           },
         },
+        "/api/query/diagnose": {
+          POST: async (req: Request) => {
+            if (!isRequestAllowed(req, port)) {
+              return withSecurityHeaders(forbiddenResponse(), isDev);
+            }
+            return withSecurityHeaders(
+              await handleQueryDiagnose(ctxHolder.current, req),
+              isDev
+            );
+          },
+        },
         "/api/ask": {
           POST: async (req: Request) => {
             if (!isRequestAllowed(req, port)) {
@@ -653,6 +665,17 @@ export async function startServer(
             return withSecurityHeaders(await handleGraph(store, url), isDev);
           },
         },
+        "/api/graph/query": {
+          POST: async (req: Request) => {
+            if (!isRequestAllowed(req, port)) {
+              return withSecurityHeaders(forbiddenResponse(), isDev);
+            }
+            return withSecurityHeaders(
+              await handleGraphQuery(store, ctxHolder.config, req),
+              isDev
+            );
+          },
+        },
       },
     });
   } catch (e) {

package/src/serve/watch-service.ts

@@ -2,7 +2,7 @@ import { watch, type FSWatcher } from "node:fs";
 import { join, normalize, sep } from "node:path";
 
 import type { Collection } from "../config/types";
-import type { CollectionSyncResult } from "../ingestion";
+import type { CollectionSyncResult, SyncOptions } from "../ingestion";
 import type { SqliteAdapter } from "../store/sqlite/adapter";
 import type { DocumentEvent, DocumentEventBus } from "./doc-events";
 import type { EmbedScheduler } from "./embed-scheduler";
@@ -39,6 +39,7 @@ interface CollectionWatchServiceOptions {
   scheduler: EmbedScheduler | null;
   eventBus?: DocumentEventBus | null;
   callbacks?: CollectionWatchCallbacks;
+  syncOptions?: SyncOptions;
   watchFactory?: typeof watch;
 }
 
@@ -48,6 +49,7 @@ export class CollectionWatchService {
   readonly #scheduler: EmbedScheduler | null;
   readonly #eventBus: DocumentEventBus | null;
   readonly #callbacks: CollectionWatchCallbacks | null;
+  #syncOptions: SyncOptions;
   readonly #watchers = new Map<string, FSWatcher>();
   readonly #pendingByCollection = new Map<string, Set<string>>();
   readonly #timers = new Map<string, ReturnType<typeof setTimeout>>();
@@ -64,6 +66,7 @@ export class CollectionWatchService {
     this.#scheduler = options.scheduler;
     this.#eventBus = options.eventBus ?? null;
     this.#callbacks = options.callbacks ?? null;
+    this.#syncOptions = options.syncOptions ?? {};
     this.#watchFactory = options.watchFactory ?? watch;
   }
 
@@ -71,8 +74,14 @@ export class CollectionWatchService {
     this.updateCollections(this.#collections);
   }
 
-  updateCollections(collections: Collection[]): void {
+  updateCollections(
+    collections: Collection[],
+    syncOptions?: SyncOptions
+  ): void {
     this.#collections = collections;
+    if (syncOptions) {
+      this.#syncOptions = syncOptions;
+    }
     const nextNames = new Set(collections.map((collection) => collection.name));
 
     for (const [collectionName, watcher] of this.#watchers) {
@@ -204,6 +213,7 @@ export class CollectionWatchService {
         collection,
         this.#store,
         {
+          ...this.#syncOptions,
           runUpdateCmd: false,
         }
       );

package/src/store/migrations/009-content-type-rule-fingerprint.ts

@@ -0,0 +1,36 @@
+/**
+ * Migration: content type rule fingerprint.
+ *
+ * @module src/store/migrations/009-content-type-rule-fingerprint
+ */
+
+import type { Migration } from "./runner";
+
+export const migration: Migration = {
+  version: 9,
+  name: "content_type_rule_fingerprint",
+
+  up(db): void {
+    const columns = new Set(
+      db
+        .query<{ name: string }, []>("PRAGMA table_info(documents)")
+        .all()
+        .map((row) => row.name)
+    );
+    if (!columns.has("content_type_rules_fingerprint")) {
+      db.exec(
+        "ALTER TABLE documents ADD COLUMN content_type_rules_fingerprint TEXT"
+      );
+    }
+    db.exec(
+      "CREATE INDEX IF NOT EXISTS idx_documents_content_type_rules_fingerprint ON documents(content_type_rules_fingerprint)"
+    );
+  },
+
+  down(db): void {
+    db.exec(
+      "DROP INDEX IF EXISTS idx_documents_content_type_rules_fingerprint"
+    );
+    // SQLite cannot drop columns without a table rebuild; keep column on rollback.
+  },
+};