ucn 5.6.0 → 5.6.1

package/core/deadcode.js

@@ -19,6 +19,9 @@ const { protocolMemberOf, protocolTypeOf, typedLiteralContract, rustProjectTrait
     hierarchySlotClosure, goContractClosure, structuralContractsRequiring,
     requirementIn, resetContractIndex } = require('./contract-membership');
 const { projectKind, downstreamExposureBlocks } = require('./deletion');
+const { pythonIdentity, registrationUnknown, pythonSourceName, pythonNormalizedNames,
+    pythonProjectIdentityAffected } = require('./python-binding-identity');
+const { runtimeEntrypoints, runtimeTargetReaches } = require('./runtime-entrypoints');
 
 const _CLASS_KINDS = ['class', 'struct', 'interface', 'trait', 'record'];
 
@@ -32,12 +35,6 @@ const CLASS_AUDIT_KINDS = ['class', 'struct', 'interface', 'trait', 'record', 'e
 // the callable with an external runtime. They therefore remain eligible for a
 // name/usage-based dead-code proof. Every other unknown decorator/annotation
 // stays conservative: it may be the only evidence of framework registration.
-const _NON_REGISTERING_DECORATORS = new Set([
-    'property',
-    'classmethod',
-    'staticmethod',
-]);
-
 function _decoratorName(value) {
     const raw = typeof value === 'string'
         ? value
@@ -46,7 +43,33 @@ function _decoratorName(value) {
     return String(raw).trim().replace(/^@/, '').split('(')[0].trim();
 }
 
-function hasUnknownRegistrationDecorator(symbol) {
+const PYTHON_DECLARATIONS = new WeakMap();
+
+function pythonDeclaration(index, symbol) {
+    try {
+        const operation = index._opTreeCache;
+        let byFile = operation && PYTHON_DECLARATIONS.get(operation);
+        if (!byFile) {
+            byFile = new Map();
+            if (operation) PYTHON_DECLARATIONS.set(operation, byFile);
+        }
+        let byName = byFile.get(symbol.file);
+        if (!byName) {
+            byName = new Map();
+            const tree = index._getParsedTree(symbol.file, index._readFile(symbol.file), 'python');
+            for (const node of tree.rootNode.descendantsOfType(['function_definition', 'class_definition'])) {
+                const name = node.childForFieldName('name')?.text;
+                if (!byName.has(name)) byName.set(name, []);
+                byName.get(name).push(node);
+            }
+            byFile.set(symbol.file, byName);
+        }
+        return (byName.get(symbol.name) || []).find(node =>
+            node.startPosition.row + 1 >= symbol.startLine && node.endPosition.row + 1 <= symbol.endLine);
+    } catch { return null; }
+}
+
+function hasUnknownRegistrationDecorator(symbol, index) {
     const values = [
         symbol.decorators,
         symbol.decoratorsWithArgs,
@@ -54,15 +77,15 @@ function hasUnknownRegistrationDecorator(symbol) {
         symbol.attributesWithArgs,
     ].flatMap(items => Array.isArray(items) ? items : []);
 
+    if (values.length === 0) return false;
+    if (index?.files.get(symbol.file)?.language === 'python') {
+        if (typeof symbol.registrationUnknown === 'boolean') return symbol.registrationUnknown || pythonProjectIdentityAffected(index, 'builtins.*');
+        const declaration = pythonDeclaration(index, symbol);
+        return declaration ? registrationUnknown(declaration) || pythonProjectIdentityAffected(index, 'builtins.*') : true;
+    }
     return values.some(value => {
         const qualified = _decoratorName(value);
         if (!qualified) return false;
-        const bare = qualified.split(/\.|::/).pop();
-        if (_NON_REGISTERING_DECORATORS.has(bare)) return false;
-        // `@name.getter`, `@name.setter`, and `@name.deleter` install an
-        // accessor on an already local property; they are not external
-        // framework registration boundaries.
-        if (['getter', 'setter', 'deleter'].includes(bare)) return false;
         return true;
     });
 }
@@ -93,9 +116,20 @@ const _UNIVERSAL_ROOTS = new Set(['object', 'Object']);
 const _PY_NON_DISPATCHING_BASES = new Set(['Generic']);
 
 /** True when a base name resolves to NO in-project class/struct/interface/trait/record (an out-of-tree type). */
-function _baseIsExternal(index, bare, lang, fromDef) {
-    if (!bare || _UNIVERSAL_ROOTS.has(bare)) return false;
-    if (lang === 'python' && _PY_NON_DISPATCHING_BASES.has(bare)) return false;
+function _baseIsExternal(index, bare, lang, fromDef, raw) {
+    if (!bare) return false;
+    if (lang === 'python' && fromDef) {
+        const declaration = pythonDeclaration(index, fromDef);
+        let base = declaration?.childForFieldName('superclasses')?.namedChildren.find(node =>
+            node.text === raw || (node.type === 'subscript' && node.childForFieldName('value')?.text === raw));
+        while (base?.type === 'subscript') base = base.childForFieldName('value');
+        const identity = pythonIdentity(base);
+        if (identity === 'builtins.object' || identity === 'typing.Generic') return pythonProjectIdentityAffected(index, identity);
+        // A source import can reuse a builtin's spelling without its semantics.
+        if (identity && (_UNIVERSAL_ROOTS.has(bare) || _PY_NON_DISPATCHING_BASES.has(bare))) return true;
+    } else if (_UNIVERSAL_ROOTS.has(bare) &&
+        !(index.files.get(fromDef?.file)?.importBindings || []).some(binding => (binding.alias || binding.name) === bare) &&
+        !(index.symbols.get(bare) || []).some(def => def.file === fromDef?.file)) return false;
     const defs = index.symbols.get(bare);
     return !(defs && defs.some(d => _CLASS_KINDS.includes(d.type) &&
         // `class EnvironBuilder(werkzeug.test.EnvironBuilder)` must not
@@ -152,7 +186,7 @@ function _heritageReachesExternalBase(index, classDef, lang, followImplements) {
                 const bare = _bareBaseName(raw);
                 if (!bare || seen.has(bare)) continue;
                 seen.add(bare);
-                if (_baseIsExternal(index, bare, lang, def)) return true;
+                if (_baseIsExternal(index, bare, lang, def, raw)) return true;
                 for (const pd of index.symbols.get(bare) || []) {
                     if (_CLASS_KINDS.includes(pd.type)) next.push(pd);
                 }
@@ -349,7 +383,7 @@ function contractFactsOf(index, declared, lang) {
                 typedLiteralExternalMember(index, declared) ||
                 implicitStandardContract(declared, lang)),
         projectContract: requiredByProjectContract(index, declared),
-        registered: !!(isFrameworkEntrypoint(declared, index) || hasUnknownRegistrationDecorator(declared)),
+        registered: !!(isFrameworkEntrypoint(declared, index) || hasUnknownRegistrationDecorator(declared, index)),
     };
 }
 
@@ -885,6 +919,7 @@ function deadcode(index, options = {}) {
     // reports every outcome (detail: the audit row of a claim, the sites of
     // a use). Neither changes what is claimed.
     const onlyNames = options.names instanceof Set ? options.names : null;
+    const packagingEntrypoints = runtimeEntrypoints(index);
     const explain = typeof options.explain === 'function' ? options.explain : null;
     const withhold = (symbol, reason, detail) => { if (explain) explain(symbol, reason, detail); };
     // Assessment only: names whose every call site the caller has shown to
@@ -990,8 +1025,8 @@ function deadcode(index, options = {}) {
         if (!fe || sites.length === 0) continue;
         for (const site of sites) {
             if (site.dynamic) dynamicReflectionFiles.add(reflectionFile);
-            if (site.name) literalReflectionNames.add(site.name);
-            if (site.patterns && site.patterns.length > 0 && !site.name) {
+            if (site.name && !site.runtimeTarget) literalReflectionNames.add(site.name);
+            if (site.patterns && site.patterns.length > 0 && !site.name && !site.runtimeTarget) {
                 // Exact alternatives of a multi-spelling site are literals.
                 for (const pattern of site.patterns) {
                     if (!pattern.includes('*')) literalReflectionNames.add(pattern);
@@ -1283,6 +1318,18 @@ function deadcode(index, options = {}) {
                 // name inside /* ... */ counted as usage — commented-out code
                 // silently kept its symbols "alive" and hid true dead claims.
                 const lines = maskBlockComments(content, fileEntry.language).split('\n');
+                let stringTree;
+                const multilinePython = fileEntry.language === 'python' && (content.includes('"""') || content.includes("'''"));
+                const inMultilineString = (line, column) => {
+                    if (!multilinePython) return false;
+                    stringTree ||= index._getParsedTree(filePath, content, fileEntry.language);
+                    let node = stringTree.rootNode.descendantForPosition({ row: line, column });
+                    for (; node; node = node.parent) {
+                        if (node.type === 'interpolation') return false;
+                        if (node.type === 'string') return true;
+                    }
+                    return false;
+                };
                 for (const name of namesInFile) {
                     const nameLen = name.length;
                     for (let i = 0; i < lines.length; i++) {
@@ -1318,7 +1365,7 @@ function deadcode(index, options = {}) {
                             const rustAttributePath = fileEntry.language === 'rust' &&
                                 /^\s*#\[\s*serde\s*\(/.test(line) &&
                                 new RegExp(`\\b(?:serialize_with|deserialize_with|default|with)\\s*=\\s*["'][^"']*\\b${escapeRegExp(name)}\\b`).test(line);
-                            if (isInsideString(line, pos, fileEntry.language) &&
+                            if ((isInsideString(line, pos, fileEntry.language) || inMultilineString(i, pos)) &&
                                 !(fileEntry.language === 'python' && classKindNames.has(name)) &&
                                 !rustAttributePath) continue;
                             // Property/field access (preceded by '.'), not a
@@ -1639,7 +1686,18 @@ function deadcode(index, options = {}) {
             // call-pattern-based registration (Express routes, Gin handlers, etc.)
             // These functions are invoked by frameworks, not by user code.
             const hasFrameworkEntrypoint = isFrameworkEntrypoint(symbol, index);
-            const hasDecoratorMetadata = hasUnknownRegistrationDecorator(symbol);
+            const hasDecoratorMetadata = hasUnknownRegistrationDecorator(symbol, index);
+            if (lang === 'python' && packagingEntrypoints.some(entry => entry.unknown || runtimeTargetReaches(index, symbol, entry.target))) {
+                withhold(symbol, 'runtime-entrypoint');
+                continue;
+            }
+
+            if (langTraits(lang)?.reflectionApi?.pythonBindingIdentity && symbol.registrationUnknown === false &&
+                (symbol.decorators || []).length && pythonProjectIdentityAffected(index, 'builtins.*')) {
+                excludedDecorated++;
+                withhold(symbol, 'builtin-namespace-effect');
+                continue;
+            }
 
             // Unknown decorators are conservative runtime-registration
             // boundaries. A decorator necessarily consumes/replaces the
@@ -1653,6 +1711,19 @@ function deadcode(index, options = {}) {
                 continue;
             }
 
+            // The caller graph retains source spellings. Python can bind a
+            // different written identifier to this runtime name via NFKC;
+            // until that graph models the equivalence, do not clear it. The
+            // inventory is AST-only and shared by every symbol in this op.
+            if (langTraits(lang)?.reflectionApi?.pythonBindingIdentity &&
+                (pythonSourceName(symbol.name) !== symbol.name ||
+                 (symbol.runtimeOwnerPath || [symbol.className]).filter(Boolean)
+                     .some(owner => pythonSourceName(owner) !== owner) ||
+                 pythonNormalizedNames(index).has(pythonSourceName(symbol.name)))) {
+                withhold(symbol, 'identifier-normalization');
+                continue;
+            }
+
             const isExported = symbolIsExported(index, symbol, fileEntry);
 
             // `target.onmessage = function ...` / `target.onopen = (...) =>`
@@ -1707,7 +1778,7 @@ function deadcode(index, options = {}) {
                     continue;
                 }
                 if (members.some(m => isFrameworkEntrypoint(m, index) ||
-                    hasUnknownRegistrationDecorator(m))) {
+                    hasUnknownRegistrationDecorator(m, index))) {
                     if (!options.includeDecorated) {
                         excludedDecorated++;
                         withhold(symbol, 'registered');

package/core/deletion.js

@@ -13,11 +13,10 @@
  *   no-static-dependents   the name has no use in project source outside its
  *                          own declarations, and no shield applies: nothing
  *                          the engine can see depends on it;
- *   has-static-dependents  a call or other use of the name exists OUTSIDE
- *                          the declaration. The first such site is given.
- *                          Evidence is by name, as in the audit: with two
- *                          declarations of one name it does not say which
- *                          of them the use reaches;
+ *   has-static-dependents  a confirmed call or an unambiguous use exists
+ *                          OUTSIDE the declaration. The first such site is
+ *                          given. Unresolved name-only evidence remains
+ *                          review and never borrows another target's site;
  *   review                 no use outside the declaration was found, but a
  *                          zero is not evidence here: a shield applies
  *                          (consumers outside the repository, a contract, a
@@ -68,7 +67,10 @@ const DEPENDENT_REASONS = new Set(['has-callers', 'has-usages', 'member-in-use']
 /** Why the pipeline did or did not claim a declaration, in one sentence. */
 const REASON_TEXT = Object.freeze({
     'claimed': 'the name has no use in project source outside its own declarations, and no shield applies',
-    'has-callers': 'a call of this name exists outside the declaration',
+    'has-callers': 'a call is proven to reach this declaration from outside it',
+    'unresolved-use': 'uses of the name exist, but none is proven to reach this declaration',
+    'identifier-normalization': 'Python normalizes a source identifier spelling that the caller graph does not model',
+    'builtin-namespace-effect': 'project source can change the builtin namespace that this declaration relies on',
     'has-usages': 'the name is used outside the declaration',
     'member-in-use': 'a member of this type is called outside the declaration',
     'used-only-within-itself': 'every use found is inside the declaration itself, and the audit does not clear a name that is in use',
@@ -80,6 +82,7 @@ const REASON_TEXT = Object.freeze({
     'runtime-contract': 'invoked by the language runtime, the compiler or an assignment, not by name',
     'registered': 'decorated or registered with a framework, which may invoke it without naming it',
     'entry-point': 'an entry point the runtime or a test runner invokes',
+    'runtime-entrypoint': 'packaging metadata registers this declaration, or its runtime entrypoints cannot be resolved',
     'constructor': 'a constructor: part of its type\'s allocation protocol, assessed with the type',
     'reflection': 'reflection in the project can reach this name',
     'dynamic-dispatch': 'member of a registry that is called through a computed key',
@@ -177,7 +180,21 @@ function callSiteOutside(index, declaration, indexed, names) {
 function useOutsideDeclaration(index, declaration, indexed, deadcode, options) {
     const name = declaration.name;
     const call = callSiteOutside(index, declaration, indexed, [name]);
-    if (call) return { reason: 'has-callers', site: call };
+    if (!indexed) {
+        const definite = definiteDependentsOf(index, declaration).find(site => site.kind === 'call');
+        if (definite) return { reason: 'has-callers', site: { file: definite.file, line: definite.line } };
+    }
+    const duplicateName = (index.symbols.get(name) || []).some(def => !sameDeclaration(def, declaration));
+    if (call || duplicateName) {
+        const callers = index.findCallers(name, { targetDefinitions: [declaration], collectAccount: true,
+            includeMethods: true, maxResults: Infinity });
+        const proven = callers.filter(c => c.tier !== 'unverified' &&
+            !withinDeclaration(declaration, indexed, c.file || path.join(index.root, c.relativePath), c.line))
+            .map(c => ({ file: c.relativePath || relativeOf(index, c.file), line: c.line })).sort(compareSites);
+        if (proven.length) return { reason: 'has-callers', site: proven[0] };
+        // A callee index is a name inventory, not selected-target evidence.
+        // Its conservative audit veto survives without a misleading site.
+    }
     let found = null;
     deadcode(index, {
         names: new Set([name]),
@@ -196,13 +213,16 @@ function useOutsideDeclaration(index, declaration, indexed, deadcode, options) {
             } else if (reason === 'has-usages') {
                 const sites = ((detail && detail.usages) || [])
                     .filter(usage => !withinDeclaration(declaration, indexed, usage.file, usage.line))
+                    .filter(usage => !(index.getCachedCalls(usage.file) || []).some(candidate =>
+                        candidate.line === usage.line && !candidate.isFunctionReference &&
+                        (candidate.name === name || candidate.resolvedName === name)))
                     .map(usage => ({ file: relativeOf(index, usage.file), line: usage.line }))
                     .sort(compareSites);
-                if (sites.length > 0) found = { reason, site: sites[0] };
+                if (sites.length > 0) found = duplicateName ? { reason: 'unresolved-use' } : { reason, site: sites[0] };
             }
         },
     });
-    return found;
+    return found || (call ? { reason: 'unresolved-use' } : null);
 }
 
 /**

package/core/entrypoint-toml.js

@@ -0,0 +1,110 @@
+'use strict';
+
+// A data-only TOML reader for the PEP 621 entrypoint subtree. Other values
+// remain opaque; malformed or nonliteral entrypoint values return unknown.
+function entrypointToml(source) {
+    const tokens = [];
+    let line = 1;
+    let offset = 0;
+    while (offset < source.length) {
+        const ch = source[offset];
+        if (ch === '\n') { tokens.push({ kind: 'newline', line }); offset++; line++; continue; }
+        if (/\s/.test(ch)) { offset++; continue; }
+        if (ch === '#') { while (offset < source.length && source[offset] !== '\n') offset++; continue; }
+        if ('[]=.,{}'.includes(ch)) { tokens.push({ kind: ch, line }); offset++; continue; }
+        if (ch === '"' || ch === "'") {
+            const startLine = line;
+            const triple = source.slice(offset, offset + 3) === ch.repeat(3);
+            const delimiter = triple ? ch.repeat(3) : ch;
+            offset += delimiter.length;
+            let value = '';
+            let valid = true;
+            let closed = false;
+            while (offset < source.length) {
+                if (source.slice(offset, offset + delimiter.length) === delimiter) {
+                    offset += delimiter.length; closed = true; break;
+                }
+                const current = source[offset++];
+                if (current === '\n') line++;
+                if (current !== '\\' || ch === "'") { value += current; continue; }
+                const escaped = source[offset++];
+                const simple = { b: '\b', t: '\t', n: '\n', f: '\f', r: '\r', '"': '"', '\\': '\\' };
+                if (Object.hasOwn(simple, escaped)) value += simple[escaped];
+                else if (escaped === 'u' || escaped === 'U') {
+                    const width = escaped === 'u' ? 4 : 8;
+                    const digits = source.slice(offset, offset + width);
+                    if (!/^[0-9a-fA-F]+$/.test(digits) || digits.length !== width || parseInt(digits, 16) > 0x10ffff) valid = false;
+                    else value += String.fromCodePoint(parseInt(digits, 16));
+                    offset += width;
+                } else if (triple && /\s/.test(escaped || '')) {
+                    if (escaped === '\n') line++;
+                    while (offset < source.length && /\s/.test(source[offset])) {
+                        if (source[offset++] === '\n') line++;
+                    }
+                } else valid = false;
+            }
+            tokens.push({ kind: 'string', value: valid && closed ? value.replace(/^\n/, '') : null, line: startLine });
+            continue;
+        }
+        const start = offset;
+        while (offset < source.length && !/[\s[\]=.,{}#]/.test(source[offset])) offset++;
+        if (offset === start) offset++;
+        tokens.push({ kind: 'bare', value: source.slice(start, offset), line });
+    }
+    const rows = [];
+    let at = 0;
+    let section = [];
+    const keys = () => {
+        const parts = [];
+        while (tokens[at] && ['bare', 'string'].includes(tokens[at].kind)) {
+            parts.push(tokens[at++].value);
+            if (tokens[at]?.kind !== '.') break;
+            at++;
+        }
+        return parts;
+    };
+    const entryPath = parts => parts[0] === 'project' &&
+        (['scripts', 'gui-scripts'].includes(parts[1]) || parts[1] === 'entry-points');
+    const readValue = (parts, depth = 0) => {
+        const token = tokens[at++];
+        if (!token || depth > 32) { if (entryPath(parts)) rows.push({ unknown: true, line: token?.line }); return; }
+        if (token.kind === '{') {
+            while (tokens[at] && tokens[at].kind !== '}') {
+                if (['newline', ','].includes(tokens[at].kind)) { at++; continue; }
+                const nested = keys();
+                if (!nested.length || tokens[at++]?.kind !== '=') { if (entryPath(parts)) rows.push({ unknown: true, line: token.line }); break; }
+                readValue([...parts, ...nested], depth + 1);
+            }
+            if (tokens[at]?.kind === '}') at++;
+        } else if (token.kind === '[') {
+            let balance = 1;
+            while (tokens[at] && balance) {
+                const item = tokens[at++];
+                if (item.kind === '[') balance++;
+                if (item.kind === ']') balance--;
+                if (parts.join('.') === 'project.dynamic' && item.kind === 'string' &&
+                    ['scripts', 'gui-scripts', 'entry-points'].includes(item.value)) rows.push({ unknown: true, line: item.line });
+            }
+            if (entryPath(parts)) rows.push({ unknown: true, line: token.line });
+        } else if (entryPath(parts)) {
+            rows.push(token.kind === 'string' && token.value != null
+                ? { value: token.value, line: token.line } : { unknown: true, line: token.line });
+        }
+    };
+    while (at < tokens.length) {
+        if (tokens[at].kind === 'newline') { at++; continue; }
+        if (tokens[at].kind === '[') {
+            at++;
+            section = keys();
+            while (tokens[at] && ![']', 'newline'].includes(tokens[at].kind)) at++;
+            if (tokens[at]?.kind === ']') at++;
+            continue;
+        }
+        const parts = keys();
+        if (parts.length && tokens[at]?.kind === '=') { at++; readValue([...section, ...parts]); }
+        else while (tokens[at] && tokens[at].kind !== 'newline') at++;
+    }
+    return rows;
+}
+
+module.exports = { entrypointToml };

package/core/index-ir.js

@@ -185,7 +185,7 @@ const OPTIONAL_SYMBOL_FIELDS = Object.freeze([
     'isGenerator', 'generics', 'ownerGenerics', 'genericBounds', 'typeParameterConstraints', 'extends', 'implements', 'indent', 'isNested',
     'enclosingType', 'isMethod', 'receiver', 'memberType', 'fieldType', 'embedded',
     'aliasOf', 'aliasQualifier', 'aliasMembers', 'aliasTypeText', 'aliasTypeParameters', 'aliasTypeDefaults', 'derefTarget', 'decorators', 'decoratorsWithArgs',
-    'annotationsWithArgs', 'attributesWithArgs', 'nameLine', 'traitImpl',
+    'annotationsWithArgs', 'attributesWithArgs', 'registrationUnknown', 'runtimeOwnerPath', 'nameLine', 'traitImpl',
     'traitName', 'isSignature', 'memberAssigned', 'assignedReceiver', 'assignedObject', 'selfNamed', 'bodyScopedName',
     'registryMember', 'registryContainer', 'registryContainerType', 'objectLiteralLine', 'namespace', 'isConstructor',
     'isExtensionMethod', 'extensionReceiver', 'explicitInterface', 'primaryParams',
@@ -230,7 +230,7 @@ function materializeSymbol(fileEntry, item) {
         // Most false feature flags are omitted for compactness, but
         // functionLike=false is the semantic distinction between an
         // object-like macro and a callable macro (UCN5-170).
-        if (item[field] === false && field !== 'functionLike') continue;
+        if (item[field] === false && field !== 'functionLike' && field !== 'registrationUnknown') continue;
         symbol[field] = item[field];
     }
     return symbol;

package/core/ir.js

@@ -66,7 +66,7 @@ function normalizeSymbol(symbol, family, language, kind, owner = null) {
         'isAsync', 'isGenerator', 'generics', 'ownerGenerics', 'genericBounds', 'typeParameterConstraints', 'extends', 'implements', 'indent',
         'isNested', 'enclosingType', 'isMethod', 'memberType', 'fieldType', 'embedded',
         'aliasOf', 'aliasQualifier', 'aliasMembers', 'aliasTypeText', 'aliasTypeParameters', 'aliasTypeDefaults', 'derefTarget', 'decorators', 'decoratorsWithArgs',
-        'annotationsWithArgs', 'attributesWithArgs', 'nameLine', 'traitImpl',
+        'annotationsWithArgs', 'attributesWithArgs', 'registrationUnknown', 'runtimeOwnerPath', 'nameLine', 'traitImpl',
         'traitName', 'isSignature', 'memberAssigned', 'assignedReceiver', 'assignedObject', 'selfNamed', 'bodyScopedName',
         'registryMember', 'registryContainer', 'registryContainerType', 'objectLiteralLine', 'isConstructor',
         'isExtensionMethod', 'extensionReceiver', 'explicitInterface', 'primaryParams',

package/core/outgoing-check.js

@@ -0,0 +1,116 @@
+/** Validate changed calls against the project declarations they can reach. */
+'use strict';
+
+const { getCachedCalls } = require('./callers');
+const { verifyCallSites } = require('./verify');
+const { langTraits } = require('../languages');
+const { positivelyFits } = require('./call-fit');
+
+/** One reader and result cache for a check, including all changed symbols. */
+function outgoingChecker(index, judge, addedLinesByFile) {
+    const files = new Map();
+    const checked = new Map();
+    const read = file => {
+        if (!files.has(file)) files.set(file, {
+            calls: getCachedCalls(index, file) || [], lines: index._getFileLines(file),
+        });
+        return files.get(file);
+    };
+    return (definition, change, added) => {
+        const mismatches = [];
+        const unsettled = [];
+        if (!definition) return { mismatches, unsettled };
+        const data = read(definition.file);
+        const changedRanges = !added ? change?.changedCalls : null;
+        const lines = addedLinesByFile.get(definition.relativePath) || new Set();
+        const records = data.calls.filter(call => !call.isFunctionReference &&
+            call.line >= definition.startLine && call.line <= definition.endLine &&
+            (changedRanges ? changedRanges.some(range =>
+                range.start <= (call.callStart ?? call.callSite?.start) &&
+                range.end >= (call.callEnd ?? call.callSite?.end ?? call.callStart ?? call.callSite?.start))
+                : added || lines.has(call.line)));
+        if (records.length === 0) return { mismatches, unsettled };
+        const byStart = new Map(records.map(call => [call.callStart ?? call.callSite?.start, call]));
+        const callees = index.findCallees(definition, {
+            collectAccount: true, includeMethods: true, siteStarts: new Set(byStart.keys()),
+        });
+        const relative = definition.relativePath;
+        const positiveFamilies = new Set();
+        const possibleFamilies = new Set();
+        const issues = [];
+        const familyOf = (callee, site) => {
+            // The class's public constructor overloads are the call
+            // interface; an initializer edge also projects their body.
+            const owner = callee.initializerOf || (callee.type === 'class' ? callee.name : null);
+            return JSON.stringify([site.start, callee.file, owner || callee.name,
+                owner ? null : callee.className, callee.namespace, callee.enclosingType]);
+        };
+        const uncertain = (site, name, reason) => unsettled.push({ file: relative, line: site.line, column: site.column, name, reason });
+        for (const callee of callees) {
+            if (callee.functionReference) continue;
+            for (const site of callee.siteProvenance || []) {
+                const record = byStart.get(site.start);
+                if (!record) continue;
+                const family = familyOf(callee, site);
+                const key = JSON.stringify([definition.file, site.start, callee.file, callee.startLine,
+                    callee.sourceSpan?.start, callee.sourceSpan?.end, callee.name, callee.className,
+                    callee.type, callee.paramsStructured]);
+                let result = checked.get(key);
+                if (!result) {
+                    result = verifyCallSites(index, callee, [{
+                        ...record, file: definition.file, relativePath: relative,
+                        content: data.lines[site.line - 1] || '', calledAs: record.name,
+                        provenance: site.provenance,
+                        callerFile: definition.file, callerStartLine: definition.startLine,
+                    }]);
+                    checked.set(key, result);
+                }
+                for (const mismatch of result.mismatchDetails || []) {
+                    const counts = String(mismatch.expected || '').match(/\d+/g);
+                    const suppressed = judge.suppressed(mismatch, {
+                        kind: 'arity', name: callee.name,
+                        most: counts ? Number(counts[counts.length - 1]) : undefined,
+                        span: mismatch.span, problem: mismatch.problem, indirect: mismatch.indirect,
+                    });
+                    // JavaScript deliberately permits omitted and extra
+                    // arguments. A declared count is not runtime proof.
+                    const flexible = langTraits(index.files.get(definition.file)?.language)?.lenientCallArity === true;
+                    if ((callee.decorators || []).length) uncertain(site, callee.name, 'decorated-call-interface');
+                    else if (flexible) uncertain(site, callee.name, 'call-arity-not-enforced');
+                    else issues.push({ family, site, callee, mismatch: {
+                        ...mismatch, column: site.column, target: callee.name, ...(suppressed && { unchecked: true }),
+                    } });
+                }
+                if (result.valid > 0 || result.uncertain > 0) possibleFamilies.add(family);
+                for (const row of result.uncertainDetails || []) issues.push({ family, site, callee, reason: row.reason });
+                if (result.valid > 0) {
+                    const preserved = changedRanges?.some(range => range.stableInvocation &&
+                        range.start <= site.start && range.end >= (record.callEnd ?? record.callSite?.end ?? site.start));
+                    if (positivelyFits(index, callee, definition, record, result, preserved)) positiveFamilies.add(family);
+                    else issues.push({ family, site, callee, reason: 'argument-compatibility-unverified' });
+                }
+            }
+        }
+        // Overload declarations describe one call interface. A positively
+        // fitting alternative settles it; a merely possible alternative
+        // prevents a different signature's arity from claiming a break.
+        for (const issue of issues) {
+            if (positiveFamilies.has(issue.family)) continue;
+            if (issue.mismatch && !possibleFamilies.has(issue.family)) mismatches.push(issue.mismatch);
+            else uncertain(issue.site, issue.callee.name, issue.reason || 'overload-compatibility-unverified');
+        }
+        for (const entry of [...(callees.unverifiedCallees || []), ...(callees.initializerReviews || [])]) {
+            // External packages are outside this fit check. A candidate
+            // project declaration, however, cannot silently become READY.
+            if (!(entry.ownerCount > 0 || entry.initializerOf || index.symbols.has(entry.name))) continue;
+            for (const site of entry.siteProvenance || []) {
+                if (byStart.has(site.start)) uncertain(site, entry.name, entry.reason || 'outgoing-target-unresolved');
+            }
+        }
+        const unique = rows => [...new Map(rows.map(row => [JSON.stringify(row), row])).values()]
+            .sort((a, b) => a.line - b.line || (a.column || 0) - (b.column || 0) || ((a.name || a.target || '') < (b.name || b.target || '') ? -1 : (a.name || a.target || '') > (b.name || b.target || '') ? 1 : 0));
+        return { mismatches: unique(mismatches), unsettled: unique(unsettled) };
+    };
+}
+
+module.exports = { outgoingChecker };

package/core/output/check.js

@@ -10,8 +10,8 @@
 
 const SECTIONS = [
     ['blocked', 'BLOCKED', 'a break was observed'],
-    ['review', 'REVIEW', 'can reach existing code; not settled by the engine'],
-    ['ready', 'READY', 'nothing that existed depends on the change'],
+    ['review', 'REVIEW', 'change exposure or call requirements not settled'],
+    ['ready', 'READY', 'no unresolved exposure in the modeled checks'],
 ];
 // Occurrences of a name are context, not a worklist: a head is enough.
 const NAME_SITE_LIMIT = 10;
@@ -50,6 +50,9 @@ function itemLines(it) {
         const expression = m.expression ? `  ${String(m.expression).trim()}` : '';
         lines.push(`    ↳ ${where}${expression}  ${problem}${m.unchecked ? '  (not checked by the toolchain)' : ''}`);
     }
+    for (const site of it.outgoingReview || []) {
+        lines.push(`    ↳ ${site.file}:${site.line}${site.column != null ? `:${site.column + 1}` : ''}  ${site.name}: ${site.reason}`);
+    }
     const sites = it.sites || [];
     const definite = it.verdict === 'blocked';
     const shown = definite ? sites : sites.slice(0, NAME_SITE_LIMIT);

package/core/output/reporting.js

@@ -218,6 +218,8 @@ function formatDeadcode(results, options = {}) {
         !results.excludedDynamicDispatch && !results.excludedRequiredSlot &&
         results.projectKind !== 'application' && !results.computedDispatch?.count &&
         !results.reflection?.withheld && !results.reflection?.dynamicCount && !results.reflection?.literalCount &&
+        !results.reflection?.withheldByTable?.length && !results.macroPaste?.withheld &&
+        !results.macroPaste?.blind?.count && !results.macroRulesBlind?.count &&
         results.coverage?.complete !== false) {
         return 'No dead code found.';
     }
@@ -233,6 +235,8 @@ function formatDeadcode(results, options = {}) {
         } else {
             lines.push(`Dead code: ${results.length} unused symbol(s)\n`);
         }
+    } else {
+        lines.push('Dead code: 0 unused symbol(s)\n');
     }
 
     let currentFile = null;

package/core/output/search.js

@@ -438,6 +438,9 @@ function formatTests(tests, name) {
             }
             if (testFile.run) lines.push(`  run: ${selectorText(testFile.run)}`);
             else if (testFile.role === 'tests' && testFile.runWithheld) lines.push(`  no command: ${testFile.runWithheld}`);
+            for (const unit of testFile.units || []) {
+                if (unit.selector) lines.push(`  run test: ${selectorText(unit.selector)}`);
+            }
             lines.push('');
         }
     }

package/core/output/tracing.js

@@ -619,7 +619,7 @@ function formatAffectedTests(result, options = {}) {
         }
         const pat = result.possiblyAffectedTests || [];
         if (pat.length > 0) {
-            lines.push(`  Additional test files (${pat.length}):`);
+            lines.push(`  Test files with possible links (${pat.length}):`);
             const MAX_POSSIBLE = options.all ? Infinity : 10;
             for (const tf of pat.slice(0, MAX_POSSIBLE)) {
                 lines.push(`    ${tf.file} (links: ${linkList(tf.linkedFunctions, options)})`);