gitnexus 1.5.3 → 1.6.1

package/dist/core/group/extractors/topic-patterns/node.js

@@ -0,0 +1,155 @@
+import JavaScript from 'tree-sitter-javascript';
+import TypeScript from 'tree-sitter-typescript';
+import { compilePatterns, } from '../tree-sitter-scanner.js';
+/**
+ * Node.js / TypeScript topic extraction patterns.
+ *
+ * Detects kafkajs, amqplib (RabbitMQ), and nats.js producer/consumer APIs:
+ *   - `producer.send({ topic: 'xxx', ... })` (kafkajs)
+ *   - `consumer.subscribe({ topic: 'xxx', ... })` (kafkajs)
+ *   - `channel.consume("queue", ...)` / `channel.publish(...)` / `channel.sendToQueue(...)`
+ *   - `nc.subscribe("topic")` / `js.subscribe("topic")`
+ *   - `nc.publish("topic", ...)` / `js.publish("topic", ...)`
+ *
+ * The JavaScript and TypeScript tree-sitter grammars share node type
+ * names for every construct we query here, so the pattern sources are
+ * defined once and compiled against each grammar variant. We export three
+ * providers because Parser.Query objects are NOT portable across grammar
+ * instances — `.js` files use the JavaScript grammar, `.ts` uses
+ * TypeScript.typescript, and `.tsx` uses TypeScript.tsx.
+ *
+ * Every query MUST bind `@value` to the topic literal node.
+ */
+const NODE_TOPIC_PATTERNS = [
+    {
+        meta: {
+            role: 'provider',
+            broker: 'kafka',
+            confidence: 0.8,
+            symbolName: 'producer.send',
+        },
+        query: `
+      (call_expression
+        function: (member_expression
+          object: (identifier) @obj (#eq? @obj "producer")
+          property: (property_identifier) @prop (#eq? @prop "send"))
+        arguments: (arguments
+          (object
+            (pair
+              key: (property_identifier) @key (#eq? @key "topic")
+              value: [(string) (template_string)] @value))))
+    `,
+    },
+    {
+        meta: {
+            role: 'consumer',
+            broker: 'kafka',
+            confidence: 0.8,
+            symbolName: 'consumer.subscribe',
+        },
+        query: `
+      (call_expression
+        function: (member_expression
+          object: (identifier) @obj (#eq? @obj "consumer")
+          property: (property_identifier) @prop (#eq? @prop "subscribe"))
+        arguments: (arguments
+          (object
+            (pair
+              key: (property_identifier) @key (#eq? @key "topic")
+              value: [(string) (template_string)] @value))))
+    `,
+    },
+    {
+        meta: {
+            role: 'consumer',
+            broker: 'rabbitmq',
+            confidence: 0.8,
+            symbolName: 'channel.consume',
+        },
+        query: `
+      (call_expression
+        function: (member_expression
+          object: (identifier) @obj (#eq? @obj "channel")
+          property: (property_identifier) @prop (#eq? @prop "consume"))
+        arguments: (arguments . [(string) (template_string)] @value))
+    `,
+    },
+    {
+        meta: {
+            role: 'provider',
+            broker: 'rabbitmq',
+            confidence: 0.8,
+            symbolName: 'channel.publish',
+        },
+        query: `
+      (call_expression
+        function: (member_expression
+          object: (identifier) @obj (#eq? @obj "channel")
+          property: (property_identifier) @prop (#eq? @prop "publish"))
+        arguments: (arguments . [(string) (template_string)] @value))
+    `,
+    },
+    {
+        meta: {
+            role: 'provider',
+            broker: 'rabbitmq',
+            confidence: 0.8,
+            symbolName: 'channel.sendToQueue',
+        },
+        query: `
+      (call_expression
+        function: (member_expression
+          object: (identifier) @obj (#eq? @obj "channel")
+          property: (property_identifier) @prop (#eq? @prop "sendToQueue"))
+        arguments: (arguments . [(string) (template_string)] @value))
+    `,
+    },
+    {
+        meta: {
+            role: 'consumer',
+            broker: 'nats',
+            confidence: 0.8,
+            symbolName: 'nc.subscribe',
+        },
+        query: `
+      (call_expression
+        function: (member_expression
+          object: (identifier) @obj (#match? @obj "^(nc|js)$")
+          property: (property_identifier) @prop (#match? @prop "^[Ss]ubscribe$"))
+        arguments: (arguments . [(string) (template_string)] @value))
+    `,
+    },
+    {
+        meta: {
+            role: 'provider',
+            broker: 'nats',
+            confidence: 0.8,
+            symbolName: 'nc.publish',
+        },
+        query: `
+      (call_expression
+        function: (member_expression
+          object: (identifier) @obj (#match? @obj "^(nc|js)$")
+          property: (property_identifier) @prop (#match? @prop "^[Pp]ublish$"))
+        arguments: (arguments . [(string) (template_string)] @value))
+    `,
+    },
+];
+const JAVASCRIPT_TOPIC_SPEC = {
+    name: 'javascript-topic',
+    language: JavaScript,
+    patterns: NODE_TOPIC_PATTERNS,
+};
+const TYPESCRIPT_TOPIC_SPEC = {
+    name: 'typescript-topic',
+    language: TypeScript.typescript,
+    patterns: NODE_TOPIC_PATTERNS,
+};
+const TSX_TOPIC_SPEC = {
+    name: 'tsx-topic',
+    language: TypeScript.tsx,
+    patterns: NODE_TOPIC_PATTERNS,
+};
+export const JAVASCRIPT_TOPIC_PROVIDER = compilePatterns(JAVASCRIPT_TOPIC_SPEC);
+export const TYPESCRIPT_TOPIC_PROVIDER = compilePatterns(TYPESCRIPT_TOPIC_SPEC);
+export const TSX_TOPIC_PROVIDER = compilePatterns(TSX_TOPIC_SPEC);

