cgraphx 2.0.1 → 2.0.3

package/dist/core/code/engine/core/ingestion/languages/python/scope-resolver.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Python `ScopeResolver` registered in `SCOPE_RESOLVERS` and consumed
+ * by the generic `runScopeResolution` orchestrator.
+ *
+ * The provider is a thin wiring object — Python's specific bits
+ * (super recognizer, LEGB merge precedence, Python's relative-import
+ * resolver, the simplified MRO walk) plug into `runScopeResolution`.
+ *
+ * Migration reference: when bringing up the next language
+ * (TypeScript / Java / Kotlin / Ruby), copy this file's structure —
+ * implement the 6 required `ScopeResolver` fields, optionally toggle
+ * the 2 booleans, and register in `scope-resolution/pipeline/registry.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pythonScopeResolver = void 0;
+const index_js_1 = require("../../../../../shared/index.js");
+const mro_js_1 = require("../../scope-resolution/passes/mro.js");
+const walkers_js_1 = require("../../scope-resolution/scope/walkers.js");
+const shared_js_1 = require("../../type-extractors/shared.js");
+const python_js_1 = require("../python.js");
+const index_js_2 = require("./index.js");
+const pythonScopeResolver = {
+    // A free call naming a class constructs it: `Service(db).do_work()` (#2708).
+    constructionSyntax: { bare: true },
+    language: index_js_1.SupportedLanguages.Python,
+    languageProvider: python_js_1.pythonProvider,
+    importEdgeReason: 'python-scope: import',
+    resolveImportTarget: (targetRaw, fromFile, allFilePaths, _resolutionConfig, context) => {
+        // Pass the orchestrator's stable run-level `ReadonlySet` straight through
+        // (no per-import copy). The Python resolver chain only reads the set, and
+        // `getPythonFileIndex` memoizes its index on the set's identity via a
+        // WeakMap — so the index is built once per run and reused across every
+        // import. Copying here (the previous `new Set(allFilePaths)`) handed a
+        // fresh identity to every import, defeating that cache (PR #1918 review P1).
+        const ws = {
+            fromFile,
+            allFilePaths,
+            parsedFiles: context?.parsedFiles,
+        };
+        // `WorkspaceIndex` is an opaque `unknown` placeholder in the
+        // shared contract, so `ws` passes structurally without a cast.
+        return (0, index_js_2.resolvePythonImportTarget)(context?.parsedImport ?? { kind: 'namespace', localName: '_', importedName: '_', targetRaw }, ws);
+    },
+    isNamespaceImport: (parsedImport, targetFile, fromFile) => (0, index_js_2.isPythonImportedModule)(parsedImport, targetFile, fromFile),
+    // `import a.b.c` binds only `a`, yet makes `a`, `a.b` and `a.b.c` all
+    // callable — each naming a different file. Without this the absolute-import
+    // style is invisible to the call graph, and the root key points at the leaf
+    // module instead of the package (#2826).
+    namespaceReceiverPaths: index_js_2.pythonNamespaceReceiverPaths,
+    // Python LEGB precedence: local > import/namespace/reexport > wildcard.
+    // The per-scope id is unused by pythonMergeBindings (tier ordering
+    // is computed purely from BindingRef.origin), so we don't need to
+    // synthesize a Scope.
+    mergeBindings: (existing, incoming) => [...(0, index_js_2.pythonMergeBindings)([...existing, ...incoming])],
+    // Adapter: pythonArityCompatibility predates RegistryProviders and
+    // uses (def, callsite). ScopeResolver contract is (callsite, def).
+    // Wrapper kept to honor both contracts without altering the legacy
+    // shape that LanguageProvider.arityCompatibility consumes.
+    arityCompatibility: (callsite, def) => (0, index_js_2.pythonArityCompatibility)(def, callsite),
+    buildMro: (graph, parsedFiles, nodeLookup) => (0, mro_js_1.buildMro)(graph, parsedFiles, nodeLookup, mro_js_1.defaultLinearize),
+    populateOwners: (parsed) => (0, walkers_js_1.populateClassOwnedMembers)(parsed),
+    isSuperReceiver: (text) => /^super\s*\(/.test(text),
+    // Subscript route only — Python spells collection views as method calls
+    // (`.values()`), which the compound resolver's call branch already handles.
+    //
+    // The hook receives the annotation AS WRITTEN (`List[User]`, `Dict[str, User]`),
+    // not the name `interpret.ts`'s `stripGeneric` reduced it to, so `undefined`
+    // here means "this spelling is not a container" — which is what stops
+    // `cfg['k'].run()` on a `__getitem__`-bearing class from folding onto the
+    // class itself. Answering the route at all is what keeps `repos[0].save()`
+    // resolving.
+    elementTypeOf: shared_js_1.indexOnlyElementType,
+    // Python is dynamically typed — field-fallback heuristic on, return-
+    // type propagation across imports on. Both default to true; listed
+    // explicitly here for documentation.
+    fieldFallbackOnMethodLookup: true,
+    propagatesReturnTypesAcrossImports: true,
+};
+exports.pythonScopeResolver = pythonScopeResolver;

package/dist/core/code/engine/core/ingestion/languages/python/simple-hooks.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Trivial / no-op-ish hooks for the Python provider. Kept together
+ * because each is a few lines and they share a common theme: they exist
+ * to make the provider's choice explicit (rather than relying on
+ * "absence == default") so reviewers don't have to re-derive the
+ * analysis.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pythonFunctionDefinitionLabel = pythonFunctionDefinitionLabel;
+exports.pythonBindingScopeFor = pythonBindingScopeFor;
+exports.pythonImportOwningScope = pythonImportOwningScope;
+exports.pythonReceiverBinding = pythonReceiverBinding;
+const ast_helpers_js_1 = require("../../utils/ast-helpers.js");
+const scope_tree_walk_js_1 = require("../../utils/scope-tree-walk.js");
+const PYTHON_METHOD_CONTAINER_TYPES = new Set(['class_definition']);
+function pythonFunctionDefinitionLabel(functionNode, defaultLabel) {
+    if (defaultLabel !== 'Function')
+        return defaultLabel;
+    const ancestor = (0, ast_helpers_js_1.findAncestorBeforeBoundary)(functionNode, PYTHON_METHOD_CONTAINER_TYPES, ast_helpers_js_1.FUNCTION_NODE_TYPES);
+    return ancestor === null ? 'Function' : 'Method';
+}
+// ─── bindingScopeFor ──────────────────────────────────────────────────────
+/** Python has no block scope, so the central extractor's "innermost
+ *  enclosing scope" default is already correct for ordinary bindings.
+ *  Constructor-injected instance fields are the exception: their marker is
+ *  anchored inside `__init__`, but compound receiver resolution needs the
+ *  field type on the enclosing Class scope. */
+function pythonBindingScopeFor(decl, innermost, tree) {
+    if (decl['@type-binding.instance-field'] !== undefined) {
+        return (0, scope_tree_walk_js_1.walkToScope)(innermost, tree, 'Class');
+    }
+    return null;
+}
+// ─── importOwningScope ────────────────────────────────────────────────────
+/** Function-local `from x import Y` should attach the binding to the
+ *  function scope, not the module. Class-body imports (rare but legal —
+ *  `class A: import x` makes `x` a class attribute) attach to the class.
+ *  Module-level imports delegate to the central default. */
+function pythonImportOwningScope(_imp, innermost, _tree) {
+    if (innermost.kind === 'Function' || innermost.kind === 'Class')
+        return innermost.id;
+    return null;
+}
+// ─── receiverBinding ──────────────────────────────────────────────────────
+/** Look up `self` or `cls` in the function scope's type bindings.
+ *  Returns `null` for free functions (no `self`/`cls`) and for
+ *  non-Function scopes. */
+function pythonReceiverBinding(functionScope) {
+    if (functionScope.kind !== 'Function')
+        return null;
+    return functionScope.typeBindings.get('self') ?? functionScope.typeBindings.get('cls') ?? null;
+}

package/dist/core/code/engine/core/ingestion/languages/python.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * Python Language Provider
+ *
+ * Assembles all Python-specific ingestion capabilities into a single
+ * LanguageProvider, following the Strategy pattern used by the pipeline.
+ *
+ * Key Python traits:
+ *   - mroStrategy: 'c3' (Python C3 linearization for multiple inheritance)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pythonProvider = void 0;
+const index_js_1 = require("../../../../shared/index.js");
+const generic_js_1 = require("../class-extractors/generic.js");
+const python_js_1 = require("../class-extractors/configs/python.js");
+const language_provider_js_1 = require("../language-provider.js");
+const python_js_2 = require("../type-extractors/python.js");
+const export_detection_js_1 = require("../export-detection.js");
+const resolver_factory_js_1 = require("../import-resolvers/resolver-factory.js");
+const python_js_3 = require("../import-resolvers/configs/python.js");
+const tree_sitter_queries_js_1 = require("../tree-sitter-queries.js");
+const generic_js_2 = require("../field-extractors/generic.js");
+const python_js_4 = require("../field-extractors/configs/python.js");
+const generic_js_3 = require("../method-extractors/generic.js");
+const python_js_5 = require("../method-extractors/configs/python.js");
+const generic_js_4 = require("../variable-extractors/generic.js");
+const python_js_6 = require("../variable-extractors/configs/python.js");
+const generic_js_5 = require("../call-extractors/generic.js");
+const python_js_7 = require("../call-extractors/configs/python.js");
+const python_js_8 = require("../cfg/visitors/python.js");
+const index_js_2 = require("./python/index.js");
+const django_js_1 = require("../route-extractors/django.js");
+const django_root_discovery_js_1 = require("../route-extractors/django-root-discovery.js");
+const BUILT_INS = new Set([
+    'print',
+    'len',
+    'range',
+    'str',
+    'int',
+    'float',
+    'list',
+    'dict',
+    'set',
+    'tuple',
+    'append',
+    'extend',
+    'update',
+    'type',
+    'isinstance',
+    'issubclass',
+    'getattr',
+    'setattr',
+    'hasattr',
+    'enumerate',
+    'zip',
+    'sorted',
+    'reversed',
+    'min',
+    'max',
+    'sum',
+    'abs',
+]);
+function pythonDescriptionExtractor(nodeLabel, _nodeName, captureMap) {
+    if (nodeLabel !== 'Function' && nodeLabel !== 'Method')
+        return undefined;
+    const functionNode = captureMap['definition.function'] ?? captureMap['definition.method'];
+    if (functionNode === undefined)
+        return undefined;
+    return extractPythonDocstring(functionNode);
+}
+function extractPythonDocstring(functionNode) {
+    const body = functionNode.childForFieldName('body');
+    const firstStatement = body?.namedChild(0);
+    if (firstStatement?.type !== 'expression_statement')
+        return undefined;
+    const literal = firstStatement.namedChild(0);
+    if (literal?.type !== 'string')
+        return undefined;
+    return normalizePythonStringLiteral(literal.text);
+}
+function normalizePythonStringLiteral(text) {
+    const match = text.match(/^[rRuUbBfF]*("""|'''|"|')([\s\S]*)\1$/);
+    const raw = match?.[2]?.trim();
+    if (!raw)
+        return undefined;
+    return raw.replace(/\s+/g, ' ');
+}
+exports.pythonProvider = (0, language_provider_js_1.defineLanguage)({
+    id: index_js_1.SupportedLanguages.Python,
+    extensions: ['.py'],
+    entryPointPatterns: [/^app$/, /^(get|post|put|delete|patch)_/i, /^api_/, /^view_/],
+    astFrameworkPatterns: [
+        {
+            framework: 'fastapi',
+            entryPointMultiplier: 3.0,
+            reason: 'fastapi-decorator',
+            patterns: ['@app.get', '@app.post', '@app.put', '@app.delete', '@router.get'],
+        },
+        {
+            framework: 'flask',
+            entryPointMultiplier: 2.8,
+            reason: 'flask-decorator',
+            patterns: ['@app.route', '@blueprint.route'],
+        },
+    ],
+    treeSitterQueries: tree_sitter_queries_js_1.PYTHON_QUERIES,
+    typeConfig: python_js_2.typeConfig,
+    exportChecker: export_detection_js_1.pythonExportChecker,
+    importResolver: (0, resolver_factory_js_1.createImportResolver)(python_js_3.pythonImportConfig),
+    mroStrategy: 'c3',
+    callExtractor: (0, generic_js_5.createCallExtractor)(python_js_7.pythonCallConfig),
+    fieldExtractor: (0, generic_js_2.createFieldExtractor)(python_js_4.pythonConfig),
+    methodExtractor: (0, generic_js_3.createMethodExtractor)(python_js_5.pythonMethodConfig),
+    variableExtractor: (0, generic_js_4.createVariableExtractor)(python_js_6.pythonVariableConfig),
+    classExtractor: (0, generic_js_1.createClassExtractor)(python_js_1.pythonClassConfig),
+    descriptionExtractor: pythonDescriptionExtractor,
+    builtInNames: BUILT_INS,
+    // Django routing is whole-repo and cross-file (manage.py → settings →
+    // ROOT_URLCONF → root urls.py, then include()s across files), so it runs as
+    // a main-thread pass (see parse-impl's cross-file route extraction) rather
+    // than the worker's single-file `isRouteFile` path. `reader` lets discovery
+    // and extraction resolve any repo-relative file regardless of parse chunking.
+    discoverRootRouteFiles: (files, contentMap, reader) => (0, django_root_discovery_js_1.discoverDjangoRootUrls)(files, contentMap, reader),
+    extractRoutes: (tree, filePath, reader, parser) => parser ? (0, django_js_1.extractDjangoRoutes)(tree, filePath, parser, reader) : [],
+    labelOverride: index_js_2.pythonFunctionDefinitionLabel,
+    // ── RFC #909 Ring 3: scope-based resolution hooks (RFC §5) ──────────
+    // Python is the first migration. See ./python/index.ts for the
+    // full per-hook rationale and the canonical capture vocabulary in
+    // ./python/query.ts (PYTHON_SCOPE_QUERY constant).
+    emitScopeCaptures: index_js_2.emitPythonScopeCaptures,
+    cfgVisitor: (0, python_js_8.createPythonCfgVisitor)(),
+    interpretImport: index_js_2.interpretPythonImport,
+    interpretTypeBinding: index_js_2.interpretPythonTypeBinding,
+    bindingScopeFor: index_js_2.pythonBindingScopeFor,
+    importOwningScope: index_js_2.pythonImportOwningScope,
+    mergeBindings: (_scope, bindings) => (0, index_js_2.pythonMergeBindings)(bindings),
+    receiverBinding: index_js_2.pythonReceiverBinding,
+    arityCompatibility: index_js_2.pythonArityCompatibility,
+    resolveImportTarget: index_js_2.resolvePythonImportTarget,
+});

package/dist/core/code/engine/core/ingestion/languages/ruby/arity.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Ruby arity check, accommodating `*args`, `**kwargs`, and defaults.
+ *
+ * The `def` metadata we care about (set by the existing Ruby method/
+ * function extractor):
+ *   - `parameterCount`         — total positional + keyword params
+ *   - `requiredParameterCount` — min required (excludes defaults / `*args` / `**kwargs`)
+ *   - `parameterTypes`         — present when types are known; we also use it
+ *                                as a "we have varargs" hint (`'*args'`,
+ *                                `'**kwargs'` literals appear in the array).
+ *
+ * Verdicts:
+ *   - `'compatible'`   — `requiredParameterCount <= argCount <= parameterCount`,
+ *                        OR the def takes `*args` (then any `argCount >= required` ok).
+ *   - `'incompatible'` — argCount is below required, OR above max with no `*args`.
+ *   - `'unknown'`      — def metadata is absent / incomplete.
+ *
+ * `'incompatible'` is a soft signal in `Registry.lookup` (penalized but
+ * still considered when no compatible candidate exists), per RFC 4.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rubyArityCompatibility = rubyArityCompatibility;
+function rubyArityCompatibility(def, callsite) {
+    const max = def.parameterCount;
+    const min = def.requiredParameterCount;
+    if (max === undefined && min === undefined)
+        return 'unknown';
+    const argCount = callsite.arity;
+    if (!Number.isFinite(argCount) || argCount < 0)
+        return 'unknown';
+    // Detect varargs/kwargs from parameterTypes if present (the Ruby
+    // method extractor stores `'*args'`/`'**kwargs'` in this list).
+    const hasVarArgs = def.parameterTypes !== undefined &&
+        def.parameterTypes.some((t) => t === '*args' || t === '**kwargs' || t.startsWith('*'));
+    if (min !== undefined && argCount < min)
+        return 'incompatible';
+    if (max !== undefined && argCount > max && !hasVarArgs)
+        return 'incompatible';
+    return 'compatible';
+}

package/dist/core/code/engine/core/ingestion/languages/ruby/cache-stats.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordRubyCacheHit = recordRubyCacheHit;
+exports.recordRubyCacheMiss = recordRubyCacheMiss;
+exports.getRubyCaptureCacheStats = getRubyCaptureCacheStats;
+exports.resetRubyCaptureCacheStats = resetRubyCaptureCacheStats;
+let hits = 0;
+let misses = 0;
+function recordRubyCacheHit() {
+    hits++;
+}
+function recordRubyCacheMiss() {
+    misses++;
+}
+function getRubyCaptureCacheStats() {
+    return { hits, misses };
+}
+function resetRubyCaptureCacheStats() {
+    hits = 0;
+    misses = 0;
+}