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

package/dist/typecheck.js

@@ -0,0 +1,365 @@
+import { existsSync, readFileSync } from "node:fs";
+import { BROWSER_CORE_IMPORTS } from "./browser-core-imports.js";
+import path from "node:path";
+import { listComposableModules } from "./composable-loader.js";
+import { STX_RUNTIME_GLOBALS } from "./runtime-globals.js";
+import { stateDir } from "./state-dir.js";
+import {
+  absolutizeRelativeSpecifiers,
+  buildVirtualTypeScript,
+  extractScriptBlocks,
+  resolvePosition,
+  clientPayloadDeclarations,
+  scrapedBridgeNames,
+  serverContextDeclarations,
+  blankScriptDirectives,
+  substituteInterpolationsInPlace
+} from "./stx-virtual-ts.js";
+export {
+  extractScriptBlocks,
+  extractTemplateExpressions
+} from "./stx-virtual-ts.js";
+export function buildVirtualSource(block, serverCode = "", originDir = "") {
+  const leadingNewlines = block.startLine > 1 ? `
+`.repeat(block.startLine - 1) : "", code = blankScriptDirectives(substituteInterpolationsInPlace(block.code)), payload = block.kind === "client" || block.kind === "plain" ? clientPayloadDeclarations(serverCode, block.code) : "";
+  return absolutizeRelativeSpecifiers(`${leadingNewlines + code}
+${payload}
+export {}
+`, originDir);
+}
+function virtualStxModuleDeclaration(files) {
+  const anchor = files.length > 0 ? path.dirname(path.resolve(files[0])) : process.cwd();
+  try {
+    Bun.resolveSync("@stacksjs/stx", anchor);
+  } catch {
+    return "";
+  }
+  return [
+    "// Generated \u2014 `stx` is the virtual specifier client-script.ts strips.",
+    "declare module 'stx' {",
+    "  export * from '@stacksjs/stx'",
+    "}"
+  ].join(`
+`);
+}
+const WINDOW_OWNED_NAMES = new Set([
+  "name",
+  "status",
+  "length",
+  "location",
+  "history",
+  "origin",
+  "closed",
+  "close",
+  "open",
+  "focus",
+  "blur",
+  "print",
+  "scroll",
+  "scrollTo",
+  "scrollBy",
+  "stop",
+  "top",
+  "parent",
+  "self",
+  "frames",
+  "event",
+  "external",
+  "menubar",
+  "toolbar"
+]);
+function composableGlobalDeclarations(modules) {
+  if (modules.length === 0)
+    return "";
+  const lines = ["// Generated \u2014 the composables the runtime publishes as bare globals."], taken = new Set(STX_RUNTIME_GLOBALS), reExports = [];
+  for (const { file, names } of modules) {
+    const specifier = JSON.stringify(file.replace(/\\/g, "/").replace(/\.ts$/, ""));
+    reExports.push(`  export * from ${specifier}`);
+    for (const name of names) {
+      if (taken.has(name) || WINDOW_OWNED_NAMES.has(name))
+        continue;
+      taken.add(name);
+      lines.push(`declare const ${name}: typeof import(${specifier})[${JSON.stringify(name)}]`);
+    }
+  }
+  lines.push("declare module '@composables' {", ...reExports, "}");
+  return lines.join(`
+`);
+}
+export function virtualPathFor(filePath, kind, index) {
+  return `${filePath}.__stx_${kind}${index}.ts`;
+}
+export function sourcePathFor(virtualPath) {
+  return virtualPath.replace(/\.__stx_(?:server|client|plain|template)\d+\.ts$/, "");
+}
+export function findRuntimeTypeDeclarations() {
+  for (const candidate of [
+    path.resolve(import.meta.dir, "..", "stx.d.ts"),
+    path.resolve(import.meta.dir, "..", "..", "stx.d.ts")
+  ])
+    if (existsSync(candidate))
+      return candidate;
+  return null;
+}
+const TSC_LINE_RE = /^(.*?)\((\d+),(\d+)\):\s+(error|warning)\s+TS(\d+):\s+(.*)$/;
+function isSyntactic(code) {
+  return code >= 1000 && code < 2000;
+}
+function readProjectPathAliases(startDir) {
+  let dir = path.resolve(startDir), configPath;
+  for (;; ) {
+    const candidate = path.join(dir, "tsconfig.json");
+    if (existsSync(candidate)) {
+      configPath = candidate;
+      break;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  if (!configPath)
+    return {};
+  const stripJsonc = (text) => {
+    let out = "", inString = !1, escaped = !1;
+    for (let i = 0;i < text.length; i++) {
+      const c = text[i];
+      if (inString) {
+        out += c;
+        if (escaped)
+          escaped = !1;
+        else if (c === "\\")
+          escaped = !0;
+        else if (c === '"')
+          inString = !1;
+        continue;
+      }
+      if (c === '"') {
+        inString = !0;
+        out += c;
+        continue;
+      }
+      if (c === "/" && text[i + 1] === "/") {
+        while (i < text.length && text[i] !== `
+`)
+          i++;
+        out += `
+`;
+        continue;
+      }
+      if (c === "/" && text[i + 1] === "*") {
+        i += 2;
+        while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
+          i++;
+        i++;
+        continue;
+      }
+      out += c;
+    }
+    return out.replace(/,(\s*[}\]])/g, "$1");
+  }, seen = new Set;
+  let current = configPath, paths, baseUrl, owner = configPath;
+  while (current && !seen.has(current)) {
+    seen.add(current);
+    let parsed;
+    try {
+      parsed = JSON.parse(stripJsonc(readFileSync(current, "utf8")));
+    } catch {
+      break;
+    }
+    const co = parsed?.compilerOptions ?? {};
+    if (!paths && co.paths && typeof co.paths === "object") {
+      paths = co.paths;
+      owner = current;
+    }
+    if (!baseUrl && typeof co.baseUrl === "string")
+      baseUrl = path.resolve(path.dirname(current), co.baseUrl);
+    if (paths && baseUrl)
+      break;
+    current = typeof parsed?.extends === "string" ? path.resolve(path.dirname(current), parsed.extends.endsWith(".json") ? parsed.extends : `${parsed.extends}.json`) : void 0;
+  }
+  if (!paths)
+    return {};
+  const base = baseUrl ?? path.dirname(owner), absolute = {};
+  for (const [pattern, targets] of Object.entries(paths)) {
+    if (!Array.isArray(targets))
+      continue;
+    absolute[pattern] = targets.map((t) => typeof t === "string" && !path.isAbsolute(t) ? path.resolve(base, t) : t);
+  }
+  return { paths: absolute };
+}
+export async function typecheckStxFiles(files, options = {}) {
+  const checkClient = options.client !== !1, checkServer = options.server !== !1, checkTemplates = options.templates !== !1, virtualFiles = new Map, scrapedByFile = new Map, checkedFiles = [];
+  let blockCount = 0, expressionCount = 0;
+  const runtimeTypes = findRuntimeTypeDeclarations();
+  for (const file of files) {
+    const source = await Bun.file(file).text(), blocks = extractScriptBlocks(source).filter((b) => {
+      if (b.kind === "server")
+        return checkServer;
+      return checkClient;
+    }), serverCode = extractScriptBlocks(source).filter((block) => block.kind === "server").map((block) => block.code).join(`
+`);
+    if (checkClient && serverCode) {
+      const clientBlocks = blocks.filter((block) => block.kind !== "server"), names = [...new Set(clientBlocks.flatMap((block) => scrapedBridgeNames(serverCode, block.code)))];
+      if (names.length > 0)
+        scrapedByFile.set(file, { names, line: clientBlocks[0].startLine, kind: clientBlocks[0].kind });
+    }
+    const originDir = path.dirname(path.resolve(file)), templateBuffer = checkTemplates ? buildVirtualTypeScript(source, { runtimeGlobals: !runtimeTypes, originDir }) : null, expressions = templateBuffer ? [...templateBuffer.lineMap.values()].filter((m) => m.expression).length : 0;
+    if (blocks.length === 0 && expressions === 0)
+      continue;
+    checkedFiles.push(file);
+    blockCount += blocks.length;
+    expressionCount += expressions;
+    blocks.forEach((block, i) => {
+      virtualFiles.set(virtualPathFor(file, block.kind, i), {
+        source: buildVirtualSource(block, serverCode, originDir),
+        origin: file,
+        kind: block.kind
+      });
+    });
+    if (templateBuffer && expressions > 0)
+      virtualFiles.set(virtualPathFor(file, "template", 0), {
+        source: templateBuffer.text,
+        origin: file,
+        kind: "template",
+        virtual: templateBuffer
+      });
+  }
+  if (virtualFiles.size === 0)
+    return { diagnostics: [], checkedFiles, blockCount: 0, expressionCount: 0 };
+  const ambient = (options.extraLibs ?? []).map((lib) => path.resolve(lib));
+  if (runtimeTypes)
+    ambient.push(runtimeTypes);
+  const globalsDts = `${stateDir()}/typecheck/__stx_globals.d.ts`, globalDecls = [
+    "// Generated \u2014 the context serve.ts injects into <script server> blocks.",
+    serverContextDeclarations(),
+    ...runtimeTypes ? [] : ["declare const window: any", ...STX_RUNTIME_GLOBALS.map((name) => `declare const ${name}: any`)],
+    [
+      "// Generated \u2014 the names stx auto-imports from @stacksjs/browser.",
+      ...BROWSER_CORE_IMPORTS.map((name) => `declare const ${name}: any`)
+    ].join(`
+`),
+    virtualStxModuleDeclaration(files),
+    composableGlobalDeclarations(await listComposableModules())
+  ].filter(Boolean).join(`
+`), workDir = `${stateDir()}/typecheck`;
+  await Bun.$`rm -rf ${workDir}`.quiet().nothrow();
+  await Bun.$`mkdir -p ${workDir}`.quiet().nothrow();
+  await Bun.write(globalsDts, globalDecls);
+  const writtenToOrigin = new Map;
+  let counter = 0;
+  for (const [virtualPath, meta] of virtualFiles) {
+    const safe = `${counter++}_${virtualPath.replace(/[^\w.-]+/g, "_")}`;
+    await Bun.write(`${workDir}/${safe}`, meta.source);
+    writtenToOrigin.set(safe, meta);
+  }
+  const compilerOptions = {
+    target: "ESNext",
+    module: "ESNext",
+    moduleResolution: "bundler",
+    strict: !0,
+    noEmit: !0,
+    skipLibCheck: !0,
+    allowJs: !0,
+    esModuleInterop: !0,
+    resolveJsonModule: !0,
+    lib: ["ESNext", "DOM", "DOM.Iterable"],
+    types: [],
+    ...readProjectPathAliases(files.length > 0 ? path.dirname(path.resolve(files[0])) : process.cwd()),
+    ...options.compilerOptions ?? {}
+  }, runTsc = async (names, pass) => {
+    const tsconfigPath = `${workDir}/tsconfig${pass === 1 ? "" : `.${pass}`}.json`;
+    await Bun.write(tsconfigPath, JSON.stringify({
+      compilerOptions,
+      files: names.map((name) => `${workDir}/${name}`).concat(globalsDts, ...ambient)
+    }, null, 2));
+    const proc = Bun.spawnSync(["bun", "x", "tsc", "-p", tsconfigPath, "--pretty", "false"], {
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    return {
+      output: new TextDecoder().decode(proc.stdout) + new TextDecoder().decode(proc.stderr),
+      exitCode: proc.exitCode ?? 0
+    };
+  }, first = await runTsc([...writtenToOrigin.keys()], 1), output = first.output, diagnostics = [], exitCode = first.exitCode;
+  let printedDiagnostics = 0;
+  const ambientBasenames = new Set(ambient.map((lib) => lib.split("/").pop()));
+  let ambientDiagnostics = 0;
+  const unparseable = new Set, parseTscOutput = (text) => {
+    for (const rawLine of text.split(`
+`)) {
+      const m = rawLine.match(TSC_LINE_RE);
+      if (!m)
+        continue;
+      printedDiagnostics++;
+      if (ambientBasenames.has(m[1].split("/").pop()))
+        ambientDiagnostics++;
+      const [, filePart, lineStr, colStr, category, code, message] = m, written = filePart.split("/").pop(), entry = writtenToOrigin.get(written);
+      if (!entry)
+        continue;
+      if (isSyntactic(Number(code)))
+        unparseable.add(written);
+      let line = Number(lineStr), column = Number(colStr), expression;
+      if (entry.virtual) {
+        const at = resolvePosition(entry.virtual, line, column);
+        if (!at?.expression)
+          continue;
+        if (Number(code) === 2774)
+          continue;
+        line = at.line;
+        column = at.column;
+        expression = at.expression.code.trim();
+      }
+      diagnostics.push({
+        file: entry.origin,
+        line,
+        column,
+        code: Number(code),
+        message,
+        category: category === "error" ? "error" : "warning",
+        blockKind: entry.kind,
+        expression
+      });
+    }
+  };
+  parseTscOutput(output);
+  const firstPassPrinted = printedDiagnostics, firstPassAmbient = ambientDiagnostics;
+  if (unparseable.size > 0 && unparseable.size < writtenToOrigin.size) {
+    const survivors = [...writtenToOrigin.keys()].filter((name) => !unparseable.has(name));
+    parseTscOutput((await runTsc(survivors, 2)).output);
+  }
+  if (checkClient)
+    for (const [file, scraped] of scrapedByFile) {
+      if (scraped.names.length === 0)
+        continue;
+      diagnostics.push({
+        file,
+        line: scraped.line,
+        column: 1,
+        code: 0,
+        message: `${scraped.names.length === 1 ? "1 value reaches" : `${scraped.names.length} values reach`} this block on the implicit bridge and ${scraped.names.length === 1 ? "is" : "are"} untyped: ${scraped.names.join(", ")}. Declare them with defineClientPayload({ ${scraped.names.join(", ")} }) in the server block to have them checked.`,
+        category: "warning",
+        blockKind: scraped.kind
+      });
+    }
+  const seen = new Set, unique = diagnostics.filter((d) => {
+    const key = `${d.file}:${d.line}:${d.column}:${d.code}:${d.message}`;
+    if (seen.has(key))
+      return !1;
+    seen.add(key);
+    return !0;
+  });
+  unique.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column);
+  const brokenLib = firstPassAmbient > 0 && unique.length === 0, failure = brokenLib || exitCode !== 0 && firstPassPrinted === 0 ? `${brokenLib ? "a file passed with --lib has errors of its own, so nothing in your code was checked" : `tsc exited ${exitCode} without reporting any diagnostic, so nothing was checked`}. ` + "A syntax error in an ambient declaration file does this \u2014 skipLibCheck suppresses " + `SEMANTIC diagnostics only. tsc said:
+${output.trim().split(`
+`).slice(0, 12).join(`
+`) || "(no output)"}` : void 0;
+  return { diagnostics: unique, checkedFiles, blockCount, expressionCount, failure };
+}
+export function formatTypecheckDiagnostics(diagnostics) {
+  return diagnostics.map((d) => {
+    const where = d.blockKind === "template" ? `[template: ${d.expression ?? ""}]` : `[${d.blockKind === "plain" ? "<script>" : `<script ${d.blockKind}>`}]`;
+    return `${d.file}:${d.line}:${d.column}  ${d.category} TS${d.code}  ${d.message}  ${where}`;
+  }).join(`
+`);
+}

package/dist/types/component-types.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Component System Types
+ */
+/**
+ * Prop type definition for component prop validation
+ */
+export type PropType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'function' | 'any';
+/**
+ * Component prop definition for validation
+ */
+export interface PropDefinition {
+    /** Type of the prop */
+    type: PropType | PropType[];
+    /** Whether the prop is required */
+    required?: boolean;
+    /** Default value if not provided */
+    default?: unknown;
+    /** Custom validator function */
+    validator?: (value: unknown) => boolean;
+}
+/**
+ * Component props schema for validation
+ *
+ * @example
+ * ```typescript
+ * const alertProps: ComponentPropsSchema = {
+ *   title: { type: 'string', required: true },
+ *   type: { type: 'string', default: 'info' },
+ *   dismissible: { type: 'boolean', default: false }
+ * }
+ * ```
+ */
+export interface ComponentPropsSchema {
+    [propName: string]: PropDefinition;
+}
+/**
+ * Component definition with metadata
+ */
+export interface ComponentDefinition {
+    /** Component name */
+    name: string;
+    /** Path to component file */
+    path?: string;
+    /** Props schema for validation */
+    props?: ComponentPropsSchema;
+    /** Component description for documentation */
+    description?: string;
+}
+/**
+ * Component configuration
+ */
+export interface ComponentConfig {
+    /** Enable prop validation */
+    validateProps?: boolean;
+    /** Component definitions for prop validation */
+    components?: Record<string, ComponentDefinition>;
+}
+/**
+ * Web component definition
+ */
+export interface WebComponent {
+    /** Name of the web component class */
+    name: string;
+    /** HTML tag to register (must include a hyphen) */
+    tag: string;
+    /** Path to the stx component file to convert */
+    file: string;
+    /** Optional element to extend (default: HTMLElement) */
+    extends?: string;
+    /** Whether to use shadow DOM (default: true) */
+    shadowDOM?: boolean;
+    /** Whether to use a template element (default: true) */
+    template?: boolean;
+    /** Path to an external stylesheet to link */
+    styleSource?: string;
+    /** List of attributes to observe */
+    attributes?: string[];
+    /** Description of the component for documentation */
+    description?: string;
+    /** Output format: 'js' (default) or 'ts' for TypeScript */
+    outputFormat?: 'js' | 'ts';
+    /** Type definitions for observed attributes (for TypeScript output) */
+    attributeTypes?: Record<string, 'string' | 'number' | 'boolean' | 'object'>;
+}
+/**
+ * Web components configuration
+ */
+export interface WebComponentConfig {
+    /** Enable web component integration */
+    enabled: boolean;
+    /** Directory to output web components */
+    outputDir: string;
+    /** Web components to build */
+    components: WebComponent[];
+}
+/** Reactive property emitted by the component-library compiler. */
+export interface ComponentLibraryProperty {
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    default?: unknown;
+    required?: boolean;
+    reflect?: boolean;
+    attribute?: string | false;
+    description?: string;
+}
+/** Public custom event emitted by a compiled component. */
+export interface ComponentLibraryEvent {
+    description?: string;
+    detailType?: string;
+}
+/** One .stx source entry in a component-library build. */
+export interface ComponentLibraryComponent {
+    file: string;
+    name?: string;
+    tag?: string;
+    description?: string;
+    shadowDOM?: boolean | 'open' | 'closed';
+    progressive?: boolean;
+    properties?: Record<string, ComponentLibraryProperty>;
+    events?: Record<string, ComponentLibraryEvent>;
+    methods?: Record<string, string>;
+}
+/** Build configuration for a standards-based web component library. */
+export interface ComponentLibraryConfig {
+    /** Directory recursively scanned for .stx files. */
+    inputDir: string;
+    /** Build output directory. */
+    outputDir: string;
+    /** Prefix used for inferred custom-element tags. Defaults to "stx". */
+    prefix?: string;
+    /** Explicit entries. When omitted, every .stx file is discovered. */
+    components?: ComponentLibraryComponent[];
+    /** Default rendering mode. Light DOM is the progressive default. */
+    shadowDOM?: boolean | 'open' | 'closed';
+    /** Preserve server-rendered markup until a reactive update. */
+    progressive?: boolean;
+    /** Generate custom-elements.json. */
+    manifest?: boolean;
+    /** Generate per-component, JSX, and index declarations. */
+    declarations?: boolean;
+    /** Generate per-component and bundled CSS. */
+    css?: boolean;
+    /** Generate a single tree-shakeable ESM bundle. */
+    bundle?: boolean;
+    /** Minify JavaScript and CSS output. */
+    minify?: boolean;
+    /** Generate source maps for bundle.js. */
+    sourcemap?: boolean | 'inline' | 'external';
+}
+export interface ComponentLibraryBuildResult {
+    components: Array<{
+        name: string;
+        tag: string;
+        source: string;
+        module: string;
+    }>;
+    files: string[];
+    manifest?: string;
+    bundle?: string;
+    cssBundle?: string;
+    totalBytes: number;
+}
+/**
+ * Documentation format options
+ */
+export type DocFormat = 'markdown' | 'html' | 'json';
+/**
+ * Component property documentation
+ */
+export interface ComponentPropDoc {
+    /** Name of the property */
+    name: string;
+    /** Type of the property (e.g., string, number, boolean) */
+    type?: string;
+    /** Whether the property is required */
+    required?: boolean;
+    /** Default value if any */
+    default?: string;
+    /** Description of the property */
+    description?: string;
+}
+/**
+ * Component documentation
+ */
+export interface ComponentDoc {
+    /** Name of the component */
+    name: string;
+    /** File path */
+    path: string;
+    /** Component description */
+    description?: string;
+    /** Component properties/attributes */
+    props: ComponentPropDoc[];
+    /** Example usage */
+    example?: string;
+    /** Whether this is a web component */
+    isWebComponent?: boolean;
+    /** HTML tag if it's a web component */
+    tag?: string;
+}
+/**
+ * Template documentation
+ */
+export interface TemplateDoc {
+    /** Template name */
+    name: string;
+    /** File path */
+    path: string;
+    /** Description */
+    description?: string;
+    /** Used components */
+    components?: string[];
+    /** Used directives */
+    directives?: string[];
+}
+/**
+ * Directive documentation
+ */
+export interface DirectiveDoc {
+    /** Directive name */
+    name: string;
+    /** Description */
+    description?: string;
+    /** Has end tag */
+    hasEndTag: boolean;
+    /** Example usage */
+    example?: string;
+}
+/**
+ * Documentation generator configuration
+ */
+export interface DocGeneratorConfig {
+    /** Enable documentation generation */
+    enabled: boolean;
+    /** Output directory for documentation */
+    outputDir: string;
+    /** Format of generated documentation */
+    format: DocFormat;
+    /** Generate docs for components */
+    components: boolean;
+    /** Generate docs for templates */
+    templates: boolean;
+    /** Generate docs for directives */
+    directives: boolean;
+    /** Extra content to include in documentation */
+    extraContent?: string;
+    /** Custom template for documentation */
+    template?: string;
+}