@monocle.sh/vite-plugin 0.2.0 → 0.3.0

package/README.md

@@ -70,14 +70,28 @@ unless it is one of the placeholders above.
 
 ## How it works
 
-The plugin prepends `globalThis.__MONOCLE_BUILD__ = {…}` to each of your modules
-that imports `@monocle.sh/browser-sdk`. The SDK reads it in `initMonocle()`.
-
-This targets application code rather than relying on `define`, which Vite does
-not apply to pre-bundled dependencies. It needs no inline `<script>`, so it
-works with SSR frameworks that don't use `index.html` and with strict CSPs.
-During SSR, the global is also set on the server, where the Browser SDK stays
-inactive.
+When every entry of `vite build` is an HTML page (the default `index.html`
+setup), the plugin writes the release into the page as
+`<meta name="monocle-build" content="{…}">`, which the SDK reads in
+`initMonocle()`. Your JavaScript chunks never contain the release, so two builds
+of the same code produce identical chunks, file names and debug IDs: a deploy
+only uploads the source maps of the chunks that changed. A `<meta>` tag is not
+affected by Content Security Policies. This needs `@monocle.sh/browser-sdk`
+0.13.0 or later; with an older SDK the plugin warns and falls back to the
+bundle.
+
+Otherwise (dev server, SSR, library builds, frameworks rendering the HTML
+themselves), the plugin prepends `globalThis.__MONOCLE_BUILD__ = {…}` to each of
+your modules that imports `@monocle.sh/browser-sdk`. This targets application
+code rather than relying on `define`, which Vite does not apply to pre-bundled
+dependencies. During SSR, the global is also set on the server, where the
+Browser SDK stays inactive.
+
+Vite and Rolldown also put the hashed file name of every imported chunk into
+the importing chunk, so changing one chunk renames the chunks that import it,
+up to the entry. To keep those unchanged too, enable Vite's
+[`build.chunkImportMap`](https://vite.dev/config/build-options) (Vite 8,
+experimental).
 
 ## Source maps
 

package/dist/vite.d.mts