package/dist/core/group/extractors/topic-patterns/python.d.ts

@@ -0,0 +1,2 @@
+import type { TopicMeta } from './types.js';
+export declare const PYTHON_TOPIC_PROVIDER: import("../tree-sitter-scanner.js").CompiledPatterns<TopicMeta>;

package/dist/core/group/extractors/topic-patterns/python.js

@@ -0,0 +1,116 @@
+import Python from 'tree-sitter-python';
+import { compilePatterns } from '../tree-sitter-scanner.js';
+/**
+ * Python topic extraction patterns.
+ *
+ * Detects kafka-python, pika (RabbitMQ), and nats-py producer/consumer APIs:
+ *   - `KafkaConsumer('topic', ...)`
+ *   - `producer.send('topic', ...)` / `producer.produce('topic', ...)`
+ *   - `channel.basic_consume(queue='xxx', ...)`
+ *   - `channel.basic_publish(exchange='xxx', ...)`
+ *   - `await nc.subscribe('topic')`
+ *   - `await nc.publish('topic', ...)`
+ *
+ * Every query MUST bind `@value` to the topic literal node.
+ */
+const PYTHON_TOPIC_SPEC = {
+    name: 'python-topic',
+    language: Python,
+    patterns: [
+        {
+            meta: {
+                role: 'consumer',
+                broker: 'kafka',
+                confidence: 0.7,
+                symbolName: 'KafkaConsumer',
+            },
+            query: `
+        (call
+          function: (identifier) @func (#eq? @func "KafkaConsumer")
+          arguments: (argument_list . (string) @value))
+      `,
+        },
+        {
+            meta: {
+                role: 'provider',
+                broker: 'kafka',
+                confidence: 0.7,
+                symbolName: 'producer.send',
+            },
+            query: `
+        (call
+          function: (attribute
+            object: (identifier) @obj (#eq? @obj "producer")
+            attribute: (identifier) @method (#match? @method "^(send|produce)$"))
+          arguments: (argument_list . (string) @value))
+      `,
+        },
+        {
+            meta: {
+                role: 'consumer',
+                broker: 'rabbitmq',
+                confidence: 0.7,
+                symbolName: 'basic_consume',
+            },
+            query: `
+        (call
+          function: (attribute
+            object: (identifier) @obj (#eq? @obj "channel")
+            attribute: (identifier) @method (#eq? @method "basic_consume"))
+          arguments: (argument_list
+            (keyword_argument
+              name: (identifier) @kw (#eq? @kw "queue")
+              value: (string) @value)))
+      `,
+        },
+        {
+            meta: {
+                role: 'provider',
+                broker: 'rabbitmq',
+                confidence: 0.7,
+                symbolName: 'basic_publish',
+            },
+            query: `
+        (call
+          function: (attribute
+            object: (identifier) @obj (#eq? @obj "channel")
+            attribute: (identifier) @method (#eq? @method "basic_publish"))
+          arguments: (argument_list
+            (keyword_argument
+              name: (identifier) @kw (#eq? @kw "exchange")
+              value: (string) @value)))
+      `,
+        },
+        {
+            meta: {
+                role: 'consumer',
+                broker: 'nats',
+                confidence: 0.75,
+                symbolName: 'nc.subscribe',
+            },
+            query: `
+        (call
+          function: (attribute
+            object: (identifier) @obj (#eq? @obj "nc")
+            attribute: (identifier) @method (#eq? @method "subscribe"))
+          arguments: (argument_list . (string) @value))
+      `,
+        },
+        {
+            meta: {
+                role: 'provider',
+                broker: 'nats',
+                confidence: 0.75,
+                symbolName: 'nc.publish',
+            },
+            query: `
+        (call
+          function: (attribute
+            object: (identifier) @obj (#eq? @obj "nc")
+            attribute: (identifier) @method (#eq? @method "publish"))
+          arguments: (argument_list . (string) @value))
+      `,
+        },
+    ],
+};
+export const PYTHON_TOPIC_PROVIDER = compilePatterns(PYTHON_TOPIC_SPEC);

