@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/stx-virtual-ts.d.ts

@@ -0,0 +1,358 @@
+/**
+ * Pull the script blocks out of a `.stx` source, with the line each body starts on.
+ *
+ * `<script server>` and `<script client>` are recognised by attribute. A bare
+ * `<script>` is reported as `plain` so a caller can tell which tag the author
+ * actually wrote — NOT so it can be skipped. It is a client block; `client` is
+ * an explicit alias for the default, not a separate kind (stacksjs/stx#1920).
+ */
+export declare function extractScriptBlocks(source: string): ScriptBlock[];
+/**
+ * Blank out everything an expression cannot appear in, preserving offsets.
+ *
+ * Scripts, styles, HTML comments and `@verbatim` blocks are replaced with
+ * spaces so that scanning for `{{ }}` never has to reason about nesting, while
+ * every surviving character keeps its original line and column.
+ */
+export declare function maskNonTemplateRegions(source: string): string;
+/**
+ * Split a filter chain off an interpolation, returning the head expression.
+ *
+ * `{{ name | upper }}` is stx syntax, not TypeScript — the pipe is a filter
+ * separator (`expressions.ts`). Only the part before the first top-level `|`
+ * is TypeScript, and `||` is a real operator that must survive.
+ */
+export declare function stripFilterChain(expression: string): string;
+export declare function substituteInterpolations(value: string): string;
+/**
+ * The same substitution, but the result occupies the same space as the source.
+ *
+ * A `<script client>` block may take a server value through an interpolation —
+ * `const duration = {{ duration }}` — and 48 of the framework's own 95
+ * components do exactly that. As TypeScript that is a syntax error, so
+ * `stx typecheck` reported 369 of them across the component library: a parse
+ * failure, which suppresses every real diagnostic in the same file. The gate
+ * was not strict there, it was blind.
+ *
+ * Position-preserving because these are script blocks, not attribute values.
+ * A diagnostic on the line after an interpolation has to keep pointing at the
+ * code the author wrote, so the replacement is padded to the original width and
+ * carries the original newline count. For a single-line interpolation — all but
+ * a handful — every column after it is preserved exactly.
+ *
+ * `0` rather than a named placeholder because it fits in `{{a}}`, the shortest
+ * interpolation anyone writes; a longer identifier could not be padded DOWN to
+ * fit and would shift the line.
+ */
+export declare function substituteInterpolationsInPlace(code: string): string;
+/**
+ * Blank stx directives that a script body writes to generate JavaScript.
+ *
+ * A template can loop inside a script — building a lookup table from server
+ * data is the obvious use — and the directive is expanded away long before the
+ * browser sees it:
+ *
+ *   const data = {
+ *     &#64;foreach(features as f)
+ *       '{{ f.id }}': { title: '{{ f.title }}' },
+ *     &#64;endforeach
+ *   }
+ *
+ * To TypeScript the directive line is a syntax error, and one of those mutes
+ * semantic checking for the WHOLE program, not just the file. So checking bare
+ * `<script>` blocks (#1920) made a valid page report 37 invented syntax errors
+ * — and a checker that invents errors gets muted, which is the failure mode
+ * this file exists to avoid.
+ *
+ * Blanked rather than removed so every line number after it still points at the
+ * line the author wrote. Only a directive ALONE on its line is matched: that is
+ * how they are written, and it cannot swallow code sharing the line.
+ */
+export declare function blankScriptDirectives(code: string): string;
+/**
+ * Every checkable expression in the markup, with the position it occupies.
+ *
+ * Interpolations escaped as `@{{ … }}` are skipped: that syntax exists to emit
+ * the braces literally.
+ */
+export declare function extractTemplateExpressions(source: string): TemplateExpression[];
+export declare function collectTemplateBindings(source: string): TemplateBinding[];
+/**
+ * Top-level names a script block declares.
+ *
+ * Used to give template expressions a scope without inlining a block that
+ * would collide with another one.
+ */
+export declare function collectBlockDeclarations(code: string): string[];
+/** Ambient declarations for the globals the stx runtime injects. */
+export declare function runtimeGlobalDeclarations(): string;
+export declare function serverContextDeclarations(): string;
+/**
+ * The names a `defineClientPayload({ … })` call publishes, or `null` when the
+ * page does not declare one.
+ *
+ * Only the keys matter. The runtime captures values, and `extractBridgeData`
+ * publishes the declared set in full and nothing else, so the key set IS the
+ * contract between the two blocks (#1868).
+ *
+ * `null` and `[]` mean different things: `null` is a page that never declared,
+ * and still gets the old name-scraping bridge; `[]` is a page that declared an
+ * empty payload and therefore publishes nothing.
+ */
+export declare function extractClientPayloadNames(serverCode: string): string[] | null;
+/** Top-level `import` statements, and everything else, separated. */
+export declare function splitTopLevelImports(code: string): { imports: string, body: string };
+/**
+ * Declarations that give a client block the server values it is actually given.
+ *
+ * A `<script client>` block is checked in its own buffer, so a name reaching it
+ * through the server-to-client bridge was simply "Cannot find name" — which
+ * means `stx typecheck` reported an error for every page that used the bridge
+ * at all. A checker that invents errors gets muted, and a muted gate catches
+ * nothing.
+ *
+ * The types are inferred rather than guessed. The server block is re-emitted
+ * inside a wrapper function that returns exactly the declared payload, and each
+ * published name is then declared as a lookup into that function's return type,
+ * so `const liveNow = await countLive()` reaches the client block as whatever
+ * `countLive` returns — not `any`, and not a hand-written annotation that can
+ * drift from the code above it (#1868 ask 2).
+ *
+ * Everything is emitted with `var`, `function` and `type`, all of which hoist,
+ * so this appends to the buffer and no line number moves.
+ *
+ * A page that declares nothing still gets its server bindings, as `any`. That
+ * is exactly what the scraping bridge does — publish any server name the client
+ * source mentions — and declaring `any` is the honest description of a value
+ * whose delivery depends on textual reference. Omitting them instead would make
+ * `stx typecheck` report "Cannot find name" on every page that uses the bridge
+ * at all, and a checker that invents errors gets muted.
+ *
+ * So the incentive runs the right way: declare a payload and the names are
+ * checked against the server block, or do not and they are `any`.
+ */
+/**
+ * Top-level `interface X {…}` / `type X = …` statements, with their source text.
+ *
+ * The payload projection wraps the whole server body in a scope function so the
+ * checker can infer each published value's type from real code. That works for
+ * VALUES and traps TYPES: an `interface AutofixState` declared in
+ * `<script server>` lives inside that function, so a `<script client>` block in
+ * the same file naming it got `Cannot find name 'AutofixState'` — an error about
+ * code that is correct and runs (stacksjs/stx#1924).
+ *
+ * Scanned at depth zero so an interface declared inside a helper is not lifted
+ * out of the scope it belongs to. The brace matcher walks the real source rather
+ * than a blanked copy, because the declaration's BODY is what has to be carried
+ * across, not just its name.
+ */
+export declare function extractTypeDeclarations(code: string): Array<{ name: string, text: string }>;
+export declare function clientPayloadDeclarations(serverCode: string, clientCode?: string): string;
+/**
+ * Declarations at the TOP LEVEL of a block, ignoring anything nested.
+ *
+ * `collectBlockDeclarations` matches `^\s*const …` with leading whitespace
+ * allowed, so it also returns bindings local to a function. For most callers
+ * that is harmless. For the bridge warning it is not: a `const state` inside a
+ * helper never crosses to the client, and naming it told the author to declare
+ * a payload entry that would do nothing (stacksjs/stx#1908).
+ *
+ * Nested braces are blanked first, so only depth-zero declarations survive to
+ * be matched by the shared patterns.
+ */
+export declare function collectTopLevelDeclarations(code: string): string[];
+/**
+ * Server bindings a client block reaches for without a declared payload.
+ *
+ * The scraping bridge publishes a server binding when its name appears as a
+ * free identifier in the client source, so these DO arrive at runtime — they
+ * are just untyped, and their delivery depends on a textual coincidence rather
+ * than on anything the page states. Reporting them is #1868 ask 4, and it is
+ * only worth doing now that ask 2 gives them somewhere to go: warning people
+ * off the implicit path before the typed replacement existed would have been
+ * noise.
+ *
+ * A warning, not an error. These pages work; the fix is mechanical and the
+ * reward is types rather than correctness, so a gate that fails CI over it
+ * would be punishing an app for predating the feature.
+ *
+ * Empty once the page declares a payload, and empty when the client block does
+ * not actually mention any server name.
+ */
+export declare function scrapedBridgeNames(serverCode: string, clientCode: string): string[];
+/**
+ * Names declared by both a server block and a client/plain block.
+ *
+ * The editor gets one buffer per file, so blocks cannot be given separate
+ * modules the way the CLI does — they all land at top level and a name declared
+ * on both sides reads as a redeclaration. That is a false signal, and this is
+ * what lets the plugin suppress exactly those and nothing else.
+ */
+export declare function crossScopeCollisions(blocks: readonly ScriptBlock[]): string[];
+/**
+ * Render one template expression as a checkable statement.
+ *
+ * Returns `null` for the shapes that cannot be modelled without inventing
+ * errors — `@click="open = !open"` assigns to what TypeScript sees as a
+ * `const`, and that form is documented stx syntax, not a mistake.
+ */
+/**
+ * The `@if` / `@unless` conditions that enclose a given offset, outermost first
+ * and already negated for `@else` / `@elseif` branches.
+ *
+ * Markup guards its own expressions, and the checker did not know it. A page
+ * that writes
+ *
+ *   @if (comparison)
+ *     {{ comparison.name }}
+ *   @endif
+ *
+ * is safe, and `comparison` is `T | undefined` from the `.find()` above it, so
+ * every read inside the branch came back as "possibly undefined" - 75 of them
+ * in one application. Reported against markup that cannot fail is the fastest
+ * way to make a checker ignored, and the advice it implies (add a `?.`) makes
+ * the template worse.
+ *
+ * Conditions are emitted verbatim into `if (…)`, so a condition that does not
+ * compile is reported where it is written - as its own template expression -
+ * rather than twice.
+ */
+export declare function guardChainAt(source: string, offset: number): string[];
+export declare function expressionStatement(expression: TemplateExpression): { text: string, prefixLength: number } | null;
+/**
+ * Rewrite relative module specifiers to absolute paths against the real file.
+ *
+ * A block's virtual buffer is written into the state directory, and TypeScript
+ * resolves a relative specifier against the file that CONTAINS it — so
+ * `../target`, written in `pages/deep/rel.stx`, was looked for next to
+ * `.stx/typecheck/` and reported as a missing module (stacksjs/stx#1928).
+ *
+ * A `paths` alias to the same file resolved fine, because those go through the
+ * absolute `baseUrl` the checker emits. That asymmetry is the whole bug: a
+ * relative import is the first thing anyone writes and what every editor's
+ * auto-import produces, so an app hitting it either rewrites correct imports
+ * into aliases to appease the checker, or mutes the checker.
+ *
+ * Rewriting each specifier is preferred over pointing the program at the source
+ * directory — `rootDirs`, the built-in answer for a virtual layout, MERGES its
+ * entries into one namespace, so `./util` from one checked page could silently
+ * resolve to a different page's `util` when both directories are roots. Each
+ * buffer knows exactly one origin, so resolving per file cannot cross-talk.
+ *
+ * Textual rather than parsed, and deliberately: `Bun.Transpiler.scanImports`
+ * erases `import type`, which is the form a type-checker cares about most. The
+ * cost is that the literal text `from './x'` inside a string or comment is
+ * rewritten too — inert, since this buffer is never executed, and it cannot
+ * change a line count, so every diagnostic still lands on the author's line.
+ */
+export declare function absolutizeRelativeSpecifiers(code: string, originDir: string): string;
+/**
+ * Build one line-aligned TypeScript buffer for a whole `.stx` file.
+ *
+ * Every script body is written at the line index it already occupies, so a
+ * diagnostic's line and column are the `.stx` file's line and column with no
+ * translation. Synthetic content is appended past the end of the file and
+ * carried by {@link VirtualFile.lineMap}, so a diagnostic there still resolves
+ * to a real position — or to nothing, for the ambient declarations, which is
+ * how the caller knows to drop it.
+ */
+export declare function buildVirtualTypeScript(source: string, options?: BuildVirtualOptions): VirtualFile;
+/** Offsets at which each 1-based line starts. */
+export declare function lineStarts(text: string): number[];
+/** Offset → 1-based line and column. */
+export declare function offsetToPosition(starts: readonly number[], offset: number): { line: number, column: number };
+/** 1-based line and column → offset, clamped to the line. */
+export declare function positionToOffset(starts: readonly number[], line: number, column: number): number;
+/**
+ * Translate a position in a virtual buffer back to the `.stx` file.
+ *
+ * Returns `null` for the ambient declarations appended past the end of the
+ * file — they correspond to nothing the author wrote, so a diagnostic there
+ * must be dropped rather than pointed at an arbitrary line.
+ */
+export declare function resolvePosition(virtual: VirtualFile, line: number, column: number): ResolvedPosition | null;
+/**
+ * Placeholder for a server interpolation spliced into a client expression.
+ *
+ * `:show="photos()[{{ idx }}]"` is real stx — the server fills `{{ idx }}` in
+ * before the client ever parses the attribute. Left in place it is a syntax
+ * error, so it is replaced with a declared `any`; the interpolation itself is
+ * still extracted and checked on its own.
+ */
+export declare const INTERPOLATION_PLACEHOLDER: '__stx_interpolated';
+/** Name of the generated helper that reads an iterable's element type. */
+export declare const ELEMENT_HELPER: '__StxElement';
+/** Name of the generated helper that models a template's signal auto-unwrap. */
+export declare const UNWRAP_HELPER: '__StxTemplateValue';
+/**
+ * Context the server injects into a `<script server>` block.
+ *
+ * Mirrors what `serve.ts` puts in scope. Declaring these is what lets the
+ * checker report a genuine typo instead of suppressing every unresolved name.
+ */
+export declare const STX_SERVER_CONTEXT: readonly ['params', 'query', 'cookies', 'host', 'ip', 'setResponseStatus', 'setResponseHeader', 'notFound', 'request', 'url', 'definePageMeta', unknown, unknown, 'defineStore', unknown, unknown, unknown, unknown, unknown, '$props'];
+/** Marker comment so a generated preamble is recognisable in a dumped buffer. */
+export declare const PAYLOAD_COMMENT: 'stx: types for the declared client payload (#1868)';
+/** The same, for a page still relying on the name-scraping bridge. */
+export declare const SCRAPED_COMMENT: 'stx: untyped bridge names — declare a defineClientPayload to check these (#1868)';
+/**
+ * Names the template engine puts in scope for every page.
+ *
+ * Declared rather than suppressed. The editor plugin used to drop every
+ * "Cannot find name" whose message mentioned one of a hardcoded list, which
+ * also dropped genuine typos; giving the names a declaration means an
+ * unrecognised one is still an error (#1852 ask 3).
+ */
+export declare const STX_TEMPLATE_GLOBALS: readonly ['$env', '$user', '$slot', '$slots', '$attrs', '$props', '$page', '$route', '$loop', unknown, unknown, '$errors', '$csrf', 'props', 'slot'];
+export declare interface ScriptBlock {
+  kind: ScriptKind
+  code: string
+  startLine: number
+  attrs: string
+}
+/** A `{{ }}` interpolation or a directive attribute value. */
+export declare interface TemplateExpression {
+  code: string
+  line: number
+  column: number
+  kind: 'interpolation' | 'directive'
+  attribute?: string
+  offset?: number
+}
+/** A synthetic line's origin, for diagnostics that land outside the source. */
+export declare interface MappedLine {
+  line: number
+  column: number
+  expression?: TemplateExpression
+  prefixLength?: number
+}
+export declare interface VirtualFile {
+  text: string
+  lineMap: Map<number, MappedLine>
+  sourceLineCount: number
+}
+/**
+ * Names a template introduces that no script block declares.
+ *
+ * Loop bindings are collected for the whole file rather than tracked per
+ * subtree. That is deliberately over-permissive: using a loop variable outside
+ * its loop goes unreported, which is a missing error, whereas scoping it
+ * precisely without an HTML parser would invent errors that are not there.
+ */
+export declare interface TemplateBinding {
+  name: string
+  iterable?: string
+}
+export declare interface BuildVirtualOptions {
+  templateExpressions?: boolean
+  originDir?: string
+  globals?: boolean
+  runtimeGlobals?: boolean
+}
+/** Where a diagnostic in a virtual buffer belongs in the `.stx` file. */
+export declare interface ResolvedPosition {
+  line: number
+  column: number
+  expression?: TemplateExpression
+}
+export type ScriptKind = 'server' | 'client' | 'plain';