@gmickel/gno 2.7.0 → 2.8.0

package/src/cli/commands/ask.ts

@@ -81,6 +81,36 @@ export type AskCommandResult =
     }
   | { success: false; error: string };
 
+/**
+ * Give every document URI `?index=` on a named index, like search and
+ * Capsule results: results, citations and the answer-context selection.
+ */
+export function decorateAskUris(
+  result: AskResult,
+  indexName: string | undefined
+): AskResult {
+  const decorate = <T extends { uri: string }>(item: T): T => ({
+    ...item,
+    uri: decorateUriForIndex(item.uri, indexName),
+  });
+  const answerContext = result.meta.answerContext;
+  return {
+    ...result,
+    results: result.results.map(decorate),
+    citations: result.citations?.map(decorate),
+    meta: answerContext
+      ? {
+          ...result.meta,
+          answerContext: {
+            ...answerContext,
+            selected: answerContext.selected.map(decorate),
+            dropped: answerContext.dropped.map(decorate),
+          },
+        }
+      : result.meta,
+  };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Command Implementation
 // ─────────────────────────────────────────────────────────────────────────────
@@ -435,20 +465,9 @@ export async function ask(
         return { success: false, error: finalized.error.message };
       }
     }
-    // URIs carry `?index=` like search and Capsule results on a named index.
     return {
       success: true,
-      data: {
-        ...askResult,
-        results: askResult.results.map((result) => ({
-          ...result,
-          uri: decorateUriForIndex(result.uri, globals.index),
-        })),
-        citations: askResult.citations?.map((citation) => ({
-          ...citation,
-          uri: decorateUriForIndex(citation.uri, globals.index),
-        })),
-      },
+      data: decorateAskUris(askResult, globals.index),
       metadata: traceSession?.metadata(),
     };
   } catch (cause) {

package/src/cli/commands/audit.ts

@@ -14,8 +14,11 @@ import type { WorkspaceAuditProgress } from "../../core/audit-workspace";
 import { getIndexDbPath } from "../../app/constants";
 import { loadConfig } from "../../config";
 import {
+  AUDIT_MAX_FINDINGS_RANGE_MESSAGE,
   auditExitCode,
   AUDIT_CATEGORIES,
+  parseAuditMaxFindingsInput,
+  resolveAuditMaxFindings,
   serializeAuditReportCanonical,
 } from "../../core/audit";
 import { runWorkspaceAudit } from "../../core/audit-workspace";
@@ -31,7 +34,8 @@ export interface AuditCommandOptions {
   collections?: string[];
   paths?: string[];
   tags?: string[];
-  maxFindings?: number;
+  /** Positive integer, `all`, or the raw CLI string for either. */
+  maxFindings?: number | string;
   maxAgeDays?: number;
   orphanRoots?: string[];
   orphanIgnorePrefixes?: string[];
@@ -80,11 +84,18 @@ export const audit = async (
       error: "category must be links, provenance, freshness, or all",
     };
   }
-  if (invalidPositiveInteger(options.maxFindings)) {
+  const maxFindings =
+    typeof options.maxFindings === "string"
+      ? parseAuditMaxFindingsInput(options.maxFindings)
+      : options.maxFindings;
+  if (
+    (options.maxFindings !== undefined && maxFindings === undefined) ||
+    !resolveAuditMaxFindings(maxFindings).ok
+  ) {
     return {
       success: false,
       invalid: true,
-      error: "maxFindings must be a positive integer",
+      error: AUDIT_MAX_FINDINGS_RANGE_MESSAGE,
     };
   }
   if (invalidPositiveInteger(options.maxAgeDays)) {
@@ -155,7 +166,7 @@ export const audit = async (
       collectionFilters: requestedCollections,
       pathFilters: options.paths,
       tagFilters: requestedTags,
-      maxFindings: options.maxFindings,
+      maxFindings,
       agePolicy:
         options.maxAgeDays === undefined
           ? undefined
@@ -188,6 +199,14 @@ export const formatAuditReport = (
     `Categories: ${report.scope.categories.join(", ")}`,
     `Rules: ${report.counts.rules.total} (${report.counts.rules.fail} failed, ${report.counts.rules.unavailable} unavailable, ${report.counts.rules.inconclusive} inconclusive)`,
     `Findings: ${report.counts.findings.total}${report.counts.findings.truncated ? ` (${report.counts.findings.returned} shown)` : ""}`,
+    ...(report.truncation.snapshotTruncated
+      ? [
+          "Snapshot: truncated; totals cover the bounded audit snapshot, not the whole index",
+        ]
+      : []),
+    ...(report.truncation.evidenceTruncated
+      ? ["Evidence: some finding evidence was shortened"]
+      : []),
     `Examined: ${report.counts.examined.documents} document/rule observations`,
     `Duration: ${report.durationMs}ms`,
   ];

package/src/cli/commands/collection/list.ts

@@ -5,6 +5,10 @@
 import type { Collection } from "../../../config";
 
 import { loadConfig } from "../../../config";
+import {
+  detectCollectionWorkspace,
+  formatLinkWorkspace,
+} from "../../../core/link-workspace";
 import { bold, cyan, dim } from "../../colors";
 import { CliError } from "../../errors";
 
@@ -23,7 +27,30 @@ interface ListOptions {
   md?: boolean;
 }
 
-function formatMarkdown(collections: Collection[]): string {
+type ListedCollection = Collection & {
+  /** Effective link workspace root (detected or configured). */
+  effectiveWorkspaceRoot?: string;
+  workspaceSource: ReturnType<typeof detectCollectionWorkspace>["source"];
+};
+
+/** Resolve each collection's effective link workspace from the filesystem. */
+const withLinkWorkspaces = (collections: Collection[]): ListedCollection[] =>
+  collections.map((collection) => {
+    const workspace = detectCollectionWorkspace(collection);
+    return {
+      ...collection,
+      ...(workspace.root ? { effectiveWorkspaceRoot: workspace.root } : {}),
+      workspaceSource: workspace.source,
+    };
+  });
+
+const linkWorkspaceLine = (collection: ListedCollection): string | null =>
+  formatLinkWorkspace({
+    workspaceRoot: collection.effectiveWorkspaceRoot,
+    workspaceSource: collection.workspaceSource,
+  });
+
+function formatMarkdown(collections: ListedCollection[]): string {
   const lines: string[] = ["# Collections", ""];
   if (collections.length === 0) {
     lines.push("No collections configured.");
@@ -43,12 +70,14 @@ function formatMarkdown(collections: Collection[]): string {
     if (coll.updateCmd) {
       lines.push(`- **Update Command:** \`${coll.updateCmd}\``);
     }
+    const workspace = linkWorkspaceLine(coll);
+    if (workspace) lines.push(`- **Link workspace:** ${workspace}`);
     lines.push("");
   }
   return lines.join("\n");
 }
 
-function formatTerminal(collections: Collection[]): string {
+function formatTerminal(collections: ListedCollection[]): string {
   if (collections.length === 0) {
     return dim("No collections configured.");
   }
@@ -78,6 +107,10 @@ function formatTerminal(collections: Collection[]): string {
     if (updateCmd) {
       lines.push(`    ${dim("Update:")}  ${updateCmd}`);
     }
+    const workspace = linkWorkspaceLine(coll);
+    if (workspace) {
+      lines.push(`    ${dim("Links:")}   workspace ${sanitize(workspace)}`);
+    }
     lines.push("");
   }
   return lines.join("\n");
@@ -96,13 +129,14 @@ export async function collectionList(options: ListOptions): Promise<void> {
   const config = result.value;
 
   // Format and output
+  const collections = withLinkWorkspaces(config.collections);
   let output: string;
   if (options.json) {
-    output = JSON.stringify(config.collections, null, 2);
+    output = JSON.stringify(collections, null, 2);
   } else if (options.md) {
-    output = formatMarkdown(config.collections);
+    output = formatMarkdown(collections);
   } else {
-    output = formatTerminal(config.collections);
+    output = formatTerminal(collections);
   }
 
   process.stdout.write(`${output}\n`);

package/src/cli/commands/embed.ts

@@ -818,7 +818,7 @@ function getActiveChunkCount(
         `
         SELECT COUNT(*) as count FROM content_chunks c
         WHERE EXISTS (
-          SELECT 1 FROM documents d
+          SELECT 1 FROM documents d INDEXED BY idx_documents_mirror_hash
           WHERE d.mirror_hash = c.mirror_hash AND d.active = 1${collectionClause}
         )
       `
@@ -851,7 +851,7 @@ function getActiveChunks(
           'force' as reason
         FROM content_chunks c
         WHERE EXISTS (
-          SELECT 1 FROM documents d
+          SELECT 1 FROM documents d INDEXED BY idx_documents_mirror_hash
           WHERE d.mirror_hash = c.mirror_hash AND d.active = 1${collectionClause}
         )
         AND (c.mirror_hash > ? OR (c.mirror_hash = ? AND c.seq > ?))
@@ -864,7 +864,7 @@ function getActiveChunks(
           'force' as reason
         FROM content_chunks c
         WHERE EXISTS (
-          SELECT 1 FROM documents d
+          SELECT 1 FROM documents d INDEXED BY idx_documents_mirror_hash
           WHERE d.mirror_hash = c.mirror_hash AND d.active = 1${collectionClause}
         )
         ORDER BY c.mirror_hash, c.seq

package/src/cli/commands/links.ts

@@ -5,8 +5,6 @@
  * @module src/cli/commands/links
  */
 
-import { basename } from "node:path";
-
 import type {
   DocEdgeRow,
   DocLinkRow,
@@ -14,7 +12,6 @@ import type {
   StorePort,
 } from "../../store/types";
 
-import { normalizeWikiName } from "../../core/links";
 import { resolveDocRef } from "../../core/ref-parser";
 import { initStore } from "./shared";
 
@@ -51,6 +48,8 @@ export interface LinkWithResolution {
   resolved: boolean;
   resolvedDocid?: string;
   resolvedUri?: string;
+  /** Collection of the resolved target (may differ from the source's). */
+  resolvedCollection?: string;
 }
 
 export interface SemanticLinkItem {
@@ -155,6 +154,8 @@ export interface BacklinkItem {
   sourceDocid: string;
   sourceUri: string;
   sourceTitle?: string;
+  /** Collection of the linking document. */
+  sourceCollection?: string;
   linkText?: string;
   startLine: number;
   startCol: number;
@@ -233,96 +234,13 @@ export type SimilarResult =
   | { success: true; data: SimilarResponse }
   | { success: false; error: string; isValidation?: boolean };
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Helper: Build resolution indexes (cached per collection)
-// ─────────────────────────────────────────────────────────────────────────────
-
-interface ResolutionIndexes {
-  // Map: normalized wiki name -> DocumentRow
-  wikiIndex: Map<string, DocumentRow>;
-  // Map: relPath -> DocumentRow
-  pathIndex: Map<string, DocumentRow>;
-}
-
-/** Normalize markdown link path for matching (strip ./, collapse ..) */
-function normalizeMarkdownPath(path: string): string {
-  // Strip leading ./
-  let normalized = path.replace(/^\.\//, "");
-  // Collapse simple parent refs (a/b/../c -> a/c)
-  while (normalized.includes("/../")) {
-    normalized = normalized.replace(/[^/]+\/\.\.\//, "");
-  }
-  return normalized;
-}
-
-async function buildResolutionIndexes(
-  store: StorePort,
-  collection: string,
-  cache: Map<string, ResolutionIndexes>
-): Promise<ResolutionIndexes> {
-  const cached = cache.get(collection);
-  if (cached) {
-    return cached;
-  }
-
-  const indexes: ResolutionIndexes = {
-    wikiIndex: new Map(),
-    pathIndex: new Map(),
-  };
-
-  const docsResult = await store.listDocuments(collection);
-  if (!docsResult.ok) {
-    // Collection may not exist or store error - return empty indexes
-    // Links to this collection will show as unresolved
-    cache.set(collection, indexes);
-    return indexes;
-  }
-
-  for (const d of docsResult.value) {
-    if (!d.active) continue;
-
-    // Index by relPath for markdown links (exact match)
-    indexes.pathIndex.set(d.relPath, d);
-
-    // Also index by normalized path (without ./) for common variants
-    const normalizedPath = normalizeMarkdownPath(d.relPath);
-    if (
-      normalizedPath !== d.relPath &&
-      !indexes.pathIndex.has(normalizedPath)
-    ) {
-      indexes.pathIndex.set(normalizedPath, d);
-    }
-
-    // Index by normalized title for wiki links
-    if (d.title) {
-      const wikiKey = normalizeWikiName(d.title);
-      indexes.wikiIndex.set(wikiKey, d);
-    }
-
-    // Also index by filename stem as fallback for wiki links
-    const stem = basename(d.relPath).replace(/\.[^.]+$/, "");
-    if (stem) {
-      const stemKey = normalizeWikiName(stem);
-      // Don't overwrite title match
-      if (!indexes.wikiIndex.has(stemKey)) {
-        indexes.wikiIndex.set(stemKey, d);
-      }
-    }
-  }
-
-  cache.set(collection, indexes);
-  return indexes;
-}
-
 // ─────────────────────────────────────────────────────────────────────────────
 // Helper: Map DocLinkRow to output format (avoids null leakage)
 // ─────────────────────────────────────────────────────────────────────────────
 
 function mapLinkToOutput(
   link: DocLinkRow,
-  resolved: boolean,
-  resolvedDocid?: string,
-  resolvedUri?: string
+  resolved: { docid: string; uri: string; collection?: string } | null
 ): LinkWithResolution {
   return {
     targetRef: link.targetRef,
@@ -336,9 +254,12 @@ function mapLinkToOutput(
     startCol: link.startCol,
     endLine: link.endLine,
     endCol: link.endCol,
-    resolved,
-    ...(resolvedDocid && { resolvedDocid }),
-    ...(resolvedUri && { resolvedUri }),
+    resolved: resolved !== null,
+    ...(resolved && {
+      resolvedDocid: resolved.docid,
+      resolvedUri: resolved.uri,
+      ...(resolved.collection && { resolvedCollection: resolved.collection }),
+    }),
   };
 }
 
@@ -443,48 +364,29 @@ export async function linksList(
       return a.startCol - b.startCol;
     });
 
-    // Build resolution indexes (cached per collection)
-    const indexCache = new Map<string, ResolutionIndexes>();
-    const linksWithResolution: LinkWithResolution[] = [];
-
-    for (const link of links) {
-      let resolvedDoc: DocumentRow | undefined;
-
-      // Determine target collection (explicit or same as source)
-      const targetCollection = link.targetCollection ?? doc.collection;
-
-      // Get or build index for target collection
-      const indexes = await buildResolutionIndexes(
-        store,
-        targetCollection,
-        indexCache
-      );
-
-      // Safe fallback for targetRefNorm
-      const targetNorm = link.targetRefNorm || link.targetRef;
-
-      if (link.linkType === "wiki") {
-        // Wiki links: match by normalized title or filename
-        const wikiKey = normalizeWikiName(targetNorm);
-        resolvedDoc = indexes.wikiIndex.get(wikiKey);
-      } else {
-        // Markdown links: match by relPath (try exact, then normalized)
-        resolvedDoc = indexes.pathIndex.get(targetNorm);
-        if (!resolvedDoc) {
-          const normalizedTarget = normalizeMarkdownPath(targetNorm);
-          resolvedDoc = indexes.pathIndex.get(normalizedTarget);
-        }
-      }
-
-      linksWithResolution.push(
-        mapLinkToOutput(
-          link,
-          !!resolvedDoc,
-          resolvedDoc?.docid,
-          resolvedDoc?.uri
-        )
-      );
+    // Resolve with the shared link resolver (workspace-aware for plain wiki
+    // links whose source sits in a link workspace).
+    const resolvedResult = await store.resolveLinks(
+      links.map((link) => ({
+        targetRefNorm: link.targetRefNorm || link.targetRef,
+        targetCollection: link.targetCollection ?? doc.collection,
+        linkType: link.linkType,
+        source: {
+          collection: doc.collection,
+          relPath: doc.relPath,
+          explicit: Boolean(link.targetCollection),
+        },
+      }))
+    );
+    if (!resolvedResult.ok) {
+      return { success: false, error: resolvedResult.error.message };
     }
+    const linksWithResolution: LinkWithResolution[] = links.map(
+      (link, index) => {
+        const resolved = resolvedResult.value[index] ?? null;
+        return mapLinkToOutput(link, resolved);
+      }
+    );
 
     const resolvedCount = linksWithResolution.filter((l) => l.resolved).length;
 
@@ -606,6 +508,7 @@ export async function backlinks(
       sourceDocid: bl.sourceDocid,
       sourceUri: bl.sourceDocUri,
       ...(bl.sourceDocTitle && { sourceTitle: bl.sourceDocTitle }),
+      ...(bl.sourceCollection && { sourceCollection: bl.sourceCollection }),
       ...(bl.linkText && { linkText: bl.linkText }),
       startLine: bl.startLine,
       startCol: bl.startCol,

package/src/cli/commands/ls.ts

@@ -7,6 +7,7 @@
 
 import type { DocumentRow, StorePort, StoreResult } from "../../store/types";
 
+import { decorateUriForIndex } from "../../app/constants";
 import { initStore } from "./shared";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -145,7 +146,11 @@ export async function ls(
     // Apply offset and limit
     const offset = options.offset ?? 0;
     const limit = options.limit ?? 20;
-    const paged = allActive.slice(offset, offset + limit);
+    // Sorted on canonical URIs; the output URIs carry `?index=` like search.
+    const paged = allActive.slice(offset, offset + limit).map((doc) => ({
+      ...doc,
+      uri: decorateUriForIndex(doc.uri, options.indexName),
+    }));
 
     return {
       success: true,

package/src/cli/commands/shared.ts

@@ -178,6 +178,13 @@ export function formatSyncResultLines(
       `Rechunked ${syncResult.rechunkedMirrors} cached mirrors. Run gno embed if embedding was skipped.`
     );
   }
+  if (syncResult.graphRebuild) {
+    lines.push(
+      syncResult.graphRebuild === "resolver-upgrade"
+        ? "Link graph rebuilt: link resolution was upgraded."
+        : "Link graph rebuilt: collection settings or link workspace membership changed."
+    );
+  }
 
   for (const c of syncResult.collections) {
     lines.push(`${c.collection}:`);

package/src/cli/commands/status.ts

@@ -21,6 +21,7 @@ import {
 import { isConnectorActivationComplete } from "../../core/activation-connector-health";
 import { buildActivationStatus } from "../../core/activation-status";
 import { formatChunkingStatus } from "../../core/chunking-status";
+import { formatLinkWorkspace } from "../../core/link-workspace";
 import {
   buildMemoryStatus,
   formatMemoryStatusLines,
@@ -140,6 +141,8 @@ function formatTerminal(
         `  ${c.name}: ${c.activeDocuments} docs, ${c.totalChunks} chunks` +
           (c.embeddedChunks > 0 ? `, ${c.embeddedChunks} embedded` : "")
       );
+      const workspace = formatLinkWorkspace(c);
+      if (workspace) lines.push(`    Link workspace: ${workspace}`);
     }
   }
 
@@ -395,6 +398,8 @@ export function formatStatus(
         collections: s.collections.map((c) => ({
           name: c.name,
           path: c.path,
+          ...(c.workspaceRoot ? { workspaceRoot: c.workspaceRoot } : {}),
+          workspaceSource: c.workspaceSource ?? "none",
           documentCount: c.activeDocuments,
           chunkCount: c.totalChunks,
           embeddedCount: c.embeddedChunks,

package/src/cli/program.ts

@@ -1694,7 +1694,10 @@ function wireOnboardingCommands(program: Command): void {
       collectRepeatableValue,
       []
     )
-    .option("--max-findings <count>", "maximum returned findings", Number)
+    .option(
+      "--max-findings <count>",
+      "maximum returned findings (1-100000, or all)"
+    )
     .option("--max-age-days <days>", "explicit age review signal", Number)
     .option(
       "--orphan-root <uri>",
@@ -1736,7 +1739,7 @@ function wireOnboardingCommands(program: Command): void {
             collections: cmdOpts.collection as string[],
             paths: cmdOpts.path as string[],
             tags: cmdOpts.tag as string[],
-            maxFindings: cmdOpts.maxFindings as number | undefined,
+            maxFindings: cmdOpts.maxFindings as string | undefined,
             maxAgeDays: cmdOpts.maxAgeDays as number | undefined,
             orphanRoots: cmdOpts.orphanRoot as string[],
             orphanIgnorePrefixes: cmdOpts.orphanIgnorePrefix as string[],
@@ -4749,6 +4752,12 @@ function wireKnowledgeDeltaCommands(program: Command): void {
   program
     .command("impact <doc>")
     .description("Find bounded inbound knowledge dependencies")
+    .option(
+      "-c, --collection <name>",
+      "only traverse these collections (repeatable; default all)",
+      collectRepeatableValue,
+      []
+    )
     .option("--max-depth <n>", "maximum dependency depth", "3")
     .option("--max-nodes <n>", "maximum returned nodes", "100")
     .option("--max-edges <n>", "maximum traversed evidence edges", "250")
@@ -4764,6 +4773,7 @@ function wireKnowledgeDeltaCommands(program: Command): void {
       const result = await impact(
         doc,
         {
+          collections: cmdOpts.collection as string[],
           maxDepth: parsePositiveInt("max-depth", cmdOpts.maxDepth),
           maxNodes: parsePositiveInt("max-nodes", cmdOpts.maxNodes),
           maxEdges: parsePositiveInt("max-edges", cmdOpts.maxEdges),

package/src/config/loader.ts

@@ -7,6 +7,10 @@
 
 import type { ZodError } from "zod";
 
+import {
+  validateWorkspaceRootSetting,
+  workspaceRootSettingMessage,
+} from "../core/link-workspace";
 import {
   normalizeConfigContentTypes,
   type ConfigWarning,
@@ -132,6 +136,18 @@ export async function loadConfigFromPath(
     };
   }
 
+  const workspaceIssues = validateCollectionWorkspaceRoots(result.data);
+  if (workspaceIssues.length > 0) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: `Config validation failed: ${workspaceIssues.map((issue) => issue.message).join("; ")}`,
+        issues: workspaceIssues,
+      },
+    };
+  }
+
   const normalized = normalizeConfigContentTypes(result.data);
   return {
     ok: true,
@@ -140,6 +156,33 @@ export async function loadConfigFromPath(
   };
 }
 
+/**
+ * Validate explicit `workspaceRoot` settings against the filesystem: each must
+ * be absolute, exist, and contain its collection root. Messages name the
+ * collection so the error is actionable.
+ */
+export function validateCollectionWorkspaceRoots(
+  config: Config
+): ZodError["issues"] {
+  const issues: ZodError["issues"] = [];
+  for (const [index, collection] of config.collections.entries()) {
+    if (typeof collection.workspaceRoot !== "string") continue;
+    const error = validateWorkspaceRootSetting(
+      collection.path,
+      collection.workspaceRoot
+    );
+    if (error) {
+      issues.push({
+        code: "custom",
+        message: workspaceRootSettingMessage(collection.name, error),
+        path: ["collections", index, "workspaceRoot"],
+        input: collection.workspaceRoot,
+      });
+    }
+  }
+  return issues;
+}
+
 /**
  * Load config, returning null if not found (convenience wrapper).
  * Throws on parse/validation errors.

package/src/config/types.ts

@@ -166,6 +166,14 @@ export const CollectionSchema = z.object({
    */
   sourceAvailability: SourceAvailabilitySchema.optional(),
 
+  /**
+   * Link workspace for plain wiki links. Omitted: auto-detect the nearest
+   * `.obsidian/` ancestor-or-self. An absolute path joins the collection to
+   * that workspace root (it must contain the collection root); `false` keeps
+   * the collection's links collection-scoped.
+   */
+  workspaceRoot: z.union([z.string().min(1), z.literal(false)]).optional(),
+
   /**
    * Declares the collection as a GNO-managed memory substrate: `remember`
    * writes fact files here and refuses every collection without the flag.