@kinotic-ai/spawn 0.4.0 → 0.5.0

package/dist/graal-spawn-renderer.js

@@ -14,7 +14,7 @@
       });
   };
 
-  // ../../node_modules/.bun/liquidjs@10.25.7/node_modules/liquidjs/dist/liquid.browser.mjs
+  // ../../node_modules/.bun/liquidjs@10.27.0/node_modules/liquidjs/dist/liquid.browser.mjs
   class Token {
     constructor(kind, input, begin, end, file) {
       this.kind = kind;
@@ -154,10 +154,10 @@
   }
   function pad(str, length, ch, add) {
     str = String(str);
-    let n = length - str.length;
-    while (n-- > 0)
-      str = add(str, ch);
-    return str;
+    const n = length - str.length;
+    if (n <= 0)
+      return str;
+    return add(str, ch.repeat(n));
   }
   function identify(val) {
     return val;
@@ -703,8 +703,10 @@ From ` + this.originalError.stack;
     m: (d) => d.getMonth() + 1,
     M: (d) => d.getMinutes(),
     N: (d, opts) => {
+      var _a;
       const width = Number(opts.width) || 9;
       const str = String(d.getMilliseconds()).slice(0, width);
+      (_a = opts.memoryLimit) === null || _a === undefined || _a.use(width - str.length);
       return padEnd(str, width, "0");
     },
     p: (d) => d.getHours() < 12 ? "AM" : "PM",
@@ -728,18 +730,18 @@ From ` + this.originalError.stack;
     "%": () => "%"
   };
   formatCodes.h = formatCodes.b;
-  function strftime(d, formatStr) {
+  function strftime(d, formatStr, memoryLimit) {
     let output = "";
     let remaining = formatStr;
     let match;
     while (match = rFormat.exec(remaining)) {
       output += remaining.slice(0, match.index);
       remaining = remaining.slice(match.index + match[0].length);
-      output += format(d, match);
+      output += format(d, match, memoryLimit);
     }
     return output + remaining;
   }
-  function format(d, match) {
+  function format(d, match, memoryLimit) {
     const [input, flagStr = "", width, modifier, conversion] = match;
     const convert = formatCodes[conversion];
     if (!convert)
@@ -747,7 +749,7 @@ From ` + this.originalError.stack;
     const flags = {};
     for (const flag of flagStr)
       flags[flag] = true;
-    let ret = String(convert(d, { flags, width, modifier }));
+    let ret = String(convert(d, { flags, width, modifier, memoryLimit }));
     let padChar = padSpaceChars.has(conversion) ? " " : "0";
     let padWidth = width || padWidths[conversion] || 0;
     if (flags["^"])
@@ -760,6 +762,7 @@ From ` + this.originalError.stack;
       padChar = "0";
     if (flags["-"])
       padWidth = 0;
+    memoryLimit === null || memoryLimit === undefined || memoryLimit.use(Number(padWidth) - ret.length);
     return padStart(ret, padWidth, padChar);
   }
   function getDateTimeFormat() {
@@ -1192,6 +1195,7 @@ From ` + this.originalError.stack;
       if (!emitter) {
         emitter = ctx.opts.keepOutputType ? new KeepingTypeEmitter : new SimpleEmitter;
       }
+      ctx.renderLimit.check(getPerformance().now());
       const errors = [];
       for (const tpl of templates) {
         ctx.renderLimit.check(getPerformance().now());
@@ -1577,7 +1581,28 @@ From ` + this.originalError.stack;
   function strip_html(v) {
     const str = stringify(v);
     this.context.memoryLimit.use(str.length);
-    return str.replace(/<script[\s\S]*?<\/script>|<style[\s\S]*?<\/style>|<.*?>|<!--[\s\S]*?-->/g, "");
+    const blocks = new Map([["<script", "</script>"], ["<style", "</style>"], ["<!--", "-->"], ["<", ">"]]);
+    let out = "";
+    let i = 0;
+    while (i < str.length) {
+      const lt = str.indexOf("<", i);
+      if (lt < 0)
+        return out + str.slice(i);
+      out += str.slice(i, lt);
+      for (const [opener, closer] of blocks) {
+        if (!str.startsWith(opener, lt))
+          continue;
+        const e = str.indexOf(closer, lt + opener.length);
+        if (e >= 0) {
+          i = e + closer.length;
+          break;
+        }
+        blocks.delete(opener);
+      }
+      if (i === lt)
+        return out + str.slice(lt);
+    }
+    return out;
   }
   var htmlFilters = /* @__PURE__ */ Object.freeze({
     __proto__: null,
@@ -2845,10 +2870,17 @@ From ` + this.originalError.stack;
   function getKind(val) {
     return val ? val.kind : -1;
   }
+  function createScope(from) {
+    const scope = Object.create(null);
+    if (from)
+      Object.assign(scope, from);
+    return scope;
+  }
+
   class Context {
     constructor(env = {}, opts = defaultOptions, renderOptions = {}, { memoryLimit, renderLimit } = {}) {
       var _a, _b, _c, _d, _e;
-      this.scopes = [{}];
+      this.scopes = [createScope()];
       this.registers = {};
       this.breakCalled = false;
       this.continueCalled = false;
@@ -2913,7 +2945,8 @@ From ` + this.originalError.stack;
       return new Context(scope, this.opts, {
         sync: this.sync,
         globals: this.globals,
-        strictVariables: this.strictVariables
+        strictVariables: this.strictVariables,
+        ownPropertyOnly: this.ownPropertyOnly
       }, {
         renderLimit: this.renderLimit,
         memoryLimit: this.memoryLimit
@@ -3307,15 +3340,16 @@ From ` + this.originalError.stack;
     sample
   });
   function date(v, format2, timezoneOffset) {
-    var _a, _b, _c;
-    const size2 = ((_a = v === null || v === undefined ? undefined : v.length) !== null && _a !== undefined ? _a : 0) + ((_b = format2 === null || format2 === undefined ? undefined : format2.length) !== null && _b !== undefined ? _b : 0) + ((_c = timezoneOffset === null || timezoneOffset === undefined ? undefined : timezoneOffset.length) !== null && _c !== undefined ? _c : 0);
+    var _a, _b;
+    const size2 = ((_a = v === null || v === undefined ? undefined : v.length) !== null && _a !== undefined ? _a : 0) + ((_b = timezoneOffset === null || timezoneOffset === undefined ? undefined : timezoneOffset.length) !== null && _b !== undefined ? _b : 0);
     this.context.memoryLimit.use(size2);
     const date2 = parseDate(v, this.context.opts, timezoneOffset);
     if (!date2)
       return v;
     format2 = toValue(format2);
     format2 = isNil(format2) ? this.context.opts.dateFormat : stringify(format2);
-    return strftime(date2, format2);
+    this.context.memoryLimit.use(format2.length);
+    return strftime(date2, format2, this.context.memoryLimit);
   }
   function date_to_xmlschema(v) {
     return date.call(this, v, "%Y-%m-%dT%H:%M:%S%:z");
@@ -3333,11 +3367,12 @@ From ` + this.originalError.stack;
     const date2 = parseDate(v, this.context.opts);
     if (!date2)
       return v;
+    const ml = this.context.memoryLimit;
     if (type === "ordinal") {
       const d = date2.getDate();
-      return style === "US" ? strftime(date2, `${month_type} ${d}%q, %Y`) : strftime(date2, `${d}%q ${month_type} %Y`);
+      return style === "US" ? strftime(date2, `${month_type} ${d}%q, %Y`, ml) : strftime(date2, `${d}%q ${month_type} %Y`, ml);
     }
-    return strftime(date2, `%d ${month_type} %Y`);
+    return strftime(date2, `%d ${month_type} %Y`, ml);
   }
   function parseDate(v, opts, timezoneOffset) {
     let date2;
@@ -3609,7 +3644,46 @@ From ` + this.originalError.stack;
     base64_encode,
     base64_decode
   });
-  var filters = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, htmlFilters), mathFilters), urlFilters), arrayFilters), dateFilters), stringFilters), base64Filters), misc);
+  function bufferToHex(buffer) {
+    const bytes = new Uint8Array(buffer);
+    let hex = "";
+    for (let i = 0;i < bytes.length; i++) {
+      hex += bytes[i].toString(16).padStart(2, "0");
+    }
+    return hex;
+  }
+  function sha256(str) {
+    return __awaiter(this, undefined, undefined, function* () {
+      const data = new TextEncoder().encode(str);
+      const digest = yield crypto.subtle.digest("SHA-256", data);
+      return bufferToHex(digest);
+    });
+  }
+  function hmacSha256(str, key) {
+    return __awaiter(this, undefined, undefined, function* () {
+      const encoder = new TextEncoder;
+      const cryptoKey = yield crypto.subtle.importKey("raw", encoder.encode(key), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+      const signature = yield crypto.subtle.sign("HMAC", cryptoKey, encoder.encode(str));
+      return bufferToHex(signature);
+    });
+  }
+  function sha256$1(value) {
+    const str = stringify(value);
+    this.context.memoryLimit.use(str.length);
+    return sha256(str);
+  }
+  function hmac_sha256(value, key) {
+    const str = stringify(value);
+    const keyStr = stringify(key);
+    this.context.memoryLimit.use(str.length + keyStr.length);
+    return hmacSha256(str, keyStr);
+  }
+  var cryptoFilters = /* @__PURE__ */ Object.freeze({
+    __proto__: null,
+    sha256: sha256$1,
+    hmac_sha256
+  });
+  var filters = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, htmlFilters), mathFilters), urlFilters), arrayFilters), dateFilters), stringFilters), base64Filters), cryptoFilters), misc);
 
   class AssignTag extends Tag {
     constructor(token, remainTokens, liquid) {
@@ -3668,7 +3742,7 @@ From ` + this.originalError.stack;
         return;
       }
       const continueKey = "continue-" + this.variable + "-" + this.collection.getText();
-      ctx.push({ continue: ctx.getRegister(continueKey, {}) });
+      ctx.push(createScope({ continue: ctx.getRegister(continueKey, {}) }));
       const hash = yield this.hash.render(ctx);
       ctx.pop();
       const modifiers = this.liquid.options.orderedFilterParameters ? Object.keys(hash).filter((x) => MODIFIERS.includes(x)) : MODIFIERS.filter((x) => hash[x] !== undefined);
@@ -3680,7 +3754,7 @@ From ` + this.originalError.stack;
         return reversed(collection2);
       }, collection);
       ctx.setRegister(continueKey, (hash["offset"] || 0) + collection.length);
-      const scope = { forloop: new ForloopDrop(collection.length, this.collection.getText(), this.variable) };
+      const scope = createScope({ forloop: new ForloopDrop(collection.length, this.collection.getText(), this.variable) });
       ctx.push(scope);
       for (const item of collection) {
         scope[this.variable] = item;
@@ -4006,11 +4080,11 @@ From ` + this.originalError.stack;
       const saved = ctx.saveRegister("blocks", "blockMode");
       ctx.setRegister("blocks", {});
       ctx.setRegister("blockMode", BlockMode.OUTPUT);
-      const scope = yield hash.render(ctx);
+      const scope = createScope(yield hash.render(ctx));
       if (withVar)
         scope[filepath] = yield evalToken(withVar, ctx);
       const templates = yield liquid._parsePartialFile(filepath, ctx.sync, this["currentFile"]);
-      ctx.push(ctx.opts.jekyllInclude ? { include: scope } : scope);
+      ctx.push(ctx.opts.jekyllInclude ? createScope({ include: scope }) : scope);
       yield renderer.renderTemplates(templates, ctx, emitter);
       ctx.pop();
       ctx.restoreRegister(saved);
@@ -4199,7 +4273,7 @@ From ` + this.originalError.stack;
       if (blocks[""] === undefined)
         blocks[""] = (parent, emitter2) => emitter2.write(html);
       ctx.setRegister("blockMode", BlockMode.OUTPUT);
-      ctx.push(yield args.render(ctx));
+      ctx.push(createScope(yield args.render(ctx)));
       yield renderer.renderTemplates(templates, ctx, emitter);
       ctx.pop();
     }
@@ -4259,7 +4333,7 @@ From ` + this.originalError.stack;
         if (stack.includes(self))
           throw new Error("block tag cannot be nested");
         stack.push(self);
-        ctx.push({ block: superBlock });
+        ctx.push(createScope({ block: superBlock }));
         yield liquid.renderer.renderTemplates(templates, ctx, emitter);
         ctx.pop();
         stack.pop();
@@ -4343,7 +4417,7 @@ From ` + this.originalError.stack;
       const cols = args.cols || collection.length;
       const r = this.liquid.renderer;
       const tablerowloop = new TablerowloopDrop(collection.length, cols, this.collection.getText(), this.variable);
-      const scope = { tablerowloop };
+      const scope = createScope({ tablerowloop });
       ctx.push(scope);
       for (let idx = 0;idx < collection.length; idx++, tablerowloop.next()) {
         scope[this.variable] = collection[idx];
@@ -4516,8 +4590,8 @@ From ` + this.originalError.stack;
   class Liquid {
     constructor(opts = {}) {
       this.renderer = new Render;
-      this.filters = {};
-      this.tags = {};
+      this.filters = Object.create(null);
+      this.tags = Object.create(null);
       this.options = normalize(opts);
       this.parser = new Parser(this);
       forOwn(tags, (conf, name) => this.registerTag(name, conf));
@@ -19014,23 +19088,7 @@ From ` + this.originalError.stack;
       this.engine.registerFilter("upperFirst", (v) => upperFirst(v));
     }
     async renderSpawn(spawn, options) {
-      const trees = [spawn];
-      const configs = [];
-      let currentConfig = this.parseConfig(spawn);
-      if (currentConfig) {
-        configs.push(currentConfig);
-      }
-      while (currentConfig?.inherits) {
-        if (!options?.loadInherited) {
-          throw new Error(`Spawn inherits '${currentConfig.inherits}' but no loadInherited callback was provided`);
-        }
-        const inherited = await options.loadInherited(currentConfig.inherits);
-        trees.push(inherited);
-        currentConfig = this.parseConfig(inherited);
-        if (currentConfig) {
-          configs.push(currentConfig);
-        }
-      }
+      const { trees, configs } = await this.walkInheritance(spawn, options?.loadInherited);
       let globals = {};
       let propertySchemas = {};
       for (const config2 of [...configs].reverse()) {
@@ -19069,6 +19127,69 @@ From ` + this.originalError.stack;
       }
       return { files, sources, context };
     }
+    async lint(spawn, options) {
+      const { trees, configs } = await this.walkInheritance(spawn, options?.loadInherited);
+      const declared = new Set;
+      for (const config2 of configs) {
+        if (config2.globals) {
+          Object.keys(config2.globals).forEach((key) => declared.add(key));
+        }
+        if (config2.propertySchema) {
+          Object.keys(config2.propertySchema).forEach((key) => declared.add(key));
+        }
+      }
+      const usedIn = new Map;
+      const record2 = (name, file2) => {
+        let files = usedIn.get(name);
+        if (!files) {
+          files = new Set;
+          usedIn.set(name, files);
+        }
+        files.add(file2);
+      };
+      const externalVars = (template) => Object.keys(this.engine.parseAndAnalyzeSync(template, undefined, { partials: false }).globals);
+      for (const tree of trees) {
+        for (const source of Object.keys(tree)) {
+          const fileName = source.substring(source.lastIndexOf("/") + 1);
+          if (IGNORED_FILE_NAMES.includes(fileName)) {
+            continue;
+          }
+          externalVars(source).forEach((name) => record2(name, source));
+          const content = tree[source];
+          if (source.endsWith(".liquid") && typeof content === "string") {
+            externalVars(content).forEach((name) => record2(name, source));
+          }
+        }
+      }
+      const undeclared = [];
+      for (const [name, files] of usedIn) {
+        if (!declared.has(name)) {
+          undeclared.push({ name, files: [...files].sort() });
+        }
+      }
+      undeclared.sort((a, b) => a.name.localeCompare(b.name));
+      return { undeclared };
+    }
+    async walkInheritance(spawn, loadInherited) {
+      const trees = [spawn];
+      const configs = [];
+      let currentConfig = this.parseConfig(spawn);
+      if (currentConfig) {
+        configs.push(currentConfig);
+      }
+      while (currentConfig?.inherits) {
+        if (!loadInherited) {
+          throw new Error(`Spawn inherits '${currentConfig.inherits}' but no loadInherited callback was provided`);
+        }
+        const inherited = await loadInherited(currentConfig.inherits);
+        trees.push(inherited);
+        currentConfig = this.parseConfig(inherited);
+        if (currentConfig) {
+          configs.push(currentConfig);
+        }
+      }
+      return { trees, configs };
+    }
     parseConfig(tree) {
       const raw2 = tree["spawn.json"];
       if (raw2 === undefined) {

package/dist/index.cjs

@@ -104,23 +104,7 @@ class SpawnEngine {
     this.engine.registerFilter("upperFirst", (v) => upperFirst(v));
   }
   async renderSpawn(spawn, options) {
-    const trees = [spawn];
-    const configs = [];
-    let currentConfig = this.parseConfig(spawn);
-    if (currentConfig) {
-      configs.push(currentConfig);
-    }
-    while (currentConfig?.inherits) {
-      if (!options?.loadInherited) {
-        throw new Error(`Spawn inherits '${currentConfig.inherits}' but no loadInherited callback was provided`);
-      }
-      const inherited = await options.loadInherited(currentConfig.inherits);
-      trees.push(inherited);
-      currentConfig = this.parseConfig(inherited);
-      if (currentConfig) {
-        configs.push(currentConfig);
-      }
-    }
+    const { trees, configs } = await this.walkInheritance(spawn, options?.loadInherited);
     let globals = {};
     let propertySchemas = {};
     for (const config of [...configs].reverse()) {
@@ -159,6 +143,69 @@ class SpawnEngine {
     }
     return { files, sources, context };
   }
+  async lint(spawn, options) {
+    const { trees, configs } = await this.walkInheritance(spawn, options?.loadInherited);
+    const declared = new Set;
+    for (const config of configs) {
+      if (config.globals) {
+        Object.keys(config.globals).forEach((key) => declared.add(key));
+      }
+      if (config.propertySchema) {
+        Object.keys(config.propertySchema).forEach((key) => declared.add(key));
+      }
+    }
+    const usedIn = new Map;
+    const record = (name, file) => {
+      let files = usedIn.get(name);
+      if (!files) {
+        files = new Set;
+        usedIn.set(name, files);
+      }
+      files.add(file);
+    };
+    const externalVars = (template) => Object.keys(this.engine.parseAndAnalyzeSync(template, undefined, { partials: false }).globals);
+    for (const tree of trees) {
+      for (const source of Object.keys(tree)) {
+        const fileName = source.substring(source.lastIndexOf("/") + 1);
+        if (IGNORED_FILE_NAMES.includes(fileName)) {
+          continue;
+        }
+        externalVars(source).forEach((name) => record(name, source));
+        const content = tree[source];
+        if (source.endsWith(".liquid") && typeof content === "string") {
+          externalVars(content).forEach((name) => record(name, source));
+        }
+      }
+    }
+    const undeclared = [];
+    for (const [name, files] of usedIn) {
+      if (!declared.has(name)) {
+        undeclared.push({ name, files: [...files].sort() });
+      }
+    }
+    undeclared.sort((a, b) => a.name.localeCompare(b.name));
+    return { undeclared };
+  }
+  async walkInheritance(spawn, loadInherited) {
+    const trees = [spawn];
+    const configs = [];
+    let currentConfig = this.parseConfig(spawn);
+    if (currentConfig) {
+      configs.push(currentConfig);
+    }
+    while (currentConfig?.inherits) {
+      if (!loadInherited) {
+        throw new Error(`Spawn inherits '${currentConfig.inherits}' but no loadInherited callback was provided`);
+      }
+      const inherited = await loadInherited(currentConfig.inherits);
+      trees.push(inherited);
+      currentConfig = this.parseConfig(inherited);
+      if (currentConfig) {
+        configs.push(currentConfig);
+      }
+    }
+    return { trees, configs };
+  }
   parseConfig(tree) {
     const raw = tree["spawn.json"];
     if (raw === undefined) {

package/dist/index.d.cts

@@ -61,6 +61,31 @@ interface RenderSpawnOptions {
 	loadInherited?: (ref: string) => Promise<SpawnTree>;
 }
 /**
+* A variable referenced in a spawn's templates that is declared neither in
+* propertySchema nor in globals, reported by {@link SpawnEngine#lint}.
+*
+* @see SpawnLintResult
+*/
+interface UndeclaredVariable {
+	/** The variable name as referenced in the templates. */
+	name: string;
+	/**
+	* The spawn paths where the variable appears — file contents for
+	* {@code .liquid} files, and path templates for any file whose path contains
+	* the variable.
+	*/
+	files: string[];
+}
+/**
+* The outcome of {@link SpawnEngine#lint}: the variables a spawn's templates
+* reference that are not declared in propertySchema or globals. A spawn is
+* lint-clean when {@code undeclared} is empty.
+*/
+interface SpawnLintResult {
+	/** Referenced-but-undeclared variables, sorted by name. */
+	undeclared: UndeclaredVariable[];
+}
+/**
 * The outcome of rendering a spawn.
 */
 interface SpawnRenderResult {
@@ -113,7 +138,18 @@ declare class SpawnEngine {
 	* context used, including values added by the property resolver.
 	*/
 	renderSpawn(spawn: SpawnTree, options?: RenderSpawnOptions): Promise<SpawnRenderResult>;
+	/**
+	* Reports the variables a spawn's templates reference that are declared
+	* neither in propertySchema nor in globals, across the full inheritance
+	* chain. Variables come from the path of every file plus the contents of
+	* {@code .liquid} files; registered filters are not mistaken for variables.
+	* A clean spawn has an empty {@code undeclared} list.
+	*/
+	lint(spawn: SpawnTree, options?: {
+		loadInherited?: (ref: string) => Promise<SpawnTree>;
+	}): Promise<SpawnLintResult>;
+	private walkInheritance;
 	private parseConfig;
 	private resolveMissingProperties;
 }
-export { SpawnTree, SpawnRenderResult, SpawnEngine, RenderSpawnOptions, PropertySchema, PropertyResolver };
+export { UndeclaredVariable, SpawnTree, SpawnRenderResult, SpawnLintResult, SpawnEngine, RenderSpawnOptions, PropertySchema, PropertyResolver };

package/dist/index.d.ts

@@ -61,6 +61,31 @@ interface RenderSpawnOptions {
 	loadInherited?: (ref: string) => Promise<SpawnTree>;
 }
 /**
+* A variable referenced in a spawn's templates that is declared neither in
+* propertySchema nor in globals, reported by {@link SpawnEngine#lint}.
+*
+* @see SpawnLintResult
+*/
+interface UndeclaredVariable {
+	/** The variable name as referenced in the templates. */
+	name: string;
+	/**
+	* The spawn paths where the variable appears — file contents for
+	* {@code .liquid} files, and path templates for any file whose path contains
+	* the variable.
+	*/
+	files: string[];
+}
+/**
+* The outcome of {@link SpawnEngine#lint}: the variables a spawn's templates
+* reference that are not declared in propertySchema or globals. A spawn is
+* lint-clean when {@code undeclared} is empty.
+*/
+interface SpawnLintResult {
+	/** Referenced-but-undeclared variables, sorted by name. */
+	undeclared: UndeclaredVariable[];
+}
+/**
 * The outcome of rendering a spawn.
 */
 interface SpawnRenderResult {
@@ -113,7 +138,18 @@ declare class SpawnEngine {
 	* context used, including values added by the property resolver.
 	*/
 	renderSpawn(spawn: SpawnTree, options?: RenderSpawnOptions): Promise<SpawnRenderResult>;
+	/**
+	* Reports the variables a spawn's templates reference that are declared
+	* neither in propertySchema nor in globals, across the full inheritance
+	* chain. Variables come from the path of every file plus the contents of
+	* {@code .liquid} files; registered filters are not mistaken for variables.
+	* A clean spawn has an empty {@code undeclared} list.
+	*/
+	lint(spawn: SpawnTree, options?: {
+		loadInherited?: (ref: string) => Promise<SpawnTree>;
+	}): Promise<SpawnLintResult>;
+	private walkInheritance;
 	private parseConfig;
 	private resolveMissingProperties;
 }
-export { SpawnTree, SpawnRenderResult, SpawnEngine, RenderSpawnOptions, PropertySchema, PropertyResolver };
+export { UndeclaredVariable, SpawnTree, SpawnRenderResult, SpawnLintResult, SpawnEngine, RenderSpawnOptions, PropertySchema, PropertyResolver };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   SpawnEngine
-} from "./shared/spawn-4k8xtpe9.js";
+} from "./shared/spawn-1h1k8w8r.js";
 export {
   SpawnEngine
 };

package/dist/node/index.cjs

@@ -64,6 +64,7 @@ var __export = (target, all) => {
 // packages/spawn/src/node/index.ts
 var exports_node = {};
 __export(exports_node, {
+  lintSpawnDir: () => lintSpawnDir,
   assertPathWithin: () => assertPathWithin,
   NodeSpawnRenderer: () => NodeSpawnRenderer
 });
@@ -108,23 +109,7 @@ class SpawnEngine {
     this.engine.registerFilter("upperFirst", (v) => upperFirst(v));
   }
   async renderSpawn(spawn, options) {
-    const trees = [spawn];
-    const configs = [];
-    let currentConfig = this.parseConfig(spawn);
-    if (currentConfig) {
-      configs.push(currentConfig);
-    }
-    while (currentConfig?.inherits) {
-      if (!options?.loadInherited) {
-        throw new Error(`Spawn inherits '${currentConfig.inherits}' but no loadInherited callback was provided`);
-      }
-      const inherited = await options.loadInherited(currentConfig.inherits);
-      trees.push(inherited);
-      currentConfig = this.parseConfig(inherited);
-      if (currentConfig) {
-        configs.push(currentConfig);
-      }
-    }
+    const { trees, configs } = await this.walkInheritance(spawn, options?.loadInherited);
     let globals = {};
     let propertySchemas = {};
     for (const config of [...configs].reverse()) {
@@ -163,6 +148,69 @@ class SpawnEngine {
     }
     return { files, sources, context };
   }
+  async lint(spawn, options) {
+    const { trees, configs } = await this.walkInheritance(spawn, options?.loadInherited);
+    const declared = new Set;
+    for (const config of configs) {
+      if (config.globals) {
+        Object.keys(config.globals).forEach((key) => declared.add(key));
+      }
+      if (config.propertySchema) {
+        Object.keys(config.propertySchema).forEach((key) => declared.add(key));
+      }
+    }
+    const usedIn = new Map;
+    const record = (name, file) => {
+      let files = usedIn.get(name);
+      if (!files) {
+        files = new Set;
+        usedIn.set(name, files);
+      }
+      files.add(file);
+    };
+    const externalVars = (template) => Object.keys(this.engine.parseAndAnalyzeSync(template, undefined, { partials: false }).globals);
+    for (const tree of trees) {
+      for (const source of Object.keys(tree)) {
+        const fileName = source.substring(source.lastIndexOf("/") + 1);
+        if (IGNORED_FILE_NAMES.includes(fileName)) {
+          continue;
+        }
+        externalVars(source).forEach((name) => record(name, source));
+        const content = tree[source];
+        if (source.endsWith(".liquid") && typeof content === "string") {
+          externalVars(content).forEach((name) => record(name, source));
+        }
+      }
+    }
+    const undeclared = [];
+    for (const [name, files] of usedIn) {
+      if (!declared.has(name)) {
+        undeclared.push({ name, files: [...files].sort() });
+      }
+    }
+    undeclared.sort((a, b) => a.name.localeCompare(b.name));
+    return { undeclared };
+  }
+  async walkInheritance(spawn, loadInherited) {
+    const trees = [spawn];
+    const configs = [];
+    let currentConfig = this.parseConfig(spawn);
+    if (currentConfig) {
+      configs.push(currentConfig);
+    }
+    while (currentConfig?.inherits) {
+      if (!loadInherited) {
+        throw new Error(`Spawn inherits '${currentConfig.inherits}' but no loadInherited callback was provided`);
+      }
+      const inherited = await loadInherited(currentConfig.inherits);
+      trees.push(inherited);
+      currentConfig = this.parseConfig(inherited);
+      if (currentConfig) {
+        configs.push(currentConfig);
+      }
+    }
+    return { trees, configs };
+  }
   parseConfig(tree) {
     const raw = tree["spawn.json"];
     if (raw === undefined) {
@@ -207,6 +255,36 @@ function assertContained(root, resolved) {
 function assertPathWithin(root, target) {
   return assertContained(root, import_node_path.default.resolve(root, target));
 }
+async function loadSpawnTree(dir) {
+  const tree = {};
+  const entries = await import_promises.default.readdir(dir, { recursive: true, withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isFile()) {
+      continue;
+    }
+    const filePath = import_node_path.default.join(entry.parentPath, entry.name);
+    const treePath = import_node_path.default.relative(dir, filePath).split(import_node_path.default.sep).join("/");
+    if (treePath.endsWith(".liquid")) {
+      tree[treePath] = await import_promises.default.readFile(filePath, { encoding: "utf8" });
+    } else {
+      tree[treePath] = await import_promises.default.readFile(filePath);
+    }
+  }
+  return tree;
+}
+function diskInheritanceLoader(spawnRoot) {
+  let currentDir = spawnRoot;
+  return async (ref) => {
+    currentDir = assertContained(spawnRoot, import_node_path.default.resolve(currentDir, ref));
+    if (!import_node_fs.default.existsSync(import_node_path.default.resolve(currentDir, "spawn.json"))) {
+      throw new Error(`Inherited spawn ${import_node_path.default.resolve(currentDir, "spawn.json")} does not exist`);
+    }
+    return loadSpawnTree(currentDir);
+  };
+}
+async function lintSpawnDir(dir) {
+  return new SpawnEngine().lint(await loadSpawnTree(dir), { loadInherited: diskInheritanceLoader(dir) });
+}
 
 class NodeSpawnRenderer {
   engine = new SpawnEngine;
@@ -214,38 +292,14 @@ class NodeSpawnRenderer {
     if (import_node_fs.default.existsSync(destination)) {
       throw new Error(`The target directory ${destination} already exists`);
     }
-    let currentDir = spawnDir;
-    const result = await this.engine.renderSpawn(await this.loadSpawnTree(spawnDir), {
+    const result = await this.engine.renderSpawn(await loadSpawnTree(spawnDir), {
       context: options?.context,
       propertyResolver: options?.propertyResolver,
-      loadInherited: async (ref) => {
-        currentDir = assertContained(spawnDir, import_node_path.default.resolve(currentDir, ref));
-        if (!import_node_fs.default.existsSync(import_node_path.default.resolve(currentDir, "spawn.json"))) {
-          throw new Error(`Inherited spawn ${import_node_path.default.resolve(currentDir, "spawn.json")} does not exist`);
-        }
-        return this.loadSpawnTree(currentDir);
-      }
+      loadInherited: diskInheritanceLoader(spawnDir)
     });
     await this.writeSpawnTree(result.files, destination);
     return result.context;
   }
-  async loadSpawnTree(dir) {
-    const tree = {};
-    const entries = await import_promises.default.readdir(dir, { recursive: true, withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isFile()) {
-        continue;
-      }
-      const filePath = import_node_path.default.join(entry.parentPath, entry.name);
-      const treePath = import_node_path.default.relative(dir, filePath).split(import_node_path.default.sep).join("/");
-      if (treePath.endsWith(".liquid")) {
-        tree[treePath] = await import_promises.default.readFile(filePath, { encoding: "utf8" });
-      } else {
-        tree[treePath] = await import_promises.default.readFile(filePath);
-      }
-    }
-    return tree;
-  }
   async writeSpawnTree(tree, destination) {
     await import_promises.default.mkdir(destination, { recursive: true });
     for (const [treePath, content] of Object.entries(tree)) {

package/dist/node/index.d.cts

@@ -31,6 +31,31 @@ interface PropertyResolver {
 	resolve(key: string, schema: PropertySchema, message: string, defaultValue?: unknown): Promise<unknown>;
 }
 /**
+* A variable referenced in a spawn's templates that is declared neither in
+* propertySchema nor in globals, reported by {@link SpawnEngine#lint}.
+*
+* @see SpawnLintResult
+*/
+interface UndeclaredVariable {
+	/** The variable name as referenced in the templates. */
+	name: string;
+	/**
+	* The spawn paths where the variable appears — file contents for
+	* {@code .liquid} files, and path templates for any file whose path contains
+	* the variable.
+	*/
+	files: string[];
+}
+/**
+* The outcome of {@link SpawnEngine#lint}: the variables a spawn's templates
+* reference that are not declared in propertySchema or globals. A spawn is
+* lint-clean when {@code undeclared} is empty.
+*/
+interface SpawnLintResult {
+	/** Referenced-but-undeclared variables, sorted by name. */
+	undeclared: UndeclaredVariable[];
+}
+/**
 * Resolves {@code target} against {@code root} and asserts the result stays at or
 * below {@code root}, so a path can't escape the directory being operated in via
 * {@code ..} (whether authored that way or injected through a property value).
@@ -38,6 +63,12 @@ interface PropertyResolver {
 */
 declare function assertPathWithin(root: string, target: string): string;
 /**
+* Reports the variables a spawn directory's templates reference that are
+* declared neither in propertySchema nor in globals (following inheritance on
+* disk, confined to {@code dir}). See {@link SpawnEngine#lint}.
+*/
+declare function lintSpawnDir(dir: string): Promise<SpawnLintResult>;
+/**
 * Options for {@link NodeSpawnRenderer#render}.
 */
 interface NodeRenderOptions {
@@ -66,7 +97,6 @@ declare class NodeSpawnRenderer {
 	*         rendered path escapes its root, or a required property has no value
 	*/
 	render(spawnDir: string, destination: string, options?: NodeRenderOptions): Promise<Record<string, unknown>>;
-	private loadSpawnTree;
 	private writeSpawnTree;
 }
-export { assertPathWithin, NodeSpawnRenderer, NodeRenderOptions };
+export { lintSpawnDir, assertPathWithin, NodeSpawnRenderer, NodeRenderOptions };

package/dist/node/index.d.ts

@@ -31,6 +31,31 @@ interface PropertyResolver {
 	resolve(key: string, schema: PropertySchema, message: string, defaultValue?: unknown): Promise<unknown>;
 }
 /**
+* A variable referenced in a spawn's templates that is declared neither in
+* propertySchema nor in globals, reported by {@link SpawnEngine#lint}.
+*
+* @see SpawnLintResult
+*/
+interface UndeclaredVariable {
+	/** The variable name as referenced in the templates. */
+	name: string;
+	/**
+	* The spawn paths where the variable appears — file contents for
+	* {@code .liquid} files, and path templates for any file whose path contains
+	* the variable.
+	*/
+	files: string[];
+}
+/**
+* The outcome of {@link SpawnEngine#lint}: the variables a spawn's templates
+* reference that are not declared in propertySchema or globals. A spawn is
+* lint-clean when {@code undeclared} is empty.
+*/
+interface SpawnLintResult {
+	/** Referenced-but-undeclared variables, sorted by name. */
+	undeclared: UndeclaredVariable[];
+}
+/**
 * Resolves {@code target} against {@code root} and asserts the result stays at or
 * below {@code root}, so a path can't escape the directory being operated in via
 * {@code ..} (whether authored that way or injected through a property value).
@@ -38,6 +63,12 @@ interface PropertyResolver {
 */
 declare function assertPathWithin(root: string, target: string): string;
 /**
+* Reports the variables a spawn directory's templates reference that are
+* declared neither in propertySchema nor in globals (following inheritance on
+* disk, confined to {@code dir}). See {@link SpawnEngine#lint}.
+*/
+declare function lintSpawnDir(dir: string): Promise<SpawnLintResult>;
+/**
 * Options for {@link NodeSpawnRenderer#render}.
 */
 interface NodeRenderOptions {
@@ -66,7 +97,6 @@ declare class NodeSpawnRenderer {
 	*         rendered path escapes its root, or a required property has no value
 	*/
 	render(spawnDir: string, destination: string, options?: NodeRenderOptions): Promise<Record<string, unknown>>;
-	private loadSpawnTree;
 	private writeSpawnTree;
 }
-export { assertPathWithin, NodeSpawnRenderer, NodeRenderOptions };
+export { lintSpawnDir, assertPathWithin, NodeSpawnRenderer, NodeRenderOptions };

package/dist/node/index.js

@@ -1,6 +1,6 @@
 import {
   SpawnEngine
-} from "../shared/spawn-4k8xtpe9.js";
+} from "../shared/spawn-1h1k8w8r.js";
 
 // packages/spawn/src/node/index.ts
 import fs from "node:fs";
@@ -16,6 +16,36 @@ function assertContained(root, resolved) {
 function assertPathWithin(root, target) {
   return assertContained(root, path.resolve(root, target));
 }
+async function loadSpawnTree(dir) {
+  const tree = {};
+  const entries = await fsP.readdir(dir, { recursive: true, withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isFile()) {
+      continue;
+    }
+    const filePath = path.join(entry.parentPath, entry.name);
+    const treePath = path.relative(dir, filePath).split(path.sep).join("/");
+    if (treePath.endsWith(".liquid")) {
+      tree[treePath] = await fsP.readFile(filePath, { encoding: "utf8" });
+    } else {
+      tree[treePath] = await fsP.readFile(filePath);
+    }
+  }
+  return tree;
+}
+function diskInheritanceLoader(spawnRoot) {
+  let currentDir = spawnRoot;
+  return async (ref) => {
+    currentDir = assertContained(spawnRoot, path.resolve(currentDir, ref));
+    if (!fs.existsSync(path.resolve(currentDir, "spawn.json"))) {
+      throw new Error(`Inherited spawn ${path.resolve(currentDir, "spawn.json")} does not exist`);
+    }
+    return loadSpawnTree(currentDir);
+  };
+}
+async function lintSpawnDir(dir) {
+  return new SpawnEngine().lint(await loadSpawnTree(dir), { loadInherited: diskInheritanceLoader(dir) });
+}
 
 class NodeSpawnRenderer {
   engine = new SpawnEngine;
@@ -23,38 +53,14 @@ class NodeSpawnRenderer {
     if (fs.existsSync(destination)) {
       throw new Error(`The target directory ${destination} already exists`);
     }
-    let currentDir = spawnDir;
-    const result = await this.engine.renderSpawn(await this.loadSpawnTree(spawnDir), {
+    const result = await this.engine.renderSpawn(await loadSpawnTree(spawnDir), {
       context: options?.context,
       propertyResolver: options?.propertyResolver,
-      loadInherited: async (ref) => {
-        currentDir = assertContained(spawnDir, path.resolve(currentDir, ref));
-        if (!fs.existsSync(path.resolve(currentDir, "spawn.json"))) {
-          throw new Error(`Inherited spawn ${path.resolve(currentDir, "spawn.json")} does not exist`);
-        }
-        return this.loadSpawnTree(currentDir);
-      }
+      loadInherited: diskInheritanceLoader(spawnDir)
     });
     await this.writeSpawnTree(result.files, destination);
     return result.context;
   }
-  async loadSpawnTree(dir) {
-    const tree = {};
-    const entries = await fsP.readdir(dir, { recursive: true, withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isFile()) {
-        continue;
-      }
-      const filePath = path.join(entry.parentPath, entry.name);
-      const treePath = path.relative(dir, filePath).split(path.sep).join("/");
-      if (treePath.endsWith(".liquid")) {
-        tree[treePath] = await fsP.readFile(filePath, { encoding: "utf8" });
-      } else {
-        tree[treePath] = await fsP.readFile(filePath);
-      }
-    }
-    return tree;
-  }
   async writeSpawnTree(tree, destination) {
     await fsP.mkdir(destination, { recursive: true });
     for (const [treePath, content] of Object.entries(tree)) {
@@ -65,6 +71,7 @@ class NodeSpawnRenderer {
   }
 }
 export {
+  lintSpawnDir,
   assertPathWithin,
   NodeSpawnRenderer
 };

package/dist/shared/{spawn-4k8xtpe9.js → spawn-1h1k8w8r.js}

@@ -34,23 +34,7 @@ class SpawnEngine {
     this.engine.registerFilter("upperFirst", (v) => upperFirst(v));
   }
   async renderSpawn(spawn, options) {
-    const trees = [spawn];
-    const configs = [];
-    let currentConfig = this.parseConfig(spawn);
-    if (currentConfig) {
-      configs.push(currentConfig);
-    }
-    while (currentConfig?.inherits) {
-      if (!options?.loadInherited) {
-        throw new Error(`Spawn inherits '${currentConfig.inherits}' but no loadInherited callback was provided`);
-      }
-      const inherited = await options.loadInherited(currentConfig.inherits);
-      trees.push(inherited);
-      currentConfig = this.parseConfig(inherited);
-      if (currentConfig) {
-        configs.push(currentConfig);
-      }
-    }
+    const { trees, configs } = await this.walkInheritance(spawn, options?.loadInherited);
     let globals = {};
     let propertySchemas = {};
     for (const config of [...configs].reverse()) {
@@ -89,6 +73,69 @@ class SpawnEngine {
     }
     return { files, sources, context };
   }
+  async lint(spawn, options) {
+    const { trees, configs } = await this.walkInheritance(spawn, options?.loadInherited);
+    const declared = new Set;
+    for (const config of configs) {
+      if (config.globals) {
+        Object.keys(config.globals).forEach((key) => declared.add(key));
+      }
+      if (config.propertySchema) {
+        Object.keys(config.propertySchema).forEach((key) => declared.add(key));
+      }
+    }
+    const usedIn = new Map;
+    const record = (name, file) => {
+      let files = usedIn.get(name);
+      if (!files) {
+        files = new Set;
+        usedIn.set(name, files);
+      }
+      files.add(file);
+    };
+    const externalVars = (template) => Object.keys(this.engine.parseAndAnalyzeSync(template, undefined, { partials: false }).globals);
+    for (const tree of trees) {
+      for (const source of Object.keys(tree)) {
+        const fileName = source.substring(source.lastIndexOf("/") + 1);
+        if (IGNORED_FILE_NAMES.includes(fileName)) {
+          continue;
+        }
+        externalVars(source).forEach((name) => record(name, source));
+        const content = tree[source];
+        if (source.endsWith(".liquid") && typeof content === "string") {
+          externalVars(content).forEach((name) => record(name, source));
+        }
+      }
+    }
+    const undeclared = [];
+    for (const [name, files] of usedIn) {
+      if (!declared.has(name)) {
+        undeclared.push({ name, files: [...files].sort() });
+      }
+    }
+    undeclared.sort((a, b) => a.name.localeCompare(b.name));
+    return { undeclared };
+  }
+  async walkInheritance(spawn, loadInherited) {
+    const trees = [spawn];
+    const configs = [];
+    let currentConfig = this.parseConfig(spawn);
+    if (currentConfig) {
+      configs.push(currentConfig);
+    }
+    while (currentConfig?.inherits) {
+      if (!loadInherited) {
+        throw new Error(`Spawn inherits '${currentConfig.inherits}' but no loadInherited callback was provided`);
+      }
+      const inherited = await loadInherited(currentConfig.inherits);
+      trees.push(inherited);
+      currentConfig = this.parseConfig(inherited);
+      if (currentConfig) {
+        configs.push(currentConfig);
+      }
+    }
+    return { trees, configs };
+  }
   parseConfig(tree) {
     const raw = tree["spawn.json"];
     if (raw === undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kinotic-ai/spawn",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "files": [
     "dist"
@@ -43,8 +43,8 @@
     "build:graal-spawn-renderer": "bun build ./src/graalSpawnRendererMain.ts --outfile ./dist/graal-spawn-renderer.js --format=iife --target=browser"
   },
   "dependencies": {
-    "liquidjs": "10.25.7",
-    "zod": "^4.3.6"
+    "liquidjs": "10.27.0",
+    "zod": "4.4.3"
   },
   "devDependencies": {
     "@types/node": "^25.3.2",