@ispriter/core 2.0.0 → 2.0.2

package/README.md

@@ -0,0 +1,26 @@
+# @ispriter/core
+
+Core sprite generation engine for [iSpriter](https://github.com/iazrael/ispriter).
+
+## Installation
+
+```bash
+npm install @ispriter/core
+```
+
+## Usage
+
+```typescript
+import { Spriter } from '@ispriter/core';
+
+const spriter = new Spriter({
+  input: { cssSource: './src/css/' },
+  output: { cssDist: './dist/css/' },
+});
+
+const result = await spriter.run({ css, images, cssBaseDir: './src/css/' });
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -175,6 +175,7 @@ interface SpriterRunInput {
     css: Map<string, string>;
     images: Map<string, Buffer>;
     cssBaseDir: string;
+    dryRun?: boolean;
 }
 /** 打包后的精灵图条目 */
 interface PackedSprite {
@@ -201,6 +202,8 @@ interface SpriterResult {
         height: number;
     }>;
     skippedImages: string[];
+    /** Only present when dryRun=true */
+    dryRunReport?: string;
 }
 
 interface PackOutput<T> {
@@ -270,6 +273,7 @@ declare class Spriter {
     /** Fix #13: 按 maxSingleSize 拆分精灵图 */
     private splitByMaxSize;
     private buildManifest;
+    private buildDryRunReport;
 }
 
 interface PluginRunOptions {

package/dist/index.js

@@ -37,10 +37,12 @@ var SpriterConfigSchema = z.object({
     unit: z.enum(["px", "rem"]).default("px"),
     remBase: z.number().positive().default(16)
   }),
-  groups: z.array(z.object({
-    name: z.string(),
-    images: z.union([z.string(), z.array(z.string())])
-  })).optional()
+  groups: z.array(
+    z.object({
+      name: z.string(),
+      images: z.union([z.string(), z.array(z.string())])
+    })
+  ).optional()
 });
 function normalizeConfig(input) {
   if (typeof input === "string") {
@@ -66,13 +68,11 @@ function parseConfig(raw) {
   validateNoTraversal(result.data.output.imageDist, "output.imageDist");
   return result.data;
 }
-function validateNoTraversal(pathStr, fieldName) {
-  if (pathStr.includes("..")) {
-    throw new IspriterError(
-      `Path traversal detected in ${fieldName}: "${pathStr}"`,
-      "CONFIG_INVALID",
-      { field: fieldName }
-    );
+function validateNoTraversal(pathStr, _fieldName) {
+  if (pathStr.includes("\0")) {
+    throw new IspriterError(`Invalid path in ${_fieldName}: null byte detected`, "CONFIG_INVALID", {
+      field: _fieldName
+    });
   }
 }
 
@@ -103,7 +103,9 @@ function analyseBackground(value) {
   }
   if (result.imageUrl) {
     const afterUrl = value.replace(/url\([^)]*\)/, "").trim();
-    const posTokens = afterUrl.split(/\s+/).filter((t) => t && !["no-repeat", "repeat", "repeat-x", "repeat-y", "repeat-space"].includes(t)).filter((t) => !t.startsWith("/") && !t.startsWith("#"));
+    const posTokens = afterUrl.split(/\s+/).filter(
+      (t) => t && !["no-repeat", "repeat", "repeat-x", "repeat-y", "repeat-space"].includes(t)
+    ).filter((t) => !t.startsWith("/") && !t.startsWith("#"));
     if (posTokens.length >= 1) {
       result.positionX = parsePositionValue(posTokens[0]);
     }
@@ -128,8 +130,10 @@ function shouldSkip(parsed) {
   }
   if (parsed.positionX === "100%" || parsed.positionY === "100%") return true;
   if (parsed.positionX === "center" || parsed.positionY === "center") return true;
-  if (typeof parsed.positionX === "string" && parsed.positionX.endsWith("%") && parsed.positionX !== "100%") return true;
-  if (typeof parsed.positionY === "string" && parsed.positionY.endsWith("%") && parsed.positionY !== "100%") return true;
+  if (typeof parsed.positionX === "string" && parsed.positionX.endsWith("%") && parsed.positionX !== "100%")
+    return true;
+  if (typeof parsed.positionY === "string" && parsed.positionY.endsWith("%") && parsed.positionY !== "100%")
+    return true;
   return false;
 }
 function cleanImageUrl(url) {
@@ -173,7 +177,9 @@ async function extractBackgrounds(cssContents) {
       processRules(root, filename, false, rules);
       root.walkAtRules(/keyframes/i, (atRule) => {
         if (atRule.nodes) {
-          const kfRoot = postcss2.parse(atRule.toString().replace(/@[^{]+\{/, "").replace(/\}$/, ""));
+          const kfRoot = postcss2.parse(
+            atRule.toString().replace(/@[^{]+\{/, "").replace(/\}$/, "")
+          );
           processRules(kfRoot, filename, true, rules);
         }
       });
@@ -328,14 +334,19 @@ async function emitCSS(cssContents, packedSprites, config, retinaInfo) {
         );
         const minified = cleaner.minify(output);
         if (minified.errors.length > 0) {
-          throw new IspriterError(`CSS compression failed: ${minified.errors.join(", ")}`, "OUTPUT_ERROR");
+          throw new IspriterError(
+            `CSS compression failed: ${minified.errors.join(", ")}`,
+            "OUTPUT_ERROR"
+          );
         }
         output = minified.styles;
       }
       results.set(filename, output);
     } catch (e) {
       if (e instanceof IspriterError) throw e;
-      throw new IspriterError(`Failed to emit CSS for ${filename}`, "OUTPUT_ERROR", { file: filename });
+      throw new IspriterError(`Failed to emit CSS for ${filename}`, "OUTPUT_ERROR", {
+        file: filename
+      });
     }
   }
   if (config.output.combine && results.size > 1) {
@@ -368,13 +379,15 @@ async function generateSprites(packedSprites, config) {
           background: { r: 0, g: 0, b: 0, alpha: 0 }
         }
       });
-      const composites = await Promise.all(items.map(async (item) => {
-        let inputBuf = item.asset.buffer;
-        if (item.width !== item.asset.naturalWidth || item.height !== item.asset.naturalHeight) {
-          inputBuf = await sharp(item.asset.buffer).resize(item.width, item.height, { fit: "fill" }).toBuffer();
-        }
-        return { input: inputBuf, left: item.x, top: item.y };
-      }));
+      const composites = await Promise.all(
+        items.map(async (item) => {
+          let inputBuf = item.asset.buffer;
+          if (item.width !== item.asset.naturalWidth || item.height !== item.asset.naturalHeight) {
+            inputBuf = await sharp(item.asset.buffer).resize(item.width, item.height, { fit: "fill" }).toBuffer();
+          }
+          return { input: inputBuf, left: item.x, top: item.y };
+        })
+      );
       let output = canvas.composite(composites);
       if (config.output.format === "webp") {
         output = output.webp({ quality: config.output.quality });
@@ -385,10 +398,14 @@ async function generateSprites(packedSprites, config) {
       results.set(sprite.spriteFile, buffer);
     } catch (e) {
       if (e instanceof IspriterError) throw e;
-      throw new IspriterError(`Failed to generate sprite: ${sprite.spriteFile}: ${e.message}`, "OUTPUT_ERROR", {
-        spriteFile: sprite.spriteFile,
-        cause: e
-      });
+      throw new IspriterError(
+        `Failed to generate sprite: ${sprite.spriteFile}: ${e.message}`,
+        "OUTPUT_ERROR",
+        {
+          spriteFile: sprite.spriteFile,
+          cause: e
+        }
+      );
     }
   }
   return results;
@@ -415,6 +432,16 @@ var Spriter = class {
       allPackedSprites.push(...packed);
     }
     const finalSprites = this.splitByMaxSize(allPackedSprites);
+    if (input.dryRun) {
+      const manifest2 = this.buildManifest(finalSprites);
+      return {
+        cssFiles: /* @__PURE__ */ new Map(),
+        spriteImages: /* @__PURE__ */ new Map(),
+        manifest: manifest2,
+        skippedImages: skipped,
+        dryRunReport: this.buildDryRunReport(finalSprites, skipped, assets.length)
+      };
+    }
     const spriteImages = await generateSprites(finalSprites, this.config);
     let retinaInfo;
     if (this.config.output.retina) {
@@ -583,6 +610,33 @@ var Spriter = class {
     }
     return manifest;
   }
+  buildDryRunReport(packedSprites, skipped, totalAssets) {
+    const lines = [];
+    lines.push("");
+    lines.push("\u{1F4CB} Dry-run report");
+    lines.push("\u2500".repeat(50));
+    lines.push(`Images found:    ${totalAssets}`);
+    lines.push(`Images sprited:  ${totalAssets - skipped.length}`);
+    lines.push(`Images skipped:  ${skipped.length}`);
+    lines.push(`Sprite sheets:   ${packedSprites.length}`);
+    lines.push("");
+    for (const sprite of packedSprites) {
+      lines.push(`\u{1F4C4} ${sprite.spriteFile} (${sprite.canvasWidth}\xD7${sprite.canvasHeight}px)`);
+      lines.push(`   Contains ${sprite.items.length} image(s):`);
+      for (const item of sprite.items) {
+        lines.push(`   \u2022 ${item.asset.url} \u2192 (${item.x}, ${item.y}) ${item.width}\xD7${item.height}`);
+      }
+      lines.push("");
+    }
+    if (skipped.length > 0) {
+      lines.push(`\u26A0\uFE0F  Skipped (${skipped.length}):`);
+      for (const url of skipped) {
+        lines.push(`   \u2022 ${url}`);
+      }
+      lines.push("");
+    }
+    return lines.join("\n");
+  }
 };
 
 // src/plugin-helper.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ispriter/core",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -10,31 +10,34 @@
       "types": "./dist/index.d.ts"
     }
   },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run"
+  },
   "dependencies": {
+    "@ispriter/shared": "workspace:*",
     "clean-css": "^5.3.0",
     "postcss": "^8.5.0",
     "postcss-import": "^16.1.1",
     "sharp": "^0.33.0",
-    "zod": "^3.24.0",
-    "@ispriter/shared": "2.0.0"
+    "zod": "^3.24.0"
   },
   "devDependencies": {
     "@types/clean-css": "^4.2.0",
     "tsup": "^8.4.0",
-    "vitest": "^3.1.0"
+    "vitest": "^3.1.0",
+    "zod-to-json-schema": "^3.25.2"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=20.0.0"
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-The MIT License (MIT)
-
-Copyright (c) 2014 iazrael.
-
-Permission is hereby granted,  free of charge,  to any person obtaining a
-copy of this software and associated documentation files (the "Software"),
-to deal in the Software without restriction, including without limitation
-the rights to  use, copy, modify, merge, publish, distribute, sublicense,
-and/or sell copies of the Software, and to permit persons to whom the
-Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
-DEALINGS IN THE SOFTWARE.