@adecore/editor-react 0.0.1 → 0.17.0-beta.2

package/src/code-vision-model.ts

@@ -0,0 +1,230 @@
+import type { DocumentSymbol, DocumentSymbolResult, Position, SymbolInformation } from '@adecore/lsp';
+import { formatNumber } from '@adecore/ui/format';
+import type { i18n } from 'i18next';
+
+/* More declarations than this in one file and the rows are left out, which is the file that is too big for them to be quiet. */
+export const MAX_DECLARATIONS = 3000;
+
+/* LSP's SymbolKind: the kinds a row is drawn for and the ones whose children can be declarations too. */
+const CLASS = 5;
+const METHOD = 6;
+const PROPERTY = 7;
+const FIELD = 8;
+const CONSTRUCTOR = 9;
+const ENUM = 10;
+const INTERFACE = 11;
+const FUNCTION = 12;
+const CONSTANT = 14;
+const STRUCT = 23;
+const CONTAINERS: ReadonlySet<number> = new Set([1, 2, 3, 4, CLASS, ENUM, INTERFACE, STRUCT]);
+const TYPES: ReadonlySet<number> = new Set([CLASS, ENUM, INTERFACE, STRUCT]);
+const CALLABLES: ReadonlySet<number> = new Set([METHOD, FUNCTION]);
+
+export interface CodeVisionDeclaration {
+    /* The same declaration keeps its id through edits, so what a row showed stays until the new answer is in. */
+    readonly id: string;
+    readonly name: string;
+    /* Where the name starts, which is where the references are asked. */
+    readonly position: Position;
+    /* The line the row sits above: where the declaration starts once the comments before it are passed. */
+    readonly line: number;
+    readonly usages: boolean;
+    readonly authors: boolean;
+    /* The lines whose authors count: from the name to the last line that holds more than closing brackets. */
+    readonly authorFrom: number;
+    readonly authorTo: number;
+}
+
+export interface DeclarationSource {
+    readonly lineCount: number;
+    lineAt(line: number): string;
+    readonly languageId: string;
+}
+
+/* Languages whose `#` starts a comment, so a docblock written with it is passed like any other. */
+const HASH_COMMENTS: ReadonlySet<string> = new Set(['php', 'python', 'shellscript', 'ruby', 'yaml', 'dockerfile']);
+
+interface Candidate {
+    readonly name: string;
+    readonly kind: number;
+    readonly start: Position;
+    readonly end: Position;
+    readonly namePosition: Position | null;
+    readonly path: readonly string[];
+    readonly parentKind: number | null;
+}
+
+function isLocalName(name: string): boolean {
+    return name === '' || name.startsWith('<') || name === 'default';
+}
+
+function isUsageKind(kind: number, parentKind: number | null): boolean {
+    if (TYPES.has(kind) || CALLABLES.has(kind)) {
+        return true;
+    }
+    return (kind === PROPERTY || kind === FIELD || kind === CONSTANT) && (parentKind === CLASS || parentKind === STRUCT);
+}
+
+function isAuthorKind(kind: number): boolean {
+    return TYPES.has(kind) || CALLABLES.has(kind) || kind === CONSTRUCTOR;
+}
+
+function walk(symbols: readonly DocumentSymbol[], path: readonly string[], parentKind: number | null, out: Candidate[]): void {
+    for (const symbol of symbols) {
+        out.push({
+            name: symbol.name,
+            kind: symbol.kind,
+            start: symbol.range.start,
+            end: symbol.range.end,
+            namePosition: symbol.selectionRange.start,
+            path,
+            parentKind
+        });
+        // What a function or a method holds is local to it, and a row for a callback is noise.
+        if (CONTAINERS.has(symbol.kind)) {
+            walk(symbol.children ?? [], [...path, symbol.name], symbol.kind, out);
+        }
+    }
+}
+
+function candidatesOf(result: DocumentSymbolResult): Candidate[] {
+    const out: Candidate[] = [];
+    if (result === null || result.length === 0) {
+        return out;
+    }
+    if ('range' in result[0]!) {
+        walk(result as DocumentSymbol[], [], null, out);
+        return out;
+    }
+    const flat = result as SymbolInformation[];
+    const containers = new Map(flat.filter((symbol) => CONTAINERS.has(symbol.kind)).map((symbol) => [symbol.name, symbol.kind]));
+    for (const symbol of flat) {
+        const container = symbol.containerName ?? '';
+        if (container !== '' && !containers.has(container)) {
+            continue;
+        }
+        out.push({
+            name: symbol.name,
+            kind: symbol.kind,
+            start: symbol.location.range.start,
+            end: symbol.location.range.end,
+            namePosition: null,
+            path: container === '' ? [] : [container],
+            parentKind: container === '' ? null : (containers.get(container) ?? null)
+        });
+    }
+    return out;
+}
+
+/*
+ * Where a declaration really starts: past the comments and the blank lines a server counts into its
+ * range. Null when its range is nothing but comments.
+ */
+export function startAfterComments(source: DeclarationSource, from: Position, to: Position): Position | null {
+    const hash = HASH_COMMENTS.has(source.languageId);
+    let line = from.line;
+    let character = from.character;
+    while (line <= to.line && line < source.lineCount) {
+        const text = source.lineAt(line);
+        let at = character;
+        while (at < text.length && (text[at] === ' ' || text[at] === '\t')) {
+            at++;
+        }
+        if (at >= text.length) {
+            line++;
+            character = 0;
+            continue;
+        }
+        if (text.startsWith('/*', at)) {
+            let end = text.indexOf('*/', at + 2);
+            let scan = line;
+            while (end === -1 && scan + 1 <= to.line && scan + 1 < source.lineCount) {
+                scan++;
+                end = source.lineAt(scan).indexOf('*/');
+            }
+            if (end === -1) {
+                return null;
+            }
+            line = scan;
+            character = end + 2;
+            continue;
+        }
+        if (text.startsWith('//', at) || (hash && text[at] === '#' && text[at + 1] !== '[')) {
+            line++;
+            character = 0;
+            continue;
+        }
+        return line > to.line ? null : { line, character: at };
+    }
+    return null;
+}
+
+const CLOSERS = /^\s*[})\]]*[;,]?\s*$/;
+
+/* The last line of a declaration that holds more than the brackets that close it or nothing, which is what its authors are read from. */
+function lastLineWithCode(source: DeclarationSource, from: number, to: number): number {
+    for (let line = Math.min(to, source.lineCount - 1); line > from; line--) {
+        if (!CLOSERS.test(source.lineAt(line))) {
+            return line;
+        }
+    }
+    return from;
+}
+
+/* Where the name starts when a server gave only a range: its first occurrence on the line the declaration starts on. */
+function nameIn(source: DeclarationSource, name: string, start: Position): Position | null {
+    const at = source.lineAt(start.line).indexOf(name, start.character);
+    return at === -1 ? null : { line: start.line, character: at };
+}
+
+/*
+ * The declarations of a file a row is drawn above: classes, interfaces, enums, structs, functions and
+ * methods, and the properties and constants of a class, wherever they stand outside the body of a
+ * function. Only one that starts its line gets a row, since a row sits above the line.
+ */
+export function declarationsOf(result: DocumentSymbolResult, source: DeclarationSource): CodeVisionDeclaration[] {
+    const declarations: CodeVisionDeclaration[] = [];
+    const seen = new Map<string, number>();
+    for (const candidate of candidatesOf(result)) {
+        if (isLocalName(candidate.name)) {
+            continue;
+        }
+        const usages = isUsageKind(candidate.kind, candidate.parentKind) && !candidate.name.startsWith('__');
+        const authors = isAuthorKind(candidate.kind);
+        if (!usages && !authors) {
+            continue;
+        }
+        const start = startAfterComments(source, candidate.start, candidate.end);
+        if (start === null || source.lineAt(start.line).slice(0, start.character).trim() !== '') {
+            continue;
+        }
+        const position = candidate.namePosition ?? nameIn(source, candidate.name, start);
+        if (position === null) {
+            continue;
+        }
+        const key = `${candidate.path.join('>')}>${candidate.name}#${candidate.kind}`;
+        const index = seen.get(key) ?? 0;
+        seen.set(key, index + 1);
+        declarations.push({
+            id: `${key}#${index}`,
+            name: candidate.name,
+            position,
+            line: start.line,
+            usages,
+            authors,
+            authorFrom: position.line,
+            authorTo: lastLineWithCode(source, position.line, candidate.end.line)
+        });
+        if (declarations.length > MAX_DECLARATIONS) {
+            return [];
+        }
+    }
+    return declarations;
+}
+
+/* "No usages", "1 usage" and "N usages". */
+export function usagesText(count: number, i18n: i18n): string {
+    return count === 0
+        ? i18n.t('editor:language.codeVision.usagesNone')
+        : i18n.t('editor:language.codeVision.usages', { count, formatted: formatNumber(count) });
+}

