@secureport/core 0.2.0 → 0.3.0

package/dist/reconcile.js

@@ -1,23 +1,317 @@
+import { DEFAULT_SLA_POLICY, SEVERITY_ORDER, SEVERITY_WEIGHTS, severityRank, slaDueAt, } from './severity.js';
+import { coversLocation } from './coverage.js';
 /**
- * Merges incoming findings into the tracked issue set. A finding whose title
- * matches an open issue is folded into it; anything new opens an issue.
+ * The key an issue and a finding must share to be the same issue.
  *
- * Pure: no I/O, no clock, no randomness. Callers supply the id for any issue
- * this opens via `nextId`.
+ * **The fingerprint version is part of it, not decoration.** A fingerprint means
+ * nothing without the algorithm that produced it, so an `fp_v1` finding must
+ * never match an `fp_v2` issue — reconciling across versions would silently
+ * merge two things that were never computed the same way. Crossing a version is
+ * what a re-fingerprint migration is for.
+ *
+ * The separator is an escape rather than a literal control character, so the
+ * source stays plain text: an invisible NUL here once passed prettier, eslint,
+ * tsc and the whole test suite, and was only caught because `grep` went quiet
+ * on a file it could no longer read.
  */
-export function reconcile(findings, openIssues, nextId) {
-    const byTitle = new Map(openIssues.map((issue) => [issue.title, issue]));
+function issueKey(of) {
+    return `${of.fingerprintVersion}\u0000${of.fingerprint}`;
+}
+/** Groups this run's findings by the issue they belong to. */
+function groupByFingerprint(findings) {
+    const groups = new Map();
     for (const finding of findings) {
-        const existing = byTitle.get(finding.title);
+        // The version is part of the key. A fingerprint means nothing without the
+        // algorithm that produced it, so a `fp_v1` finding must never match a
+        // `fp_v2` issue — that is what a re-fingerprint migration is for.
+        const key = issueKey(finding);
+        const existing = groups.get(key);
+        if (existing)
+            existing.push(finding);
+        else
+            groups.set(key, [finding]);
+    }
+    return groups;
+}
+/** The most urgent severity among a group of findings for one issue. */
+function highestSeverity(findings) {
+    return findings.reduce((worst, candidate) => severityRank(candidate.detectedSeverity) > severityRank(worst.detectedSeverity)
+        ? candidate
+        : worst);
+}
+/** The default flapping guard for a run kind. */
+function defaultThreshold(kind) {
+    // An upload asserts a complete result, so one miss is enough. A scan can miss
+    // for reasons that say nothing about the issue.
+    return kind === 'upload' ? 1 : 2;
+}
+/** An all-zero count, so a report never has to decide what a missing key means. */
+function emptyCounts() {
+    return Object.fromEntries(SEVERITY_ORDER.map((s) => [s, 0]));
+}
+/** Whole days between two moments, floored. */
+function daysBetween(from, to) {
+    return Math.max(0, Math.floor((to.getTime() - from.getTime()) / 86_400_000));
+}
+/**
+ * Turns a run's findings into issue state.
+ *
+ * **The only writer of issue state, and a pure function.** Given the same
+ * issues, findings, run and clock it produces the same result every time. It
+ * performs no I/O, reads no clock and generates no randomness; the caller
+ * supplies `now` and `newId` and persists what comes back.
+ *
+ * This half handles everything a **present** finding causes:
+ *
+ * - a fingerprint that matches nothing opens an issue (`created`);
+ * - a fingerprint that matches attaches evidence and refreshes `lastSeen`,
+ *   clearing the miss counter (`seen`);
+ * - a `resolved` issue seen again becomes `regressed` (`reopened`) — a returning
+ *   problem is a different and more interesting event than a new one;
+ * - a changed detected severity updates the issue, and updates the *effective*
+ *   severity and the SLA deadline only where nobody has overridden it
+ *   (`severity_detected_changed`);
+ * - an `ignored` issue whose detected severity has risen above what was
+ *   accepted comes back (`unignored`) — accepting the risk of a medium is not
+ *   accepting the risk of the critical it turned out to be.
+ *
+ * And everything an **absent** finding causes:
+ *
+ * - an issue the run covered but did not see takes a miss, and resolves once it
+ *   has missed enough consecutive covering runs (`resolved`);
+ * - an issue **outside** the run's coverage is untouched — not resolved, and not
+ *   even counted as a miss, so a sequence of narrow scans cannot accumulate
+ *   misses against a path none of them looked at (invariant 5);
+ * - a **manual-origin** issue never auto-resolves; a human closes what a human
+ *   opened (invariant 6);
+ * - a suppression whose expiry has passed lapses (`unignored`), regardless of
+ *   coverage — an ignore expiring is a decision timing out, not an observation.
+ *
+ * Finally it computes the {@link RunSummary}: counts by severity for new, still
+ * open, resolved, regressed and ignored, plus the exposure score. Ignored issues
+ * are excluded from every count but their own, and from exposure, and never from
+ * the suppressed appendix (invariant 7).
+ *
+ * `firstSeen` is never reset, by anything here (invariant 4).
+ *
+ * @param input - Issues, findings, the run, the clock and an id source.
+ * @returns Every issue for the target, plus the events that explain the changes.
+ */
+export function reconcile(input) {
+    const { issues, findings, run, now, newId } = input;
+    const actor = input.actor ?? 'reconciler';
+    const slaPolicy = input.slaPolicy ?? DEFAULT_SLA_POLICY;
+    const events = [];
+    const emit = (issueId, type, payload) => {
+        events.push({
+            id: newId(),
+            orgId: run.orgId,
+            issueId,
+            runId: run.id,
+            type,
+            actor,
+            ...(payload === undefined ? {} : { payload }),
+            createdAt: now,
+        });
+    };
+    const byKey = new Map(issues.map((i) => [issueKey(i), i]));
+    const updated = new Map();
+    for (const [key, group] of groupByFingerprint(findings)) {
+        const existing = byKey.get(key);
+        const worst = highestSeverity(group);
+        const findingIds = group.map((f) => f.id);
         if (!existing) {
-            byTitle.set(finding.title, {
-                id: nextId(),
-                title: finding.title,
-                severity: finding.severity,
+            const id = newId();
+            const issue = {
+                id,
+                orgId: run.orgId,
+                targetId: run.targetId,
+                fingerprint: worst.fingerprint,
+                fingerprintVersion: worst.fingerprintVersion,
+                title: worst.title,
+                vulnKey: worst.vulnKey,
+                ...(worst.cwe === undefined ? {} : { cwe: worst.cwe }),
+                location: worst.location,
+                ...(worst.parameter === undefined ? {} : { parameter: worst.parameter }),
                 status: 'open',
+                detectedSeverity: worst.detectedSeverity,
+                effectiveSeverity: worst.detectedSeverity,
+                firstSeen: now,
+                lastSeen: now,
+                consecutiveMisses: 0,
+                origin: run.kind,
+                slaDueAt: slaDueAt(worst.detectedSeverity, now, slaPolicy),
+            };
+            updated.set(key, issue);
+            emit(id, 'created', { findingIds, severity: worst.detectedSeverity });
+            continue;
+        }
+        // One `seen` per issue per run, not one per finding. `issue_events` is what
+        // every analytic counts, and a weakness two engines both detected would
+        // otherwise register as two sightings of one issue.
+        let issue = { ...existing, lastSeen: now, consecutiveMisses: 0 };
+        emit(issue.id, 'seen', { findingIds });
+        if (issue.status === 'resolved') {
+            issue = { ...issue, status: 'regressed', reopenedAt: now };
+            emit(issue.id, 'reopened', { resolvedAt: existing.resolvedAt?.toISOString() });
+        }
+        if (worst.detectedSeverity !== issue.detectedSeverity) {
+            const overridden = issue.severityOverriddenAt !== undefined;
+            const raisedAboveOverride = overridden && severityRank(worst.detectedSeverity) > severityRank(issue.effectiveSeverity);
+            emit(issue.id, 'severity_detected_changed', {
+                from: issue.detectedSeverity,
+                to: worst.detectedSeverity,
+                // "Flag for review" in the spec, which names no column to flag it in.
+                // Recorded on the event rather than invented as a field: the detected
+                // severity has risen above a human's override, and somebody should look.
+                needsReview: raisedAboveOverride,
+            });
+            issue = overridden
+                ? { ...issue, detectedSeverity: worst.detectedSeverity }
+                : {
+                    ...issue,
+                    detectedSeverity: worst.detectedSeverity,
+                    effectiveSeverity: worst.detectedSeverity,
+                    slaDueAt: slaDueAt(worst.detectedSeverity, issue.firstSeen, slaPolicy),
+                };
+        }
+        if (issue.status === 'ignored' &&
+            issue.severityAtIgnore !== undefined &&
+            severityRank(worst.detectedSeverity) > severityRank(issue.severityAtIgnore)) {
+            emit(issue.id, 'unignored', {
+                reason: 'severity increased',
+                from: issue.severityAtIgnore,
+                to: worst.detectedSeverity,
             });
+            issue = {
+                ...issue,
+                status: 'open',
+                ignoreReason: undefined,
+                ignoreComment: undefined,
+                ignoreScope: undefined,
+                ignoreExpiresAt: undefined,
+                ignoredBy: undefined,
+                severityAtIgnore: undefined,
+            };
+        }
+        updated.set(key, issue);
+    }
+    const created = new Set([...updated.keys()].filter((k) => !byKey.has(k)));
+    const regressedNow = new Set([...updated].filter(([k, i]) => !created.has(k) && i.status === 'regressed').map(([k]) => k));
+    const resolvedNow = new Set();
+    // ---- what an absent finding causes -------------------------------------
+    //
+    // A run resolves only what it could have found. An issue outside coverage is
+    // left entirely alone: not resolved, and not counted as a miss either, so a
+    // sequence of narrow scans cannot accumulate misses against a path none of
+    // them looked at.
+    const threshold = input.autoResolveThreshold ?? defaultThreshold(run.kind);
+    for (const original of issues) {
+        const key = issueKey(original);
+        if (updated.has(key))
+            continue; // seen this run
+        if (original.status !== 'open' && original.status !== 'regressed')
+            continue;
+        // A human closes what a human opened (invariant 6).
+        if (original.origin === 'manual')
+            continue;
+        if (!coversLocation(original.location, run.coverage))
+            continue;
+        const misses = original.consecutiveMisses + 1;
+        if (misses < threshold) {
+            updated.set(key, { ...original, consecutiveMisses: misses });
+            continue;
+        }
+        updated.set(key, {
+            ...original,
+            consecutiveMisses: misses,
+            status: 'resolved',
+            resolvedAt: now,
+        });
+        resolvedNow.add(key);
+        emit(original.id, 'resolved', { consecutiveMisses: misses, threshold });
+    }
+    // ---- suppressions that have lapsed --------------------------------------
+    //
+    // Independent of coverage and of whether the issue was seen: an ignore
+    // expiring is a decision timing out, not an observation.
+    for (const original of issues) {
+        const key = issueKey(original);
+        const current = updated.get(key) ?? original;
+        if (current.status !== 'ignored')
+            continue;
+        if (current.ignoreExpiresAt === undefined)
+            continue;
+        if (current.ignoreExpiresAt.getTime() > now.getTime())
+            continue;
+        emit(current.id, 'unignored', {
+            reason: 'expired',
+            expiredAt: current.ignoreExpiresAt.toISOString(),
+        });
+        updated.set(key, {
+            ...current,
+            status: 'open',
+            ignoreReason: undefined,
+            ignoreComment: undefined,
+            ignoreScope: undefined,
+            ignoreExpiresAt: undefined,
+            ignoredBy: undefined,
+            severityAtIgnore: undefined,
+        });
+    }
+    // Untouched issues are returned unchanged, in their original order, so a
+    // caller can write the whole set back without diffing.
+    const result = issues.map((i) => updated.get(issueKey(i)) ?? i);
+    for (const [key, issue] of updated)
+        if (!byKey.has(key))
+            result.push(issue);
+    // ---- the summary --------------------------------------------------------
+    const counts = {
+        new: emptyCounts(),
+        stillOpen: emptyCounts(),
+        resolved: emptyCounts(),
+        regressed: emptyCounts(),
+        ignored: emptyCounts(),
+    };
+    let exposureScore = 0;
+    for (const issue of result) {
+        const key = issueKey(issue);
+        const severity = issue.effectiveSeverity;
+        if (issue.status === 'ignored') {
+            // Excluded from every other count and from exposure, never from the
+            // suppressed appendix (invariant 7).
+            counts.ignored[severity]++;
+            continue;
+        }
+        if (created.has(key))
+            counts.new[severity]++;
+        else if (resolvedNow.has(key))
+            counts.resolved[severity]++;
+        else if (regressedNow.has(key))
+            counts.regressed[severity]++;
+        else if (updated.has(key))
+            counts.stillOpen[severity]++;
+        if (issue.status === 'open' || issue.status === 'regressed') {
+            exposureScore += SEVERITY_WEIGHTS[severity] * Math.min(daysBetween(issue.firstSeen, now), 90);
         }
     }
-    return [...byTitle.values()];
+    const summary = {
+        runId: run.id,
+        orgId: run.orgId,
+        targetId: run.targetId,
+        kind: run.kind,
+        trigger: run.trigger,
+        engines: run.coverage.engines,
+        coverage: run.coverage,
+        durationMs: input.durationMs ?? 0,
+        new: counts.new,
+        stillOpen: counts.stillOpen,
+        resolved: counts.resolved,
+        regressed: counts.regressed,
+        ignored: counts.ignored,
+        exposureScore,
+        createdAt: now,
+    };
+    return { issues: result, events, summary };
 }
 //# sourceMappingURL=reconcile.js.map

package/dist/reconcile.js.map

@@ -1 +1 @@
-{"version":3,"file":"reconcile.js","sourceRoot":"","sources":["../src/reconcile.ts"],"names":[],"mappings":"AAQA;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,QAAmB,EAAE,UAAmB,EAAE,MAAoB;IACtF,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAEzE,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC5C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE;gBACzB,EAAE,EAAE,MAAM,EAAE;gBACZ,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,MAAM,EAAE,MAAM;aACf,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"reconcile.js","sourceRoot":"","sources":["../src/reconcile.ts"],"names":[],"mappings":"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"}

package/dist/run.d.ts

@@ -0,0 +1,134 @@
+import type { Severity } from './severity.js';
+/**
+ * What kind of run this was.
+ *
+ * - `scan` — Secureport originated the traffic.
+ * - `upload` — someone brought results from elsewhere.
+ * - `manual` — a human recorded a finding directly.
+ *
+ * **An upload is first-class, not a lesser scan.** Much of the value is in
+ * tracking results a customer already has, and a model that treated uploads as
+ * second-class would make that path feel second-class too.
+ */
+export type RunKind = 'scan' | 'upload' | 'manual';
+/**
+ * What set the run going.
+ *
+ * Recorded on every run from the first line of code, because it is what lets
+ * you say "the Action ran 340 times this quarter" — the sentence that shows
+ * automation is actually being used rather than merely installed.
+ */
+export type RunTrigger = 'github_action' | 'cli' | 'api' | 'scheduled' | 'web';
+/**
+ * What a run actually exercised.
+ *
+ * The reason auto-resolution is safe. **A run only resolves what it could have
+ * found** (invariant 5): a quick profile that skipped `/admin` must not close
+ * an `/admin` issue, because not looking is not the same as not finding.
+ *
+ * Scan runs record what they genuinely reached. Upload runs take a declared
+ * scope, defaulting to the whole target — the person uploading is asserting
+ * what their results cover.
+ */
+export interface Coverage {
+    /**
+     * Location patterns the run covered, as globs, e.g.
+     * `https://app.example.com/**`.
+     *
+     * An issue whose location matches none of these is untouched by this run,
+     * whatever else happened.
+     */
+    readonly paths: readonly string[];
+    /** Ports exercised, where the run was port-aware. */
+    readonly ports?: readonly number[];
+    /** Engines that took part. */
+    readonly engines: readonly string[];
+}
+/**
+ * One execution against a target.
+ */
+export interface Run {
+    /** Unique id. */
+    readonly id: string;
+    /** Organisation this run belongs to. */
+    readonly orgId: string;
+    /** Target it ran against. */
+    readonly targetId: string;
+    /** What kind of run it was. */
+    readonly kind: RunKind;
+    /** What set it going. */
+    readonly trigger: RunTrigger;
+    /** What it exercised. */
+    readonly coverage: Coverage;
+    /**
+     * The verification this run relied on, for runs that originate traffic.
+     *
+     * Recorded per run rather than per organisation, because verification
+     * belongs to a target: verifying production must never authorise scanning
+     * staging, even on the same wildcard domain (invariant 11).
+     */
+    readonly verificationId?: string;
+    /** When it started. */
+    readonly startedAt: Date;
+    /** When it finished. */
+    readonly finishedAt?: Date;
+}
+/**
+ * A count of issues per {@link Severity}.
+ *
+ * Every severity is present, including zeroes, so a report renders a complete
+ * table without deciding what a missing key means.
+ */
+export type SeverityCounts = Readonly<Record<Severity, number>>;
+/**
+ * What a run did, in the terms a reader cares about.
+ *
+ * The change summary every report opens with, and the row analytics aggregate.
+ * Computed once by reconciliation and stored, so no report has to recount
+ * findings at render time.
+ */
+export interface RunSummary {
+    /** The run this summarises. */
+    readonly runId: string;
+    /** Organisation it belongs to. */
+    readonly orgId: string;
+    /** Target it ran against. */
+    readonly targetId: string;
+    /** What kind of run it was. */
+    readonly kind: RunKind;
+    /** What set it going. */
+    readonly trigger: RunTrigger;
+    /** Engines that took part. */
+    readonly engines: readonly string[];
+    /** What the run exercised. */
+    readonly coverage: Coverage;
+    /** How long it took. */
+    readonly durationMs: number;
+    /** Issues opened for the first time by this run. */
+    readonly new: SeverityCounts;
+    /** Issues already open that this run saw again. */
+    readonly stillOpen: SeverityCounts;
+    /** Issues this run resolved. */
+    readonly resolved: SeverityCounts;
+    /** Issues that were resolved and that this run found again. */
+    readonly regressed: SeverityCounts;
+    /**
+     * Issues currently suppressed.
+     *
+     * Reported separately and **never folded into the other counts**: an ignored
+     * issue is excluded from metrics but never from the suppressed appendix
+     * (invariant 7).
+     */
+    readonly ignored: SeverityCounts;
+    /**
+     * Exposure at the end of this run.
+     *
+     * `Σ over open issues of severityWeight × min(daysOpen, 90)`. Simple,
+     * explainable and monotone — it can only fall by fixing things or by time not
+     * passing.
+     */
+    readonly exposureScore: number;
+    /** When the summary was computed. */
+    readonly createdAt: Date;
+}
+//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG,KAAK,GAAG,KAAK,GAAG,WAAW,GAAG,KAAK,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAElC,qDAAqD;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEnC,8BAA8B;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,GAAG;IAClB,iBAAiB;IACjB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,6BAA6B;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAEvB,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAE7B,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAEjC,uBAAuB;IACvB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IAEzB,wBAAwB;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,6BAA6B;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAEvB,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAE7B,8BAA8B;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAEpC,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B,wBAAwB;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,oDAAoD;IACpD,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAE7B,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IAEnC,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAElC,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IAEnC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAEjC;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B,qCAAqC;IACrC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;CAC1B"}

package/dist/run.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":""}