@ohos-ports/nx 23.2.0-beta.0 → 23.2.1-beta.0

package/dist/src/tasks-runner/life-cycles/performance-life-cycle.js

@@ -1,193 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PerformanceLifeCycle = void 0;
-exports.getPerformanceSummaryPayload = getPerformanceSummaryPayload;
-exports.getPerformanceReport = getPerformanceReport;
-exports.flushPerformanceReport = flushPerformanceReport;
-const node_fs_1 = require("node:fs");
-const performance_report_1 = require("./performance-report");
-const is_tui_enabled_1 = require("../is-tui-enabled");
-const performance_analysis_1 = require("./performance-analysis");
-/**
- * Measures how much wall-clock a run loses to parallelism contention versus its
- * critical-path floor, and reports it at the end of a run. Added on every run by
- * `constructLifeCycles`, but only emitted where the report is flushed (the CLI
- * `invokeTasksRunner` path) — the programmatic `init-tasks-runner` path collects
- * timings but never displays them.
- *
- * overhead = runDuration − criticalPathDuration, split by CAUSE off the occupancy
- * timeline: slot-queued time (recoverable by parallelism / machines) versus
- * coordinator time (hashing, scheduling, continuous-dep waits).
- *
- * Scope: discrete tasks only. Continuous tasks (no end time) are excluded; a
- * discrete task's wait for a continuous dependency to start is eligibility, not
- * contention.
- */
-class PerformanceLifeCycle {
-    constructor(taskGraph, options = {}) {
-        this.taskGraph = taskGraph;
-        this.options = options;
-        this.timings = new Map();
-        /** taskId → terminal status (cache hit vs ran), for the cache summary. */
-        this.statuses = new Map();
-        /** taskId → other tasks in its batch (batches run sequentially). */
-        this.batchSiblings = new Map();
-        /** Resolved `--parallel`, set by the runner via {@link startCommand}'s second arg once the thread pool is sized. */
-        this.parallel = 1;
-        activePerformanceLifeCycle = this;
-    }
-    // === Lifecycle hooks (called by the orchestrator as the run progresses) ===
-    /**
-     * The runner passes the resolved `--parallel` (getThreadPoolSize's `discrete`) as the
-     * second arg; the first (thread count) is for the TUI and ignored here.
-     */
-    startCommand(_threadCount, parallel) {
-        if (parallel != null) {
-            this.parallel = parallel;
-        }
-    }
-    registerRunningBatch(_batchId, batchInfo) {
-        for (const id of batchInfo.taskIds) {
-            this.batchSiblings.set(id, batchInfo.taskIds.filter((other) => other !== id));
-        }
-    }
-    endTasks(taskResults) {
-        // Called incrementally (per group/batch); accumulate so the last call sees every timing.
-        for (const { task, status } of taskResults) {
-            const entry = this.entry(task.id);
-            // `!= null`, not truthiness: synthetic/relative timelines can legitimately start at 0.
-            if (task.startTime != null) {
-                entry.startTime = task.startTime;
-            }
-            if (task.endTime != null) {
-                entry.endTime = task.endTime;
-            }
-            if (status != null) {
-                this.statuses.set(task.id, status);
-            }
-        }
-    }
-    entry(taskId) {
-        let entry = this.timings.get(taskId);
-        if (!entry) {
-            entry = { continuous: this.taskGraph.tasks[taskId]?.continuous ?? false };
-            this.timings.set(taskId, entry);
-        }
-        return entry;
-    }
-    /** Analyze the collected timings into a structured summary, or `null` when no discrete task timings were recorded. */
-    getSummary() {
-        return new performance_analysis_1.PerformanceAnalysis(this.timings, this.statuses, this.taskGraph, this.batchSiblings, this.parallel, this.options).summary();
-    }
-}
-exports.PerformanceLifeCycle = PerformanceLifeCycle;
-/** The most recently constructed performance lifecycle, read after the run. Cleared once consumed. */
-let activePerformanceLifeCycle = null;
-/**
- * Structured report for the TUI's exit-countdown popup, or null when nothing to
- * show. Clears the active lifecycle so the popup owns the report and a later terminal
- * flush can't re-print it. Best-effort: a throw degrades to null.
- */
-function getPerformanceSummaryPayload() {
-    const lifeCycle = activePerformanceLifeCycle;
-    if (!lifeCycle) {
-        return null;
-    }
-    try {
-        const summary = lifeCycle.getSummary();
-        if (!summary) {
-            return null;
-        }
-        activePerformanceLifeCycle = null;
-        return (0, performance_report_1.buildExitSummaryPayload)(summary);
-    }
-    catch (e) {
-        // Best-effort: the report must never break the run. Surface the cause only under
-        // verbose logging so a missing report stays debuggable.
-        if (process.env.NX_VERBOSE_LOGGING === 'true') {
-            console.error(e);
-        }
-        return null;
-    }
-}
-/**
- * The performance report payload for `endCommand`'s TUI exit popup, or undefined when the
- * report should instead be flushed to the terminal — non-TUI runs, or a single task (the
- * complement of run-command's flush gate). Reading it consumes the report so the flush
- * won't reprint it.
- */
-function getPerformanceReport(taskCount) {
-    if (!(0, is_tui_enabled_1.isTuiEnabled)() || taskCount <= 1) {
-        return undefined;
-    }
-    return getPerformanceSummaryPayload() ?? undefined;
-}
-/**
- * Print the performance report (if enabled) after the run summary. Called once the
- * terminal is restored, so it appears in every output mode including the TUI.
- */
-function flushPerformanceReport() {
-    const lifeCycle = activePerformanceLifeCycle;
-    activePerformanceLifeCycle = null;
-    if (!lifeCycle) {
-        return;
-    }
-    // Cosmetic report; a throw (e.g. EPIPE to a closed pipe) must never mask the
-    // real task error or fail an otherwise successful run.
-    try {
-        const summary = lifeCycle.getSummary();
-        if (!summary) {
-            return;
-        }
-        // restore_terminal cooks the terminal back post-TUI, so console.log's plain \n
-        // renders fine; it also supplies the single trailing newline formatReport omits.
-        console.log((0, performance_report_1.formatReport)(summary));
-        // In GitHub Actions, also append the report to the job summary page — the same stats
-        // as above, led by the run's outcome (a failed-tasks list, or a success line).
-        // Independent of the console.log above so neither masks the other.
-        writePerformanceReportToGitHubActions(summary);
-    }
-    catch (e) {
-        // Best-effort report; never let it affect the run's exit behavior. Surface the
-        // cause only under verbose logging.
-        if (process.env.NX_VERBOSE_LOGGING === 'true') {
-            console.error(e);
-        }
-    }
-}
-/**
- * Append the performance report to the GitHub Actions job summary page when running in
- * Actions (`$GITHUB_STEP_SUMMARY` is set there and nowhere else). No-op otherwise. The
- * Markdown is rendered below the guard, so non-CI runs don't pay to format a report
- * nothing reads. Best-effort: a write failure must never affect the run.
- *
- * Skipped for a nested run (one nx command invoked by another nx task's command), so only
- * the outermost run writes to the summary. Nx sets `NX_TASK_TARGET_PROJECT` on every task's
- * environment, which a nested nx inherits; its absence marks the top-level invocation (the
- * same "NX is already running" signal `nx exec` uses).
- */
-function writePerformanceReportToGitHubActions(summary) {
-    const summaryPath = process.env.GITHUB_STEP_SUMMARY;
-    if (process.env.GITHUB_ACTIONS !== 'true' ||
-        !summaryPath ||
-        process.env.NX_TASK_TARGET_PROJECT) {
-        return;
-    }
-    try {
-        const report = (0, performance_report_1.formatReportMarkdown)(summary, currentNxCommand());
-        (0, node_fs_1.appendFileSync)(summaryPath, `${report}\n`);
-    }
-    catch (e) {
-        if (process.env.NX_VERBOSE_LOGGING === 'true') {
-            console.error(e);
-        }
-    }
-}
-/**
- * The nx command as typed — everything after the nx bin (`process.argv[0]` is node,
- * `[1]` is the bin). Only read on the CLI flush path, where argv is always the real nx
- * invocation, so it identifies the run in the summary heading.
- */
-function currentNxCommand() {
-    return process.argv.slice(2).join(' ').trim();
-}

