Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
7.7 KB
Raw Blame
/**
 * Read-only graph-health gate for the codegraph partner
 * (https://github.com/colbymchenry/codegraph, upstream feature parity with
 * safishamsi/graphify v0.8.46).
 *
 * A code graph can be syntactically present - `codegraph status` reports it
 * `initialized` with node and edge counts - while being subtly wrong: the
 * index was built for a different root, relationship extraction collapsed to
 * zero edges, or the partner's own diagnostics found dangling references and
 * self-loops. Any of those makes the graph an untrustworthy input for
 * labeling, import, or downstream recall.
 *
 * This gate runs AFTER the partner has constructed/indexed the graph and
 * BEFORE any OSB surface (the partner report, `o2b doctor`, and any future
 * codegraph-derived edge import) trusts it. It is strictly read-only and
 * non-destructive: it never runs extraction, never mutates the index or the
 * vault, and NEVER aborts. Every problem is surfaced as a warning; the caller
 * decides how loudly to report it. `ok` is a convenience derived from
 * `warnings.length === 0`.
 *
 * Detection is grounded in the fields the real `codegraph status -j` emits
 * (node/edge counts, `worktreeMismatch`), plus optional partner-provided
 * diagnostic counts (`danglingRefs`, `selfLoops`) consumed when present so the
 * gate stays forward-compatible with a richer status surface.
 */

/**
 * Stable code per health finding so callers can filter without parsing text.
 *
 * Frozen rather than a bare union because the codes are consumed outside
 * TypeScript: the codegraph resync cron recipe emits a shell gate that
 * selects one of them out of `--json` output, so the string has to be
 * reachable as a value, not only as a type.
 */
export const GRAPH_HEALTH_CODES = Object.freeze({
  emptyGraph: "empty-graph",
  collapsedEdges: "collapsed-edges",
  danglingReferences: "dangling-references",
  selfLoops: "self-loops",
  cacheRootMismatch: "cache-root-mismatch",
} as const);

export type GraphHealthCode = (typeof GRAPH_HEALTH_CODES)[keyof typeof GRAPH_HEALTH_CODES];

/**
 * Membership list, in declaration (severity) order.
 *
 * Named `_LIST` rather than pluralized because the frozen object above
 * already carries the plural name and is quoted by callers outside this
 * module; renaming it to free the plural would move a value the emitted
 * shell script selects on.
 */
export const GRAPH_HEALTH_CODE_LIST: ReadonlyArray<GraphHealthCode> = Object.freeze(
  Object.values(GRAPH_HEALTH_CODES),
);

/**
 * Narrow a string that arrives from outside TypeScript.
 *
 * The codes leave this process: the resync cron recipe interpolates one
 * into a shell gate that selects it out of `--json` output, and a caller
 * filtering the report by code may equally read one from a config file or
 * an operator's argument. A guard is what keeps "no finding with that
 * code" distinguishable from "that is not a code" - the same reason the
 * snapshot-reason filter has one.
 */
export function isGraphHealthCode(value: unknown): value is GraphHealthCode {
  return (
    typeof value === "string" && (GRAPH_HEALTH_CODE_LIST as ReadonlyArray<string>).includes(value)
  );
}

/** One non-blocking graph-health finding. */
export interface GraphHealthWarning {
  readonly code: GraphHealthCode;
  readonly message: string;
}

/** Outcome of the gate. `ok` is true exactly when there are no warnings. */
export interface GraphHealthReport {
  readonly ok: boolean;
  readonly warnings: ReadonlyArray<GraphHealthWarning>;
}

