styled-components-to-stylex-codemod 0.0.9 → 0.0.10

package/README.md

@@ -21,10 +21,7 @@ pnpm add styled-components-to-stylex-codemod
 Use `runTransform` to transform files matching a glob pattern:
 
 ```ts
-import {
-  runTransform,
-  defineAdapter,
-} from "styled-components-to-stylex-codemod";
+import { runTransform, defineAdapter } from "styled-components-to-stylex-codemod";
 
 const adapter = defineAdapter({
   resolveValue(ctx) {
@@ -70,9 +67,7 @@ const adapter = defineAdapter({
           .replace(/^--/, "")
           .split("-")
           .filter(Boolean)
-          .map((part, i) =>
-            i === 0 ? part : part[0]?.toUpperCase() + part.slice(1)
-          )
+          .map((part, i) => (i === 0 ? part : part[0]?.toUpperCase() + part.slice(1)))
           .join("");
 
       // If you care about fallbacks, you can use `fallback` here to decide whether to resolve or not.
@@ -97,18 +92,20 @@ const adapter = defineAdapter({
     // `calleeSource` tells you where it came from:
     // - { kind: "absolutePath", value: "/abs/path" } for relative imports
     // - { kind: "specifier", value: "some-package/foo" } for package imports
+    //
+    // The codemod determines how to use the result based on context:
+    // - If `ctx.cssProperty` exists (e.g., `border: ${helper()}`) → result is used as a CSS value
+    // - If `ctx.cssProperty` is undefined (e.g., `${helper()}`) → result is used as a StyleX style object
+    //
+    // Use `ctx.cssProperty` to return the appropriate expression for the context.
 
     const arg0 = ctx.args[0];
-    const key =
-      arg0?.kind === "literal" && typeof arg0.value === "string"
-        ? arg0.value
-        : null;
+    const key = arg0?.kind === "literal" && typeof arg0.value === "string" ? arg0.value : null;
     if (ctx.calleeImportedName !== "transitionSpeed" || !key) {
       return null;
     }
 
     return {
-      usage: "create",
       expr: `transitionSpeedVars.${key}`,
       imports: [
         {
@@ -119,9 +116,11 @@ const adapter = defineAdapter({
     };
   },
 
-  shouldSupportExternalStyling() {
-    return false;
+  externalInterface() {
+    return null;
   },
+
+  styleMerger: null,
 });
 
 const result = await runTransform({
@@ -139,10 +138,10 @@ console.log(result);
 
 Adapters are the main extension point. They let you control:
 
-- how theme paths and CSS variables are turned into StyleX-compatible JS values (`resolveValue`)
+- how theme paths, CSS variables, and imported values are turned into StyleX-compatible JS values (`resolveValue`)
 - what extra imports to inject into transformed files (returned from `resolveValue`)
-- how helper calls are resolved (via `resolveCall({ ... })` returning `usage: "props" | "create"`; `null`/`undefined` now bails)
-- which exported components should support external className/style extension (`shouldSupportExternalStyling`)
+- how helper calls are resolved (via `resolveCall({ ... })` returning `{ expr, imports }`; `null`/`undefined` bails the file)
+- which exported components should support external className/style extension and/or polymorphic `as` prop (`externalInterface`)
 - how className/style merging is handled for components accepting external styling (`styleMerger`)
 
 #### Style Merger
@@ -160,8 +159,15 @@ const adapter = defineAdapter({
     return null;
   },
 
-  shouldSupportExternalStyling(ctx) {
-    return ctx.filePath.includes("/shared/components/");
+  resolveCall() {
+    return null;
+  },
+
+  externalInterface(ctx) {
+    if (ctx.filePath.includes("/shared/components/")) {
+      return { styles: true };
+    }
+    return null;
   },
 
   // Use a custom merger function for cleaner output
@@ -178,15 +184,15 @@ The merger function should have this signature:
 function mergedSx(
   styles: StyleXStyles,
   className?: string,
-  style?: React.CSSProperties
+  style?: React.CSSProperties,
 ): ReturnType<typeof stylex.props>;
 ```
 
 See [`test-cases/lib/mergedSx.ts`](./test-cases/lib/mergedSx.ts) for a reference implementation.
 
