codegraph/src/resolution/frameworks/terraform.ts

/**
 * Terraform Framework Resolver
 *
 * Terraform's scoping rule is narrow and directory-shaped: `var.X`,
 * `local.X`, `module.M`, and resource/data references resolve ONLY inside
 * the same module directory as the reference site. The generic name matcher
 * resolves by qualified-name alone, so a reference to `var.project_id` from
 * `modules/net-vpc/main.tf` could bind to a `variable "project_id"` declared
 * in an unrelated module — a wrong cross-module edge that poisons impact
 * analysis. This resolver enforces the real semantics:
 *
 *   1. Same directory as the reference site → resolve (highest confidence).
 *   2. `.tfvars` files additionally walk UP to the nearest ancestor
 *      directory declaring the variable (`terraform apply -var-file=envs/prod.tfvars`
 *      sets ROOT module variables from a subdirectory).
 *   3. Otherwise: no edge. Terraform cannot reference across sibling module
 *      directories, so a non-local candidate is never a correct target.
 *
 * It also bridges the module boundary through `:`-scoped references that
 * only this resolver understands (see the extractor's emitModuleWiring):
 *
 *   - `module.M:file`       → the entry file of the module's local source
 *     directory (an `imports` edge, so a module call connects to the code
 *     it instantiates).
 *   - `module.M:var.<in>`   → the child module's `variable "<in>"` node —
 *     the module block sets that variable, so "what depends on the child's
 *     var.cidr" reaches every caller.
 *   - `module.M:output.<o>` → the child module's `output "<o>"` node —
 *     `module.M.o` uses flow through to the output's definition instead of
 *     dead-ending at the module declaration.
 *
 * The module's `source` is re-read from the declaration's file (cached
 * lines); only local `./`/`../` sources bridge. Registry/git sources stay
 * unresolved — an out-of-repo module is a visible boundary, never a guess.
 */

import * as path from 'path';
import type { Node } from '../../types';
import type { FrameworkResolver, UnresolvedRef, ResolvedRef, ResolutionContext } from '../types';

/** `module.M:file` / `module.M:var.X` / `module.M:output.X` / `module.M:remote-output.X` — extractor-emitted scoped refs. */
const SCOPED_REF = /^module\.([^.:\s]+):(file$|var\.|output\.|remote-output\.)/;

