paths-le: Instructions file for Codex

AGENTS.md — Paths-LE

Technical source of truth for this repo. README.md is the user-facing doc; this file is for anyone (human or agent) changing the code.

This repo hosts two products: the extension at the root (this document's scope) and the Rust CLI in crate/ (its own AGENTS.md + SPEC.md). The shared extraction corpus lives at crate/fixtures/; scripts/check-extraction-parity.ts fails CI when this extension drifts from it.

The Rust CLI also ships a second way, through npm: src/cli/ is its terminal surface rebuilt over this extension's extraction engine, bundled to cli/cli.js as the npm package paths-le. Both install a command named paths-le, so the npm one is held to the crate's surface byte for byte, which is a different contract from the extraction parity above. src/cli/ follows crate/src/cli.rs, audit.rs, resolve.rs, walk.rs and mcp/mod.rs, not the extension's commands, and scripts/check-cli-parity.ts runs both binaries over one generated tree and fails on any difference in stdout, stderr or exit code, and in what paths-le mcp answers. scripts/check-cli-pipes.ts, shared with every port, closes stdout or stderr before either binary writes and fails on any difference in what follows, on all three operating systems. A change to the crate's surface changes src/cli/ in the same commit.

What this is

A VS Code extension that extracts file paths from the active document — JS/TS, JSON/JSONC, YAML, HTML, CSS/SCSS/LESS, TOML, CSV and dotenv through a parser, every other language through a text scan — into a results editor, with dedupe/sort post-processing. No network access, no filesystem writes outside optional opt-in canonical path resolution (reads only).

Architecture

extension.ts            activate(): createServices() -> registerCommands()
services/serviceFactory createServices(context) -> { telemetry, notifier, statusBar }
commands/               one file per command; deps injected as a frozen bag
extraction/extract.ts   dispatcher: languageId -> FileType -> extractor
extraction/heuristics.ts  THE single isPathLike + classifyPathType
extraction/position.ts    offset -> {line, column} via newline index (1-based)
extraction/formats/*.ts   one extractor per format, whole-content matching
ui/                     notifier (window messages, gated by notificationsLevel:
                        all -> everything, important -> warn+error, silent -> error only),
                        statusBar, help webView
utils/                  errors (sanitizeErrorMessage), safety (size guards),
                        pathResolver (normalize + opt-in canonical resolution)
config/config.ts        getConfiguration() snapshot; CONFIG_DEFAULTS table
types.ts                shared types only — no logic
cli/                    the npm command line: args, walk + ignoreRules
                        (ripgrep's precedence), rustPath (std::path
                        arithmetic), resolve, root, audit, run, and
                        auditTool for `paths-le mcp`. No `vscode`, ever