@master/css-compiler 0.0.0-site.1793659883.g69c9aebcf628

package/dist/stylesheet/output-map.js

@@ -0,0 +1,222 @@
+import { sourceMapBase, sourceMapURL } from "./source-map-url.js";
+import { SourceMap } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
+// src/stylesheet/output-map.ts
+const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function vlq(value) {
+	let encoded = "", bits = value < 0 ? -value * 2 + 1 : value * 2;
+	do {
+		const digit = bits % 32;
+		bits = Math.floor(bits / 32);
+		encoded += alphabet[digit + (bits ? 32 : 0)];
+	} while (bits);
+	return encoded;
+}
+function positions(source) {
+	const starts = [0];
+	for (const match of source.matchAll(/\r\n?|\n/g)) starts.push(match.index + match[0].length);
+	return (offset) => {
+		let low = 0, high = starts.length;
+		while (low < high) {
+			const mid = low + high >>> 1;
+			if (starts[mid] <= offset) low = mid + 1;
+			else high = mid;
+		}
+		const line = Math.max(0, low - 1);
+		return {
+			line,
+			column: offset - starts[line]
+		};
+	};
+}
+/** Chain only compiler-provided offsets and host maps. No CSS parsing or matching. */
+function origins(context) {
+	let payload, inputMap, invalidMap = false;
+	try {
+		payload = context.sourceMap ? JSON.parse(context.sourceMap) : void 0;
+		inputMap = payload ? new SourceMap(payload) : void 0;
+	} catch {
+		payload = void 0;
+		invalidMap = true;
+	}
+	const indices = /* @__PURE__ */ new Map();
+	const locate = (content, offset) => {
+		let index = indices.get(content);
+		if (!index) {
+			index = positions(content);
+			indices.set(content, index);
+		}
+		return index(offset);
+	};
+	const preparedLines = context.source.split(/\r\n?|\n/);
+	const authoredLines = payload?.sourcesContent?.map((content) => content?.split(/\r\n?|\n/));
+	const sourceBase = sourceMapBase(context.file, payload?.sourceRoot);
+	return (reference) => {
+		let file = reference.file ?? context.compilationFile, offset = reference.range.start;
+		if (file === context.compilationFile && context.graph?.sourceMappings) {
+			const spans = context.graph.sourceMappings;
+			let low = 0, high = spans.length;
+			while (low < high) {
+				const mid = low + high >>> 1;
+				if (spans[mid].generatedStart <= offset) low = mid + 1;
+				else high = mid;
+			}
+			const span = spans[low - 1];
+			if (offset >= (span?.generatedEnd ?? 0)) return;
+			if (!span?.source.file) return;
+			file = span.source.file;
+			offset = span.source.range.start + offset - span.generatedStart;
+		}
+		const content = file === context.file ? context.source : context.graph?.sources[file];
+		const point = content !== void 0 ? locate(content, offset) : reference.loc ? {
+			line: reference.loc.start.line - 1,
+			column: reference.loc.start.column - 1
+		} : void 0;
+		if (!point) return;
+		if (file === context.file && inputMap && payload) {
+			const entry = inputMap.findEntry(point.line, point.column);
+			if (!("originalSource" in entry) || !entry.originalSource || entry.generatedLine !== point.line) return;
+			const originalContent = payload.sourcesContent?.[payload.sources.indexOf(entry.originalSource)] ?? null;
+			let column = entry.originalColumn;
+			const length = point.column - entry.generatedColumn;
+			const prepared = preparedLines[point.line];
+			const authored = authoredLines?.[payload.sources.indexOf(entry.originalSource)]?.[entry.originalLine];
+			if (length > 0 && prepared !== void 0 && authored !== void 0 && prepared.slice(entry.generatedColumn, point.column) === authored.slice(entry.originalColumn, entry.originalColumn + length)) column += length;
+			return {
+				source: sourceMapURL(entry.originalSource, sourceBase).href,
+				line: entry.originalLine,
+				column,
+				content: originalContent
+			};
+		}
+		return {
+			source: sourceMapURL(file, pathToFileURL(context.file)).href + (invalidMap && file === context.file ? "?master-css-preprocessed" : ""),
+			...point,
+			content: content ?? null
+		};
+	};
+}
+function serializeMap(code, points) {
+	const locate = positions(code);
+	const sources = [], sourcesContent = [], lines = [];
+	const offsets = /* @__PURE__ */ new Map();
+	for (const point of points) if (point.origin || !offsets.has(point.offset)) offsets.set(point.offset, point.origin);
+	let lastSource = 0, lastLine = 0, lastColumn = 0, generatedLine = -1, generatedColumn = 0;
+	for (const [offset, origin] of [...offsets].sort(([a], [b]) => a - b)) {
+		if (offset < 0 || offset > code.length) continue;
+		const point = locate(offset);
+		if (point.line !== generatedLine) {
+			generatedLine = point.line;
+			generatedColumn = 0;
+		}
+		while (lines.length <= point.line) lines.push([]);
+		const segment = [point.column - generatedColumn];
+		generatedColumn = point.column;
+		if (origin) {
+			let index = sources.indexOf(origin.source);
+			if (index === -1) {
+				index = sources.length;
+				sources.push(origin.source);
+				sourcesContent.push(origin.content);
+			}
+			segment.push(index - lastSource, origin.line - lastLine, origin.column - lastColumn);
+			lastSource = index;
+			lastLine = origin.line;
+			lastColumn = origin.column;
+		}
+		lines[point.line].push(segment.map(vlq).join(""));
+	}
+	return JSON.stringify({
+		version: 3,
+		sources,
+		sourcesContent,
+		names: [],
+		mappings: lines.map((line) => line.join(",")).join(";")
+	});
+}
+function stylesheetOutputMap(code, mappings, context, mappedLength = code.length) {
+	const origin = origins(context);
+	const points = mappings.flatMap((mapping) => [{
+		offset: mapping.generatedStart,
+		origin: origin(mapping.source)
+	}, ...mapping.generatedEnd === void 0 ? [] : [{ offset: mapping.generatedEnd }]]);
+	points.push({ offset: mappedLength });
+	return serializeMap(code, points);
+}
+/** The concatenation order is supplied by the owning compiler result. */
+function stylesheetOutputMappings(nativeCSS, native = [], generated = []) {
+	const shift = nativeCSS.length ? nativeCSS.length + 1 : 0;
+	return [...native, ...generated.map((mapping) => ({
+		...mapping,
+		generatedStart: mapping.generatedStart + shift,
+		generatedEnd: mapping.generatedEnd === void 0 ? void 0 : mapping.generatedEnd + shift
+	}))];
+}
+/** Exact graph copies also form the input map for structured lowering errors. */
+function stylesheetInputMap(code, context) {
+	const origin = origins(context), points = [];
+	for (const span of context.graph?.sourceMappings ?? []) {
+		const end = span.generatedEnd ?? span.generatedStart;
+		const offsets = [span.generatedStart, ...Array.from(code.slice(span.generatedStart, end).matchAll(/\r\n?|\n/g), (match) => span.generatedStart + match.index + match[0].length)];
+		for (const offset of offsets) if (offset < end) points.push({
+			offset,
+			origin: origin({
+				file: context.compilationFile,
+				range: {
+					start: offset,
+					end: offset
+				}
+			})
+		});
+		points.push({ offset: end });
+	}
+	return serializeMap(code, points);
+}
+/** Map validation to the same authoring segments as browser devtools. */
+function stylesheetValidationSource(css, source, sourceMap, mappings) {
+	if (!sourceMap) return {
+		css,
+		source,
+		mappings
+	};
+	let payload, map;
+	try {
+		payload = JSON.parse(sourceMap);
+		map = new SourceMap(payload);
+	} catch {
+		return {
+			css,
+			source
+		};
+	}
+	const locate = positions(css);
+	return {
+		css,
+		source,
+		locate(range) {
+			const start = locate(range.start), end = locate(range.end);
+			const entry = map.findEntry(start.line, start.column);
+			if (!("originalSource" in entry) || !entry.originalSource || entry.generatedLine !== start.line) return;
+			const url = sourceMapURL(entry.originalSource, sourceMapBase(source ?? "/", payload.sourceRoot));
+			const file = url.protocol === "file:" ? fileURLToPath(url) : url.href;
+			const original = payload.sourcesContent?.[payload.sources.indexOf(entry.originalSource)]?.split(/\r\n?|\n/)[entry.originalLine];
+			const generated = css.split(/\r\n?|\n/)[start.line];
+			const offset = start.column - entry.generatedColumn, length = end.column - entry.generatedColumn;
+			const exact = start.line === end.line && offset >= 0 && length >= offset && original !== void 0 && original.slice(entry.originalColumn, entry.originalColumn + length) === generated.slice(entry.generatedColumn, end.column);
+			return {
+				source: file,
+				range: {
+					start: {
+						line: entry.originalLine,
+						character: entry.originalColumn + (exact ? offset : 0)
+					},
+					end: {
+						line: entry.originalLine,
+						character: entry.originalColumn + (exact ? length : 0)
+					}
+				}
+			};
+		}
+	};
+}
+export { stylesheetInputMap, stylesheetOutputMap, stylesheetOutputMappings, stylesheetValidationSource };

