@gmickel/gno 1.9.0 → 1.10.0

package/src/cli/commands/ref-parser.ts

@@ -1,108 +1,13 @@
 /**
- * Reference parser for document refs.
- * Pure lexical parsing - NO store/config access.
+ * CLI compatibility re-export for document ref parsing.
  *
  * @module src/cli/commands/ref-parser
  */
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Types
-// ─────────────────────────────────────────────────────────────────────────────
-
-export type RefType = "docid" | "uri" | "collPath";
-
-export interface ParsedRef {
-  type: RefType;
-  /** Normalized ref (without :line suffix) */
-  value: string;
-  /** For collPath type */
-  collection?: string;
-  /** For collPath type */
-  relPath?: string;
-  /** Parsed :line suffix (1-indexed) */
-  line?: number;
-}
-
-export type ParseRefResult = ParsedRef | { error: string };
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Top-level regex patterns (perf: avoid recreating in functions)
-// ─────────────────────────────────────────────────────────────────────────────
-
-const DOCID_PATTERN = /^#[a-f0-9]{6,}$/;
-const LINE_SUFFIX_PATTERN = /:(\d+)$/;
-const GLOB_PATTERN = /[*?[\]]/;
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Parser Functions
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Parse a single ref string.
- * - Docid: starts with # (no :line suffix allowed)
- * - URI: starts with gno:// (optional :N suffix)
- * - Else: collection/path (optional :N suffix)
- */
-export function parseRef(ref: string): ParseRefResult {
-  // 1. DocID: starts with #, validate pattern
-  if (ref.startsWith("#")) {
-    if (ref.includes(":")) {
-      return { error: "Docid refs cannot have :line suffix" };
-    }
-    if (!DOCID_PATTERN.test(ref)) {
-      return { error: `Invalid docid format: ${ref}` };
-    }
-    return { type: "docid", value: ref };
-  }
-
-  // 2. Parse optional :line suffix for URI and collPath
-  let line: number | undefined;
-  let baseRef = ref;
-  const lineMatch = ref.match(LINE_SUFFIX_PATTERN);
-  if (lineMatch?.[1]) {
-    const parsed = Number.parseInt(lineMatch[1], 10);
-    if (!Number.isInteger(parsed) || parsed < 1) {
-      return { error: `Invalid line suffix (must be >= 1): ${ref}` };
-    }
-    line = parsed;
-    baseRef = ref.slice(0, -lineMatch[0].length);
-  }
-
-  // 3. URI: starts with gno://
-  if (baseRef.startsWith("gno://")) {
-    return { type: "uri", value: baseRef, line };
-  }
-
-  // 4. Collection/path: must contain /
-  const slashIdx = baseRef.indexOf("/");
-  if (slashIdx === -1) {
-    return { error: `Invalid ref format (missing /): ${ref}` };
-  }
-  const collection = baseRef.slice(0, slashIdx);
-  const relPath = baseRef.slice(slashIdx + 1);
-
-  return { type: "collPath", value: baseRef, collection, relPath, line };
-}
-
-/**
- * Split comma-separated refs. Does NOT expand globs.
- */
-export function splitRefs(refs: string[]): string[] {
-  const result: string[] = [];
-  for (const r of refs) {
-    for (const part of r.split(",")) {
-      const trimmed = part.trim();
-      if (trimmed) {
-        result.push(trimmed);
-      }
-    }
-  }
-  return result;
-}
-
-/**
- * Check if a ref contains glob characters.
- */
-export function isGlobPattern(ref: string): boolean {
-  return GLOB_PATTERN.test(ref);
-}
+export type { ParsedRef, ParseRefResult, RefType } from "../../core/ref-parser";
+export {
+  isGlobPattern,
+  parseRef,
+  resolveDocRef,
+  splitRefs,
+} from "../../core/ref-parser";

package/src/cli/options.ts

