@gmickel/gno 1.9.0 → 1.10.1

package/src/cli/commands/links.ts

@@ -7,10 +7,15 @@
 
 import { basename } from "node:path";
 
-import type { DocLinkRow, DocumentRow, StorePort } from "../../store/types";
+import type {
+  DocEdgeRow,
+  DocLinkRow,
+  DocumentRow,
+  StorePort,
+} from "../../store/types";
 
 import { normalizeWikiName } from "../../core/links";
-import { parseRef } from "./ref-parser";
+import { resolveDocRef } from "../../core/ref-parser";
 import { initStore } from "./shared";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -22,6 +27,10 @@ export interface LinksListOptions {
   configPath?: string;
   /** Filter by link type */
   type?: "wiki" | "markdown";
+  /** Filter semantic edges by relationship type */
+  edgeType?: string;
+  /** Alias for edgeType */
+  relation?: string;
   /** JSON output */
   json?: boolean;
   /** Markdown output */
@@ -44,8 +53,18 @@ export interface LinkWithResolution {
   resolvedUri?: string;
 }
 
+export interface SemanticLinkItem {
+  targetDocid: string;
+  targetUri: string;
+  targetTitle?: string;
+  edgeType: string;
+  relationType: string;
+  confidence: DocEdgeRow["confidence"];
+  edgeSource: DocEdgeRow["edgeSource"];
+}
+
 export interface LinksListResponse {
-  links: LinkWithResolution[];
+  links: Array<LinkWithResolution | SemanticLinkItem>;
   meta: {
     docid: string;
     uri: string;
@@ -53,6 +72,9 @@ export interface LinksListResponse {
     totalLinks: number;
     resolvedCount: number;
     typeFilter?: "wiki" | "markdown";
+    edgeTypeFilter?: string;
+    relationFilter?: string;
+    semantic: boolean;
   };
 }
 
@@ -60,6 +82,56 @@ export type LinksListResult =
   | { success: true; data: LinksListResponse }
   | { success: false; error: string; isValidation?: boolean };
 
+function resolveSemanticEdgeFilter(options: {
+  edgeType?: string;
+  relation?: string;
+}): string | undefined {
+  if (
+    options.edgeType &&
+    options.relation &&
+    options.edgeType !== options.relation
+  ) {
+    return undefined;
+  }
+  return options.edgeType ?? options.relation;
+}
+
+function mapEdgeToLinkOutput(edge: DocEdgeRow): SemanticLinkItem {
+  return {
+    targetDocid: edge.targetDocid,
+    targetUri: edge.targetUri,
+    ...(edge.targetTitle && { targetTitle: edge.targetTitle }),
+    edgeType: edge.edgeType,
+    relationType: edge.relationType,
+    confidence: edge.confidence,
+    edgeSource: edge.edgeSource,
+  };
+}
+
+function mapEdgeToBacklinkOutput(edge: DocEdgeRow): SemanticBacklinkItem {
+  return {
+    sourceDocid: edge.sourceDocid,
+    sourceUri: edge.sourceUri,
+    ...(edge.sourceTitle && { sourceTitle: edge.sourceTitle }),
+    edgeType: edge.edgeType,
+    relationType: edge.relationType,
+    confidence: edge.confidence,
+    edgeSource: edge.edgeSource,
+  };
+}
+
+function isSemanticLink(
+  link: LinkWithResolution | SemanticLinkItem
+): link is SemanticLinkItem {
+  return "edgeType" in link;
+}
+
+function isSemanticBacklink(
+  backlink: BacklinkItem | SemanticBacklinkItem
+): backlink is SemanticBacklinkItem {
+  return "edgeType" in backlink;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Types - Backlinks
 // ─────────────────────────────────────────────────────────────────────────────
@@ -69,6 +141,10 @@ export interface BacklinksOptions {
   configPath?: string;
   /** Filter by collection */
   collection?: string;
+  /** Filter semantic edges by relationship type */
+  edgeType?: string;
+  /** Alias for edgeType */
+  relation?: string;
   /** JSON output */
   json?: boolean;
   /** Markdown output */
@@ -84,14 +160,27 @@ export interface BacklinkItem {
   startCol: number;
 }
 
+export interface SemanticBacklinkItem {
+  sourceDocid: string;
+  sourceUri: string;
+  sourceTitle?: string;
+  edgeType: string;
+  relationType: string;
+  confidence: DocEdgeRow["confidence"];
+  edgeSource: DocEdgeRow["edgeSource"];
+}
+
 export interface BacklinksResponse {
-  backlinks: BacklinkItem[];
+  backlinks: Array<BacklinkItem | SemanticBacklinkItem>;
   meta: {
     docid: string;
     uri: string;
     title?: string;
     totalBacklinks: number;
     collection?: string;
+    edgeTypeFilter?: string;
+    relationFilter?: string;
+    semantic: boolean;
   };
 }
 
@@ -144,56 +233,6 @@ export type SimilarResult =
   | { success: true; data: SimilarResponse }
   | { success: false; error: string; isValidation?: boolean };
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Helper: Resolve document reference (supports all ref formats)
-// ─────────────────────────────────────────────────────────────────────────────
-
-async function resolveDocRef(
-  store: StorePort,
-  docRef: string
-): Promise<{ doc: DocumentRow } | { error: string; isValidation: boolean }> {
-  // Parse the ref to determine type
-  const parsed = parseRef(docRef);
-
-  if ("error" in parsed) {
-    return { error: parsed.error, isValidation: true };
-  }
-
-  let doc: DocumentRow | null = null;
-
-  switch (parsed.type) {
-    case "docid": {
-      const result = await store.getDocumentByDocid(parsed.value);
-      if (result.ok && result.value) {
-        doc = result.value;
-      }
-      break;
-    }
-    case "uri": {
-      const result = await store.getDocumentByUri(parsed.value);
-      if (result.ok && result.value) {
-        doc = result.value;
-      }
-      break;
-    }
-    case "collPath": {
-      // Build URI from collection/path
-      const uri = `gno://${parsed.collection}/${parsed.relPath}`;
-      const result = await store.getDocumentByUri(uri);
-      if (result.ok && result.value) {
-        doc = result.value;
-      }
-      break;
-    }
-  }
-
-  if (!doc) {
-    return { error: `Document not found: ${docRef}`, isValidation: true };
-  }
-
-  return { doc };
-}
-
 // ─────────────────────────────────────────────────────────────────────────────
 // Helper: Build resolution indexes (cached per collection)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -315,6 +354,26 @@ export async function linksList(
   docRef: string,
   options: LinksListOptions = {}
 ): Promise<LinksListResult> {
+  if (options.type && (options.edgeType || options.relation)) {
+    return {
+      success: false,
+      error: "--type cannot be combined with --edge-type or --relation",
+      isValidation: true,
+    };
+  }
+  if (
+    options.edgeType &&
+    options.relation &&
+    options.edgeType !== options.relation
+  ) {
+    return {
+      success: false,
+      error:
+        "--edge-type and --relation are aliases and must match when both are provided",
+      isValidation: true,
+    };
+  }
+
   const initResult = await initStore({
     configPath: options.configPath,
     syncConfig: false,
@@ -336,6 +395,35 @@ export async function linksList(
     }
     const { doc } = resolved;
 
+    const semanticEdgeType = resolveSemanticEdgeFilter(options);
+    if (semanticEdgeType) {
+      const edgesResult = await store.getEdgesForDoc(doc.id, {
+        edgeType: semanticEdgeType,
+      });
+      if (!edgesResult.ok) {
+        return { success: false, error: edgesResult.error.message };
+      }
+
+      const linksWithResolution = edgesResult.value.map(mapEdgeToLinkOutput);
+
+      return {
+        success: true,
+        data: {
+          links: linksWithResolution,
+          meta: {
+            docid: doc.docid,
+            uri: doc.uri,
+            ...(doc.title && { title: doc.title }),
+            totalLinks: linksWithResolution.length,
+            resolvedCount: linksWithResolution.length,
+            ...(options.edgeType && { edgeTypeFilter: options.edgeType }),
+            ...(options.relation && { relationFilter: options.relation }),
+            semantic: true,
+          },
+        },
+      };
+    }
+
     // Get links
     const linksResult = await store.getLinksForDoc(doc.id);
     if (!linksResult.ok) {
@@ -411,6 +499,7 @@ export async function linksList(
           totalLinks: linksWithResolution.length,
           resolvedCount,
           ...(options.type && { typeFilter: options.type }),
+          semantic: false,
         },
       },
     };
@@ -431,6 +520,19 @@ export async function backlinks(
   docRef: string,
   options: BacklinksOptions = {}
 ): Promise<BacklinksResult> {
+  if (
+    options.edgeType &&
+    options.relation &&
+    options.edgeType !== options.relation
+  ) {
+    return {
+      success: false,
+      error:
+        "--edge-type and --relation are aliases and must match when both are provided",
+      isValidation: true,
+    };
+  }
+
   const initResult = await initStore({
     configPath: options.configPath,
     syncConfig: false,
@@ -452,6 +554,36 @@ export async function backlinks(
     }
     const { doc } = resolved;
 
+    const semanticEdgeType = resolveSemanticEdgeFilter(options);
+    if (semanticEdgeType) {
+      const edgesResult = await store.getEdgeBacklinksForDoc(doc.id, {
+        collection: options.collection,
+        edgeType: semanticEdgeType,
+      });
+      if (!edgesResult.ok) {
+        return { success: false, error: edgesResult.error.message };
+      }
+
+      const backlinkItems = edgesResult.value.map(mapEdgeToBacklinkOutput);
+
+      return {
+        success: true,
+        data: {
+          backlinks: backlinkItems,
+          meta: {
+            docid: doc.docid,
+            uri: doc.uri,
+            ...(doc.title && { title: doc.title }),
+            totalBacklinks: backlinkItems.length,
+            ...(options.collection && { collection: options.collection }),
+            ...(options.edgeType && { edgeTypeFilter: options.edgeType }),
+            ...(options.relation && { relationFilter: options.relation }),
+            semantic: true,
+          },
+        },
+      };
+    }
+
     // Get backlinks
     const backlinksResult = await store.getBacklinksForDoc(doc.id, {
       collection: options.collection,
@@ -489,6 +621,7 @@ export async function backlinks(
           ...(doc.title && { title: doc.title }),
           totalBacklinks: backlinkItems.length,
           ...(options.collection && { collection: options.collection }),
+          semantic: false,
         },
       },
     };
@@ -746,6 +879,24 @@ export function formatLinksList(
     if (data.links.length === 0) {
       return `# Links from ${data.meta.docid}\n\nNo outgoing links found.`;
     }
+    if (data.meta.semantic) {
+      const lines: string[] = [
+        `# Links from ${escapeTableCell(data.meta.title ?? data.meta.docid)}`,
+        "",
+        `*${data.meta.totalLinks} semantic links*`,
+        "",
+        "| Target | Relation | Confidence | Source |",
+        "|--------|----------|------------|--------|",
+      ];
+      for (const l of data.links) {
+        if (!isSemanticLink(l)) continue;
+        const target = escapeTableCell(l.targetTitle ?? l.targetDocid);
+        lines.push(
+          `| ${target} | ${l.edgeType} | ${l.confidence} | ${l.edgeSource} |`
+        );
+      }
+      return lines.join("\n");
+    }
     const lines: string[] = [
       `# Links from ${escapeTableCell(data.meta.title ?? data.meta.docid)}`,
       "",
@@ -755,6 +906,7 @@ export function formatLinksList(
       "|-----------|------|------|------|----------|",
     ];
     for (const l of data.links) {
+      if (isSemanticLink(l)) continue;
       const targetRef = escapeTableCell(l.targetRef);
       const text = l.linkText ? escapeTableCell(l.linkText) : "-";
       const resolved = l.resolved ? `\`${l.resolvedDocid}\`` : "-";
@@ -772,6 +924,11 @@ export function formatLinksList(
 
   const lines: string[] = [];
   for (const l of data.links) {
+    if (isSemanticLink(l)) {
+      const target = l.targetTitle ?? l.targetDocid;
+      lines.push(`${l.edgeType}\t${target}\t${l.confidence}\t${l.edgeSource}`);
+      continue;
+    }
     const target = l.targetRef;
     const status = l.resolved ? `-> ${l.resolvedDocid}` : "(unresolved)";
     lines.push(
@@ -811,6 +968,24 @@ export function formatBacklinks(
     if (data.backlinks.length === 0) {
       return `# Backlinks to ${data.meta.docid}\n\nNo backlinks found.`;
     }
+    if (data.meta.semantic) {
+      const lines: string[] = [
+        `# Backlinks to ${escapeTableCell(data.meta.title ?? data.meta.docid)}`,
+        "",
+        `*${data.meta.totalBacklinks} semantic backlinks*`,
+        "",
+        "| Source | Relation | Confidence | Edge Source |",
+        "|--------|----------|------------|-------------|",
+      ];
+      for (const bl of data.backlinks) {
+        if (!isSemanticBacklink(bl)) continue;
+        const source = escapeTableCell(bl.sourceTitle ?? bl.sourceDocid);
+        lines.push(
+          `| ${source} | ${bl.edgeType} | ${bl.confidence} | ${bl.edgeSource} |`
+        );
+      }
+      return lines.join("\n");
+    }
     const lines: string[] = [
       `# Backlinks to ${escapeTableCell(data.meta.title ?? data.meta.docid)}`,
       "",
@@ -820,6 +995,7 @@ export function formatBacklinks(
       "|--------|------|-----------|",
     ];
     for (const bl of data.backlinks) {
+      if (isSemanticBacklink(bl)) continue;
       const source = escapeTableCell(bl.sourceTitle ?? bl.sourceDocid);
       const text = bl.linkText ? escapeTableCell(bl.linkText) : "-";
       lines.push(`| ${source} | ${bl.startLine} | ${text} |`);
@@ -834,6 +1010,13 @@ export function formatBacklinks(
 
   const lines: string[] = [];
   for (const bl of data.backlinks) {
+    if (isSemanticBacklink(bl)) {
+      const source = bl.sourceTitle ?? bl.sourceDocid;
+      lines.push(
+        `${source}\t${bl.edgeType}\t${bl.confidence}\t${bl.edgeSource}`
+      );
+      continue;
+    }
     const source = bl.sourceTitle ?? bl.sourceDocid;
     const text = bl.linkText ? `"${bl.linkText}"` : "";
     lines.push(`${source}\t${bl.startLine}:${bl.startCol}\t${text}`);

package/src/cli/commands/query.ts

@@ -12,9 +12,17 @@ import type {
 } from "../../llm/types";
 import type { HybridSearchOptions, SearchResults } from "../../pipeline/types";
 
+import {
+  fingerprintContentTypeRules,
+  normalizeContentTypes,
+} from "../../config";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../../llm/policy";
 import { resolveModelUri } from "../../llm/registry";
+import {
+  diagnoseQueryTarget,
+  type QueryDiagnoseResult as PipelineQueryDiagnoseResult,
+} from "../../pipeline/diagnose";
 import { type HybridSearchDeps, searchHybrid } from "../../pipeline/hybrid";
 import {
   createVectorIndexPort,
@@ -67,6 +75,25 @@ export type QueryResult =
   | { success: true; data: SearchResults }
   | { success: false; error: string };
 
+export type QueryDiagnoseCommandOptions = HybridSearchOptions & {
+  target: string;
+  configPath?: string;
+  indexName?: string;
+  embedModel?: string;
+  expandModel?: string;
+  genModel?: string;
+  rerankModel?: string;
+  json?: boolean;
+};
+
+export interface QueryDiagnoseFormatOptions {
+  format: "terminal" | "json";
+}
+
+export type QueryDiagnoseResult =
+  | { success: true; data: PipelineQueryDiagnoseResult }
+  | { success: false; error: string };
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Command Implementation
 // ─────────────────────────────────────────────────────────────────────────────
@@ -229,6 +256,149 @@ export async function query(
   }
 }
 
+// oxlint-disable-next-line max-lines-per-function -- mirrors query setup for diagnose-specific shared core
+export async function queryDiagnose(
+  queryText: string,
+  options: QueryDiagnoseCommandOptions
+): Promise<QueryDiagnoseResult> {
+  const initResult = await initStore({
+    configPath: options.configPath,
+    indexName: options.indexName,
+    collection: options.collection,
+    syncConfig: false,
+  });
+
+  if (!initResult.ok) {
+    return { success: false, error: initResult.error };
+  }
+
+  const { store, config } = initResult;
+  let embedPort: EmbeddingPort | null = null;
+  let expandPort: GenerationPort | null = null;
+  let rerankPort: RerankPort | null = null;
+
+  try {
+    const globals = getGlobals();
+    const policy = resolveDownloadPolicy(process.env, {
+      offline: globals.offline,
+    });
+    const showProgress = !options.json && process.stderr.isTTY;
+    const downloadProgress = showProgress
+      ? createThrottledProgressRenderer(createProgressRenderer())
+      : undefined;
+    const shouldCreateEmbeddingPort =
+      !options.noExpand || !options.noRerank || Boolean(options.graph);
+    const shouldCreateAnyModel =
+      shouldCreateEmbeddingPort || !options.noExpand || !options.noRerank;
+    const llm = shouldCreateAnyModel ? new LlmAdapter(config) : null;
+
+    const embedUri = shouldCreateEmbeddingPort
+      ? resolveModelUri(config, "embed", options.embedModel, options.collection)
+      : null;
+    if (embedUri && llm) {
+      const embedResult = await llm.createEmbeddingPort(embedUri, {
+        policy,
+        onProgress: downloadProgress
+          ? (progress) => downloadProgress("embed", progress)
+          : undefined,
+      });
+      if (embedResult.ok) {
+        embedPort = embedResult.value;
+      }
+    }
+
+    if (llm && !options.noExpand && !options.queryModes?.length) {
+      const expandUri = resolveModelUri(
+        config,
+        "expand",
+        options.expandModel ?? options.genModel,
+        options.collection
+      );
+      const genResult = await llm.createExpansionPort(expandUri, {
+        policy,
+        onProgress: downloadProgress
+          ? (progress) => downloadProgress("expand", progress)
+          : undefined,
+      });
+      if (genResult.ok) {
+        expandPort = genResult.value;
+      }
+    }
+
+    if (llm && !options.noRerank) {
+      const rerankUri = resolveModelUri(
+        config,
+        "rerank",
+        options.rerankModel,
+        options.collection
+      );
+      const rerankResult = await llm.createRerankPort(rerankUri, {
+        policy,
+        onProgress: downloadProgress
+          ? (progress) => downloadProgress("rerank", progress)
+          : undefined,
+      });
+      if (rerankResult.ok) {
+        rerankPort = rerankResult.value;
+      }
+    }
+
+    if (showProgress && downloadProgress) {
+      process.stderr.write("\n");
+    }
+
+    let vectorIndex: VectorIndexPort | null = null;
+    if (embedPort && embedUri) {
+      const embedInitResult = await embedPort.init();
+      if (embedInitResult.ok) {
+        const dimensions = embedPort.dimensions();
+        const db = store.getRawDb();
+        const vectorResult = await createVectorIndexPort(db, {
+          model: embedUri,
+          dimensions,
+        });
+        if (vectorResult.ok) {
+          vectorIndex = vectorResult.value;
+        }
+      }
+    }
+
+    const contentTypeRules = normalizeContentTypes(
+      config.contentTypes ?? []
+    ).rules;
+    const deps: HybridSearchDeps = {
+      store,
+      config,
+      vectorIndex,
+      embedPort,
+      expandPort,
+      rerankPort,
+    };
+    const result = await diagnoseQueryTarget(deps, queryText, {
+      ...options,
+      contentTypeRules,
+      contentTypeRulesFingerprint:
+        fingerprintContentTypeRules(contentTypeRules),
+    });
+
+    if (!result.ok) {
+      return { success: false, error: result.error.message };
+    }
+    return { success: true, data: result.value };
+  } finally {
+    if (embedPort) {
+      await embedPort.dispose();
+    }
+    if (expandPort) {
+      await expandPort.dispose();
+    }
+    if (rerankPort) {
+      await rerankPort.dispose();
+    }
+    await store.close();
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Formatters
 // ─────────────────────────────────────────────────────────────────────────────
@@ -283,3 +453,45 @@ export function formatQuery(
     terminalLinks: options.terminalLinks,
   });
 }
+
+export function formatQueryDiagnose(
+  result: QueryDiagnoseResult,
+  options: QueryDiagnoseFormatOptions
+): string {
+  if (!result.success) {
+    return options.format === "json"
+      ? JSON.stringify({
+          error: { code: "QUERY_DIAGNOSE_FAILED", message: result.error },
+        })
+      : `Error: ${result.error}`;
+  }
+
+  if (options.format === "json") {
+    return JSON.stringify(result.data, null, 2);
+  }
+
+  const target = result.data.target;
+  const lines = [
+    `Target: ${target.uri ?? target.ref}`,
+    `Status: ${target.status}`,
+    `Mode: ${result.data.meta.mode}`,
+  ];
+  if (target.filterReasons.length > 0) {
+    lines.push(`Filters: ${target.filterReasons.join(", ")}`);
+  }
+  if (target.graphHints.length > 0) {
+    lines.push(`Graph hints: ${target.graphHints.join(", ")}`);
+  }
+  if (result.data.stages.length > 0) {
+    lines.push("", "Stages:");
+    for (const stage of result.data.stages) {
+      const rank = stage.rank === null ? "-" : `#${stage.rank}`;
+      const score = stage.score === null ? "-" : stage.score.toFixed(4);
+      const reason = stage.dropReason ? ` ${stage.dropReason}` : "";
+      lines.push(
+        `  ${stage.id}: ${stage.status} present=${stage.present} rank=${rank} score=${score}${reason}`
+      );
+    }
+  }
+  return lines.join("\n");
+}