package/dist/core/group/extractors/topic-patterns/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared types for the topic-extractor language plugins.
+ *
+ * Each plugin lives in its own file (java.ts, go.ts, ...) and owns the
+ * tree-sitter grammar import + query sources. The top-level
+ * `topic-extractor.ts` orchestrator only knows about this type module and
+ * the plugin registry (`./index.ts`). It MUST NOT import any grammar or
+ * query text directly — that's the whole point of the split.
+ */
+export type Broker = 'kafka' | 'rabbitmq' | 'nats';
+/**
+ * Per-pattern payload every topic plugin attaches to its query. Whatever
+ * the pattern matches, the orchestrator receives this object verbatim
+ * and uses it to build an `ExtractedContract`.
+ *
+ * Plugins produce one `TopicMeta` per pattern (not per match) because a
+ * single query uniquely identifies its broker/role/confidence triple.
+ */
+export interface TopicMeta {
+    role: 'provider' | 'consumer';
+    broker: Broker;
+    confidence: number;
+    /** Short human-readable label of the API being detected. */
+    symbolName: string;
+}

package/dist/core/group/extractors/topic-patterns/types.js

@@ -0,0 +1,10 @@
+/**
+ * Shared types for the topic-extractor language plugins.
+ *
+ * Each plugin lives in its own file (java.ts, go.ts, ...) and owns the
+ * tree-sitter grammar import + query sources. The top-level
+ * `topic-extractor.ts` orchestrator only knows about this type module and
+ * the plugin registry (`./index.ts`). It MUST NOT import any grammar or
+ * query text directly — that's the whole point of the split.
+ */
+export {};

package/dist/core/group/extractors/tree-sitter-scanner.d.ts

