paths-le

<p align="center">
  <img src="src/assets/images/icon.png" alt="Paths-LE Logo" width="96" height="96"/>
</p>
<h1 align="center">Paths-LE: Zero Hassle Path Extraction</h1>
<p align="center">
  <b>Pull every file path out of the current file in one keystroke</b><br/>
  <i>JavaScript, TypeScript, JSON, YAML, HTML, CSS, TOML, CSV and Environment files — and every other file, by text scan</i>
</p>

<p align="center">
  <a href="https://marketplace.visualstudio.com/items?itemName=nolindnaidoo.paths-le">
    <img src="https://img.shields.io/badge/Install%20from-VS%20Code-blue?style=for-the-badge&logo=visualstudiocode" alt="Install from VS Code Marketplace" />
  </a>
  <a href="https://open-vsx.org/extension/OffensiveEdge/paths-le">
    <img src="https://img.shields.io/open-vsx/dt/OffensiveEdge/paths-le?style=for-the-badge&label=Open%20VSX&color=blue" alt="Open VSX downloads" />
  </a>
  <a href="https://www.npmjs.com/package/paths-le-mcp">
    <img src="https://img.shields.io/npm/v/paths-le-mcp?style=for-the-badge&label=MCP%20server&color=blue&logo=npm" alt="paths-le-mcp on npm" />
  </a>
  <a href="https://crates.io/crates/paths-le">
    <img src="https://img.shields.io/crates/v/paths-le?style=for-the-badge&label=Rust%20CLI&color=blue&logo=rust" alt="paths-le on crates.io" />
  </a>
  <a href="https://letools.dev/tools/paths-le">
    <img src="https://img.shields.io/badge/LE%20Tools-letools.dev-blue?style=for-the-badge" alt="LE Tools" />
  </a>
</p>

---

<p align="center">
  <img src="src/assets/images/demo.gif" alt="Paths-LE Demo" style="max-width: 100%; height: auto;" />
</p>

