paths-le AGENTS.md

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.

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

Conventions: factory functions + Object.freeze (no classes), guard clauses, dependency bags typed inline at the consumer — see Code style below. Both the manifest and the runtime strings are localized into 12 locales; see Toolchain.