{"_id":"@a11yst/source-mapping","_rev":"3-25a888a882c9c6c2291f7410b1c5dc96","name":"@a11yst/source-mapping","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@a11yst/source-mapping","version":"1.0.0","license":"MPL-2.0","_id":"@a11yst/source-mapping@1.0.0","maintainers":[{"name":"angelabenavente","email":"ang.ben.dev@gmail.com"}],"homepage":"https://github.com/angelabenavente/a11yst#readme","bugs":{"url":"https://github.com/angelabenavente/a11yst/issues"},"dist":{"shasum":"767ccd91be976f03b9aa9346ee42760f1b378bad","tarball":"https://registry.npmjs.org/@a11yst/source-mapping/-/source-mapping-1.0.0.tgz","fileCount":47,"integrity":"sha512-q/YDLL57AEMR1Iq0vzX3oDuPKU8B1LEKgC2UMsPjJliHaqUVS56xWxxOXg2C8o+A7ZbgZUXJI3agwZo5/TiQqw==","signatures":[{"sig":"MEUCIC2OTfKyBWEd6xKSakZv/GxopwEXoLddsqeoLpAQoxpGAiEAqywN15qoQ7zANle7XlWusNc/aqnxTSid1VOxlwTsljM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":95194},"main":"./dist/index.js","type":"module","_from":"file:a11yst-source-mapping-1.0.0.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc -p tsconfig.json","clean":"rm -rf dist *.tsbuildinfo","typecheck":"tsc -p tsconfig.json --noEmit"},"_npmUser":{"name":"angelabenavente","email":"ang.ben.dev@gmail.com"},"_resolved":"/private/var/folders/tf/l5jz90dj0yncc_ds04tbfs5c0000gn/T/edaba952829fd48bed4f37e6f43e66f9/a11yst-source-mapping-1.0.0.tgz","_integrity":"sha512-q/YDLL57AEMR1Iq0vzX3oDuPKU8B1LEKgC2UMsPjJliHaqUVS56xWxxOXg2C8o+A7ZbgZUXJI3agwZo5/TiQqw==","repository":{"url":"git+https://github.com/angelabenavente/a11yst.git","type":"git"},"_npmVersion":"10.9.0","description":"Pure source mapping domain model for a11yst findings","directories":{},"_nodeVersion":"22.12.0","dependencies":{"@a11yst/types":"1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.2"},"_npmOperationalInternal":{"tmp":"tmp/source-mapping_1.0.0_1787506236417_0.9484032834413134","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@a11yst/source-mapping","version":"1.0.1","license":"MPL-2.0","_id":"@a11yst/source-mapping@1.0.1","maintainers":[{"name":"angelabenavente","email":"ang.ben.dev@gmail.com"}],"homepage":"https://github.com/angelabenavente/a11yst#readme","bugs":{"url":"https://github.com/angelabenavente/a11yst/issues"},"dist":{"shasum":"c4fa26d22e1394410b7b1dea0c44552dbfd49f9f","tarball":"https://registry.npmjs.org/@a11yst/source-mapping/-/source-mapping-1.0.1.tgz","fileCount":47,"integrity":"sha512-dk6HjTH1/nD/BDgZGGIKTDPp8ftPYaIRQzcllKvYcDvxboGK8pkxgdKmN+O+luLhF0+IxfyE7q+zDPBRlf+iRA==","signatures":[{"sig":"MEQCIF7kh6x+1Qr/ziRORwWNln/EU59o9I/XP2WGqWculTRCAiBGME2P/OiITnGWjDA+W2j+VGwFh3+ff9ejGIe4XcwBrQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":95194},"main":"./dist/index.js","type":"module","_from":"file:a11yst-source-mapping-1.0.1.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc -p tsconfig.json","clean":"rm -rf dist *.tsbuildinfo","typecheck":"tsc -p tsconfig.json --noEmit"},"_npmUser":{"name":"angelabenavente","email":"ang.ben.dev@gmail.com"},"_resolved":"/private/var/folders/tf/l5jz90dj0yncc_ds04tbfs5c0000gn/T/0ad5b85aaaf0a71f684cc0a1247f1936/a11yst-source-mapping-1.0.1.tgz","_integrity":"sha512-dk6HjTH1/nD/BDgZGGIKTDPp8ftPYaIRQzcllKvYcDvxboGK8pkxgdKmN+O+luLhF0+IxfyE7q+zDPBRlf+iRA==","repository":{"url":"git+https://github.com/angelabenavente/a11yst.git","type":"git"},"_npmVersion":"10.9.8","description":"Pure source mapping domain model for a11yst findings","directories":{},"_nodeVersion":"22.23.1","dependencies":{"@a11yst/types":"1.0.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.2"},"_npmOperationalInternal":{"tmp":"tmp/source-mapping_1.0.1_1787508668810_0.5240714369553134","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@a11yst/source-mapping","version":"1.0.2","description":"Pure source mapping domain model for a11yst findings","type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"main":"./dist/index.js","types":"./dist/index.d.ts","dependencies":{"@a11yst/types":"1.0.2"},"devDependencies":{"typescript":"^5.7.2"},"license":"MPL-2.0","repository":{"type":"git","url":"git+https://github.com/angelabenavente/a11yst.git"},"homepage":"https://www.a11yst.dev","bugs":{"url":"https://github.com/angelabenavente/a11yst/issues"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit","clean":"rm -rf dist *.tsbuildinfo"},"_id":"@a11yst/source-mapping@1.0.2","_integrity":"sha512-nredMaRqj1xkp51hz1WlsjgNuP9q4IZhNp4KaxF9Qwfy4t9uq4OaXsIbk4m2fOQqhUzWyj25y1gRcKhAiHakVg==","_resolved":"/private/var/folders/tf/l5jz90dj0yncc_ds04tbfs5c0000gn/T/75ed3e8f6f7500b3a1f881f8cf9cbaf8/a11yst-source-mapping-1.0.2.tgz","_from":"file:a11yst-source-mapping-1.0.2.tgz","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-nredMaRqj1xkp51hz1WlsjgNuP9q4IZhNp4KaxF9Qwfy4t9uq4OaXsIbk4m2fOQqhUzWyj25y1gRcKhAiHakVg==","shasum":"62fba0ccf099e02645a5ac98c42e851b1e548517","tarball":"https://registry.npmjs.org/@a11yst/source-mapping/-/source-mapping-1.0.2.tgz","fileCount":47,"unpackedSize":95542,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHqZKcyEhS9Nm/5xZuPIw1UdLuZbOk1YUzCKAaShhVmsAiAaiALqF0p639eh0qEHs6xJFC+jdHuLmQGggX72MAiSxQ=="}]},"_npmUser":{"name":"angelabenavente","email":"ang.ben.dev@gmail.com"},"directories":{},"maintainers":[{"name":"angelabenavente","email":"ang.ben.dev@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/source-mapping_1.0.2_1787683107714_0.5663103474106304"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-23T17:30:36.061Z","modified":"2026-08-25T18:38:28.053Z","1.0.0":"2026-08-23T17:30:36.811Z","1.0.1":"2026-08-23T18:11:08.946Z","1.0.2":"2026-08-25T18:38:27.878Z"},"bugs":{"url":"https://github.com/angelabenavente/a11yst/issues"},"license":"MPL-2.0","homepage":"https://www.a11yst.dev","repository":{"type":"git","url":"git+https://github.com/angelabenavente/a11yst.git"},"description":"Pure source mapping domain model for a11yst findings","maintainers":[{"name":"angelabenavente","email":"ang.ben.dev@gmail.com"}],"readme":"# @a11yst/source-mapping [![NPM version](https://img.shields.io/npm/v/@a11yst/source-mapping.svg?style=flat)](https://www.npmjs.com/package/@a11yst/source-mapping) [![License: MPL-2.0](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](LICENSE) [![NPM total downloads](https://img.shields.io/npm/dt/@a11yst/source-mapping.svg?style=flat)](https://www.npmjs.com/package/@a11yst/source-mapping)\n\nPure domain model for mapping browser findings to repository-relative source\nlocations with explicit confidence, provenance, and safety invariants.\n\nPhase **10a** defines contracts and validation only. It does **not** inspect the\nfilesystem, parse frameworks, resolve source maps, rank heuristics, or integrate\nwith reports.\n\n## Concepts\n\n### Source location\n\nA canonical `SourceLocation` contains:\n\n- `uri` — repository-relative path using `/` separators\n- `region` — positive 1-based line/column positions\n- optional metadata: `symbol`, `component`, `language`\n\nLocations never include absolute paths, file URLs, HTTP URLs, snippets, or file\nhashes.\n\n### Candidate\n\nA `SourceMappingCandidate` pairs a validated location with:\n\n- `confidence` — `exact`, `high`, `medium`, or `low`\n- `provenance` — where the candidate came from\n- `signals` — short structured evidence items\n\nCandidates never embed full findings, DOM trees, screenshots, or timestamps.\n\n### Result\n\n`SourceMappingResult` describes the outcome for one finding:\n\n| Status | Meaning |\n| --- | --- |\n| `mapped` | Exactly one defensible candidate is selected |\n| `ambiguous` | Multiple distinct candidates; no invented winner |\n| `unmapped` | No usable candidate (not an operational error) |\n| `invalid` | Input metadata was unsafe or structurally invalid |\n\n## Confidence\n\n- **exact** — direct, verifiable relationship (validated existing location, validated source map, compiler metadata)\n- **high** — several independent signals converge on one location\n- **medium** — reasonable but not unique match\n- **low** — useful investigative hint with substantial ambiguity\n\nHeuristic provenance (`selector-match`, `text-match`, `component-match`,\n`user-provided`) cannot produce `exact` confidence.\n\n## Provenance\n\nStable provenance values describe candidate origin:\n\n| Value | Phase 10a |\n| --- | --- |\n| `existing-source-location` | Implemented (adapter) |\n| `runtime-metadata` | Contract only |\n| `source-map` | Contract only |\n| `framework-compiler` | Contract only |\n| `static-source-index` | Contract only |\n| `selector-match` | Contract only |\n| `text-match` | Contract only |\n| `component-match` | Contract only |\n| `user-provided` | Contract only |\n\nProvenance does not replace confidence.\n\n## Signals\n\nSignals are small serializable records (`kind`, `matched`, optional `value`).\nValues are length-limited, control characters stripped, and sensitive literals\nredacted. Signals do not compute numeric scores and are not natural-language\nexplanations.\n\n## Safety rules\n\nSource locations are accepted only when paths are repository-relative and regions\nare valid. The package rejects:\n\n- Unix/Windows absolute paths and UNC paths\n- `file://`, `http://`, and `https://` URIs\n- `..` traversal escaping the repository root\n- null bytes and control characters\n- home-like absolute prefixes in paths and signal values\n\n**No location is invented** when evidence is insufficient. Reports should keep\nusing route/flow logical locations until mapping is justified.\n\n## Existing `sourceLocation` compatibility\n\n`createMappingFromExistingSourceLocation()` formalizes the flat location shape\nalready used by SARIF and GitHub annotations:\n\n- absent → `unmapped`\n- valid relative location → `mapped` with `exact` / `existing-source-location`\n- unsafe/invalid input → `invalid`\n\nFile existence is **not** checked in 10a.\n\n## Public API (10a)\n\n- `normalizeSourceUri`, `validateSourceRegion`, `validateSourceLocation`\n- `createSourceMappingCandidate`, `createSourceMappingResult`\n- `createMappingFromExistingSourceLocation`\n- signal sanitization and deterministic ordering helpers\n- `serializeSourceMappingResult`\n\n## Out of scope for 10a\n\n- Repository indexing and file search (10b)\n- HTML/JSX/Vue/Angular parsing (10c–10g)\n- Advanced ranking and recommendation engines (10h–10i)\n- SARIF/HTML/Markdown/annotation integration (10j)\n\nSource mapping improves traceability but **does not guarantee** that a future\nrecommendation will be correct.\n","readmeFilename":"README.md"}