@gmickel/gno 1.8.0 → 1.10.0

package/src/config/index.ts

@@ -5,6 +5,16 @@
  */
 
 export { createDefaultConfig } from "./defaults";
+export {
+  type ConfigWarning,
+  fingerprintContentTypeRules,
+  formatConfigWarning,
+  formatConfigWarnings,
+  normalizeConfigContentTypes,
+  normalizeContentTypes,
+  type NormalizedContentTypeRule,
+  writeConfigWarningsToStderr,
+} from "./content-types";
 // Loading
 export {
   isInitialized,
@@ -40,6 +50,10 @@ export {
   CollectionSchema,
   type Config,
   ConfigSchema,
+  CONTENT_TYPE_GRAPH_HINTS,
+  type ContentTypeConfig,
+  type ContentTypeGraphHint,
+  ContentTypeSchema,
   type Context,
   ContextSchema,
   DEFAULT_EXCLUDES,

package/src/config/loader.ts

@@ -7,6 +7,10 @@
 
 import type { ZodError } from "zod";
 
+import {
+  normalizeConfigContentTypes,
+  type ConfigWarning,
+} from "./content-types";
 import { configExists, expandPath, getConfigPaths } from "./paths";
 import { CONFIG_VERSION, type Config, ConfigSchema } from "./types";
 
@@ -15,7 +19,7 @@ import { CONFIG_VERSION, type Config, ConfigSchema } from "./types";
 // ─────────────────────────────────────────────────────────────────────────────
 
 export type LoadResult<T> =
-  | { ok: true; value: T }
+  | { ok: true; value: T; warnings: ConfigWarning[] }
   | { ok: false; error: LoadError };
 
 export type LoadError =
@@ -128,7 +132,12 @@ export async function loadConfigFromPath(
     };
   }
 
-  return { ok: true, value: result.data };
+  const normalized = normalizeConfigContentTypes(result.data);
+  return {
+    ok: true,
+    value: normalized.config,
+    warnings: normalized.warnings,
+  };
 }
 
 /**

package/src/config/types.ts

@@ -245,6 +245,37 @@ export const ModelConfigSchema = z.object({
 
 export type ModelConfig = z.infer<typeof ModelConfigSchema>;
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Content Type Schema
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const CONTENT_TYPE_GRAPH_HINTS = [
+  "mentions",
+  "works_at",
+  "attended",
+  "decided",
+  "related_to",
+] as const;
+
+export type ContentTypeGraphHint = (typeof CONTENT_TYPE_GRAPH_HINTS)[number];
+
+export const ContentTypeSchema = z.object({
+  /** Stable content type identifier */
+  id: z.string().min(1),
+  /** Relative path prefixes that map to this content type */
+  prefixes: z.array(z.string().min(1)),
+  /** Note preset ID, resolved post-parse so unknown refs warn-and-drop */
+  preset: z.string().min(1),
+  /** Reserved for fn-84 typed graph hints; accepted but no-op in fn-83 */
+  graphHints: z.array(z.string().min(1)).optional(),
+  /** Reserved for future ranking; accepted but no-op in fn-83 */
+  searchBoost: z.number().finite().optional(),
+  /** Marks time-oriented content types; accepted but no-op in fn-83 */
+  temporal: z.boolean().optional(),
+});
+
+export type ContentTypeConfig = z.infer<typeof ContentTypeSchema>;
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Config Schema (root)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -265,11 +296,16 @@ export const ConfigSchema = z.object({
   /** Context metadata */
   contexts: z.array(ContextSchema).default([]),
 
+  /** Opt-in schema-lite content type rules */
+  contentTypes: z.array(ContentTypeSchema).default([]),
+
   /** Model configuration */
   models: ModelConfigSchema.optional(),
 });
 
-export type Config = z.infer<typeof ConfigSchema>;
+export type Config = Omit<z.infer<typeof ConfigSchema>, "contentTypes"> & {
+  contentTypes?: ContentTypeConfig[];
+};
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Scope Utilities

