monkeypatchlist 0.0.0-stage → 0.1.0

package/dist/packages/analysis/lib/keys.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A property key the analyzer knows: a string, or one of the well-known symbols, which are real symbols here so that
+ * they compare, convert and test as JavaScript's own do (`typeof`, `===`, truthiness).
+ */
+export type Key = string | symbol;
+/** The well-known symbol ECMA-262 names `Symbol.<name>` (`%Symbol.iterator%`), e.g. `iterator`. */
+export declare function wellKnownSymbol(name: string): symbol;
+/** How the catalog spells a well-known symbol as a member: `@@iterator`. */
+export declare function symbolMember(symbol: symbol): string;
+/** ECMA-262 ToPropertyKey of a primitive constant: a well-known symbol is itself, and anything else its string. */
+export declare function toPropertyKey(value: string | number | bigint | boolean | null | undefined | symbol): Key;
+/**
+ * The key a literal property name gives in an object literal or pattern (`{ "a": x }`, `{ 1e21: x }`, `{ 1n: x }`), as
+ * ECMA-262 PropertyDefinitionEvaluation converts it: a string, or a number's or BigInt's string. Undefined for any
+ * other node.
+ */
+export declare function literalKey(node: {
+    type: string;
+    [field: string]: unknown;
+}): string | undefined;
+/**
+ * The name of the member `key` of `holder`: `Array.prototype.map`, `Array.prototype.0`, `Array.prototype.@@iterator`,
+ * `Array["prototype.map"]`.
+ */
+export declare function memberName(holder: string, key: Key): string;
+/**
+ * The name of a pattern wildcard (§5 Pattern wildcards): the members of `holder` whose key starts with `prefix`,
+ * `EventTarget.prototype.__zone_symbol__*`. A prefix holding a character §4 writes in brackets (`.`, `[`, `]`, `"`,
+ * `\`, a control character, a leading `@@`, or a `*` anywhere) is JSON-quoted in brackets with the star outside,
+ * `Object.prototype["__core.hidden."]*`, so it never spells a named member (`Object.prototype["__core.hidden.*"]`) or a
+ * nested name.
+ */
+export declare function patternName(holder: string, prefix: string): string;

package/dist/packages/analysis/lib/keys.js

