Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.5 KB
Raw Blame
/**
 * Shared `--source` / `--all-sources` resolution for the four code-* CLI
 * commands (code-def, code-refs, code-callers, code-callees).
 *
 * Extracted from code-callers.ts / code-callees.ts, which carried identical
 * copies of this block. code-def and code-refs were brain-wide and had no copy
 * at all; giving all four one resolver is what keeps them from drifting again.
 *
 * Exits the process with code 2 on a usage-level failure (ambiguous source, bad
 * pin), matching the pre-extraction behavior of both callers.
 */

import type { BrainEngine } from '../core/engine.ts';
import { errorFor } from '../core/errors.ts';
import { resolveScopedSourceOrThrow, SourceResolutionError } from '../core/sources-ops.ts';
import { formatSoleNonDefaultNudge, isResolverUserError } from '../core/source-resolver.ts';
import { codeChunksExist } from '../core/code-graph-readiness.ts';

// A bad/invalid `.gbrain-source` pin or GBRAIN_SOURCE value surfaces from
// `resolveSourceWithTier`'s `assertSourceExists` as a resolver user error;
// the shared `isResolverUserError` (source-resolver.ts, next to the messages
// it matches) turns it into the exit-2 `invalid_source_pin` envelope below
// instead of an uncaught stack.

/**
 * Flags that consume the NEXT argv entry as their value. A positional scan that
 * ignores them treats the value as the symbol: `code-def --source srcb sym`
 * looked up the symbol "srcb". Pre-existing for --lang/--limit; adding --source
 * to code-def/code-refs multiplied the ways to hit it.
 */
const VALUE_FLAGS = new Set(['--source', '--limit', '--lang']);

/** Positional args, skipping both value-taking flags and their values.
 * The inline `name=value` flag spelling is one token starting with a double
 * dash, so the generic branch skips it without consuming a following token. */
/**
 * #5001: the symbol resolver links calls within one file, so every cross-file call stays unresolved and is
 * matched by short name only (it can name a different symbol with the same name).
 */
export const UNRESOLVED_CALL_LABEL = 'unresolved (cross-file, matched by name)';

export function positionalArgs(args: string[]): string[] {
  const out: string[] = [];
  for (let i = 0; i < args.length; i++) {
    const a = args[i];
    if (a.startsWith('--')) {
      if (VALUE_FLAGS.has(a)) i++;
      continue;
    }
    out.push(a);
  }
  return out;
}

/**
 * Value-flag reader shared by the four code-* commands: accepts BOTH the
 * two-token `name value` and the inline `name=value` flag spellings. The
 * per-command exact-token copies silently ignored the inline spelling of
 * the source flag, answering from the wrong scope for a user who explicitly
 * named a source (review fix on the #4749 adoption).
 * NOTE: no double-dash flag literals in this comment — the flag-registry
 * generator harvests them from every scanned module (see source-resolver.ts).
 */
export function parseFlag(args: string[], name: string): string | undefined {
  const i = args.indexOf(name);
  if (i >= 0 && i + 1 < args.length) return args[i + 1];
  const inline = args.find((a) => a.startsWith(`${name}=`));
  return inline ? inline.slice(name.length + 1) : undefined;
}

/**
 * Source-scope SQL predicate shared by the code-def / code-refs lookups (and
 * code-def's filtered-types probe): appends the source id to `params` and
 * returns the `AND p.source_id = $N` fragment, or '' when spanning every
 * source. Numbered off `params.length` so it composes with any number of
 * optional predicates before it (a fixed `$2` broke the moment --lang joined).
 */
export function pushSourcePredicate(
  params: unknown[],
  opts: { sourceId?: string; allSources?: boolean },
): string {
  if (opts.allSources || !opts.sourceId) return '';
  params.push(opts.sourceId);
  return `AND p.source_id = $${params.length}`;
}

export interface CodeScope {
  allSources: boolean;
  sourceId?: string;
  /** `'all'` when spanning sources, `'single'` when one source was resolved. */
  scope: 'all' | 'single';
  /** null when spanning sources — the value the JSON envelope reports. */
  envelopeSourceId: string | null;
}

/**
 * Resolve the source scope for a code-* CLI invocation.
 *
 * When neither `--source` nor `--all-sources` is set, routes through the full
 * source-resolution chain (`.gbrain-source` pin, env, local_path,
 * brain_default, sole_non_default); only a no-signal multi-source brain still
 * errors as `multiple_sources_ambiguous`.
 */