-#### External Styles Support
+#### External Interface (Styles and Polymorphic `as` Support)
 
-Transformed components are "closed" by default — they don't accept external `className` or `style` props. Use `shouldSupportExternalStyling` to control which exported components should support external styling:
+Transformed components are "closed" by default — they don't accept external `className` or `style` props, and exported components only get `as` support when it is used inside the file. Use `externalInterface` to control which exported components should support these features:
 
 ```ts
 const adapter = defineAdapter({
@@ -195,39 +201,59 @@ const adapter = defineAdapter({
     return null;
   },
 
-  shouldSupportExternalStyling(ctx) {
+  resolveCall() {
+    return null;
+  },
+
+  externalInterface(ctx) {
     // ctx: { filePath, componentName, exportName, isDefaultExport }
 
-    // Example: Enable for all exports in shared components folder
+    // Example: Enable styles (and `as`) for all exports in shared components folder
     if (ctx.filePath.includes("/shared/components/")) {
-      return true;
+      return { styles: true };
     }
 
-    // Example: Enable for specific component names
-    if (ctx.componentName === "Button" || ctx.componentName === "Card") {
-      return true;
+    // Example: Enable only `as` prop (no style merging)
+    if (ctx.componentName === "Typography") {
+      return { styles: false, as: true };
     }
 
-    return false;
+    // Disable both (default)
+    return null;
   },
+
+  styleMerger: null,
 });
 ```
 
-When `shouldSupportExternalStyling` returns `true`, the generated component will:
+The `externalInterface` method returns:
+
+- `null` — no external interface (neither className/style nor `as` prop)
+- `{ styles: true }` — accept className/style props AND polymorphic `as` prop
+- `{ styles: false, as: true }` — accept only polymorphic `as` prop (no style merging)
+- `{ styles: false, as: false }` — equivalent to `null`
+
+When `styles: true`, the generated component will:
 
 - Accept `className` and `style` props
 - Merge them with the StyleX-generated styles
 - Forward remaining props via `...rest`
+- Accept polymorphic `as` prop (required for style merging to work correctly)
+
+When `{ styles: false, as: true }`, the generated component will accept a polymorphic `as` prop but won't include className/style merging.
 
 #### Dynamic interpolations
 
 When the codemod encounters an interpolation inside a styled template literal, it runs an internal dynamic resolution pipeline which covers common cases like:
 
 - theme access (`props.theme...`) via `resolveValue({ kind: "theme", path })`
+- imported value access (`import { zIndex } ...; ${zIndex.popover}`) via `resolveValue({ kind: "importedValue", importedName, source, path })`
 - prop access (`props.foo`) and conditionals (`props.foo ? "a" : "b"`, `props.foo && "color: red;"`)
-- simple helper calls (`transitionSpeed("slowTransition")`) via `resolveCall({ ... })` returning `usage: "create"`
-- style helper calls (returning StyleX styles) via `resolveCall({ ... })` returning `usage: "props"`; these are emitted as extra `stylex.props(...)` args
-- if `resolveCall` returns `null` or `undefined`, the transform now **bails the file** and logs a warning
+- helper calls (`transitionSpeed("slowTransition")`) via `resolveCall({ ... })` — the codemod infers usage from context:
+  - With `ctx.cssProperty` (e.g., `color: ${helper()}`) → result used as CSS value in `stylex.create()`
+  - Without `ctx.cssProperty` (e.g., `${helper()}`) → result used as StyleX styles in `stylex.props()`
+  - Use the optional `usage: "create" | "props"` field to override the default inference
+- if `resolveCall` returns `null` or `undefined`, the transform **bails the file** and logs a warning
 - helper calls applied to prop values (e.g. `shadow(props.shadow)`) by emitting a StyleX style function that calls the helper at runtime
 - conditional CSS blocks via ternary (e.g. `props.$dim ? "opacity: 0.5;" : ""`)
 
