fix: ignore braces inside strings and comments when matching blocks

signalblur · claude · signalblur · commit b39d25e3afb6 · 2026-07-30T16:56:22.000-04:00
The terraform, protobuf, graphql, and shell parsers locate a block's
extent by counting `{` and `}` as raw characters. A brace inside a string
literal or a comment decrements the depth early, so the block is
truncated: the reported `lineRange` stops short, and anything derived
from the body is sliced off with it. `extractMessageFields` returns an
empty array for a protobuf message whose first field carries an option
with a brace in its value, and `extractFields` loses GraphQL fields that
follow a default value containing one.

`graphql-parser.ts` had a second problem in `extractDefinitions`: it used
`indexOf("}")` with no depth counting at all, so the first brace in the
file ended every definition regardless of nesting.

Adds `brace-matcher.ts`, a state machine that tracks quote and
line-comment context, with a per-language `BraceSyntax` describing which
quote and comment forms to honor. `findClosingBrace` returns an index for
the parsers that slice by offset; `countBracesPerLine` returns per-line
deltas for the shell parser, which walks lines. Unbalanced input still
returns `content.length` and warns under the calling parser's name, as
the four private implementations did.

In `extractDefinitions` the brace scan now runs only when the definition's
header line opens a brace, so a bodyless `scalar` or `union` no longer
matches a later definition's closing brace.

Adds 11 regression tests. Each was confirmed to fail before the fix:
string and comment cases per parser, an escaped-quote case, a
backslash-continued line case, and the bodyless-scalar case.

Co-Authored-By: Claude Fable 5 &lt;noreply@anthropic.com&gt;
diff --git a/understand-anything-plugin/packages/core/src/__tests__/parsers.test.ts b/understand-anything-plugin/packages/core/src/__tests__/parsers.test.ts
@@ -627,3 +627,129 @@ describe("registerAllParsers", () => {
     expect(registry.getSupportedLanguages()).toContain("shell");
   });
 });
