ucn 5.5.2 → 5.6.0

package/core/execute.js

@@ -15,7 +15,7 @@ const path = require('path');
 const { addTestExclusions, pickBestDefinition, parseSymbolHandle, looksLikeHandle } = require('./shared');
 const { cleanHtmlScriptTags, detectLanguage } = require('./parser');
 const { renderExpandItem } = require('./expand-cache');
-const { CANONICAL_COMMANDS } = require('./registry');
+const { CANONICAL_COMMANDS, FLAG_APPLICABILITY, commandMode, paramDefault, paramTableError, toCliName } = require('./registry');
 const { sourceRangeTarget } = require('./public-command');
 const { isAccessorDefinition } = require('./accessors');
 const { describeError } = require('./errors');
@@ -24,11 +24,11 @@ const { describeError } = require('./errors');
 // HELPERS
 // ============================================================================
 
+// A state, said once and short: what the absence never means is in the
+// tool description and the usage guide.
 const NO_STATIC_TEST_LINK_NOTE =
-    'No confirmed static test link was found. This is not runtime coverage evidence: ' +
-    'subprocess/black-box tests, reflection, generated code, and external harnesses can still ' +
-    'exercise the target. Inspect the project test runner and search for the defining module/file ' +
-    'before concluding it is untested.';
+    'No static test link found; this is not runtime coverage evidence ' +
+    '(tests that reach the target by subprocess, reflection or generated code are not seen).';
 
 function requireName(name) {
     if (!name || (typeof name === 'string' && !name.trim())) {
@@ -99,17 +99,20 @@ function symbolNotFound(index, name, label = 'Symbol') {
     } else {
         message = `${label} "${query}" not found. Use find with a shorter name, or search for a literal occurrence.`;
     }
+    // Unanalyzed source is searched for this name; it is mentioned only
+    // when the name occurs in it, or when part of the project could not be
+    // searched at all.
+    const universeTools = require('./source-universe');
     const unsupported = require('./account').scanUnsupportedFiles(index, query);
     if (unsupported.lines > 0) {
-        const languages = Object.keys(unsupported.languages).join(', ');
+        const labels = universeTools.matchLabels(unsupported);
         message += ` ${unsupported.lines} literal match(es) exist in ` +
-            `${unsupported.fileCount} unsupported-language file(s)` +
-            `${languages ? ` (${languages})` : ''}; this is not a semantic zero. ` +
-            'Use grep/ripgrep plus a language-native analyzer.';
-    } else if (index.unsupportedFiles?.length > 0) {
-        message += ` UCN skipped ${index.unsupportedFiles.length} unsupported source ` +
-            `file(s), so this is not a repository-wide semantic zero; verify with grep/ripgrep.`;
+            `${unsupported.fileCount} unanalyzed file(s)` +
+            `${labels ? ` (${labels})` : ''}; this is not a semantic zero. ` +
+            universeTools.matchAdvice(unsupported);
     }
+    const unsearched = universeTools.unsearchedNote(index);
+    if (unsearched) message += ` ${unsearched}`;
     return message;
 }
 
@@ -213,7 +216,7 @@ function buildCallerOptions(p) {
         includeUncertain: p.includeUncertain || false,
         includeTests: p.includeTests,
         exclude: toExcludeArray(p.exclude),
-        minConfidence: num(p.minConfidence, 0),
+        minConfidence: num(p.minConfidence, paramDefault('minConfidence')),
     };
 }
 
@@ -294,9 +297,12 @@ function num(val, fallback) {
     return isNaN(n) ? fallback : n;
 }
 