package/src/core/config-mutation.ts

@@ -7,7 +7,12 @@
 import type { Config } from "../config/types";
 import type { SqliteAdapter } from "../store/sqlite/adapter";
 
-import { loadConfig, saveConfig } from "../config";
+import {
+  formatConfigWarnings,
+  loadConfig,
+  normalizeConfigContentTypes,
+  saveConfig,
+} from "../config";
 
 export interface ConfigMutationContext {
   store: SqliteAdapter;
@@ -53,6 +58,9 @@ export async function applyConfigChange<T = void>(
         code: "LOAD_ERROR",
       };
     }
+    for (const warning of formatConfigWarnings(loadResult.warnings)) {
+      console.warn(warning);
+    }
 
     const mutationResult = await mutate(loadResult.value);
     if (!mutationResult.ok) {
@@ -63,7 +71,11 @@ export async function applyConfigChange<T = void>(
       };
     }
 
-    const newConfig = mutationResult.config;
+    const normalized = normalizeConfigContentTypes(mutationResult.config);
+    for (const warning of formatConfigWarnings(normalized.warnings)) {
+      console.warn(warning);
+    }
+    const newConfig = normalized.config;
     const saveResult = await saveConfig(newConfig, ctx.configPath);
     if (!saveResult.ok) {
       return {

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,
+      },
+    },
+  };
+}

package/src/core/graph-resolver.ts