@@ -239,8 +265,8 @@ If the pipeline can’t resolve an interpolation:
 ### Limitations
 
 - **Flow** type generation is non-existing, works best with TypeScript or plain JS right now. Contributions more than welcome!
-- **ThemeProvider**: if a file imports and uses `ThemeProvider` from `styled-components`, the transform **skips the entire file** (theming strategy is project-specific).
 - **createGlobalStyle**: detected usage is reported as an **unsupported-feature** warning (StyleX does not support global styles in the same way).
+- **Theme prop overrides**: passing a `theme` prop directly to styled components (e.g. `<Button theme={...} />`) is not supported and will bail with a warning.
 
 ## License
 

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { i as defineAdapter, r as Adapter, t as CollectedWarning } from "./logger-CNmtK-uJ.mjs";
+import { i as defineAdapter, r as Adapter, t as CollectedWarning } from "./logger-DC-1uogs.mjs";
 
 //#region src/run.d.ts
 interface RunTransformOptions {

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { n as assertValidAdapter, r as describeValue, t as Logger } from "./logger-DKelw2HS.mjs";
+import { n as assertValidAdapter, r as describeValue, t as Logger } from "./logger-BLeJjMzG.mjs";
 import { run } from "jscodeshift/src/Runner.js";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
@@ -8,7 +8,8 @@ import { spawn } from "node:child_process";
 
 //#region src/adapter.ts
 /**
-* Adapter - Single user entry point for customizing the codemod.
+* Adapter entry point for customizing the codemod.
+* Core concepts: value resolution hooks and adapter validation.
 */
 /**
 * Helper for nicer user authoring + type inference.
@@ -27,23 +28,33 @@ import { spawn } from "node:child_process";
 *           ],
 *         };
 *       }
-*       return null;
+*       // Return undefined to bail/skip the file
 *     },
 *
 *     resolveCall(ctx) {
 *       // Resolve helper calls inside template interpolations.
+*       // Use ctx.cssProperty to determine context:
+*       // - If ctx.cssProperty exists → return a CSS value expression
+*       // - If ctx.cssProperty is undefined → return a StyleX style object reference
+*       // Return { expr, imports } or undefined to bail/skip the file
+*       void ctx;
+*     },
+*
+*     resolveSelector(ctx) {
+*       // Resolve imported values used in selector position (e.g., media query helpers).
 *       // Return:
-*       // - { usage: "props", expr, imports } for StyleX styles (usable in stylex.props)
-*       // - { usage: "create", expr, imports } for a single value (usable in stylex.create)
-*       // - null to leave the call unresolved
+*       // - { kind: "media", expr, imports } for media queries (e.g., breakpoints.phone)
+*       // - undefined to bail/skip the file
 *       void ctx;
-*       return null;
 *     },
 *
-*     // Enable className/style/rest support for exported components
-*     shouldSupportExternalStyling(ctx) {
-*       // Example: Enable for all exported components in a shared components folder
-*       return ctx.filePath.includes("/shared/components/");
+*     // Configure external interface for exported components
+*     externalInterface(ctx) {
+*       // Example: Enable styles (and `as`) for shared components folder
+*       if (ctx.filePath.includes("/shared/components/")) {
+*         return { styles: true };
+*       }
+*       return null;
 *     },
 *
 *     // Optional: provide a custom merger, or use `null` for the default verbose merge output
@@ -57,6 +68,10 @@ function defineAdapter(adapter) {
 
 //#endregion
 //#region src/run.ts
+/**
+* Runs the codemod over input files with an adapter.
+* Core concepts: jscodeshift execution, globs, and adapter hooks.
+*/
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /**
 * Run the styled-components to StyleX transform on files matching the glob pattern.
@@ -114,7 +129,7 @@ async function runTransform(options) {
 		} catch (e) {
 			const msg = `adapter.resolveValue threw an error: ${e instanceof Error ? e.message : String(e)}`;
 			const filePath = ctx.filePath ?? "<unknown>";
-			Logger.logError(msg, filePath, void 0, ctx);
+			Logger.logError(msg, filePath, ctx.loc, ctx);
 			throw e;
 		}
 	};
@@ -123,17 +138,27 @@ async function runTransform(options) {
 			return adapter.resolveCall(ctx);
 		} catch (e) {
 			const msg = `adapter.resolveCall threw an error: ${e instanceof Error ? e.message : String(e)}`;
-			Logger.logError(msg, ctx.callSiteFilePath, void 0, ctx);
+			Logger.logError(msg, ctx.callSiteFilePath, ctx.loc, ctx);
+			throw e;
+		}
+	};
+	const resolveSelectorWithLogging = (ctx) => {
+		try {
+			return adapter.resolveSelector(ctx);
+		} catch (e) {
+			const msg = `adapter.resolveSelector threw an error: ${e instanceof Error ? e.message : String(e)}`;
+			Logger.logError(msg, ctx.filePath, ctx.loc, ctx);
 			throw e;
 		}
 	};
 	const adapterWithLogging = {
 		styleMerger: adapter.styleMerger,
-		shouldSupportExternalStyling(ctx) {
-			return adapter.shouldSupportExternalStyling(ctx);
+		externalInterface(ctx) {
+			return adapter.externalInterface(ctx);
 		},
 		resolveValue: resolveValueWithLogging,
-		resolveCall: resolveCallWithLogging
+		resolveCall: resolveCallWithLogging,
+		resolveSelector: resolveSelectorWithLogging
 	};
 	const patterns = Array.isArray(files) ? files : [files];
 	const filePaths = [];
@@ -171,13 +196,13 @@ async function runTransform(options) {
 	if (formatterCommand && result.ok > 0 && !dryRun) {
 		const [cmd, ...cmdArgs] = formatterCommand.split(/\s+/);
 		if (cmd) try {
-			await new Promise((resolve$1, reject) => {
+			await new Promise((resolve, reject) => {
 				const proc = spawn(cmd, [...cmdArgs, ...filePaths], {
 					stdio: "inherit",
 					shell: true
 				});
 				proc.on("close", (code) => {
-					if (code === 0) resolve$1();
+					if (code === 0) resolve();
 					else reject(/* @__PURE__ */ new Error(`Formatter command exited with code ${code}`));
 				});
 				proc.on("error", reject);
