ucn 5.4.1 → 5.5.0

package/core/command-contracts.js

@@ -69,11 +69,11 @@ const COMMAND_CONTRACTS = Object.freeze({
         modes: [
             { name: 'inventory', when: 'Always.', answer: 'Occurrence records classified by usage kind.' },
         ],
-        defaults: ['Tests excluded unless `includeTests=true`.', 'Comments/strings included unless `codeOnly=true`.'],
+        defaults: ['Test files included; `excludeTests=true` hides them and reports how many.', 'Comments/strings included unless `codeOnly=true`.'],
         truth: 'The command reports the indexed literal-name occurrence universe, not exact semantic references to one definition. Classification is by syntax alone; show/impact ACCOUNT lines are engine-adjudicated, so the two breakdowns can legitimately differ (a method reference is a `reference` here but may be a confirmed caller there).',
         nonGoals: ['Alias-only references whose source line does not contain the queried name.', 'Safe-delete proof.'],
         invalidCombinations: ['A missing name is rejected.'],
-        examples: ['ucn usages parseRequest --include-tests', 'ucn usages parseRequest --code-only --file=src'],
+        examples: ['ucn usages parseRequest --exclude-tests', 'ucn usages parseRequest --code-only --file=src'],
         jsonData: 'Definition/reference records plus separately classified text occurrences, each with file, line, and content.',
         output: 'Broad output; narrow with `file`, `in`, `exclude`, or `limit`.',
         next: ['Use `find` plus `impact` when target identity matters.', 'Use `search` for arbitrary text.'],
@@ -182,17 +182,17 @@ const COMMAND_CONTRACTS = Object.freeze({
         purpose: 'Validate a symbol signature against call sites or compose checks over a Git diff.',
         target: 'Optional symbol/handle. Omitting it selects diff/precommit mode.',
         modes: [
-            { name: 'symbol', when: 'A symbol target is supplied.', answer: 'Argument-count compatibility, uncertain sites, and the caller account.' },
+            { 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: 'Composed diff impact, signature checks, and affected tests.' },
         ],
-        defaults: ['Symbol mode checks static arity, not compiler type compatibility.'],
+        defaults: ['Symbol mode checks static arity, not compiler type compatibility.', '`base` defaults to HEAD in both modes.'],
         truth: 'Findings are static diagnostics with explicit uncertainty; a clean result is not a compiler/test pass.',
         nonGoals: ['Full type checking.', 'Linting or executing project tests.'],
         invalidCombinations: [
-            'A named symbol cannot also select staged/diff scope.',
+            'A named symbol cannot take `staged`.',
             '`base` and `staged` cannot both select the diff.',
         ],
-        examples: ['ucn check publishOrderCreated', 'ucn check --staged'],
+        examples: ['ucn check publishOrderCreated', 'ucn check publishOrderCreated --base=main', 'ucn check --staged'],
         jsonData: 'Symbol mode returns signature, valid/mismatched/uncertain sites and accounting; diff mode returns composed diagnostics.',
         output: 'Broad diagnostic; scope to a symbol or focused Git diff.',
         next: ['Run the language compiler/type checker and selected tests.', 'Use `plan` before a signature refactor.'],

package/core/configuration-items.js

@@ -0,0 +1,86 @@
+'use strict';
+
+/**
+ * Configuration items of dynamically configured scopes (fix #398F).
+ *
+ * A Python name bound in one scope only in mutually exclusive branches
+ * (`if sys.platform == "win32": def getchar` / `else: def getchar`, `try:
+ * from ._speedups import f` / `except ImportError: def f`) is one item with
+ * an alternative per configuration. The parser records each item
+ * (`fileEntry.configurationItems`): its sites (def, class, import or value),
+ * each site's branch path, and the line range of every clause on those paths.
+ *
+ * Reachability of an alternative from a line: code inside another exclusive
+ * clause of a statement on the site's branch path runs only in a
+ * configuration without that site. Code anywhere else may run in either.
+ */
+
+const { branchClausesExclusive } = require('../languages/utils');
+
+const NO_ITEMS = Object.freeze([]);
+
+function configurationItemsOf(index, file) {
+    return index.files.get(file)?.configurationItems || NO_ITEMS;
+}
+
+const DEFINITION_KINDS = new Set(['def', 'class']);
+
+/** The item a def/class definition is an alternative of, with its site. */
+function itemOfDefinition(index, definition) {
+    if (!definition?.file || definition.startLine == null) return null;
+    for (const item of configurationItemsOf(index, definition.file)) {
+        if (item.name !== definition.name) continue;
+        const site = item.sites.find(s => DEFINITION_KINDS.has(s.kind) && s.line === definition.startLine);
+        if (site) return { item, site };
+    }
+    return null;
+}
+
+/** Two definitions are alternatives of one configuration item. */
+function sameConfigurationItem(index, a, b) {
+    if (!a || !b || a === b || a.file !== b.file || a.name !== b.name) return false;
+    const found = itemOfDefinition(index, a);
+    return !!found && found.item.sites.some(s => DEFINITION_KINDS.has(s.kind) && s.line === b.startLine &&
+        s !== found.site);
+}
+
+/** The module-scope item of `name` in `file`, if any. */
+function moduleItemNamed(index, file, name) {
+    return configurationItemsOf(index, file).find(item => item.scope === 0 && item.name === name) || null;
+}
+
+/** Items of `name` in `file` (any scope). */
+function itemsNamed(index, file, name) {
+    return configurationItemsOf(index, file).filter(item => item.name === name);
+}
+
+/**
+ * Code at `line` never reaches `site`: the line lies inside another
+ * exclusive clause of a statement on the site's branch path.
+ */
+function siteExcludedAt(item, site, line) {
+    if (!Number.isInteger(line)) return false;
+    for (const [statement, tag] of site.branch) {
+        const clauses = item.clauses.find(([at]) => at === statement)?.[1];
+        if (!clauses) continue;
+        const holder = clauses.find(([, start, end]) => start <= line && line <= end);
+        if (holder && holder[0] !== tag && branchClausesExclusive(holder[0], tag)) return true;
+    }
+    return false;
+}
+
+/** The sites of `item` code at `line` may reach. */
+function sitesReachableAt(item, line) {
+    return item.sites.filter(site => !siteExcludedAt(item, site, line));
+}
+
+module.exports = {
+    DEFINITION_KINDS,
+    configurationItemsOf,
+    itemOfDefinition,
+    sameConfigurationItem,
+    moduleItemNamed,
+    itemsNamed,
+    siteExcludedAt,
+    sitesReachableAt,
+};