ucn 5.5.3 → 5.6.0

package/core/public-command.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { CANONICAL_COMMANDS } = require('./registry');
+const { CANONICAL_COMMANDS, GLOBAL_PARAMS } = require('./registry');
 
 const NAME_COMMANDS = new Set(['show', 'find', 'usages', 'trace', 'tests', 'plan']);
 
@@ -34,14 +34,16 @@ function sourceRangeTarget(params) {
 /** Build normalized execute() params from the shared CLI-style positional arg. */
 function buildPublicParams(command, arg, params = {}) {
     const clean = { ...params };
-    if (clean.top === 0 && params.topRaw == null) delete clean.top;
-    if (clean.maxLines == null) delete clean.maxLines;
-    // Surface-only values never belong in execute params.
-    for (const key of ['json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'includeBundled', 'interactive',
-        'topRaw', 'limitRaw', 'maxFilesRaw', 'maxLinesRaw', 'maxChars', 'maxCharsRaw',
-        'depthRaw', 'contextRaw', 'workersRaw',
-        '_fileFromFileMode']) delete clean[key];
+    // Process flags and the build/transport parameters every command accepts
+    // never belong in execute params: the surface applies them itself.
+    for (const key of ['json', 'quiet', 'cache', 'clearCache', 'interactive', 'workers', '_fileFromFileMode',
+        ...GLOBAL_PARAMS]) delete clean[key];
 
+    return withoutUnset(subjectParams(command, arg, clean));
+}
+
+/** The params with the positional argument placed as the command's subject. */
+function subjectParams(command, arg, clean) {
     if (NAME_COMMANDS.has(command)) return { ...clean, name: arg || clean.name };
     switch (command) {
         case 'search': return { ...clean, term: arg || clean.term };
@@ -58,8 +60,32 @@ function buildPublicParams(command, arg, params = {}) {
     }
 }
 
+/** A parameter that was not given has no key: the same object MCP arguments make. */
+function withoutUnset(params) {
+    for (const key of Object.keys(params)) {
+        if (params[key] === undefined) delete params[key];
+    }
+    return params;
+}
+
+/**
+ * What to say about a parameter a command accepts and that changes nothing,
+ * or less than its name suggests, there. One text for every surface, in CLI
+ * spelling: the surface renders it with formatSurfaceMessage.
+ */
+function noOpNotes(command, params = {}) {
+    if (!params.includeMethods) return [];
+    if (['impact', 'trace', 'tests', 'check'].includes(command)) {
+        return [`--include-methods has no effect on '${command}' — method calls are always tiered by receiver evidence.`];
+    }
+    if (command === 'show') {
+        return [`--include-methods on '${command}' affects only method-callee display for standalone-function targets — caller tiers are always evidence-based, and method targets analyze method calls by default.`];
+    }
+    return [];
+}
+
 function isPublicCommand(command) {
     return CANONICAL_COMMANDS.includes(command);
 }
 
-module.exports = { buildPublicParams, isPublicCommand, parseSourceTarget, sourceRangeTarget };
+module.exports = { buildPublicParams, isPublicCommand, noOpNotes, parseSourceTarget, sourceRangeTarget };

package/core/python-modules.js

@@ -141,6 +141,12 @@ function pythonModuleScope(index, file, receiver, site, memo = new Map()) {
                 for (const child of current.namedChildren) stack.push(child);
             }
         }
+        // The name token of `module.Name`: the module root is read where
+        // the whole attribute is.
+        const { sameNode } = require('../languages/utils');
+        if (node?.parent?.type === 'attribute' && sameNode(node.parent.childForFieldName('attribute'), node)) {
+            node = node.parent;
+        }
         if (node) {
             const { referenceScope } = require('../languages/lexical-scope');
             const scopesKey = 'py-module-scopes';

package/core/reflection.js

@@ -730,8 +730,31 @@ const MEMBER_CALLEE_FIELDS = {
     member_expression: ['property', 'object'], // JS/TS
     member_access_expression: ['name', 'expression'], // C#
     attribute: ['attribute', 'object'], // Python
+    field_access: ['field', 'object'], // Java qualified namespace
 };
 
+/** Parentheses change neither a callee nor a namespace qualifier. */
+function _calleeNode(node) {
+    while (node?.type === 'parenthesized_expression') {
+        node = node.namedChildren.find(child => child.type !== 'comment');
+    }
+    return node;
+}
+
+/** A written identifier/member path, from fields rather than intervening text. */
+function _calleeName(node) {
+    node = _calleeNode(node);
+    if (!node) return '';
+    if (['identifier', 'property_identifier', 'field_identifier', 'package_identifier'].includes(node.type)) {
+        return node.text;
+    }
+    const fields = MEMBER_CALLEE_FIELDS[node.type];
+    if (!fields) return '';
+    const owner = _calleeName(node.childForFieldName(fields[1]));
+    const member = _calleeName(node.childForFieldName(fields[0]));
+    return owner && member ? `${owner}.${member}` : '';
+}
+
 /** Callee text, member name and receiver of a call node (no arguments). */
 function _calleeParts(node, wantMembers, wantQualified) {
     if (node.type === 'method_invocation') {
@@ -739,7 +762,7 @@ function _calleeParts(node, wantMembers, wantQualified) {
         const name = node.childForFieldName('name')?.text || '';
         return { calleeText: name, member: name, object: node.childForFieldName('object') };
     }
-    const fn = node.childForFieldName('function') || node.namedChild(0);
+    const fn = _calleeNode(node.childForFieldName('function') || node.namedChild(0));
     if (!fn) return null;
     if (fn.type === 'identifier') {
         return { calleeText: fn.text || '', member: fn.text, object: null, bare: true };
@@ -762,18 +785,58 @@ function _callArgs(node) {
     return argsNode ? argsNode.namedChildren.filter(c => c.type !== 'comment') : null;
 }
 
+// Construction nodes: `new Function(..)` builds a callable from a string.
+const NEW_NODE_TYPES = ['new_expression', 'object_creation_expression'];
+
+/**
+ * Local names a file's imports bind to the modules of `{ package }` rules:
+ * `reflect` for `import "reflect"`, `r` for `import r "reflect"`. An import
+ * that binds no qualifier (Go `.` and `_`) names none.
+ * @returns {Map<string, string>} local name -> module
+ */
+function _packageQualifiers(rules, imports) {
+    const modules = new Set(rules.filter(rule => rule.package).map(rule => rule.package));
+    const qualifiers = new Map();
+    if (modules.size === 0) return qualifiers;
+    for (const item of imports || []) {
+        if (!item || !modules.has(item.module)) continue;
+        for (const name of item.names || []) {
+            // The parser already supplies valid import names, including
+            // Unicode identifiers. Dot and blank imports bind no qualifier.
+            if (name && name !== '_' && name !== '.') qualifiers.set(name, item.module);
+        }
+    }
+    return qualifiers;
+}
+
 /**
- * Reflection sites of one parsed file.
+ * Reflection facts of one parsed file: { sites, reflectionUses, evalUses }.
+ *
  * Each site: { kind, line, expression, dynamic, name?, patterns?, receiver?,
- *   membersOnly? }.
+ *   membersOnly? }: a reflective access that names its member by a string.
+ *
+ * The two counts are how often the file uses the language's reflection and
+ * code-execution vocabulary, whether or not a name can be read from the use.
+ * `reflectionUses`: the call-shaped sites (a `functions` or `members` call
+ * that passes its name argument) plus calls of the `unnamed` rules.
+ * `evalUses`: bare calls of `namespaceLookups.calls` that pass an argument,
+ * plus calls and constructions of the `codeExecution` rules. They count call
+ * and construction nodes of the tree, so a spelling inside a comment or a
+ * string is no use, and neither is a method or a definition that shares a
+ * name with a builtin (`self.exec(..)`, `def eval(..)`), nor a same-named
+ * method called without the name (`request.getMethod()`).
+ *
+ * `options.imports` are the file's import records: a `{ package }` rule
+ * matches a call qualified by a local name they bind to that module.
  */
-function reflectionSitesInTree(tree, language, code = null) {
+function reflectionFactsInTree(tree, language, code = null, options = {}) {
+    const facts = { sites: [], reflectionUses: 0, evalUses: 0 };
     const traits = langTraits(language) || {};
     const api = traits.reflectionApi;
-    if (!api || !tree) return [];
+    if (!api || !tree) return facts;
     const resolve = makeResolver();
     const ctx = { formatCalls: api.formatCalls || null, resolve };
-    const sites = [];
+    const sites = facts.sites;
     const push = (node, kind, nameNode, receiverNode, receiverFact) => {
         const cls = classifyNameExpression(nameNode, ctx);
         const expression = String(node.text || '');
@@ -796,22 +859,37 @@ function reflectionSitesInTree(tree, language, code = null) {
         });
     };
     const ns = api.namespaceLookups;
+    // Vocabulary that names no member: counted, never a site.
+    const unnamed = api.unnamed || [];
+    const codeExecution = api.codeExecution || [];
+    const constructs = codeExecution.filter(rule => rule.construct);
+    const qualifiers = _packageQualifiers([...unnamed, ...codeExecution], options.imports);
+    const scopeMemo = new Map();
     // Candidate nodes are located natively: reflective calls from the
     // vocabulary's spelling positions (descendantForIndex, walking up to the
     // enclosing call), computed member keys by node type. No JS-side walk of
     // the whole tree.
-    const hintPattern = api.hintPattern || null;
-    const useHints = code != null && hintPattern;
+    const hintSources = [];
+    if (api.hintPattern) hintSources.push(api.hintPattern.source);
+    // A package's qualifier is the file's own choice (`r "reflect"`).
+    if (qualifiers.size > 0) {
+        const { literalNameRegex } = require('./shared');
+        hintSources.push(...[...qualifiers.keys()].map(name => literalNameRegex(name).source));
+    }
+    const useHints = code != null && hintSources.length > 0;
+    const callTypes = constructs.length > 0 ? [...CALL_NODE_TYPES, ...NEW_NODE_TYPES] : CALL_NODE_TYPES;
     const types = [];
     if (!useHints) {
-        types.push(...CALL_NODE_TYPES);
+        types.push(...callTypes);
         if (ns?.subscriptOf) types.push('subscript');
     }
     if (api.computedMembers) types.push('subscript_expression');
     const wantMembers = (api.members || []).length > 0;
-    // Qualified function callees (`Reflect.get`) need the callee text of
-    // member-shaped calls; bare vocabularies (`getattr`) never do.
-    const wantQualified = (api.functions || []).some(rule => rule.qualified);
+    // Qualified callees (`Reflect.get`, a package's functions) need the
+    // callee text of member-shaped calls; bare vocabularies (`getattr`)
+    // never do.
+    const wantQualified = qualifiers.size > 0 ||
+        [...(api.functions || []), ...unnamed, ...codeExecution].some(rule => rule.qualified);
     const visitNode = node => {
         if (node.type === 'subscript_expression') {
             // obj["on" + evt] / this[`handle${t}`] (JS/TS computed member
@@ -843,15 +921,23 @@ function reflectionSitesInTree(tree, language, code = null) {
             }
             return;
         }
+        if (NEW_NODE_TYPES.includes(node.type)) {
+            // `new Function(code)`: the constructed class decides.
+            const constructed = node.childForFieldName('constructor') || node.childForFieldName('type');
+            const text = _calleeName(constructed);
+            if (constructs.some(rule => rule.construct.test(text))) facts.evalUses++;
+            return;
+        }
         const call = _calleeParts(node, wantMembers, wantQualified);
         if (!call) return;
         // Match on the callee spelling first; arguments are read only for a
         // vocabulary hit (most calls in a hinted file are unrelated).
-        const calleeText = () => (call.calleeText ??= call.fn.text || '');
+        const calleeText = () => (call.calleeText ??= _calleeName(call.fn));
         for (const rule of api.functions || []) {
             if (!rule.callee.test(calleeText())) continue;
             const args = _callArgs(node);
             if (args && args[rule.nameArg]) {
+                facts.reflectionUses++;
                 push(node, rule.kind || calleeText().split('.').pop(),
                     args[rule.nameArg], args[rule.receiverArg]);
             }
@@ -861,7 +947,10 @@ function reflectionSitesInTree(tree, language, code = null) {
             for (const rule of api.members || []) {
                 if (!rule.member.test(call.member)) continue;
                 const args = _callArgs(node);
-                if (args && args[rule.nameArg]) push(node, call.member, args[rule.nameArg], call.object);
+                if (args && args[rule.nameArg]) {
+                    facts.reflectionUses++;
+                    push(node, call.member, args[rule.nameArg], call.object);
+                }
                 return;
             }
         }
@@ -869,25 +958,58 @@ function reflectionSitesInTree(tree, language, code = null) {
         // so even a fully dynamic name is bounded to it.
         if (ns?.calls && call.bare && ns.calls.test(call.calleeText)) {
             const args = _callArgs(node);
-            if (args && args[0]) push(node, call.calleeText, args[0], null, MODULE_RECEIVER);
+            if (args && args[0]) {
+                facts.evalUses++;
+                push(node, call.calleeText, args[0], null, MODULE_RECEIVER);
+            }
+            return;
         }
+        if (unnamed.length === 0 && codeExecution.length === 0) return;
+        // The callee as written, receiver included (`Class.forName`,
+        // `reflect.ValueOf`); a bare callee is its own text.
+        let written = null;
+        const writtenCallee = () => (written ??= (node.type === 'method_invocation'
+            ? (call.object ? `${_calleeName(call.object)}.${call.member}` : call.member || '')
+            : calleeText()));
+        const matches = rule => {
+            if (rule.construct) return false;
+            if (rule.callee) return rule.callee.test(writtenCallee());
+            if (rule.package) {
+                const qualifier = _calleeNode(call.object);
+                if (qualifier?.type !== 'identifier' || qualifiers.get(qualifier.text) !== rule.package) return false;
+                // The file import owns the spelling only outside scopes
+                // that bind another value to it (parameters, locals, etc.).
+                return require('../languages/lexical-scope').referenceScope(
+                    qualifier, language, scopeMemo) === 'module';
+            }
+            return false;
+        };
+        if (unnamed.some(matches)) facts.reflectionUses++;
+        else if (codeExecution.some(matches)) facts.evalUses++;
     };
     try {
         const candidates = [];
         if (useHints) {
+            // One candidate per node: nested calls can begin at one offset
+            // (`a.getMethod(x).getField(y)`), so the end is part of the key.
             const seen = new Set();
-            const re = new RegExp(hintPattern.source, 'g');
+            const once = (kind, node) => {
+                const key = `${kind}${node.startIndex}:${node.endIndex}`;
+                if (seen.has(key)) return false;
+                seen.add(key);
+                return true;
+            };
+            const re = new RegExp(hintSources.join('|'), 'gu');
             let m;
             while ((m = re.exec(code)) !== null) {
+                if (m[0] === '') { re.lastIndex++; continue; }
                 let node = tree.rootNode.descendantForIndex(m.index);
-                for (let i = 0; node && i < 6; i++, node = node.parent) {
-                    if (!CALL_NODE_TYPES.includes(node.type)) continue;
-                    if (!seen.has(node.startIndex)) { seen.add(node.startIndex); candidates.push(node); }
+                for (; node; node = node.parent) {
+                    if (!callTypes.includes(node.type)) continue;
+                    if (once('c', node)) candidates.push(node);
                     // `globals()[name]`: the lookup is the enclosing subscript.
                     const parent = node.parent;
-                    if (ns?.subscriptOf && parent?.type === 'subscript' &&
-                        !seen.has(-parent.startIndex - 1)) {
-                        seen.add(-parent.startIndex - 1);
+                    if (ns?.subscriptOf && parent?.type === 'subscript' && once('s', parent)) {
                         candidates.push(parent);
                     }
                     break;
@@ -898,7 +1020,12 @@ function reflectionSitesInTree(tree, language, code = null) {
         candidates.sort((a, b) => a.startIndex - b.startIndex || (a.endIndex - b.endIndex));
         for (const node of candidates) visitNode(node);
     } catch (_) { /* partial inventory is disclosed as-is */ }
-    return sites;
+    return facts;
+}
+
+/** The reflection sites of one parsed file (see reflectionFactsInTree). */
+function reflectionSitesInTree(tree, language, code = null) {
+    return reflectionFactsInTree(tree, language, code).sites;
 }
 
 // ---------------------------------------------------------------------------
@@ -1132,6 +1259,7 @@ module.exports = {
     stringAlternatives,
     classifyNameExpression,
     classifyReceiver,
+    reflectionFactsInTree,
     reflectionSitesInTree,
     globMatches,
     patternEntriesFor,