@m6d/cortex-cli 0.1.0

package/src/commands/swagger.ts

@@ -0,0 +1,261 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+import { type Command, Option } from "@commander-js/extra-typings";
+
+import { configLabel, configOption, openProject } from "@/config/load";
+import { extractEndpoints } from "@/swagger/extract-endpoints";
+import * as report from "@/ui/report";
+
+/** A convention, not config: `KnowledgeConfig` has no `domainsDir`. */
+const DEFAULT_DOMAINS_DIR = "src/domains";
+
+/** Only the parts of a loaded config `swagger` reads to report its inputs. */
+type ProjectConfig = {
+    knowledge?: { swagger?: { url?: string } };
+    agents?: Record<string, { knowledge?: { swagger?: { url?: string } } | null } | undefined>;
+};
+
+export function registerSwagger(program: Command) {
+    const swagger = program
+        .command("swagger")
+        .helpGroup("Resources:")
+        .summary("Endpoint schemas, from your Swagger spec")
+        .description(
+            "Endpoint schemas, from your Swagger spec.\n\nReads `knowledge.swagger.url` from your cortex.config.ts and the .endpoint.ts\nfiles under src/domains.",
+        )
+        .addOption(configOption())
+        // Declared once, on the group: the two verbs read the same directory, and
+        // commander hands a verb's unknown options back to its parent, so
+        // `swagger -d x sync` and `swagger sync -d x` both land here.
+        .addOption(
+            new Option(
+                "-d, --domains-dir <path>",
+                "Domains root, relative to the config file",
+            ).default(DEFAULT_DOMAINS_DIR, DEFAULT_DOMAINS_DIR),
+        )
+        .helpCommand(false);
+
+    for (const verb of ["sync", "check"] as const) {
+        swagger
+            .command(verb)
+            .description(
+                verb === "sync"
+                    ? "Update .endpoint.ts files in place"
+                    : "Report drift without writing (exit 2 if stale)",
+            )
+            .action(async function () {
+                await run(swagger, verb, swagger.opts().domainsDir);
+            });
+    }
+}
+
+async function run(group: Command, verb: "sync" | "check", domainsDirOption: string) {
+    const title = `cortex swagger ${verb}`;
+    const { config: loaded, configPath, path, explicit, verbose } = await openProject(group, title);
+
+    // Relative to the config file, never to the cwd — the domains tree belongs to
+    // the project, and `--config ../other/cortex.config.ts` must still find it.
+    const domainsDir = resolve(dirname(configPath), domainsDirOption);
+    if (!existsSync(domainsDir)) failMissingDomainsDir(domainsDir, verb);
+
+    const urls = swaggerUrls(loaded);
+    for (const url of urls) report.input("Swagger", url);
+
+    const startedAt = Date.now();
+    const result = await runExtract(urls, domainsDir, verb).catch(function (error: unknown): never {
+        return failExtract({ error, configPath, verbose, verb });
+    });
+
+    // Reported once the run is over because that is when the count is known —
+    // the total is every file the walk considered, however it ended up.
+    const total =
+        result.matched + result.updated.length + result.drift.length + result.missing.length;
+    report.input(
+        "Domains",
+        `${configLabel(domainsDir)} — ${report.plural(total, "endpoint file")}`,
+    );
+    report.blank();
+
+    const elapsed = `(${((Date.now() - startedAt) / 1000).toFixed(1)}s)`;
+    if (verb === "sync") return renderSync(result, domainsDir, elapsed);
+    renderCheck(
+        result,
+        domainsDir,
+        elapsed,
+        syncCommand({ path, explicit, domainsDir: domainsDirOption }),
+    );
+}
+
+/**
+ * The `sync` that fixes what `check` found has to act on the tree `check` read,
+ * so it carries whatever flags got it there. Defaults stay off the line — a hint
+ * is something to paste, not a transcript.
+ */
+function syncCommand(options: { path: string; explicit: boolean; domainsDir: string }) {
+    return [
+        "cortex swagger sync",
+        ...(options.explicit ? [`--config ${options.path}`] : []),
+        ...(options.domainsDir === DEFAULT_DOMAINS_DIR
+            ? []
+            : [`--domains-dir ${options.domainsDir}`]),
+    ].join(" ");
+}
+
+type Report = {
+    matched: number;
+    missing: string[];
+    drift: string[];
+    updated: string[];
+};
+
+/**
+ * `sync` says what it did. Only changed files are printed — at 37 files a
+ * per-file log is 34 lines of `ok` — and `MISSING` goes last, because it is the
+ * one thing left for a human. Writing is the job, so it still exits 0.
+ */
+function renderSync(result: Report, domainsDir: string, elapsed: string) {
+    for (const file of result.updated) report.row("updated", file);
+    for (const file of result.missing) {
+        report.row("missing", file);
+        report.row("", `${routeOf(join(domainsDir, file))} — no match in the spec`);
+    }
+    if (result.updated.length || result.missing.length) report.blank();
+
+    const parts = [`${result.updated.length} updated`];
+    if (result.missing.length) parts.push(`${result.missing.length} missing`);
+    parts.push(`${result.matched} unchanged`);
+    if (result.updated.length) parts.push("formatted with prettier");
+    report.footer(`${parts.join(" · ")}  ${elapsed}`);
+
+    if (result.missing.length) {
+        report.note(
+            `${missingLead(result)} no match in the spec. Either the route moved, or the file is\nstale — \`cortex swagger check\` will keep failing until it is resolved.`,
+        );
+    }
+}
+
+/**
+ * `check` says what is wrong, and writes nothing. `drift` and `MISSING` are both
+ * findings — one is fixed by a tool, the other by a person — so either exits 2.
+ */
+function renderCheck(result: Report, domainsDir: string, elapsed: string, sync: string) {
+    for (const file of result.drift) {
+        report.row("drift", file);
+        report.row("", `${routeOf(join(domainsDir, file))} — no longer matches the spec`);
+    }
+    for (const file of result.missing) {
+        report.row("missing", file);
+        report.row("", `${routeOf(join(domainsDir, file))} — no match in the spec`);
+    }
+    if (result.drift.length || result.missing.length) report.blank();
+
+    const parts: string[] = [];
+    if (result.drift.length) parts.push(`${result.drift.length} drifted`);
+    if (result.missing.length) parts.push(`${result.missing.length} missing`);
+    parts.push(`${result.matched} up to date`);
+    report.footer(`${parts.join(" · ")}  ${elapsed}`);
+
+    if (result.drift.length) {
+        report.note(
+            `Run \`${sync}\` to update the ${report.plural(result.drift.length, "drifted file")}.`,
+        );
+    }
+    if (result.missing.length) {
+        report.note(
+            `${missingLead(result)} no match in the spec. Either the route moved, or the file is\nstale — \`cortex swagger sync\` cannot fix it; it needs a human.`,
+        );
+    }
+    if (result.drift.length || result.missing.length) process.exit(2);
+}
+
+/**
+ * The route a finding is about, read back the way the server's own file walk
+ * reads it. The report is a list of paths; the route is what the reader has to
+ * act on, and it lives in the file.
+ */
+function routeOf(filePath: string) {
+    const source = readFileSync(filePath, "utf8");
+    const method = source.match(/^\s*method:\s*(['"])([^'"]+)\1/m)?.[2] ?? "?";
+    const route = source.match(/^\s*path:\s*(['"])([^'"]+)\1/m)?.[2] ?? "?";
+    return `${method} ${route}`;
+}
+
+/**
+ * Unlike `graph seed`, this needs nothing from the project's server — not even a
+ * version handshake. What it writes is `.endpoint.ts` source whose generated block
+ * has to satisfy that server's own `EndpointDef`, so a codegen that outran the
+ * installed server is a type error in the project's `bun run check`, loudly, rather
+ * than something to detect here.
+ */
+async function runExtract(swaggerUrls: string[], domainsDir: string, verb: "sync" | "check") {
+    if (!swaggerUrls.length) throw new Error("No swagger URLs found in knowledge config");
+
+    return await extractEndpoints({ swaggerUrls, domainsDir, write: verb === "sync" });
+}
+
+/** Server level, then per agent, deduped — per-agent docs override on a key clash. */
+function swaggerUrls(config: ProjectConfig) {
+    const urls = new Set<string>();
+    if (config.knowledge?.swagger?.url) urls.add(config.knowledge.swagger.url);
+
+    for (const agent of Object.values(config.agents ?? {})) {
+        if (agent?.knowledge?.swagger?.url) urls.add(agent.knowledge.swagger.url);
+    }
+
+    return [...urls];
+}
+
+/** `1 endpoint file has` / `3 endpoint files have` — both notes open with it. */
+function missingLead(result: Report) {
+    return `${report.plural(result.missing.length, "endpoint file")} ${result.missing.length === 1 ? "has" : "have"}`;
+}
+
+/**
+ * An absent domains dir is *couldn't run*, not "nothing to do": `extractEndpoints`
+ * walks a missing directory as an empty one and would report a clean 0 of 0.
+ */
+function failMissingDomainsDir(domainsDir: string, verb: string): never {
+    report.fail({
+        what: `No domains directory at ${configLabel(domainsDir)}`,
+        blocks: [
+            `\`swagger ${verb}\` reads .endpoint.ts files under a domains root — ${DEFAULT_DOMAINS_DIR} by\ndefault — resolved relative to the config file. Point it somewhere else:`,
+            `  cortex swagger ${verb} --domains-dir ./lib/domains`,
+        ],
+    });
+}
+
+/**
+ * Section requirements are `runExtract`'s to enforce — it already throws
+ * `"No swagger URLs found in knowledge config"`. This renders what it threw.
+ */
+function failExtract(options: {
+    error: unknown;
+    configPath: string;
+    verbose: boolean;
+    verb: string;
+}): never {
+    const { error, configPath, verbose, verb } = options;
+    const label = configLabel(configPath);
+    const message = error instanceof Error ? error.message : String(error);
+
+    if (message === "No swagger URLs found in knowledge config") {
+        report.fail({
+            what: `${label} has no knowledge.swagger.url`,
+            blocks: [
+                `\`swagger ${verb}\` generates endpoint schemas from a Swagger spec. Add one:`,
+                '  knowledge: { swagger: { url: "https://api.example.com/swagger/v1/swagger.json" } }',
+                "See https://github.com/boring91/cortex/blob/main/packages/cortex-server/README.md#file-structure-convention",
+            ],
+        });
+    }
+
+    // The `◇ Swagger` lines above name every URL that was tried, so the error
+    // states the failure and points at the key behind it.
+    report.fail({
+        what: "Could not read the Swagger spec",
+        error,
+        blocks: [`Is the API running? Otherwise check knowledge.swagger.url in\n${label}.`],
+        verbose,
+    });
+}

package/src/config/load.ts

@@ -0,0 +1,122 @@
+/**
+ * Config discovery and loading. Env needs no step of its own:
+ * discovery is cwd-only and Bun's `.env` auto-load is cwd-relative, so the two
+ * are always colocated and `process.env` is populated before the config
+ * evaluates.
+ */
+
+import { existsSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { Option } from "@commander-js/extra-typings";
+import type { Command } from "@commander-js/extra-typings";
+
+import { validateConfig } from "@/config/validate";
+import * as report from "@/ui/report";
+
+// Discovery is this exact name in the cwd, with no upward walk, so the flag's
+// default *is* the discovery rule. The second argument is what help prints;
+// without it commander would JSON.stringify the path and show quotes.
+const DEFAULT_CONFIG = "./cortex.config.ts";
+
+/**
+ * `-c, --config <path>` for a command group that reads the project: declared
+ * on the group, so `cortex new` and `cortex cc` never show it. Commander hands
+ * a verb's unknown options back to its parent, so `swagger -c x sync` and
+ * `swagger sync -c x` both land on the group.
+ */
+export function configOption() {
+    return new Option("-c, --config <path>", "Path to cortex.config.ts").default(
+        DEFAULT_CONFIG,
+        DEFAULT_CONFIG,
+    );
+}
+
+/** How a config path is printed once found: relative to the cwd, `./`-prefixed. */
+export function configLabel(path: string) {
+    const relativePath = relative(process.cwd(), path);
+    return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
+}
+
+/**
+ * `./cortex.config.ts` in the cwd, that exact name — no upward walk and no
+ * extension fallback, so a run from the wrong directory fails loudly instead of
+ * silently picking up an ancestor's config. `--config` replaces the path
+ * outright and accepts anything Bun can import.
+ */
+function findConfig(options: { path: string; explicit: boolean; command: string }) {
+    const { path, explicit, command } = options;
+    const absolute = resolve(process.cwd(), path);
+    if (existsSync(absolute)) return absolute;
+
+    if (explicit) {
+        report.fail({
+            what: `No config file at ${path}`,
+            blocks: [
+                "--config takes a path to a file Bun can import, resolved from the\ndirectory you run in.",
+            ],
+        });
+    }
+
+    report.fail({
+        what: `No cortex.config.ts in ${process.cwd()}`,
+        blocks: [
+            "The CLI looks for exactly ./cortex.config.ts in the directory you run in.\nIt does not search parent directories.",
+            "Run it from the project root, or point at the file:",
+            `  ${command} --config ./server/cortex.config.ts`,
+        ],
+    });
+}
+
+/**
+ * What every project command does before its own work: find the config from
+ * its group's `--config`, open the report, load and validate it, and report
+ * its path as the first input. Discovery runs before the report opens: with
+ * no config there is no run to report on, only the reason there isn't one.
+ */
+export async function openProject(group: Command, title: string) {
+    // The group and the root reach this file untyped: `Command` here is the
+    // parameter type, not cli.ts's inferred one.
+    const { config: path, verbose = false } = group.optsWithGlobals() as {
+        config: string;
+        verbose?: boolean;
+    };
+    const explicit = group.getOptionValueSource("config") !== "default";
+    const configPath = findConfig({ path, explicit, command: title });
+
+    report.header(title);
+    const config = await loadConfig(configPath, verbose);
+    validateConfig(config, configLabel(configPath));
+    report.input("Config", configLabel(configPath));
+
+    return { config, configPath, path, explicit, verbose };
+}
+
+/** The whole loader: one import, one default export, no unwrap branch. */
+async function loadConfig(path: string, verbose: boolean) {
+    try {
+        const module = (await import(pathToFileURL(path).href)) as { default?: unknown };
+        const config = module.default;
+
+        if (config === undefined) throw new Error("The module has no default export.");
+        if (typeof config !== "object" || config === null || Array.isArray(config)) {
+            throw new Error("The default export is not an object.");
+        }
+
+        return config as Record<string, unknown>;
+    } catch (error) {
+        report.fail({
+            what: `Could not load ${configLabel(path)}`,
+            error,
+            blocks: [
+                // The line above this one is the underlying error, and for the most
+                // common failure it reads `Cannot find package '@m6d/cortex-server'` —
+                // the config imports the server for `defineAgent`. So the install is
+                // named here rather than left to be inferred.
+                "Importing the file has to run cleanly on its own: it default-exports a\nplain CortexConfig object and nothing else, and every package it imports\nhas to be installed — `bun add @m6d/cortex-server` if that is what is\nmissing above.",
+            ],
+            verbose,
+        });
+    }
+}

package/src/config/validate.ts

@@ -0,0 +1,46 @@
+/**
+ * One generic rule: a key present with an `undefined` value
+ * is a failure, listed by full path. It is essentially always the
+ * `process.env["X"]!` pattern, where `!` silences the type error and `undefined`
+ * flows on to fail far from its cause. Absent keys are fine — that is how
+ * optional sections are expressed.
+ *
+ * The error names config paths only. Annotating each with the env var behind it
+ * is not implementable: the CLI imports an already-evaluated object, so the name
+ * is gone. Point at `.env` and stop.
+ */
+
+import * as report from "@/ui/report";
+
+/** `label` is how the config file is named in the failure: the `./`-relative path the loader prints. */
+export function validateConfig(config: Record<string, unknown>, label: string) {
+    const paths = findUndefined(config, "", new WeakSet());
+    if (!paths.length) return;
+
+    report.fail({
+        what: `${label} has ${paths.length} undefined value${paths.length === 1 ? "" : "s"}`,
+        blocks: [
+            paths.map((entry) => `  ${entry}`).join("\n"),
+            "These keys are present but evaluate to undefined — usually a missing\nenvironment variable. Bun loads .env from the directory you run in; check\nthat ./.env exists and is complete.",
+        ],
+    });
+}
+
+// `seen` guards the domain graph, where concepts and endpoints reference each
+// other in cycles.
+function findUndefined(value: object, prefix: string, seen: WeakSet<object>): string[] {
+    if (seen.has(value)) return [];
+    seen.add(value);
+
+    return (Object.entries(value) as [string, unknown][]).flatMap(function ([key, child]) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (child === undefined) return [path];
+        if (typeof child !== "object" || child === null) return [];
+        // Domain data is built by the server's `define*` helpers, which write
+        // every optional key whether or not it was passed. `undefined` under a
+        // `__brand` means "this endpoint mutates nothing", never a missing env
+        // var, so the rule stops at the seed data it would otherwise drown in.
+        if ("__brand" in child) return [];
+        return findUndefined(child, path, seen);
+    });
+}

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

@@ -0,0 +1,201 @@
+/*
+ * The boundary on a Vega-Lite spec the model wrote, shared by the widget
+ * (which draws it live) and, as needed, the server:
+ * 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",
+]);
+
+/** 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;
+/** Every CSS function that names a resource to load; only url() can point at a fragment. */
+export const IMAGE_FUNCTION = /\b(url|src|image|image-set|-webkit-image-set|cross-fade|element)\(/i;
+/** The same set without url(), whose argument is checked for a fragment instead. */
+const OTHER_IMAGE_FUNCTION = /\b(src|image|image-set|-webkit-image-set|cross-fade|element)\(/i;
+const OTHER_IMAGE_FUNCTION_GLOBAL =
+    /\b(src|image|image-set|-webkit-image-set|cross-fade|element)\([^)]*\)/gi;
+const CSS_ESCAPE = /\\([0-9a-f]{1,6})\s?|\\(.)/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. */
+export function scrubStyleText(text: string) {
+    return decodeCssEscapes(text)
+        .replace(OTHER_IMAGE_FUNCTION_GLOBAL, "none")
+        .replace(URL_FUNCTION, (match, argument: string) =>
+            urlTarget(argument).startsWith("#") ? match : "none",
+        );
+}

package/src/contracts/charts/index.ts

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