package/dist/stylesheet/public.d.ts

@@ -0,0 +1,171 @@
+import { MasterCSSScanner } from "@master/css-tooling/scanner/node";
+import { MasterCSSManifest } from "@master/css-schema/manifest";
+import { MasterCSSCompileOptions, MasterCSSCompileResult } from "../index.js";
+import { CSSImportFileResolver, CSSImportFileResolver as MasterCSSStylesheetImportResolver, CSSImportSource as MasterCSSStylesheetImportSource } from "../node-imports.js";
+import { StylesheetDeliveryOptions, StylesheetDeliveryOptions as MasterCSSStylesheetDeliveryOptions, StylesheetResourceAsset, StylesheetResourceAsset as MasterCSSStylesheetResourceAsset } from "./delivery.js";
+import { MasterCSSEmittedGlobals } from "@master/css-schema/emitted-globals";
+import { PreparedStylesheetSource as MasterCSSPreparedStylesheet, SassModule, SassModule as MasterCSSSassCompiler, StylesheetPreparationOptions as MasterCSSStylesheetPreparationOptions } from "./types.js";
+import { StylesheetSourceContext } from "./source-context.js";
+import { prepareStylesheetSource as prepareStylesheet } from "./index.js";
+interface MasterCSSStylesheetCompileOptions extends MasterCSSCompileOptions, StylesheetSourceContext {
+  /** Absolute definition files applied before authored @reference and local definitions. Does not load their native CSS or scanning policy. */
+  readonly referenceFiles?: readonly string[];
+  readonly delivery?: StylesheetDeliveryOptions;
+  readonly baseManifest: MasterCSSManifest;
+  readonly projectDir?: string;
+  readonly loadSass?: (projectDir?: string) => SassModule;
+  readonly signal?: AbortSignal;
+}
+interface MasterCSSRenderedStylesheetCompileOptions extends MasterCSSStylesheetCompileOptions {
+  /** Globals already present outside this render; emit only additional resources. */
+  readonly emittedGlobals?: MasterCSSEmittedGlobals;
+}
+interface MasterCSSCompiledStylesheet extends MasterCSSCompileResult {
+  readonly entry?: string;
+  /** Delivery assets, including the entry. Each map describes its final CSS. */
+  readonly stylesheets?: readonly {
+    readonly id: string;
+    readonly href: string;
+    readonly css: string;
+    readonly sourceMap: string;
+  }[];
+  readonly resources?: readonly StylesheetResourceAsset[];
+  readonly manifest: MasterCSSManifest;
+  readonly emittedGlobals: Required<MasterCSSEmittedGlobals>;
+}
+interface MasterCSSStylesheetTransformResult {
+  /** Generated resources retain their original global selectors and conditions. */
+  readonly globalStylesheet?: Readonly<{
+    css: string;
+    sourceMap?: string;
+  }>;
+  readonly diagnostics: readonly import('@master/css-schema').MasterCSSDiagnostic[];
+  readonly sourceMap?: string;
+  /** Retained child stylesheets; delivery hosts must publish every returned asset. */
+  readonly stylesheets?: readonly {
+    readonly id: string;
+    readonly href: string;
+    readonly css: string;
+  }[];
+  readonly resources?: readonly StylesheetResourceAsset[];
+  readonly code: string;
+  readonly dependencies: readonly string[];
+  readonly transformed: boolean;
+  readonly compilation?: MasterCSSCompileResult;
+}
+interface MasterCSSStylesheetTransformOptions extends MasterCSSStylesheetCompileOptions {
+  /** Leave native CSS to its host when it needs no Master CSS resource expansion. */
+  readonly preserveUnchangedNativeCSS?: boolean;
+  /** Defaults to inline; separate returns globals outside code for scoped hosts. */
+  readonly generatedGlobals?: 'inline' | 'separate';
+  /** Also resolve resource usage in native CSS using the supplied context. */
+  readonly transformNativeStylesheets?: boolean;
+  readonly emittedGlobals?: MasterCSSEmittedGlobals;
+}
+interface MasterCSSStylesheetResolutionOptions extends StylesheetSourceContext {
+  readonly projectDir?: string;
+  /** Classify a prepared graph without flattening its CSS for delivery hosts. */
+  readonly preserveImports?: boolean;
+  readonly signal?: AbortSignal;
+}
+interface MasterCSSStylesheetDependencyOptions {
+  readonly projectDir?: string;
+  readonly signal?: AbortSignal;
+}
+interface MasterCSSStylesheetAsyncResolutionOptions extends MasterCSSStylesheetResolutionOptions {
+  readonly baseFile?: string;
+  readonly resolveImport?: CSSImportFileResolver;
+  readonly onDependency?: (file: string) => void;
+}
+type MasterCSSStylesheetKind = 'entry' | 'local' | 'master-package' | 'master-package-entry' | 'plain';
+interface MasterCSSStylesheetResolution {
+  readonly id: string;
+  readonly kind: MasterCSSStylesheetKind;
+  readonly source: string;
+  readonly compilationSource: string;
+  readonly outputSource: string;
+  readonly dependencies: readonly string[];
+}
+interface MasterCSSStylesheetHostOptions {
+  readonly masterImport?: string;
+  readonly masterSource?: string;
+  readonly signal?: AbortSignal;
+}
+interface MasterCSSStylesheetCompositionOptions extends MasterCSSStylesheetCompileOptions {
+  /** Compose only these registered source IDs; omitted selects all and an empty list selects none. */
+  readonly sourceIds?: readonly string[];
+  readonly scanner: MasterCSSScanner;
+  readonly manifest?: MasterCSSManifest;
+  readonly classes?: readonly string[];
+  readonly includeGeneratedCSS?: boolean;
+  readonly includeNativeCSS?: boolean;
+  readonly includeMasterBaseCSS?: boolean;
+}
+interface MasterCSSStylesheetComposition {
+  readonly diagnostics: readonly import('@master/css-schema').MasterCSSDiagnostic[];
+  readonly stylesheets?: readonly {
+    readonly id: string;
+    readonly href: string;
+    readonly css: string;
+  }[];
+  readonly resources?: readonly StylesheetResourceAsset[];
+  readonly dependencies?: readonly string[];
+  readonly css: string;
+  readonly emittedGlobals: Required<MasterCSSEmittedGlobals>;
+}
+interface MasterCSSStylesheetSourceSnapshot {
+  readonly id: string;
+  readonly source: string;
+  readonly dependencies: readonly string[];
+  readonly sourceDependencies: readonly string[];
+  readonly isMasterCSS: boolean;
+  readonly prunesNativeCSS: boolean;
+}
+interface MasterCSSStylesheetCollectionSnapshot {
+  readonly size: number;
+  readonly sourceIds: readonly string[];
+  readonly dependencies: readonly string[];
+  readonly sources: readonly MasterCSSStylesheetSourceSnapshot[];
+}
+declare function resolveStylesheetSync(id: string, source: string, options?: MasterCSSStylesheetResolutionOptions): MasterCSSStylesheetResolution | undefined;
+declare function resolveStylesheet(id: string, source: string, options?: MasterCSSStylesheetAsyncResolutionOptions): Promise<MasterCSSStylesheetResolution | undefined>;
+interface MasterCSSStylesheetDependencies {
+  /** References are resolved while lowering; this import inventory cannot prove their context unchanged. */
+  readonly hasReferences: boolean;
+  readonly dependencies: readonly string[];
+  readonly edges: readonly Readonly<{
+    from: string;
+    specifier: string;
+    resolved: string;
+  }>[];
+}
+/** Resolve the complete delivery graph, including package CSS, without lowering or flattening.
+ * Unlike classification-only dependency collection, resolution failures propagate.
+ */
+declare function resolveStylesheetDependenciesSync(id: string, source: string, options?: MasterCSSStylesheetDependencyOptions): MasterCSSStylesheetDependencies;
+declare function collectStylesheetDependenciesSync(id: string, source?: string, options?: MasterCSSStylesheetDependencyOptions): readonly string[];
+declare function collectStylesheetDependencies(id: string, source?: string, options?: MasterCSSStylesheetDependencyOptions): Promise<readonly string[]>;
+declare function composeStylesheetHostSync(source: string, options?: MasterCSSStylesheetHostOptions): string;
+declare function composeStylesheetHost(source: string, options?: MasterCSSStylesheetHostOptions): Promise<string>;
+declare function compileStylesheet(id: string, source: string, options: MasterCSSStylesheetCompileOptions): Promise<MasterCSSCompileResult>;
+declare function compileRenderedStylesheet(id: string, source: string, options: MasterCSSRenderedStylesheetCompileOptions): Promise<MasterCSSCompiledStylesheet>;
+declare function collectStylesheetEmittedGlobals(entries: readonly string[], options: MasterCSSStylesheetCompileOptions): Promise<Readonly<{
+  emittedGlobals: Required<MasterCSSEmittedGlobals>;
+  dependencies: readonly string[];
+}>>;
+declare function transformStylesheet(id: string, source: string, options: MasterCSSStylesheetTransformOptions): Promise<MasterCSSStylesheetTransformResult>;
+declare class MasterCSSStylesheetCollection implements Disposable {
+  #private;
+  private constructor();
+  get size(): number;
+  register(scanner: MasterCSSScanner, id: string, source: string, options: MasterCSSStylesheetCompileOptions): Promise<MasterCSSCompileResult>;
+  delete(id: string): boolean;
+  clear(): void;
+  compose(options: MasterCSSStylesheetCompositionOptions): Promise<MasterCSSStylesheetComposition>;
+  snapshot(): MasterCSSStylesheetCollectionSnapshot;
+  dispose(): void;
+  [Symbol.dispose](): void;
+  private assertActive;
+}
+declare function createStylesheetCollection(): MasterCSSStylesheetCollection;
+export { MasterCSSCompiledStylesheet, type MasterCSSPreparedStylesheet, MasterCSSRenderedStylesheetCompileOptions, type MasterCSSSassCompiler, MasterCSSStylesheetAsyncResolutionOptions, MasterCSSStylesheetCollection, MasterCSSStylesheetCollectionSnapshot, MasterCSSStylesheetCompileOptions, MasterCSSStylesheetComposition, MasterCSSStylesheetCompositionOptions, type MasterCSSStylesheetDeliveryOptions, MasterCSSStylesheetDependencies, MasterCSSStylesheetDependencyOptions, MasterCSSStylesheetHostOptions, type MasterCSSStylesheetImportResolver, type MasterCSSStylesheetImportSource, MasterCSSStylesheetKind, type MasterCSSStylesheetPreparationOptions, MasterCSSStylesheetResolution, MasterCSSStylesheetResolutionOptions, type MasterCSSStylesheetResourceAsset, MasterCSSStylesheetSourceSnapshot, MasterCSSStylesheetTransformOptions, MasterCSSStylesheetTransformResult, collectStylesheetDependencies, collectStylesheetDependenciesSync, collectStylesheetEmittedGlobals, compileRenderedStylesheet, compileStylesheet, composeStylesheetHost, composeStylesheetHostSync, createStylesheetCollection, prepareStylesheet, resolveStylesheet, resolveStylesheetDependenciesSync, resolveStylesheetSync, transformStylesheet };