export const terraformResolver: FrameworkResolver = {
  name: 'terraform',
  languages: ['terraform'],

  detect(context: ResolutionContext): boolean {
    return context.getAllFiles().some((f) => f.endsWith('.tf') || f.endsWith('.tfvars') || f.endsWith('.tofu'));
  },

  // Scoped refs name no declared symbol; opt them through the resolver's
  // name-exists pre-filter so they reach resolve() at all.
  claimsReference(name: string): boolean {
    return SCOPED_REF.test(name);
  },

  resolve(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null {
    if (ref.language !== 'terraform') return null;

    const qname = ref.referenceName;
    const refDir = dirOf(ref.filePath);

    // --- module-boundary bridge: module.M:file / module.M:var.X / module.M:output.X ---
    const scoped = qname.match(/^module\.([^.:\s]+):(.+)$/);
    if (scoped) {
      return resolveScopedModuleRef(ref, scoped[1]!, scoped[2]!, refDir, context);
    }

    const candidates = context.getNodesByQualifiedName(qname);
    if (candidates.length === 0) return null;

    // 1. Same directory — the only scope Terraform can actually reference.
    const sameDir = candidates.filter((c) => dirOf(c.filePath) === refDir);
    if (sameDir.length > 0) {
      return {
        original: ref,
        targetNodeId: sameDir[0]!.id,
        confidence: 0.95,
        resolvedBy: 'framework',
      };
    }

    // 2. `.tfvars` assignments set ROOT module variables, and var-files are
    //    routinely kept in a subdirectory (`envs/prod.tfvars`). Walk up to
    //    the nearest ancestor directory that declares the variable.
    if (ref.filePath.endsWith('.tfvars') && qname.startsWith('var.')) {
      const up = nearestAncestorMatch(candidates, refDir);
      if (up) {
        return { original: ref, targetNodeId: up.id, confidence: 0.9, resolvedBy: 'framework' };
      }
    }

    // 2b. Provider configurations are the one construct Terraform inherits
    //     across the module tree: they're declared in the root (or a parent)
    //     module and passed down, so `provider = aws.east` inside a child
    //     module legitimately names a configuration declared above it.
    if (qname.startsWith('provider.')) {
      const configs = candidates.filter((c) => c.kind === 'namespace');
      const up = nearestAncestorMatch(configs, refDir);
      if (up) {
        return { original: ref, targetNodeId: up.id, confidence: 0.9, resolvedBy: 'framework' };
      }
      return null;
    }

    // 3. No same-directory declaration → no edge. A candidate in another
    //    module directory is never the real target (cross-module access only
    //    exists through module.M inputs/outputs, bridged above), and a wrong
    //    edge is worse than none.
    return null;
  },
};

/** Nearest candidate walking UP the directory tree from refDir (exclusive). */
function nearestAncestorMatch<T extends { filePath: string }>(candidates: T[], refDir: string): T | null {
  for (let dir = parentOf(refDir); dir !== null; dir = parentOf(dir)) {
    const inDir = candidates.filter((c) => dirOf(c.filePath) === dir);
    if (inDir.length > 0) return inDir[0]!;
  }
  return null;
}

/**
 * Resolve `module.M:<child>` by locating the `module "M"` declaration in the
 * reference's own directory, reading its `source` attribute, and looking the
 * child symbol up inside that directory.
 */
function resolveScopedModuleRef(
  ref: UnresolvedRef,
  moduleName: string,
  child: string,
  refDir: string,
  context: ResolutionContext
): ResolvedRef | null {
  const decls = context
    .getNodesByQualifiedName(`module.${moduleName}`)
    .filter((n) => n.kind === 'module');
  if (decls.length === 0) return null;
  // Terraform scoping: the declaration lives in the reference's directory.
  const decl = decls.find((d) => dirOf(d.filePath) === refDir) ?? (decls.length === 1 ? decls[0]! : null);
  if (!decl) return null;

  const source = readModuleAttr(decl, 'source', context);
  if (!source) return null;

  // --- cloudposse/atmos remote-state: module.M.outputs.X where M is the
  // stack-config remote-state module reading another COMPONENT's state. The
  // component name is static in the monorepo case (`component = "vpc"` or
  // "eks/cluster"), so bridge to that component directory's own
  // `output "X"` — but only when every gate holds: the module source is the
  // remote-state module, the component is a string literal, and exactly ONE
  // directory in the repo matches the component name and declares that
  // output. Anything dynamic or ambiguous stays a visible boundary.
  if (child.startsWith('remote-output.')) {
    if (!/\/remote-state(\/|$)/.test(source)) return null;
    let component = readModuleAttr(decl, 'component', context);
    if (!component) {
      // The other half of real-world declarations indirect through a
      // variable with a literal default in the same directory
      // (`component = var.vpc_component_name` + `default = "vpc"`) — the
      // component's declared static wiring. One hop, same literal gate.
      const viaVar = readNodeSpanMatch(decl, /^\s*component\s*=\s*var\.([A-Za-z0-9_-]+)\s*$/, context);
      if (viaVar) {
        const declared = context
          .getNodesByQualifiedName(`var.${viaVar}`)
          .filter((n) => dirOf(n.filePath) === dirOf(decl.filePath));
        if (declared.length === 1) {
          component = readNodeSpanMatch(declared[0]!, /^\s*default\s*=\s*"([^"]+)"/, context);
        }
      }
    }
    if (!component) return null;
    const outName = child.slice('remote-output.'.length);
    const outs = context
      .getNodesByQualifiedName(`output.${outName}`)
      .filter((o) => {
        const d = dirOf(o.filePath);
        return d === component || d.endsWith('/' + component);
      });
    if (outs.length === 0) return null;
    const dirs = new Set(outs.map((o) => dirOf(o.filePath)));
    if (dirs.size > 1) return null; // two directories claim this component name — never guess
    return { original: ref, targetNodeId: outs[0]!.id, confidence: 0.9, resolvedBy: 'framework' };
  }

  if (!(source.startsWith('./') || source.startsWith('../'))) {
    // Registry / git / absolute sources are out-of-repo: stay unresolved.
    return null;
  }
  const targetDir = normalizeRel(joinDirs(dirOf(decl.filePath), source));

  if (child === 'file') {
    const tfFiles = context
      .getAllFiles()
      .filter((f) => dirOf(f) === targetDir && (f.endsWith('.tf') || f.endsWith('.tofu')))
      .sort();
    if (tfFiles.length === 0) return null;
    const entry = tfFiles.find((f) => f.endsWith('/main.tf') || f === 'main.tf') ?? tfFiles[0]!;
    const fileNode = context.getNodesInFile(entry).find((n) => n.kind === 'file');
    if (!fileNode) return null;
    return { original: ref, targetNodeId: fileNode.id, confidence: 0.95, resolvedBy: 'framework' };
  }

  // child is `var.X` or `output.X` — the child module's own qualified names.
  const target = context
    .getNodesByQualifiedName(child)
    .filter((c) => dirOf(c.filePath) === targetDir);
  if (target.length === 0) return null;
  return { original: ref, targetNodeId: target[0]!.id, confidence: 0.95, resolvedBy: 'framework' };
}

/**
 * A direct string-literal attribute (`source = "…"`, `component = "…"`) of a
 * module declaration, re-read from its file (project paths are stored
 * relative; node metadata isn't persisted, so the declaration's line span +
 * cached file lines are the durable carrier). Non-literal values (variables,
 * expressions) return null — dynamic wiring is never guessed.
 */
function readModuleAttr(decl: Node, name: string, context: ResolutionContext): string | null {
  return readNodeSpanMatch(decl, new RegExp(`^\\s*${name}\\s*=\\s*"([^"]+)"`), context);
}

/** First capture of `re` across the node's line span, or null. */
function readNodeSpanMatch(node: Node, re: RegExp, context: ResolutionContext): string | null {
  const lines =
    context.getFileLines?.(node.filePath) ?? context.readFile(node.filePath)?.split('\n') ?? null;
  if (!lines) return null;
  const end = Math.min(node.endLine, lines.length);
  for (let i = Math.max(node.startLine - 1, 0); i < end; i++) {
    const m = lines[i]!.match(re);
    if (m) return m[1]!;
  }
  return null;
}

/** Directory of a stored (forward-slash, project-relative) path. */
function dirOf(p: string): string {
  const d = path.dirname(p);
  return d === '' ? '.' : d;
}

/** Parent directory, or null above the project root. */
function parentOf(dir: string): string | null {
  if (dir === '.' || dir === '') return null;
  const parent = path.dirname(dir);
  return parent === dir ? null : parent;
}

/** Join a base directory with a `./`/`../` relative source path. */
function joinDirs(base: string, rel: string): string {
  return path.join(base === '.' ? '' : base, rel);
}

/** Normalize to the stored path shape: forward slashes, '.' for the root. */
function normalizeRel(p: string): string {
  const n = path.normalize(p).replace(/\\/g, '/').replace(/\/+$/, '');
  return n === '' ? '.' : n;
}