spectra-cli 4.1.1 → 4.2.0

package/dist/core/import-resolver.js

@@ -0,0 +1,273 @@
+/**
+ * import-resolver.ts — TS/JS import specifier 解析（Feature 156 W1.0 / CRITICAL-1 关闭）
+ *
+ * 背景：
+ *   ast-analyzer.ts:376 与 tree-sitter-fallback.ts / typescript-mapper.ts 在提取 import 时
+ *   把 `resolvedPath` 置为 null（"不解析路径，性能优化"）。删除 dependency-cruiser 后，
+ *   knowledge-graph/index.ts 的 deriveImportEdges 跳过 `resolvedPath=null` 的 import，
+ *   导致 TS/JS depends-on 边数为 0。
+ *
+ * 本模块提供两个核心能力：
+ *   1. resolveTsJsImport — specifier → 绝对路径（无法解析返回 null）
+ *      - 覆盖 4 类 import：static / dynamic / commonjs-require / type-only（路径解析逻辑相同）
+ *      - 支持相对路径、扩展名补全、index.{ts,js} fallback、tsconfig path alias
+ *      - node_modules / 外部包：返回 null（不解析外部依赖）
+ *   2. detectImportType — 从 ts-morph 节点派生 ImportType 字面量
+ *      - 用于 CodeSkeleton.imports[].importType + ModuleEdge.importType
+ *
+ * 设计约束：
+ *   - 不引入新 npm 依赖（仅用 node:fs / node:path）
+ *   - 不抛异常（无法解析返回 null + 静默忽略）
+ *   - 跨平台：path.resolve / path.posix 兼容 win32 + posix
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { Node, SyntaxKind } from 'ts-morph';
+const DEFAULT_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
+const DEFAULT_INDEX_FILES = ['index.ts', 'index.tsx', 'index.js', 'index.jsx'];
+/**
+ * Feature 156 W1.0 v2 / CRIT-1：TypeScript ESM 惯例下，`import './foo.js'` 实际指向 `./foo.ts`。
+ *
+ * 当 specifier 以 JS 扩展名结尾时，先尝试对应的 TS 扩展名候选；命中则返回，否则 fallback
+ * 到原扩展名继续走标准解析流程（保持非 TS 项目的兼容性）。
+ */
+const ESM_TS_EXT_MAP = {
+    '.js': ['.ts', '.tsx'],
+    '.jsx': ['.tsx'],
+    '.mjs': ['.mts'],
+    '.cjs': ['.cts'],
+};
+// ───────────────────────────────────────────────────────────
+// resolveTsJsImport — specifier → 绝对路径
+// ───────────────────────────────────────────────────────────
+/**
+ * 把 TS/JS import specifier 解析为绝对文件路径。
+ *
+ * 解析顺序：
+ *   1. node 内置模块（如 'fs'）/ npm 包（不带相对前缀且无 alias 命中）→ null
+ *   2. tsconfig path alias 命中 → 替换前缀后按相对路径流程解析
+ *   3. 相对路径（`./xxx` / `../xxx` / `/xxx`）→ 基于 fromFile 拼接
+ *
+ * 文件存在性检查：
+ *   - 直接命中（specifier 已含 .ts/.js 等扩展名）
+ *   - 扩展名补全（依次尝试 options.extensions）
+ *   - 目录 + index 文件 fallback（如果 specifier 指向目录）
+ *
+ * 失败时静默返回 null，不抛异常（FR-28 best-effort 语义）。
+ *
+ * @param specifier - import 字符串字面量（如 './foo'）
+ * @param fromFile - 发起 import 的源文件绝对路径
+ * @param projectRoot - 项目根目录（用于 alias 相对路径解析；可为空字符串，alias 失效）
+ * @param options - 扩展名 / index 文件 / alias 配置
+ * @returns 解析到的绝对路径；外部模块或解析失败返回 null
+ */
+export function resolveTsJsImport(specifier, fromFile, projectRoot, options) {
+    if (!specifier || typeof specifier !== 'string')
+        return null;
+    const extensions = options?.extensions ?? DEFAULT_EXTENSIONS;
+    const indexFiles = options?.indexFiles ?? DEFAULT_INDEX_FILES;
+    // 1. node 内置模块（'fs', 'path', 'node:fs'）→ null（不解析外部依赖）
+    if (specifier.startsWith('node:'))
+        return null;
+    // 2. 尝试 tsconfig path alias（多候选最长前缀匹配，CRIT-2 v2）
+    const aliasCandidates = resolveAliasCandidates(specifier, projectRoot, options?.pathAliases);
+    for (const cand of aliasCandidates) {
+        const hit = tryFilePathVariants(cand, extensions, indexFiles);
+        if (hit)
+            return hit;
+    }
+    // 3. 相对路径前缀（'.', '..', '/'）才进入文件系统解析
+    if (specifier.startsWith('.') || specifier.startsWith('/')) {
+        const fromDir = path.dirname(path.resolve(fromFile));
+        const baseSpecifier = path.resolve(fromDir, specifier);
+        return tryFilePathVariants(baseSpecifier, extensions, indexFiles);
+    }
+    // 4. baseUrl fallback（CRIT-2 v2）：未命中 alias / 非相对路径，
+    //    若 baseUrl 提供，则按非相对 module 解析（baseUrl + specifier）
+    if (options?.baseUrl) {
+        const baseRel = path.resolve(options.baseUrl, specifier);
+        const hit = tryFilePathVariants(baseRel, extensions, indexFiles);
+        if (hit)
+            return hit;
+    }
+    // 5. 不带相对前缀、无 alias / baseUrl 命中：视为 npm 包 / 外部模块 → null
+    return null;
+}
+/**
+ * 尝试 alias 替换，返回所有候选绝对路径列表（CRIT-2 v2）。
+ *
+ * 改进：
+ *   1. 支持单值与多候选数组（`Record<string, string | readonly string[]>`）
+ *   2. 最长前缀匹配（`@app/utils/foo` 命中 `@app/utils/*` 优先于 `@app/*`）
+ *   3. 一个 alias 可对应多个目标，全部作为候选返回（调用方逐个 tryFilePathVariants）
+ *
+ * @returns 候选绝对路径列表（按优先级排序：最长前缀优先 + 配置顺序）；未命中返回空数组
+ */
+function resolveAliasCandidates(specifier, projectRoot, pathAliases) {
+    if (!pathAliases || !projectRoot)
+        return [];
+    // 收集所有命中的 alias，按 prefix 长度降序（最长前缀优先）
+    const matched = [];
+    for (const [aliasPattern, targetValue] of Object.entries(pathAliases)) {
+        const aliasPrefix = aliasPattern.replace(/\*$/, '');
+        if (!specifier.startsWith(aliasPrefix))
+            continue;
+        const remainder = specifier.slice(aliasPrefix.length);
+        const targets = Array.isArray(targetValue) ? targetValue : [targetValue];
+        matched.push({ prefixLen: aliasPrefix.length, remainder, targets });
+    }
+    if (matched.length === 0)
+        return [];
+    matched.sort((a, b) => b.prefixLen - a.prefixLen);
+    const candidates = [];
+    for (const m of matched) {
+        for (const target of m.targets) {
+            const targetPrefix = target.replace(/\*$/, '');
+            const joined = path.posix.join(targetPrefix, m.remainder);
+            // target 可能已是绝对路径（ts.parseJsonConfigFileContent 解析后）；保留绝对路径不再 join projectRoot
+            candidates.push(path.isAbsolute(joined) ? joined : path.resolve(projectRoot, joined));
+        }
+    }
+    return candidates;
+}
+/**
+ * 给定一个 base 路径，依次尝试：
+ *   1. base 直接存在（含扩展名）
+ *   2. base + 扩展名（.ts, .tsx, .js, ...）
+ *   3. base / index.ts、base / index.js 等
+ */
+function tryFilePathVariants(base, extensions, indexFiles) {
+    // CRIT-1：TS ESM 惯例 — 若 base 以 JS 扩展名结尾，先尝试 TS 候选（如 foo.js → foo.ts）
+    // 命中则直接返回；不命中再 fallback 到原 base 走后续标准解析流程
+    const sourceExt = path.extname(base);
+    const tsCandidatesExts = ESM_TS_EXT_MAP[sourceExt];
+    if (tsCandidatesExts) {
+        const baseWithoutExt = base.slice(0, -sourceExt.length);
+        for (const tsExt of tsCandidatesExts) {
+            const tsCandidate = baseWithoutExt + tsExt;
+            if (existsAndIsFile(tsCandidate))
+                return tsCandidate;
+        }
+        // TS 候选未命中：继续 fallback 到下方标准解析（直接命中 / 扩展名补全 / index）
+    }
+    // 1. 直接命中
+    if (existsAndIsFile(base))
+        return base;
+    // 2. 扩展名补全
+    for (const ext of extensions) {
+        const candidate = base + ext;
+        if (existsAndIsFile(candidate))
+            return candidate;
+    }
+    // 3. 目录 + index 文件
+    if (existsAndIsDir(base)) {
+        for (const idxFile of indexFiles) {
+            const candidate = path.join(base, idxFile);
+            if (existsAndIsFile(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+function existsAndIsFile(p) {
+    try {
+        const st = fs.statSync(p);
+        return st.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function existsAndIsDir(p) {
+    try {
+        const st = fs.statSync(p);
+        return st.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+// ───────────────────────────────────────────────────────────
+// detectImportType — 从 ts-morph 节点派生 ImportType
+// ───────────────────────────────────────────────────────────
+/**
+ * 从 ts-morph 节点派生 ImportType 字面量（FR-28 / plan §2.5）。
+ *
+ * 判断规则：
+ *   1. 'type-only'：ImportDeclaration 且 isTypeOnly()=true
+ *   2. 'dynamic'：CallExpression 且 callee 为 import 关键字（SyntaxKind.ImportKeyword）
+ *   3. 'commonjs-require'：CallExpression 且 callee 文本 = "require"
+ *   4. 'static'：默认（标准 ImportDeclaration）
+ *
+ * 注：tree-sitter / 正则降级路径不调用此函数，由调用点直接根据 query 节点类型映射
+ * （tree-sitter typescript-mapper 仅处理 import_statement，importType 始终为 'static' 或 'type-only'，
+ * 由 isTypeOnly 字段派生）。
+ */
+export function detectImportType(node) {
+    if (Node.isImportDeclaration(node)) {
+        return detectImportDeclarationType(node);
+    }
+    if (Node.isCallExpression(node)) {
+        return detectCallExpressionImportType(node);
+    }
+    // 兜底：未识别节点视为 static（保持非破坏性行为）
+    return 'static';
+}
+function detectImportDeclarationType(decl) {
+    // (a) 顶层 `import type` 关键字
+    if (decl.isTypeOnly())
+        return 'type-only';
+    // WARN-1 修订：混合 import（含 default 或 namespace）即使 named import 全是 type-only，
+    // 也保留 'static' 语义 —— default / namespace 在运行时仍是值导入。
+    // 仅当 (a) 没有 default + 没有 namespace + (b) 有 named import 且全为 type-only 才归 type-only。
+    const hasDefaultImport = decl.getDefaultImport() != null;
+    const hasNamespaceImport = decl.getNamespaceImport() != null;
+    if (hasDefaultImport || hasNamespaceImport) {
+        return 'static';
+    }
+    const named = decl.getNamedImports();
+    if (named.length > 0 && named.every((n) => n.isTypeOnly())) {
+        return 'type-only';
+    }
+    return 'static';
+}
+function detectCallExpressionImportType(call) {
+    if (!Node.isCallExpression(call))
+        return 'static';
+    const expr = call.getExpression();
+    // 动态 import：callee 为 ImportKeyword
+    if (expr.getKind() === SyntaxKind.ImportKeyword)
+        return 'dynamic';
+    // CommonJS require：callee 为 Identifier("require")
+    if (Node.isIdentifier(expr) && expr.getText() === 'require')
+        return 'commonjs-require';
+    return 'static';
+}
+/**
+ * 给定一个文件的 imports 列表，逐项调用 resolveTsJsImport 填充 resolvedPath。
+ *
+ * 复用动机：ast-analyzer / tree-sitter-analyzer / tree-sitter-fallback 三处都需要
+ * 在 imports 收集完毕后批量 resolve；提取此 helper 避免重复实现。
+ *
+ * - importType 默认从 `isTypeOnly` 派生（type-only / static）；ts-morph 路径可在调用前覆盖。
+ * - 仅处理 TS/JS 语言；其他语言（Python / Go / Java）应跳过此函数。
+ */
+export function resolveImportsForFile(imports, fromFile, projectRoot, options) {
+    return imports.map((imp) => {
+        // 已 resolve 过则保留（如 ts-morph 路径已在 ast-analyzer 中显式调用）
+        const alreadyResolved = imp.resolvedPath != null && imp.resolvedPath !== '';
+        const resolvedPath = alreadyResolved
+            ? imp.resolvedPath
+            : resolveTsJsImport(imp.moduleSpecifier, fromFile, projectRoot, options);
+        // 如果未显式设置 importType，从 isTypeOnly 派生
+        const inferredImportType = imp.isTypeOnly ? 'type-only' : 'static';
+        return {
+            ...imp,
+            resolvedPath: resolvedPath ?? null,
+            // ImportReferenceSchema 已扩展 importType?: ImportType（v152 W1.0）
+            importType: imp.importType
+                ?? inferredImportType,
+        };
+    });
+}
+//# sourceMappingURL=import-resolver.js.map

package/dist/core/import-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-resolver.js","sourceRoot":"","sources":["../../src/core/import-resolver.ts"],"names":[],"mappings":"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"}

package/dist/core/query-mappers/base-mapper.d.ts

@@ -3,9 +3,12 @@
  */
 import type Parser from 'web-tree-sitter';
 import type { ExportSymbol, ImportReference, ParseError, Language } from '../../models/code-skeleton.js';
+import type { CallSite } from '../../models/call-site.js';
 export interface MapperOptions {
     /** 包含私有/非导出符号 */
     includePrivate?: boolean;
+    /** 抽取函数调用点（Feature 151，默认 false；仅 panoramic 流水线显式传 true） */
+    extractCallSites?: boolean;
 }
 export interface QueryMapper {
     /** 映射器对应的语言 */
@@ -18,5 +21,15 @@ export interface QueryMapper {
     extractParseErrors(tree: Parser.Tree): ParseError[];
     /** 提取模块级文档注释（可选，仅支持此概念的语言实现，如 Python） */
     extractModuleDoc?(tree: Parser.Tree): string | null;
+    /**
+     * 抽取函数调用点（Feature 151，可选；仅 PythonMapper 在 P1 阶段实现）。
+     *
+     * 实现要求：
+     * - 遍历 call / attribute / binary_operator / unary_operator / decorated_definition 等 AST 节点
+     * - 与 truth-set extractor (scripts/lib/python-call-extractor.py) 行为对齐（CL-04）
+     * - dynamic call (getattr / eval / 字符串拼接 attribute) 直接 skip 不输出（EC-12）
+     * - bare decorator (@staticmethod / @property) 不记录（CL-04）
+     */
+    extractCallSites?(tree: Parser.Tree, source: string): CallSite[];
 }
 //# sourceMappingURL=base-mapper.d.ts.map

package/dist/core/query-mappers/base-mapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-mapper.d.ts","sourceRoot":"","sources":["../../../src/core/query-mappers/base-mapper.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAEzG,MAAM,WAAW,aAAa;IAC5B,iBAAiB;IACjB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,eAAe;IACf,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B,wBAAwB;IACxB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,YAAY,EAAE,CAAC;IAE3F,wBAAwB;IACxB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,eAAe,EAAE,CAAC;IAErE,wBAAwB;IACxB,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,GAAG,UAAU,EAAE,CAAC;IAEpD,yCAAyC;IACzC,gBAAgB,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;CACrD"}
+{"version":3,"file":"base-mapper.d.ts","sourceRoot":"","sources":["../../../src/core/query-mappers/base-mapper.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AACzG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE1D,MAAM,WAAW,aAAa;IAC5B,iBAAiB;IACjB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,eAAe;IACf,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B,wBAAwB;IACxB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,YAAY,EAAE,CAAC;IAE3F,wBAAwB;IACxB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,eAAe,EAAE,CAAC;IAErE,wBAAwB;IACxB,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,GAAG,UAAU,EAAE,CAAC;IAEpD,yCAAyC;IACzC,gBAAgB,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;IAEpD;;;;;;;;OAQG;IACH,gBAAgB,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,EAAE,CAAC;CAClE"}

package/dist/core/query-mappers/go-mapper.d.ts

@@ -4,6 +4,7 @@
  */
 import type Parser from 'web-tree-sitter';
 import type { ExportSymbol, ImportReference, ParseError, Language } from '../../models/code-skeleton.js';
+import type { CallSite } from '../../models/call-site.js';
 import type { QueryMapper, MapperOptions } from './base-mapper.js';
 export declare class GoMapper implements QueryMapper {
     readonly language: Language;
@@ -42,5 +43,72 @@ export declare class GoMapper implements QueryMapper {
     private _extractImportSpec;
     /** 递归收集 AST 中的 ERROR 节点 */
     private _collectErrors;
+    /**
+     * 抽取 Go 函数调用点。
+     *
+     * 行为对齐：
+     * - scripts/lib/go-call-extractor.mjs 的 _classifyCallExpression / _scanImports / _resolveGoCaller
+     * - call-resolver 4-stage 决策表（spec.md FR-2 表格 11 行 short-circuit）
+     *
+     * Size guard：source.length > 1MB 时返回 []（与 PythonMapper.extractCallSites 一致）。
+     */
+    extractCallSites(tree: Parser.Tree, source: string): CallSite[];
+    /**
+     * FR-5: 扫描 source_file → import_declaration → import_spec 收集 alias 集合。
+     *
+     * 与 go-call-extractor.mjs `_scanImports` 行为完全一致：
+     * - 自定义 alias `import f "fmt"` → 记 alias `f`
+     * - 标准 import `import "fmt"` → 记 path 末段 `fmt`
+     * - dot import (name=dot) / blank import (name=blank_identifier) → skip（不入集合）
+     */
+    private _scanImports;
+    /** FR-5 辅助：从 import_spec 提取 alias 名（dot/blank 返回 null）。 */
+    private _extractAliasFromImportSpec;
+    /**
+     * FR-7: 从 method_declaration 的 receiver 字段递归提取 type 名。
+     *
+     * 支持形态：值 receiver / 指针 / 嵌套指针 / 泛型 / 泛型指针 / qualified type，
+     * 与 go-call-extractor.mjs `_extractReceiverTypeName` + `_extractTypeNameRecursive` 行为一致。
+     */
+    private _extractReceiverTypeName;
+    /** 递归从 type 节点中提取末段 type_identifier 名（值 type / pointer / generic / qualified）。 */
+    private _extractTypeNameRecursive;
+    /** FR-7: 从 method_declaration receiver 提取 var name（identifier 子节点；可能为 null）。 */
+    private _extractReceiverVarName;
+    /**
+     * FR-1, FR-7: 递归遍历 AST，对 call_expression 产 CallSite。
+     *
+     * 栈协议（try/finally 配对）：
+     * - 进入 method_declaration → push `Type.method` + receiver var
+     * - 进入 function_declaration → push `funcName` + null
+     * - 进入 func_literal → push `<closure:line:col>` + null
+     * - 离开时 pop（finally 块保证）
+     */
+    private _walkCallSites;
+    /**
+     * FR-1, FR-2 (11 行分类表), FR-6: 处理单个 call_expression 节点。
+     *
+     * 路由顺序按 spec.md FR-2 表格行 #1 → #11 short-circuit 匹配，先匹配的形态先返回。
+     */
+    private _handleCall;
+    /**
+     * FR-2 行 #3, #4: 解开 parenthesized_expression 的 callee。
+     *
+     * 实测形态（与 go-call-extractor.mjs `_classifyCallExpression` 行 1.6 节段一致）：
+     * - `(T)(nil)` → parenthesized(identifier "T") → free + "T"
+     * - `(*T)(nil)` → parenthesized(unary_expression("*", identifier "T")) → free + "T"
+     * - `(*pkg.T)(nil)` → parenthesized(unary_expression("*", selector(pkg, T))) → cross-module + "T" + qualifier "pkg"
+     */
+    private _classifyParenthesized;
+    /**
+     * FR-6: phantom call 检测。
+     *
+     * - funcNode 缺失 / hasError → phantom（skip 抽取）
+     * - sibling 含 ERROR/MISSING → phantom
+     * children 仍由 _walkCallSites 递归 walk（不会因 phantom skip 整个子树）。
+     */
+    private _isPhantomCall;
+    /** 构造单个 CallSite 记录。 */
+    private _mkCallSite;
 }
 //# sourceMappingURL=go-mapper.d.ts.map

package/dist/core/query-mappers/go-mapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"go-mapper.d.ts","sourceRoot":"","sources":["../../../src/core/query-mappers/go-mapper.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAC;AAC1C,OAAO,KAAK,EACV,YAAY,EAEZ,eAAe,EACf,UAAU,EAEV,QAAQ,EAET,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAiEnE,qBAAa,QAAS,YAAW,WAAW;IAC1C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAQ;IAEnC;;;OAGG;IACH,cAAc,CACZ,IAAI,EAAE,MAAM,CAAC,IAAI,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,aAAkB,GAC1B,YAAY,EAAE;IA+EjB;;OAEG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,eAAe,EAAE;IAiBrE;;OAEG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,GAAG,UAAU,EAAE;IAUnD,eAAe;IACf,OAAO,CAAC,gBAAgB;IAwBxB,4BAA4B;IAC5B,OAAO,CAAC,cAAc;IAyCtB,4CAA4C;IAC5C,OAAO,CAAC,uBAAuB;IA4B/B,qBAAqB;IACrB,OAAO,CAAC,gBAAgB;IA8CxB,oBAAoB;IACpB,OAAO,CAAC,oBAAoB;IAiC5B,yBAAyB;IACzB,OAAO,CAAC,wBAAwB;IAqChC,6CAA6C;IAC7C,OAAO,CAAC,kBAAkB;IAoB1B,iCAAiC;IACjC,OAAO,CAAC,YAAY;IAiCpB,4BAA4B;IAC5B,OAAO,CAAC,yBAAyB;IAoCjC,uBAAuB;IACvB,OAAO,CAAC,kBAAkB;IAqC1B,2BAA2B;IAC3B,OAAO,CAAC,cAAc;CAkBvB"}
+{"version":3,"file":"go-mapper.d.ts","sourceRoot":"","sources":["../../../src/core/query-mappers/go-mapper.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAC;AAC1C,OAAO,KAAK,EACV,YAAY,EAEZ,eAAe,EACf,UAAU,EAEV,QAAQ,EAET,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,QAAQ,EAAc,MAAM,2BAA2B,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AA2EnE,qBAAa,QAAS,YAAW,WAAW;IAC1C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAQ;IAEnC;;;OAGG;IACH,cAAc,CACZ,IAAI,EAAE,MAAM,CAAC,IAAI,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,aAAkB,GAC1B,YAAY,EAAE;IA+EjB;;OAEG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,eAAe,EAAE;IAiBrE;;OAEG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,GAAG,UAAU,EAAE;IAUnD,eAAe;IACf,OAAO,CAAC,gBAAgB;IAwBxB,4BAA4B;IAC5B,OAAO,CAAC,cAAc;IAyCtB,4CAA4C;IAC5C,OAAO,CAAC,uBAAuB;IA4B/B,qBAAqB;IACrB,OAAO,CAAC,gBAAgB;IA8CxB,oBAAoB;IACpB,OAAO,CAAC,oBAAoB;IAiC5B,yBAAyB;IACzB,OAAO,CAAC,wBAAwB;IAqChC,6CAA6C;IAC7C,OAAO,CAAC,kBAAkB;IAoB1B,iCAAiC;IACjC,OAAO,CAAC,YAAY;IAiCpB,4BAA4B;IAC5B,OAAO,CAAC,yBAAyB;IAoCjC,uBAAuB;IACvB,OAAO,CAAC,kBAAkB;IAqC1B,2BAA2B;IAC3B,OAAO,CAAC,cAAc;IAuBtB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,EAAE;IAa/D;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IA0BpB,2DAA2D;IAC3D,OAAO,CAAC,2BAA2B;IAmBnC;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB;IAiBhC,kFAAkF;IAClF,OAAO,CAAC,yBAAyB;IAiCjC,gFAAgF;IAChF,OAAO,CAAC,uBAAuB;IAgB/B;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAuDtB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAwHnB;;;;;;;OAOG;IACH,OAAO,CAAC,sBAAsB;IAuE9B;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAetB,wBAAwB;IACxB,OAAO,CAAC,WAAW;CAkBpB"}