@@ -0,0 +1,117 @@
+/**
+ * Shared SQL expressions for graph link target resolution.
+ *
+ * These helpers preserve getGraph's existing wiki matching order so future
+ * typed-edge projection/backfill can reuse the exact resolver.
+ *
+ * @module src/core/graph-resolver
+ */
+
+const suffixMatch = (targetExpr: string, valueExpr: string): string =>
+  `(substr(${targetExpr}, -length(${valueExpr})) = ${valueExpr}
+    AND (length(${targetExpr}) = length(${valueExpr})
+      OR substr(${targetExpr}, -length(${valueExpr}) - 1, 1) = '/'))`;
+
+const wikiTitleExpr = (alias: string): string => `lower(trim(${alias}.title))`;
+const wikiRelPathExpr = (alias: string): string => `lower(${alias}.rel_path)`;
+
+function wikiTargetExpressions(targetRefExpr: string): {
+  targetBaseExpr: string;
+  targetMdExpr: string;
+} {
+  const targetBaseExpr = `CASE
+    WHEN ${targetRefExpr} LIKE '%.md' THEN substr(${targetRefExpr}, 1, length(${targetRefExpr}) - 3)
+    ELSE ${targetRefExpr}
+  END`;
+  return { targetBaseExpr, targetMdExpr: `${targetBaseExpr} || '.md'` };
+}
+
+export function buildWikiMatchExpression(
+  alias: string,
+  targetRefExpr: string
+): string {
+  const titleExpr = wikiTitleExpr(alias);
+  const relExpr = wikiRelPathExpr(alias);
+  const { targetBaseExpr, targetMdExpr } = wikiTargetExpressions(targetRefExpr);
+  return `(
+    ${titleExpr} = ${targetBaseExpr}
+    OR ${titleExpr} = ${targetMdExpr}
+    OR ${suffixMatch(targetBaseExpr, titleExpr)}
+    OR ${suffixMatch(targetMdExpr, `${titleExpr} || '.md'`)}
+    OR ${relExpr} = ${targetBaseExpr}
+    OR ${relExpr} = ${targetMdExpr}
+    OR ${suffixMatch(relExpr, targetMdExpr)}
+    OR ${suffixMatch(relExpr, targetBaseExpr)}
+    OR ${suffixMatch(targetMdExpr, relExpr)}
+    OR ${suffixMatch(targetBaseExpr, relExpr)}
+  )`;
+}
+
+export function buildWikiOrderExpression(
+  alias: string,
+  targetRefExpr: string
+): string {
+  const titleExpr = wikiTitleExpr(alias);
+  const relExpr = wikiRelPathExpr(alias);
+  const { targetBaseExpr, targetMdExpr } = wikiTargetExpressions(targetRefExpr);
+  return `CASE
+    WHEN ${titleExpr} = ${targetBaseExpr} THEN 1
+    WHEN ${titleExpr} = ${targetMdExpr} THEN 2
+    WHEN ${suffixMatch(targetBaseExpr, titleExpr)} THEN 3
+    WHEN ${suffixMatch(targetMdExpr, `${titleExpr} || '.md'`)} THEN 4
+    WHEN ${relExpr} = ${targetBaseExpr} THEN 5
+    WHEN ${relExpr} = ${targetMdExpr} THEN 6
+    WHEN ${suffixMatch(relExpr, targetMdExpr)} THEN 7
+    WHEN ${suffixMatch(relExpr, targetBaseExpr)} THEN 8
+    WHEN ${suffixMatch(targetMdExpr, relExpr)} THEN 9
+    WHEN ${suffixMatch(targetBaseExpr, relExpr)} THEN 10
+    ELSE 11
+  END`;
+}
+
+export function buildWikiBestMatchSubquery(
+  collectionExpr: string,
+  targetRefExpr: string
+): string {
+  return `
+    SELECT t.id FROM documents t
+    WHERE t.active = 1
+      AND t.collection = ${collectionExpr}
+      AND ${buildWikiMatchExpression("t", targetRefExpr)}
+      AND ${buildWikiOrderExpression("t", targetRefExpr)} = (
+        SELECT MIN(${buildWikiOrderExpression("t2", targetRefExpr)}) FROM documents t2
+        WHERE t2.active = 1
+          AND t2.collection = ${collectionExpr}
+          AND ${buildWikiMatchExpression("t2", targetRefExpr)}
+      )
+    ORDER BY t.id LIMIT 1
+  `;
+}
+
+export function buildWikiBestRankSubquery(
+  collectionExpr: string,
+  targetRefExpr: string
+): string {
+  return `
+    SELECT MIN(${buildWikiOrderExpression("t", targetRefExpr)}) FROM documents t
+    WHERE t.active = 1
+      AND t.collection = ${collectionExpr}
+      AND ${buildWikiMatchExpression("t", targetRefExpr)}
+  `;
+}
+
+export function buildWikiBestRankMatchCountSubquery(
+  collectionExpr: string,
+  targetRefExpr: string
+): string {
+  return `
+    SELECT COUNT(*) FROM documents t
+    WHERE t.active = 1
+      AND t.collection = ${collectionExpr}
+      AND ${buildWikiMatchExpression("t", targetRefExpr)}
+      AND ${buildWikiOrderExpression("t", targetRefExpr)} = (${buildWikiBestRankSubquery(
+        collectionExpr,
+        targetRefExpr
+      )})
+  `;
+}

package/src/core/note-presets.ts

@@ -14,7 +14,11 @@ export type NotePresetId =
   | "research-note"
   | "decision-note"
   | "prompt-pattern"