@@ -22,6 +22,7 @@ export const CMD = {
   search: "search",
   vsearch: "vsearch",
   query: "query",
+  queryDiagnose: "query.diagnose",
   bench: "bench",
   ask: "ask",
   get: "get",
@@ -38,6 +39,7 @@ export const CMD = {
   backlinks: "backlinks",
   similar: "similar",
   graph: "graph",
+  graphQuery: "graph.query",
   capture: "capture",
 } as const;
 
@@ -47,6 +49,7 @@ const FORMAT_SUPPORT: Record<CommandId, OutputFormat[]> = {
   [CMD.search]: ["terminal", "json", "files", "csv", "md", "xml"],
   [CMD.vsearch]: ["terminal", "json", "files", "csv", "md", "xml"],
   [CMD.query]: ["terminal", "json", "files", "csv", "md", "xml"],
+  [CMD.queryDiagnose]: ["terminal", "json"],
   [CMD.bench]: ["terminal", "json"],
   [CMD.ask]: ["terminal", "json", "md"],
   [CMD.get]: ["terminal", "json", "md"],
@@ -64,6 +67,7 @@ const FORMAT_SUPPORT: Record<CommandId, OutputFormat[]> = {
   [CMD.similar]: ["terminal", "json", "md"],
   // graph uses custom --dot/--mermaid flags (not OutputFormat) and writes via terminal output
   [CMD.graph]: ["json", "terminal"],
+  [CMD.graphQuery]: ["terminal", "json"],
   [CMD.capture]: ["terminal", "json"],
 };
 

package/src/cli/program.ts

@@ -508,7 +508,7 @@ function wireSearchCommands(program: Command): void {
 
   // query - Hybrid search with expansion and reranking
   program
-    .command("query <query>")
+    .command("query <query...>")
     .description("Hybrid search with expansion and reranking")
     .option("-n, --limit <num>", "max results")
     .option("--min-score <num>", "minimum score threshold")
@@ -542,6 +542,7 @@ function wireSearchCommands(program: Command): void {
     .option("--no-rerank", "disable reranking")
     .option("--graph", "enable graph neighbor expansion")
     .option("--no-graph", "compatibility no-op; graph is off by default")
+    .option("--target <doc>", "diagnose target document ref")
     .option(
       "--query-mode <mode:text>",
       "structured mode entry (repeatable): term:<text>, intent:<text>, or hyde:<text>",
@@ -555,10 +556,16 @@ function wireSearchCommands(program: Command): void {
     .option("--csv", "CSV output")
     .option("--xml", "XML output")
     .option("--files", "file paths only")
-    .action(async (queryText: string, cmdOpts: Record<string, unknown>) => {
+    .action(async (queryParts: string[], cmdOpts: Record<string, unknown>) => {
       const format = getFormat(cmdOpts);
-      assertFormatSupported(CMD.query, format);
+      const isDiagnose =
+        queryParts[0] === "diagnose" && Boolean(cmdOpts.target);
+      assertFormatSupported(isDiagnose ? CMD.queryDiagnose : CMD.query, format);
+      const diagnoseFormat = format === "json" ? "json" : "terminal";
       const globals = getGlobals();
+      let queryText = isDiagnose
+        ? queryParts.slice(1).join(" ")
+        : queryParts.join(" ");
 
       // Validate empty query
       if (!queryText.trim()) {
@@ -638,6 +645,44 @@ function wireSearchCommands(program: Command): void {
         candidateLimit,
       });
 
+      if (isDiagnose) {
+        const { queryDiagnose, formatQueryDiagnose } =
+          await import("./commands/query");
+        const result = await queryDiagnose(queryText, {
+          configPath: globals.config,
+          indexName: globals.index,
+          target: cmdOpts.target as string,
+          limit,
+          minScore,
+          collection: cmdOpts.collection as string | undefined,
+          lang: cmdOpts.lang as string | undefined,
+          since: cmdOpts.since as string | undefined,
+          until: cmdOpts.until as string | undefined,
+          categories,
+          author: cmdOpts.author as string | undefined,
+          intent: cmdOpts.intent as string | undefined,
+          exclude,
+          tagsAll,
+          tagsAny,
+          noExpand: depthPolicy.noExpand,
+          noRerank: depthPolicy.noRerank,
+          graph: Boolean(cmdOpts.graph),
+          noGraph: Boolean(cmdOpts.fast) || cmdOpts.graph === false,
+          candidateLimit: depthPolicy.candidateLimit,
+          queryModes,
+          json: diagnoseFormat === "json",
+        });
+
+        if (!result.success) {
+          throw new CliError("RUNTIME", result.error);
+        }
+        await writeOutput(
+          formatQueryDiagnose(result, { format: diagnoseFormat }),
+          diagnoseFormat
+        );
+        return;
+      }
+
       const { query, formatQuery } = await import("./commands/query");
       const result = await query(queryText, {
         configPath: globals.config,
@@ -2153,6 +2198,8 @@ function wireLinksCommands(program: Command): void {
     .command("list <doc>", { isDefault: true })
     .description("List outgoing links from a document")
     .option("--type <type>", "filter by link type (wiki, markdown)")
+    .option("--edge-type <type>", "filter by semantic edge type")
+    .option("--relation <type>", "alias for --edge-type")
     .option("--json", "JSON output")
     .option("--md", "Markdown output")
     .action(async (doc: string, cmdOpts: Record<string, unknown>) => {
@@ -2168,11 +2215,27 @@ function wireLinksCommands(program: Command): void {
           `Invalid link type: ${linkType}. Must be 'wiki' or 'markdown'.`
         );
       }
+      const edgeType = cmdOpts.edgeType as string | undefined;
+      const relation = cmdOpts.relation as string | undefined;
+      if (linkType && (edgeType || relation)) {
+        throw new CliError(
+          "VALIDATION",
+          "--type cannot be combined with --edge-type or --relation"
+        );
+      }
+      if (edgeType && relation && edgeType !== relation) {
+        throw new CliError(
+          "VALIDATION",
+          "--edge-type and --relation are aliases and must match when both are provided"
+        );
+      }
 
       const { linksList, formatLinksList } = await import("./commands/links");
       const result = await linksList(doc, {
         configPath: globals.config,
         type: linkType as "wiki" | "markdown" | undefined,
+        edgeType,
+        relation,
         json: format === "json",
         md: format === "md",
       });
@@ -2196,6 +2259,8 @@ function wireLinksCommands(program: Command): void {
     .command("backlinks <doc>")
     .description("List documents linking to this document")
     .option("-c, --collection <name>", "filter by collection")
+    .option("--edge-type <type>", "filter by semantic edge type")
+    .option("--relation <type>", "alias for --edge-type")
     .option("--json", "JSON output")
     .option("--md", "Markdown output")
     .action(async (doc: string, cmdOpts: Record<string, unknown>) => {
@@ -2204,9 +2269,19 @@ function wireLinksCommands(program: Command): void {
       const globals = getGlobals();
 
       const { backlinks, formatBacklinks } = await import("./commands/links");
+      const edgeType = cmdOpts.edgeType as string | undefined;
+      const relation = cmdOpts.relation as string | undefined;
+      if (edgeType && relation && edgeType !== relation) {
+        throw new CliError(
+          "VALIDATION",
+          "--edge-type and --relation are aliases and must match when both are provided"
+        );
+      }
       const result = await backlinks(doc, {
         configPath: globals.config,
         collection: cmdOpts.collection as string | undefined,
+        edgeType,
+        relation,
         json: format === "json",
         md: format === "md",
       });
@@ -2278,7 +2353,7 @@ function wireLinksCommands(program: Command): void {
 // ─────────────────────────────────────────────────────────────────────────────
 
 function wireGraphCommand(program: Command): void {
-  program
+  const graphCmd = program
     .command("graph")
     .description("Output knowledge graph of document links")
     .option("-c, --collection <name>", "filter by collection")
@@ -2289,7 +2364,7 @@ function wireGraphCommand(program: Command): void {
     .option("--include-isolated", "include nodes with no links")
     .option("--similar-top-k <n>", "similar docs per node (default 5)")
     .option("--neighbors <ref>", "show graph neighbors for document/node ref")
-    .option("--direction <dir>", "neighbor direction: both, out, in", "both")
+    .option("--direction <dir>", "neighbor direction: both, out, in")
     .option("--from <ref>", "path start document/node ref")
     .option("--to <ref>", "path target document/node ref")
     .option("--max-depth <n>", "max path hops (default 6)")
@@ -2332,10 +2407,11 @@ function wireGraphCommand(program: Command): void {
       const maxDepth = cmdOpts.maxDepth
         ? parsePositiveInt("max-depth", cmdOpts.maxDepth)
         : undefined;
+      const graphDirection = (cmdOpts.direction ?? "both") as string;
       if (
-        cmdOpts.direction !== "both" &&
-        cmdOpts.direction !== "out" &&
-        cmdOpts.direction !== "in"
+        graphDirection !== "both" &&
+        graphDirection !== "out" &&
+        graphDirection !== "in"
       ) {
         throw new CliError(
           "VALIDATION",
@@ -2352,6 +2428,7 @@ function wireGraphCommand(program: Command): void {
       const { graph, formatGraph } = await import("./commands/graph.js");
       const result = await graph({
         configPath: globals.config,
+        indexName: globals.index,
         collection: cmdOpts.collection as string | undefined,
         limitNodes,
         limitEdges,
@@ -2361,7 +2438,7 @@ function wireGraphCommand(program: Command): void {
         similarTopK,
         format,
         neighbors: cmdOpts.neighbors as string | undefined,
-        direction: cmdOpts.direction as "both" | "out" | "in",
+        direction: graphDirection as "both" | "out" | "in",
         from: cmdOpts.from as string | undefined,
         to: cmdOpts.to as string | undefined,
         maxDepth,
@@ -2385,6 +2462,96 @@ function wireGraphCommand(program: Command): void {
 
       await writeOutput(output, format === "json" ? "json" : "terminal");
     });
+
+  graphCmd
+    .command("query <doc>")
+    .description("Run bounded typed-edge traversal from a document")
+    .option("--direction <dir>", "direction: both, out, in")
+    .option("--edge-type <type>", "filter by typed edge type")
+    .option("--max-depth <n>", "max traversal depth (default 2)")
+    .option("--max-nodes <n>", "max returned nodes (default 100)")
+    .option(
+      "--frontier-limit <n>",
+      "max frontier width per depth (default 100)"
+    )
+    .option(
+      "--visited-limit <n>",
+      "max visited rows during traversal (default 500)"
+    )
+    .option("--json", "JSON output")
+    .action(
+      async (
+        doc: string,
+        cmdOpts: Record<string, unknown>,
+        command: Command
+      ) => {
+        const globals = getGlobals();
+        const format = getFormat(cmdOpts);
+        assertFormatSupported(CMD.graphQuery, format);
+        if (format !== "terminal" && format !== "json") {
+          throw new CliError(
+            "VALIDATION",
+            "gno graph query supports terminal and json output"
+          );
+        }
+        const argv = resolveCliArgv(command);
+        const directionFlagIndex = argv.lastIndexOf("--direction");
+        const rawDirection =
+          directionFlagIndex >= 0 ? argv[directionFlagIndex + 1] : undefined;
+        const direction = (rawDirection ??
+          cmdOpts.direction ??
+          "both") as string;
+        if (direction !== "both" && direction !== "out" && direction !== "in") {
+          throw new CliError(
+            "VALIDATION",
+            "--direction must be one of: both, out, in"
+          );
+        }
+
+        const maxDepth = cmdOpts.maxDepth
+          ? parsePositiveInt("max-depth", cmdOpts.maxDepth)
+          : undefined;
+        const maxNodes = cmdOpts.maxNodes
+          ? parsePositiveInt("max-nodes", cmdOpts.maxNodes)
+          : undefined;
+        const frontierLimit = cmdOpts.frontierLimit
+          ? parsePositiveInt("frontier-limit", cmdOpts.frontierLimit)
+          : undefined;
+        const visitedLimit = cmdOpts.visitedLimit
+          ? parsePositiveInt("visited-limit", cmdOpts.visitedLimit)
+          : undefined;
+
+        const { graphQuery, formatGraphQuery } =
+          await import("./commands/graph.js");
+        const result = await graphQuery(doc, {
+          configPath: globals.config,
+          indexName: globals.index,
+          direction: direction as "both" | "out" | "in",
+          edgeType: cmdOpts.edgeType as string | undefined,
+          maxDepth,
+          maxNodes,
+          frontierLimit,
+          visitedLimit,
+          format,
+        });
+
+        if (!result.success) {
+          throw new CliError(
+            result.isValidation ? "VALIDATION" : "RUNTIME",
+            result.error
+          );
+        }
+
+        const output = formatGraphQuery(result, { format });
+        if (result.data.meta.truncated) {
+          for (const warning of result.data.meta.warnings) {
+            console.error(`Warning: ${warning}`);
+          }
+        }
+
+        await writeOutput(output, format);
+      }
+    );
 }
 
 // ─────────────────────────────────────────────────────────────────────────────

package/src/config/content-types.ts

@@ -37,6 +37,13 @@ const NOTE_PRESET_IDS = new Set<NotePresetId>(
   NOTE_PRESETS.map((preset) => preset.id)
 );
 
+function normalizeGraphHint(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[-\s]+/g, "_");
+}
+
 function isNotePresetId(value: string): value is NotePresetId {
   return NOTE_PRESET_IDS.has(value as NotePresetId);
 }
@@ -79,6 +86,9 @@ export function normalizeContentTypes(
         ...contentType,
         preset: contentType.preset,
         prefixes,
+        graphHints: contentType.graphHints
+          ? contentType.graphHints.map(normalizeGraphHint).filter(Boolean)
+          : undefined,
       });
       continue;
     }
@@ -87,6 +97,9 @@ export function normalizeContentTypes(
       ...contentType,
       preset: contentType.preset,
       prefixes: [...prefixes].sort((a, b) => b.length - a.length),
+      graphHints: contentType.graphHints
+        ? contentType.graphHints.map(normalizeGraphHint).filter(Boolean)
+        : undefined,
     });
   }
 
@@ -119,6 +132,7 @@ export function fingerprintContentTypeRules(
     id: rule.id,
     preset: rule.preset,
     prefixes: rule.prefixes,
+    graphHints: rule.graphHints ?? [],
   }));
   const hasher = new Bun.CryptoHasher("sha256");
   hasher.update(JSON.stringify(canonical));

package/src/core/graph-query.ts

@@ -0,0 +1,137 @@
+/**
+ * Shared bounded typed-edge graph traversal.
+ *
+ * @module src/core/graph-query
+ */
+
+import type { NormalizedContentTypeRule } from "../config";
+import type {
+  DocumentRow,
+  GraphQueryNode,
+  GraphQueryOptions,
+  GraphQueryResult,
+  StorePort,
+} from "../store/types";
+
+import { resolveDocRef } from "./ref-parser";
+
+export type DiagnoseGraphQueryResult =
+  | { success: true; data: GraphQueryResult }
+  | { success: false; error: string; isValidation?: boolean };
+
+export interface DiagnoseGraphQueryOptions extends GraphQueryOptions {
+  contentTypeRules?: NormalizedContentTypeRule[];
+}
+
+function graphHintsForDoc(
+  doc: DocumentRow,
+  rules: NormalizedContentTypeRule[]
+): string[] {
+  if (!doc.contentType) {
+    return [];
+  }
+  return rules.find((rule) => rule.id === doc.contentType)?.graphHints ?? [];
+}
+
+function toNode(
+  doc: DocumentRow,
+  depth: number,
+  rules: NormalizedContentTypeRule[]
+): GraphQueryNode {
+  return {
+    id: doc.docid,
+    uri: doc.uri,
+    title: doc.title,
+    collection: doc.collection,
+    relPath: doc.relPath,
+    depth,
+    graphHints: graphHintsForDoc(doc, rules),
+  };
+}
+
+export async function diagnoseGraphQuery(
+  store: StorePort,
+  rootRef: string,
+  options: DiagnoseGraphQueryOptions = {}
+): Promise<DiagnoseGraphQueryResult> {
+  const resolved = await resolveDocRef(store, rootRef);
+  if ("error" in resolved) {
+    return {
+      success: false,
+      error: resolved.error,
+      isValidation: resolved.isValidation,
+    };
+  }
+
+  const rootDoc = resolved.doc;
+  if (!rootDoc.active) {
+    return {
+      success: false,
+      error: `Document is inactive: ${rootRef}`,
+      isValidation: true,
+    };
+  }
+
+  const direction = options.direction ?? "both";
+  const traversal = await store.queryGraphTraversal(rootDoc.id, {
+    direction,
+    edgeType: options.edgeType,
+    maxDepth: options.maxDepth,
+    maxNodes: options.maxNodes,
+    frontierLimit: options.frontierLimit,
+    visitedLimit: options.visitedLimit,
+  });
+  if (!traversal.ok) {
+    return { success: false, error: traversal.error.message };
+  }
+
+  const rules = options.contentTypeRules ?? [];
+  const nodes = traversal.value.nodes
+    .map(({ doc, depth }) => toNode(doc, depth, rules))
+    .sort((a, b) => a.depth - b.depth || a.uri.localeCompare(b.uri));
+  const root =
+    nodes.find((node) => node.id === rootDoc.docid) ??
+    toNode(rootDoc, 0, rules);
+  const edges = traversal.value.edges
+    .map(({ edge, depth }) => ({
+      source: edge.sourceDocid,
+      target: edge.targetDocid,
+      edgeType: edge.edgeType,
+      relationType: edge.relationType,
+      confidence: edge.confidence,
+      edgeSource: edge.edgeSource,
+      depth,
+    }))
+    .sort(
+      (a, b) =>
+        a.depth - b.depth ||
+        a.edgeType.localeCompare(b.edgeType) ||
+        a.source.localeCompare(b.source) ||
+        a.target.localeCompare(b.target)
+    );
+
+  return {
+    success: true,
+    data: {
+      schemaVersion: "1.0",
+      root,
+      nodes,
+      edges,
+      meta: {
+        direction,
+        edgeType: options.edgeType ?? null,
+        maxDepth: Math.max(1, Math.min(options.maxDepth ?? 2, 6)),
+        maxNodes: Math.max(1, Math.min(options.maxNodes ?? 100, 1_000)),
+        frontierLimit: Math.max(
+          1,
+          Math.min(options.frontierLimit ?? 100, 1_000)
+        ),
+        visitedLimit: Math.max(1, Math.min(options.visitedLimit ?? 500, 5_000)),
+        returnedNodes: nodes.length,
+        returnedEdges: edges.length,
+        truncated: traversal.value.truncated,
+        warnings: traversal.value.warnings,
+      },
+    },
+  };
+}