feat: add openFileInNpmx command for node_modules files (#34)

* test: setup `jest-mock-vscode`

This allows testing code which imports `vscode`, particularly including infrastructure for manipulating `Uri` objects.

* test: add filesystem mocking utility

This is a generic utility for creating a fake filesystem used by `workspace.fs`. Only `readFile` is implemented for now as that's all that's immediately needed, but other functions could be mocked just as easily when they become necessary.

* refactor: resolve files within their local package

This adds a new `resolvePackageRelativePath` function which takes an arbitrary file within `node_modules/` and returns its package-relative path. This is useful for generating links to specific files in npmx.dev.

Given a file path, the logic for finding its associated `package.json` is the following:
* Walk up its ancestor directories.
* Check each for a `package.json` file.
* If the file exists, and has a `name` and `version` field, use that path.
  * The motivation for checking `name` and `version` is to ignore "fake" `package.json` files used for configuring specific directories, such as Webpack's [`sideEffects: false`](https://webpack.js.org/guides/tree-shaking/) flag.
* Calculate the relative path from the `package.json` to the original file path.

For this module, we assume the file path is within a `node_modules/` directory, though this will be actually enforced earlier in the process.

* feat: add `openFileInNpmx` command

This command opens a given file under `node_modules/` in npmx.dev, deep linking to its specific package version, relative file path, and line number. The command is only shown when in a `node_modules/` context and only includes a line number when opening the currently active file.

There are some edge cases for opening files like:
* `node_modules/.bin/foo`
* `node_modules/foo`
* `node_modules/@foo/bar`
* `node_modules/.pnpm`

Ideally these wouldn't even support the command through the `when` filter, but that regex starts to get complicated, so I didn't bite off that complexity here. A potential future feature might be "npmx: Open package" and work specifically on `node_modules/foo` and `node_modules/@foo/bar` directories, opening the package itself rather than deep-linking to any specific file. But such a command is out of scope for now.

* [autofix.ci] apply automated fixes

* fix: improve `node_modules` check

* refactor: move command into `commands`

* refactor: prefer return an object instead of tuple

* fix(explorer): hide context command on folders

* test: fix

* apply suggestions from coderabbit

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Vida Xie <vida_2020@163.com>

Author: 3 people

package.json

@@ -91,8 +91,39 @@
         "command": "npmx.openInBrowser",
         "title": "Open npmx.dev in external browser",
         "category": "npmx"
+      },
+      {
+        "command": "npmx.openFileInNpmx",
+        "title": "Open file on npmx.dev",
+        "category": "npmx"
       }