@@ -0,0 +1,113 @@
+import Parser from 'tree-sitter';
+/**
+ * Shared, language-agnostic tree-sitter scanning utilities used by group
+ * extractors (topic, http, grpc, ...).
+ *
+ * Design goals:
+ *  - The top-level extractors must not import any tree-sitter grammar.
+ *  - Per-language plugins own their grammar import, their query sources,
+ *    and the mapping from capture → meta.
+ *  - This module provides the plumbing: compile queries once per plugin,
+ *    parse a file with a given grammar, run all patterns, and return the
+ *    captured `string_literal`-style nodes together with the plugin's meta.
+ */
+/**
+ * One pattern owned by a language plugin. Each pattern owns a tree-sitter
+ * S-expression query. Plugins can freely choose which capture names to
+ * use — the scanner exposes every capture in the returned `captures`
+ * map and does not privilege any particular name.
+ *
+ * `TMeta` is the plugin-specific payload the orchestrator receives back
+ * when this pattern matches — e.g. for topic extraction it carries the
+ * broker name, role, confidence, symbol name.
+ */
+export interface PatternSpec<TMeta> {
+    /** Tree-sitter S-expression. */
+    query: string;
+    /** Plugin-specific payload returned on every match. */
+    meta: TMeta;
+}
+/**
+ * A set of patterns owned by one language plugin, bound to a specific
+ * tree-sitter grammar.
+ *
+ * `language` is typed as `unknown` because tree-sitter's TypeScript
+ * declarations use `any` for the grammar object, and the grammar modules
+ * export different shapes (plain grammar vs. namespace with `typescript`
+ * / `tsx` members). Callers pass the concrete grammar object; this
+ * module forwards it to `parser.setLanguage` / `new Parser.Query`.
+ */
+export interface LanguagePatterns<TMeta> {
+    /** Human-readable plugin name for diagnostics. */
+    name: string;
+    /** tree-sitter grammar object. */
+    language: unknown;
+    /** Patterns authored against `language`. */
+    patterns: PatternSpec<TMeta>[];
+}
+/**
+ * Compiled form of a `LanguagePatterns` bundle. Queries are compiled
+ * eagerly at module load time so a broken grammar/query pair fails
+ * loudly the first time the plugin is imported, instead of silently
+ * at scan time when no contract is produced.
+ */
+export interface CompiledPatterns<TMeta> {
+    name: string;
+    language: unknown;
+    patterns: CompiledPattern<TMeta>[];
+}
+export interface CompiledPattern<TMeta> {
+    query: Parser.Query;
+    meta: TMeta;
+}
+/**
+ * Map from capture name → syntax node. Every named capture the query
+ * binds is exposed as an entry. If a query captures the same name more
+ * than once (unusual), the first occurrence wins — plugins that need
+ * all occurrences should use distinct capture names or fall back to
+ * `match.captures` array directly by iterating `query.matches()`
+ * themselves.
+ */
+export type CaptureMap = Record<string, Parser.SyntaxNode>;
+/**
+ * One match returned by `scanFile` / `runCompiledPatterns`. The caller
+ * receives the full capture map plus the plugin meta, and is
+ * responsible for turning it into a domain object.
+ */
+export interface ScanMatch<TMeta> {
+    meta: TMeta;
+    captures: CaptureMap;
+}
+/**
+ * Compile a LanguagePatterns bundle. Call this once per plugin, at
+ * module load time, and export the result. Throws if any pattern
+ * fails to compile against the grammar — that's a bug in the plugin
+ * author's query, not a runtime condition.
+ */
+export declare function compilePatterns<TMeta>(bundle: LanguagePatterns<TMeta>): CompiledPatterns<TMeta>;
+/**
+ * Run every compiled pattern in `plugin` against an already-parsed
+ * tree. Use this when a plugin needs multiple query bundles against
+ * the same file (e.g. one query for class-level prefixes and another
+ * for method-level annotations) and wants to avoid re-parsing.
+ */
+export declare function runCompiledPatterns<TMeta>(plugin: CompiledPatterns<TMeta>, tree: Parser.Tree): ScanMatch<TMeta>[];
+/**
+ * Parse `content` with the plugin's grammar and run every compiled
+ * pattern against the AST. Returns one `ScanMatch` per matched query
+ * occurrence, carrying the plugin's meta payload.
+ *
+ * Errors are swallowed at the file level (malformed file must not abort
+ * the whole extract). Individual pattern failures are swallowed too so
+ * a single unusable query doesn't block the rest of the plugin.
+ */
+export declare function scanFile<TMeta>(parser: Parser, plugin: CompiledPatterns<TMeta>, content: string): ScanMatch<TMeta>[];
+/**
+ * Strip enclosing quotes from a tree-sitter string literal node's text.
+ * Handles single / double / template quotes, Python triple-quoted strings,
+ * and Go raw string literals (backticks).
+ *
+ * Returns null for empty/nullish input so callers can uniformly skip
+ * captures whose value is missing.
+ */
+export declare function unquoteLiteral(raw: string): string | null;

