@pygmalionjs/pygmalion 0.6.19 → 0.6.20

package/inspect.d.ts

@@ -0,0 +1,35 @@
+import type { InspectApplyPayload } from './dist-lib/types/lib';
+
+export interface PygmalionInspectWritebackOptions {
+  sourceDirectory?: string;
+  normalizeValue?: (property: string, value: string) => string;
+}
+
+export interface PygmalionInspectPreviewResult {
+  files: { file: string; diff: string }[];
+  affectedFiles: string[];
+}
+
+export interface PygmalionInspectWriteResult {
+  applied: number;
+  changed: number;
+  files: string[];
+}
+
+export declare function previewInspectChanges(
+  root: string,
+  input: InspectApplyPayload,
+  options?: PygmalionInspectWritebackOptions,
+): Promise<PygmalionInspectPreviewResult>;
+
+export declare function writeInspectChanges(
+  root: string,
+  input: InspectApplyPayload,
+  options?: PygmalionInspectWritebackOptions,
+): Promise<PygmalionInspectWriteResult>;
+
+export declare function findAffectedSourceFiles(
+  root: string,
+  componentFiles: string[],
+  options?: { sourceDirectory?: string },
+): Promise<string[]>;

package/node/inspect-plugin.mjs

@@ -385,7 +385,7 @@ export function pygmalionInspectPlugin({
         magic.append(`
 
 ;(() => {
-  if (!import.meta.env.DEV) return;
+  if (typeof window === 'undefined') return;
   (globalThis.__PYG_CSS_MODULES__ ||= []).push(${items});
 })();`);
       }

package/node/inspect-writeback.mjs

@@ -0,0 +1,163 @@
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { writeStyleEdit, writeTextEdit } from './inspect-plugin.mjs';
+import { createUnifiedDiff } from './source-diff.mjs';
+import { writeSourceOperations } from './source-operations.mjs';
+
+const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.mts', '.cjs', '.cts']);
+
+function normalizeSourceDirectory(value = 'src') {
+  return value.replace(/^\.?\//, '').replace(/\/$/, '') || '.';
+}
+
+function validateRelativeSourcePath(root, value, sourceDirectory, extensions) {
+  if (
+    typeof value !== 'string' ||
+    path.isAbsolute(value) ||
+    value.includes('\0') ||
+    value.split(/[\\/]/).includes('..') ||
+    !extensions.has(path.extname(value).toLowerCase())
+  ) {
+    throw new Error(`Source path cannot be modified: ${String(value)}`);
+  }
+  const normalized = value.split(path.sep).join('/');
+  if (
+    sourceDirectory !== '.' &&
+    normalized !== sourceDirectory &&
+    !normalized.startsWith(`${sourceDirectory}/`)
+  ) {
+    throw new Error(`Only ${sourceDirectory} source files can be modified`);
+  }
+  const absolutePath = path.resolve(root, normalized);
+  const relativePath = path.relative(root, absolutePath);
+  if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+    throw new Error('Source path escapes app root');
+  }
+  return {
+    absolutePath,
+    relativePath: relativePath.split(path.sep).join('/'),
+  };
+}
+
+function normalizeInspectChanges(input) {
+  const styles = Array.isArray(input?.styles) ? input.styles : [];
+  const texts = Array.isArray(input?.texts) ? input.texts : [];
+  const operations = Array.isArray(input?.operations) ? input.operations : [];
+  const operationCount = styles.length + texts.length + operations.length;
+  if (operationCount === 0 || operationCount > 100) {
+    throw new Error('Inspect changes must contain between 1 and 100 operations');
+  }
+  return { styles, texts, operations, operationCount };
+}
+
+function collectInspectFiles(root, changes, sourceDirectory) {
+  const files = new Map();
+  for (const style of changes.styles) {
+    const file = validateRelativeSourcePath(
+      root,
+      style?.file,
+      sourceDirectory,
+      new Set(['.scss']),
+    );
+    files.set(file.relativePath, file.absolutePath);
+  }
+  for (const text of changes.texts) {
+    const file = validateRelativeSourcePath(
+      root,
+      text?.componentFile,
+      sourceDirectory,
+      SOURCE_EXTENSIONS,
+    );
+    files.set(file.relativePath, file.absolutePath);
+  }
+  for (const operation of changes.operations) {
+    const file = validateRelativeSourcePath(
+      root,
+      operation?.identity?.componentFile,
+      sourceDirectory,
+      SOURCE_EXTENSIONS,
+    );
+    files.set(file.relativePath, file.absolutePath);
+  }
+  return files;
+}
+
+async function applyInspectChanges(root, changes, options) {
+  const results = [];
+  for (const style of changes.styles) {
+    results.push(await writeStyleEdit(root, style, options));
+  }
+  const sourceResult = changes.operations.length
+    ? await writeSourceOperations(root, changes.operations, options)
+    : null;
+  for (const text of changes.texts) {
+    results.push(await writeTextEdit(root, text, options));
+  }
+  return {
+    applied: results.length + (sourceResult?.operations ?? 0),
+    changed: results.filter((result) => result.changed).length + (sourceResult?.changed ?? 0),
+  };
+}
+
+export async function previewInspectChanges(root, input, options = {}) {
+  const appRoot = path.resolve(root);
+  const sourceDirectory = normalizeSourceDirectory(options.sourceDirectory);
+  const changes = normalizeInspectChanges(input);
+  const files = collectInspectFiles(appRoot, changes, sourceDirectory);
+  const before = new Map();
+  for (const [relativePath, absolutePath] of files) {
+    before.set(relativePath, await fsp.readFile(absolutePath, 'utf8'));
+  }
+
+  const temporaryRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'pygmalion-inspect-'));
+  try {
+    for (const [relativePath, source] of before) {
+      const target = path.join(temporaryRoot, relativePath);
+      await fsp.mkdir(path.dirname(target), { recursive: true });
+      await fsp.writeFile(target, source);
+    }
+    await applyInspectChanges(temporaryRoot, changes, {
+      ...options,
+      sourceDirectory,
+    });
+    const diffs = [];
+    for (const [relativePath, source] of before) {
+      const next = await fsp.readFile(path.join(temporaryRoot, relativePath), 'utf8');
+      const diff = createUnifiedDiff(source, next, relativePath);
+      if (diff) diffs.push({ file: relativePath, diff });
+    }
+    return {
+      files: diffs,
+      affectedFiles: [...files.keys()].sort(),
+    };
+  } finally {
+    await fsp.rm(temporaryRoot, { recursive: true, force: true });
+  }
+}
+
+export async function writeInspectChanges(root, input, options = {}) {
+  const appRoot = path.resolve(root);
+  const sourceDirectory = normalizeSourceDirectory(options.sourceDirectory);
+  const changes = normalizeInspectChanges(input);
+  const files = collectInspectFiles(appRoot, changes, sourceDirectory);
+  const backups = new Map();
+  for (const [relativePath, absolutePath] of files) {
+    backups.set(relativePath, await fsp.readFile(absolutePath, 'utf8'));
+  }
+
+  try {
+    const result = await applyInspectChanges(appRoot, changes, {
+      ...options,
+      sourceDirectory,
+    });
+    return { ...result, files: [...files.keys()].sort() };
+  } catch (error) {
+    await Promise.all(
+      [...backups].map(([relativePath, source]) =>
+        fsp.writeFile(files.get(relativePath), source),
+      ),
+    );
+    throw error;
+  }
+}