-    ]
+    ],
+    "menus": {
+      "editor/context": [
+        {
+          "command": "npmx.openFileInNpmx",
+          "when": "resourceScheme == file && resourcePath =~ /[\\/]node_modules[\\/]/"
+        }
+      ],
+      "editor/title": [
+        {
+          "command": "npmx.openFileInNpmx",
+          "when": "resourceScheme == file && resourcePath =~ /[\\/]node_modules[\\/]/"
+        }
+      ],
+      "explorer/context": [
+        {
+          "command": "npmx.openFileInNpmx",
+          "when": "resourceScheme == file && resourcePath =~ /[\\/]node_modules[\\/]/ && !explorerResourceIsFolder"
+        }
+      ],
+      "commandPalette": [
+        {
+          "command": "npmx.openFileInNpmx",
+          "when": "resourceScheme == file && resourcePath =~ /[\\/]node_modules[\\/]/"
+        }
+      ]
+    }
   },
   "scripts": {
     "dev": "tsdown --watch",
@@ -120,6 +151,7 @@
     "eslint": "^9.39.2",
     "fast-npm-meta": "^1.2.0",
     "husky": "^9.1.7",
+    "jest-mock-vscode": "^4.10.0",
     "jsonc-parser": "^3.3.1",
     "module-replacements": "^2.11.0",
     "nano-staged": "^0.9.0",

pnpm-lock.yaml

@@ -0,0 +1,44 @@
+import { logger } from '#state'
+import { npmxFileUrl } from '#utils/links'
+import { resolvePackageRelativePath } from '#utils/resolve'
+import { useActiveTextEditor } from 'reactive-vscode'
+import { env, Uri, window } from 'vscode'
+
+export async function openFileInNpmx(fileUri?: Uri) {
+  const textEditor = useActiveTextEditor()
+
+  // If triggered from context menu, fileUri is provided.
+  // If triggered from command palette, use active text editor.
+  const uri = fileUri ?? textEditor.value?.document.uri
+  if (!uri) {
+    window.showErrorMessage('npmx: No active file selected.')
+    return
+  }
+
+  // Assert the given file is in `node_modules/`, though the command should
+  // already be limited to such files.
+  if (!uri.path.includes('/node_modules/')) {
+    window.showErrorMessage('npmx: Selected file is not within a node_modules folder.')
+    return
+  }
+
+  // Find the associated package manifest and the relative path to the given file.
+  const result = await resolvePackageRelativePath(uri)
+  if (!result) {
+    logger.warn(`Could not resolve npmx url: ${uri.toString()}`)
+    window.showWarningMessage(`npmx: Could not find package.json for ${uri.toString()}`)
+    return
+  }
+  const { manifest, relativePath } = result
+
+  // Use line number only if the user is actively looking at the relevant file
+  const openingActiveFile = !fileUri || fileUri.toString() === textEditor.value?.document.uri.toString()
+
+  // VSCode uses 0-indexed lines, npmx uses 1-indexed lines
+  const vsCodeLine = openingActiveFile ? textEditor.value?.selection.active.line : undefined
+  const npmxLine = vsCodeLine !== undefined ? vsCodeLine + 1 : undefined
+
+  // Construct the npmx.dev URL and open it.
+  const url = npmxFileUrl(manifest.name, manifest.version, relativePath, npmxLine)
+  await env.openExternal(Uri.parse(url))
+}

src/commands/open-file-in-npmx.ts

@@ -8,6 +8,7 @@ import {
 } from '#constants'
 import { defineExtension, useCommands, watchEffect } from 'reactive-vscode'
 import { Disposable, env, languages, Uri } from 'vscode'
+import { openFileInNpmx } from './commands/open-file-in-npmx'
 import { PackageJsonExtractor } from './extractors/package-json'
 import { PnpmWorkspaceYamlExtractor } from './extractors/pnpm-workspace-yaml'
 import { commands, displayName, version } from './generated-meta'
@@ -69,5 +70,6 @@ export const { activate, deactivate } = defineExtension(() => {
     [commands.openInBrowser]: () => {
       env.openExternal(Uri.parse(NPMX_DEV))
     },
+    [commands.openFileInNpmx]: openFileInNpmx,
   })
 })

src/index.ts

@@ -10,6 +10,10 @@ export function npmxDocsUrl(name: string, version: string): string {
   return `${NPMX_DEV}/docs/${name}/v/${version}`
 }
 
+export function npmxFileUrl(name: string, version: string, path: string, line?: number): string {
+  return `${NPMX_DEV}/package-code/${name}/v/${version}/${path}${line !== undefined ? `#L${line}` : ''}`
+}
+
 export function jsrPackageUrl(name: string, version: string): string {
   return `https://jsr.io/${name}@${version}`
 }

src/utils/links.ts

@@ -0,0 +1,87 @@
+import { Uri, workspace } from 'vscode'
+
+/**
+ * Resolves the relative path of a file within its package.
+ *
+ * @param uri The URI of the file to resolve.
+ * @returns A promise that resolves to the package manifest and relative path,
+ *     or `undefined` if not found.
+ */
+export async function resolvePackageRelativePath(uri: Uri): Promise<{ manifest: PackageManifest, relativePath: string } | undefined> {
+  const result = await findPackageJson(uri)
+  if (!result)
+    return undefined
+
+  const { uri: pkgUri, manifest } = result
+  const relativePath = uri.path.slice(pkgUri.path.lastIndexOf('/') + 1)
+
+  return { manifest, relativePath }
+}
+
+/** A parsed `package.json` manifest file. */
+interface PackageManifest {
+  /** Package name. */
+  name: string
+
+  /** Package version specifier. */
+  version: string
+}
+
+/**
+ * Finds the nearest package.json file by searching upwards from the given URI.
+ *
+ * @param file The URI to start the search from.
+ * @returns The URI and parsed content of the package.json, or `undefined` if
+ *     not found.
+ */
+async function findPackageJson(file: Uri): Promise<{ uri: Uri, manifest: PackageManifest } | undefined> {
+  // Start from the directory, so we don't look for
+  // `node_modules/foo/bar.js/package.json`
+  const startDir = Uri.joinPath(file, '..')
+
+  for (const dir of walkAncestors(startDir)) {
+    const pkgUri = Uri.joinPath(dir, 'package.json')
+
+    let pkg: Partial<PackageManifest> | undefined
+    try {
+      const content = await workspace.fs.readFile(pkgUri)
+      pkg = JSON.parse(new TextDecoder().decode(content)) as Partial<PackageManifest>
+    } catch {
+      continue
+    }
+
+    if (isValidManifest(pkg)) {
+      return {
+        uri: pkgUri,
+        manifest: pkg,
+      }
+    }
+  }
+
+  return undefined
+}
+
+function* walkAncestors(start: Uri): Generator<Uri, void, void> {
+  let currentUri = start
+  while (true) {
+    yield currentUri
+
+    if (currentUri.path.endsWith('/node_modules'))
+      return
+
+    const parentUri = Uri.joinPath(currentUri, '..')
+    if (parentUri.toString() === currentUri.toString())
+      return
+
+    currentUri = parentUri
+  }
+}
+
+/**
+ * Check for valid package manifest, as it might be a manifest which just
+ * configures a setting without really being a package (such as
+ * `{sideEffects: false}`).
+ */
+function isValidManifest(json: Partial<PackageManifest>): json is PackageManifest {
+  return Boolean(json && json.name && json.version)
+}