+
+describe("brace matching ignores strings and comments", () => {
+  it("terraform: a closing brace in a string does not end the block", () => {
+    const content = `resource "aws_ssm_parameter" "example" {
+  name  = "/app/config"
+  value = "suffix-}-marker"
+  type  = "String"
+}`;
+    const result = new TerraformParser().analyzeFile("main.tf", content);
+    expect(result.resources![0]).toMatchObject({ name: "aws_ssm_parameter.example" });
+    expect(result.resources![0].lineRange).toEqual([1, 5]);
+  });
+
+  it("terraform: a closing brace in a comment does not end the block", () => {
+    const content = `variable "example" {
+  # a brace in a comment: }
+  type    = string
+  default = "x"
+}`;
+    const result = new TerraformParser().analyzeFile("main.tf", content);
+    const def = result.definitions!.find(d => d.name === "example");
+    expect(def!.lineRange).toEqual([1, 5]);
+  });
+
+  it("protobuf: a closing brace in a comment keeps all fields", () => {
+    const content = `message Outer {
+  // a closing brace in a comment: }
+  string note = 1;
+  int32 after_comment = 2;
+}`;
+    const result = new ProtobufParser().analyzeFile("a.proto", content);
+    const msg = result.definitions!.find(d => d.name === "Outer");
+    expect(msg!.lineRange).toEqual([1, 5]);
+    expect(msg!.fields).toEqual(["note", "after_comment"]);
+  });
+
+  it("protobuf: a closing brace in a field option keeps later fields", () => {
+    const content = `message Outer {
+  string tmpl = 1 [(validate.rules).string.pattern = "^[a-z]}$"];
+  int32 after_literal = 2;
+}`;
+    const result = new ProtobufParser().analyzeFile("a.proto", content);
+    const msg = result.definitions!.find(d => d.name === "Outer");
+    expect(msg!.fields).toEqual(["tmpl", "after_literal"]);
+  });
+
+  it("graphql: a closing brace in a default value keeps all fields", () => {
+    const content = `input Config {
+  key: String = "a}b"
+  count: Int
+}`;
+    const result = new GraphQLParser().analyzeFile("schema.graphql", content);
+    const def = result.definitions!.find(d => d.name === "Config");
+    expect(def!.lineRange).toEqual([1, 4]);
+    expect(def!.fields).toEqual(["key", "count"]);
+  });
+
+  it("graphql: a nested brace does not truncate the line range", () => {
+    const content = `type Wrapper {
+  nested: Config @constraint(pattern: "{2,4}")
+  tail: Int
+}`;
+    const result = new GraphQLParser().analyzeFile("schema.graphql", content);
+    const def = result.definitions!.find(d => d.name === "Wrapper");
+    expect(def!.lineRange).toEqual([1, 4]);
+  });
+
+  it("graphql: a scalar without a body stays on its own line", () => {
+    const content = `scalar DateTime
+
+type User {
+  id: ID!
+}`;
+    const result = new GraphQLParser().analyzeFile("schema.graphql", content);
+    const scalar = result.definitions!.find(d => d.name === "DateTime");
+    expect(scalar!.lineRange).toEqual([1, 1]);
+  });
+
+  it("shell: a closing brace in a string does not end the function", () => {
+    const content = `#!/usr/bin/env bash
+render() {
+  echo "closing brace: }"
+  echo "still inside the function"
+}`;
+    const result = new ShellParser().analyzeFile("x.sh", content);
+    const fn = result.functions!.find(f => f.name === "render");
+    expect(fn!.lineRange).toEqual([2, 5]);
+  });
+
+  it("shell: a closing brace in a comment does not end the function", () => {
+    const content = `setup() {
+  # trailing brace in a comment: }
+  echo hi
+}`;
+    const result = new ShellParser().analyzeFile("x.sh", content);
+    const fn = result.functions!.find(f => f.name === "setup");
+    expect(fn!.lineRange).toEqual([1, 4]);
+  });
+
+  it("shell: escaped quotes do not swallow the rest of the file", () => {
+    const content = `first() {
+  echo "an escaped quote \\" and a brace }"
+}
+
+second() {
+  echo hi
+}`;
+    const result = new ShellParser().analyzeFile("x.sh", content);
+    expect(result.functions!.find(f => f.name === "first")!.lineRange).toEqual([1, 3]);
+    expect(result.functions!.find(f => f.name === "second")!.lineRange).toEqual([5, 7]);
+  });
+
+  it("shell: a backslash-continued string keeps later line numbers aligned", () => {
+    const content = `first() {
+  echo "continued \\
+line with a brace }"
+}
+
+second() {
+  echo hi
+}`;
+    const result = new ShellParser().analyzeFile("x.sh", content);
+    expect(result.functions!.find(f => f.name === "first")!.lineRange).toEqual([1, 4]);
+    expect(result.functions!.find(f => f.name === "second")!.lineRange).toEqual([6, 8]);
+  });
+});
diff --git a/understand-anything-plugin/packages/core/src/plugins/parsers/brace-matcher.ts b/understand-anything-plugin/packages/core/src/plugins/parsers/brace-matcher.ts
@@ -0,0 +1,159 @@
+/**
+ * Brace matching that skips string literals and line comments.
+ *
+ * Parsers in this directory locate a block's extent by counting `{` and `}`.
+ * Counting raw characters lets a brace inside a string or comment decrement the
+ * depth early, truncating the block: the reported `lineRange` stops short, and
+ * body-derived data (protobuf fields, GraphQL fields) is sliced off with it.
+ *
+ * Does not handle block comments, heredocs, or backtick/dollar interpolation.
+ */
+
+/** String and comment forms for one language. */
+export interface BraceSyntax {
+  quotes: string[];
+  lineComments: string[];
+  backslashEscapes: boolean;
+}
+
+/** HCL: double and single quotes, `#` and `//` comments. */
+export const TERRAFORM_SYNTAX: BraceSyntax = {
+  quotes: ['"', "'"],
+  lineComments: ["#", "//"],
+  backslashEscapes: true,
+};
+
+/** Protobuf: double and single quotes, `//` comments. */
+export const PROTOBUF_SYNTAX: BraceSyntax = {
+  quotes: ['"', "'"],
+  lineComments: ["//"],
+  backslashEscapes: true,
+};
+
+/** GraphQL: double quotes, `#` comments. */
+export const GRAPHQL_SYNTAX: BraceSyntax = {
+  quotes: ['"'],
+  lineComments: ["#"],
+  backslashEscapes: true,
+};
+
+/** Shell: double and single quotes, `#` comments. */
+export const SHELL_SYNTAX: BraceSyntax = {
+  quotes: ['"', "'"],
+  lineComments: ["#"],
+  backslashEscapes: true,
+};
+
+/**
+ * Finds the index of the `}` closing the first `{` in `content`, ignoring braces
+ * inside string literals and line comments.
+ *
+ * Returns `content.length` when the braces are unbalanced, matching the behavior
+ * of the per-parser implementations this replaces. When `parserName` is given, an
+ * unbalanced run warns under that name, as those implementations did.
+ */
+export function findClosingBrace(content: string, syntax: BraceSyntax, parserName?: string): number {
+  let depth = 0;
+  let quote: string | null = null;
+  let inLineComment = false;
+
+  for (let i = 0; i < content.length; i++) {
+    const ch = content[i];
+
+    if (inLineComment) {
+      if (ch === "\n") inLineComment = false;
+      continue;
+    }
+
+    if (quote !== null) {
+      if (syntax.backslashEscapes && ch === "\\") {
+        i++;
+      } else if (ch === quote) {
+        quote = null;
+      }
+      continue;
+    }
+
+    if (syntax.quotes.includes(ch)) {
+      quote = ch;
+      continue;
+    }
+
+    if (startsLineComment(content, i, syntax.lineComments)) {
+      inLineComment = true;
+      continue;
+    }
+
+    if (ch === "{") {
+      depth++;
+    } else if (ch === "}") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+
+  if (depth !== 0 && parserName) {
+    console.warn(`[${parserName}] Unbalanced braces detected (depth=${depth}), results may be incomplete`);
+  }
+  return content.length;
+}
+
+/**
+ * Counts `{` and `}` per line, ignoring those inside string literals and line
+ * comments. Line-oriented parsers need per-line deltas rather than a single index.
+ */
+export function countBracesPerLine(
+  content: string,
+  syntax: BraceSyntax,
+): Array<{ open: number; close: number }> {
+  const perLine: Array<{ open: number; close: number }> = [{ open: 0, close: 0 }];
+  let quote: string | null = null;
+  let inLineComment = false;
+
+  for (let i = 0; i < content.length; i++) {
+    const ch = content[i];
+
+    if (ch === "\n") {
+      inLineComment = false;
+      perLine.push({ open: 0, close: 0 });
+      continue;
+    }
+
+    if (inLineComment) continue;
+
+    if (quote !== null) {
+      if (syntax.backslashEscapes && ch === "\\") {
+        // An escaped newline is consumed here, so account for the line it ends —
+        // otherwise `perLine` desynchronizes from the caller's line array.
+        if (content[i + 1] === "\n") perLine.push({ open: 0, close: 0 });
+        i++;
+      } else if (ch === quote) {
+        quote = null;
+      }
+      continue;
+    }
+
+    if (syntax.quotes.includes(ch)) {
+      quote = ch;
+      continue;
+    }
+
+    if (startsLineComment(content, i, syntax.lineComments)) {
+      inLineComment = true;
+      continue;
+    }
+
+    const current = perLine[perLine.length - 1];
+    if (ch === "{") current.open++;
+    else if (ch === "}") current.close++;
+  }
+
+  return perLine;
+}
+
+function startsLineComment(content: string, index: number, prefixes: string[]): boolean {
+  for (const prefix of prefixes) {
+    if (content.startsWith(prefix, index)) return true;
+  }
+  return false;
+}
diff --git a/understand-anything-plugin/packages/core/src/plugins/parsers/graphql-parser.ts b/understand-anything-plugin/packages/core/src/plugins/parsers/graphql-parser.ts
@@ -1,4 +1,5 @@
 import type { AnalyzerPlugin, StructuralAnalysis, DefinitionInfo, EndpointInfo } from "../../types.js";
+import { findClosingBrace, GRAPHQL_SYNTAX } from "./brace-matcher.js";
 
 /**
  * Parses GraphQL schema files to extract type, input, enum, interface, union, and scalar definitions.
@@ -37,9 +38,15 @@ export class GraphQLParser implements AnalyzerPlugin {
       // Extract fields (for type/input/interface/enum)
       const fields = this.extractFields(content, match.index);
 
-      // Find closing brace
+      // Find closing brace. Bodyless definitions (scalar, union) have no brace
+      // on their header line, so only scan when the header actually opens one —
+      // otherwise the scan would run on into the next definition's block.
       const afterMatch = content.slice(match.index);
-      const closeBrace = afterMatch.indexOf("}");
+      const headerEnd = afterMatch.indexOf("\n");
+      const header = headerEnd === -1 ? afterMatch : afterMatch.slice(0, headerEnd);
+      const closeBrace = header.includes("{")
+        ? findClosingBrace(afterMatch, GRAPHQL_SYNTAX, "graphql-parser")
+        : -1;
       const endLine = closeBrace !== -1
         ? content.slice(0, match.index + closeBrace + 1).split("\n").length
         : startLine;
@@ -66,15 +73,10 @@ export class GraphQLParser implements AnalyzerPlugin {
       const startIdx = match.index + match[0].length;
 
       // Find closing brace
-      let depth = 1;
-      let i = startIdx;
-      while (i < content.length && depth > 0) {
-        if (content[i] === "{") depth++;
-        if (content[i] === "}") depth--;
-        i++;
-      }
+      const braceIdx = match.index + match[0].lastIndexOf("{");
+      const closeBrace = braceIdx + findClosingBrace(content.slice(braceIdx), GRAPHQL_SYNTAX);
 
-      const blockContent = content.slice(startIdx, i - 1);
+      const blockContent = content.slice(startIdx, closeBrace);
       const blockLines = blockContent.split("\n");
       const blockStartLine = content.slice(0, startIdx).split("\n").length;
 
@@ -100,15 +102,8 @@ export class GraphQLParser implements AnalyzerPlugin {
     const openBrace = afterType.indexOf("{");
     if (openBrace === -1) return fields;
 
-    let depth = 1;
-    let i = openBrace + 1;
-    while (i < afterType.length && depth > 0) {
-      if (afterType[i] === "{") depth++;
-      if (afterType[i] === "}") depth--;
-      i++;
-    }
-
-    const body = afterType.slice(openBrace + 1, i - 1);
+    const closeBrace = findClosingBrace(afterType, GRAPHQL_SYNTAX);
+    const body = afterType.slice(openBrace + 1, closeBrace);
     const lines = body.split("\n");
     for (const line of lines) {
       const fieldMatch = line.trim().match(/^(\w+)/);
diff --git a/understand-anything-plugin/packages/core/src/plugins/parsers/index.ts b/understand-anything-plugin/packages/core/src/plugins/parsers/index.ts
@@ -10,6 +10,7 @@ export { ProtobufParser } from "./protobuf-parser.js";
 export { TerraformParser } from "./terraform-parser.js";
 export { MakefileParser } from "./makefile-parser.js";
 export { ShellParser } from "./shell-parser.js";
+export { findClosingBrace, countBracesPerLine } from "./brace-matcher.js";
 
 import type { PluginRegistry } from "../registry.js";
 import { MarkdownParser } from "./markdown-parser.js";
diff --git a/understand-anything-plugin/packages/core/src/plugins/parsers/protobuf-parser.ts b/understand-anything-plugin/packages/core/src/plugins/parsers/protobuf-parser.ts
@@ -1,4 +1,5 @@
 import type { AnalyzerPlugin, StructuralAnalysis, DefinitionInfo, EndpointInfo } from "../../types.js";
+import { findClosingBrace, PROTOBUF_SYNTAX } from "./brace-matcher.js";
 
 /**
  * Parses Protocol Buffer (.proto) files to extract message, enum, and service definitions.
@@ -125,17 +126,6 @@ export class ProtobufParser implements AnalyzerPlugin {
   }
 
   private findClosingBrace(content: string): number {
-    let depth = 0;
-    for (let i = 0; i < content.length; i++) {
-      if (content[i] === "{") depth++;
-      if (content[i] === "}") {
-        depth--;
-        if (depth === 0) return i;
-      }
-    }
-    if (depth !== 0) {
-      console.warn(`[protobuf-parser] Unbalanced braces detected (depth=${depth}), results may be incomplete`);
-    }
-    return content.length;
+    return findClosingBrace(content, PROTOBUF_SYNTAX, "protobuf-parser");
   }
 }
diff --git a/understand-anything-plugin/packages/core/src/plugins/parsers/shell-parser.ts b/understand-anything-plugin/packages/core/src/plugins/parsers/shell-parser.ts
diff --git a/understand-anything-plugin/packages/core/src/plugins/parsers/terraform-parser.ts b/understand-anything-plugin/packages/core/src/plugins/parsers/terraform-parser.ts
