@skrr-ai/cli 0.1.102 → 0.1.103

package/dist/lib/widgetStaticScan.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Generative UI — a cheap, conservative static scan of a widget's CSS, HTML and
+ * JavaScript for things that predict a failure INSIDE the sandboxed frame.
+ *
+ * WHAT THIS IS NOT. It is not the frame. The frame's Content-Security-Policy and
+ * `sandbox="allow-scripts"` (packages/data-provider `generativeUi/csp.ts`) decide
+ * what actually runs; this module only reads source text and says what the frame
+ * would very likely refuse. Every finding is therefore tagged `heuristic` by the
+ * caller, and the wording never claims more than the text shows ("looks like a
+ * fetch() call"). A finding can be a false positive (a name inside a string that
+ * never runs); the ABSENCE of findings proves nothing, because a script can
+ * assemble `fetch` at run time. It exists so a harness can notice the likely
+ * mistake before it sends the message, when fixing it is free.
+ *
+ * Severity: `error` means "the frame's CSP or sandbox blocks this if it runs";
+ * `warn` means "this probably does not do what the author meant".
+ *
+ * It is a lexer-light scanner on purpose. JavaScript is read once into a CODE
+ * view (comments, string and template text and regular-expression bodies blanked,
+ * same length, line breaks kept) and a list of the string literals: the rules about
+ * calls and names run over the code view only, so `"eval( is blocked"` in a label and
+ * a comment that says "do not call fetch()" are not findings, and the rules about
+ * what a string SAYS (a URL, markup that loads one) run over the literals only. No
+ * regular expression here can backtrack on the size the widget limits allow, and
+ * HTML is walked with `indexOf`, not with a lazy regex.
+ *
+ * The eval's static checks (`api/.../eval/generativeUi/staticChecks.js`) ask most
+ * of the same questions with a lexer of their own (`sourceLexers.js`), because this
+ * package may not import from `api/`. `generativeUiScannerAgreement.spec.js` runs
+ * both over one corpus and fails when they disagree about what the frame refuses.
+ */
+import { UI_WIDGET_FENCE } from '@skrr-ai/data-provider';
+export type ScanSection = Exclude<(typeof UI_WIDGET_FENCE.sections)[number], 'fallback'>;
+export type StaticSeverity = 'error' | 'warn';
+export type StaticCode = 'external-resource' | 'external-url' | 'external-link' | 'relative-url' | 'network-api' | 'worker' | 'dynamic-code' | 'storage' | 'host-access' | 'popup' | 'navigation' | 'form-action' | 'base-element' | 'nested-frame' | 'plugin-element' | 'element-close' | 'webrtc';
+export interface StaticFinding {
+    severity: StaticSeverity;
+    code: StaticCode;
+    section: ScanSection;
+    /** 1-based line within the section's own text. */
+    line: number;
+    message: string;
+    fix?: string;
+}
+/** A classic inline `<script>` found inside the html section. */
+export interface InlineScript {
+    content: string;
+    /** 1-based line within the html section where the script's text starts. */
+    line: number;
+}
+export interface StaticScanResult {
+    findings: StaticFinding[];
+    /** Classic inline scripts of the html section, for a syntax check by the caller. */
+    inlineScripts: InlineScript[];
+}
+export interface WidgetSource {
+    css: string;
+    html: string;
+    js: string;
+}
+/** One string, template chunk or regular expression found in a script. */
+export interface JsLiteral {
+    kind: 'string' | 'template' | 'regex';
+    /** Offset of the delimiter that opened it (a quote, a backtick, the `}` that resumed a template, a `/`). */
+    open: number;
+    /** Offset of the first character of its text. */
+    start: number;
+    /** Its text as written in the source: escapes are NOT interpreted. */
+    value: string;
+}
+export interface LexedJs {
+    /**
+     * The script with comments, string and template text and regular-expression
+     * bodies replaced by spaces: the same length, every line break kept, delimiters
+     * kept. What is left is what the engine would read as code (template `${ … }`
+     * expressions included).
+     */
+    code: string;
+    /** The script with only its comments blanked. */
+    commentless: string;
+    literals: JsLiteral[];
+}
+/**
+ * Read a script once. Total and linear: it never throws, every loop advances, and
+ * a misread costs a missed or an extra finding, never a hang. It is a heuristic
+ * where JavaScript is ambiguous (a `/` after `)` is read as division; an unclosed
+ * quote ends at the line break), and picks the reading that leaves the rest of the
+ * text lexable.
+ */
+export declare function lexJs(src: string): LexedJs;
+/**
+ * Blank the comments of JavaScript, leaving strings, template text and regular
+ * expressions untouched (the URLs a script uses live in strings). Strings end at
+ * a line break, so one unbalanced quote cannot swallow the rest of the file; the
+ * cost of a misread is a missed finding, never a false one.
+ */
+export declare function maskJsComments(src: string): string;
+/** Blank the block comments of CSS, stepping over quoted strings. */
+export declare function maskCssComments(src: string): string;
+/** Blank `<!-- … -->` comments of HTML. */
+export declare function maskHtmlComments(src: string): string;
+type UrlKind = 'external' | 'inline' | 'relative' | 'empty';
+/** A URL the frame cannot fetch from, a self-contained one, or one with no base to resolve against. */
+export declare function classifyUrl(raw: string): UrlKind;
+/**
+ * Scan one widget's three sections. Pure and total: it never throws and reads
+ * only the strings it is given; the cost is linear in their length, which the
+ * caller has already bounded by the widget limits.
+ */
+export declare function scanWidgetSource(source: WidgetSource): StaticScanResult;
+export {};