export interface GraphHealthInput {
  /** Node count reported by `codegraph status` (defaults to 0 when absent). */
  readonly nodeCount: number;
  /** Edge count reported by `codegraph status` (defaults to 0 when absent). */
  readonly edgeCount: number;
  /**
   * Dangling-reference count from the partner's own diagnostics. Optional:
   * base `codegraph status` does not emit it, so the finding only fires when
   * a status surface provides it. `undefined` means "not measured", not zero.
   */
  readonly danglingRefs?: number;
  /**
   * Self-loop edge count from the partner's diagnostics. Same optional
   * semantics as {@link GraphHealthInput.danglingRefs}.
   */
  readonly selfLoops?: number;
  /**
   * Absolute root the index was built for (`status.projectPath` or
   * `worktreeMismatch.indexRoot`). Compared against {@link
   * GraphHealthInput.worktreeRoot} for the cache-root-mismatch finding.
   */
  readonly indexRoot?: string | null;
  /**
   * Absolute root the graph is being read from (the in-scope project or
   * `worktreeMismatch.worktreeRoot`). A mismatch means file/line references in
   * the graph are rooted elsewhere and may be stale for this tree.
   */
  readonly worktreeRoot?: string | null;
}

/** Strip trailing slashes so `/repo` and `/repo/` compare equal. */
function stripTrailingSlash(p: string): string {
  return p.replace(/\/+$/, "");
}

/** Trailing-slash-insensitive path comparison. */
function samePath(a: string, b: string): boolean {
  return stripTrailingSlash(a) === stripTrailingSlash(b);
}

/**
 * Assess graph health from the partner status projection. Pure, total, and
 * never-throwing: unknown or missing inputs simply produce no warning rather
 * than a false positive. Findings are returned in a stable, severity-ordered
 * sequence (structural emptiness first, then reference integrity, then
 * root provenance) so callers can render them deterministically.
 */
export function assessGraphHealth(input: GraphHealthInput): GraphHealthReport {
  const warnings: GraphHealthWarning[] = [];
  const nodes = Number.isFinite(input.nodeCount) ? input.nodeCount : 0;
  const edges = Number.isFinite(input.edgeCount) ? input.edgeCount : 0;

  if (nodes <= 0) {
    warnings.push({
      code: GRAPH_HEALTH_CODES.emptyGraph,
      message:
        "index is initialized but holds 0 nodes; extraction produced an empty graph - " +
        "labeling and recall will find nothing until it is re-indexed",
    });
  } else if (edges <= 0) {
    // Nodes without edges: symbols were extracted but no relationships. Only
    // meaningful when there is at least one node (an empty graph is reported
    // above and should not double-warn).
    warnings.push({
      code: GRAPH_HEALTH_CODES.collapsedEdges,
      message:
        `graph has ${nodes} node(s) but 0 edges; relationship extraction collapsed - ` +
        "callers/callees/impact traversal will be empty",
    });
  }

  if (input.danglingRefs !== undefined && input.danglingRefs > 0) {
    warnings.push({
      code: GRAPH_HEALTH_CODES.danglingReferences,
      message:
        `${input.danglingRefs} dangling reference(s): edges point at nodes absent from the ` +
        "index; derived labels/imports built from them would reference missing symbols",
    });
  }

  if (input.selfLoops !== undefined && input.selfLoops > 0) {
    warnings.push({
      code: GRAPH_HEALTH_CODES.selfLoops,
      message:
        `${input.selfLoops} self-loop edge(s): a node references itself; ` +
        "impact and traversal surfaces may double-count or cycle",
    });
  }

  if (input.indexRoot && input.worktreeRoot && !samePath(input.indexRoot, input.worktreeRoot)) {
    warnings.push({
      code: GRAPH_HEALTH_CODES.cacheRootMismatch,
      message:
        `index was built for '${input.indexRoot}' but is being read from ` +
        `'${input.worktreeRoot}'; file and line references may be stale for this tree - ` +
        "re-index the current root before trusting graph-derived artifacts",
    });
  }

  return { ok: warnings.length === 0, warnings };
}

/** Compact one-line summary of a report, e.g. `2 warning(s) [collapsed-edges, self-loops]`. */
export function summarizeGraphHealth(report: GraphHealthReport): string {
  if (report.warnings.length === 0) return "ok";
  const codes = report.warnings.map((w) => w.code).join(", ");
  return `${report.warnings.length} warning(s) [${codes}]`;
}