@@ -60,6 +60,7 @@ interface MonocleSourcemapsOptions {
  * Translate Vite hooks to the bundler-agnostic Monocle build.
  */
 declare class MonocleVitePlugin {
+  #private;
   static create(options?: MonoclePluginOptions): Plugin;
 }
 /**

package/dist/vite.mjs

@@ -1,8 +1,348 @@
-import { dirname, join, resolve } from "node:path";
-import { ServiceVersionDetector } from "@monocle.sh/otel-utils/service-version";
+import { createRequire } from "node:module";
+import { dirname, join, resolve, sep } from "node:path";
+import { readFileSync, realpathSync, statSync } from "node:fs";
 import MagicString from "magic-string";
 import { rm } from "node:fs/promises";
 import { injectDebugIds, uploadSourcemaps } from "@monocle.sh/sourcemaps";
+//#region src/core/browser_sdk.ts
+/**
+* What the Browser SDK the application resolves can read.
+*/
+var BrowserSdk = class {
+	/**
+	* First `@monocle.sh/browser-sdk` reading `<meta name="monocle-build">`.
+	*/
+	static pageReleaseSince = "0.13.0";
+	static #atLeast(version, minimum) {
+		const parse = (value) => value.split(/[-+]/)[0].split(".").map(Number);
+		const [actual, expected] = [parse(version), parse(minimum)];
+		for (let index = 0; index < 3; index++) {
+			const difference = (actual[index] ?? 0) - (expected[index] ?? 0);
+			if (Number.isNaN(difference)) return false;
+			if (difference !== 0) return difference > 0;
+		}
+		return true;
+	}
+	/**
+	* Where the installed SDK reads the release: `page` from the HTML, `bundle` only from the
+	* global, `missing` when the application does not resolve it, so nothing reads a page tag. A
+	* linked local copy (workspace) is assumed current; one that cannot be inspected (Yarn PnP
+	* archives…) reads the bundle.
+	*/
+	static releaseSource(root) {
+		let path;
+		try {
+			path = createRequire(join(root, "package.json")).resolve("@monocle.sh/browser-sdk/package.json");
+		} catch {
+			return "missing";
+		}
+		try {
+			if (!realpathSync(path).includes(`${sep}node_modules${sep}`)) return "page";
+			const { version } = JSON.parse(readFileSync(path, "utf8"));
+			return typeof version === "string" && this.#atLeast(version, this.pageReleaseSince) ? "page" : "bundle";
+		} catch {
+			return "bundle";
+		}
+	}
+};
+//#endregion
+//#region ../otel-utils/dist/service-version.mjs
+var ServiceVersionDetector = class {
+	/**
+	* Ordered platform revision variables, before CI and the local checkout.
+	*/
+	static #platformSources = [
+		["VERCEL_GIT_COMMIT_SHA", "platform:vercel"],
+		["RENDER_GIT_COMMIT", "platform:render"],
+		["RAILWAY_GIT_COMMIT_SHA", "platform:railway"],
+		["HEROKU_BUILD_COMMIT", "platform:heroku"],
+		["HEROKU_SLUG_COMMIT", "platform:heroku"],
+		["SOURCE_COMMIT", "platform:coolify"],
+		["GIT_REV", "platform:dokku"],
+		["K_REVISION", "platform:cloud-run"]
+	];
+	/**
+	* CI detection adapted from env-ci 11.2.0 (MIT): https://github.com/semantic-release/env-ci
+	* See LICENSE.env-ci. Git subprocess and Java properties adapters are excluded.
+	*/
+	static #ciSources = {
+		github: {
+			detect: (env) => Boolean(env.GITHUB_ACTIONS),
+			revisions: ["GITHUB_SHA"],
+			repository: (env) => this.#repositoryFromSlug({
+				host: env.GITHUB_SERVER_URL,
+				slug: env.GITHUB_REPOSITORY
+			})
+		},
+		gitlab: {
+			detect: (env) => Boolean(env.GITLAB_CI),
+			revisions: ["CI_COMMIT_SHA"],
+			repository: (env) => this.#normalizeRepositoryUrl(env.CI_PROJECT_URL) ?? this.#repositoryFromSlug({
+				host: env.CI_SERVER_URL,
+				slug: env.CI_PROJECT_PATH
+			})
+		},
+		woodpecker: {
+			detect: (env) => env.CI === "woodpecker",
+			revisions: ["CI_COMMIT_SHA"],
+			repository: (env) => env.CI_REPO_CLONE_URL
+		},
+		circleci: {
+			detect: (env) => Boolean(env.CIRCLECI),
+			revisions: ["CIRCLE_SHA1"],
+			repository: (env) => env.CIRCLE_REPOSITORY_URL
+		},
+		bitbucket: {
+			detect: (env) => Boolean(env.BITBUCKET_BUILD_NUMBER),
+			revisions: ["BITBUCKET_COMMIT"],
+			repository: (env) => this.#repositoryFromSlug({
+				host: "https://bitbucket.org",
+				slug: env.BITBUCKET_REPO_FULL_NAME
+			})
+		},
+		buildkite: {
+			detect: (env) => Boolean(env.BUILDKITE),
+			revisions: ["BUILDKITE_COMMIT"],
+			repository: (env) => env.BUILDKITE_REPO
+		},
+		jenkins: {
+			detect: (env) => Boolean(env.JENKINS_URL),
+			revisions: ["ghprbActualCommit", "GIT_COMMIT"],
+			repository: (env) => env.GIT_URL
+		},
+		"azure-pipelines": {
+			detect: (env) => Boolean(env.BUILD_BUILDURI),
+			revisions: ["BUILD_SOURCEVERSION"],
+			repository: (env) => env.BUILD_REPOSITORY_URI
+		},
+		travis: {
+			detect: (env) => Boolean(env.TRAVIS),
+			revisions: ["TRAVIS_COMMIT"]
+		},
+		netlify: {
+			detect: (env) => env.NETLIFY === "true",
+			revisions: ["COMMIT_REF"],
+			repository: (env) => env.REPOSITORY_URL
+		},
+		"cloudflare-pages": {
+			detect: (env) => env.CF_PAGES === "1",
+			revisions: ["CF_PAGES_COMMIT_SHA"]
+		},
+		drone: {
+			detect: (env) => Boolean(env.DRONE),
+			revisions: ["DRONE_COMMIT_SHA"],
+			repository: (env) => env.DRONE_REMOTE_URL
+		},
+		bitrise: {
+			detect: (env) => Boolean(env.BITRISE_IO),
+			revisions: ["BITRISE_GIT_COMMIT"]
+		},
+		appveyor: {
+			detect: (env) => Boolean(env.APPVEYOR),
+			revisions: ["APPVEYOR_REPO_COMMIT"]
+		},
+		semaphore: {
+			detect: (env) => Boolean(env.SEMAPHORE),
+			revisions: ["SEMAPHORE_GIT_SHA"]
+		},
+		codefresh: {
+			detect: (env) => Boolean(env.CF_BUILD_ID),
+			revisions: ["CF_REVISION"]
+		},
+		buddy: {
+			detect: (env) => Boolean(env.BUDDY_WORKSPACE_ID),
+			revisions: ["BUDDY_EXECUTION_REVISION"]
+		},
+		cirrus: {
+			detect: (env) => Boolean(env.CIRRUS_CI),
+			revisions: ["CIRRUS_CHANGE_IN_REPO"]
+		},
+		vela: {
+			detect: (env) => Boolean(env.VELA),
+			revisions: ["VELA_BUILD_COMMIT"]
+		},
+		screwdriver: {
+			detect: (env) => Boolean(env.SCREWDRIVER),
+			revisions: ["SD_BUILD_SHA"]
+		},
+		bamboo: {
+			detect: (env) => Boolean(env.bamboo_agentId),
+			revisions: ["bamboo_planRepository_1_revision"]
+		},
+		codeship: {
+			detect: (env) => env.CI_NAME === "codeship",
+			revisions: ["CI_COMMIT_ID"]
+		},
+		"jetbrains-space": {
+			detect: (env) => Boolean(env.JB_SPACE_EXECUTION_NUMBER),
+			revisions: ["JB_SPACE_GIT_REVISION"]
+		},
+		scrutinizer: {
+			detect: (env) => Boolean(env.SCRUTINIZER),
+			revisions: ["SCRUTINIZER_SHA1"]
+		}
+	};
+	static #value(value) {
+		const trimmed = value?.trim();
+		if (!trimmed || [
+			"0.0.0",
+			"0.0.1",
+			"1.0.0",
+			"unknown",
+			"dev",
+			"latest"
+		].includes(trimmed.toLowerCase())) return;
+		return trimmed;
+	}
+	static #sha(value) {
+		if (value && /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i.test(value)) return value;
+	}
+	static #read(path) {
+		try {
+			return readFileSync(path, "utf8").trim();
+		} catch {
+			return;
+		}
+	}
+	static #gitDirectory(cwd) {
+		let directory = resolve(cwd);
+		while (true) {
+			const path = join(directory, ".git");
+			try {
+				if (statSync(path).isDirectory()) return path;
+				const target = this.#read(path)?.match(/^gitdir:\s*(.+)$/)?.[1];
+				return target ? resolve(directory, target) : void 0;
+			} catch {
+				const parent = dirname(directory);
+				if (parent === directory) return;
+				directory = parent;
+			}
+		}
+	}
+	static #gitRevision(cwd) {
+		const gitDirectory = this.#gitDirectory(cwd);
+		if (!gitDirectory) return;
+		const head = this.#read(join(gitDirectory, "HEAD"));
+		const detached = this.#sha(head);
+		if (detached) return detached;
+		const ref = head?.match(/^ref:\s*(refs\/[^\s]+)$/)?.[1];
+		if (!ref || ref.split("/").includes("..")) return;
+		const common = this.#read(join(gitDirectory, "commondir"));
+		const directories = common ? [gitDirectory, resolve(gitDirectory, common)] : [gitDirectory];
+		for (const directory of directories) {
+			const direct = this.#sha(this.#read(join(directory, ref)));
+			if (direct) return direct;
+			const packed = this.#read(join(directory, "packed-refs"));
+			for (const line of packed?.split("\n") ?? []) {
+				const [sha, name] = line.trim().split(/\s+/);
+				if (name === ref && this.#sha(sha)) return sha;
+			}
+		}
+	}
+	static #githubRevision(env) {
+		const fallback = this.#value(env.GITHUB_SHA);
+		if (env.GITHUB_EVENT_NAME !== "pull_request") return fallback;
+		if (!env.GITHUB_EVENT_PATH) return fallback;
+		try {
+			const sha = JSON.parse(this.#read(env.GITHUB_EVENT_PATH) ?? "")?.pull_request?.head?.sha;
+			return typeof sha === "string" ? this.#sha(sha) ?? fallback : fallback;
+		} catch {
+			return fallback;
+		}
+	}
+	static #repositoryFromSlug(options) {
+		const host = this.#normalizeRepositoryUrl(options.host);
+		const slug = this.#value(options.slug);
+		if (!host || !slug) return;
+		return `${host}/${slug.replace(/^\/+/, "")}`;
+	}
+	static #vercelRepository(env) {
+		const hosts = new Map([
+			["github", "https://github.com"],
+			["gitlab", "https://gitlab.com"],
+			["bitbucket", "https://bitbucket.org"]
+		]);
+		const owner = this.#value(env.VERCEL_GIT_REPO_OWNER);
+		const slug = this.#value(env.VERCEL_GIT_REPO_SLUG);
+		if (!owner || !slug) return;
+		return this.#repositoryFromSlug({
+			host: hosts.get(env.VERCEL_GIT_PROVIDER ?? ""),
+			slug: `${owner}/${slug}`
+		});
+	}
+	static #repositoryUrl(env) {
+		return [
+			env.VERCEL || env.NOW_GITHUB_DEPLOYMENT ? this.#vercelRepository(env) : void 0,
+			env.RENDER ? env.RENDER_GIT_REPO_URL : void 0,
+			env.RAILWAY_PROJECT_ID ? env.RAILWAY_GIT_REPO_URL : void 0,
+			...Object.values(this.#ciSources).filter((provider) => provider.detect(env)).map((provider) => provider.repository?.(env))
+		].map((candidate) => this.#normalizeRepositoryUrl(candidate)).find(Boolean);
+	}
+	static #normalizeRepositoryUrl(candidate) {
+		const value = this.#value(candidate);
+		if (!value) return;
+		try {
+			const url = new URL(value.replace(/^git@([^:/]+):/, "ssh://git@$1/"));
+			if (!url.host || ![
+				"https:",
+				"http:",
+				"ssh:"
+			].includes(url.protocol)) return;
+			const path = url.pathname.replace(/\/+$/, "").replace(/\.git$/, "").replace(/\/+$/, "");
+			return `https://${url.protocol === "ssh:" ? url.hostname : url.host}${path}`;
+		} catch {
+			return;
+		}
+	}
+	static detect(options = {}) {
+		const env = options.env ?? process.env;
+		const candidates = [
+			{
+				version: this.#value(options.serviceVersion),
+				source: "config"
+			},
+			{
+				version: this.#value(env.MONOCLE_VERSION),
+				source: "env"
+			},
+			{
+				version: this.#value(env.APP_VERSION),
+				source: "env"
+			},
+			...this.#platformSources.map(([key, source]) => ({
+				version: this.#value(env[key]),
+				source
+			})),
+			...Object.entries(this.#ciSources).filter(([, provider]) => provider.detect(env)).flatMap(([name, provider]) => provider.revisions.map((key) => ({
+				version: name === "github" ? this.#githubRevision(env) : this.#value(env[key]),
+				source: `ci:${name}`
+			})))
+		];
+		const selected = candidates.find(({ version }) => version);
+		const knownSha = candidates.map(({ version }) => this.#sha(version)).find(Boolean);
+		const gitSha = knownSha ? void 0 : this.#gitRevision(options.cwd ?? process.cwd());
+		return {
+			version: selected?.version ?? gitSha,
+			source: selected?.source ?? (gitSha ? "git" : "none"),
+			commitSha: knownSha ?? gitSha,
+			repositoryUrl: this.#repositoryUrl(env),
+			deploymentId: [
+				env.RAILWAY_DEPLOYMENT_ID,
+				env.VERCEL_DEPLOYMENT_ID,
+				env.RENDER_DEPLOY_ID
+			].map((value) => this.#value(value)).find(Boolean)
+		};
+	}
+	static resourceAttributes(result) {
+		const attributes = { "monocle.service.version.source": result.source };
+		if (result.version) attributes["service.version"] = result.version;
+		if (result.commitSha) attributes["vcs.ref.head.revision"] = result.commitSha;
+		if (result.repositoryUrl) attributes["vcs.repository.url.full"] = result.repositoryUrl;
+		if (result.deploymentId) attributes["deployment.id"] = result.deploymentId;
+		return attributes;
+	}
+};
+//#endregion
 //#region src/core/build_metadata.ts
 /**
 * Resolve the release with the same priority chain as the server agents, without spawning Git
@@ -30,7 +370,10 @@ var BuildMetadataResolver = class {
 //#endregion
 //#region src/core/release_injection.ts
 /**
-* Prepend a global assignment to every module importing the Browser SDK.
+* Expose the release to the Browser SDK. Builds with an HTML page write it into a
+* `<meta name="monocle-build">` tag: JavaScript chunks then stay byte-identical between builds of
+* the same code, so their hashes and debug IDs do too. Other builds (SSR, library, dev server)
+* prepend a global assignment to every module importing the Browser SDK.
 *
 * Import declarations are hoisted, so the SDK module is evaluated first, but it only reads the
 * global when `initMonocle()` runs, which always happens after the importing module starts
@@ -42,6 +385,10 @@ var ReleaseInjection = class {
 	* Read by `@monocle.sh/browser-sdk`. Keep both sides in sync.
 	*/
 	static globalName = "__MONOCLE_BUILD__";
