ucn 5.6.0 → 5.6.1

package/core/change-kinds.js

@@ -54,6 +54,9 @@ const CASE_NODES = new Set(['switch_case', 'switch_default']);
 // after the block is reached is a property of the manager.
 const MANAGER_NODES = new Set(['with_statement', 'with_clause']);
 const CALL_NODES = new Set(['call_expression', 'call']);
+// Invocation syntax across the parsers; member references are not calls.
+const OUTGOING_CALL_NODES = new Set(['call_expression', 'call', 'method_invocation',
+    'invocation_expression', 'object_creation_expression', 'new_expression']);
 const AWAIT_NODES = new Set(['await_expression', 'await']);
 
 // Nodes that hold declarations rather than being one: a callable's
@@ -120,6 +123,29 @@ function tokensOf(node, skip, out = []) {
     return out;
 }
 
+// A baseline invocation is reused only when the whole callable still has
+// the same written context, apart from direct primitive call arguments.
+// This is a preservation premise, not a proof that an arbitrary new call
+// is available (access, generics, receiver modes and result use included).
+const DIRECT_LITERAL_NODES = new Set(['number', 'integer', 'float', 'number_literal',
+    'integer_literal', 'int_literal', 'decimal_integer_literal', 'float_literal', 'real_literal',
+    'string', 'string_literal', 'true', 'false', 'boolean_literal']);
+function invocationTokens(node, out = []) {
+    if (!node || COMMENT_NODES.has(node.type)) return out;
+    const parent = node.parent;
+    const list = parent?.type === 'argument' && parent.childCount === 1 ? parent.parent : parent;
+    if (DIRECT_LITERAL_NODES.has(node.type) && list &&
+        ['arguments', 'argument_list'].includes(list.type)) {
+        const kind = ['true', 'false', 'boolean_literal'].includes(node.type) ? 'boolean'
+            : ['string', 'string_literal'].includes(node.type) && ['"', "'"].includes(node.text[0]) ? 'string'
+                : /^\d+$/.test(node.text) && Number(node.text) <= 127 ? 'smallInteger' : null;
+        if (kind) { out.push(['argument-literal', kind]); return out; }
+    }
+    if (node.childCount === 0) { out.push([node.type, node.text]); return out; }
+    for (const child of node.children) invocationTokens(child, out);
+    return out;
+}
+
 function identifiersOf(node, out = new Set()) {
     if (!node) return out;
     if (node.childCount === 0) {
@@ -659,7 +685,102 @@ function callableContract(root, language, symbol, context = null) {
         }
         memberBindings = JSON.stringify(parts.sort());
     }
-    return { header: JSON.stringify(header), generator, returnForm, inferred, derivation, memberBindings };
+    const outgoingCalls = [];
+    const contextStatements = [];
+    // Native comment queries preserve extra-node identity. The binding's
+    // ordinary children wrappers can expose a Python inline-suite comment
+    // as a zero-child block, so type-testing that walk loses directives.
+    const bodyComments = body ? body.descendantsOfType([...COMMENT_NODES]) : [];
+    const commentSpans = new Set(bodyComments.map(comment => `${comment.startIndex}:${comment.endIndex}`));
+    const comments = bodyComments.filter(comment => traits.checkDirectiveComment?.(comment.text));
+    const visit = candidate => {
+        if (OUTGOING_CALL_NODES.has(candidate.type)) outgoingCalls.push({ node: candidate,
+            start: candidate.startIndex, end: candidate.endIndex });
+        if (!sameNode(candidate, body) && (bindingTargets(candidate).length || STATEMENT_SHAPE.test(candidate.type))) {
+            contextStatements.push(candidate);
+        }
+        return true;
+    };
+    if (body) { visit(body); walkOwn(body, visit); }
+    const parameters = node.childForFieldName('parameters') || node.childForFieldName('parameter');
+    // A discard occupies syntax but introduces no binding. Its spelling
+    // must not connect otherwise independent statements (Go `_ = 0`).
+    // Keep all invocation/RHS tokens: discarding a result does not erase
+    // the call that produces it.
+    const dependencyNames = candidate => [...identifiersOf(candidate)]
+        .filter(name => !(traits.discardIdentifierNames || []).includes(name));
+    const contextFacts = contextStatements.map(statement => ({
+        names: dependencyNames(statement), tokens: tokensOf(statement),
+    }));
+    const statementsByName = new Map();
+    contextFacts.forEach((fact, position) => {
+        for (const name of fact.names) {
+            if (!statementsByName.has(name)) statementsByName.set(name, []);
+            statementsByName.get(name).push(position);
+        }
+    });
+    // Checker comment position is measured against code tokens, so blank
+    // lines and ordinary comments do not change the call's applicability.
+    const sourceTokens = [];
+    const collectTokens = candidate => {
+        if (!candidate || COMMENT_NODES.has(candidate.type) ||
+            commentSpans.has(`${candidate.startIndex}:${candidate.endIndex}`)) return;
+        if (candidate.childCount === 0) { sourceTokens.push(candidate); return; }
+        for (const child of candidate.children) collectTokens(child);
+    };
+    if (comments.length) collectTokens(body);
+    const tokenPosition = offset => {
+        let low = 0;
+        let high = sourceTokens.length;
+        while (low < high) {
+            const mid = (low + high) >>> 1;
+            if (sourceTokens[mid].startIndex < offset) low = mid + 1;
+            else high = mid;
+        }
+        return low;
+    };
+    const commentFacts = comments.map(comment => {
+        const at = tokenPosition(comment.startIndex);
+        return [comment.text, at,
+            sourceTokens[at - 1]?.endPosition.row === comment.startPosition.row,
+            sourceTokens[at]?.startPosition.row === comment.endPosition.row];
+    });
+    const invocationContext = JSON.stringify([invocationTokens(declaration), commentFacts]);
+    for (const call of outgoingCalls) {
+        // A call's own tokens do not establish its meaning. Follow the
+        // written bindings of its callee, receiver and arguments (including
+        // aliases), and retain the checker comments around it.
+        const names = dependencyNames(call.node);
+        const seenNames = new Set(names);
+        const selected = new Set();
+        for (let at = 0; at < names.length; at++) {
+            for (const position of statementsByName.get(names[at]) || []) {
+                if (selected.has(position)) continue;
+                selected.add(position);
+                for (const name of contextFacts[position].names) {
+                    if (!seenNames.has(name)) { seenNames.add(name); names.push(name); }
+                }
+            }
+        }
+        const nesting = [];
+        for (let parent = call.node.parent; parent && !sameNode(parent, body); parent = parent.parent) {
+            nesting.push(parent.type);
+        }
+        call.invocationKey = JSON.stringify(invocationTokens(call.node));
+        const relevantParameters = (parameters?.namedChildren || []).filter(parameter =>
+            dependencyNames(parameter).some(name => seenNames.has(name)));
+        const returnsValue = sameNode(call.node, body) || nesting.some(type => RESULT_NODES.has(type));
+        call.key = JSON.stringify([tokensOf(call.node), relevantParameters.map(parameter => tokensOf(parameter)),
+            returnsValue ? symbol.returnType || null : null, nesting,
+            [...selected].sort((a, b) => a - b).map(position => contextFacts[position].tokens),
+            commentFacts.map(([text, at, prior, next]) => [text, at - tokenPosition(call.node.startIndex), prior, next])]);
+        delete call.node;
+    }
+    const contract = { header: JSON.stringify(header), generator, returnForm, inferred, derivation, memberBindings };
+    Object.defineProperties(contract, {
+        outgoingCalls: { value: outgoingCalls }, invocationContext: { value: invocationContext },
+    });
+    return contract;
 }
 
 /**
@@ -680,7 +801,20 @@ function classifyChange(before, after, language) {
         reasons.push('inferred-return-contract');
     }
     if ((before.memberBindings || null) !== (after.memberBindings || null)) reasons.push('inferred-member-type');
-    return { kind: reasons.length > 0 ? 'contract' : 'inert', reasons };
+    const change = { kind: reasons.length > 0 ? 'contract' : 'inert', reasons };
+    // Moving or formatting a call does not make it a new call. Repeated
+    // calls are counted, so an extra occurrence is still checked.
+    const prior = new Map();
+    for (const call of before.outgoingCalls || []) prior.set(call.key, (prior.get(call.key) || 0) + 1);
+    const preserved = new Set((before.outgoingCalls || []).map(call => call.invocationKey));
+    const changedCalls = (after.outgoingCalls || []).filter(call => {
+        const left = prior.get(call.key) || 0;
+        if (left) { prior.set(call.key, left - 1); return false; }
+        call.stableInvocation = before.invocationContext === after.invocationContext && preserved.has(call.invocationKey);
+        return true;
+    });
+    Object.defineProperty(change, 'changedCalls', { value: changedCalls });
+    return change;
 }
 
 /** The declaration in the base revision that a changed one continues. */