-  | "source-summary";
+  | "source-summary"
+  | "idea-original"
+  | "person"
+  | "company-project"
+  | "meeting";
 
 export interface NotePresetDefinition {
   id: NotePresetId;
@@ -104,14 +108,14 @@ export const NOTE_PRESETS: NotePresetDefinition[] = [
   {
     id: "decision-note",
     label: "Decision Note",
-    description: "Context, decision, rationale, and consequences.",
+    description: "Current synthesis, decision, rationale, and timeline.",
     defaultTags: ["decision"],
     frontmatter: {
       category: "decision",
       status: "proposed",
     },
     body: (title) =>
-      `# ${title}\n\n## Context\n\n## Decision\n\n## Rationale\n\n## Consequences\n`,
+      `# ${title}\n\n## Current Synthesis\n\n## Decision\n\n## Rationale\n\n## Consequences\n\n## Timeline\n`,
   },
   {
     id: "prompt-pattern",
@@ -127,14 +131,66 @@ export const NOTE_PRESETS: NotePresetDefinition[] = [
   {
     id: "source-summary",
     label: "Source Summary",
-    description: "Summarize an article, paper, or external source cleanly.",
+    description: "Summarize a source with synthesis above evidence timeline.",
     defaultTags: ["source", "summary"],
     frontmatter: {
       category: "source-summary",
       sources: [],
     },
     body: (title) =>
-      `# ${title}\n\n## Summary\n\n## Important Claims\n\n## Evidence / Quotes\n\n## Takeaways\n`,
+      `# ${title}\n\n## Current Synthesis\n\n## Important Claims\n\n## Assessment\n\n## Timeline\n\n## Evidence / Quotes\n`,
+  },
+  {
+    id: "idea-original",
+    label: "Original Idea",
+    description:
+      "Capture exact phrasing, context, related concepts, and publish potential.",
+    frontmatter: {
+      type: "idea-original",
+      category: "idea-original",
+      tags: [],
+    },
+    body: (title) =>
+      `# ${title}\n\n## Current Synthesis\n\n## Open Threads\n\n## Assessment\n\n## Timeline\n\n## Exact Phrasing\n\n## Related Concepts\n`,
+  },
+  {
+    id: "person",
+    label: "Person",
+    description:
+      "Track current state, relationship, assessment, open threads, and timeline.",
+    frontmatter: {
+      type: "person",
+      category: "person",
+      tags: [],
+    },
+    body: (title) =>
+      `# ${title}\n\n## Current Synthesis\n\n## Open Threads\n\n## Assessment\n\n## Timeline\n\n## Relationship\n`,
+  },
+  {
+    id: "company-project",
+    label: "Company / Project",
+    description:
+      "Track state, changes, decisions, people, open threads, and timeline.",
+    frontmatter: {
+      type: "company-project",
+      category: "company-project",
+      tags: [],
+    },
+    body: (title) =>
+      `# ${title}\n\n## Current Synthesis\n\n## Open Threads\n\n## Assessment\n\n## Timeline\n\n## Decisions\n\n## People\n`,
+  },
+  {
+    id: "meeting",
+    label: "Meeting",
+    description:
+      "Put analysis above the timeline; keep transcript, notes, and actions below.",
+    frontmatter: {
+      type: "meeting",
+      category: "meeting",
+      tags: [],
+    },
+    body: (title) =>
+      `# ${title}\n\n## Current Synthesis\n\n## Open Threads\n\n## Assessment\n\n## Timeline\n\n## Transcript / Notes\n\n## Action Items\n`,
   },
 ];
 

package/src/core/ref-parser.ts

@@ -0,0 +1,145 @@
+/**
+ * Reference parser and resolver for document refs.
+ * Pure parsing helpers stay store-free; resolution depends only on StorePort.
+ *
+ * @module src/core/ref-parser
+ */
+
+import type { DocumentRow, StorePort } from "../store/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 };
+
+export type ResolvedDocRef =
+  | { doc: DocumentRow }
+  | { error: string; isValidation: boolean };
+
+const DOCID_PATTERN = /^#[a-f0-9]{6,}$/;
+const LINE_SUFFIX_PATTERN = /:(\d+)$/;
+const GLOB_PATTERN = /[*?[\]]/;
+
+/**
+ * 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 {
+  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 };
+  }
+
+  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);
+  }
+
+  if (baseRef.startsWith("gno://")) {
+    return { type: "uri", value: baseRef, line };
+  }
+
+  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 };
+}
+
+/**
+ * Resolve a document reference against the store.
+ */
+export async function resolveDocRef(
+  store: StorePort,
+  docRef: string
+): Promise<ResolvedDocRef> {
+  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": {
+      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 };
+}
+
+/**
+ * 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);
+}