[release:patch] Improve hover-over and package presentation

Author: EagleoutIce

README.md

@@ -58,6 +58,8 @@ With this extension, you gain access to the following features (as the extension
 
    </details>
 
+7. 📦 [**Package Information**](#package-information): Hover over a call to see which package it comes from and its version from flowR's bundled [package database](#package-database), and get a [Project](#project-view) overview of your declared libraries.
+
 If you notice anything that could be improved, have a feature request, or notice a bug, please [open an issue](#issues-and-feature-requests)!
 
 <details><summary>Reporting an Issue</summary>
@@ -113,7 +115,7 @@ Additionally, we recommend using the [R extension](https://marketplace.visualstu
 
 ### Linting
 
-By default, the extension ships with all linting rules that are available in *flowR*, extensive information about which can be found on the [wiki page](https://github.com/flowr-analysis/flowr/wiki/Linter). Some linters additionally ship with code actions in the form of quick fixes which, once invoked, automatically edit or remove the relevant code snippet.
+By default, the extension enables all linting rules available in *flowR* except `naming-convention` and `roxygen-arguments`; extensive information about the rules can be found on the [wiki page](https://github.com/flowr-analysis/flowr/wiki/Linter). The package-structure rules `software-has-license` and `software-has-tests` are only applied when the file is part of an R package (i.e. a `DESCRIPTION` file is present up the directory tree), so they do not add noise to standalone scripts. You can adjust the enabled rules under `vscode-flowr.linter.enabledRules`. Some linters additionally ship with code actions in the form of quick fixes which, once invoked, automatically edit or remove the relevant code snippet.
 
 To manually invoke the linter, you can use the "Code Quality Analysis (Linter)" command. Additionally, you can modify under what conditions the linter automatically refreshes its results in the extension's settings.
 
@@ -158,7 +160,19 @@ To clear the slice highlighting, use the "Clear Current Slice Presentation" comm
 
 ![A screenshot of a dependency diagram for a piece of code](https://raw.githubusercontent.com/flowr-analysis/vscode-flowr/refs/heads/main/media/dependencies.png)
 
-Using the extension, the sidebar should contain a flowR icon which holds more information on the current file, listing the libraries loaded, the files read and written, and the sourced scripts. If you expand the respective sections, clicking on the found entries should open them in the editor. The context menu (available with a right click) allows you to [slice](#slicing) for the selected entry.
+Using the extension, the sidebar should contain a flowR icon whose **Overview** view holds more information on the current file, listing the libraries loaded, the files read and written, and the sourced scripts. If you expand the respective sections, clicking on the found entries should open them in the editor. The context menu (available with a right click) allows you to [slice](#slicing) for the selected entry.
+
+### Package Information
+
+Hovering over a call in an R file tells you which package it stems from — for example, hovering over `map` after `library(purrr)` shows *`map` is provided by the `purrr` package*, together with the version recorded in flowR's [package database](#package-database) and a link to the package's CRAN page. Hovering over the package name inside `library(pkg)`/`require(pkg)` shows that package's database version and CRAN link. For locally defined functions and variables, <kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+click (Go to Definition) jumps to their definition.
+
+### Project View
+
+When the open workspace contains an R project manifest — a `renv.lock`, a `DESCRIPTION`, or an `rv.lock`/`rproject.toml` — a **Project** tab appears in the flowR sidebar. It lists the libraries each manifest declares and, for every one, whether flowR's [package database](#package-database) knows it: matched (with the database version), a base package bundled with R, unmatched, or unavailable. The tab is hidden when no manifest is detected.
+
+### Package Database
+
+flowR resolves the exports, definitions and versions of external packages from a precomputed *package database* that ships with the extension, so package attribution works out of the box without a local R installation. It powers the [package information](#package-information) hovers, the [project view](#project-view) matching, and dependency resolution. The active database (scope and date) is shown when hovering the flowR status-bar item and in the REPL banner. You can toggle it or point at a custom database under the `vscode-flowr.config.solver.pkgdb.*` settings.
 
 ### Value Resolution
 

package.json

@@ -805,7 +805,7 @@
         {
           "id": "flowr-dependencies",
           "icon": "$(notebook-template)",
-          "name": "Dependencies"
+          "name": "Overview"
         },
         {
           "id": "flowr-project",

src/flowr/internal-session.ts

@@ -404,16 +404,29 @@ export class FlowrInternalSession implements FlowrSession {
 		});
 	}
 
-	public async runRepl(config: Omit<Required<FlowrReplOptions>, 'parser'>) {
+	/**
+	 * Builds the analyzer the REPL runs on (validating the flowR configuration) and the banner shown on start,
+	 * which includes the flowR/engine versions and the active package database. Split out from {@link runRepl}
+	 * so it can be exercised in tests without entering the interactive read loop (which would end the process).
+	 */
+	public async replStartup(): Promise<{ analyzer: FlowrAnalyzer, banner: string } | undefined> {
 		if(!this.parser) {
-			return;
+			return undefined;
 		}
 		const analyzer = await new FlowrAnalyzerBuilder()
 			.setParser(this.parser)
 			.setConfig(VSCodeFlowrConfiguration)
 			.build();
-		(config.output as { stdout: (s: string) => void }).stdout(`${await versionReplString(this.parser)}\n${packageDbSummary()}`);
-		await repl({ analyzer: analyzer, ...config });
+		return { analyzer, banner: `${await versionReplString(this.parser)}\n${packageDbSummary()}` };
+	}
+
+	public async runRepl(config: Omit<Required<FlowrReplOptions>, 'parser'>) {
+		const startup = await this.replStartup();
+		if(!startup) {
+			return;
+		}
+		(config.output as { stdout: (s: string) => void }).stdout(startup.banner);
+		await repl({ analyzer: startup.analyzer, ...config });
 	}
 
 	public static getEngineToUse(): KnownParserName {

src/flowr/views/project-view.ts

@@ -1,26 +1,13 @@
 import * as vscode from 'vscode';
 import { Settings } from '../../settings';
 import type { PkgDatabase } from '@eagleoutice/flowr/project/plugins/package-version-plugins/pkgdb';
-import { getPackageDatabase } from '../../package-db';
+import { getPackageDatabase, baseRPackages } from '../../package-db';
 
 export const FlowrProjectViewId = 'flowr-project';
 
 /** context key backing the `when` clause that hides the Project tab until a manifest is found */
 const ProjectContextKey = 'vscode-flowr:hasProject';
 
-/**
- * Packages that ship with R itself (the `base` and `recommended` priority packages). They are never part
- * of the CRAN package database, so we must not flag them as "unmatched" - they are simply always present.
- */
-const BaseAndRecommendedPackages = new Set([
-	// base
-	'base', 'compiler', 'datasets', 'grDevices', 'graphics', 'grid', 'methods', 'parallel', 'splines',
-	'stats', 'stats4', 'tcltk', 'tools', 'translations', 'utils',
-	// recommended
-	'boot', 'class', 'cluster', 'codetools', 'foreign', 'KernSmooth', 'lattice', 'MASS', 'Matrix', 'mgcv',
-	'nlme', 'nnet', 'rpart', 'spatial', 'survival'
-]);
-
 /** how a declared library relates to the package database */
 type MatchStatus = 'matched' | 'base' | 'unmatched' | 'db-unavailable';
 
@@ -34,12 +21,12 @@ interface LibraryMatch {
 type PackageLookup = Pick<PkgDatabase, 'lookup'>;
 
 /**
- * Classifies a declared library against the package database: base/recommended packages (which ship with R
- * and are never in the CRAN database) are recognised up front; otherwise we report whether the database
- * knows the package, or that the database itself was unavailable.
+ * Classifies a declared library against the package database: base packages (part of R itself, never in the
+ * CRAN database) are recognised up front; otherwise we report whether the database knows the package, or that
+ * the database itself was unavailable.
  */
 export function classifyLibrary(name: string, db: PackageLookup | undefined): LibraryMatch {
-	if(BaseAndRecommendedPackages.has(name)) {
+	if(baseRPackages.has(name)) {
 		return { status: 'base' };
 	}
 	if(!db) {
@@ -59,12 +46,16 @@ interface DeclaredLibrary {
 
 interface ProjectManifest {
 	/** absolute path of the manifest file */
-	uri:       vscode.Uri;
+	uri:             vscode.Uri;
 	/** short, human-readable label (relative to the workspace folder) */
-	label:     string;
+	label:           string;
 	/** e.g. `renv`, `DESCRIPTION`, `rv` */
-	kind:      string;
-	libraries: DeclaredLibrary[];
+	kind:            string;
+	/** the package this manifest itself describes (from a `DESCRIPTION`'s `Package:` field), if any */
+	packageName?:    string;
+	/** the version this manifest declares for itself (from a `DESCRIPTION`'s `Version:` field), if any */
+	packageVersion?: string;
+	libraries:       DeclaredLibrary[];
 }
 
 /** the tree is two levels deep: manifests at the top, their libraries below */
@@ -92,7 +83,7 @@ const statusPresentations: Record<MatchStatus, StatusPresentation> = {
 	base: {
 		icon:    'library',
 		badge:   () => 'bundled with R',
-		tooltip: node => `\`${node.library.name}\` is a base/recommended package that ships with R.`
+		tooltip: node => `\`${node.library.name}\` is a base package that is part of R itself.`
 	},
 	unmatched: {
 		icon:    'circle-slash',
@@ -113,31 +104,47 @@ const statusPresentations: Record<MatchStatus, StatusPresentation> = {
  */
 export function registerProjectView(output: vscode.OutputChannel): { dispose: () => void } {
 	const data = new FlowrProjectTreeView(output);
-	const tv = vscode.window.createTreeView(FlowrProjectViewId, { treeDataProvider: data });
-	data.setTreeView(tv);
+	const disposables: vscode.Disposable[] = [];
+	let treeView: vscode.TreeView<ProjectNode> | undefined;
 
 	// re-scan when project manifests appear/change/disappear or the workspace layout changes
 	const watcher = vscode.workspace.createFileSystemWatcher('**/{renv.lock,DESCRIPTION,rv.lock,rproject.toml}');
 	const refresh = () => void data.refresh();
 	watcher.onDidCreate(refresh);
 	watcher.onDidChange(refresh);
 	watcher.onDidDelete(refresh);
-	const disposeFolders = vscode.workspace.onDidChangeWorkspaceFolders(refresh);
-	const disposeConfig = vscode.workspace.onDidChangeConfiguration(e => {
-		if(e.affectsConfiguration(Settings.Category)) {
-			refresh();
+	disposables.push(
+		watcher,
+		vscode.workspace.onDidChangeWorkspaceFolders(refresh),
+		vscode.workspace.onDidChangeConfiguration(e => {
+			if(e.affectsConfiguration(Settings.Category)) {
+				refresh();
+			}
+		})
+	);
+
+	// The view is contributed behind a `when: vscode-flowr:hasProject` clause so it stays hidden until a manifest
+	// is found. Some editors (e.g. Positron) do not register a `when`-hidden view yet, so creating the tree view
+	// while the context is unset errors with "No view is registered". We therefore enable the context first, then
+	// create the view, then let refresh() set the real state (hiding it again when there is no project).
+	void (async() => {
+		await vscode.commands.executeCommand('setContext', ProjectContextKey, true);
+		try {
+			treeView = vscode.window.createTreeView(FlowrProjectViewId, { treeDataProvider: data });
+			data.setTreeView(treeView);
+		} catch(e) {
+			output.appendLine(`[Project View] Could not create the tree view: ${(e as Error).message}`);
 		}
-	});
-
-	void data.refresh();
+		await data.refresh();
+	})();
 
 	return {
 		dispose: () => {
-			tv.dispose();
-			watcher.dispose();
-			disposeFolders.dispose();
-			disposeConfig.dispose();
+			treeView?.dispose();
 			data.dispose();
+			for(const d of disposables) {
+				d.dispose();
+			}
 		}
 	};
 }
@@ -200,11 +207,16 @@ class FlowrProjectTreeView implements vscode.TreeDataProvider<ProjectNode> {
 }
 
 function manifestTreeItem(manifest: ProjectManifest): vscode.TreeItem {
-	const item = new vscode.TreeItem(manifest.label, vscode.TreeItemCollapsibleState.Expanded);
-	item.description = `${manifest.kind} · ${manifest.libraries.length} librar${manifest.libraries.length === 1 ? 'y' : 'ies'}`;
-	item.iconPath = new vscode.ThemeIcon('project');
+	// when the manifest describes a package itself (a DESCRIPTION), surface that package's name and version
+	const libraryCount = `${manifest.libraries.length} librar${manifest.libraries.length === 1 ? 'y' : 'ies'}`;
+	const item = new vscode.TreeItem(manifest.packageName ?? manifest.label, vscode.TreeItemCollapsibleState.Expanded);
+	item.description = [manifest.packageVersion && `v${manifest.packageVersion}`, manifest.kind, libraryCount].filter(Boolean).join(' · ');
+	item.iconPath = new vscode.ThemeIcon('package');
 	item.resourceUri = manifest.uri;
-	item.tooltip = new vscode.MarkdownString(`Detected ${manifest.kind} manifest\n\n\`${manifest.uri.fsPath}\``);
+	const title = manifest.packageName
+		? `\`${manifest.packageName}\`${manifest.packageVersion ? ` version ${manifest.packageVersion}` : ''} — ${manifest.kind}`
+		: `Detected ${manifest.kind} manifest`;
+	item.tooltip = new vscode.MarkdownString(`${title}\n\n\`${manifest.uri.fsPath}\``);
 	item.command = { command: 'vscode.open', title: 'Open manifest', arguments: [manifest.uri] };
 	return item;
 }
@@ -221,16 +233,18 @@ function libraryTreeItem(node: LibraryNode): vscode.TreeItem {
 
 /* ------------------------------------------------------------------ detection ------------------------------------------------------------------ */
 
-/** binds a manifest file name to the project kind it represents and the parser that reads its libraries */
+/** binds a manifest file name to the project kind it represents and the parsers that read it */
 interface ManifestDetector {
 	file:  string;
 	kind:  string;
 	parse: (content: string) => DeclaredLibrary[];
+	/** optional: extract the package this manifest describes itself (name/version) */
+	meta?: (content: string) => { packageName?: string, packageVersion?: string };
 }
 
 const manifestDetectors: readonly ManifestDetector[] = [
 	{ file: 'renv.lock', kind: 'renv', parse: parseRenvLock },
-	{ file: 'DESCRIPTION', kind: 'DESCRIPTION', parse: parseDescription },
+	{ file: 'DESCRIPTION', kind: 'DESCRIPTION', parse: parseDescription, meta: parseDescriptionMeta },
 	{ file: 'rv.lock', kind: 'rv', parse: parseRvLock },
 	{ file: 'rproject.toml', kind: 'rv', parse: parseRvToml }
 ];
@@ -239,7 +253,7 @@ async function detectManifests(output: vscode.OutputChannel): Promise<ProjectMan
 	const folders = vscode.workspace.workspaceFolders ?? [];
 	const manifests: ProjectManifest[] = [];
 	for(const folder of folders) {
-		for(const { file, kind, parse } of manifestDetectors) {
+		for(const { file, kind, parse, meta } of manifestDetectors) {
 			const uri = vscode.Uri.joinPath(folder.uri, file);
 			let content: string;
 			try {
@@ -248,7 +262,7 @@ async function detectManifests(output: vscode.OutputChannel): Promise<ProjectMan
 				continue; // file does not exist
 			}
 			try {
-				manifests.push({ uri, label: file, kind, libraries: dedupeLibraries(parse(content)) });
+				manifests.push({ uri, label: file, kind, ...meta?.(content), libraries: dedupeLibraries(parse(content)) });
 			} catch(e) {
 				output.appendLine(`[Project View] Failed to parse ${uri.fsPath}: ${(e as Error).message}`);
 				manifests.push({ uri, label: file, kind, libraries: [] });
@@ -284,6 +298,12 @@ export function parseRenvLock(content: string): DeclaredLibrary[] {
 	}));
 }
 
+/** Extracts the package this `DESCRIPTION` describes itself: its `Package:` name and `Version:`. */
+export function parseDescriptionMeta(content: string): { packageName?: string, packageVersion?: string } {
+	const field = (name: string) => new RegExp(`^${name}\\s*:\\s*(.+)$`, 'm').exec(content.replace(/\r\n/g, '\n'))?.[1].trim();
+	return { packageName: field('Package'), packageVersion: field('Version') };
+}
+
 /** Extracts the packages listed in the `Depends`/`Imports`/`Suggests`/`LinkingTo` fields of a `DESCRIPTION` file. */
 export function parseDescription(content: string): DeclaredLibrary[] {
 	// DESCRIPTION is a DCF file; the dependency fields are comma-separated, possibly wrapped across lines

src/package-db.ts

@@ -2,6 +2,15 @@ import { PkgDatabase } from '@eagleoutice/flowr/project/plugins/package-version-
 import { getBundledPackageDbPath } from './extension';
 import { getConfig, Settings } from './settings';
 
+/**
+ * R's base priority packages: part of R itself, available without an explicit `library()`, and never
+ * published on CRAN (so they never appear in the package database).
+ */
+export const baseRPackages = new Set([
+	'base', 'compiler', 'datasets', 'grDevices', 'graphics', 'grid', 'methods', 'parallel',
+	'splines', 'stats', 'stats4', 'tcltk', 'tools', 'translations', 'utils'
+]);
+
 /** cached database, keyed by the file path it was loaded from */
 let cache: { path: string, db: PkgDatabase } | undefined;