@chrismo/superkit 1.1.0 → 1.3.0

package/dist/recipes.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=recipes.test.d.ts.map

package/dist/recipes.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipes.test.d.ts","sourceRoot":"","sources":["../src/recipes.test.ts"],"names":[],"mappings":""}

package/dist/recipes.test.js

@@ -0,0 +1,142 @@
+import { describe, it, expect } from 'vitest';
+import { execFileSync } from 'child_process';
+import { readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { superRecipes } from './lib/recipes.js';
+const recipesDir = join(import.meta.dirname, '..', 'docs', 'recipes');
+// Load all .spq files and strip skdoc blocks — they contain nested
+// brackets in example fields that super can't parse as valid syntax.
+// Keep only the actual fn/op implementations.
+const allSpqFiles = readdirSync(recipesDir)
+    .filter(f => f.endsWith('.spq'))
+    .sort();
+// Strip skdoc blocks and functions that can't be parsed by super -I
+// (sk_shell_quote has nested quotes in f-strings that break the file parser)
+const UNPARSEABLE_FNS = [
+    'sk_shell_quote', // nested quotes in f-string
+    'sk_merge_records', // string literal with braces
+    'sk_chr', // uses `let` keyword (broken in current super)
+    'sk_alpha', // depends on sk_chr
+    'sk_seq', // depends on sk_chr (via sk_pad_left, but also broken)
+    'sk_add_ids', // uses `that` (old syntax for `this`)
+];
+function stripSkdocBlocks(content) {
+    const lines = content.split('\n');
+    const result = [];
+    let inSkdoc = false;
+    let inUnparseable = false;
+    let skipNextClosingParen = false;
+    let parenDepth = 0;
+    for (const line of lines) {
+        // Strip skdoc metadata blocks
+        if (!inSkdoc && !inUnparseable && /^(?:fn|op)\s+skdoc_/.test(line)) {
+            inSkdoc = true;
+            continue;
+        }
+        if (inSkdoc) {
+            if (line.includes('<skdoc>)')) {
+                inSkdoc = false;
+                skipNextClosingParen = true;
+            }
+            continue;
+        }
+        if (skipNextClosingParen) {
+            if (line.trim() === '') {
+                result.push(line);
+                continue;
+            }
+            if (line.trim() === ')') {
+                skipNextClosingParen = false;
+                continue;
+            }
+            skipNextClosingParen = false;
+        }
+        // Strip functions that cause parse errors when loaded via -I
+        if (!inUnparseable) {
+            const fnMatch = line.match(/^(?:fn|op)\s+(\w+)/);
+            if (fnMatch && UNPARSEABLE_FNS.includes(fnMatch[1])) {
+                inUnparseable = true;
+                parenDepth = 0;
+                for (const ch of line) {
+                    if (ch === '(')
+                        parenDepth++;
+                    if (ch === ')')
+                        parenDepth--;
+                }
+                if (parenDepth <= 0)
+                    inUnparseable = false;
+                continue;
+            }
+        }
+        if (inUnparseable) {
+            for (const ch of line) {
+                if (ch === '(')
+                    parenDepth++;
+                if (ch === ')')
+                    parenDepth--;
+            }
+            if (parenDepth <= 0)
+                inUnparseable = false;
+            continue;
+        }
+        result.push(line);
+    }
+    return result.join('\n');
+}
+import { writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+const allDefinitions = allSpqFiles
+    .map(f => stripSkdocBlocks(readFileSync(join(recipesDir, f), 'utf-8')))
+    .join('\n');
+function normalizeOutput(s) {
+    return s
+        .replace(/^'(.*)'$/, '"$1"')
+        .trim();
+}
+// Write stripped defs to a file that super can load with -I
+const defsFile = join(tmpdir(), 'superkit-test-defs.spq');
+writeFileSync(defsFile, allDefinitions);
+function runSuper(query) {
+    const result = execFileSync('super', ['-I', defsFile, '-s', '-c', query], {
+        encoding: 'utf-8',
+        timeout: 10_000,
+    });
+    return result.trim();
+}
+// Functions stripped from defs that can't be tested
+const SKIPPED_FNS = new Set(UNPARSEABLE_FNS);
+const { recipes } = superRecipes();
+// Skip examples that are prose descriptions, not executable assertions
+function isExecutableExample(example) {
+    const nonExecutable = [
+        'quoted and wrapped', 'single-quoted', 'tabs replaced',
+        'newlines replaced', 'safely embedded', 'properly escaped',
+        'single record', 'arbitrary user', 'formatted',
+    ];
+    return !nonExecutable.some(s => example.o.toLowerCase().includes(s));
+}
+describe('recipe skdoc examples', () => {
+    for (const recipe of recipes) {
+        if (SKIPPED_FNS.has(recipe.name))
+            continue;
+        // Skip shell-pattern recipes (type: "shell") — not SuperDB functions
+        if (recipe.type === 'shell')
+            continue;
+        for (const example of recipe.examples) {
+            if (!isExecutableExample(example))
+                continue;
+            it(`${recipe.name}: ${example.i}`, () => {
+                // Some examples already include "values", don't double-prefix
+                const query = example.i.startsWith('values ')
+                    ? example.i
+                    : `values ${example.i}`;
+                const actual = runSuper(query);
+                const expected = normalizeOutput(example.o);
+                // Strip type decorators (e.g., "29::uint8" → "29") for comparison
+                const actualClean = actual.replace(/::\w+$/, '');
+                expect(actualClean).toBe(expected);
+            });
+        }
+    }
+});
+//# sourceMappingURL=recipes.test.js.map

package/dist/recipes.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipes.test.js","sourceRoot":"","sources":["../src/recipes.test.ts"],"names":[],"mappings":"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"}

package/docs/recipes/character.spq

@@ -9,7 +9,7 @@ op skdoc_seq: (
      examples:[{i:"sk_seq(3)",o:"0, 1, 2"}] }, <skdoc>)
 )
 
