@variance-authority/core 0.1.0

package/dist/attribute/source-map.js

@@ -0,0 +1,264 @@
+/**
+ * A generated position, mapped back to the source somebody wrote.
+ *
+ * Every build in ordinary use already ships this. A dev server emits it inline
+ * on each module it transforms; a production bundler writes it beside the
+ * bundle. It is the same argument the rest of provenance keeps making — the
+ * information is not missing from the build, only from the hop that would carry
+ * it — and it is what makes a browser stack frame usable: a frame says
+ * `/src/probe.jsx:23:26` about a file the browser was served, and the file the
+ * reviewer has to open is line 21 of the file they wrote.
+ *
+ * **Written out rather than installed.** `core` has no third-party dependencies
+ * (ADR-0013) and a source map is a documented format with one interesting part,
+ * so decoding it here costs less than the rule it would break. What is
+ * deliberately *not* implemented is left as a refusal rather than a wrong
+ * answer: an index map's sections are resolved, and a map whose version this
+ * does not recognise returns nothing at all.
+ */
+/** Base64 VLQ, the one encoding a source map has that JSON does not. */
+const DIGITS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const VALUE_OF = new Int8Array(128).fill(-1);
+for (let i = 0; i < DIGITS.length; i += 1)
+    VALUE_OF[DIGITS.charCodeAt(i)] = i;
+function decodeMappings(mappings, sourceCount) {
+    const lines = [];
+    let sourceIndex = 0;
+    let originalLine = 0;
+    let originalColumn = 0;
+    for (const encoded of mappings.split(';')) {
+        const segments = [];
+        let generatedColumn = 0;
+        if (encoded !== '') {
+            for (const field of encoded.split(',')) {
+                const values = decodeVlq(field);
+                // A one-field segment says "generated code with no origin" — a bundler's
+                // own prelude, a helper it injected. It advances the column and maps
+                // nowhere, so recording it would let a lookup land on it and answer with
+                // whatever the previous segment's source was.
+                if (values.length < 4) {
+                    if (values.length > 0)
+                        generatedColumn += values[0];
+                    continue;
+                }
+                generatedColumn += values[0];
+                sourceIndex += values[1];
+                originalLine += values[2];
+                originalColumn += values[3];
+                if (sourceIndex >= 0 && sourceIndex < sourceCount) {
+                    segments.push({ generatedColumn, sourceIndex, originalLine, originalColumn });
+                }
+            }
+        }
+        // The format does not promise ordered columns, and the lookup is a binary
+        // search that assumes them. Sorting once here is cheaper than a scan per
+        // frame, and every map met so far was already in order.
+        segments.sort((a, b) => a.generatedColumn - b.generatedColumn);
+        lines.push(segments);
+    }
+    return lines;
+}
+function decodeVlq(field) {
+    const values = [];
+    let value = 0;
+    let shift = 0;
+    for (let i = 0; i < field.length; i += 1) {
+        const code = field.charCodeAt(i);
+        const digit = code < 128 ? VALUE_OF[code] : -1;
+        if (digit < 0)
+            return values; // Not a source map. Stop rather than invent.
+        const more = (digit & 32) !== 0;
+        value += (digit & 31) << shift;
+        if (more) {
+            shift += 5;
+            continue;
+        }
+        const negative = (value & 1) === 1;
+        const magnitude = value >>> 1;
+        values.push(negative ? (magnitude === 0 ? -0x80000000 : -magnitude) : magnitude);
+        value = 0;
+        shift = 0;
+    }
+    return values;
+}
+function resolveSources(raw) {
+    if (!Array.isArray(raw.sources))
+        return null;
+    const root = typeof raw.sourceRoot === 'string' ? raw.sourceRoot.replace(/\/+$/, '') : '';
+    return raw.sources.map((source) => {
+        if (typeof source !== 'string')
+            return '';
+        if (root === '' || source === '' || /^[a-z][a-z0-9+.-]*:/i.test(source))
+            return source;
+        return source.startsWith('/') ? `${root}${source}` : `${root}/${source}`;
+    });
+}
+/**
+ * Parse a source map, or decide this is not one.
+ *
+ * Returns a list because an index map is several maps at several offsets, and
+ * flattening them here means the lookup does not have to know which kind it was
+ * handed. An ordinary map is a list of one.
+ *
+ * Every refusal is silent and total. The caller is resolving a stack frame for a
+ * report, and a map that does not parse means one node reports no location —
+ * which is a state the whole provenance path already treats as normal.
+ */
+export function parseSourceMap(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    if (raw === null || typeof raw !== 'object')
+        return [];
+    if (raw.version !== undefined && raw.version !== 3)
+        return [];
+    if (Array.isArray(raw.sections)) {
+        return raw.sections.flatMap((section) => {
+            if (section === null || typeof section !== 'object')
+                return [];
+            const { offset, map } = section;
+            if (offset === null || typeof offset !== 'object')
+                return [];
+            if (map === null || typeof map !== 'object')
+                return [];
+            const { line, column } = offset;
+            if (typeof line !== 'number' || typeof column !== 'number')
+                return [];
+            return parseSourceMap(JSON.stringify(map)).map((parsed) => ({
+                ...parsed,
+                offset: { line, column },
+            }));
+        });
+    }
+    const sources = resolveSources(raw);
+    if (sources === null || typeof raw.mappings !== 'string')
+        return [];
+    return [
+        {
+            sources,
+            lines: decodeMappings(raw.mappings, sources.length),
+            offset: { line: 0, column: 0 },
+        },
+    ];
+}
+/**
+ * The source position a generated position came from, or nothing.
+ *
+ * `line` and `column` are 1-based on the way in and on the way out, because both
+ * ends of this are 1-based: a browser's stack frame counts from one, and so does
+ * every editor a reviewer opens the answer in. The wire format counts from zero
+ * and that stays inside this file.
+ *
+ * A position between two mappings resolves to the earlier one — which is the
+ * standard reading, and the right one: generated code that maps nowhere belongs
+ * to the last construct that did.
+ */
+export function originalPositionFor(maps, line, column) {
+    for (const map of sectionsFor(maps, line, column)) {
+        // A section's own coordinates are relative to where it was placed. Only the
+        // first generated line of a section is column-shifted; every line after it
+        // starts at zero, the same way a paragraph only indents its first line.
+        const localLine = line - map.offset.line;
+        const localColumn = localLine === 1 ? column - map.offset.column : column;
+        const segments = map.lines[localLine - 1];
+        if (segments === undefined || segments.length === 0)
+            continue;
+        const found = segmentAt(segments, localColumn - 1);
+        if (found === undefined)
+            continue;
+        const source = map.sources[found.sourceIndex];
+        if (source === undefined || source === '')
+            continue;
+        return { source, line: found.originalLine + 1, column: found.originalColumn + 1 };
+    }
+    return null;
+}
+/**
+ * The sections a position could be in, innermost placement first.
+ *
+ * An ordinary map is one section at the origin and this is the identity. For an
+ * index map the sections partition the generated file, so the answer is the last
+ * one that starts at or before the position — searched in reverse for exactly
+ * that reason.
+ */
+function sectionsFor(maps, line, column) {
+    if (maps.length <= 1)
+        return maps;
+    const candidates = maps.filter((map) => map.offset.line < line || (map.offset.line === line - 1 && map.offset.column < column));
+    return candidates.length === 0 ? [] : [candidates[candidates.length - 1]];
+}
+function segmentAt(segments, column) {
+    let low = 0;
+    let high = segments.length - 1;
+    let found;
+    while (low <= high) {
+        const middle = (low + high) >> 1;
+        const segment = segments[middle];
+        if (segment.generatedColumn <= column) {
+            found = segment;
+            low = middle + 1;
+        }
+        else {
+            high = middle - 1;
+        }
+    }
+    // Before the first mapping on the line. The line is still attributable — the
+    // first construct on it is what generated code at column 0 belongs to.
+    return found ?? segments[0];
+}
+/**
+ * The map a served module points at, as a URL or as the map itself.
+ *
+ * Two forms, and a build uses whichever suits it: a dev server inlines the map
+ * as a `data:` URI because it is transforming one module in memory, and a
+ * production bundler writes a sibling `.map` because inlining megabytes into
+ * every response is not free.
+ *
+ * Read from the end of the file. The comment is a trailing annotation by
+ * construction, and a bundle that merely *mentions* the token — this file does,
+ * a few lines up — would otherwise hand back its own prose.
+ */
+export function sourceMappingUrlOf(code) {
+    const found = [...code.matchAll(/^[/*]{2,}[#@]\s*sourceMappingURL=(\S+)\s*(?:\*\/)?$/gm)];
+    const last = found[found.length - 1];
+    return last === undefined ? null : last[1];
+}
+/**
+ * The JSON of a `data:` source-map URL, when that is what it is.
+ *
+ * Base64 is what every bundler writes; the spec permits percent-encoding, and
+ * `decodeURIComponent` is what reads it. Both are handled because handling the
+ * second costs one branch.
+ */
+export function inlineSourceMapOf(url) {
+    const match = /^data:application\/json[^,]*,(.*)$/s.exec(url);
+    if (match === null)
+        return null;
+    const payload = match[1];
+    if (!/;base64/i.test(url)) {
+        try {
+            return decodeURIComponent(payload);
+        }
+        catch {
+            return null;
+        }
+    }
+    try {
+        // `atob` in a browser, `Buffer` in Node — this package may not assume either,
+        // so it uses whichever the host actually has.
+        const decode = globalThis.atob;
+        if (decode !== undefined)
+            return decode(payload);
+        const buffer = globalThis
+            .Buffer;
+        return buffer === undefined ? null : buffer.from(payload, 'base64').toString('utf8');
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=source-map.js.map

package/dist/attribute/source-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-map.js","sourceRoot":"","sources":["../../src/attribute/source-map.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A generated position, mapped back to the source somebody wrote.\n *\n * Every build in ordinary use already ships this. A dev server emits it inline\n * on each module it transforms; a production bundler writes it beside the\n * bundle. It is the same argument the rest of provenance keeps making — the\n * information is not missing from the build, only from the hop that would carry\n * it — and it is what makes a browser stack frame usable: a frame says\n * `/src/probe.jsx:23:26` about a file the browser was served, and the file the\n * reviewer has to open is line 21 of the file they wrote.\n *\n * **Written out rather than installed.** `core` has no third-party dependencies\n * (ADR-0013) and a source map is a documented format with one interesting part,\n * so decoding it here costs less than the rule it would break. What is\n * deliberately *not* implemented is left as a refusal rather than a wrong\n * answer: an index map's sections are resolved, and a map whose version this\n * does not recognise returns nothing at all.\n */\n\n/** Base64 VLQ, the one encoding a source map has that JSON does not. */\nconst DIGITS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';\n\nconst VALUE_OF = new Int8Array(128).fill(-1);\nfor (let i = 0; i < DIGITS.length; i += 1) VALUE_OF[DIGITS.charCodeAt(i)] = i;\n\n/**\n * One decoded mapping: where a generated column came from.\n *\n * Column-only because the generated *line* is the index of the array this sits\n * in — that is how the `;`-separated wire format is shaped, and keeping it that\n * way is what makes the lookup a binary search rather than a scan.\n */\ninterface Segment {\n  readonly generatedColumn: number;\n  readonly sourceIndex: number;\n  readonly originalLine: number;\n  readonly originalColumn: number;\n}\n\nexport interface SourceMap {\n  /** Source paths as the map states them, already resolved against `sourceRoot`. */\n  readonly sources: readonly string[];\n  /** Segments per generated line, `[0]` being generated line 1. */\n  readonly lines: readonly (readonly Segment[])[];\n  /** Non-zero only for a section of an index map. */\n  readonly offset: { readonly line: number; readonly column: number };\n}\n\nexport interface OriginalPosition {\n  /** The source path, exactly as the map spells it. */\n  readonly source: string;\n  /** 1-based, matching how a stack frame and an editor both count. */\n  readonly line: number;\n  /** 1-based, for the same reason. The wire format is 0-based; this is not. */\n  readonly column: number;\n}\n\n/**\n * The shape a map arrives in, before anything has been checked about it.\n *\n * Deliberately loose. This is parsed from whatever a dev server served, which\n * on a bad day is an HTML error page, and every field is therefore treated as\n * absent until it proves otherwise.\n */\ninterface RawMap {\n  readonly version?: unknown;\n  readonly sources?: unknown;\n  readonly sourceRoot?: unknown;\n  readonly mappings?: unknown;\n  readonly sections?: unknown;\n}\n\nfunction decodeMappings(mappings: string, sourceCount: number): Segment[][] {\n  const lines: Segment[][] = [];\n\n  let sourceIndex = 0;\n  let originalLine = 0;\n  let originalColumn = 0;\n\n  for (const encoded of mappings.split(';')) {\n    const segments: Segment[] = [];\n    let generatedColumn = 0;\n\n    if (encoded !== '') {\n      for (const field of encoded.split(',')) {\n        const values = decodeVlq(field);\n\n        // A one-field segment says \"generated code with no origin\" — a bundler's\n        // own prelude, a helper it injected. It advances the column and maps\n        // nowhere, so recording it would let a lookup land on it and answer with\n        // whatever the previous segment's source was.\n        if (values.length < 4) {\n          if (values.length > 0) generatedColumn += values[0]!;\n          continue;\n        }\n\n        generatedColumn += values[0]!;\n        sourceIndex += values[1]!;\n        originalLine += values[2]!;\n        originalColumn += values[3]!;\n\n        if (sourceIndex >= 0 && sourceIndex < sourceCount) {\n          segments.push({ generatedColumn, sourceIndex, originalLine, originalColumn });\n        }\n      }\n    }\n\n    // The format does not promise ordered columns, and the lookup is a binary\n    // search that assumes them. Sorting once here is cheaper than a scan per\n    // frame, and every map met so far was already in order.\n    segments.sort((a, b) => a.generatedColumn - b.generatedColumn);\n    lines.push(segments);\n  }\n\n  return lines;\n}\n\nfunction decodeVlq(field: string): number[] {\n  const values: number[] = [];\n\n  let value = 0;\n  let shift = 0;\n\n  for (let i = 0; i < field.length; i += 1) {\n    const code = field.charCodeAt(i);\n    const digit = code < 128 ? VALUE_OF[code]! : -1;\n    if (digit < 0) return values; // Not a source map. Stop rather than invent.\n\n    const more = (digit & 32) !== 0;\n    value += (digit & 31) << shift;\n\n    if (more) {\n      shift += 5;\n      continue;\n    }\n\n    const negative = (value & 1) === 1;\n    const magnitude = value >>> 1;\n    values.push(negative ? (magnitude === 0 ? -0x80000000 : -magnitude) : magnitude);\n\n    value = 0;\n    shift = 0;\n  }\n\n  return values;\n}\n\nfunction resolveSources(raw: RawMap): string[] | null {\n  if (!Array.isArray(raw.sources)) return null;\n\n  const root = typeof raw.sourceRoot === 'string' ? raw.sourceRoot.replace(/\\/+$/, '') : '';\n\n  return raw.sources.map((source) => {\n    if (typeof source !== 'string') return '';\n    if (root === '' || source === '' || /^[a-z][a-z0-9+.-]*:/i.test(source)) return source;\n    return source.startsWith('/') ? `${root}${source}` : `${root}/${source}`;\n  });\n}\n\n/**\n * Parse a source map, or decide this is not one.\n *\n * Returns a list because an index map is several maps at several offsets, and\n * flattening them here means the lookup does not have to know which kind it was\n * handed. An ordinary map is a list of one.\n *\n * Every refusal is silent and total. The caller is resolving a stack frame for a\n * report, and a map that does not parse means one node reports no location —\n * which is a state the whole provenance path already treats as normal.\n */\nexport function parseSourceMap(text: string): SourceMap[] {\n  let raw: RawMap;\n  try {\n    raw = JSON.parse(text) as RawMap;\n  } catch {\n    return [];\n  }\n\n  if (raw === null || typeof raw !== 'object') return [];\n  if (raw.version !== undefined && raw.version !== 3) return [];\n\n  if (Array.isArray(raw.sections)) {\n    return raw.sections.flatMap((section) => {\n      if (section === null || typeof section !== 'object') return [];\n\n      const { offset, map } = section as { offset?: unknown; map?: unknown };\n      if (offset === null || typeof offset !== 'object') return [];\n      if (map === null || typeof map !== 'object') return [];\n\n      const { line, column } = offset as { line?: unknown; column?: unknown };\n      if (typeof line !== 'number' || typeof column !== 'number') return [];\n\n      return parseSourceMap(JSON.stringify(map)).map((parsed) => ({\n        ...parsed,\n        offset: { line, column },\n      }));\n    });\n  }\n\n  const sources = resolveSources(raw);\n  if (sources === null || typeof raw.mappings !== 'string') return [];\n\n  return [\n    {\n      sources,\n      lines: decodeMappings(raw.mappings, sources.length),\n      offset: { line: 0, column: 0 },\n    },\n  ];\n}\n\n/**\n * The source position a generated position came from, or nothing.\n *\n * `line` and `column` are 1-based on the way in and on the way out, because both\n * ends of this are 1-based: a browser's stack frame counts from one, and so does\n * every editor a reviewer opens the answer in. The wire format counts from zero\n * and that stays inside this file.\n *\n * A position between two mappings resolves to the earlier one — which is the\n * standard reading, and the right one: generated code that maps nowhere belongs\n * to the last construct that did.\n */\nexport function originalPositionFor(\n  maps: readonly SourceMap[],\n  line: number,\n  column: number,\n): OriginalPosition | null {\n  for (const map of sectionsFor(maps, line, column)) {\n    // A section's own coordinates are relative to where it was placed. Only the\n    // first generated line of a section is column-shifted; every line after it\n    // starts at zero, the same way a paragraph only indents its first line.\n    const localLine = line - map.offset.line;\n    const localColumn = localLine === 1 ? column - map.offset.column : column;\n\n    const segments = map.lines[localLine - 1];\n    if (segments === undefined || segments.length === 0) continue;\n\n    const found = segmentAt(segments, localColumn - 1);\n    if (found === undefined) continue;\n\n    const source = map.sources[found.sourceIndex];\n    if (source === undefined || source === '') continue;\n\n    return { source, line: found.originalLine + 1, column: found.originalColumn + 1 };\n  }\n\n  return null;\n}\n\n/**\n * The sections a position could be in, innermost placement first.\n *\n * An ordinary map is one section at the origin and this is the identity. For an\n * index map the sections partition the generated file, so the answer is the last\n * one that starts at or before the position — searched in reverse for exactly\n * that reason.\n */\nfunction sectionsFor(\n  maps: readonly SourceMap[],\n  line: number,\n  column: number,\n): readonly SourceMap[] {\n  if (maps.length <= 1) return maps;\n\n  const candidates = maps.filter(\n    (map) =>\n      map.offset.line < line || (map.offset.line === line - 1 && map.offset.column < column),\n  );\n\n  return candidates.length === 0 ? [] : [candidates[candidates.length - 1]!];\n}\n\nfunction segmentAt(segments: readonly Segment[], column: number): Segment | undefined {\n  let low = 0;\n  let high = segments.length - 1;\n  let found: Segment | undefined;\n\n  while (low <= high) {\n    const middle = (low + high) >> 1;\n    const segment = segments[middle]!;\n\n    if (segment.generatedColumn <= column) {\n      found = segment;\n      low = middle + 1;\n    } else {\n      high = middle - 1;\n    }\n  }\n\n  // Before the first mapping on the line. The line is still attributable — the\n  // first construct on it is what generated code at column 0 belongs to.\n  return found ?? segments[0];\n}\n\n/**\n * The map a served module points at, as a URL or as the map itself.\n *\n * Two forms, and a build uses whichever suits it: a dev server inlines the map\n * as a `data:` URI because it is transforming one module in memory, and a\n * production bundler writes a sibling `.map` because inlining megabytes into\n * every response is not free.\n *\n * Read from the end of the file. The comment is a trailing annotation by\n * construction, and a bundle that merely *mentions* the token — this file does,\n * a few lines up — would otherwise hand back its own prose.\n */\nexport function sourceMappingUrlOf(code: string): string | null {\n  const found = [...code.matchAll(/^[/*]{2,}[#@]\\s*sourceMappingURL=(\\S+)\\s*(?:\\*\\/)?$/gm)];\n  const last = found[found.length - 1];\n  return last === undefined ? null : last[1]!;\n}\n\n/**\n * The JSON of a `data:` source-map URL, when that is what it is.\n *\n * Base64 is what every bundler writes; the spec permits percent-encoding, and\n * `decodeURIComponent` is what reads it. Both are handled because handling the\n * second costs one branch.\n */\nexport function inlineSourceMapOf(url: string): string | null {\n  const match = /^data:application\\/json[^,]*,(.*)$/s.exec(url);\n  if (match === null) return null;\n\n  const payload = match[1]!;\n  if (!/;base64/i.test(url)) {\n    try {\n      return decodeURIComponent(payload);\n    } catch {\n      return null;\n    }\n  }\n\n  try {\n    // `atob` in a browser, `Buffer` in Node — this package may not assume either,\n    // so it uses whichever the host actually has.\n    const decode = (globalThis as { atob?: (input: string) => string }).atob;\n    if (decode !== undefined) return decode(payload);\n\n    const buffer = (globalThis as { Buffer?: { from(s: string, e: string): { toString(e: string): string } } })\n      .Buffer;\n    return buffer === undefined ? null : buffer.from(payload, 'base64').toString('utf8');\n  } catch {\n    return null;\n  }\n}\n"]}

package/dist/attribute/source.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Connecting a change to a file.
+ *
+ * A report that says `Button` is one step short of useful. An agent asked to fix
+ * it still has to find `Button`, and a reviewer still has to guess whether the
+ * `Button` in question is the design-system one or the local one in checkout.
+ * The last hop — **which file** — is what turns a finding into an edit.
+ *
+ * There are two mechanisms, and this file is the second one.
+ *
+ * The first is exact. Spec §6.1 assumes the build tells us: every JSX transform
+ * already computes each element's file, line and column, and
+ * `@variance-authority/jsx-source` is the `jsxImportSource` setting that keeps
+ * that location as far as the fiber — React 19 drops it otherwise, on every path.
+ * When it is on, a finding names the element's own line and this index is not
+ * consulted.
+ *
+ * The second is this one, and it is what a repository that has changed nothing
+ * gets. Attribution names *components*, so a **component → file** index answers
+ * the question attribution asks. It is built by reading source rather than by
+ * configuring a build, and it answers with where a component is *declared* —
+ * coarser than a call site, and enough to open the right file.
+ *
+ * The index is plain data. `core` performs no I/O (ADR-0006), so building one is
+ * a caller's job; resolving against one is here.
+ */
+export interface SourceRef {
+    /** Repository-relative, so a report is portable between machines and CI. */
+    readonly file: string;
+    readonly line: number;
+    /** How the declaration was recognised. Carried so a bad match is debuggable. */
+    readonly via: 'function' | 'const' | 'class' | 'declared';
+}
+/**
+ * Component name → where it is declared.
+ *
+ * A name may map to several files. That is not an error to be resolved by
+ * picking one: two components genuinely can share a name, and silently choosing
+ * the first would send an agent to edit the wrong file with full confidence.
+ * Ambiguity is reported (ADR-0003's rule for overlapping projections, applied to
+ * source).
+ */
+export type SourceIndex = Readonly<Record<string, readonly SourceRef[]>>;
+export interface Resolution {
+    readonly name: string;
+    readonly refs: readonly SourceRef[];
+    /** `true` when more than one file declares this name. */
+    readonly ambiguous: boolean;
+}
+export declare function resolveSource(name: string, index: SourceIndex): Resolution | null;
+/**
+ * `file:line`, or a disambiguating list when a name is declared more than once.
+ *
+ * Formatted as `path:line` because that is the form an editor, a terminal, and
+ * every agent harness already know how to open.
+ */
+export declare function formatSource(resolution: Resolution): string;
+/**
+ * Extract component declarations from one file's source.
+ *
+ * A regex scan, and the limits are worth stating rather than discovering. It
+ * finds exported and local declarations in the three shapes React components are
+ * written in, and it will miss a component produced by a factory, assigned
+ * dynamically, or re-exported under another name. It can also match a function
+ * that merely looks like a component — capitalised, declared at top level — and
+ * name a non-component in a report.
+ *
+ * Both failures are survivable in a way a wrong file path would not be: a miss
+ * degrades the report to the component name, which is what it said before, and a
+ * false positive can only appear if attribution already named that identifier.
+ * Parsing properly is the right answer eventually; it is not worth a parser
+ * dependency to find out whether the link is useful.
+ */
+export declare function indexSource(file: string, contents: string): SourceIndex;
+/** Merge per-file indexes. A name declared in several files keeps every ref. */
+export declare function mergeSourceIndexes(indexes: readonly SourceIndex[]): SourceIndex;
+//# sourceMappingURL=source.d.ts.map

package/dist/attribute/source.js

@@ -0,0 +1,95 @@
+/**
+ * Connecting a change to a file.
+ *
+ * A report that says `Button` is one step short of useful. An agent asked to fix
+ * it still has to find `Button`, and a reviewer still has to guess whether the
+ * `Button` in question is the design-system one or the local one in checkout.
+ * The last hop — **which file** — is what turns a finding into an edit.
+ *
+ * There are two mechanisms, and this file is the second one.
+ *
+ * The first is exact. Spec §6.1 assumes the build tells us: every JSX transform
+ * already computes each element's file, line and column, and
+ * `@variance-authority/jsx-source` is the `jsxImportSource` setting that keeps
+ * that location as far as the fiber — React 19 drops it otherwise, on every path.
+ * When it is on, a finding names the element's own line and this index is not
+ * consulted.
+ *
+ * The second is this one, and it is what a repository that has changed nothing
+ * gets. Attribution names *components*, so a **component → file** index answers
+ * the question attribution asks. It is built by reading source rather than by
+ * configuring a build, and it answers with where a component is *declared* —
+ * coarser than a call site, and enough to open the right file.
+ *
+ * The index is plain data. `core` performs no I/O (ADR-0006), so building one is
+ * a caller's job; resolving against one is here.
+ */
+export function resolveSource(name, index) {
+    const refs = index[name];
+    if (refs === undefined || refs.length === 0)
+        return null;
+    return { name, refs, ambiguous: refs.length > 1 };
+}
+/**
+ * `file:line`, or a disambiguating list when a name is declared more than once.
+ *
+ * Formatted as `path:line` because that is the form an editor, a terminal, and
+ * every agent harness already know how to open.
+ */
+export function formatSource(resolution) {
+    const [first] = resolution.refs;
+    if (first === undefined)
+        return resolution.name;
+    const primary = `${first.file}:${first.line}`;
+    if (!resolution.ambiguous)
+        return primary;
+    const others = resolution.refs.slice(1).map((ref) => `${ref.file}:${ref.line}`);
+    return `${primary} (ambiguous — also ${others.join(', ')})`;
+}
+/**
+ * Extract component declarations from one file's source.
+ *
+ * A regex scan, and the limits are worth stating rather than discovering. It
+ * finds exported and local declarations in the three shapes React components are
+ * written in, and it will miss a component produced by a factory, assigned
+ * dynamically, or re-exported under another name. It can also match a function
+ * that merely looks like a component — capitalised, declared at top level — and
+ * name a non-component in a report.
+ *
+ * Both failures are survivable in a way a wrong file path would not be: a miss
+ * degrades the report to the component name, which is what it said before, and a
+ * false positive can only appear if attribution already named that identifier.
+ * Parsing properly is the right answer eventually; it is not worth a parser
+ * dependency to find out whether the link is useful.
+ */
+export function indexSource(file, contents) {
+    const found = {};
+    const lines = contents.split('\n');
+    const patterns = [
+        { re: /^\s*(?:export\s+)?(?:default\s+)?function\s+([A-Z][A-Za-z0-9_]*)/, via: 'function' },
+        { re: /^\s*(?:export\s+)?(?:const|let)\s+([A-Z][A-Za-z0-9_]*)\s*[:=]/, via: 'const' },
+        { re: /^\s*(?:export\s+)?(?:default\s+)?class\s+([A-Z][A-Za-z0-9_]*)/, via: 'class' },
+    ];
+    for (const [index, line] of lines.entries()) {
+        for (const { re, via } of patterns) {
+            const match = re.exec(line);
+            if (!match)
+                continue;
+            const name = match[1];
+            (found[name] ??= []).push({ file, line: index + 1, via });
+            break;
+        }
+    }
+    return found;
+}
+/** Merge per-file indexes. A name declared in several files keeps every ref. */
+export function mergeSourceIndexes(indexes) {
+    const merged = {};
+    for (const index of indexes) {
+        for (const [name, refs] of Object.entries(index)) {
+            (merged[name] ??= []).push(...refs);
+        }
+    }
+    return merged;
+}
+//# sourceMappingURL=source.js.map

package/dist/attribute/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../../src/attribute/source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AA4BH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,KAAkB;IAC5D,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;IACzB,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEzD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,UAAsB;IACjD,MAAM,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC;IAChC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC,IAAI,CAAC;IAEhD,MAAM,OAAO,GAAG,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;IAC9C,IAAI,CAAC,UAAU,CAAC,SAAS;QAAE,OAAO,OAAO,CAAC;IAE1C,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAChF,OAAO,GAAG,OAAO,sBAAsB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,QAAgB;IACxD,MAAM,KAAK,GAAgC,EAAE,CAAC;IAC9C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAEnC,MAAM,QAAQ,GAAuE;QACnF,EAAE,EAAE,EAAE,kEAAkE,EAAE,GAAG,EAAE,UAAU,EAAE;QAC3F,EAAE,EAAE,EAAE,+DAA+D,EAAE,GAAG,EAAE,OAAO,EAAE;QACrF,EAAE,EAAE,EAAE,+DAA+D,EAAE,GAAG,EAAE,OAAO,EAAE;KACtF,CAAC;IAEF,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC5C,KAAK,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,QAAQ,EAAE,CAAC;YACnC,MAAM,KAAK,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC5B,IAAI,CAAC,KAAK;gBAAE,SAAS;YAErB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;YACvB,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;YAC1D,MAAM;QACR,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,kBAAkB,CAAC,OAA+B;IAChE,MAAM,MAAM,GAAgC,EAAE,CAAC;IAE/C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACjD,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["/**\n * Connecting a change to a file.\n *\n * A report that says `Button` is one step short of useful. An agent asked to fix\n * it still has to find `Button`, and a reviewer still has to guess whether the\n * `Button` in question is the design-system one or the local one in checkout.\n * The last hop — **which file** — is what turns a finding into an edit.\n *\n * There are two mechanisms, and this file is the second one.\n *\n * The first is exact. Spec §6.1 assumes the build tells us: every JSX transform\n * already computes each element's file, line and column, and\n * `@variance-authority/jsx-source` is the `jsxImportSource` setting that keeps\n * that location as far as the fiber — React 19 drops it otherwise, on every path.\n * When it is on, a finding names the element's own line and this index is not\n * consulted.\n *\n * The second is this one, and it is what a repository that has changed nothing\n * gets. Attribution names *components*, so a **component → file** index answers\n * the question attribution asks. It is built by reading source rather than by\n * configuring a build, and it answers with where a component is *declared* —\n * coarser than a call site, and enough to open the right file.\n *\n * The index is plain data. `core` performs no I/O (ADR-0006), so building one is\n * a caller's job; resolving against one is here.\n */\n\nexport interface SourceRef {\n  /** Repository-relative, so a report is portable between machines and CI. */\n  readonly file: string;\n  readonly line: number;\n  /** How the declaration was recognised. Carried so a bad match is debuggable. */\n  readonly via: 'function' | 'const' | 'class' | 'declared';\n}\n\n/**\n * Component name → where it is declared.\n *\n * A name may map to several files. That is not an error to be resolved by\n * picking one: two components genuinely can share a name, and silently choosing\n * the first would send an agent to edit the wrong file with full confidence.\n * Ambiguity is reported (ADR-0003's rule for overlapping projections, applied to\n * source).\n */\nexport type SourceIndex = Readonly<Record<string, readonly SourceRef[]>>;\n\nexport interface Resolution {\n  readonly name: string;\n  readonly refs: readonly SourceRef[];\n  /** `true` when more than one file declares this name. */\n  readonly ambiguous: boolean;\n}\n\nexport function resolveSource(name: string, index: SourceIndex): Resolution | null {\n  const refs = index[name];\n  if (refs === undefined || refs.length === 0) return null;\n\n  return { name, refs, ambiguous: refs.length > 1 };\n}\n\n/**\n * `file:line`, or a disambiguating list when a name is declared more than once.\n *\n * Formatted as `path:line` because that is the form an editor, a terminal, and\n * every agent harness already know how to open.\n */\nexport function formatSource(resolution: Resolution): string {\n  const [first] = resolution.refs;\n  if (first === undefined) return resolution.name;\n\n  const primary = `${first.file}:${first.line}`;\n  if (!resolution.ambiguous) return primary;\n\n  const others = resolution.refs.slice(1).map((ref) => `${ref.file}:${ref.line}`);\n  return `${primary} (ambiguous — also ${others.join(', ')})`;\n}\n\n/**\n * Extract component declarations from one file's source.\n *\n * A regex scan, and the limits are worth stating rather than discovering. It\n * finds exported and local declarations in the three shapes React components are\n * written in, and it will miss a component produced by a factory, assigned\n * dynamically, or re-exported under another name. It can also match a function\n * that merely looks like a component — capitalised, declared at top level — and\n * name a non-component in a report.\n *\n * Both failures are survivable in a way a wrong file path would not be: a miss\n * degrades the report to the component name, which is what it said before, and a\n * false positive can only appear if attribution already named that identifier.\n * Parsing properly is the right answer eventually; it is not worth a parser\n * dependency to find out whether the link is useful.\n */\nexport function indexSource(file: string, contents: string): SourceIndex {\n  const found: Record<string, SourceRef[]> = {};\n  const lines = contents.split('\\n');\n\n  const patterns: readonly { readonly re: RegExp; readonly via: SourceRef['via'] }[] = [\n    { re: /^\\s*(?:export\\s+)?(?:default\\s+)?function\\s+([A-Z][A-Za-z0-9_]*)/, via: 'function' },\n    { re: /^\\s*(?:export\\s+)?(?:const|let)\\s+([A-Z][A-Za-z0-9_]*)\\s*[:=]/, via: 'const' },\n    { re: /^\\s*(?:export\\s+)?(?:default\\s+)?class\\s+([A-Z][A-Za-z0-9_]*)/, via: 'class' },\n  ];\n\n  for (const [index, line] of lines.entries()) {\n    for (const { re, via } of patterns) {\n      const match = re.exec(line);\n      if (!match) continue;\n\n      const name = match[1]!;\n      (found[name] ??= []).push({ file, line: index + 1, via });\n      break;\n    }\n  }\n\n  return found;\n}\n\n/** Merge per-file indexes. A name declared in several files keeps every ref. */\nexport function mergeSourceIndexes(indexes: readonly SourceIndex[]): SourceIndex {\n  const merged: Record<string, SourceRef[]> = {};\n\n  for (const index of indexes) {\n    for (const [name, refs] of Object.entries(index)) {\n      (merged[name] ??= []).push(...refs);\n    }\n  }\n\n  return merged;\n}\n"]}

package/dist/attribute/stack.d.ts

@@ -0,0 +1,80 @@
+import type { SourceLocation, StackFrame } from '../format/provenance.js';
+import type { OriginalPosition } from './source-map.js';
+/**
+ * Reading a call site out of a stack, and deciding which frame is the author.
+ *
+ * React 19 constructs an `Error` inside its own `jsx`/`jsxDEV` and keeps it on
+ * every fiber. That error is a complete answer to "which line wrote this
+ * element" that no build has to opt into: the runtime that captured it is frame
+ * zero, and whoever called it is frame one. Nothing is configured, nothing is
+ * installed, and the location is present in any build where React is the
+ * development build — which is every dev server, every Vitest run and every Jest
+ * run, because all three are what "not production" means.
+ *
+ * Two jobs live here and they are separable on purpose. Parsing a stack is a
+ * fact about a JavaScript engine. Choosing *which* frame is the author is a
+ * policy, and it is the part with a defensible rule rather than a heuristic:
+ * the author is the first frame that maps back to code the project wrote. A
+ * custom JSX runtime — Emotion, theme-ui — sits between React and the author and
+ * is skipped not because it is on a list but because it resolves into
+ * `node_modules`.
+ */
+/**
+ * A frame is a wire value, not a local one: the page reads it, the collector
+ * resolves it, and it travels between them on `Provenance`. It is declared where
+ * the rest of provenance is declared, and re-exported here because this is the
+ * group that does something with it.
+ */
+export type { StackFrame };
+/**
+ * The frames of a stack, in order, outermost call last.
+ *
+ * The message line is dropped, and so is any line neither engine format
+ * recognises — a stack is diagnostic output rather than a data format, and a
+ * frame that cannot be read is one fewer candidate rather than a failure.
+ *
+ * `eval` frames are deliberately not unwrapped. V8 writes them as
+ * `at eval (eval at fn (http://host/a.js:1:1), <anonymous>:2:3)`, where two
+ * positions are present and the inner one is meaningless outside the eval.
+ * Taking the outer one would name the line that *called* `eval` as the line that
+ * wrote the element, which is a confident wrong answer.
+ */
+export declare function parseStackFrames(stack: string): StackFrame[];
+/**
+ * Whether a path belongs to a dependency rather than to the project.
+ *
+ * Three spellings of the same fact, because three build tools spell it
+ * differently: the directory itself, Vite's prebundled dependency cache, and the
+ * `webpack-internal:` scheme wrapping the same directory. The test runs against
+ * both the served URL — which saves fetching a map for a megabyte of vendor
+ * code — and against the path the map resolves to, which is what actually
+ * decides it.
+ *
+ * A dependency that *is* the subject cannot be attributed by this, and that is
+ * the intended reading: a project reviewing its own components wants the line in
+ * its own repository, and the line inside `react-dom` that rendered it is never
+ * the answer to "what changed".
+ */
+export declare function isVendorPath(path: string): boolean;
+/**
+ * The location that wrote this element, chosen from its stack.
+ *
+ * The rule is one sentence: **the first frame that resolves to a file the
+ * project wrote.** Frame zero is always React's own runtime, because React is
+ * what constructed the error. Frame one is the author in an ordinary build and
+ * is a custom JSX runtime in a build that has one — and this does not need to
+ * know which, because Emotion resolves into `node_modules` and the component
+ * does not.
+ *
+ * That is the same answer the recorded-symbol path gives, arrived at from the
+ * other side. Where `jsx-source` is installed it wins, because it is exact
+ * without a map; this is what a project that installed nothing still gets.
+ *
+ * `originalFor` is supplied rather than performed because resolving a frame
+ * means fetching the module the browser was served, and this package may not
+ * assume a network (ADR-0013). The caller owns the fetch, the cache, and the
+ * decision about how long to wait; this owns which frame to ask about and when
+ * to stop asking.
+ */
+export declare function writerLocationOf(frames: readonly StackFrame[], originalFor: (frame: StackFrame) => OriginalPosition | null): SourceLocation | null;
+//# sourceMappingURL=stack.d.ts.map