export async function resolveCliCodeScope(
  engine: BrainEngine,
  opts: { sourceId?: string; allSources: boolean; jsonMode: boolean; command: string },
): Promise<CodeScope> {
  const { allSources, jsonMode, command } = opts;
  let sourceId = opts.sourceId;

  // Contradictory flags are a usage error, not a silent winner. Resolving them
  // by precedence hides a typo'd invocation behind plausible-looking output.
  if (allSources && sourceId) {
    exitUsage(jsonMode, errorFor({
      class: 'UsageError',
      code: 'conflicting_source_scope',
      message: `${command}: --source and --all-sources are mutually exclusive`,
      hint: 'pass --source <id> to scope to one source, or --all-sources to span every source',
    }).envelope, `${command}: --source and --all-sources are mutually exclusive`);
  }

  // An explicit --source skips the resolution chain, so it also skips that
  // chain's existence check. Unvalidated, a typo lands in the SQL predicate and
  // returns an empty result that reads as "no such symbol".
  if (sourceId) {
    if (sourceId.startsWith('--')) {
      exitUsage(jsonMode, errorFor({
        class: 'UsageError',
        code: 'missing_source_value',
        message: `${command}: --source expects a source id, got '${sourceId}'`,
        hint: 'pass --source <id>, or drop it to use the .gbrain-source pin',
      }).envelope, `${command}: --source expects a source id, got '${sourceId}'`);
    }
    if (!(await sourceExists(engine, sourceId))) {
      exitUsage(jsonMode, errorFor({
        class: 'UsageError',
        code: 'unknown_source',
        message: `Source "${sourceId}" not found or is archived.`,
        hint: 'run `gbrain sources list` to see registered sources',
      }).envelope, `Source "${sourceId}" not found or is archived.`);
    }
  }

  if (!allSources && !sourceId) {
    try {
      const resolved = await resolveScopedSourceOrThrow(engine);
      sourceId = resolved.source_id;
      // Nudge only when we auto-routed to the sole non-default source (the one
      // tier with no explicit user signal). Matches sync/import behavior.
      if (resolved.tier === 'sole_non_default') {
        const nudge = formatSoleNonDefaultNudge(resolved.source_id);
        if (nudge) console.error(nudge);
      }
    } catch (e: unknown) {
      if (e instanceof SourceResolutionError) {
        exitUsage(jsonMode, errorFor({
          class: 'UsageError',
          code: e.code,
          message: e.message,
          hint: 'pass --source <id> for one source, or --all-sources to search every source',
        }).envelope, e.message);
      }
      if (isResolverUserError(e)) {
        exitUsage(jsonMode, errorFor({
          class: 'UsageError',
          code: 'invalid_source_pin',
          message: (e as Error).message,
          hint: `fix the .gbrain-source pin / GBRAIN_SOURCE value, or pass --source <id> / --all-sources to ${command}`,
        }).envelope, (e as Error).message);
      }
      throw e;
    }
  }

  // #4747 / #3242 sibling: on a vault+code brain the resolution chain can land
  // on a source that holds no code at all (the scalar seed source, usually
  // 'default'). Scoping to it turns every lookup into a silent zero. The MCP
  // graph ops RE-ROUTE for this shape; def/refs are plain SQL, so they can just
  // widen. Only fires when the resolved source was implicit — an explicit
  // --source is the user's word and is never second-guessed.
  const widened = (!allSources && sourceId && !opts.sourceId)
    ? await shouldWidenForNoCode(engine, sourceId)
    : false;
  if (widened) {
    console.error(
      `[${command}] resolved source '${sourceId}' holds no code — widening to every source. ` +
      `Pass --source <id> to pin one, or --all-sources to make this explicit.`,
    );
  }

  const spanning = allSources || widened;
  return {
    allSources: spanning,
    sourceId: spanning ? undefined : (sourceId ?? undefined),
    scope: spanning ? 'all' : 'single',
    envelopeSourceId: spanning ? null : (sourceId ?? null),
  };
}

/**
 * True when an IMPLICITLY resolved source holds no code but the brain has code
 * elsewhere — the vault+code shape where scoping would answer every lookup with
 * a silent zero. Exported for tests; a probe failure returns false so the
 * resolved scope stands.
 */
export async function shouldWidenForNoCode(
  engine: BrainEngine,
  sourceId: string,
): Promise<boolean> {
  try {
    if (await codeChunksExist(engine, sourceId)) return false;
    return await codeChunksExist(engine, undefined);
  } catch {
    return false;
  }
}

/** Existence check for an explicit --source, mirroring the resolver's own gate. */
async function sourceExists(engine: BrainEngine, sourceId: string): Promise<boolean> {
  try {
    const rows = await engine.executeRaw<{ e: boolean }>(
      `SELECT EXISTS(SELECT 1 FROM sources WHERE id = $1 AND NOT archived) AS e`,
      [sourceId],
    );
    return rows[0]?.e === true;
  } catch {
    // A probe failure must not block a lookup the user could otherwise run.
    return true;
  }
}

function exitUsage(jsonMode: boolean, envelope: unknown, message: string): never {
  if (jsonMode) {
    console.log(JSON.stringify({ error: envelope }));
  } else {
    console.error(message);
  }
  process.exit(2);
}