package/dist/core/group/extractors/tree-sitter-scanner.js

@@ -0,0 +1,94 @@
+import Parser from 'tree-sitter';
+/**
+ * Compile a LanguagePatterns bundle. Call this once per plugin, at
+ * module load time, and export the result. Throws if any pattern
+ * fails to compile against the grammar — that's a bug in the plugin
+ * author's query, not a runtime condition.
+ */
+export function compilePatterns(bundle) {
+    const compiled = [];
+    for (const spec of bundle.patterns) {
+        try {
+            const query = new Parser.Query(bundle.language, spec.query);
+            compiled.push({ query, meta: spec.meta });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`[tree-sitter-scanner] Failed to compile pattern in ${bundle.name}: ${message}\n` +
+                `Query source:\n${spec.query}`);
+        }
+    }
+    return { name: bundle.name, language: bundle.language, patterns: compiled };
+}
+/**
+ * Run every compiled pattern in `plugin` against an already-parsed
+ * tree. Use this when a plugin needs multiple query bundles against
+ * the same file (e.g. one query for class-level prefixes and another
+ * for method-level annotations) and wants to avoid re-parsing.
+ */
+export function runCompiledPatterns(plugin, tree) {
+    const out = [];
+    for (const compiled of plugin.patterns) {
+        let matches;
+        try {
+            matches = compiled.query.matches(tree.rootNode);
+        }
+        catch {
+            continue;
+        }
+        for (const match of matches) {
+            const captures = {};
+            for (const cap of match.captures) {
+                if (!(cap.name in captures))
+                    captures[cap.name] = cap.node;
+            }
+            out.push({ meta: compiled.meta, captures });
+        }
+    }
+    return out;
+}
+/**
+ * Parse `content` with the plugin's grammar and run every compiled
+ * pattern against the AST. Returns one `ScanMatch` per matched query
+ * occurrence, carrying the plugin's meta payload.
+ *
+ * Errors are swallowed at the file level (malformed file must not abort
+ * the whole extract). Individual pattern failures are swallowed too so
+ * a single unusable query doesn't block the rest of the plugin.
+ */
+export function scanFile(parser, plugin, content) {
+    let tree;
+    try {
+        parser.setLanguage(plugin.language);
+        tree = parser.parse(content);
+    }
+    catch {
+        return [];
+    }
+    return runCompiledPatterns(plugin, tree);
+}
+/**
+ * Strip enclosing quotes from a tree-sitter string literal node's text.
+ * Handles single / double / template quotes, Python triple-quoted strings,
+ * and Go raw string literals (backticks).
+ *
+ * Returns null for empty/nullish input so callers can uniformly skip
+ * captures whose value is missing.
+ */
+export function unquoteLiteral(raw) {
+    if (!raw)
+        return null;
+    // Python triple-quoted
+    if ((raw.startsWith('"""') && raw.endsWith('"""')) ||
+        (raw.startsWith("'''") && raw.endsWith("'''"))) {
+        return raw.slice(3, -3);
+    }
+    const first = raw[0];
+    const last = raw[raw.length - 1];
+    if ((first === '"' || first === "'" || first === '`') && last === first && raw.length >= 2) {
+        return raw.slice(1, -1);
+    }
+    // Some grammars expose the string content without quotes already (e.g.
+    // Python `string_content` child). Return as-is.
+    return raw;
+}

package/dist/core/group/matching.d.ts

@@ -0,0 +1,13 @@
+import type { StoredContract, CrossLink } from './types.js';
+export interface MatchResult {
+    matched: CrossLink[];
+    unmatched: StoredContract[];
+}
+export interface WildcardMatchResult {
+    matched: CrossLink[];
+    remaining: StoredContract[];
+}
+export declare function normalizeContractId(id: string): string;
+export declare function buildProviderIndex(contracts: StoredContract[]): Map<string, StoredContract[]>;
+export declare function runExactMatch(contracts: StoredContract[], providerIndex?: Map<string, StoredContract[]>): MatchResult;
+export declare function runWildcardMatch(unmatched: StoredContract[], providerIndex: Map<string, StoredContract[]>): WildcardMatchResult;