gitnexus 1.6.12-rc.2 → 1.6.12-rc.21

package/dist/core/embeddings/chunker.js

@@ -89,8 +89,32 @@ const DECLARATION_BODY_NODE_TYPES = new Set([
     'class_body',
     'object_type',
     'declaration_list',
+    'implementation_definition',
     'interface_body',
 ]);
+const DIRECT_MEMBER_DECLARATION_TYPES = new Set([
+    'protocol_declaration',
+    'class_interface',
+    // tree-sitter-objc exposes each implementation_definition directly under
+    // class_implementation, rather than grouping them in a shared body node.
+    'class_implementation',
+]);
+const DIRECT_MEMBER_HEADER_NODE_TYPES = new Set([
+    'identifier',
+    'parameterized_arguments',
+    'protocol_reference_list',
+    // tree-sitter-objc `_type_params` hides itself and exposes this named child
+    // for `(T)` generics and category-shaped argument lists.
+    'generic_arguments',
+    // `_class_interface_header` / `_class_implementation_header` expose these
+    // named children before members (`NS_ROOT_CLASS @interface …`).
+    'attribute_declaration',
+    'attribute_specifier',
+    'availability_attribute_specifier',
+    'ms_declspec_modifier',
+    'storage_class_specifier',
+    'type_qualifier',
+]);
 const FIELD_LIKE_MEMBER_TYPES = new Set([
     'field_definition',
     'public_field_definition',
@@ -100,7 +124,15 @@ const FIELD_LIKE_MEMBER_TYPES = new Set([
     'lexical_declaration',
     'pair',
     'enum_assignment',
+    // tree-sitter-objc wraps each ivar as `instance_variable`, not field_definition.
+    'instance_variable',
 ]);
+const DECLARATION_MEMBER_WRAPPER_TYPES = new Set([
+    'qualified_protocol_interface_declaration',
+    'instance_variables',
+]);
+/** Named prefixes the ObjC grammar allows immediately before each ivar. */
+const IVAR_ATTRIBUTE_PREFIX_TYPES = new Set(['attribute_specifier', 'attribute_declaration']);
 const declarationChunk = async (content, filePath, startLine, endLine, chunkSize, overlap, rule) => {
     const tree = await ensureAndParse(content, filePath);
     if (!tree)
@@ -196,6 +228,8 @@ const getDeclarationBodyNode = (node) => {
     const bodyNode = node.childForFieldName?.('body');
     if (bodyNode)
         return bodyNode;
+    if (DIRECT_MEMBER_DECLARATION_TYPES.has(node.type))
+        return node;
     for (let i = 0; i < node.namedChildCount; i++) {
         const child = node.namedChild(i);
         if (!child)
@@ -207,16 +241,39 @@ const getDeclarationBodyNode = (node) => {
 };
 const collectDeclarationUnits = (bodyNode, groupFields) => {
     const members = [];
-    for (let i = 0; i < bodyNode.namedChildCount; i++) {
-        const child = bodyNode.namedChild(i);
-        if (!child)
-            continue;
-        members.push({
-            startIndex: child.startIndex,
-            endIndex: child.endIndex,
-            groupable: groupFields && FIELD_LIKE_MEMBER_TYPES.has(child.type),
-        });
-    }
+    const collectMembers = (node, skipHeaderChildren, includeNodePrefixOnFirstMember = false) => {
+        const firstMemberIndex = members.length;
+        let ivarAttributePrefixStart;
+        for (let i = 0; i < node.namedChildCount; i++) {
+            const child = node.namedChild(i);
+            if (!child)
+                continue;
+            if (DECLARATION_MEMBER_WRAPPER_TYPES.has(child.type)) {
+                collectMembers(child, false, true);
+                continue;
+            }
+            if (skipHeaderChildren && DIRECT_MEMBER_HEADER_NODE_TYPES.has(child.type))
+                continue;
+            if (node.type === 'instance_variables' && IVAR_ATTRIBUTE_PREFIX_TYPES.has(child.type)) {
+                ivarAttributePrefixStart ??= child.startIndex;
+                continue;
+            }
+            members.push({
+                startIndex: ivarAttributePrefixStart ?? child.startIndex,
+                endIndex: child.endIndex,
+                groupable: groupFields && FIELD_LIKE_MEMBER_TYPES.has(child.type),
+            });
+            ivarAttributePrefixStart = undefined;
+        }
+        const firstMember = members[firstMemberIndex];
+        if (includeNodePrefixOnFirstMember && firstMember) {
+            firstMember.startIndex = node.startIndex;
+            if (node.type === 'instance_variables') {
+                members[members.length - 1].endIndex = node.endIndex;
+            }
+        }
+    };
+    collectMembers(bodyNode, DIRECT_MEMBER_DECLARATION_TYPES.has(bodyNode.type));
     if (members.length === 0)
         return [];
     const grouped = [];

package/dist/core/embeddings/embedding-pipeline.d.ts

@@ -28,7 +28,7 @@ export declare const resolveEmbeddingInstallPolicy: () => ExtensionInstallPolicy
  * invalidate existing vectors, such as metadata/header shape changes,
  * structural container context changes, or preceding-context formatting rules.
  */
-export declare const EMBEDDING_TEXT_VERSION = "v4";
+export declare const EMBEDDING_TEXT_VERSION = "v5";
 /**
  * Compute a stable content fingerprint for an embeddable node.
  * Used to detect when the underlying text has changed so stale vectors

package/dist/core/embeddings/embedding-pipeline.js

@@ -53,7 +53,7 @@ const ensureVectorExtensionAvailable = async () => {
  * invalidate existing vectors, such as metadata/header shape changes,
  * structural container context changes, or preceding-context formatting rules.
  */
-export const EMBEDDING_TEXT_VERSION = 'v4';
+export const EMBEDDING_TEXT_VERSION = 'v5';
 /**
  * Compute a stable content fingerprint for an embeddable node.
  * Used to detect when the underlying text has changed so stale vectors

package/dist/core/embeddings/structural-extractor.js

@@ -4,7 +4,7 @@
  * Reuses ingestion pipeline's AST-based MethodExtractor / FieldExtractor
  * to extract method and field names for embedding text generation.
  */
-import { getProviderForFile } from '../ingestion/languages/index.js';
+import { getProviderForFileContent } from '../ingestion/languages/index.js';
 import { buildTypeEnv } from '../ingestion/type-env.js';
 import { ensureAndParse, findDeclarationNode } from './ast-utils.js';
 const NOOP_SYMBOL_TABLE = {
@@ -17,7 +17,7 @@ const NOOP_SYMBOL_TABLE = {
  * using the ingestion pipeline's AST extractors.
  */
 export const extractStructuralNames = async (content, filePath) => {
-    const provider = getProviderForFile(filePath);
+    const provider = getProviderForFileContent(filePath, content);
     if (!provider)
         return { methodNames: [], fieldNames: [] };
     const tree = await ensureAndParse(content, filePath);

package/dist/core/embeddings/types.d.ts

@@ -7,6 +7,8 @@ export declare const LABEL_FUNCTION: "Function";
 export declare const LABEL_METHOD: "Method";
 export declare const LABEL_CONSTRUCTOR: "Constructor";
 export declare const LABEL_CLASS: "Class";
+export declare const LABEL_PROTOCOL: "Protocol";
+export declare const LABEL_CATEGORY: "Category";
 export declare const LABEL_INTERFACE: "Interface";
 export declare const LABEL_STRUCT: "Struct";
 export declare const LABEL_ENUM: "Enum";
@@ -38,7 +40,7 @@ export interface ChunkingRule {
 /**
  * Node labels that need chunking (have code body, potentially long)
  */
-export declare const CHUNKABLE_LABELS: readonly ["Function", "Method", "Constructor", "Class", "Interface", "Struct", "Enum", "Trait", "Impl", "Macro", "Namespace"];
+export declare const CHUNKABLE_LABELS: readonly ["Function", "Method", "Constructor", "Class", "Protocol", "Category", "Interface", "Struct", "Enum", "Trait", "Impl", "Macro", "Namespace"];
 /**
  * Node labels that are short (no chunking needed, embed directly)
  */
@@ -46,7 +48,7 @@ export declare const SHORT_LABELS: readonly ["TypeAlias", "Typedef", "Const", "P
 /**
  * All embeddable labels (union of CHUNKABLE + SHORT)
  */
-export declare const EMBEDDABLE_LABELS: readonly ["Function", "Method", "Constructor", "Class", "Interface", "Struct", "Enum", "Trait", "Impl", "Macro", "Namespace", "TypeAlias", "Typedef", "Const", "Property", "Record", "Union", "Static", "Variable"];
+export declare const EMBEDDABLE_LABELS: readonly ["Function", "Method", "Constructor", "Class", "Protocol", "Category", "Interface", "Struct", "Enum", "Trait", "Impl", "Macro", "Namespace", "TypeAlias", "Typedef", "Const", "Property", "Record", "Union", "Static", "Variable"];
 export type EmbeddableLabel = (typeof EMBEDDABLE_LABELS)[number];
 /**
  * Check if a label should be embedded

package/dist/core/embeddings/types.js

@@ -7,6 +7,8 @@ export const LABEL_FUNCTION = 'Function';
 export const LABEL_METHOD = 'Method';
 export const LABEL_CONSTRUCTOR = 'Constructor';
 export const LABEL_CLASS = 'Class';
+export const LABEL_PROTOCOL = 'Protocol';
+export const LABEL_CATEGORY = 'Category';
 export const LABEL_INTERFACE = 'Interface';
 export const LABEL_STRUCT = 'Struct';
 export const LABEL_ENUM = 'Enum';
@@ -38,6 +40,8 @@ export const CHUNKABLE_LABELS = [
     LABEL_METHOD,
     LABEL_CONSTRUCTOR,
     LABEL_CLASS,
+    LABEL_PROTOCOL,
+    LABEL_CATEGORY,
     LABEL_INTERFACE,
     LABEL_STRUCT,
     LABEL_ENUM,
@@ -131,6 +135,20 @@ export const CHUNKING_RULES = {
         groupFields: false,
         structuralTextMode: STRUCTURAL_TEXT_MODE_DECLARATION,
     },
+    [LABEL_PROTOCOL]: {
+        mode: CHUNK_MODE_AST_DECLARATION,
+        includePrefix: true,
+        includeSuffix: false,
+        groupFields: false,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_NONE,
+    },
+    [LABEL_CATEGORY]: {
+        mode: CHUNK_MODE_AST_DECLARATION,
+        includePrefix: true,
+        includeSuffix: false,
+        groupFields: true,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_NONE,
+    },
     [LABEL_STRUCT]: {
         mode: CHUNK_MODE_AST_DECLARATION,
         includePrefix: true,

package/dist/core/git-ref.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Git ref-name validation used by both the CLI and the HTTP analyze route.
+ *
+ * Lives in `core/` so `server/api.ts` does not import `cli/analyze-config`
+ * (that import closed a cli → server → cli cycle: `cli/serve.ts` already
+ * imports `createServer`). The CLI keeps a thin wrapper that rethrows
+ * {@link InvalidBranchError} as `GitNexusRcError`.
+ */
+/**
+ * Thrown when a user-supplied branch name fails {@link validateBranchName}.
+ * Callers at a product boundary map this to their own error type (CLI:
+ * `GitNexusRcError`; HTTP: 400).
+ */
+export declare class InvalidBranchError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate a user-supplied branch name. Returns the trimmed name or throws
+ * {@link InvalidBranchError}. Conservative but accepts the shapes real
+ * branches use (`feature/foo-bar`, `release/1.2`, `develop`).
+ */
+export declare function validateBranchName(value: string, source: string): string;

package/dist/core/git-ref.js

@@ -0,0 +1,114 @@
+/**
+ * Git ref-name validation used by both the CLI and the HTTP analyze route.
+ *
+ * Lives in `core/` so `server/api.ts` does not import `cli/analyze-config`
+ * (that import closed a cli → server → cli cycle: `cli/serve.ts` already
+ * imports `createServer`). The CLI keeps a thin wrapper that rethrows
+ * {@link InvalidBranchError} as `GitNexusRcError`.
+ */
+/** Git refs longer than this are almost certainly a mistake / injection attempt. */
+const BRANCH_MAX_LENGTH = 255;
+/**
+ * Thrown when a user-supplied branch name fails {@link validateBranchName}.
+ * Callers at a product boundary map this to their own error type (CLI:
+ * `GitNexusRcError`; HTTP: 400).
+ */
+export class InvalidBranchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidBranchError';
+    }
+}
+/**
+ * Reject control characters and hidden / bidirectional Unicode in a string
+ * value. These have no legitimate place in a branch name and would otherwise
+ * let a committed config or HTTP body smuggle invisible controls into
+ * generated AGENTS.md / CLAUDE.md content.
+ */
+const isHiddenOrControl = (codePoint) => codePoint < 0x20 ||
+    codePoint === 0x7f ||
+    (codePoint >= 0x200b && codePoint <= 0x200f) || // zero-width + LRM/RLM
+    (codePoint >= 0x202a && codePoint <= 0x202e) || // bidi embeddings/overrides
+    (codePoint >= 0x2060 && codePoint <= 0x2064) || // word-joiner + invisible math
+    (codePoint >= 0x2066 && codePoint <= 0x206f) || // bidi isolates + deprecated
+    codePoint === 0xfeff; // BOM / zero-width no-break space
+const assertNoHiddenChars = (value, source) => {
+    for (const ch of value) {
+        const cp = ch.codePointAt(0);
+        if (cp !== undefined && isHiddenOrControl(cp)) {
+            throw new InvalidBranchError(`${source}: value contains control or hidden/bidirectional characters, which are not allowed.`);
+        }
+    }
+};
+/**
+ * Validate a user-supplied branch name. Returns the trimmed name or throws
+ * {@link InvalidBranchError}. Conservative but accepts the shapes real
+ * branches use (`feature/foo-bar`, `release/1.2`, `develop`).
+ */
+export function validateBranchName(value, source) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new InvalidBranchError(`${source}: branch name must not be empty.`);
+    }
+    if (trimmed.length > BRANCH_MAX_LENGTH) {
+        throw new InvalidBranchError(`${source}: branch name is too long (max ${BRANCH_MAX_LENGTH}).`);
+    }
+    assertNoHiddenChars(trimmed, source);
+    if (/\s/.test(trimmed)) {
+        throw new InvalidBranchError(`${source}: branch name must not contain whitespace.`);
+    }
+    // git ref-name rules (subset): reject characters git itself forbids in refs.
+    if (/[~^:?*[\\]/.test(trimmed)) {
+        throw new InvalidBranchError(`${source}: branch name contains characters not allowed in a git ref (~ ^ : ? * [ \\).`);
+    }
+    if (trimmed.startsWith('-')) {
+        throw new InvalidBranchError(`${source}: branch name must not start with "-".`);
+    }
+    // Force-refspec prefix (`git fetch origin +main` / `+refs/heads/main:…`).
+    // Rejected here so neither the CLI nor HTTP can pass a force-update refspec
+    // through as a "branch" (#3199 review, defense in depth).
+    if (trimmed.startsWith('+')) {
+        throw new InvalidBranchError(`${source}: branch name must not start with "+".`);
+    }
+    // The symbolic ref HEAD (case-sensitive). A repo can have a branch named
+    // `head`; git itself treats only `HEAD` as the current-commit alias.
+    if (trimmed === 'HEAD') {
+        throw new InvalidBranchError(`${source}: branch name must not be "HEAD".`);
+    }
+    if (trimmed.includes('..')) {
+        throw new InvalidBranchError(`${source}: branch name must not contain "..".`);
+    }
+    // The remaining `git check-ref-format` rules. Without these the validator
+    // accepted refs git itself refuses (`feature.lock`, `/feature`, `feature/`,
+    // `feature//next`, `@`, `.hidden`), so the failure surfaced later from the
+    // git subprocess instead of here. No real branch can violate them — git
+    // could not have created one — so nothing that works today starts failing.
+    if (trimmed.endsWith('.lock') || trimmed.split('/').some((part) => part.endsWith('.lock'))) {
+        throw new InvalidBranchError(`${source}: branch name must not end with ".lock".`);
+    }
+    if (trimmed.startsWith('/') || trimmed.endsWith('/')) {
+        throw new InvalidBranchError(`${source}: branch name must not start or end with "/".`);
+    }
+    if (trimmed.includes('//')) {
+        throw new InvalidBranchError(`${source}: branch name must not contain consecutive slashes.`);
+    }
+    if (trimmed === '@') {
+        throw new InvalidBranchError(`${source}: branch name must not be the single character "@".`);
+    }
+    if (trimmed.includes('@{')) {
+        throw new InvalidBranchError(`${source}: branch name must not contain "@{".`);
+    }
+    if (trimmed.endsWith('.') || trimmed.split('/').some((part) => part.startsWith('.'))) {
+        throw new InvalidBranchError(`${source}: branch name must not end with "." or have a path component starting with ".".`);
+    }
+    // Git permits a backtick in a ref, but the branch is embedded inside a
+    // Markdown inline-code span in the generated AGENTS.md/CLAUDE.md regression
+    // example, where a backtick would close the span early and let the rest of
+    // the template render as instruction text. Reject it at this single
+    // chokepoint so all three tiers (CLI flag, .gitnexusrc, auto-detect via
+    // sanitizeDetectedBranch) are covered (#1996 tri-review P1).
+    if (trimmed.includes('`')) {
+        throw new InvalidBranchError(`${source}: branch name must not contain a backtick (it would break the generated Markdown).`);
+    }
+    return trimmed;
+}

package/dist/core/git-staleness.js

@@ -8,6 +8,12 @@ import path from 'path';
 import { readRegistry } from '../storage/repo-manager.js';
 import { findGitRootByDotGit, getCurrentCommit, getRemoteUrl } from '../storage/git.js';
 const execFileAsync = promisify(execFile);
+/**
+ * Ceiling for one `git rev-list` staleness probe. Generous for the local
+ * history walk this is, and short enough that an unresponsive working tree
+ * degrades to "not stale" quickly rather than holding a request open.
+ */
+const STALENESS_TIMEOUT_MS = 5_000;
 /**
  * Check how many commits the index is behind HEAD (synchronous; uses git CLI).
  */
@@ -46,6 +52,14 @@ export async function checkStalenessAsync(repoPath, lastCommit) {
             cwd: repoPath,
             encoding: 'utf-8',
             windowsHide: true,
+            // The catch below fails closed on every git ERROR, but a hang is not an
+            // error — it is silence, and without a bound this await never settles.
+            // A working tree on a disconnected network mount or behind a stuck lock
+            // does exactly that, and `/api/repos` fans this out once per registered
+            // repo, so one unreachable mount could hold the whole listing open
+            // (#3232 review). The timeout kills the child and rejects, which routes
+            // a hang into the same fail-closed "not stale" answer as a bad SHA.
+            timeout: STALENESS_TIMEOUT_MS,
         });
         const commitsBehind = parseInt(stdout.trim(), 10) || 0;
         if (commitsBehind > 0) {

package/dist/core/group/extractors/graphql-extractor.d.ts

@@ -5,7 +5,7 @@ type GraphqlOperationKind = 'query' | 'mutation' | 'subscription';
 type GeneratedSymbolIndex = Map<string, Parser.SyntaxNode[]>;
 export declare const RESOLVE_METHOD_QUERY = "\nMATCH (n)\nWHERE labels(n) IN ['Method','Function','Property','CodeElement']\n  AND n.name = $name AND n.filePath = $filePath AND n.startLine = $startLine AND n.id <> ''\nRETURN n.id AS uid, n.name AS name, n.filePath AS filePath\nORDER BY n.id ASC\nLIMIT 2";
 export declare const RESOLVE_GENERATED_SYMBOL_QUERY = "\nMATCH (n)\nWHERE labels(n) IN ['Const','Variable','Function','Method','CodeElement']\n  AND n.name = $name AND n.filePath <> '' AND n.id <> ''\nRETURN n.id AS uid, n.name AS name, n.filePath AS filePath\nORDER BY n.id ASC\nLIMIT 2";
-export declare function hasGeneratedDocumentProof(initializer: Parser.SyntaxNode, operationKind: GraphqlOperationKind, operationName: string, requiredFields: readonly string[]): boolean;
+export declare function hasGeneratedDocumentProof(initializer: Parser.SyntaxNode, operationKind: GraphqlOperationKind, operationName: string, requiredFields: readonly string[], declarators?: GeneratedSymbolIndex): boolean;
 export declare function indexGeneratedDeclarators(root: Parser.SyntaxNode): GeneratedSymbolIndex;
 export declare class GraphqlExtractor implements ContractExtractor {
     type: "graphql";

package/dist/core/group/extractors/graphql-extractor.js

@@ -58,6 +58,130 @@ function unquote(text) {
     const value = trimmed.slice(1, -1);
     return value.includes('${') ? null : value;
 }
+const SIMPLE_TEMPLATE_ESCAPES = {
+    b: '\b',
+    f: '\f',
+    n: '\n',
+    r: '\r',
+    t: '\t',
+    v: '\v',
+    '0': '\0',
+    "'": "'",
+    '"': '"',
+    '\\': '\\',
+    '`': '`',
+};
+/** Graph Method `startLine` is the 0-based wrapper row (see line-base.ts). */
+function providerMemberStartLine(member) {
+    // Class-field arrows are `@declaration.property`; parse-worker falls back to
+    // the `public_field_definition` wrapper (decorator row when it is a child),
+    // not the initializer. Do not probe the `value` child.
+    return member.startPosition.row;
+}
+/** tree-sitter `escape_sequence.text` is the source spelling (`\\n`), not the JS value. */
+function decodeEscapeSequence(text) {
+    if (!text.startsWith('\\') || text.length < 2)
+        return null;
+    const escaped = text.slice(1);
+    // Tagged-template cooked value: LineContinuation is empty; `\8`/`\9` and
+    // LegacyOctalEscapeSequence (`\1`–`\7`, `\00`…) make cooked undefined.
+    if (/^[\n\r\u2028\u2029]$/.test(escaped) || escaped === '\r\n')
+        return '';
+    if (/^[1-9]$/.test(escaped) || /^[0-7]{2,3}$/.test(escaped))
+        return null;
+    if (escaped.length === 1)
+        return SIMPLE_TEMPLATE_ESCAPES[escaped] ?? escaped;
+    if (escaped[0] === 'x' && /^[0-9A-Fa-f]{2}$/.test(escaped.slice(1))) {
+        return String.fromCharCode(Number.parseInt(escaped.slice(1), 16));
+    }
+    if (escaped.startsWith('u{') && escaped.endsWith('}')) {
+        const hex = escaped.slice(2, -1);
+        if (!/^[0-9A-Fa-f]{1,6}$/.test(hex))
+            return null;
+        const codePoint = Number.parseInt(hex, 16);
+        if (codePoint > 0x10ffff)
+            return null;
+        return String.fromCodePoint(codePoint);
+    }
+    if (escaped[0] === 'u' && /^[0-9A-Fa-f]{4}$/.test(escaped.slice(1))) {
+        return String.fromCharCode(Number.parseInt(escaped.slice(1), 16));
+    }
+    return null;
+}
+function substitutionIdentifier(substitution) {
+    if (substitution.namedChildren.length !== 1)
+        return null;
+    const expr = unwrapExpression(substitution.namedChildren[0]);
+    return expr.type === 'identifier' ? expr.text : null;
+}
+function isGraphqlTagCall(call) {
+    const callee = call.childForFieldName('function');
+    return callee?.type === 'identifier' && callee.text === 'gql';
+}
+function pascalCaseGraphqlName(name) {
+    return name
+        .split(/[^A-Za-z0-9]+/)
+        .filter((part) => part.length > 0)
+        .map((part) => `${part[0].toUpperCase()}${part.slice(1)}`)
+        .join('');
+}
+function uniqueStaticSource(name, declarators, resolving, cache) {
+    if (cache.has(name))
+        return cache.get(name) ?? null;
+    if (resolving.has(name) || resolving.size >= MAX_GRAPHQL_TRAVERSAL_DEPTH)
+        return null;
+    const values = declarators.get(name) ?? [];
+    if (values.length === 0) {
+        cache.set(name, null);
+        return null;
+    }
+    resolving.add(name);
+    const sources = new Set();
+    for (const value of values) {
+        const source = staticGraphqlSource(value, declarators, resolving, cache);
+        // A dynamic or unprovable sibling makes the name ambiguous — do not pick
+        // the one static spelling and ignore the rest.
+        if (source === null) {
+            resolving.delete(name);
+            cache.set(name, null);
+            return null;
+        }
+        sources.add(source);
+    }
+    resolving.delete(name);
+    const unique = sources.size === 1 ? [...sources][0] : null;
+    cache.set(name, unique);
+    return unique;
+}
+function interpolatedTemplateSource(template, declarators, resolving, cache) {
+    let out = '';
+    for (const child of template.namedChildren) {
+        if (child.type === 'string_fragment') {
+            out += child.text;
+        }
+        else if (child.type === 'escape_sequence') {
+            const decoded = decodeEscapeSequence(child.text);
+            if (decoded === null)
+                return null;
+            out += decoded;
+        }
+        else if (child.type === 'template_substitution') {
+            const name = substitutionIdentifier(child);
+            if (!name)
+                return null;
+            const inlined = uniqueStaticSource(name, declarators, resolving, cache);
+            if (inlined === null)
+                return null;
+            out += inlined;
+        }
+        else {
+            return null;
+        }
+        if (out.length > MAX_GRAPHQL_TOKENS)
+            return null;
+    }
+    return out;
+}
 function unwrapExpression(node) {
     let current = node;
     while (['as_expression', 'satisfies_expression', 'parenthesized_expression'].includes(current.type) &&
@@ -183,7 +307,7 @@ function parsedDocumentProof(source, operationKind, operationName, requiredField
     }
     return false;
 }
-function staticGraphqlSource(initializer) {
+function staticGraphqlSource(initializer, declarators, resolving = new Set(), cache = new Map()) {
     const value = unwrapExpression(initializer);
     if (value.type === 'string') {
         if (value.text.startsWith('"')) {
@@ -196,11 +320,22 @@ function staticGraphqlSource(initializer) {
         }
         return unquote(value.text);
     }
-    if (value.type === 'template_string')
-        return unquote(value.text);
+    if (value.type === 'template_string') {
+        const hasSubstitution = value.namedChildren.some((child) => child.type === 'template_substitution');
+        if (!hasSubstitution)
+            return unquote(value.text);
+        return declarators ? interpolatedTemplateSource(value, declarators, resolving, cache) : null;
+    }
     if (value.type === 'call_expression') {
         const template = value.namedChildren.find((child) => child.type === 'template_string');
-        return template ? unquote(template.text) : null;
+        if (!template)
+            return null;
+        const hasSubstitution = template.namedChildren.some((child) => child.type === 'template_substitution');
+        // Interpolated reconstruction is the cooked template. Only `gql` is
+        // treated as preserving that source; String.raw / unknown tags stay fail-closed.
+        if (hasSubstitution && !isGraphqlTagCall(value))
+            return null;
+        return staticGraphqlSource(template, declarators, resolving, cache);
     }
     if (value.type !== 'new_expression')
         return null;
@@ -209,12 +344,12 @@ function staticGraphqlSource(initializer) {
         return null;
     const args = value.childForFieldName('arguments');
     const first = args?.namedChildren[0];
-    return first ? staticGraphqlSource(first) : null;
+    return first ? staticGraphqlSource(first, declarators, resolving, cache) : null;
 }
-export function hasGeneratedDocumentProof(initializer, operationKind, operationName, requiredFields) {
+export function hasGeneratedDocumentProof(initializer, operationKind, operationName, requiredFields, declarators) {
     if (!withinGeneratedAstBudget(initializer))
         return false;
-    const staticSource = staticGraphqlSource(initializer);
+    const staticSource = staticGraphqlSource(initializer, declarators);
     if (staticSource !== null) {
         return parsedDocumentProof(staticSource, operationKind, operationName, requiredFields);
     }
@@ -406,7 +541,11 @@ function rootFields(selectionSet, fragments) {
 }
 function generatedCandidates(operation) {
     const name = operation.name?.value;
-    return name ? [`${name}Document`] : [];
+    if (!name)
+        return [];
+    const exact = `${name}Document`;
+    const pascal = `${pascalCaseGraphqlName(name)}Document`;
+    return exact === pascal ? [exact] : [exact, pascal];
 }
 async function generatedDocumentMatches(repoPath, symbol, operationKind, operationName, requiredFields, cache) {
     const normalizedPath = symbol.filePath.replace(/\\/g, '/');
@@ -417,7 +556,7 @@ async function generatedDocumentMatches(repoPath, symbol, operationKind, operati
     }
     const index = await pendingIndex;
     const values = index?.get(symbol.name) ?? [];
-    return values.some((value) => hasGeneratedDocumentProof(value, operationKind, operationName, requiredFields));
+    return values.some((value) => hasGeneratedDocumentProof(value, operationKind, operationName, requiredFields, index ?? undefined));
 }
 async function buildGeneratedSymbolIndex(repoPath, filePath) {
     const source = await readSafeBounded(repoPath, filePath, getMaxFileSizeBytes());
@@ -551,10 +690,7 @@ export class GraphqlExtractor {
                         const symbol = uniqueRealSymbol(await dbExecutor(RESOLVE_METHOD_QUERY, {
                             name: methodName,
                             filePath,
-                            startLine: member.type === 'public_field_definition'
-                                ? (member.childForFieldName('value')?.startPosition.row ??
-                                    member.startPosition.row) + 1
-                                : member.startPosition.row + 1,
+                            startLine: providerMemberStartLine(member),
                         }));
                         if (!symbol)
                             continue;

package/dist/core/group/extractors/manifest-extractor.d.ts

@@ -4,7 +4,7 @@ export interface ManifestExtractResult {
     contracts: StoredContract[];
     crossLinks: CrossLink[];
 }
-export declare const CUSTOM_CONTRACT_RESOLVE_QUERY = "MATCH (n)\n   WHERE labels(n) IN ['Function','Method','Class','Interface','Struct','Enum','Trait','Constructor','TypeAlias','Impl','Macro','Union','Typedef','Property','Record','Delegate','Annotation','Template','Const','Static','CodeElement']\n     AND n.name = $symbolName\n   RETURN n.id AS uid, n.name AS name, n.filePath AS filePath\n   ORDER BY n.filePath ASC, n.id ASC\n   LIMIT 1";
+export declare const CUSTOM_CONTRACT_RESOLVE_QUERY = "MATCH (n)\n   WHERE labels(n) IN ['Function','Method','Class','Protocol','Category','Interface','Struct','Enum','Trait','Constructor','TypeAlias','Impl','Macro','Union','Typedef','Property','Record','Delegate','Annotation','Template','Const','Static','CodeElement']\n     AND n.name = $symbolName\n   RETURN n.id AS uid, n.name AS name, n.filePath AS filePath\n   ORDER BY n.filePath ASC, n.id ASC\n   LIMIT 1";
 /**
  * Stable synthetic symbolUid for a manifest-declared contract whose target
  * symbol could not be resolved against the per-repo graph (resolveSymbol

package/dist/core/group/extractors/manifest-extractor.js

@@ -3,7 +3,7 @@ import { logger } from '../../logger.js';
 // #2325 integration test can run the EXACT production query against a real
 // LadybugDB — a hand-copied query string in the test would silently drift
 // from this allowlist. Uses the `labels(n) IN [...]` allowlist form rather
-// than a `MATCH (n:A|B)` disjunction: this 21-label list contains the
+// than a `MATCH (n:A|B)` disjunction: this 23-label list contains the
 // reserved-keyword labels `Macro` and `Union`, and LadybugDB's parser rejects
 // a disjunction that names a reserved keyword (#2325) — which the resolver's
 // try/catch then swallowed. `labels(n) IN` has no such collision.
@@ -12,7 +12,7 @@ import { logger } from '../../logger.js';
 // two would widen which nodes resolve as contract symbols and must update the
 // #2325 test, so they are intentionally kept separate for now.
 export const CUSTOM_CONTRACT_RESOLVE_QUERY = `MATCH (n)
-   WHERE labels(n) IN ['Function','Method','Class','Interface','Struct','Enum','Trait','Constructor','TypeAlias','Impl','Macro','Union','Typedef','Property','Record','Delegate','Annotation','Template','Const','Static','CodeElement']
+   WHERE labels(n) IN ['Function','Method','Class','Protocol','Category','Interface','Struct','Enum','Trait','Constructor','TypeAlias','Impl','Macro','Union','Typedef','Property','Record','Delegate','Annotation','Template','Const','Static','CodeElement']
      AND n.name = $symbolName
    RETURN n.id AS uid, n.name AS name, n.filePath AS filePath
    ORDER BY n.filePath ASC, n.id ASC