@decantr/vite-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Decantr AI
+
+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.

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { Plugin } from 'vite';
+export { EssenceFile, GuardContext, GuardViolation } from '@decantr/essence-spec';
+
+interface DecantrPluginOptions {
+    /** Path to the essence file, relative to project root. Default: 'decantr.essence.json' */
+    essencePath?: string;
+    /** Debounce delay in ms before running guard after a file change. Default: 300 */
+    debounceMs?: number;
+}
+declare function decantrPlugin(options?: DecantrPluginOptions): Plugin;
+
+export { type DecantrPluginOptions, decantrPlugin, decantrPlugin as default };

package/dist/index.js

@@ -0,0 +1,136 @@
+// src/index.ts
+import { join } from "path";
+import { evaluateGuard } from "@decantr/essence-spec";
+
+// src/watcher.ts
+import { readFileSync, existsSync } from "fs";
+import { normalizeEssence } from "@decantr/essence-spec";
+function loadEssence(filePath) {
+  if (!existsSync(filePath)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(filePath, "utf-8"));
+    return normalizeEssence(raw);
+  } catch {
+    return null;
+  }
+}
+var TRIGGER_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".vue",
+  ".svelte",
+  ".astro"
+]);
+var IGNORE_PATTERNS = [
+  "node_modules",
+  ".decantr",
+  "decantr.essence.json"
+];
+function shouldTriggerGuard(filePath) {
+  if (IGNORE_PATTERNS.some((p) => filePath.includes(p))) return false;
+  const ext = filePath.slice(filePath.lastIndexOf("."));
+  return TRIGGER_EXTENSIONS.has(ext);
+}
+function createDebouncedGuard(callback, delayMs) {
+  let timer = null;
+  return () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      callback();
+    }, delayMs);
+  };
+}
+
+// src/overlay.ts
+function formatViolation(v) {
+  const layerTag = v.layer ? `[${v.layer === "dna" ? "DNA" : "Blueprint"}] ` : "";
+  const fixHint = v.autoFixable ? " (auto-fixable via decantr_accept_drift)" : "";
+  return `${layerTag}[${v.rule}] ${v.message}${fixHint}`;
+}
+function formatViolations(violations) {
+  if (violations.length === 0) return null;
+  const errors = violations.filter((v) => v.severity === "error");
+  const warnings = violations.filter((v) => v.severity === "warning");
+  const sections = [];
+  if (errors.length > 0) {
+    sections.push("Errors:");
+    for (const v of errors) {
+      sections.push(`  ${formatViolation(v)}`);
+    }
+  }
+  if (warnings.length > 0) {
+    if (sections.length > 0) sections.push("");
+    sections.push("Warnings:");
+    for (const v of warnings) {
+      sections.push(`  ${formatViolation(v)}`);
+    }
+  }
+  return {
+    id: "decantr-guard",
+    message: `Decantr: ${violations.length} guard violation${violations.length === 1 ? "" : "s"} detected`,
+    frame: sections.join("\n"),
+    plugin: "@decantr/vite-plugin"
+  };
+}
+
+// src/index.ts
+function decantrPlugin(options = {}) {
+  const essenceFileName = options.essencePath ?? "decantr.essence.json";
+  const debounceMs = options.debounceMs ?? 300;
+  let essence = null;
+  let root = "";
+  function runGuard(server) {
+    const essencePath = join(root, essenceFileName);
+    essence = loadEssence(essencePath);
+    if (!essence) {
+      server.hot.send({
+        type: "error",
+        err: { message: "", stack: "", plugin: "@decantr/vite-plugin" }
+      });
+      return;
+    }
+    const violations = evaluateGuard(essence, {});
+    const overlayError = formatViolations(violations);
+    if (overlayError) {
+      server.config.logger.warn(
+        `[decantr] ${violations.length} guard violation(s) detected`,
+        { timestamp: true }
+      );
+      server.hot.send({
+        type: "error",
+        err: {
+          message: overlayError.message,
+          stack: overlayError.frame,
+          plugin: overlayError.plugin
+        }
+      });
+    }
+  }
+  return {
+    name: "decantr-guard",
+    configureServer(server) {
+      root = server.config.root;
+      const debouncedGuard = createDebouncedGuard(() => runGuard(server), debounceMs);
+      server.httpServer?.once("listening", () => {
+        runGuard(server);
+      });
+      server.watcher.on("change", (filePath) => {
+        const relative = filePath.startsWith(root) ? filePath.slice(root.length + 1) : filePath;
+        if (relative === essenceFileName || relative.endsWith("decantr.essence.json")) {
+          runGuard(server);
+        } else if (shouldTriggerGuard(relative)) {
+          debouncedGuard();
+        }
+      });
+    }
+  };
+}
+var index_default = decantrPlugin;
+export {
+  decantrPlugin,
+  index_default as default
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/watcher.ts","../src/overlay.ts"],"sourcesContent":["import type { Plugin, ViteDevServer } from 'vite';\nimport { join } from 'node:path';\nimport { evaluateGuard } from '@decantr/essence-spec';\nimport type { EssenceFile } from '@decantr/essence-spec';\nimport { loadEssence, shouldTriggerGuard, createDebouncedGuard } from './watcher.js';\nimport { formatViolations } from './overlay.js';\n\nexport interface DecantrPluginOptions {\n  /** Path to the essence file, relative to project root. Default: 'decantr.essence.json' */\n  essencePath?: string;\n  /** Debounce delay in ms before running guard after a file change. Default: 300 */\n  debounceMs?: number;\n}\n\nexport function decantrPlugin(options: DecantrPluginOptions = {}): Plugin {\n  const essenceFileName = options.essencePath ?? 'decantr.essence.json';\n  const debounceMs = options.debounceMs ?? 300;\n\n  let essence: EssenceFile | null = null;\n  let root = '';\n\n  function runGuard(server: ViteDevServer): void {\n    const essencePath = join(root, essenceFileName);\n    essence = loadEssence(essencePath);\n\n    if (!essence) {\n      server.hot.send({\n        type: 'error',\n        err: { message: '', stack: '', plugin: '@decantr/vite-plugin' },\n      });\n      return;\n    }\n\n    const violations = evaluateGuard(essence, {});\n    const overlayError = formatViolations(violations);\n\n    if (overlayError) {\n      server.config.logger.warn(\n        `[decantr] ${violations.length} guard violation(s) detected`,\n        { timestamp: true },\n      );\n      server.hot.send({\n        type: 'error',\n        err: {\n          message: overlayError.message,\n          stack: overlayError.frame,\n          plugin: overlayError.plugin,\n        },\n      });\n    }\n  }\n\n  return {\n    name: 'decantr-guard',\n\n    configureServer(server) {\n      root = server.config.root;\n\n      const debouncedGuard = createDebouncedGuard(() => runGuard(server), debounceMs);\n\n      server.httpServer?.once('listening', () => {\n        runGuard(server);\n      });\n\n      server.watcher.on('change', (filePath: string) => {\n        const relative = filePath.startsWith(root)\n          ? filePath.slice(root.length + 1)\n          : filePath;\n\n        if (relative === essenceFileName || relative.endsWith('decantr.essence.json')) {\n          runGuard(server);\n        } else if (shouldTriggerGuard(relative)) {\n          debouncedGuard();\n        }\n      });\n    },\n  };\n}\n\nexport default decantrPlugin;\nexport type { GuardViolation, GuardContext, EssenceFile } from '@decantr/essence-spec';\n","import { readFileSync, existsSync } from 'node:fs';\nimport { normalizeEssence } from '@decantr/essence-spec';\nimport type { EssenceFile } from '@decantr/essence-spec';\n\nexport function loadEssence(filePath: string): EssenceFile | null {\n  if (!existsSync(filePath)) return null;\n\n  try {\n    const raw = JSON.parse(readFileSync(filePath, 'utf-8'));\n    return normalizeEssence(raw);\n  } catch {\n    return null;\n  }\n}\n\nconst TRIGGER_EXTENSIONS = new Set([\n  '.ts', '.tsx', '.js', '.jsx', '.vue', '.svelte', '.astro',\n]);\n\nconst IGNORE_PATTERNS = [\n  'node_modules',\n  '.decantr',\n  'decantr.essence.json',\n];\n\nexport function shouldTriggerGuard(filePath: string): boolean {\n  if (IGNORE_PATTERNS.some(p => filePath.includes(p))) return false;\n\n  const ext = filePath.slice(filePath.lastIndexOf('.'));\n  return TRIGGER_EXTENSIONS.has(ext);\n}\n\nexport function createDebouncedGuard(\n  callback: () => void,\n  delayMs: number,\n): () => void {\n  let timer: ReturnType<typeof setTimeout> | null = null;\n\n  return () => {\n    if (timer) clearTimeout(timer);\n    timer = setTimeout(() => {\n      timer = null;\n      callback();\n    }, delayMs);\n  };\n}\n","import type { GuardViolation } from '@decantr/essence-spec';\n\nexport interface OverlayError {\n  id: string;\n  message: string;\n  frame: string;\n  plugin: string;\n}\n\nexport function formatViolation(v: GuardViolation): string {\n  const layerTag = v.layer ? `[${v.layer === 'dna' ? 'DNA' : 'Blueprint'}] ` : '';\n  const fixHint = v.autoFixable ? ' (auto-fixable via decantr_accept_drift)' : '';\n  return `${layerTag}[${v.rule}] ${v.message}${fixHint}`;\n}\n\nexport function formatViolations(violations: GuardViolation[]): OverlayError | null {\n  if (violations.length === 0) return null;\n\n  const errors = violations.filter(v => v.severity === 'error');\n  const warnings = violations.filter(v => v.severity === 'warning');\n\n  const sections: string[] = [];\n\n  if (errors.length > 0) {\n    sections.push('Errors:');\n    for (const v of errors) {\n      sections.push(`  ${formatViolation(v)}`);\n    }\n  }\n\n  if (warnings.length > 0) {\n    if (sections.length > 0) sections.push('');\n    sections.push('Warnings:');\n    for (const v of warnings) {\n      sections.push(`  ${formatViolation(v)}`);\n    }\n  }\n\n  return {\n    id: 'decantr-guard',\n    message: `Decantr: ${violations.length} guard violation${violations.length === 1 ? '' : 's'} detected`,\n    frame: sections.join('\\n'),\n    plugin: '@decantr/vite-plugin',\n  };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@decantr/vite-plugin",
+  "version": "0.1.0",
+  "description": "Vite plugin for real-time Decantr design drift detection",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/decantr-ai/decantr.git",
+    "directory": "packages/vite-plugin"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@decantr/essence-spec": "1.0.0-beta.6"
+  },
+  "peerDependencies": {
+    "vite": "^5.0.0 || ^6.0.0"
+  },
+  "devDependencies": {
+    "vite": "^6.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}