-op sk_seq(n): (
+op sk_seq n: (
   split(sk_pad_left('', '0', n), '')
   | unnest this
   | count

package/docs/recipes/escape.spq

@@ -21,7 +21,7 @@ fn skdoc_csv_row(): (
      type:"func",
      desc:"Builds a CSV row from an array of values. Each element is cast to string and escaped with sk_csv_field, then joined with commas.",
      args:[{name:"arr",desc:"Array of values to format as a CSV row"}],
-     examples:[{i:"sk_csv_row(arr) where arr has commas",o:"fields with commas get quoted"}] }, <skdoc>)
+     examples:[{i:"sk_csv_row(['a', 'b,c', 'd'])",o:"'a,\"b,c\",d'"}] }, <skdoc>)
 )
 
 fn sk_csv_row(arr): (

package/docs/recipes/string.md

@@ -24,8 +24,8 @@ Returns a slice of the string passed in, even if indexes are out of range.
 | `end` | Ending index, exclusive. |
 
 ```supersql
-sk_slice('howdy')
--- => 'Howdy'
+sk_slice('howdy', 0, 3)
+-- => 'how'
 ```
 
 **Implementation:**
@@ -235,15 +235,15 @@ super -I string.spq -s -c 'values sk_urldecode("%2Ftavern%20test")' -
 op sk_decode_seg s: (
   len(s) == 0
     ? s
-    : (is_error(hex(s[1:3]))
+    : (is_error(hex(s[0:2]))
         ? s
-        : hex(s[1:3])::string + s[3:])
+        : f'{hex(s[0:2])::string}{s[2:]}')
 )
 
 op sk_urldecode url: (
-  split(url, "%")
+  split(url, "%%")
     | unnest this
-    | decode_seg this
+    | sk_decode_seg this
     | collect(this)
     | join(this, "")
 )

package/docs/recipes/string.spq

@@ -9,7 +9,7 @@ op skdoc_slice: (
      args:[{name:"s",desc:"The string to slice."}
            {name:"start",desc:"Starting index, zero-based, inclusive."}
            {name:"end",desc:"Ending index, exclusive."}],
-     examples:[{i:"sk_slice('howdy')",o:"'Howdy'"}] }, <skdoc>)
+     examples:[{i:"sk_slice('howdy', 0, 3)",o:"'how'"}] }, <skdoc>)
 )
 
 -- This isn't necessary with zq, but during early releases of super, the
@@ -114,21 +114,20 @@ fn skdoc_mid(): (
 
 fn sk_mid(s, start, n): (sk_slice(s, sk_clamp(start, 0, len(s)), sk_clamp(start, 0, len(s)) + sk_clamp(n, 0, len(s))))
 
--- TODO: skdoc_urldecode
-
--- URL Decoder for SuperDB
--- Usage: super -I urldecode.spq -s -c 'values sk_urldecode(this)' - <<< '"%%2Ftavern%%20test"'
--- Or inline the definitions in your query
-
--- Helper operator to decode a single segment after splitting on %%
--- If the segment starts with valid 2-char hex, converts it to the character
--- Otherwise returns the segment as-is
+fn skdoc_urldecode(): (
+  cast(
+    {name:"sk_urldecode",
+     type:"op",
+     desc:"URL-decodes a percent-encoded string. Splits on %%, decodes each hex-encoded segment, and joins back together.",
+     args:[{name:"url",desc:"The URL-encoded string to decode."}],
+     examples:[{i:"'%%2Fhello%%20world' | sk_urldecode this",o:"'/hello world'"}]}, <skdoc>)
+)
 op sk_decode_seg s: (
   len(s) == 0
     ? s
-    : (is_error(hex(s[1:3]))
+    : (is_error(hex(s[0:2]))
         ? s
-        : hex(s[1:3])::string + s[3:])
+        : f'{hex(s[0:2])::string}{s[2:]}')
 )
 
 -- Main URL decoder operator

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrismo/superkit",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "SuperDB toolkit — docs, recipes, grok patterns, and CLI tools for the super binary",
   "type": "module",
   "main": "dist/index.js",