package/dist/src/tasks-runner/life-cycles/performance-report.d.ts

@@ -1,77 +0,0 @@
-import type { PerformanceSummaryPayload } from '../../native';
-import type { NxJsonConfiguration } from '../../config/nx-json';
-import type { PerformanceSummary, TaskDurationRow } from './performance-analysis';
-/**
- * Point the remote-cache CTA at a short Nx Cloud onboarding URL for a
- * disconnected GitHub workspace - the VCS flow where Cloud opens the nx.json PR.
- * Non-GitHub remotes keep the get-started link (handles every provider) and skip
- * the network entirely. Runs in CI too - terminal + job summary.
- *
- * Best-effort: the get-started link stays on failure/timeout. Fired at run start;
- * the CTA needs a >30s run (MIN_RECOMMENDATION_RUN_DURATION), so the fetch
- * always resolves first.
- */
-export declare function prefetchRemoteCacheOnboardingUrl(nxJson: NxJsonConfiguration): Promise<void>;
-/**
- * A recommendation built from structured parts so the link text comes from the link
- * definition (not a substring scanned out of the assembled report). A part is literal
- * text, a {@link RecLink}, or a {@link RecTaskRows}, projected to each output string by
- * {@link renderRecommendation}.
- *
- * String parts must be single-line — multi-line content needs its own structured part (as
- * {@link RecTaskRows} is). TS can't enforce this: `string` is already a handled member, so
- * a multi-line one compiles and then breaks the Markdown nested list.
- */
-type RecPart = string | RecLink | RecTaskRows;
-export type Recommendation = RecPart[];
-/**
- * A docs link inside a recommendation: a sentence is the visible text and the whole of
- * it links to the utm-tagged URL. With OSC 8 the phrase is a hyperlink; without it the
- * tagged URL is appended as ` → <url>`. The payload string is URL-less — the Rust popup
- * re-links the phrase from {@link PerformanceSummaryPayload.links}.
- */
-interface RecLink {
-    visible: string;
-    href: string;
-}
-/**
- * The critical path's longest tasks as data, so each renderer formats them natively:
- * the terminal and payload as space-aligned columns, Markdown as a nested list
- * (HTML collapses space runs, so aligned columns don't survive rendering there).
- */
-type RecTaskRows = TaskDurationRow[];
-/**
- * The recommendation string the napi payload ships and the Rust popup matches against.
- * Links are URL-less (the popup re-links them from {@link PerformanceSummaryPayload.links}).
- */
-export declare function recommendationToPayloadString(rec: Recommendation): string;
-/** Below this run duration (ms), the run is already fast — recommend nothing. */
-export declare const MIN_RECOMMENDATION_RUN_DURATION = 30000;
-/** Below this (ms) overhead is noise, not worth a recommendation. */
-export declare const MEANINGFUL_OVERHEAD = 1000;
-/**
- * The recommendations the report shows, in display order: every candidate in
- * {@link RECOMMENDATIONS} whose criteria apply to this run. Shared by the terminal report,
- * the GitHub-summary Markdown, and the TUI payload.
- */
-export declare function buildRecommendations(s: PerformanceSummary): Recommendation[];
-/** The full performance report as a terminal string (the TUI popup renders natively from {@link buildExitSummaryPayload} instead). */
-export declare function formatReport(s: PerformanceSummary): string;
-/**
- * The performance report as GitHub-flavored Markdown for the Actions job summary
- * (`$GITHUB_STEP_SUMMARY`). Mirrors {@link formatReport}'s content — the same stats and
- * recommendations — and, when the run had failures, lists them above the stats. Links
- * render as Markdown links rather than OSC 8 hyperlinks.
- *
- * `command` (the nx command, e.g. `run-many -t build`) is appended to the heading so
- * stacked reports from multiple nx commands in one job summary stay distinguishable.
- */
-export declare function formatReportMarkdown(s: PerformanceSummary, command: string): string;
-/**
- * Build the payload for the TUI's exit-countdown popup, which renders natively in Rust
- * (the terminal path uses {@link formatReport}). The shape is the generated napi
- * {@link PerformanceSummaryPayload}, imported not re-declared so the producer and the
- * Rust struct can't drift.
- */
-export declare function buildExitSummaryPayload(s: PerformanceSummary): PerformanceSummaryPayload;
-export {};