package/src/code-vision.ts

@@ -0,0 +1,269 @@
+import { splitLines } from '@adecore/merge';
+import type { GitBlameResult } from './host-types.ts';
+import type { EditorCodeVision, EditorCodeVisionEntry, EditorRect } from '@adecore/editor';
+import type { DocumentSymbolResult } from '@adecore/lsp';
+import type { EditorLanguage } from './editor-language.ts';
+import { type CodeAuthorship, authorsText, authorshipOf, mapBlame } from './code-authors.ts';
+import { type CodeVisionDeclaration, declarationsOf, usagesText } from './code-vision-model.ts';
+import { realTimers, type Timers } from './timers.ts';
+
+const REFERENCES = 'textDocument/references';
+/* Lines asked about above and below what is in view, so a little scrolling stays inside what is counted. */
+const MARGIN_LINES = 40;
+/* References are the slowest question a server is asked here, so only this many are in flight at once. */
+const MAX_PARALLEL = 3;
+const SCROLL_PAUSE_MS = 150;
+/* Past this many lines a file gets no rows at all, which is also what keeps blame and the walk of symbols cheap. */
+export const MAX_LINES = 20_000;
+
+export interface CodeVisionSettings {
+    readonly usages: boolean;
+    readonly authors: boolean;
+}
+
+/*
+ * What git says about the file: `pending` while it is being asked, so the rows are held for the authors
+ * that will come, and the blame of the text on disk once it is in. Null where git has nothing to say.
+ */
+export type BlameSource =
+    | { readonly kind: 'pending' }
+    | { readonly kind: 'ready'; readonly blame: GitBlameResult; readonly base: string; openCommit?(hash: string): void };
+
+/*
+ * The rows above declarations: how often each is used and, once git has been asked, who wrote it. The
+ * declarations come from the symbols the servers know, and a row holds its height from the first
+ * answer on, empty until its entries are in, so the text never moves when they arrive. Counts are asked
+ * lazily, for the declarations in view and a margin around them, a few at a time, and only after the
+ * text has settled; an old count stays on its row until the new one is in.
+ */
+export class CodeVisionFeature {
+    private readonly language: EditorLanguage;
+    private readonly timers: Timers;
+    private settings: CodeVisionSettings = { usages: false, authors: false };
+    private declarations: CodeVisionDeclaration[] = [];
+    /* What the declarations were read from, so a count never outlives the text it was asked for. */
+    private epoch = 0;
+    private edited = false;
+    private readonly counts = new Map<string, { count: number; epoch: number }>();
+    private queue: CodeVisionDeclaration[] = [];
+    /* Scrolling changes the pending queue but keeps requests already in flight. */
+    private readonly running = new Map<string, AbortController>();
+    /* Declarations a server could not count for this text, which are not asked again until it says it can. */
+    private failed = new Set<string>();
+    private blame: BlameSource | null = null;
+    /* The text the declarations were read from, which the lines of their authors are counted in. */
+    private lines: readonly string[] = [];
+    private mapped: { blame: GitBlameResult; lines: Int32Array | null } | null = null;
+    private readonly authorships = new Map<string, CodeAuthorship>();
+    private scrollTimer: unknown;
+    private publishing = false;
+    private disposed = false;
+
+    constructor(language: EditorLanguage, onSymbols: (listener: (result: DocumentSymbolResult) => void) => () => void, timers: Timers = realTimers) {
+        this.language = language;
+        this.timers = timers;
+        const { editor } = language;
+        const offs = [
+            onSymbols((result) => this.read(result)),
+            editor.onTextChange(() => {
+                this.edited = true;
+                this.closeAuthors();
+            }),
+            editor.onViewChange(() => {
+                this.timers.clear(this.scrollTimer);
+                this.scrollTimer = this.timers.set(() => this.plan(), SCROLL_PAUSE_MS);
+            })
+        ];
+        const providers = language.onProvidersChanged(() => {
+            this.failed.clear();
+            this.publish();
+            this.plan();
+        });
+        language.onDispose(() => {
+            this.disposed = true;
+            for (const off of offs) {
+                off();
+            }
+            providers();
+            this.timers.clear(this.scrollTimer);
+            for (const controller of this.running.values()) {
+                controller.abort();
+            }
+            this.closeAuthors();
+            editor.setCodeVision([]);
+        });
+    }
+
+    /* Which rows to draw, from the settings of the client. */
+    configure(settings: CodeVisionSettings): void {
+        if (settings.usages === this.settings.usages && settings.authors === this.settings.authors) {
+            return;
+        }
+        this.settings = settings;
+        this.publish();
+        this.plan();
+    }
+
+    /* What git says about the file, from the client that asked it. */
+    setBlame(blame: BlameSource | null): void {
+        this.blame = blame;
+        this.mapped = null;
+        this.authorships.clear();
+        this.publish();
+    }
+
+    private read(result: DocumentSymbolResult): void {
+        const { editor, languageId } = this.language;
+        const lines = splitLines(editor.getText());
+        this.lines = lines;
+        this.mapped = null;
+        this.authorships.clear();
+        this.edited = false;
+        this.declarations =
+            lines.length > MAX_LINES ? [] : declarationsOf(result, { lineCount: lines.length, lineAt: (line) => lines[line] ?? '', languageId });
+        this.epoch++;
+        this.failed.clear();
+        this.publish();
+        this.plan();
+    }
+
+    private get canCount(): boolean {
+        return this.settings.usages && this.language.project.service.supports(REFERENCES, this.language.uri);
+    }
+
+    /* Queues the declarations in view whose count is not from the current text, nearest the top of the view first. */
+    private plan(): void {
+        if (this.disposed || this.edited || !this.canCount) {
+            return;
+        }
+        const view = this.language.editor.getVisibleRange();
+        const first = view.start.line - MARGIN_LINES;
+        const last = view.end.line + MARGIN_LINES;
+        this.queue = this.declarations
+            .filter(
+                (declaration) =>
+                    declaration.usages &&
+                    declaration.line >= first &&
+                    declaration.line <= last &&
+                    this.counts.get(declaration.id)?.epoch !== this.epoch &&
+                    !this.running.has(declaration.id) &&
+                    !this.failed.has(declaration.id)
+            )
+            .sort((left, right) => Math.abs(left.line - view.start.line) - Math.abs(right.line - view.start.line));
+        while (this.running.size < MAX_PARALLEL && this.queue.length > 0) {
+            void this.count(this.queue.shift()!);
+        }
+    }
+
+    private async count(declaration: CodeVisionDeclaration): Promise<void> {
+        const { project, uri } = this.language;
+        const controller = new AbortController();
+        this.running.set(declaration.id, controller);
+        const epoch = this.epoch;
+        try {
+            const locations = await project.service.references(uri, declaration.position, false, { signal: controller.signal, parallel: true });
+            if (!this.disposed && epoch === this.epoch) {
+                this.counts.set(declaration.id, { count: distinctPlaces(locations ?? []), epoch });
+                this.publish();
+            }
+        } catch {
+            // A text that moved on is counted again from its own symbols; for a server that is not up the declaration waits for it to say so.
+            if (epoch === this.epoch) {
+                this.failed.add(declaration.id);
+            }
+        } finally {
+            this.running.delete(declaration.id);
+            this.plan();
+        }
+    }
+
+    /* Said once for every change that lands in the same turn, since each is a pass over the rows of the layout. */
+    private publish(): void {
+        if (this.publishing) {
+            return;
+        }
+        this.publishing = true;
+        queueMicrotask(() => {
+            this.publishing = false;
+            if (!this.disposed) {
+                this.language.editor.setCodeVision(this.rows());
+            }
+        });
+    }
+
+    private rows(): EditorCodeVision[] {
+        const rows: EditorCodeVision[] = [];
+        const taken = new Set<number>();
+        const counted = this.canCount;
+        const withAuthors = this.settings.authors && this.blame !== null;
+        const commits = this.blame?.kind === 'ready' ? this.blame.blame.commits : [];
+        const mapped = this.blame?.kind === 'ready' && this.settings.authors ? this.mapOfBlame(this.blame) : null;
+        for (const declaration of this.declarations) {
+            const reserved = (counted && declaration.usages) || (withAuthors && declaration.authors);
+            if (!reserved || taken.has(declaration.line)) {
+                continue;
+            }
+            taken.add(declaration.line);
+            const entries: EditorCodeVisionEntry[] = [];
+            const known = this.counts.get(declaration.id);
+            if (counted && declaration.usages && known !== undefined) {
+                entries.push({
+                    id: 'usages',
+                    text: usagesText(known.count, this.language.project.i18n),
+                    activate: () => void this.language.peek.open(declaration.position)
+                });
+            }
+            if (mapped !== null && declaration.authors) {
+                let authorship = this.authorships.get(declaration.id);
+                if (authorship === undefined) {
+                    authorship = authorshipOf(commits, mapped, this.lines, declaration.authorFrom, declaration.authorTo);
+                    this.authorships.set(declaration.id, authorship);
+                }
+                const shown = authorship;
+                entries.push({
+                    id: 'authors',
+                    text: authorsText(shown, this.language.project.i18n),
+                    ...(shown.authors.length > 0 ? { icon: shown.authors.length > 1 ? ('users' as const) : ('user' as const) } : {}),
+                    activate: (anchor) => this.showAuthors(declaration, shown, anchor)
+                });
+            }
+            rows.push({ id: declaration.id, line: declaration.line, entries });
+        }
+        return rows;
+    }
+
+    private mapOfBlame(source: Extract<BlameSource, { kind: 'ready' }>): Int32Array | null {
+        if (this.mapped?.blame !== source.blame) {
+            this.mapped = { blame: source.blame, lines: mapBlame(source.blame, source.base, this.lines) };
+        }
+        return this.mapped.lines;
+    }
+
+    private showAuthors(declaration: CodeVisionDeclaration, authorship: CodeAuthorship, anchor: EditorRect): void {
+        const source = this.blame;
+        const openCommit = source?.kind === 'ready' ? source.openCommit : undefined;
+        this.language.popups.setState({
+            authors: {
+                anchor,
+                name: declaration.name,
+                authorship,
+                openCommit: openCommit === undefined || authorship.latest === null ? null : () => openCommit(authorship.latest!.hash)
+            }
+        });
+    }
+
+    /* Closes the card of the authors; `restoreFocus` is for a close that came from the keyboard, which gives the editor its keys back. */
+    closeAuthors(restoreFocus = false): void {
+        if (this.language.popups.getState().authors !== null) {
+            this.language.popups.setState({ authors: null });
+            if (restoreFocus) {
+                this.language.editor.focus();
+            }
+        }
+    }
+}
+
+/* The places a server named, each counted once however many ways it was reached. */
+function distinctPlaces(locations: readonly { uri: string; range: { start: { line: number; character: number } } }[]): number {
+    return new Set(locations.map((location) => `${location.uri}\0${location.range.start.line}\0${location.range.start.character}`)).size;
+}