@@ -821,6 +955,90 @@ function removedFrom(before, after) {
     return removed;
 }
 
+/** Checker comments carry semantics even when no declaration changed. */
+function checkingContext(root, traits) {
+    if (!root || !traits.checkDirectiveComment) return null;
+    const all = root.descendantsOfType([...COMMENT_NODES]);
+    const comments = all.filter(node => traits.checkDirectiveComment(node.text));
+    if (comments.length === 0) return null;
+    const barriers = all.filter(node => !traits.checkDirectiveComment(node.text) && traits.checkDirectiveBarrier?.(node.text));
+    const spans = new Set(all.map(node => `${node.startIndex}:${node.endIndex}`));
+    const code = [];
+    const scopeCounts = new Map();
+    const walk = (node, scope = []) => {
+        if (spans.has(`${node.startIndex}:${node.endIndex}`)) return;
+        if (CALLABLE_NODES.has(node.type) || ['class', 'class_declaration', 'class_definition'].includes(node.type)) {
+            const body = node.childForFieldName('body');
+            if (body) {
+                const header = tokensOf(node, body);
+                const key = JSON.stringify([scope, node.type, header]);
+                const ordinal = scopeCounts.get(key) || 0;
+                scopeCounts.set(key, ordinal + 1);
+                scope = [...scope, [node.type, header, ordinal]];
+            }
+        }
+        if (node.childCount === 0) code.push({ node, scope });
+        else for (const child of node.children) walk(child, scope);
+    };
+    walk(root);
+    // Identify the neighboring code by its line tokens and declaration,
+    // not by an absolute token offset. An inert edit in an earlier body
+    // cannot move a later directive onto different code. Repeated equal
+    // lines retain an occurrence number, so moving a suppression between
+    // identical calls still changes its attachment.
+    const lines = [];
+    for (const entry of code) {
+        let line = lines[lines.length - 1];
+        if (!line || line.row !== entry.node.startPosition.row) {
+            line = { row: entry.node.startPosition.row, entries: [] };
+            lines.push(line);
+        }
+        entry.line = line;
+        entry.column = line.entries.length;
+        line.entries.push(entry);
+    }
+    const lineCounts = new Map();
+    for (const line of lines) {
+        line.key = JSON.stringify(line.entries.map(({ node, scope }) => [node.type, node.text, scope]));
+        line.ordinal = lineCounts.get(line.key) || 0;
+        lineCounts.set(line.key, line.ordinal + 1);
+    }
+    const anchor = entry => entry ? [entry.line.key, entry.line.ordinal, entry.column] : null;
+    const position = node => {
+        let low = 0;
+        let high = code.length;
+        while (low < high) {
+            const middle = (low + high) >>> 1;
+            if (code[middle].node.startIndex < node.startIndex) low = middle + 1;
+            else high = middle;
+        }
+        const at = [anchor(code[low - 1]), anchor(code[low]),
+            code[low - 1]?.node.endPosition.row === node.startPosition.row,
+            code[low]?.node.startPosition.row === node.endPosition.row];
+        return { at, nextRow: code[low]?.node.startPosition.row };
+    };
+    return JSON.stringify([
+        comments.map(node => {
+            const mode = traits.checkFileDirectiveComment?.(node.text) || 'local';
+            const { at, nextRow } = position(node);
+            let attachment;
+            if (mode === 'column-zero-file') attachment = node.startPosition.column === 0;
+            else if (mode === 'local' || mode === 'leading-or-local' && at[0] !== null) {
+                if (traits.checkDirectiveTarget === 'next-line') {
+                    // A line directive applies forward. Earlier code is
+                    // not its target; a block comment matters only if it
+                    // occupies a line between the directive and its code.
+                    const blocked = barriers.some(barrier =>
+                        barrier.startPosition.row < nextRow &&
+                        barrier.endPosition.row > node.endPosition.row);
+                    attachment = [at[1], at[2], at[3], blocked];
+                } else attachment = at;
+            } else attachment = mode === 'file' || at[0] === null;
+            return [node.text, mode, attachment];
+        }),
+    ]);
+}
+
 /**
  * What a change did to a module outside its declarations.
  *
@@ -852,6 +1070,7 @@ function moduleChange(before, after, traits) {
     const exported = explicit(before.fileEntry);
     return {
         removedNames,
+        checkingChanged: checkingContext(before.root, traits) !== checkingContext(after.root, traits),
         removedExports: removedNames.filter(name => exported.has(name)),
         // The module passed on everything another module exports, and no
         // longer does: which names that took away is not written here.

package/core/check.js

@@ -21,10 +21,13 @@
  *   blocked    a break was observed: a confirmed call site that no longer
  *              fits the signature, an import of a name its module no
  *              longer has, a bare call nothing is left to answer.
- *   review     the change can reach existing code and the engine cannot
- *              settle whether it breaks: the reason is named and the sites
- *              are listed.
- *   ready      nothing that existed before depends on what changed.
+ *   review     change exposure or call requirements are not settled:
+ *              the reason is named and the sites are listed.
+ *   ready      no unresolved exposure remains in the modeled checks.
+ *
+ * A changed outgoing call is checked too. Positive argument fit preserves
+ * a baseline invocation only in an unchanged written context; it is not a
+ * compiler proof for arbitrary new calls or surrounding expressions.
  *
  * TRUST is the worst verdict among the items. BLOCKED means a definite
  * break, or that the check itself could not run. It never means "there is
@@ -35,14 +38,15 @@
 
 const { diffImpact, composeAccount, callNotResolvedEntries } = require('./analysis');
 const { providedNames } = require('./change-kinds');
+const { outgoingChecker } = require('./outgoing-check');
 const fs = require('fs');
 const path = require('path');
 const { isValueDefinition, isTestPath } = require('./shared');
 const { langTraits } = require('../languages');
 const { assessDeletion, definiteDependentsOf, REASON_TEXT } = require('./deletion');
-const { occurrencesOutsideChange, captureHazards, shapeChangeOf, literalsLackingMember, HAZARD_TEXT } = require('./capture');
+const { occurrencesOutsideChange, captureHazards, shapeChangeOf, literalsLackingMember, newOwnerUnreached, HAZARD_TEXT } = require('./capture');
 const { reviewItemsOf } = require('./review-items');
-const { createTestModel, linkFiles, commandsFor } = require('./test-units');
+const { createTestModel, linkFiles, commandsFor, testSiteKey } = require('./test-units');
 // Reasons a file has no command that are about the file, not the runner.
 const FILE_WOULD_NOT_RUN = new Set(['declared-indirectly', 'collection-switched-off', 'conditional-tests']);
 const { resolveTarget, flaggedPaths } = require('./snapshot');
@@ -65,6 +69,7 @@ const MODULE_TEXT = Object.freeze({
     'no-longer-provided': 'other files import a name from this module that it no longer provides',
     'import-removed-still-used': 'an import was removed and the file still uses the name it bound',
     'imports-removed': 'a module the file imported or included without binding a name is no longer imported',
+    'checking-context-changed': 'checker directives changed; previously unchecked source may now be checked',
     'module-level-code': 'code outside any declaration changed; what runs when the module loads is not modeled',
     'name-in-use': 'a new import binds a name the file already used',
     'downstream-exposure': 'a name left the exports of a library: consumers outside the repository may use it',
@@ -167,7 +172,10 @@ function callersOf(index, name, definition) {
  */
 function assessAddition(index, entry, definition, addedLinesByFile, account, judge, nonCallable = false) {
     if (!definition) return { verdict: 'review', reasons: ['declaration-not-indexed'] };
-    const occurrences = occurrencesOutsideChange(index, entry.name, addedLinesByFile, definition);
+    const ownerExisted = ownerExistedBefore(index, definition, addedLinesByFile);
+    const occurrences = !ownerExisted && newOwnerUnreached(index, definition, addedLinesByFile)
+        ? { outside: [], total: 0 }
+        : occurrencesOutsideChange(index, entry.name, addedLinesByFile, definition);
     const summary = summarizeAccount(account);
     const reasons = [];
     if (occurrences.outside.length > 0) reasons.push('name-in-use');
@@ -182,7 +190,6 @@ function assessAddition(index, entry, definition, addedLinesByFile, account, jud
     try {
         contract = require('./deadcode').contractFactsOf(index, definition, index.files.get(definition.file)?.language);
     } catch (_) { contract = null; }
-    const ownerExisted = ownerExistedBefore(index, definition, addedLinesByFile);
     let shape;
     try { shape = ownerExisted ? shapeChangeOf(index, definition, addedLinesByFile) : null; } catch (_) { shape = 'shape'; }
     const hazards = captureHazards(index, definition, { ownerExisted, contract, shield, nonCallable, shape });
@@ -403,6 +410,7 @@ function assessModuleChange(index, moved, judge) {
     // Loose code in a test file is the test: nothing imports it for
     // what it does when it loads.
     if (moved.codeChanged && !isTestPath(moved.relativePath)) reasons.push('module-level-code');
+    if (moved.checkingChanged) reasons.push('checking-context-changed');
     if ((moved.shadowed || []).length > 0) reasons.push('name-in-use');
     return {
         verdict: reasons.length > 0 ? 'review' : 'ready', reasons,
@@ -686,6 +694,7 @@ function check(live, options = {}) {
         }
         throw e;
     }
+    target.index._beginOp();
     try {
         const result = checkTarget(target.index, options, target.repoRoot);
         const notes = [...target.notes];
@@ -703,6 +712,7 @@ function check(live, options = {}) {
         if (notes.length > 0 && result && result.ok !== false) result.notes = notes;
         return result;
     } finally {
+        target.index._endOp();
         target.dispose();
     }
 }
@@ -848,6 +858,26 @@ function checkTarget(index, options, repoRoot) {
     const changed = limit ? allChanged.slice(0, limit) : allChanged;
 
     const items = [];
+    const outgoing = outgoingChecker(index, judge, addedLinesByFile);
+    const withOutgoing = (item, fn) => {
+        if (fn._kind === 'deleted') return item;
+        const result = outgoing(definitionOf(index, fn), fn.change, fn._kind === 'added');
+        if (!result.mismatches.length && !result.unsettled.length) return item;
+        const blocking = result.mismatches.filter(row => !row.unchecked).length;
+        item.signatureMismatches += blocking;
+        if (result.mismatches.length) item.mismatches = [...(item.mismatches || []), ...result.mismatches];
+        if (result.unsettled.length) item.outgoingReview = result.unsettled;
+        if (blocking) {
+            item.verdict = 'blocked';
+            item.reasons = [...new Set(['outgoing-signature-mismatch', ...item.reasons])];
+        } else {
+            if (item.verdict === 'ready') item.verdict = 'review';
+            item.reasons = [...new Set([...item.reasons,
+                ...(result.mismatches.length ? ['site-not-checked'] : []),
+                ...(result.unsettled.length ? ['outgoing-call-unverified'] : [])])];
+        }
+        return item;
+    };
 
     for (const fn of changed) {
         const filePath = fn.relativePath || fn.file || '';
@@ -897,7 +927,7 @@ function checkTarget(index, options, repoRoot) {
                 item.verdict = 'review';
                 item.reasons = [valueDeclaration ? 'value-change' : 'declaration-change'];
             }
-            items.push(item);
+            items.push(withOutgoing(item, fn));
             continue;
         }
 
@@ -920,7 +950,7 @@ function checkTarget(index, options, repoRoot) {
                 // The contract every caller relies on is untouched.
                 item.verdict = 'ready';
                 item.reasons = [];
-                items.push(item);
+                items.push(withOutgoing(item, fn));
                 continue;
             }
             // The base revision decides which call sites the changed
@@ -975,7 +1005,7 @@ function checkTarget(index, options, repoRoot) {
                 }
             }
             item.reviewItems = reviewItemsOf(unverifiedCallers);
-            items.push(item);
+            items.push(withOutgoing(item, fn));
             continue;
         }
 
@@ -1010,7 +1040,7 @@ function checkTarget(index, options, repoRoot) {
             try { isEntry = isEntry || !!adapter?.isEntryPoint?.(definition); } catch (_) { /* keep */ }
             item.orphan = !isEntry;
         }
-        items.push(item);
+        items.push(withOutgoing(item, fn));
     }
 
     // Deleted callables: the base revision's declaration, assessed against
@@ -1067,6 +1097,7 @@ function checkTarget(index, options, repoRoot) {
                 className: fn.className || undefined,
                 _callerCache: callerCache,
                 _testModel: model,
+                _testSitesOnly: true,
             });
         } catch (e) {
             t = null;
@@ -1074,12 +1105,14 @@ function checkTarget(index, options, repoRoot) {
         for (const tf of (t && t.testFiles) || []) {
             let held = linesByFile.get(tf.file);
             if (!held) {
-                held = { row: tf, lines: new Set(), linked: new Set() };
+                held = { row: tf, lines: new Map(), linked: new Set() };
                 linesByFile.set(tf.file, held);
             }
             for (const name of tf.linkedFunctions || []) held.linked.add(name);
             for (const match of tf.matches || []) {
-                if (match.matchType === 'call' || match.matchType === 'test-case') held.lines.add(match.line);
+                if (match.matchType === 'call' || match.matchType === 'test-case') {
+                    held.lines.set(testSiteKey(match), match);
+                }
             }
         }
     }
@@ -1092,7 +1125,7 @@ function checkTarget(index, options, repoRoot) {
     // no link stands in.
     const linesOf = new Map();
     for (const [rel, held] of linesByFile) {
-        if (absoluteTest.has(rel)) linesOf.set(absoluteTest.get(rel), [...held.lines]);
+        if (absoluteTest.has(rel)) linesOf.set(absoluteTest.get(rel), [...held.lines.values()]);
     }
     testFiles = [];
     supportFiles = [];

package/core/command-contracts.js

@@ -52,7 +52,7 @@ const COMMAND_CONTRACTS = Object.freeze({
             { name: 'definition', when: 'Default or `type` is a symbol kind such as function/class.', answer: 'Matching indexed definitions with location and signature metadata.' },
             { name: 'type lookup', when: '`type=type`.', answer: 'Type-definition records rather than general name matches.' },
         ],
-        defaults: ['Substring matching unless `exact=true`.', 'Tests excluded unless `includeTests=true`.', '`limit` is the single result cap; `withSource=true` attaches exact bodies.'],
+        defaults: ['Substring matching unless `exact=true`.', 'Test definitions included unless `includeTests=false`.', '`limit` is the single result cap; `withSource=true` attaches exact bodies.'],
         truth: 'Results are exact records from the static symbol index; usage counts are static indexed occurrences.',
         nonGoals: ['Text search inside comments or configuration.', 'Compiler overload resolution across external dependencies.'],
         invalidCombinations: ['A missing name is rejected.'],
@@ -183,7 +183,7 @@ const COMMAND_CONTRACTS = Object.freeze({
         target: 'Optional symbol/handle. Omitting it selects diff/precommit mode.',
         modes: [
             { name: 'symbol', when: 'A symbol target is supplied; `base` names the revision whose declaration its call sites were written against.', answer: 'Argument-count compatibility, uncertain sites, and the caller account.' },
-            { name: 'diff', when: 'No target is supplied; `base` or `staged` selects changes.', answer: 'A verdict per changed symbol by what the change did: blocked (a break was observed, every site listed), review (can reach existing code, reason named) or ready (nothing that existed depends on it); TRUST is the worst of them. Affected tests.' },
+            { name: 'diff', when: 'No target is supplied; `base` or `staged` selects changes.', answer: 'A verdict per changed symbol by what the change did: blocked (a break was observed, every site listed), review (change exposure or call requirements not settled, reason named) or ready (no unresolved exposure in the modeled checks, not compiler or runtime proof); TRUST is the worst of them. Affected tests.' },
         ],
         defaults: ['Symbol mode checks static arity, not compiler type compatibility.', '`base` defaults to HEAD in both modes.', 'Diff mode: `staged` reads the staged tree from the git index, never the worktree; `strict` makes REVIEW_REQUIRED fail as BLOCKED does.'],
         truth: 'Findings are static diagnostics with explicit uncertainty; a clean result is not a compiler/test pass.',