src/utils/resolve.ts

@@ -0,0 +1,27 @@
+import { expect, vi } from 'vitest'
+import { workspace } from 'vscode'
+
+/**
+ * Mocks the VS Code filesystem by intercepting {@link workspace.fs}.
+ *
+ * @param files A record mapping file paths to their string content.
+ */
+export function mockFileSystem(files: Record<string, string>) {
+  // Make all functions throw by default.
+  for (const [name, fn] of Object.entries(workspace.fs)) {
+    if (typeof fn === 'function') {
+      vi.mocked(fn).mockImplementation(() => {
+        expect.fail(`\`workspace.fs.${name}\` is not supported as a fake.`)
+      })
+    }
+  }
+
+  vi.mocked(workspace.fs.readFile).mockImplementation(async (uri) => {
+    const path = uri.path
+    const content = files[path]
+    if (content === undefined) {
+      throw new Error(`File not found: ${uri.toString()}`)
+    }
+    return new TextEncoder().encode(content)
+  })
+}

tests/__mocks__/filesystem.ts

@@ -0,0 +1,17 @@
+import { createVSCodeMock } from 'jest-mock-vscode'
+import { vi } from 'vitest'
+
+const vscode = createVSCodeMock(vi)
+
+export const Uri = vscode.Uri
+export const workspace = vscode.workspace
+export const Range = vscode.Range
+export const Position = vscode.Position
+export const Location = vscode.Location
+export const Selection = vscode.Selection
+export const ThemeColor = vscode.ThemeColor
+export const ThemeIcon = vscode.ThemeIcon
+export const TreeItem = vscode.TreeItem
+export const TreeItemCollapsibleState = vscode.TreeItemCollapsibleState
+export const Disposable = vscode.Disposable
+export default vscode

tests/__mocks__/vscode.ts

@@ -0,0 +1,42 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { Uri, workspace } from 'vscode'
+import { mockFileSystem } from './__mocks__/filesystem'
+
+describe('mockFileSystem', () => {
+  beforeEach(() => {
+    vi.resetAllMocks()
+  })
+
+  describe('`readFile`', () => {
+    it('should mock matched paths', async () => {
+      mockFileSystem({
+        '/test/file.txt': 'hello world',
+      })
+
+      const uri = Uri.file('/test/file.txt')
+      const content = await workspace.fs.readFile(uri)
+
+      expect(new TextDecoder().decode(content)).toBe('hello world')
+    })
+
+    it('should throw error for unmatched paths', async () => {
+      mockFileSystem({})
+
+      const uri = Uri.file('/does-not-exist.txt')
+      await expect(workspace.fs.readFile(uri)).rejects.toThrow('File not found')
+    })
+
+    it('should handle multiple files', async () => {
+      mockFileSystem({
+        '/a.js': 'content a',
+        '/b.js': 'content b',
+      })
+
+      const contentA = await workspace.fs.readFile(Uri.file('/a.js'))
+      const contentB = await workspace.fs.readFile(Uri.file('/b.js'))
+
+      expect(new TextDecoder().decode(contentA)).toBe('content a')
+      expect(new TextDecoder().decode(contentB)).toBe('content b')
+    })
+  })
+})