+	/**
+	* Name of the `<meta>` tag the Browser SDK reads when the global is not set.
+	*/
+	static metaName = "monocle-build";
 	static sdkImport = /["']@monocle\.sh\/browser-sdk(?:\/[^"'\s]*)?["']/;
 	/**
 	* Stylesheets, markup and data can mention the package without being JavaScript. Markup is
@@ -56,6 +403,15 @@ var ReleaseInjection = class {
 	static snippet(metadata) {
 		return `globalThis.${this.globalName}=${JSON.stringify(metadata)};`;
 	}
+	/**
+	* URI-encoded JSON: without quotes, it survives Vite 5, which does not escape attributes.
+	*/
+	static meta(metadata) {
+		return {
+			name: this.metaName,
+			content: encodeURIComponent(JSON.stringify(metadata))
+		};
+	}
 	static shouldInject(options) {
 		return !this.nonScriptIds.test(options.id) && this.sdkImport.test(options.code);
 	}
@@ -112,6 +468,13 @@ var MonocleBuild = class {
 		this.#log(value);
 		return value;
 	}
+	/**
+	* The release for the `<meta>` tag of an HTML page, when injection is on.
+	*/
+	pageMetadata() {
+		if (!this.enabled || this.#options.options.inject === false) return;
+		return this.resolve();
+	}
 	transform(options) {
 		if (!this.enabled || this.#options.options.inject === false) return;
 		if (!ReleaseInjection.shouldInject(options)) return;
@@ -232,12 +595,47 @@ var SourcemapsStep = class {
 /**
 * Translate Vite hooks to the bundler-agnostic Monocle build.
 */
-var MonocleVitePlugin = class {
+var MonocleVitePlugin = class MonocleVitePlugin {
+	/**
+	* Client builds whose every entry is an HTML page, the only ones where the release can live
+	* in the page instead of the chunks. Vite builds `index.html` without an explicit input.
+	* Frameworks rendering the HTML themselves set another input, per environment since Vite 6.
+	*/
+	static #htmlBuild(config) {
+		const { build } = config;
+		if (config.consumer === "server" || build.ssr || build.lib) return false;
+		const input = (build.rolldownOptions ?? build.rollupOptions)?.input;
+		if (input === void 0) return true;
+		const entries = typeof input === "string" ? [input] : Object.values(input);
+		return entries.length > 0 && entries.every((entry) => /\.html?$/.test(entry));
+	}
 	static create(options = {}) {
 		const plugin = { name: "@monocle.sh/vite-plugin" };
 		if (options.enabled === false) return plugin;
 		let build;
 		let resolved;
+		let sdkReadsPage;
+		/**
+		* Whether the release can go into the HTML pages of this build: a build with injection on,
+		* for an installed Browser SDK reading the page. Detected once, with a warning for older
+		* SDKs. Without the SDK, nothing reads a page tag: none is written.
+		*/
+		function pageSupported() {
+			if (!resolved || resolved.command !== "build" || options.inject === false) return false;
+			if (sdkReadsPage === void 0) {
+				const source = BrowserSdk.releaseSource(resolved.root);
+				sdkReadsPage = source === "page";
+				if (source === "bundle") resolved.logger.warn(`[monocle] @monocle.sh/browser-sdk < ${BrowserSdk.pageReleaseSince} reads the release from the bundle only, so every build changes all chunk hashes. Upgrade it to keep unchanged chunks identical.`);
+			}
+			return sdkReadsPage;
+		}
+		/**
+		* Whether modules of this environment leave the release to its HTML page. Vite 5 has no
+		* environments: the top-level configuration applies.
+		*/
+		function releaseInPage(environment) {
+			return !!resolved && MonocleVitePlugin.#htmlBuild(environment?.config ?? resolved) && pageSupported();
+		}
 		const sourcemaps = new SourcemapsStep({
 			options,
 			env: process.env
@@ -279,6 +677,7 @@ var MonocleVitePlugin = class {
 					code: ReleaseInjection.sdkImport
 				},
 				handler(code, id) {
+					if (releaseInPage(this.environment)) return;
 					return build?.transform({
 						code,
 						id
@@ -286,6 +685,20 @@ var MonocleVitePlugin = class {
 				}
 			},
 			/**
+			* Builds only call it for HTML entries. When some modules still got the global (mixed
+			* HTML and script entries), the SDK prefers the global, so the tag is harmless.
+			*/
+			transformIndexHtml() {
+				if (!pageSupported()) return;
+				const metadata = build?.pageMetadata();
+				if (!metadata) return;
+				return [{
+					tag: "meta",
+					attrs: ReleaseInjection.meta(metadata),
+					injectTo: "head-prepend"
+				}];
+			},
+			/**
 			* Sequential and last, so compression or copy plugins see the injected files.
 			*/
 			writeBundle: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monocle.sh/vite-plugin",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Vite plugin that injects your release into the Monocle Browser SDK and uploads source maps at build time",
   "keywords": [
     "monocle",
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "magic-string": "^0.30.21",
-    "@monocle.sh/sourcemaps": "^0.1.0"
+    "@monocle.sh/sourcemaps": "^0.2.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.63.0",
@@ -49,7 +49,7 @@
     "tsdown": "^0.21.10",
     "vite": "^8.3.4",
     "vue": "^3.5.44",
-    "@monocle.sh/browser-sdk": "0.12.0",
+    "@monocle.sh/browser-sdk": "0.13.0",
     "@monocle.sh/otel-utils": "1.9.0"
   },
   "peerDependencies": {