@zzzen/pyright-internal 1.2.0-dev.20260906 → 1.2.0-dev.20260920

package/dist/trace/reader.js

@@ -0,0 +1,296 @@
+"use strict";
+/*
+ * reader.ts
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT license.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceReader = void 0;
+exports.readTrace = readTrace;
+const recordKinds = new Set([
+    'header',
+    'footer',
+    'entity',
+    'state',
+    'observation',
+    'edge',
+    'program',
+    'enter',
+    'exit',
+    'return',
+    'throw',
+    'branch',
+    'collection-attempt',
+    'collection',
+    'generation',
+    'field-write',
+    'checkpoint',
+    'owner-state',
+    'summary',
+]);
+function readTrace(text, maxBytes = 128 * 1024 * 1024) {
+    if (Buffer.byteLength(text) > maxBytes) {
+        throw new Error('Artifact exceeds reader byte limit');
+    }
+    const records = [];
+    for (const line of text.trimEnd().split('\n')) {
+        const value = JSON.parse(line);
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new Error('Invalid trace record');
+        }
+        const record = value;
+        if (record.seq !== records.length + 1 ||
+            typeof record.kind !== 'string' ||
+            !recordKinds.has(record.kind) ||
+            !record.data ||
+            typeof record.data !== 'object' ||
+            Array.isArray(record.data)) {
+            throw new Error(`Invalid trace record at sequence ${records.length + 1}`);
+        }
+        const requiredStrings = {
+            entity: ['id', 'category'],
+            state: ['entity', 'cause', 'writer'],
+            observation: ['entity', 'cause'],
+            edge: ['relation', 'from', 'to'],
+            enter: ['span', 'label', 'site', 'role'],
+            exit: ['span', 'label'],
+            return: ['span', 'label'],
+            throw: ['span'],
+            checkpoint: ['span', 'phase'],
+            'owner-state': ['span', 'phase'],
+        };
+        if (requiredStrings[record.kind]?.some((key) => typeof record.data[key] !== 'string')) {
+            throw new Error(`Invalid ${record.kind} payload at sequence ${record.seq}`);
+        }
+        if (record.kind === 'state' &&
+            (!Number.isSafeInteger(record.data.version) ||
+                Number(record.data.version) < 1 ||
+                !Array.isArray(record.data.fields) ||
+                !record.data.fields.every((field) => Array.isArray(field) && field.length === 2 && typeof field[0] === 'string'))) {
+            throw new Error(`Invalid state payload at sequence ${record.seq}`);
+        }
+        records.push(record);
+    }
+    const header = records[0];
+    if (header?.kind !== 'header' || header.data.schema !== 'pyright-evaluation-trace' || header.data.version !== 1) {
+        throw new Error('Unsupported trace schema/version');
+    }
+    if (records[records.length - 1]?.kind !== 'footer') {
+        throw new Error('Incomplete artifact: footer missing (do not interpret as complete capture)');
+    }
+    if (records.slice(1, -1).some((r) => r.kind === 'header' || r.kind === 'footer')) {
+        throw new Error('Multiple runs or misplaced header/footer in artifact');
+    }
+    return records;
+}
+class TraceReader {
+    constructor(records) {
+        this.records = records;
+        this._histories = new Map();
+        this._entries = new Map();
+        for (const record of records) {
+            if (record.kind === 'enter') {
+                this._entries.set(String(record.data.span), record);
+            }
+            if (record.kind === 'state') {
+                const id = String(record.data.entity);
+                const history = this._histories.get(id) ?? [];
+                history.push(record);
+                this._histories.set(id, history);
+            }
+        }
+    }
+    timeline(kind, span) {
+        const spans = span ? this._descendants(span) : undefined;
+        return this.records.filter((r) => (!kind || r.kind === kind) && (!spans || spans.has(String(r.data.span))));
+    }
+    history(entity, at = Infinity) {
+        return (this._histories.get(entity) ?? []).filter((r) => r.seq <= at);
+    }
+    latest(entity, at = Infinity) {
+        const history = this.history(entity, at);
+        return history[history.length - 1] ?? null;
+    }
+    neighborhood(entity, relation) {
+        return this.records.filter((r) => r.kind === 'edge' &&
+            (r.data.from === entity || r.data.to === entity) &&
+            (!relation || r.data.relation === relation));
+    }
+    pairs() {
+        const baselines = new Map();
+        const pairs = [];
+        for (const r of this.records) {
+            if (r.kind !== 'enter' || r.data.label !== '_trial' || !r.data.operation) {
+                continue;
+            }
+            const key = JSON.stringify(r.data.operation);
+            if (r.data.role === 'baseline') {
+                baselines.set(key, String(r.data.span));
+            }
+            else if (r.data.role === 'candidate' && baselines.has(key)) {
+                pairs.push({ operation: r.data.operation, baseline: baselines.get(key), replay: String(r.data.span) });
+            }
+        }
+        return pairs;
+    }
+    diff(baseline, replay) {
+        for (const span of [baseline, replay]) {
+            if (!this.records.some((r) => r.kind === 'enter' && r.data.span === span)) {
+                throw new Error(`Unknown evaluation span ${span}`);
+            }
+        }
+        const summarize = (span) => {
+            const events = this.timeline(undefined, span);
+            const counts = {};
+            for (const r of events) {
+                const key = `${r.kind}:${r.data.label ?? ''}:${r.data.method ?? ''}`;
+                counts[key] = (counts[key] ?? 0) + 1;
+            }
+            const first = events[0]?.seq;
+            const last = events[events.length - 1]?.seq;
+            const changes = first === undefined || last === undefined
+                ? []
+                : this.records.filter((r) => r.kind === 'state' && r.seq >= first && r.seq <= last && r.data.previous !== null);
+            return {
+                counts,
+                boundaries: events.filter((r) => ['checkpoint', 'owner-state', 'throw'].includes(r.kind) ||
+                    (r.data.span === span && ['enter', 'return', 'exit'].includes(r.kind))),
+                firstResult: this.firstResult(span),
+                changes,
+            };
+        };
+        const left = summarize(baseline);
+        const right = summarize(replay);
+        const all = this.timeline(undefined, baseline);
+        const after = all[all.length - 1]?.seq ?? 0;
+        const beforeReplay = this.timeline(undefined, replay)[0]?.seq ?? 0;
+        const changedEntities = [...new Set(left.changes.map((r) => String(r.data.entity)))];
+        return {
+            baseline: left,
+            replay: right,
+            boundaryComparisons: this.boundaryComparisons(baseline, replay),
+            survivingObservations: changedEntities.map((entity) => ({
+                entity,
+                afterBaseline: this.latest(entity, after),
+                beforeReplay: this.latest(entity, beforeReplay),
+                meaning: 'latest observations only; unobserved intervals do not establish persistence',
+            })),
+            coverage: this.records[this.records.length - 1],
+            conclusion: 'Observed differences, not a reuse certificate or universal equivalence',
+        };
+    }
+    boundaryComparisons(baseline, replay) {
+        const boundaries = [
+            this.checkpoint(baseline, 'entry'),
+            this.checkpoint(baseline, 'complete-live'),
+            this.checkpoint(baseline, 'unwind'),
+            this.checkpoint(replay, 'entry'),
+            this.checkpoint(replay, 'complete-live'),
+            this.checkpoint(replay, 'unwind'),
+        ];
+        const observed = boundaries.map((boundary) => {
+            const entities = new Map();
+            if (boundary) {
+                const cause = `${boundary.data.span}:${boundary.data.phase}`;
+                for (const record of this.records) {
+                    if (record.kind === 'observation' && record.data.cause === cause) {
+                        const entity = String(record.data.entity);
+                        const state = this._histories.get(entity)?.find((s) => s.data.version === record.data.version);
+                        if (state) {
+                            entities.set(entity, { state, observation: record });
+                        }
+                    }
+                }
+            }
+            return entities;
+        });
+        const same = (a, b) => !a || !b
+            ? 'unobserved'
+            : JSON.stringify(a.data.fields) === JSON.stringify(b.data.fields)
+                ? 'same-fields'
+                : 'changed-fields';
+        const entities = [...new Set(observed.flatMap((map) => [...map.keys()]))];
+        return {
+            order: [
+                'baseline-entry',
+                'baseline-live',
+                'baseline-unwind',
+                'replay-entry',
+                'replay-live',
+                'replay-unwind',
+            ],
+            entities: entities.map((entity) => {
+                const states = observed.map((map) => map.get(entity)?.state);
+                return {
+                    entity,
+                    versions: states.map((s) => s?.data.version ?? null),
+                    // Owner-state snapshots can follow the checkpoint marker. A
+                    // cell links its actual observation, not the marker or the
+                    // earlier sequence that first introduced an unchanged version.
+                    observationSequences: observed.map((map) => map.get(entity)?.observation.seq ?? null),
+                    stateSequences: states.map((s) => s?.seq ?? null),
+                    complete: states.map((s) => s?.data.complete ?? false),
+                    baselineChange: same(states[0], states[1]),
+                    unwindChange: same(states[1], states[2]),
+                    betweenTrials: same(states[2], states[3]),
+                    replayChange: same(states[3], states[4]),
+                    observedMutationSurvived: same(states[0], states[1]) === 'changed-fields' && same(states[1], states[2]) === 'same-fields',
+                };
+            }),
+            meaning: 'Own fields observed at both boundaries only. Missing/depth-limited children remain unknown.',
+        };
+    }
+    checkpoint(span, phase) {
+        const matches = this.timeline('checkpoint', span).filter((r) => r.data.phase === phase && this._belongsToScope(String(r.data.span), span));
+        // Missing or ambiguous boundaries are unknown, not a descendant's state.
+        return matches.length === 1 ? matches[0] : null;
+    }
+    firstResult(span) {
+        const entry = this._entries.get(span);
+        const args = entry?.data.args;
+        const expression = JSON.stringify(entry?.data.label === 'getTypeOfExpression' && args && typeof args === 'object' && !Array.isArray(args)
+            ? args.node
+            : entry?.data.expression);
+        const events = this.timeline(undefined, span);
+        const call = events.find((r) => r.kind === 'enter' &&
+            r.data.label === 'getTypeOfExpression' &&
+            this._belongsToScope(String(r.data.span), span) &&
+            r.data.args &&
+            !Array.isArray(r.data.args) &&
+            typeof r.data.args === 'object' &&
+            JSON.stringify(r.data.args.node) === expression);
+        return events.find((r) => r.kind === 'return' && r.data.span === call?.data.span) ?? null;
+    }
+    _belongsToScope(candidate, scope) {
+        const seen = new Set();
+        let current = candidate;
+        while (current !== undefined && !seen.has(current)) {
+            seen.add(current);
+            const entry = this._entries.get(current);
+            if (!entry) {
+                return false;
+            }
+            if (current === scope) {
+                return true;
+            }
+            // The nearest trial owns its descendants, even for the same expression
+            // or logical role. Ordinary scopes still work without a trial ancestor.
+            if (entry.data.label === '_trial') {
+                return false;
+            }
+            current = typeof entry.data.parent === 'string' ? entry.data.parent : undefined;
+        }
+        return false;
+    }
+    _descendants(span) {
+        const spans = new Set([span]);
+        for (const r of this.records) {
+            if (r.kind === 'enter' && spans.has(String(r.data.parent))) {
+                spans.add(String(r.data.span));
+            }
+        }
+        return spans;
+    }
+}
+exports.TraceReader = TraceReader;
+//# sourceMappingURL=reader.js.map

package/dist/trace/reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.js","sourceRoot":"","sources":["../../../../../src/trace/reader.ts"],"names":[],"mappings":"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"}

package/dist/trace/recorder.d.ts

@@ -0,0 +1,59 @@
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export type Atom = null | boolean | number | string | {
+    ref: string;
+} | {
+    special: string;
+};
+export interface TraceRecord {
+    seq: number;
+    kind: string;
+    data: {
+        [key: string]: Json;
+    };
+}
+export interface Limits {
+    events: number;
+    entities: number;
+    bytes: number;
+    depth: number;
+    properties: number;
+    snapshotEntities: number;
+    stringLength: number;
+}
+export declare const defaultLimits: Limits;
+export declare function own(value: unknown, key: string): unknown;
+export declare function isObject(value: unknown): value is object;
+export declare class Recorder {
+    private readonly _sink;
+    readonly run: string;
+    readonly limits: Limits;
+    private _ids;
+    private _states;
+    private _nextEntity;
+    private _nextOccurrence;
+    private _sequence;
+    private _bytes;
+    private _ended;
+    private _exhausted;
+    private _gaps;
+    private _dropped;
+    constructor(_sink: (record: TraceRecord) => void, provenance: {
+        [key: string]: Json;
+    }, limits?: Partial<Limits>, run?: string);
+    get active(): boolean;
+    occurrence(): string;
+    gap(reason: string): void;
+    atom(value: unknown): Atom;
+    observe(value: unknown, cause: string, depth?: number): Atom;
+    values(values: Record<string, unknown>, cause: string, depth?: number): {
+        [key: string]: Json;
+    };
+    emit(kind: string, data: {
+        [key: string]: Json;
+    }): void;
+    finish(status: 'completed' | 'threw' | 'recorder-failed', error?: string | null): void;
+    private _category;
+    private _write;
+}

package/dist/trace/recorder.js

@@ -0,0 +1,303 @@
+"use strict";
+/*
+ * recorder.ts
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT license.
+ *
+ * Developer-only, bounded observations. Nothing in the analyzer imports this module.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Recorder = exports.defaultLimits = void 0;
+exports.own = own;
+exports.isObject = isObject;
+const crypto_1 = require("crypto");
+const util_1 = require("util");
+exports.defaultLimits = {
+    events: 200000,
+    entities: 50000,
+    bytes: 64 * 1024 * 1024,
+    depth: 3,
+    properties: 80,
+    snapshotEntities: 200,
+    stringLength: 4096,
+};
+function own(value, key) {
+    if (!isObject(value) || util_1.types.isProxy(value)) {
+        return undefined;
+    }
+    return Object.getOwnPropertyDescriptor(value, key)?.value;
+}
+function isObject(value) {
+    return (typeof value === 'object' && value !== null) || typeof value === 'function';
+}
+class Recorder {
+    constructor(_sink, provenance, limits = {}, run = (0, crypto_1.randomUUID)()) {
+        this._sink = _sink;
+        this._ids = new WeakMap();
+        this._states = new Map();
+        this._nextEntity = 0;
+        this._nextOccurrence = 0;
+        this._sequence = 0;
+        this._bytes = 0;
+        this._ended = false;
+        this._exhausted = false;
+        this._gaps = new Set();
+        this._dropped = 0;
+        this.run = run;
+        if (!run || run.length > 128) {
+            throw new Error('Run identity must contain 1-128 characters');
+        }
+        this.limits = { ...exports.defaultLimits, ...limits };
+        for (const [name, value] of Object.entries(this.limits)) {
+            if (!Number.isSafeInteger(value) || value < 1) {
+                throw new Error(`Invalid trace limit ${name}: ${value}`);
+            }
+        }
+        if (this.limits.bytes < 4096) {
+            throw new Error('Trace byte limit must leave at least 4096 bytes for metadata and footer');
+        }
+        if (Buffer.byteLength(JSON.stringify(provenance)) > this.limits.bytes - 3072) {
+            this.gap('provenance-byte-budget');
+            provenance = { omitted: 'provenance exceeds byte budget' };
+        }
+        this._write('header', {
+            schema: 'pyright-evaluation-trace',
+            version: 1,
+            run,
+            provenance,
+            limits: { ...this.limits },
+        });
+    }
+    get active() {
+        return !this._ended && !this._exhausted;
+    }
+    occurrence() {
+        return `${this.run}:s${++this._nextOccurrence}`;
+    }
+    gap(reason) {
+        this._gaps.add(this._gaps.size < 16 ? reason.slice(0, 64) : 'additional-coverage-gaps');
+    }
+    atom(value) {
+        if (value === null || typeof value === 'boolean') {
+            return value;
+        }
+        if (typeof value === 'string') {
+            if (value.length > this.limits.stringLength) {
+                this.gap('stringLength');
+                return { special: `truncated-string:${value.slice(0, this.limits.stringLength)}` };
+            }
+            return value;
+        }
+        if (typeof value === 'number') {
+            return Number.isFinite(value) && !Object.is(value, -0)
+                ? value
+                : { special: Object.is(value, -0) ? '-0' : String(value) };
+        }
+        if (!isObject(value)) {
+            return { special: typeof value === 'bigint' ? `bigint:${value}` : typeof value };
+        }
+        let id = this._ids.get(value);
+        if (!id) {
+            if (this._nextEntity >= this.limits.entities || !this.active) {
+                this.gap('entities');
+                return { special: 'unobserved-entity' };
+            }
+            id = `${this.run}:e${++this._nextEntity}`;
+            this._ids.set(value, id);
+            this.emit('entity', { id, category: this._category(value) });
+        }
+        return { ref: id };
+    }
+    // Snapshot versions describe observations, not universal mutation counters. A
+    // changed child does not imply that a referencing map or Type was replaced.
+    observe(value, cause, depth = this.limits.depth) {
+        const root = this.atom(value);
+        if (!this.active || !isObject(value)) {
+            return root;
+        }
+        const seen = new Set();
+        const visit = (object, remaining) => {
+            if (seen.has(object) || !this.active) {
+                return;
+            }
+            if (seen.size >= this.limits.snapshotEntities) {
+                this.gap('snapshotEntities');
+                return;
+            }
+            seen.add(object);
+            const atom = this.atom(object);
+            if (typeof atom !== 'object' || atom === null || !('ref' in atom)) {
+                return;
+            }
+            const fields = [];
+            const children = [];
+            let complete = true;
+            const add = (name, child) => {
+                const atom = this.atom(child);
+                fields.push([name, atom]);
+                if (atom &&
+                    typeof atom === 'object' &&
+                    'special' in atom &&
+                    (atom.special === 'unobserved-entity' || atom.special.startsWith('truncated-string:'))) {
+                    complete = false;
+                }
+                if (isObject(child)) {
+                    children.push(child);
+                }
+            };
+            if (util_1.types.isProxy(object) || typeof object === 'function') {
+                fields.push(['opaque', { special: util_1.types.isProxy(object) ? 'proxy' : 'function' }]);
+                complete = false;
+                this.gap(util_1.types.isProxy(object) ? 'opaque-proxy' : 'opaque-function');
+            }
+            else if (util_1.types.isMap(object) || util_1.types.isSet(object)) {
+                const entries = util_1.types.isMap(object)
+                    ? Map.prototype.entries.call(object)
+                    : Set.prototype.values.call(object);
+                let index = 0;
+                for (const entry of entries) {
+                    if (index >= this.limits.properties) {
+                        complete = false;
+                        this.gap('properties');
+                        break;
+                    }
+                    if (util_1.types.isMap(object)) {
+                        const [key, child] = entry;
+                        add(`key:${index}`, key);
+                        add(`value:${index}`, child);
+                    }
+                    else {
+                        add(`${index}`, entry);
+                    }
+                    index++;
+                }
+            }
+            else if (util_1.types.isWeakMap(object) || util_1.types.isWeakSet(object)) {
+                fields.push(['opaque', { special: 'weak-collection' }]);
+                complete = false;
+                this.gap('opaque-weak-collection');
+            }
+            else {
+                const names = Object.getOwnPropertyNames(object);
+                complete = names.length <= this.limits.properties;
+                if (!complete) {
+                    this.gap('properties');
+                }
+                for (const name of names.slice(0, this.limits.properties)) {
+                    const descriptor = Object.getOwnPropertyDescriptor(object, name);
+                    if ('value' in descriptor) {
+                        add(name, descriptor.value);
+                    }
+                    else {
+                        fields.push([name, { special: 'accessor-not-invoked' }]);
+                        complete = false;
+                        this.gap('opaque-accessor');
+                    }
+                }
+                if (Object.getOwnPropertySymbols(object).length) {
+                    complete = false;
+                    this.gap('symbol-properties');
+                }
+            }
+            const fingerprint = JSON.stringify({ fields, complete });
+            const previous = this._states.get(atom.ref);
+            if (!previous || previous.fingerprint !== fingerprint) {
+                const version = (previous?.version ?? 0) + 1;
+                this._states.set(atom.ref, { fingerprint, version });
+                this.emit('state', {
+                    entity: atom.ref,
+                    version,
+                    previous: previous?.version ?? null,
+                    cause,
+                    writer: 'unknown-between-observations',
+                    complete,
+                    fields,
+                });
+                for (const [field, child] of fields) {
+                    if (typeof child === 'object' && child !== null && 'ref' in child) {
+                        this.emit('edge', { relation: 'reference', from: atom.ref, to: child.ref, field, version });
+                    }
+                }
+            }
+            this.emit('observation', {
+                entity: atom.ref,
+                version: this._states.get(atom.ref).version,
+                cause,
+                complete,
+            });
+            if (remaining > 0) {
+                for (const child of children) {
+                    // Parse-tree links would otherwise swamp type/state observations.
+                    if (typeof own(child, 'nodeType') !== 'number') {
+                        visit(child, remaining - 1);
+                    }
+                }
+            }
+            else if (children.length) {
+                this.gap('depth');
+            }
+        };
+        visit(value, depth);
+        return root;
+    }
+    values(values, cause, depth) {
+        return Object.fromEntries(Object.entries(values).map(([key, value]) => [key, this.observe(value, cause, depth)]));
+    }
+    emit(kind, data) {
+        if (!this.active) {
+            this._dropped++;
+            return;
+        }
+        const size = Buffer.byteLength(JSON.stringify({ seq: this._sequence + 1, kind, data })) + 1;
+        if (this._sequence >= this.limits.events || this._bytes + size > this.limits.bytes - 2048) {
+            this._exhausted = true;
+            this._dropped++;
+            this.gap('event-or-byte-budget');
+            return;
+        }
+        this._write(kind, data);
+    }
+    finish(status, error = null) {
+        if (this._ended) {
+            throw new Error('Recorder already finished');
+        }
+        this._ended = true;
+        this._write('footer', {
+            status,
+            error: error?.slice(0, 512) ?? null,
+            exhausted: this._exhausted,
+            gaps: [...this._gaps],
+            dropped: this._dropped,
+            entities: this._nextEntity,
+            occurrences: this._nextOccurrence,
+            coverage: 'observed-domains-only; not proof of no other dependencies or effects',
+        });
+        this._states.clear();
+        this._ids = new WeakMap();
+    }
+    _category(value) {
+        if (util_1.types.isProxy(value)) {
+            return 'opaque-proxy';
+        }
+        if (typeof value === 'function') {
+            return 'function';
+        }
+        if (typeof own(value, 'nodeType') === 'number') {
+            return 'parse-node';
+        }
+        if (typeof own(value, 'category') === 'number' && own(value, 'flags') !== undefined) {
+            return 'type';
+        }
+        if (own(value, 'type') !== undefined) {
+            return 'type-bearing-object';
+        }
+        return util_1.types.isMap(value) ? 'map' : util_1.types.isSet(value) ? 'set' : Array.isArray(value) ? 'array' : 'object';
+    }
+    _write(kind, data) {
+        const record = { seq: ++this._sequence, kind, data };
+        this._bytes += Buffer.byteLength(JSON.stringify(record)) + 1;
+        this._sink(record);
+    }
+}
+exports.Recorder = Recorder;
+//# sourceMappingURL=recorder.js.map