-/** Shared listing bound; shell listings remain uncapped unless requested. */
-function listingLimit(p) {
-    return num(p.limit, undefined) || (p.lines || p.all ? undefined : 500);
+/**
+ * The listing bound of `command`: an explicit limit, else the command's
+ * default limit. Shell listings and `all` have no default bound.
+ */
+function listingLimit(p, command) {
+    return num(p.limit, undefined) || (p.lines || p.all ? undefined : paramDefault('limit', command));
 }
 
 /**
@@ -421,31 +427,17 @@ function readAndExtract(match) {
     return cleanHtmlScriptTags(extracted, detectLanguage(match.file)).join('\n');
 }
 
-const SHOW_SECTIONS = new Set([
-    'summary', 'callers', 'callees', 'source', 'dependencies',
-    'tests', 'types', 'example', 'related',
-]);
-const REPO_SECTIONS = new Set(['summary', 'files', 'stats', 'health']);
-
-/** Parse a comma-separated/array section selector with validation. */
-function parseSections(value, defaults, allowed, command) {
-    const supplied = value != null && value !== '';
+/**
+ * The sections a `show` or `repo` request selects: the ones it names, else
+ * the command's default for its mode. The parameter table has already
+ * refused a name outside the command's set.
+ */
+function selectedSections(command, p) {
+    const supplied = p.sections != null && p.sections !== '';
     const raw = !supplied
-        ? defaults
-        : (Array.isArray(value) ? value : String(value).split(','));
-    const sections = [...new Set(raw.map(s => String(s).trim().toLowerCase()).filter(Boolean))];
-    if (supplied && sections.length === 0) {
-        return {
-            error: `No valid ${command} sections were provided. Available: ${[...allowed].join(', ')}.`,
-        };
-    }
-    const invalid = sections.filter(s => !allowed.has(s));
-    if (invalid.length > 0) {
-        return {
-            error: `Unknown ${command} section(s): ${invalid.join(', ')}. Available: ${[...allowed].join(', ')}.`,
-        };
-    }
-    return { sections };
+        ? paramDefault('sections', command, commandMode(command, p))
+        : (Array.isArray(p.sections) ? p.sections : String(p.sections).split(','));
+    return [...new Set(raw.map(s => String(s).trim().toLowerCase()).filter(Boolean))];
 }
 
 function addMode(result, mode) {
@@ -471,14 +463,17 @@ const PUBLIC_COMMAND_SET = new Set(CANONICAL_COMMANDS);
  * glob, file, and programmatic callers receive the same answer.
  */
 function validatePublicParams(command, p) {
-    if (p.raw && command !== 'source') return '--raw is supported only by source.';
-    if (p.lines && !['find', 'usages', 'search', 'show', 'impact'].includes(command)) {
-        return '--lines is supported by find, usages, search, show, and impact.';
-    }
-    if (p.lines && command === 'show' && p.sections) {
-        const parsed = parseSections(p.sections, ['callers'], new Set(['callers', 'callees']), 'show --lines');
-        if (parsed.error) return parsed.error;
+    // The shell modes change the shape of the whole answer: on a command
+    // that has none they are refused, not ignored.
+    for (const shape of ['raw', 'lines']) {
+        if (!p[shape] || FLAG_APPLICABILITY[command].includes(shape)) continue;
+        const takers = CANONICAL_COMMANDS.filter(name => FLAG_APPLICABILITY[name].includes(shape)).map(toCliName);
+        return takers.length === 1
+            ? `--${shape} is supported only by ${takers[0]}.`
+            : `--${shape} is supported by ${takers.slice(0, -1).join(', ')}, and ${takers.at(-1)}.`;
     }
+    const tableError = paramTableError(command, p);
+    if (tableError) return tableError;
     const hasName = typeof p.name === 'string' && p.name.trim() !== '';
     const gitScope = p.staged || (typeof p.base === 'string' && p.base.trim() !== '');
     if (command === 'impact' && hasName && gitScope) {
@@ -504,14 +499,14 @@ function validatePublicParams(command, p) {
         return 'search receiver filtering requires type=call (or omit type to select call mode).';
     }
     if (command === 'trace' && p.to === 'entrypoints' &&
-        (p.direction || 'callees') !== 'callers') {
+        (p.direction || paramDefault('direction', 'trace')) !== 'callers') {
         return 'trace --to=entrypoints requires --direction=callers.';
     }
     if (command === 'deps' && p.cycles &&
         (p.file || p.direction || p.depth != null || p.detailed || p.all)) {
         return 'deps cycles mode cannot be combined with file, direction, depth, detailed, or all.';
     }
-    if (command === 'tests' && Number(p.depth || 0) > 0 && p.callsOnly) {
+    if (command === 'tests' && Number(p.depth || paramDefault('depth', 'tests')) > 0 && p.callsOnly) {
         return 'tests callsOnly applies to direct mode and cannot be combined with depth>0.';
     }
     if (command === 'entrypoints' && p.includeTests === true && p.excludeTests === true) {
@@ -523,8 +518,9 @@ function validatePublicParams(command, p) {
     if (command === 'plan') {
         const operations = [p.addParam, p.removeParam, p.renameTo]
             .filter(value => value != null && String(value).trim() !== '');
+        if (p.delete) operations.push('delete');
         if (operations.length !== 1) {
-            return 'plan requires exactly one operation: addParam, removeParam, or renameTo.';
+            return 'plan requires exactly one operation: addParam, removeParam, renameTo, or delete.';
         }
         if (p.defaultValue != null && !p.addParam) {
             return 'plan defaultValue is valid only with addParam.';
@@ -587,13 +583,7 @@ const HANDLERS = {
             line: resolved.def.nameLine || resolved.def.startLine,
             ...(resolved.def.className && { className: resolved.def.className }),
         } : query;
-        const parsed = parseSections(
-            p.sections,
-            p.lines ? ['callers'] : ['summary', 'callers', 'callees'],
-            SHOW_SECTIONS,
-            'show',
-        );
-        if (parsed.error) return { ok: false, error: parsed.error };
+        const parsed = { sections: selectedSections('show', p) };
         if (p.withTypes && !parsed.sections.includes('types')) parsed.sections.push('types');
 
         const selected = new Set(parsed.sections);
@@ -729,10 +719,7 @@ const HANDLERS = {
         }
         const err = requireFile(p.file);
         if (err) return { ok: false, error: err };
-        const direction = p.direction || 'both';
-        if (!['imports', 'importers', 'both'].includes(direction)) {
-            return { ok: false, error: 'deps direction must be imports, importers, or both.' };
-        }
+        const direction = p.direction || paramDefault('direction', 'deps');
         const graphResponse = HANDLERS.graph(index, {
             file: p.file,
             direction,
@@ -764,9 +751,7 @@ const HANDLERS = {
         if (fileErr) return { ok: false, error: fileErr };
         const inErr = validateInFilter(index, p.in);
         if (inErr) return { ok: false, error: inErr };
-        const defaults = p.deep ? ['summary', 'health'] : ['summary'];
-        const parsed = parseSections(p.sections, defaults, REPO_SECTIONS, 'repo');
-        if (parsed.error) return { ok: false, error: parsed.error };
+        const parsed = { sections: selectedSections('repo', p) };
         const selected = new Set(parsed.sections);
         const result = { sections: parsed.sections };
         const notes = [];
@@ -783,7 +768,7 @@ const HANDLERS = {
             ...p,
             // repo's public limit caps the file result set. Direct toc's
             // legacy symbol-list cap is intentionally not composed here.
-            top: p.top || listingLimit(p),
+            top: p.top || listingLimit(p, 'repo'),
             limit: undefined,
         });
         if (!failure && selected.has('stats')) failure = collect('stats', 'stats', p);
@@ -880,6 +865,7 @@ const HANDLERS = {
             line: p.line,
             exclude: toExcludeArray(p.exclude),
             top: num(p.limit, undefined) || num(p.top, undefined),
+            all: !!p.all,
             unreachableOnly: !!p.unreachableOnly,
             // BUG-H3: pass through user-supplied flags. impact defaults to including
             // method calls because "what breaks if I change this" should include
@@ -907,7 +893,7 @@ const HANDLERS = {
         const depthVal = num(p.depth, undefined);
         const result = index.blast(p.name, {
             ...buildCallerOptions(p),
-            depth: depthVal ?? 3,
+            depth: depthVal ?? paramDefault('depth', 'trace'),
             all: !!p.all,
             expandUnverified: !!p.expandUnverified,
         });
@@ -931,7 +917,7 @@ const HANDLERS = {
         const depthVal = num(p.depth, undefined);
         const result = index.reverseTrace(p.name, {
             ...buildCallerOptions(p),
-            depth: depthVal ?? 5,
+            depth: depthVal ?? paramDefault('depth', 'trace', 'entrypoints'),
             all: !!p.all,
             expandUnverified: !!p.expandUnverified,
         });
@@ -962,13 +948,7 @@ const HANDLERS = {
     },
 
     trace: (index, p) => {
-        const direction = p.direction || 'callees';
-        if (!['callees', 'callers'].includes(direction)) {
-            return { ok: false, error: 'trace direction must be callees or callers.' };
-        }
-        if (p.to && p.to !== 'entrypoints') {
-            return { ok: false, error: 'trace --to currently accepts only entrypoints.' };
-        }
+        const direction = p.direction || paramDefault('direction', 'trace');
         if (direction === 'callers') {
             const response = p.to === 'entrypoints'
                 ? HANDLERS.reverseTrace(index, { ...p, direction: undefined, to: undefined })
@@ -991,7 +971,7 @@ const HANDLERS = {
         const depthVal = num(p.depth, undefined);
         const result = index.trace(p.name, {
             ...buildCallerOptions(p),
-            depth: depthVal ?? 3,
+            depth: depthVal ?? paramDefault('depth', 'trace'),
             all: !!p.all,
             expandUnverified: !!p.expandUnverified,
         });
@@ -1128,10 +1108,11 @@ const HANDLERS = {
         const { check } = require('./check');
         try {
             const result = check(index, {
-                base: p.base || 'HEAD',
+                base: p.base || paramDefault('base'),
                 staged: !!p.staged,
                 file: p.file,
                 limit: num(p.limit, undefined),
+                strict: !!p.strict,
             });
             addMode(result, 'diff');
             return { ok: true, result };
@@ -1145,21 +1126,13 @@ const HANDLERS = {
     find: (index, p) => {
         const inErr = validateInFilter(index, p.in);
         if (inErr) return { ok: false, error: inErr };
-        const validFindTypes = new Set([
-            'type', 'function', 'class', 'variable', 'state', 'constant',
-            'field', 'macro', 'method', 'constructor', 'interface', 'enum',
-            'struct', 'trait', 'record', 'namespace',
-        ]);
-        if (p.type && !validFindTypes.has(p.type)) {
-            return { ok: false, error: `Invalid find type "${p.type}". Valid types: ${[...validFindTypes].join(', ')}.` };
-        }
         if (p.type === 'type') {
             const response = HANDLERS.typedef(index, { ...p });
             if (response.ok) {
                 if (!p.withSource && Array.isArray(response.result)) {
                     response.result = response.result.map(({ code, ...item }) => item);
                 }
-                const limit = listingLimit(p);
+                const limit = listingLimit(p, 'find');
                 if (limit && limit > 0 && Array.isArray(response.result)) {
                     const { items, total, limited } = applyLimit(response.result, limit);
                     response.result = items;
@@ -1211,12 +1184,14 @@ const HANDLERS = {
                 item.startLine === line || item.nameLine === line);
         }
         if (p.type) {
-            const kindGroups = {
-                function: new Set(['function', 'method', 'constructor', 'get', 'set']),
-                class: new Set(CLASS_KIND_TYPES),
-                variable: new Set(['state', 'constant', 'field']),
-            };
-            const kinds = kindGroups[p.type] || new Set([p.type]);
+            // A Map: a kind may be named like an inherited object property
+            // (`constructor`), which a plain object lookup would return.
+            const kindGroups = new Map([
+                ['function', new Set(['function', 'method', 'constructor', 'get', 'set'])],
+                ['class', new Set(CLASS_KIND_TYPES)],
+                ['variable', new Set(['state', 'constant', 'field'])],
+            ]);
+            const kinds = kindGroups.get(p.type) || new Set([p.type]);
             result = result.filter(item => kinds.has(item.type));
         }
         const fullFindCount = result.length;
@@ -1232,21 +1207,24 @@ const HANDLERS = {
             notes.push(`Note: exact=true treats "${p.name}" as a literal name (glob expansion disabled).`);
         }
         let unsupportedMatches = null;
-        if (fullFindCount === 0 && index.unsupportedFiles?.length > 0) {
-            unsupportedMatches = require('./account').scanUnsupportedFiles(index, p.name);
-            const languages = Object.keys(unsupportedMatches.languages).join(', ');
-            if (unsupportedMatches.lines > 0) {
-                notes.push(`${unsupportedMatches.lines} literal match(es) exist in ` +
-                    `${unsupportedMatches.fileCount} unsupported-language file(s)` +
-                    `${languages ? ` (${languages})` : ''}; this is not a semantic zero. ` +
-                    'Use grep/ripgrep plus a language-native analyzer.');
-            } else {
-                notes.push(`UCN skipped ${index.unsupportedFiles.length} unsupported source ` +
-                    'file(s), so this is not a repository-wide semantic zero; verify with grep/ripgrep.');
+        if (fullFindCount === 0) {
+            const universeTools = require('./source-universe');
+            if (universeTools.hasTextOnly(index)) {
+                const matches = require('./account').scanUnsupportedFiles(index, p.name);
+                if (matches.lines > 0) {
+                    unsupportedMatches = matches;
+                    const labels = universeTools.matchLabels(matches);
+                    notes.push(`${matches.lines} literal match(es) exist in ` +
+                        `${matches.fileCount} unanalyzed file(s)` +
+                        `${labels ? ` (${labels})` : ''}; this is not a semantic zero. ` +
+                        universeTools.matchAdvice(matches));
+                }
             }
+            const unsearched = universeTools.unsearchedNote(index);
+            if (unsearched) notes.push(unsearched);
         }
         // Apply limit
-        const limit = listingLimit(p);
+        const limit = listingLimit(p, 'find');
         if (!p.lines) {
             index._beginOp();
             try {
@@ -1305,7 +1283,7 @@ const HANDLERS = {
         const userExclude = toExcludeArray(p.exclude);
         const unfiltered = index.usages(p.name, {
             codeOnly: p.codeOnly || false,
-            context: num(p.context, 0),
+            context: num(p.context, paramDefault('context')),
             className: p.className,
             // A stable handle pins which definition is meant; it must not
             // silently turn into a same-file-only usage scan. An explicit
@@ -1363,15 +1341,20 @@ const HANDLERS = {
         const accountTools = require('./account');
         const unsupportedMatches = accountTools.scanUnsupportedFiles(index, p.name);
         if (unsupportedMatches.lines > 0) {
-            const langs = Object.keys(unsupportedMatches.languages).join(', ');
+            const langs = require('./source-universe').matchLabels(unsupportedMatches);
             notes.push(`${unsupportedMatches.lines} line(s) in ${unsupportedMatches.fileCount} ` +
-                `unsupported-language file(s)${langs ? ` (${langs})` : ''} also match — ` +
+                `unanalyzed file(s)${langs ? ` (${langs})` : ''} also match — ` +
                 'NOT analyzed by UCN; verify with grep/ripgrep.');
             Object.defineProperty(limited, 'unsupportedMatches', {
                 value: unsupportedMatches,
                 enumerable: false, writable: true, configurable: true,
             });
         }
+        // An inventory is incomplete wherever a path could not be searched
+        // (asked after the scan above: a file that fails to read while being
+        // scanned becomes such a path).
+        const unsearched = require('./source-universe').unsearchedNote(index);
+        if (unsearched) notes.push(unsearched);
         const failed = accountTools.scanFailedFiles(index, p.name);
         if (failed.unparsed.lines > 0) {
             notes.push(`${failed.unparsed.lines} matching line(s) in ${failed.unparsed.fileCount} unparsed file(s) were not classified: ${failed.unparsed.files.join(', ')}.`);
@@ -1455,7 +1438,7 @@ const HANDLERS = {
         const fileErr = checkFilePatternMatch(index, p.file);
         if (fileErr) return { ok: false, error: fileErr };
         // Detect structural search mode: any of these flags triggers index-based search
-        const isStructural = p.type || p.param || p.receiver || p.returns || p.decorator || p.exported || p.unused;
+        const isStructural = commandMode('search', p) === 'structural';
         if (isStructural) {
             const exclude = applyTestExclusions(p.exclude, p.includeTests);
             const topVal = num(p.top, undefined) || num(p.limit, undefined);
@@ -1473,7 +1456,7 @@ const HANDLERS = {
                 testExclude: p.includeTests ? undefined : ['test files'],
                 in: p.in,
                 file: p.file,
-                top: topVal || (p.lines ? undefined : 50),
+                top: topVal || (p.lines ? undefined : paramDefault('limit', 'search', 'structural')),
             });
             if (result.meta.error) return { ok: false, error: result.meta.error };
             const unsupported = (!p.regex && (p.term || p.name))
@@ -1487,7 +1470,7 @@ const HANDLERS = {
                     value: unsupported,
                     enumerable: false, writable: true, configurable: true,
                 });
-                note = combineNotes([note, `${unsupported.lines} matching line(s) in ${unsupported.fileCount} unsupported-language file(s) were not structurally analyzed; verify with grep/ripgrep.`]);
+                note = combineNotes([note, `${unsupported.lines} matching line(s) in ${unsupported.fileCount} unanalyzed file(s) were not structurally analyzed; verify with grep/ripgrep.`]);
             }
             return { ok: true, result, structural: true, note };
         }
@@ -1497,14 +1480,14 @@ const HANDLERS = {
         const testsExcluded = !p.includeTests;
         const exclude = applyTestExclusions(p.exclude, p.includeTests);
         // JSON is intentionally structured rather than byte-truncated, so
-        // text search needs a row bound of its own. Keep the documented
-        // default at 500 and retain total/truncated metadata for controlled
-        // expansion with an explicit top/limit.
+        // text search needs a row bound of its own: the default limit, with
+        // total/truncated metadata for controlled expansion by an explicit
+        // top/limit.
         const topVal = num(p.top, undefined) || num(p.limit, undefined);
-        const effectiveLimit = topVal || (p.lines ? undefined : 500);
+        const effectiveLimit = topVal || (p.lines ? undefined : paramDefault('limit', 'search'));
         const result = index.search(p.term, {
             codeOnly: p.codeOnly || false,
-            context: num(p.context, 0),
+            context: num(p.context, paramDefault('context')),
             caseSensitive: p.caseSensitive || false,
             exclude,
             in: p.in,
@@ -1521,8 +1504,10 @@ const HANDLERS = {
                     value: unsupported,
                     enumerable: false, writable: true, configurable: true,
                 });
-                notes.push(`${unsupported.lines} matching line(s) in ${unsupported.fileCount} unsupported-language file(s) were not searched; verify with grep/ripgrep.`);
+                notes.push(`${unsupported.lines} matching line(s) in ${unsupported.fileCount} unanalyzed file(s) were not searched; verify with grep/ripgrep.`);
             }
+            const unsearched = require('./source-universe').unsearchedNote(index);
+            if (unsearched) notes.push(unsearched);
         }
         const tNote = truncationNote(index);
         if (tNote) notes.push(tNote);
@@ -1530,7 +1515,7 @@ const HANDLERS = {
     },
 
     tests: (index, p) => {
-        const depth = num(p.depth, 0);
+        const depth = num(p.depth, paramDefault('depth', 'tests'));
         if (depth > 0) {
             const response = HANDLERS.affectedTests(index, { ...p, depth });
             if (response.ok) addMode(response.result, 'affected');
@@ -1614,15 +1599,17 @@ const HANDLERS = {
         if (!testsTargetIsFile) {
             const unsupportedMatches = require('./account').scanUnsupportedFiles(index, p.name);
             if (unsupportedMatches.lines > 0) {
-                const langs = Object.keys(unsupportedMatches.languages).join(', ');
+                const langs = require('./source-universe').matchLabels(unsupportedMatches);
                 testNotes.push(`"${p.name}" also occurs on ${unsupportedMatches.lines} line(s) in ` +
-                    `${unsupportedMatches.fileCount} unsupported-language file(s)${langs ? ` (${langs})` : ''} — ` +
+                    `${unsupportedMatches.fileCount} unanalyzed file(s)${langs ? ` (${langs})` : ''} — ` +
                     'their test files are invisible to UCN; verify with grep/ripgrep.');
                 Object.defineProperty(result, 'unsupportedMatches', {
                     value: unsupportedMatches,
                     enumerable: false, writable: true, configurable: true,
                 });
             }
+            const unsearched = require('./source-universe').unsearchedNote(index);
+            if (unsearched) testNotes.push(unsearched);
         }
         return {
             ok: true,
@@ -1675,7 +1662,7 @@ const HANDLERS = {
             file: p.file,
         });
         // Apply limit to dead code results (result is an array with custom properties)
-        const limit = listingLimit(p);
+        const limit = listingLimit(p, 'deadcode');
         let note;
         if (limit && limit > 0 && Array.isArray(result) && result.length > limit) {
             note = limitNote(limit, result.length);
@@ -1687,6 +1674,8 @@ const HANDLERS = {
             if (result.excludedRuntimeContract != null) sliced.excludedRuntimeContract = result.excludedRuntimeContract;
             if (result.excludedConstructors != null) sliced.excludedConstructors = result.excludedConstructors;
             if (result.excludedDynamicDispatch != null) sliced.excludedDynamicDispatch = result.excludedDynamicDispatch;
+            if (result.excludedRequiredSlot != null) sliced.excludedRequiredSlot = result.excludedRequiredSlot;
+            if (result.projectKind != null) sliced.projectKind = result.projectKind;
             if (result.pythonImplicitExportFiles != null) sliced.pythonImplicitExportFiles = result.pythonImplicitExportFiles;
             if (result.computedDispatch != null) sliced.computedDispatch = result.computedDispatch;
             if (result.reflection != null) sliced.reflection = result.reflection;
@@ -1780,21 +1769,12 @@ const HANDLERS = {
     endpoints: (index, p) => {
         const fileErr = checkFilePatternMatch(index, p.file);
         if (fileErr) return { ok: false, error: fileErr };
-        // Minor polish: validate --method against known HTTP verbs to catch
-        // typos that would otherwise silently filter out everything.
-        // 'ALL' / 'USE' are downstream route labels that can be queried explicitly.
-        const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS', 'HEAD', 'ALL', 'USE']);
-        let normMethod = null;
-        if (p.method != null && String(p.method).trim() !== '') {
-            normMethod = String(p.method).trim().toUpperCase();
-            if (!HTTP_METHODS.has(normMethod)) {
-                return {
-                    ok: false,
-                    error: `Invalid --method value: "${p.method}". Expected one of ${[...HTTP_METHODS].join(', ')}.`,
-                };
-            }
-        }
-        const { endpoints } = require('./bridge');
+        // The method is one of the table's verbs in any letter case; a typo
+        // is refused there instead of filtering everything out.
+        const normMethod = p.method != null && String(p.method).trim() !== ''
+            ? String(p.method).trim().toUpperCase()
+            : null;
+        const { endpoints, ENDPOINT_FRAMEWORKS } = require('./bridge');
         // HIGH-2: --unmatched implies --bridge (we need bridges to know what's
         // unmatched). Without bridges computed, we can't separate matched from
         // unmatched on either side.
@@ -1813,16 +1793,14 @@ const HANDLERS = {
         });
         if (p.framework != null && String(p.framework).trim() !== '') {
             const framework = String(p.framework).trim().toLowerCase();
-            const known = new Set([
-                'actix', 'aspnet', 'aspnet-minimal', 'axios', 'axum',
-                'dotnet-httpclient', 'express', 'fastapi', 'fetch', 'flask',
-                'go-http', 'jax-rs', 'nestjs', 'nextjs', 'requests',
-                'reqwest', 'spring', 'spring-client', 'unknown-python',
-            ]);
-            if (!known.has(framework)) {
+            // Known: a label the endpoint detectors declare, or one a row of
+            // this answer carries. A label the answer prints always filters.
+            const present = [...result.routes, ...result.requests].map(row => row.framework).filter(Boolean);
+            const known = [...new Set([...ENDPOINT_FRAMEWORKS, ...present])].sort();
+            if (!known.includes(framework)) {
                 return {
                     ok: false,
-                    error: `Invalid --framework value: "${p.framework}". Valid: ${[...known].join(', ')}.`,
+                    error: `Invalid endpoints framework "${p.framework}". Valid: ${known.join(', ')}.`,
                 };
             }
             result.routes = result.routes.filter(route => route.framework === framework);
@@ -2208,8 +2186,8 @@ const HANDLERS = {
         const err = requireFile(p.file);
         if (err) return { ok: false, error: err };
         const result = index.graph(p.file, {
-            direction: p.direction || 'both',
-            maxDepth: num(p.depth, 2),
+            direction: p.direction || paramDefault('direction', 'deps'),
+            maxDepth: num(p.depth, paramDefault('depth', 'deps')),
         });
         if (result && result.error === 'invalid-direction') {
             return { ok: false, error: result.message };
@@ -2275,8 +2253,23 @@ const HANDLERS = {
         if (classErr) return { ok: false, error: classErr };
         const pinErr = checkDefinitionPin(index, p);
         if (pinErr) return { ok: false, error: pinErr };
+        if (p.delete) {
+            // The same eligibility rule the dead-code audit runs over every
+            // name, asked about this one declaration (core/deletion.js).
+            const resolved = index.resolveSymbol(p.name, {
+                file: p.file, className: p.className, line: p.line,
+            });
+            if (!resolved.def) return { ok: false, error: symbolNotFound(index, p.name) };
+            const assessment = require('./deletion').assessDeletion(index, resolved.def);
+            return { ok: true, result: {
+                found: true, operation: 'delete', ...assessment,
+                // Which declaration a bare name selected, and the others it
+                // could have meant: the verdict is about one of them.
+                ...(resolved.warnings.length > 0 && { warnings: resolved.warnings }),
+            } };
+        }
         if (!p.addParam && !p.removeParam && !p.renameTo) {
-            return { ok: false, error: 'Plan requires an operation: add_param, remove_param, or rename_to.' };
+            return { ok: false, error: 'Plan requires an operation: add_param, remove_param, rename_to, or delete.' };
         }
         const result = index.plan(p.name, {
             addParam: p.addParam,
@@ -2296,11 +2289,39 @@ const HANDLERS = {
     },
 
     diffImpact: (index, p) => {
-        let result = index.diffImpact({
-            base: p.base || 'HEAD',
-            staged: p.staged || false,
-            file: p.file,
-        });
+        // A staged diff describes the git index: its new side is read from
+        // the tree that holds it (core/snapshot.js), never from a worktree
+        // that has moved on.
+        const { resolveTarget, rebasePaths } = require('./snapshot');
+        let target = null;
+        try {
+            target = resolveTarget(index, { staged: !!p.staged });
+        } catch (e) {
+            if (!e || e.code !== 'staged-snapshot-unavailable') throw e;
+            // Outside a repository the diff itself says so, below. Anything
+            // else is a staged tree that could not be read: an answer from
+            // the worktree would be an answer about another tree.
+            if (e.reason !== 'not-a-repository') {
+                return { ok: false, error: `The staged tree could not be exported and indexed (${e.message}); nothing was analyzed.` };
+            }
+        }
+        let result;
+        try {
+            const view = target ? target.index : index;
+            result = view.diffImpact({
+                base: p.base || paramDefault('base'),
+                staged: p.staged || false,
+                file: p.file,
+                all: !!p.all,
+                top: num(p.limit, undefined) || num(p.top, undefined),
+                ...(target && { repoRoot: target.repoRoot }),
+            });
+            // Paths of an exported snapshot are reported where the
+            // repository has them.
+            if (target && target.ephemeral) rebasePaths(result, target.index.root, target.repoRoot);
+        } finally {
+            if (target) target.dispose();
+        }
         const limit = num(p.limit, undefined);
         let note;
         if (limit && limit > 0 && result) {
@@ -2373,7 +2394,7 @@ const HANDLERS = {
             if (fileErr) return { ok: false, error: fileErr };
         }
         // Apply limit to api results (api returns an array)
-        const limit = listingLimit(p);
+        const limit = listingLimit(p, 'api');
         let note;
         if (limit && limit > 0 && Array.isArray(result)) {
             const { items, total, limited } = applyLimit(result, limit);
@@ -2563,16 +2584,6 @@ function execute(index, command, params = {}) {
         }
         const response = handler(index, params);
         response.projectRoot = index.root;
-        const bundled = (index.discoveryIssues || []).filter(issue => issue.reason === 'bundled');
-        if (bundled.length > 0) {
-            const files = bundled.slice(0, 5).map(issue => issue.relativePath).join(', ');
-            const note = `UCN skipped ${bundled.length} bundled/minified or source-map file(s): ${files}` +
-                (bundled.length > 5 ? ', ...' : '') +
-                '. This is not a repository-wide semantic zero; use --include-bundled for JavaScript bundles ' +
-                '(source maps remain unindexed), or grep/ripgrep to inspect skipped files.';
-            if (response.ok) response.note = combineNotes([response.note, note]);
-            else response.error = `${response.error}\n${note}`;
-        }
         return response;
     } catch (e) {
         // A deliberate refusal keeps its message; an exception inside the