package/node/inspect.mjs

@@ -0,0 +1,5 @@
+export {
+  previewInspectChanges,
+  writeInspectChanges,
+} from './inspect-writeback.mjs';
+export { findAffectedSourceFiles } from './source-graph.mjs';

package/node/vite.mjs

@@ -84,6 +84,10 @@ import {
   validateQaCaptureRequest,
 } from './qa-capture-plugin.mjs';
 import { resolveGitSourceState } from './source-revision.mjs';
+import {
+  previewInspectChanges,
+  writeInspectChanges,
+} from './inspect-writeback.mjs';
 
 function requiredPath(value, name, base) {
   if (typeof value !== 'string' || value.trim() === '') {
@@ -414,6 +418,8 @@ export {
   writeSourceOperations,
   writeStyleEdit,
   writeTextEdit,
+  previewInspectChanges,
+  writeInspectChanges,
   convertRoutePreviewArtifactV1ToV2,
   convertRoutePreviewArtifactV2ToV1,
   createRoutePreviewArtifactV2,

package/node/webpack-loader.cjs

@@ -0,0 +1,59 @@
+const path = require('node:path');
+
+const inspectPlugins = new Map();
+
+function normalizeSourceDirectory(value) {
+  if (typeof value !== 'string') return 'src';
+  return value.replace(/^\.?\//, '').replace(/\/$/, '') || '.';
+}
+
+function isWithinSourceDirectory(relativePath, sourceDirectory) {
+  return (
+    sourceDirectory === '.' ||
+    relativePath === sourceDirectory ||
+    relativePath.startsWith(`${sourceDirectory}/`)
+  );
+}
+
+function inspectPlugin(root, sourceDirectory) {
+  const key = `${root}\0${sourceDirectory}`;
+  let promise = inspectPlugins.get(key);
+  if (!promise) {
+    promise = import('./inspect-plugin.mjs').then(({ pygmalionInspectPlugin }) =>
+      pygmalionInspectPlugin({ root, sourceDirectory }),
+    );
+    inspectPlugins.set(key, promise);
+  }
+  return promise;
+}
+
+module.exports = function pygmalionWebpackLoader(source, inputMap) {
+  const callback = this.async();
+  const options = typeof this.getOptions === 'function' ? this.getOptions() : {};
+  const root = path.resolve(options.root || this.rootContext || process.cwd());
+  const sourceDirectory = normalizeSourceDirectory(options.sourceDirectory);
+  const componentFile = path
+    .relative(root, this.resourcePath)
+    .split(path.sep)
+    .join('/');
+
+  if (
+    componentFile.startsWith('../') ||
+    path.isAbsolute(componentFile) ||
+    !isWithinSourceDirectory(componentFile, sourceDirectory)
+  ) {
+    callback(null, source, inputMap);
+    return;
+  }
+
+  inspectPlugin(root, sourceDirectory)
+    .then((plugin) => {
+      const transformed = plugin.transform(String(source), this.resourcePath);
+      if (!transformed) {
+        callback(null, source, inputMap);
+        return;
+      }
+      callback(null, transformed.code, transformed.map);
+    })
+    .catch((error) => callback(error));
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.6.19",
+  "version": "0.6.20",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -23,7 +23,12 @@
       "types": "./storyboard.d.ts",
       "default": "./node/storyboard.mjs"
     },
+    "./inspect": {
+      "types": "./inspect.d.ts",
+      "default": "./node/inspect.mjs"
+    },
     "./dev-view": "./node/dev-view.vite.mjs",
+    "./webpack-loader": "./node/webpack-loader.cjs",
     "./testing": {
       "types": "./dist-lib/types/testing.d.ts",
       "default": "./dist-lib/testing.js"
@@ -40,6 +45,8 @@
     "node/dev-mirror.mjs",
     "node/dev-view.vite.mjs",
     "node/inspect-plugin.mjs",
+    "node/inspect.mjs",
+    "node/inspect-writeback.mjs",
     "node/preview-artifact-plugin.mjs",
     "node/preview-artifact-store.mjs",
     "node/preview-capture-worker.mjs",
@@ -59,6 +66,8 @@
     "node/storyboard-environment.mjs",
     "node/storyboard.mjs",
     "node/vite.mjs",
+    "node/webpack-loader.cjs",
+    "inspect.d.ts",
     "qa.d.ts",
     "storyboard.d.ts",
     "vite.d.ts"

package/vite.d.ts

@@ -264,6 +264,34 @@ export declare function writeTextEdit(
   options?: { sourceDirectory?: string },
 ): Promise<unknown>;
 
+export interface PygmalionInspectWritebackOptions {
+  sourceDirectory?: string;
+  normalizeValue?: (property: string, value: string) => string;
+}
+
+export interface PygmalionInspectPreviewResult {
+  files: { file: string; diff: string }[];
+  affectedFiles: string[];
+}
+
+export interface PygmalionInspectWriteResult {
+  applied: number;
+  changed: number;
+  files: string[];
+}
+
+export declare function previewInspectChanges(
+  root: string,
+  input: import('./types').InspectApplyPayload,
+  options?: PygmalionInspectWritebackOptions,
+): Promise<PygmalionInspectPreviewResult>;
+
+export declare function writeInspectChanges(
+  root: string,
+  input: import('./types').InspectApplyPayload,
+  options?: PygmalionInspectWritebackOptions,
+): Promise<PygmalionInspectWriteResult>;
+
 export interface PygmalionSourceOperationApplyResult {
   code: string;
   changed: boolean;