urls-le: Instructions file for Codex

AGENTS.md — URLs-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 URLs (http/https/ftp/file/mailto/tel) from the active document — any document — into a results editor, with dedupe/sort post-processing. Markdown, HTML, CSS, JS/TS, JSON, YAML, Properties, TOML, INI and XML know what to exclude; every other languageId is scanned whole. No network access — URLs are read from text, never fetched or validated.

Architecture

extension.ts            activate(): createServices() -> registerCommands()
services/serviceFactory createServices(context) -> { telemetry, notifier, statusBar }
commands/               one file per command; deps injected as a frozen bag
mcp/                    MCP server: transport.ts holds the hand-rolled
                        protocol (one swap seam), tools.ts the tool table,
                        envelope.ts the normalisation boundary, fileType.ts a
                        tolerant format resolver. Imports the engine only —
                        never vscode. provider.ts is the one exception: it is
                        the VS Code side, offering the built server to agent
                        mode, and is not part of the server bundle.
extraction/extract.ts   dispatcher: languageId -> FileType -> extractor;
                        content-size cap (10MB), URL-count cap (50k), unknown
                        languages take the plain-text scan (no refusal)
extraction/heuristics.ts  THE single URL scanner: five protocol patterns,
                        scanUrls() -> UrlMatch[], toUrls() enrichment,
                        locateParsedValues() for parser-based formats
extraction/position.ts    offset -> {line, column} via newline index (1-based)
extraction/formats/*.ts   one extractor per format; scan-based ones filter the
                        shared scan (markdown: code regions, html: comments,
                        properties: comment lines), parser-based ones
                        (json/toml/ini) walk tokens or values, and
                        plaintext.ts is the unfiltered scan every other
                        languageId gets
ui/                     notifier (window messages, gated by notificationsLevel:
                        all -> everything, important -> warn+error, silent ->
                        error only), statusBar
utils/                  errors (sanitizeErrorMessage), safety (size guard +
                        large-file warning)
config/config.ts        getConfiguration() snapshot; CONFIG_DEFAULTS table
types.ts                shared types only — no logic