package/src/completion-call.ts

@@ -0,0 +1,139 @@
+import type { CompletionItem } from '@adecore/lsp';
+import { CLASS_KIND, CONSTRUCTOR_KIND, FUNCTION_KIND, METHOD_KIND, SNIPPET_FORMAT, type Insertion } from './completion-model.ts';
+
+/* What the platform's editors send to ask for parameter info once an item is in; the card is ours to open. */
+export const PARAMETER_HINTS_COMMAND = 'editor.action.triggerParameterHints';
+
+const CALL_LANGUAGES = new Set(['typescript', 'typescriptreact', 'javascript', 'javascriptreact', 'vue', 'php', 'python']);
+const MARKUP_LANGUAGES = new Set(['typescriptreact', 'javascriptreact', 'vue']);
+
+const IMPORT_BRACE = /\b(?:import|export)(?:\s+type)?(?:\s+[\w$]+\s*,)?\s*$/;
+const PHP_USE_BRACE = /\buse(?:\s+(?:function|const))?\s+[\w\\]*\\\s*$/;
+const TYPE_OPERATOR = /\b(?:typeof|keyof|instanceof|implements|satisfies|as)\s+[\w$.?]*$/;
+const AFTER_NEW = /\bnew\s+[\w$.\\]*$/;
+const EXISTING_CALL = /^\s*\(/;
+const SIGNATURE_KIND_PREFIX = /^\([a-z]+(?: [a-z]+)*\)\s+(?!=>)/;
+const SOURCE_LINE = /^(?:use\s|Auto import from\b)/;
+
+/*
+ * What accepting an item does about the call it names: nothing, parentheses added with the caret inside or
+ * after them, or the parenthesis that is already there, which the caret goes into on Tab and stays out of on Enter.
+ */
+export type CallPlan =
+    | { readonly action: 'none' }
+    | { readonly action: 'add'; readonly inside: boolean }
+    | { readonly action: 'enter'; readonly shift: number };
+
+export interface CallSite {
+    readonly item: CompletionItem;
+    readonly languageId: string;
+    readonly insertion: Insertion;
+    /* The text before the insertion, from some lines up, so a list that spans lines is still seen whole. */
+    readonly before: string;
+    /* The rest of the line after what the insertion replaces. */
+    readonly rest: string;
+    readonly replace: boolean;
+}
+
+/* Whether the item is something that is called where it stands: a function, a method, a constructor, or a class after `new`. */
+export function isCallItem(item: CompletionItem, lineBefore: string): boolean {
+    if (item.kind === METHOD_KIND || item.kind === FUNCTION_KIND || item.kind === CONSTRUCTOR_KIND) {
+        return true;
+    }
+    return item.kind === CLASS_KIND && AFTER_NEW.test(lineBefore);
+}
+
+/* Whether the parameter list in a signature has anything in it; null when the text names no list. */
+function listedParameters(signature: string): boolean | null {
+    const text = signature.replace(SIGNATURE_KIND_PREFIX, '');
+    const open = text.indexOf('(');
+    if (open < 0) {
+        return null;
+    }
+    let depth = 0;
+    for (let i = open; i < text.length; i++) {
+        if (text[i] === '(') {
+            depth++;
+        } else if (text[i] === ')' && --depth === 0) {
+            return text.slice(open + 1, i).trim() !== '';
+        }
+    }
+    return null;
+}
+
+/* From what the server says of the item: `(method) Box.open(flag: boolean): void` has parameters and `(): void` has none. Null when it says nothing about them. */
+export function hasParameters(item: CompletionItem): boolean | null {
+    const lines = (item.detail ?? '').split('\n').filter((line) => !SOURCE_LINE.test(line.trim()));
+    for (const signature of [item.labelDetails?.detail ?? '', ...lines]) {
+        const listed = listedParameters(signature);
+        if (listed !== null) {
+            return listed;
+        }
+    }
+    return null;
+}
+
+/* The text before the innermost brace that is still open, which says whether the caret is in an import or export list. */
+function beforeOpenBrace(before: string): string | null {
+    let depth = 0;
+    for (let i = before.length - 1; i >= 0; i--) {
+        if (before[i] === '}') {
+            depth++;
+        } else if (before[i] === '{' && depth-- === 0) {
+            return before.slice(0, i);
+        }
+    }
+    return null;
+}
+
+/* Where a name is not called: in an import or export list, a `use`, a type operator's operand, an attribute or a tag. */
+function isNameOnly(languageId: string, before: string): boolean {
+    const lineBefore = before.slice(before.lastIndexOf('\n') + 1);
+    const brace = beforeOpenBrace(before);
+    if (brace !== null && (IMPORT_BRACE.test(brace) || (languageId === 'php' && PHP_USE_BRACE.test(brace)))) {
+        return true;
+    }
+    if (TYPE_OPERATOR.test(lineBefore) || /^\s*export\s+default\s+[\w$]*$/.test(lineBefore)) {
+        return true;
+    }
+    switch (languageId) {
+        case 'php':
+            return /^\s*use\s/.test(lineBefore) || /#\[[^\]]*$/.test(lineBefore);
+        case 'python':
+            return /^\s*(?:from\s+\S+\s+)?import\b/.test(lineBefore);
+        default:
+            return /^\s*import\b/.test(lineBefore) || (MARKUP_LANGUAGES.has(languageId) && /<\/?[\w$.:-]*$/.test(lineBefore));
+    }
+}
+
+/*
+ * Decides what accepting `item` does about a call, as the platform's parentheses handler does: a callable
+ * gets `()` with the caret inside when it has parameters (or when that is not known) and behind when it has
+ * none, and one that already has a parenthesis after it gets none. A snippet, or text that already holds a
+ * parenthesis, carries its own call and wins.
+ */
+export function planCall(site: CallSite): CallPlan {
+    const { item, languageId, insertion, before, rest, replace } = site;
+    const lineBefore = before.slice(before.lastIndexOf('\n') + 1);
+    if (!CALL_LANGUAGES.has(languageId) || !isCallItem(item, lineBefore) || item.insertTextFormat === SNIPPET_FORMAT || insertion.text.includes('(')) {
+        return { action: 'none' };
+    }
+    if (isNameOnly(languageId, before)) {
+        return { action: 'none' };
+    }
+    const existing = EXISTING_CALL.exec(rest);
+    if (existing !== null) {
+        return replace ? { action: 'enter', shift: existing[0].length } : { action: 'none' };
+    }
+    if (rest.startsWith('<')) {
+        return { action: 'none' };
+    }
+    return { action: 'add', inside: hasParameters(item) !== false };
+}
+
+/* The insertion with its parentheses, and the one tab stop that puts the caret where the plan says. */
+export function withParentheses(insertion: Insertion, inside: boolean): Insertion {
+    const text = `${insertion.text}()`;
+    const caret = inside ? text.length - 1 : text.length;
+    return { range: insertion.range, text, stops: [{ index: 0, start: caret, end: caret }] };
+}