@@ -186,13 +211,15 @@ async function runTransform(options) {
 			Logger.warn(`Formatter command failed: ${e instanceof Error ? e.message : String(e)}`);
 		}
 	}
+	const report = Logger.createReport();
+	report.print();
 	return {
 		errors: result.error,
 		unchanged: result.nochange,
 		skipped: result.skip,
 		transformed: result.ok,
 		timeElapsed: parseFloat(result.timeElapsed) || 0,
-		warnings: Logger.flushWarnings()
+		warnings: report.getWarnings()
 	};
 }
 

package/dist/{logger-DKelw2HS.mjs → logger-BLeJjMzG.mjs}

@@ -1,3 +1,5 @@
+import { readFileSync } from "node:fs";
+
 //#region src/internal/public-api-validation.ts
 function describeValue(value) {
 	if (value === null) return "null";
@@ -24,7 +26,8 @@ function assertValidAdapter(candidate, where) {
 	const obj = candidate;
 	const resolveValue = obj?.resolveValue;
 	const resolveCall = obj?.resolveCall;
-	const shouldSupportExternalStyling = obj?.shouldSupportExternalStyling;
+	const resolveSelector = obj?.resolveSelector;
+	const externalInterface = obj?.externalInterface;
 	if (!candidate || typeof candidate !== "object") throw new Error([
 		`${where}: expected an adapter object.`,
 		`Received: ${describeValue(candidate)}`,
@@ -32,15 +35,20 @@ function assertValidAdapter(candidate, where) {
 		"Adapter requirements:",
 		"  - adapter.resolveValue(context) is required",
 		"  - adapter.resolveCall(context) is required",
-		"  - adapter.shouldSupportExternalStyling(context) is required",
+		"  - adapter.resolveSelector(context) is required",
+		"  - adapter.externalInterface(context) is required",
 		"",
 		"resolveValue(context) is called with one of these shapes:",
 		"  - { kind: \"theme\", path }",
 		"  - { kind: \"cssVariable\", name, fallback?, definedValue? }",
+		"  - { kind: \"importedValue\", importedName, source, path? }",
 		"",
 		"resolveCall(context) is called with:",
 		"  - { callSiteFilePath, calleeImportedName, calleeSource, args }",
 		"",
+		"resolveSelector(context) is called with:",
+		"  - { kind: \"selectorInterpolation\", importedName, source, path? }",
+		"",
 		`Docs/examples: ${ADAPTER_DOCS_URL}`
 	].join("\n"));
 	if (typeof resolveValue !== "function") throw new Error([
@@ -52,7 +60,7 @@ function assertValidAdapter(candidate, where) {
 		"    resolveValue(context) {",
 		"      // theme/cssVariable -> { expr, imports, dropDefinition? } | null",
 		"    }",
-		"    resolveCall(context) { return { usage: \"props\" | \"create\", expr, imports } | null }",
+		"    resolveCall(context) { return { expr, imports } | null }",
 		"  }",
 		"",
 		`Docs/examples: ${ADAPTER_DOCS_URL}`
@@ -63,12 +71,23 @@ function assertValidAdapter(candidate, where) {
 		"",
 		"Adapter shape:",
 		"  {",
-		"    resolveCall(context) { return { usage: \"props\" | \"create\", expr: string, imports: ImportSpec[] } | null }",
+		"    resolveCall(context) { return { expr: string, imports: ImportSpec[] } | null }",
+		"  }",
+		"",
+		`Docs/examples: ${ADAPTER_DOCS_URL}`
+	].join("\n"));
+	if (typeof resolveSelector !== "function") throw new Error([
+		`${where}: adapter.resolveSelector must be a function.`,
+		`Received: resolveSelector=${describeValue(resolveSelector)}`,
+		"",
+		"Adapter shape:",
+		"  {",
+		"    resolveSelector(context) { return { kind: \"media\", expr: string, imports: ImportSpec[] } | undefined }",
 		"  }",
 		"",
 		`Docs/examples: ${ADAPTER_DOCS_URL}`
 	].join("\n"));
-	if (typeof shouldSupportExternalStyling !== "function") throw new Error([`${where}: adapter.shouldSupportExternalStyling must be a function.`, `Received: shouldSupportExternalStyling=${describeValue(shouldSupportExternalStyling)}`].join("\n"));
+	if (typeof externalInterface !== "function") throw new Error([`${where}: adapter.externalInterface must be a function.`, `Received: externalInterface=${describeValue(externalInterface)}`].join("\n"));
 	const styleMerger = obj?.styleMerger;
 	if (styleMerger !== null && styleMerger !== void 0) {
 		if (typeof styleMerger !== "object") throw new Error([
@@ -101,21 +120,20 @@ const ADAPTER_DOCS_URL = `https://github.com/skovhus/styled-components-to-stylex
 
 //#endregion
 //#region src/internal/logger.ts
+/**
+* Logger and warning types for transform diagnostics.
+* Core concepts: severity classification and source context reporting.
+*/
 var Logger = class Logger {
-	static flushWarnings() {
-		const result = collected;
-		collected = [];
-		return result;
-	}
 	/**
-	* Log a warning message to stderr.
+	* Log a warning message to stdout.
 	* All codemod warnings go through this so tests can mock it.
 	*/
 	static warn(message, context) {
 		Logger.writeWithSpacing(message, context);
 	}
 	/**
-	* Log an error message to stderr with file path and optional location.
+	* Log an error message to stdout with file path and optional location.
 	* Formats like warnings: "Error filepath:line:column\nmessage"
 	*/
 	static logError(message, filePath, loc, context) {
@@ -124,23 +142,34 @@ var Logger = class Logger {
 		Logger.writeWithSpacing(`${label} ${location}\n${message}`, context);
 	}
 	/**
-	* Log transform warnings to stderr and collect them.
+	* Log transform warnings to stdout and collect them.
 	*/
 	static logWarnings(warnings, filePath) {
 		for (const warning of warnings) {
-			collected.push({
+			Logger.collected.push({
 				...warning,
 				filePath
 			});
 			const location = warning.loc ? `${filePath}:${warning.loc.line}:${warning.loc.column}` : `${filePath}`;
 			const label = Logger.colorizeSeverityLabel(warning.severity);
-			Logger.writeWithSpacing(`${label} ${location}\n${warning.message}`, warning.context);
+			Logger.writeWithSpacing(`${label} ${location}\n${warning.type}`, warning.context);
 		}
 	}
+	/**
+	* Create a report from all collected warnings.
+	*/
+	static createReport() {
+		return new LoggerReport([...Logger.collected]);
+	}
+	/** @internal - for testing only */
+	static _clearCollected() {
+		Logger.collected = [];
+	}
+	static collected = [];
 	static writeWithSpacing(message, context) {
 		const trimmed = message.replace(/\s+$/u, "");
 		const serialized = Logger.formatContext(context);
-		process.stderr.write(`${trimmed}${serialized ? `\n${serialized}` : ""}\n\n`);
+		process.stdout.write(`${trimmed}${serialized ? `\n${serialized}` : ""}\n\n`);
 	}
 	static colorizeSeverityLabel(severity) {
 		if (severity === "error") return Logger.colorizeErrorLabel("Error");
@@ -148,15 +177,15 @@ var Logger = class Logger {
 		return Logger.colorizeWarnLabel("Warning");
 	}
 	static colorizeWarnLabel(label) {
-		if (!process.stderr.isTTY) return label;
+		if (!process.stdout.isTTY) return label;
 		return `${WARN_BG_COLOR}${WARN_TEXT_COLOR}${label}${RESET_COLOR}`;
 	}
 	static colorizeErrorLabel(label) {
-		if (!process.stderr.isTTY) return label;
+		if (!process.stdout.isTTY) return label;
 		return `${ERROR_BG_COLOR}${ERROR_TEXT_COLOR}${label}${RESET_COLOR}`;
 	}
 	static colorizeInfoLabel(label) {
-		if (!process.stderr.isTTY) return label;
+		if (!process.stdout.isTTY) return label;
 		return `${INFO_BG_COLOR}${INFO_TEXT_COLOR}${label}${RESET_COLOR}`;
 	}
 	static formatContext(context) {
@@ -164,13 +193,113 @@ var Logger = class Logger {
 		return JSON.stringify(context, null, 2);
 	}
 };
-let collected = [];
+var LoggerReport = class {
+	warnings;
+	fileCache = /* @__PURE__ */ new Map();
+	constructor(warnings) {
+		this.warnings = warnings;
+	}
+	getWarnings() {
+		return this.warnings;
+	}
+	/**
+	* Get the formatted report as a string.
+	*/
+	toString() {
+		if (this.warnings.length === 0) return "";
+		const lines = [];
+		const groups = this.groupWarnings();
+		lines.push("");
+		lines.push("─".repeat(60));
+		lines.push(`Warning Summary: ${this.warnings.length} warning(s) in ${groups.length} category(s)`);
+		lines.push("─".repeat(60));
+		const MAX_EXAMPLES = 15;
+		for (const group of groups) {
+			lines.push("");
+			lines.push(`▸ ${group.message} (${group.warnings.length})`);
+			lines.push("");
+			const seenFiles = /* @__PURE__ */ new Set();
+			const uniqueLocations = [];
+			for (const loc of group.warnings) if (!seenFiles.has(loc.filePath)) {
+				seenFiles.add(loc.filePath);
+				uniqueLocations.push(loc);
+			}
+			const displayed = uniqueLocations.slice(0, MAX_EXAMPLES);
+			for (const loc of displayed) {
+				const location = loc.loc ? `${loc.filePath}:${loc.loc.line}:${loc.loc.column}` : loc.filePath;
+				lines.push(`  ${location}`);
+				if (loc.snippet) lines.push(loc.snippet);
+				lines.push("");
+			}
+			const remaining = uniqueLocations.length - MAX_EXAMPLES;
+			if (remaining > 0) {
+				lines.push(`  ... and ${remaining} more file(s)`);
+				lines.push("");
+			}
+		}
+		return lines.join("\n");
+	}
+	/**
+	* Print the formatted warning report to stdout.
+	*/
+	print() {
+		const output = this.toString();
+		if (output) {
+			const colored = output.replace(/▸ (.+?) \((\d+)\)/g, `${SECTION_COLOR}▸ $1 ($2)${RESET_COLOR}`);
+			process.stdout.write(colored + "\n");
+		}
+	}
+	groupWarnings() {
+		const groupMap = /* @__PURE__ */ new Map();
+		for (const warning of this.warnings) {
+			const enrichedWarning = {
+				...warning,
+				snippet: warning.loc ? this.getSnippet(warning.filePath, warning.loc) : void 0
+			};
+			const existing = groupMap.get(warning.type);
+			if (existing) existing.warnings.push(enrichedWarning);
+			else groupMap.set(warning.type, {
+				message: warning.type,
+				warnings: [enrichedWarning]
+			});
+		}
+		return Array.from(groupMap.values()).sort((a, b) => b.warnings.length - a.warnings.length);
+	}
+	getSnippet(filePath, loc) {
+		if (!loc) return;
+		const lines = this.getFileLines(filePath);
+		if (!lines) return;
+		const lineIndex = loc.line - 1;
+		if (lineIndex < 0 || lineIndex >= lines.length) return;
+		const snippetLines = [];
+		const startLine = Math.max(0, lineIndex - 2);
+		const endLine = Math.min(lines.length - 1, lineIndex + 4);
+		for (let i = startLine; i <= endLine; i++) {
+			const lineNum = String(i + 1).padStart(4, " ");
+			const marker = i === lineIndex ? ">" : " ";
+			snippetLines.push(`  ${marker} ${lineNum} | ${lines[i]}`);
+		}
+		return snippetLines.join("\n");
+	}
+	getFileLines(filePath) {
+		if (this.fileCache.has(filePath)) return this.fileCache.get(filePath) ?? null;
+		try {
+			const lines = readFileSync(filePath, "utf-8").split("\n");
+			this.fileCache.set(filePath, lines);
+			return lines;
+		} catch {
+			this.fileCache.set(filePath, null);
+			return null;
+		}
+	}
+};
 const WARN_BG_COLOR = "\x1B[43m";
 const WARN_TEXT_COLOR = "\x1B[30m";
 const ERROR_BG_COLOR = "\x1B[41m";
 const ERROR_TEXT_COLOR = "\x1B[37m";
 const INFO_BG_COLOR = "\x1B[44m";
 const INFO_TEXT_COLOR = "\x1B[37m";
+const SECTION_COLOR = "\x1B[36m";
 const RESET_COLOR = "\x1B[0m";
 
 //#endregion