> **Useful?** A star or rating is how other developers find it —
> [★ GitHub](https://github.com/nolindnaidoo/paths-le) ·
> [★ Open VSX](https://open-vsx.org/extension/OffensiveEdge/paths-le/reviews) ·
> [★ Marketplace](https://marketplace.visualstudio.com/items?itemName=nolindnaidoo.paths-le&ssr=false#review-details)

## What it does

Open a file, press `Ctrl+Alt+P` (`Cmd+Alt+P` on Mac), and every file path in the document lands in a new editor — deduplicate and sort it from there. Works in VS Code and in VS Code–based editors like Cursor and VSCodium (installable from Open VSX).

- **Import analysis** — extract local imports from JS/TS, including multi-line import statements; npm package names are filtered out
- **Asset auditing** — every `src`, `href`, `srcset`, `url()`, and `@import` in HTML/CSS
- **Config review** — path-like values from JSON/JSONC, YAML, TOML, CSV, and `.env` files
- **Anything else** — Python, Go, Markdown, XML, a Dockerfile: no parser, so a text scan finds quoted filenames and any run carrying a path separator

## Install

| Where | What you get | Install |
|---|---|---|
| **VS Code** | The extraction, in your editor, on a keystroke | [Marketplace](https://marketplace.visualstudio.com/items?itemName=nolindnaidoo.paths-le) |
| **Cursor, VSCodium, Windsurf** | The same extension | [Open VSX](https://open-vsx.org/extension/OffensiveEdge/paths-le) |
| **A terminal or a CI step** | The same run over a whole tree, with exit codes | `cargo install paths-le` · [crates.io](https://crates.io/crates/paths-le) |
| **Any MCP agent, via Node** | `extract_paths` over stdio — the same tool this binary offers | `npx paths-le-mcp` · [npm](https://www.npmjs.com/package/paths-le-mcp) |
| **Zed** | The MCP server as a context server | [add it by hand](https://zed.dev/docs/ai/mcp) *(no listing yet)* |

## Use it from an AI agent

The same engine runs as an [MCP](https://modelcontextprotocol.io) server, so an agent can call it directly instead of you running a command.

| Editor | How |
|---|---|
| **VS Code** 1.101+ | Nothing to install — the extension registers `extract_paths` with agent mode |
| **Zed** | No listing yet — [add the MCP server by hand](https://zed.dev/docs/ai/mcp) |
| **Claude Code** | `claude mcp add paths-le -- npx -y paths-le-mcp` |
| **Cursor, Windsurf, anything else** | point it at `npx paths-le-mcp` |

```
extract_paths(content, format?, filename?, dedupe?, maxResults?)
```

Returns every path classified as file, relative, absolute or url, with its 1-based line and column. Paths are reported exactly as written — nothing is resolved against a workspace or touched on disk.

The server takes content and returns data — it reads no files and makes no network requests of its own. Published as [`paths-le-mcp`](https://www.npmjs.com/package/paths-le-mcp) on npm and as `io.github.nolindnaidoo/paths-le` in the [MCP registry](https://registry.modelcontextprotocol.io).

<details>
<summary><b>Configuring it by hand</b> — any host with an MCP config file</summary>

Most hosts read a JSON config. Add one entry:

```json
{
  "mcpServers": {
    "paths-le": {
      "command": "npx",
      "args": ["-y", "paths-le-mcp"]
    }
  }
}
```

`-y` skips the install prompt on first run. Pin a version if you would rather not track releases — `paths-le-mcp@2.3.3`.

Prefer not to go through `npx` on every launch? Install it once and point at the binary instead:

```bash
npm install -g paths-le-mcp
```

```json
{
  "mcpServers": {
    "paths-le": { "command": "paths-le-mcp" }
  }
}
```

It speaks MCP over stdio and needs no environment variables, no API key and no configuration of its own. To check it before wiring it into anything:

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npx -y paths-le-mcp
```

That prints the tool list and exits — if you see `extract_paths`, the server works.

</details>

## The CLI

The same extraction runs from a terminal or an agent loop: a Rust CLI in
[`crate/`](crate/) of this repository, sharing one corpus with the extension —
[`crate/fixtures/`](crate/fixtures/) — so CI fails if the two ever read a
document differently.

It also does the half an editor cannot: **resolve what it found against the
filesystem it is standing in.** Every path gets a verdict — exists, missing,
escapes the audited tree, non-canonical, or a symlink with its target named.

```bash
paths-le .                    # audit a tree; JSON on stdout, summary on stderr
paths-le --strict .           # count sloppily-written paths too
paths-le --no-resolve src/    # just list what is written, touch nothing
paths-le mcp                  # the same audit over MCP on stdio
```

The exit code is the answer: **0 clear · 1 findings · 2 the question was
malformed** — so `paths-le --strict .` is a CI step as it stands.

## Supported formats

| Format | Language IDs | What gets extracted |
|---|---|---|
| JavaScript / TypeScript | `javascript`, `javascriptreact`, `typescript`, `typescriptreact` | `import`/`export … from`, side-effect imports, dynamic `import()`, `require()` — file paths only, package names excluded |
| JSON / JSONC | `json`, `jsonc` | Path-like string values (comments and trailing commas supported) |
| HTML | `html` | `src`, `href`, `srcset` (each entry), `action`, `poster`, and similar attributes |
| CSS / SCSS / LESS | `css`, `scss`, `less` | `url()` and `@import` |
| TOML | `toml` | Path-like values and keys |
| CSV | `csv` | Path-like cells |
| Environment | `dotenv`, `env` | Path-like variable values and names |
| YAML | `yaml` | Path-like scalar values and keys, across every document in the file |
| Everything else | any other language ID | A text scan: quoted tokens, and undelimited runs that carry a path separator |

Positions are real source positions for JS/TS, JSON/JSONC, HTML, CSS and the text scan (exact line and column of the path); TOML and YAML positions are located in the source text and can be approximate for repeated identical values; CSV positions are row/cell coordinates. Version strings (`1.8.1`) and IP addresses are never treated as paths, and `data:`/`javascript:` URLs are excluded from HTML/CSS extraction. Bare domains (`example.com`, `www.example.org`) are not paths; a name ending in a country-code extension such as `docs.rs` still is.

The text scan claims a bare `name.ext` only inside quotes. `os.path` in a Python file and `main.py` are the same shape, and no rule short of a dictionary separates them — but source quotes its filenames and does not quote its attribute access, so the quoting does. A YAML scalar holding a shell command (`run: node ./scripts/build.js`) is one token containing spaces, so no path is claimed from it, exactly as in JSON and TOML.

## Commands

| Command | Description |
|---|---|
| `Paths-LE: Extract Paths` (`Ctrl+Alt+P` / `Cmd+Alt+P`) | Extract all paths from the active document |
| `Paths-LE: Deduplicate Paths` | Remove duplicate lines from the results |
| `Paths-LE: Sort Paths` | Sort results alphabetically or by length |
| `Paths-LE: Open Settings` | Open Paths-LE settings |
| `Paths-LE: Help` | Built-in documentation |

## Settings

| Setting | Default | Description |
|---|---|---|
| `paths-le.openResultsSideBySide` | `true` | Open results beside the current editor |
| `paths-le.postProcess.openInNewFile` | `true` | Open results in a new file (when not side-by-side) |
| `paths-le.copyToClipboardEnabled` | `false` | Also copy results to the clipboard |
| `paths-le.notificationsLevel` | `silent` | `all` = every notification, `important` = warnings + errors, `silent` = errors only |
| `paths-le.safety.enabled` | `true` | Guardrails for very large files |
| `paths-le.safety.fileSizeWarnBytes` | `1000000` | Refuse extraction above this file size |
| `paths-le.safety.largeOutputLinesThreshold` | `50000` | Warn above this line count |
| `paths-le.statusBar.enabled` | `true` | Show the status bar item |
| `paths-le.telemetryEnabled` | `false` | Local-only event log (see Privacy) |
| `paths-le.resolution.resolveSymlinks` | `false` | ⚠️ Resolve symlinks to canonical paths |
| `paths-le.resolution.resolveWorkspaceRelative` | `false` | ⚠️ Resolve paths against workspace folders |

## Languages

Twelve languages besides English:

German · Spanish · French · Indonesian · Italian · Japanese · Korean ·
Portuguese (Brazil) · Russian · Ukrainian · Vietnamese · Chinese (Simplified)