@m6d/cortex-cli 0.15.0 → 0.16.0

package/src/contracts/charts/chart-spec.ts

@@ -1,217 +0,0 @@
-/*
- * The boundary on a Vega-Lite spec the model wrote, shared by the widget
- * (which draws it live) and Cortex (which describes it to the model):
- * inline data only, no fetches, no interactivity, bounded work.
- */
-
-export const MAX_CHART_ROWS = 200;
-const MAX_CHART_SIZE = 4000;
-/** Transforms whose output size is set by their own parameters or by an expression rather than by the rows. */
-const EXPANDING_TRANSFORMS = new Set([
-    "flatten",
-    "fold",
-    "density",
-    "impute",
-    "regression",
-    "loess",
-    "quantile",
-    "sample",
-]);
-
-/** The boundary as the model reads it in its system prompt, so it writes specs this file accepts. */
-export const CHART_SPEC_GUIDE = `Use Vega-Lite JSON with inline \`data.values\` only, at most ${MAX_CHART_ROWS} rows, and no \`url\` anywhere. Compute folds, trend lines and densities yourself. For several series, write one row per series and x value, or keep one row per x value and draw a layer per series (color by \`datum\`) when that would exceed the row limit. These keys are refused anywhere in the spec: ${[...EXPANDING_TRANSFORMS, "params", "selection"].join(", ")}. Expressions in \`calculate\`, \`filter\` and \`labelExpr\` may use only datum fields, literals, operators and simple math or date-part functions (no format or timeFormat), so put formatted values in the rows or use an axis \`format\`.`;
-
-/** What a single key or value in a chart spec may not be; undefined when it is fine on its own. */
-function chartNodeViolation(key: string, value: unknown) {
-    if (key === "url") return "Charts may only use inline data and no URLs.";
-    if (key === "sequence" || key === "graticule") return "Charts may only use inline data.";
-    if (EXPANDING_TRANSFORMS.has(key)) return "Charts may not use transforms that generate rows.";
-    if (key === "params" || key === "selection" || key === "signals" || key === "on") {
-        return "Charts may not be interactive.";
-    }
-    // An expression reference can compute what a literal could not, such as axis ticks.
-    if (key === "expr") return "Charts may not carry expressions.";
-    if (EXPRESSION_KEYS.has(key) && typeof value === "string" && !isBoundedExpression(value)) {
-        return "Charts may only use simple expressions over datum.";
-    }
-    if (key === "usermeta") return "Charts may not carry usermeta.";
-    if (typeof value === "string" && externalResourceIn(value)) {
-        return "Charts may not reference URLs.";
-    }
-    if ((key === "width" || key === "height") && dimensionPixels(value) > MAX_CHART_SIZE) {
-        return `Charts may be at most ${MAX_CHART_SIZE} pixels wide or tall.`;
-    }
-    return undefined;
-}
-
-/** Where a Vega-Lite spec holds an expression string that Vega evaluates per row. */
-const EXPRESSION_KEYS = new Set(["calculate", "filter", "test", "signal", "labelExpr"]);
-/** Functions an expression may call: each is constant work on scalars. */
-const EXPRESSION_FUNCTIONS = new Set([
-    "abs",
-    "ceil",
-    "floor",
-    "round",
-    "min",
-    "max",
-    "sqrt",
-    "pow",
-    "log",
-    "exp",
-    "year",
-    "month",
-    "date",
-    "day",
-    "hours",
-    "minutes",
-    "toNumber",
-    "toString",
-    "toDate",
-    "isValid",
-    "isNaN",
-    "if",
-    "indexof",
-    "length",
-]);
-
-/**
- * True when an expression is arithmetic, comparison and logic over datum
- * fields, literals and the scalar functions above. Anything else (another
- * identifier, a call to any other function) is refused, so no expression can
- * allocate by its arguments the way sequence() or pad() do.
- */
-function isBoundedExpression(expression: string) {
-    if (expression.length > 500 || /[\\`]/.test(expression)) return false;
-    const stripped = expression.replace(/'[^']*'|"[^"]*"/g, '""');
-    for (const [, name] of stripped.matchAll(/([A-Za-z_$][\w$]*)\s*\(/g)) {
-        if (!EXPRESSION_FUNCTIONS.has(name ?? "")) return false;
-    }
-    const identifiers = stripped
-        .replace(/(datum|parent)(\s*\.[\w$]+|\s*\[\s*""\s*\])+|\b\d[\w.]*/g, "")
-        .matchAll(/[A-Za-z_$][\w$]*/g);
-    for (const [name] of identifiers) {
-        if (!EXPRESSION_FUNCTIONS.has(name) && !["true", "false", "null"].includes(name))
-            return false;
-    }
-    return true;
-}
-
-/** A chart dimension in pixels: a number, or the band step of its `{ step }` form. */
-function dimensionPixels(value: unknown) {
-    if (typeof value === "number") return value;
-    const step = (value as { step?: unknown } | null)?.step;
-    return typeof step === "number" ? step : 0;
-}
-
-/**
- * Inline data is opaque: rows, or a GeoJSON collection's features, are
- * counted and never read as controls. Anything else in a `values` position
- * (an axis tick list, an expression object) is a control and is walked.
- */
-function inlineDataViolation(data: unknown, key: string) {
-    const features = (data as { features?: unknown } | null)?.features;
-    const rows = Array.isArray(data) ? data.length : Array.isArray(features) ? features.length : -1;
-    if (rows < 0)
-        return (
-            chartNodeViolation(key, data) ??
-            firstViolation(childEntries(data, key), chartSpecViolation)
-        );
-    return rows > MAX_CHART_ROWS ? `Charts may hold at most ${MAX_CHART_ROWS} rows.` : undefined;
-}
-
-/**
- * Why a Vega-Lite spec is refused, or undefined when it may be drawn. The
- * walk is over the spec's control positions: a `url` key anywhere is a fetch
- * (data, image marks); a generator or a row-producing transform is an
- * unbounded row count; params would redraw after the resource scrub;
- * `usermeta` lets the spec rewrite the embed options; a string carrying
- * url() or a CSS escape could reach an SVG presentation attribute. Inline
- * rows are only counted, never read as controls, and the drawing size is
- * capped so a spec cannot exhaust the reader's page.
- */
-export function chartSpecViolation(value: unknown, key = ""): string | undefined {
-    if (key === "values") return inlineDataViolation(value, key);
-    if (key === "datasets") return firstViolation(childEntries(value), inlineDataViolation);
-    return (
-        chartNodeViolation(key, value) ??
-        firstViolation(childEntries(value, key), (child, childKey) =>
-            chartSpecViolation(child, childKey),
-        )
-    );
-}
-
-/** An array's items under their parent's key, an object's own entries, nothing for a scalar. */
-function childEntries(value: unknown, key = "") {
-    if (Array.isArray(value)) return value.map((item) => [key, item] as [string, unknown]);
-    return value && typeof value === "object" ? Object.entries(value) : [];
-}
-
-function firstViolation(
-    entries: [string, unknown][],
-    check: (value: unknown, key: string) => string | undefined,
-) {
-    for (const [key, value] of entries) {
-        const reason = check(value, key);
-        if (reason) return reason;
-    }
-    return undefined;
-}
-
-const URL_FUNCTION = /url\(([^)]*)\)/gi;
-/** The CSS functions besides url() that name a resource to load; only url() can point at a fragment, so its argument is checked instead. */
-const OTHER_IMAGE_FUNCTION_NAMES = "src|image|image-set|-webkit-image-set|cross-fade|element";
-/** Every CSS function that names a resource to load. */
-export const IMAGE_FUNCTION = new RegExp(String.raw`\b(url|${OTHER_IMAGE_FUNCTION_NAMES})\(`, "i");
-const OTHER_IMAGE_FUNCTION = new RegExp(String.raw`\b(${OTHER_IMAGE_FUNCTION_NAMES})\(`, "i");
-const OTHER_IMAGE_FUNCTION_GLOBAL = new RegExp(
-    String.raw`\b(${OTHER_IMAGE_FUNCTION_NAMES})\([^)]*\)`,
-    "gi",
-);
-const CSS_ESCAPE = /\\([0-9a-f]{1,6})\s?|\\(.)/gi;
-const IMPORT_RULE = /@import[^;]*;?/gi;
-
-/** Style text with its CSS escapes decoded, so a url() hidden behind one reads as itself. */
-function decodeCssEscapes(text: string) {
-    return text.replace(CSS_ESCAPE, (_, hex: string | undefined, literal: string | undefined) => {
-        if (!hex) return literal ?? "";
-        const code = parseInt(hex, 16);
-        // CSS maps null, surrogates and anything past the last code point to U+FFFD.
-        const invalid = code === 0 || (code >= 0xd800 && code <= 0xdfff) || code > 0x10ffff;
-        return String.fromCodePoint(invalid ? 0xfffd : code);
-    });
-}
-
-/** The target inside one url(...) argument, unquoted and trimmed. */
-function urlTarget(argument: string) {
-    return argument
-        .trim()
-        .replace(/^(['"])(.*)\1$/s, "$2")
-        .trim();
-}
-
-/** True when a CSS or attribute value would make the browser fetch: a url() to anything but a fragment, or an escape that could hide one. */
-export function externalResourceIn(value: string) {
-    if (value.includes("\\") || OTHER_IMAGE_FUNCTION.test(value)) return true;
-    for (const [, argument] of value.matchAll(URL_FUNCTION)) {
-        if (!urlTarget(argument ?? "").startsWith("#")) return true;
-    }
-    return false;
-}
-
-/**
- * Style text with every resource-loading function neutralized: CSS escapes
- * decoded first, url() kept only to fragments. A backslash left after the one
- * decode would be a second escape layer the browser decodes again, and an
- * @import may name its target as a bare string, so both are dropped. Each
- * leaves a space behind, so the text around a removal cannot join into a
- * new one.
- */
-export function scrubStyleText(text: string) {
-    return decodeCssEscapes(text)
-        .replaceAll("\\", " ")
-        .replace(IMPORT_RULE, " ")
-        .replace(OTHER_IMAGE_FUNCTION_GLOBAL, "none")
-        .replace(URL_FUNCTION, (match, argument: string) =>
-            urlTarget(argument).startsWith("#") ? match : "none",
-        );
-}

package/src/contracts/charts/index.ts

@@ -1,8 +0,0 @@
-export {
-    CHART_SPEC_GUIDE,
-    chartSpecViolation,
-    externalResourceIn,
-    IMAGE_FUNCTION,
-    MAX_CHART_ROWS,
-    scrubStyleText,
-} from "./chart-spec";