@@ -0,0 +1,82 @@
+// Property keys (§4 Property keys): what a constant key names, as ECMA-262 ToPropertyKey converts it, and how a target
+// name spells a member.
+//
+// - A number, boolean, null or undefined key names its string, so `0` and `"0"` both name `Array.prototype.0`, and a
+//   numeric member uses its canonical string (`1e21` names `1e+21`).
+// - A well-known symbol (`Symbol.iterator`) is a constant of its own, and names the catalog's `@@` member
+//   (`Array.prototype.@@iterator`). The analyzer knows no other symbol.
+// - A string key never spells another target's name: one that could is written in JSON-quoted brackets
+//   (`X.prototype["@@toStringTag"]`, `Array["prototype.map"]`, `console["*"]`).
+/** The well-known symbols, one per name, so that the same symbol is the same value wherever it is read. */
+const symbols = new Map();
+/** Each well-known symbol's member spelling in the catalog: `@@iterator`. */
+const spellings = new Map();
+/** The well-known symbol ECMA-262 names `Symbol.<name>` (`%Symbol.iterator%`), e.g. `iterator`. */
+export function wellKnownSymbol(name) {
+    let symbol = symbols.get(name);
+    if (symbol === undefined) {
+        symbol = Symbol(`Symbol.${name}`);
+        symbols.set(name, symbol);
+        spellings.set(symbol, `@@${name}`);
+    }
+    return symbol;
+}
+/** How the catalog spells a well-known symbol as a member: `@@iterator`. */
+export function symbolMember(symbol) {
+    const spelling = spellings.get(symbol);
+    if (spelling === undefined)
+        throw new Error(`${String(symbol)} is no well-known symbol`);
+    return spelling;
+}
+/** ECMA-262 ToPropertyKey of a primitive constant: a well-known symbol is itself, and anything else its string. */
+export function toPropertyKey(value) {
+    return typeof value === 'symbol' ? value : String(value);
+}
+/**
+ * The key a literal property name gives in an object literal or pattern (`{ "a": x }`, `{ 1e21: x }`, `{ 1n: x }`), as
+ * ECMA-262 PropertyDefinitionEvaluation converts it: a string, or a number's or BigInt's string. Undefined for any
+ * other node.
+ */
+export function literalKey(node) {
+    if (node.type !== 'Literal')
+        return undefined;
+    if (typeof node['bigint'] === 'string')
+        return String(BigInt(node['bigint']));
+    const value = node['value'];
+    return typeof value === 'string' || typeof value === 'number' ? String(value) : undefined;
+}
+/**
+ * The name of the member `key` of `holder`: `Array.prototype.map`, `Array.prototype.0`, `Array.prototype.@@iterator`,
+ * `Array["prototype.map"]`.
+ */
+export function memberName(holder, key) {
+    if (typeof key === 'symbol')
+        return `${holder}.${symbolMember(key)}`;
+    return escaped(key) ? `${holder}[${JSON.stringify(key)}]` : `${holder}.${key}`;
+}
+/**
+ * Whether a string key is written in brackets (§4): one that starts with `@@` (a symbol member's spelling), contains
+ * `.`, `[`, `]`, `"`, `\` or a control character (Unicode's `Cc`), or ends with `*` (a wildcard's spelling). A
+ * canonical numeric key keeps the dot form (`Array.prototype.1.5`), and so do the catalog's names, none of which is one
+ * of these.
+ */
+function escaped(key) {
+    if (isCanonicalNumeric(key))
+        return false;
+    return key.startsWith('@@') || key.endsWith('*') || /[.[\]"\\\p{Cc}]/u.test(key);
+}
+/** ECMA-262 CanonicalNumericIndexString: a key that is the string of a number, as `"1.5"` is and `"1.50"` is not. */
+function isCanonicalNumeric(key) {
+    return key === '-0' || String(Number(key)) === key;
+}
+/**
+ * The name of a pattern wildcard (§5 Pattern wildcards): the members of `holder` whose key starts with `prefix`,
+ * `EventTarget.prototype.__zone_symbol__*`. A prefix holding a character §4 writes in brackets (`.`, `[`, `]`, `"`,
+ * `\`, a control character, a leading `@@`, or a `*` anywhere) is JSON-quoted in brackets with the star outside,
+ * `Object.prototype["__core.hidden."]*`, so it never spells a named member (`Object.prototype["__core.hidden.*"]`) or a
+ * nested name.
+ */
+export function patternName(holder, prefix) {
+    const bracketed = prefix.startsWith('@@') || prefix.includes('*') || /[.[\]"\\\p{Cc}]/u.test(prefix);
+    return bracketed ? `${holder}[${JSON.stringify(prefix)}]*` : `${holder}.${prefix}*`;
+}

package/dist/packages/analysis/lib/line-starts.d.ts

@@ -0,0 +1,41 @@
+import type { ArtifactSource, GeneratedLocation } from './types.ts';
+/**
+ * An artifact's line-start table (§5): the UTF-16 offset where each line starts. Lines end at an ECMAScript
+ * LineTerminatorSequence: LF, CR, CRLF, U+2028 or U+2029.
+ */
+export declare function lineStarts(text: string): number[];
+/**
+ * A member of a link group's text (§6 Link groups): the artifact whose code sits at `base` in the group's text, and its
+ * own line-start table.
+ */
+export interface LinesMember {
+    url: string;
+    hash: string;
+    origin?: ArtifactSource['origin'];
+    base: number;
+    length: number;
+    starts: readonly number[];
+}
+/**
+ * The line-start tables of a link group's members, whose texts the group's text holds one after another. A location is
+ * given in the coordinates of the artifact it is in, and the artifact each location was made for is remembered, so a
+ * trace step can name the artifact its location is in.
+ */
+export declare class GroupLines {
+    #private;
+    readonly members: readonly LinesMember[];
+    constructor(members: readonly LinesMember[]);
+    /** The member whose text holds the group offset `offset`. */
+    memberAt(offset: number): LinesMember;
+    /**
+     * The location of the group range `[start, end)`. One range is located once: the analysis locates the same nodes
+     * again and again, and each location it gives is one the table remembers the member of.
+     */
+    locate(start: number, end: number): GeneratedLocation;
+    /** The member a location this table made is in. */
+    artifactOf(location: GeneratedLocation): LinesMember | undefined;
+}
+/** A line-start table: an artifact's own, or a link group's (`GroupLines`). */
+export type Starts = readonly number[] | GroupLines;
+/** The generated location of the UTF-16 range `[start, end)`: its start as a 1-based line and a 0-based column. */
+export declare function locate(starts: Starts, start: number, end: number): GeneratedLocation;

package/dist/packages/analysis/lib/line-starts.js

@@ -0,0 +1,79 @@
+/**
+ * An artifact's line-start table (§5): the UTF-16 offset where each line starts. Lines end at an ECMAScript
+ * LineTerminatorSequence: LF, CR, CRLF, U+2028 or U+2029.
+ */
+export function lineStarts(text) {
+    const starts = [0];
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if (code === 0x0d && text.charCodeAt(i + 1) === 0x0a)
+            i++;
+        if (code === 0x0a || code === 0x0d || code === 0x2028 || code === 0x2029)
+            starts.push(i + 1);
+    }
+    return starts;
+}
+/**
+ * The line-start tables of a link group's members, whose texts the group's text holds one after another. A location is
+ * given in the coordinates of the artifact it is in, and the artifact each location was made for is remembered, so a
+ * trace step can name the artifact its location is in.
+ */
+export class GroupLines {
+    members;
+    #artifacts = new WeakMap();
+    #located = new Map();
+    constructor(members) {
+        this.members = members;
+    }
+    /** The member whose text holds the group offset `offset`. */
+    memberAt(offset) {
+        const { members } = this;
+        let low = 0;
+        let high = members.length - 1;
+        while (low < high) {
+            const middle = (low + high + 1) >> 1;
+            if (members[middle].base <= offset)
+                low = middle;
+            else
+                high = middle - 1;
+        }
+        return members[low];
+    }
+    /**
+     * The location of the group range `[start, end)`. One range is located once: the analysis locates the same nodes
+     * again and again, and each location it gives is one the table remembers the member of.
+     */
+    locate(start, end) {
+        let byEnd = this.#located.get(start);
+        if (byEnd === undefined)
+            this.#located.set(start, (byEnd = new Map()));
+        const known = byEnd.get(end);
+        if (known !== undefined)
+            return known;
+        const member = this.memberAt(start);
+        const location = locateIn(member.starts, start - member.base, end - member.base);
+        this.#artifacts.set(location, member);
+        byEnd.set(end, location);
+        return location;
+    }
+    /** The member a location this table made is in. */
+    artifactOf(location) {
+        return this.#artifacts.get(location);
+    }
+}
+/** The generated location of the UTF-16 range `[start, end)`: its start as a 1-based line and a 0-based column. */
+export function locate(starts, start, end) {
+    return starts instanceof GroupLines ? starts.locate(start, end) : locateIn(starts, start, end);
+}
+function locateIn(starts, start, end) {
+    let low = 0;
+    let high = starts.length - 1;
+    while (low < high) {
+        const middle = (low + high + 1) >> 1;
+        if (starts[middle] <= start)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    return { start, end, line: low + 1, column: start - starts[low] };
+}

package/dist/packages/analysis/lib/link-group.d.ts

@@ -0,0 +1,51 @@
+import { type AstNode } from './ast.ts';
+import { GroupLines } from './line-starts.ts';
+import type { AnalyzeGroupInput, ArtifactSource } from './types.ts';
+/** The variable an import binding is (`LinkGroup.bound`): its declaration, and the name it declares. */
+export interface Bound {
+    declaration: AstNode;
+    name: string;
+}
+export interface LinkGroup {
+    /** The group's text: its members' texts, one after another. */
+    text: string;
+    /** The group's program. */
+    program: AstNode;
+    sourceType: 'script' | 'module';
+    lines: GroupLines;
+    /** The group's members, entry first, then in the order their code sits in the group's text. */
+    members: ArtifactSource[];
+    /** The members that don't parse, with the parser's error. */
+    failures: {
+        source: ArtifactSource;
+        error: string;
+    }[];
+    /** The variable the import binding `name` of a declaration is, when the declaration is an import. */
+    bound(declaration: AstNode, name: string): Bound | undefined;
+    /** The function each member other than the entry runs in, and the member. */
+    wrappers: ReadonlyMap<AstNode, ArtifactSource>;
+    /** The `import(…)` calls that run each member only dynamic imports reach, by its function (§6). */
+    loadedBy: ReadonlyMap<AstNode, readonly AstNode[]>;
+    /** The members a chunk registry links (§6 idiom 6), by URL: lazy chunks, whose code is always `deferred`. */
+    chunks: ReadonlySet<string>;
+    /** How many module requests of each member's code name no member of the group (§6 Degradation), by URL. */
+    unlinked: ReadonlyMap<string, number>;
+    /**
+     * The import bindings whose module isn't in the group, by their import declaration, which a reference to one resolves
+     * to, and name, each with the import declaration.
+     */
+    unlinkedBindings: ReadonlyMap<AstNode, ReadonlyMap<string, AstNode>>;
+}
+/**
+ * The link group of `entry`: its members, pulled in through the module requests `resolveImport` resolves, and joined
+ * into one program. A group of one artifact is that artifact's program, unchanged. Undefined when the entry's own
+ * module graph fails; `failures` then says why.
+ */
+export declare function linkGroup(entry: ArtifactSource, { artifact, resolveImport, chunks, initialChunks }: Pick<AnalyzeGroupInput, 'artifact' | 'resolveImport' | 'chunks' | 'initialChunks'>): {
+    group?: LinkGroup;
+    failures: {
+        source: ArtifactSource;
+        error: string;
+    }[];
+    pulled: ArtifactSource[];
+};