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

package/dist/type-checker.js

@@ -0,0 +1,581 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+const defaultOptions = {
+  strict: !1,
+  allowAny: !0,
+  checkPropertyAccess: !0,
+  checkFunctionCalls: !0,
+  includeBuiltins: !0
+}, builtinTypes = {
+  console: {
+    kind: "object",
+    properties: {
+      log: { kind: "function", params: [{ name: "message", type: { kind: "primitive", value: "any" } }], returnType: { kind: "primitive", value: "void" } },
+      error: { kind: "function", params: [{ name: "message", type: { kind: "primitive", value: "any" } }], returnType: { kind: "primitive", value: "void" } },
+      warn: { kind: "function", params: [{ name: "message", type: { kind: "primitive", value: "any" } }], returnType: { kind: "primitive", value: "void" } }
+    }
+  },
+  Math: {
+    kind: "object",
+    properties: {
+      abs: { kind: "function", params: [{ name: "x", type: { kind: "primitive", value: "number" } }], returnType: { kind: "primitive", value: "number" } },
+      floor: { kind: "function", params: [{ name: "x", type: { kind: "primitive", value: "number" } }], returnType: { kind: "primitive", value: "number" } },
+      ceil: { kind: "function", params: [{ name: "x", type: { kind: "primitive", value: "number" } }], returnType: { kind: "primitive", value: "number" } },
+      round: { kind: "function", params: [{ name: "x", type: { kind: "primitive", value: "number" } }], returnType: { kind: "primitive", value: "number" } },
+      max: { kind: "function", params: [{ name: "values", type: { kind: "primitive", value: "number" } }], returnType: { kind: "primitive", value: "number" } },
+      min: { kind: "function", params: [{ name: "values", type: { kind: "primitive", value: "number" } }], returnType: { kind: "primitive", value: "number" } },
+      random: { kind: "function", params: [], returnType: { kind: "primitive", value: "number" } },
+      PI: { kind: "primitive", value: "number" },
+      E: { kind: "primitive", value: "number" }
+    }
+  },
+  JSON: {
+    kind: "object",
+    properties: {
+      stringify: { kind: "function", params: [{ name: "value", type: { kind: "primitive", value: "any" } }], returnType: { kind: "primitive", value: "string" } },
+      parse: { kind: "function", params: [{ name: "text", type: { kind: "primitive", value: "string" } }], returnType: { kind: "primitive", value: "any" } }
+    }
+  },
+  Date: {
+    kind: "function",
+    returnType: {
+      kind: "object",
+      properties: {
+        getTime: { kind: "function", params: [], returnType: { kind: "primitive", value: "number" } },
+        toISOString: { kind: "function", params: [], returnType: { kind: "primitive", value: "string" } },
+        toLocaleDateString: { kind: "function", params: [], returnType: { kind: "primitive", value: "string" } }
+      }
+    }
+  },
+  Array: {
+    kind: "object",
+    properties: {
+      isArray: { kind: "function", params: [{ name: "value", type: { kind: "primitive", value: "any" } }], returnType: { kind: "primitive", value: "boolean" } },
+      from: { kind: "function", params: [{ name: "arrayLike", type: { kind: "primitive", value: "any" } }], returnType: { kind: "array", elementType: { kind: "primitive", value: "any" } } }
+    }
+  },
+  Object: {
+    kind: "object",
+    properties: {
+      keys: { kind: "function", params: [{ name: "obj", type: { kind: "primitive", value: "any" } }], returnType: { kind: "array", elementType: { kind: "primitive", value: "string" } } },
+      values: { kind: "function", params: [{ name: "obj", type: { kind: "primitive", value: "any" } }], returnType: { kind: "array", elementType: { kind: "primitive", value: "any" } } },
+      entries: { kind: "function", params: [{ name: "obj", type: { kind: "primitive", value: "any" } }], returnType: { kind: "array", elementType: { kind: "primitive", value: "any" } } }
+    }
+  },
+  String: {
+    kind: "function",
+    params: [{ name: "value", type: { kind: "primitive", value: "any" } }],
+    returnType: { kind: "primitive", value: "string" }
+  },
+  Number: {
+    kind: "function",
+    params: [{ name: "value", type: { kind: "primitive", value: "any" } }],
+    returnType: { kind: "primitive", value: "number" }
+  },
+  Boolean: {
+    kind: "function",
+    params: [{ name: "value", type: { kind: "primitive", value: "any" } }],
+    returnType: { kind: "primitive", value: "boolean" }
+  },
+  props: { kind: "object", properties: {} },
+  slot: { kind: "primitive", value: "string" },
+  loop: {
+    kind: "object",
+    properties: {
+      index: { kind: "primitive", value: "number" },
+      iteration: { kind: "primitive", value: "number" },
+      first: { kind: "primitive", value: "boolean" },
+      last: { kind: "primitive", value: "boolean" },
+      even: { kind: "primitive", value: "boolean" },
+      odd: { kind: "primitive", value: "boolean" },
+      count: { kind: "primitive", value: "number" },
+      remaining: { kind: "primitive", value: "number" },
+      depth: { kind: "primitive", value: "number" },
+      parent: { kind: "object", properties: {} }
+    }
+  }
+};
+
+export class TemplateTypeChecker {
+  options;
+  variables = new Map;
+  errors = [];
+  warnings = [];
+  currentFile = "";
+  constructor(options = {}) {
+    this.options = { ...defaultOptions, ...options };
+    if (this.options.includeBuiltins)
+      Object.entries(builtinTypes).forEach(([name, type]) => {
+        this.variables.set(name, type);
+      });
+    if (this.options.customTypes)
+      Object.entries(this.options.customTypes).forEach(([name, type]) => {
+        this.variables.set(name, type);
+      });
+  }
+  checkFile(filePath) {
+    this.currentFile = filePath;
+    this.errors = [];
+    this.warnings = [];
+    if (!existsSync(filePath)) {
+      this.errors.push({
+        message: `File not found: ${filePath}`,
+        file: filePath,
+        line: 0,
+        column: 0,
+        expression: "",
+        severity: "error"
+      });
+      return this.getResult();
+    }
+    const content = readFileSync(filePath, "utf-8");
+    return this.checkTemplate(content, filePath);
+  }
+  checkTemplate(template, filePath = "<inline>") {
+    this.currentFile = filePath;
+    this.errors = [];
+    this.warnings = [];
+    const scriptMatch = template.match(/<script\b[^>]*>([\s\S]*?)<\/script>/i);
+    if (scriptMatch)
+      this.analyzeScript(scriptMatch[1], template.indexOf(scriptMatch[0]));
+    this.checkDirectives(template);
+    this.checkExpressions(template);
+    return this.getResult();
+  }
+  analyzeScript(script, scriptOffset) {
+    const lines = script.split(`
+`);
+    let lineOffset = this.getLineNumber(scriptOffset);
+    for (let i = 0;i < lines.length; i++) {
+      const line = lines[i], lineNum = lineOffset + i;
+      this.extractTypedVariables(line, lineNum);
+      this.extractInterfaces(line, lines, i, lineNum);
+      this.extractTypeAliases(line, lineNum);
+    }
+  }
+  extractTypedVariables(line, lineNum) {
+    const typedMatch = line.match(/(?:export\s+)?(?:const|let|var)\s+(\w+)\s*:\s*([^=]+?)\s*=/);
+    if (typedMatch) {
+      const [, name, typeAnnotation] = typedMatch, type = this.parseTypeAnnotation(typeAnnotation.trim());
+      this.variables.set(name, type);
+      return;
+    }
+    const inferMatch = line.match(/(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(.+)/);
+    if (inferMatch) {
+      const [, name, value] = inferMatch, type = this.inferType(value.trim());
+      this.variables.set(name, type);
+      return;
+    }
+    const funcMatch = line.match(/(?:export\s+)?function\s+(\w+)\s*\(([^)]*)\)(?:\s*:\s*(\w+))?/);
+    if (funcMatch) {
+      const [, name, paramsStr, returnTypeStr] = funcMatch, params = this.parseParams(paramsStr), returnType = returnTypeStr ? this.parseTypeAnnotation(returnTypeStr) : { kind: "primitive", value: "any" };
+      this.variables.set(name, { kind: "function", params, returnType });
+    }
+  }
+  extractInterfaces(line, lines, index, lineNum) {
+    const interfaceMatch = line.match(/(?:export\s+)?interface\s+(\w+)\s*\{/);
+    if (interfaceMatch) {
+      const [, name] = interfaceMatch, properties = {};
+      let braceCount = 1, i = index + 1;
+      while (i < lines.length && braceCount > 0) {
+        const propLine = lines[i].trim();
+        if (propLine.includes("{"))
+          braceCount++;
+        if (propLine.includes("}"))
+          braceCount--;
+        const propMatch = propLine.match(/(\w+)\??\s*:\s*([^;]+)/);
+        if (propMatch && braceCount > 0) {
+          const [, propName, propType] = propMatch;
+          properties[propName] = this.parseTypeAnnotation(propType.trim());
+        }
+        i++;
+      }
+      this.variables.set(name, { kind: "object", name, properties });
+    }
+  }
+  extractTypeAliases(line, lineNum) {
+    const typeMatch = line.match(/(?:export\s+)?type\s+(\w+)\s*=\s*(.+)/);
+    if (typeMatch) {
+      const [, name, typeExpr] = typeMatch, type = this.parseTypeAnnotation(typeExpr.trim());
+      type.name = name;
+      this.variables.set(name, type);
+    }
+  }
+  parseTypeAnnotation(annotation) {
+    const trimmed = annotation.trim();
+    if (trimmed.includes("|"))
+      return { kind: "union", types: trimmed.split("|").map((t) => this.parseTypeAnnotation(t.trim())) };
+    if (trimmed.includes("&"))
+      return { kind: "intersection", types: trimmed.split("&").map((t) => this.parseTypeAnnotation(t.trim())) };
+    if (trimmed.endsWith("[]"))
+      return { kind: "array", elementType: this.parseTypeAnnotation(trimmed.slice(0, -2)) };
+    const arrayMatch = trimmed.match(/^Array<(.+)>$/);
+    if (arrayMatch)
+      return { kind: "array", elementType: this.parseTypeAnnotation(arrayMatch[1]) };
+    if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+      const properties = {}, inner = trimmed.slice(1, -1).trim();
+      if (inner) {
+        const propParts = this.splitByComma(inner);
+        for (const part of propParts) {
+          const propMatch = part.match(/(\w+)\??\s*:\s*(.+)/);
+          if (propMatch) {
+            const [, propName, propType] = propMatch;
+            properties[propName] = this.parseTypeAnnotation(propType.trim());
+          }
+        }
+      }
+      return { kind: "object", properties };
+    }
+    if (trimmed.startsWith('"') || trimmed.startsWith("'"))
+      return { kind: "literal", value: trimmed.slice(1, -1) };
+    if (/^\d+$/.test(trimmed))
+      return { kind: "literal", value: trimmed };
+    if (trimmed === "true" || trimmed === "false")
+      return { kind: "literal", value: trimmed };
+    if (["string", "number", "boolean", "null", "undefined", "any", "unknown", "void", "never"].includes(trimmed))
+      return { kind: "primitive", value: trimmed };
+    if (this.variables.has(trimmed))
+      return this.variables.get(trimmed);
+    return { kind: "primitive", value: "any" };
+  }
+  inferType(value) {
+    const trimmed = value.trim().replace(/;$/, "");
+    if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'") || trimmed.startsWith("`") && trimmed.endsWith("`"))
+      return { kind: "primitive", value: "string" };
+    if (/^-?\d+(\.\d+)?$/.test(trimmed))
+      return { kind: "primitive", value: "number" };
+    if (trimmed === "true" || trimmed === "false")
+      return { kind: "primitive", value: "boolean" };
+    if (trimmed === "null")
+      return { kind: "primitive", value: "null" };
+    if (trimmed === "undefined")
+      return { kind: "primitive", value: "undefined" };
+    if (trimmed.startsWith("[")) {
+      const inner = trimmed.slice(1, -1).trim();
+      if (inner) {
+        const firstElement = this.splitByComma(inner)[0];
+        if (firstElement)
+          return { kind: "array", elementType: this.inferType(firstElement.trim()) };
+      }
+      return { kind: "array", elementType: { kind: "primitive", value: "any" } };
+    }
+    if (trimmed.startsWith("{")) {
+      const properties = {}, inner = this.extractObjectLiteral(trimmed);
+      for (const [key, val] of Object.entries(inner))
+        properties[key] = this.inferType(val);
+      return { kind: "object", properties };
+    }
+    if (trimmed.includes("=>")) {
+      const arrowMatch = trimmed.match(/^\(([^)]*)\)\s*(?::\s*(\w+))?\s*=>/);
+      if (arrowMatch) {
+        const params = this.parseParams(arrowMatch[1]), returnType = arrowMatch[2] ? this.parseTypeAnnotation(arrowMatch[2]) : { kind: "primitive", value: "any" };
+        return { kind: "function", params, returnType };
+      }
+    }
+    if (/^\w+$/.test(trimmed) && this.variables.has(trimmed))
+      return this.variables.get(trimmed);
+    if (trimmed.includes("."))
+      return this.resolvePropertyAccess(trimmed);
+    if (trimmed.includes("(")) {
+      const funcName = trimmed.split("(")[0], funcType = this.variables.get(funcName);
+      if (funcType?.kind === "function" && funcType.returnType)
+        return funcType.returnType;
+    }
+    return { kind: "primitive", value: "any" };
+  }
+  parseParams(paramsStr) {
+    if (!paramsStr.trim())
+      return [];
+    const params = [], parts = this.splitByComma(paramsStr);
+    for (const part of parts) {
+      const trimmed = part.trim(), optional = trimmed.includes("?"), paramMatch = trimmed.match(/(\w+)\??\s*(?::\s*([^=]+))?(?:\s*=)?/);
+      if (paramMatch) {
+        const [, name, typeStr] = paramMatch, type = typeStr ? this.parseTypeAnnotation(typeStr.trim()) : { kind: "primitive", value: "any" };
+        params.push({ name, type, optional });
+      }
+    }
+    return params;
+  }
+  checkExpressions(template) {
+    const expressionRegex = /\{\{([\s\S]*?)\}\}/g;
+    let match;
+    while ((match = expressionRegex.exec(template)) !== null) {
+      const expression = match[1].trim(), position = match.index, lineNum = this.getLineNumber(position, template), column = this.getColumn(position, template);
+      if (!expression)
+        continue;
+      if (expression.startsWith("!") || expression.endsWith("!"))
+        continue;
+      this.checkExpression(expression, lineNum, column);
+    }
+    const rawRegex = /\{!!([\s\S]*?)!!\}/g;
+    while ((match = rawRegex.exec(template)) !== null) {
+      const expression = match[1].trim(), position = match.index, lineNum = this.getLineNumber(position, template), column = this.getColumn(position, template);
+      if (!expression)
+        continue;
+      this.checkExpression(expression, lineNum, column);
+    }
+  }
+  checkExpression(expression, line, column) {
+    if (expression.includes("?") && expression.includes(":")) {
+      const parts = expression.split("?");
+      this.checkExpression(parts[0].trim(), line, column);
+      const elseParts = parts.slice(1).join("?").split(":");
+      if (elseParts.length >= 2) {
+        this.checkExpression(elseParts[0].trim(), line, column);
+        this.checkExpression(elseParts.slice(1).join(":").trim(), line, column);
+      }
+      return;
+    }
+    for (const op of ["&&", "||", "??"])
+      if (expression.includes(op)) {
+        expression.split(op).forEach((p) => this.checkExpression(p.trim(), line, column));
+        return;
+      }
+    for (const op of ["===", "!==", "==", "!=", ">=", "<=", ">", "<"])
+      if (expression.includes(op)) {
+        expression.split(op).forEach((p) => this.checkExpression(p.trim(), line, column));
+        return;
+      }
+    if (expression.startsWith("!")) {
+      this.checkExpression(expression.slice(1).trim(), line, column);
+      return;
+    }
+    if (this.isLiteral(expression))
+      return;
+    const funcCallMatch = expression.match(/^(\w+(?:\.\w+)*)\s*\(/);
+    if (funcCallMatch) {
+      const funcPath = funcCallMatch[1], type = this.resolvePropertyAccess(funcPath);
+      if (type.kind !== "function" && type.value !== "any")
+        this.addWarning(`'${funcPath}' is not a function`, line, column, expression);
+      return;
+    }
+    if (expression.includes(".")) {
+      if (this.resolvePropertyAccess(expression).value === "undefined" && this.options.checkPropertyAccess)
+        this.addWarning(`Property access '${expression}' may be undefined`, line, column, expression);
+      return;
+    }
+    const varName = expression.match(/^\w+/)?.[0];
+    if (varName && !this.variables.has(varName))
+      this.addError(`Variable '${varName}' is not defined`, line, column, expression);
+  }
+  checkDirectives(template) {
+    const ifRegex = /@if\s*\(([^)]+)\)/g;
+    let match;
+    while ((match = ifRegex.exec(template)) !== null) {
+      const condition = match[1].trim(), position = match.index, lineNum = this.getLineNumber(position, template), column = this.getColumn(position, template);
+      this.checkExpression(condition, lineNum, column);
+    }
+    const foreachRegex = /@foreach\s*\((\w+)\s+(?:as|in)\s+(\w+)(?:\s*,\s*(\w+))?\)/g;
+    while ((match = foreachRegex.exec(template)) !== null) {
+      const [, collection, item, index] = match, position = match.index, lineNum = this.getLineNumber(position, template), column = this.getColumn(position, template);
+      if (!this.variables.has(collection))
+        this.addError(`Collection '${collection}' is not defined`, lineNum, column, match[0]);
+      else {
+        const collectionType = this.variables.get(collection);
+        if (collectionType.kind === "array" && collectionType.elementType)
+          this.variables.set(item, collectionType.elementType);
+        else
+          this.variables.set(item, { kind: "primitive", value: "any" });
+        if (index)
+          this.variables.set(index, { kind: "primitive", value: "number" });
+      }
+    }
+    const unlessRegex = /@unless\s*\(([^)]+)\)/g;
+    while ((match = unlessRegex.exec(template)) !== null) {
+      const condition = match[1].trim(), position = match.index, lineNum = this.getLineNumber(position, template), column = this.getColumn(position, template);
+      this.checkExpression(condition, lineNum, column);
+    }
+    const switchRegex = /@switch\s*\(([^)]+)\)/g;
+    while ((match = switchRegex.exec(template)) !== null) {
+      const expr = match[1].trim(), position = match.index, lineNum = this.getLineNumber(position, template), column = this.getColumn(position, template);
+      this.checkExpression(expr, lineNum, column);
+    }
+  }
+  resolvePropertyAccess(expr) {
+    const parts = expr.split(".");
+    let currentType = this.variables.get(parts[0]) || { kind: "primitive", value: "any" };
+    for (let i = 1;i < parts.length; i++) {
+      const prop = parts[i].replace(/\(\)$/, "");
+      if (currentType.kind === "object" && currentType.properties)
+        if (currentType.properties[prop])
+          currentType = currentType.properties[prop];
+        else if (!this.options.allowAny)
+          return { kind: "primitive", value: "undefined" };
+        else
+          currentType = { kind: "primitive", value: "any" };
+      else if (currentType.kind === "array" && currentType.elementType)
+        if (["length"].includes(prop))
+          currentType = { kind: "primitive", value: "number" };
+        else if (["map", "filter", "find", "forEach", "some", "every", "reduce"].includes(prop))
+          currentType = { kind: "function", returnType: { kind: "primitive", value: "any" } };
+        else if (["join"].includes(prop))
+          currentType = { kind: "function", returnType: { kind: "primitive", value: "string" } };
+        else
+          currentType = { kind: "primitive", value: "any" };
+      else if (currentType.kind === "primitive" && currentType.value === "string")
+        if (["length"].includes(prop))
+          currentType = { kind: "primitive", value: "number" };
+        else if (["toUpperCase", "toLowerCase", "trim", "slice", "substring"].includes(prop))
+          currentType = { kind: "function", returnType: { kind: "primitive", value: "string" } };
+        else if (["split"].includes(prop))
+          currentType = { kind: "function", returnType: { kind: "array", elementType: { kind: "primitive", value: "string" } } };
+        else
+          currentType = { kind: "primitive", value: "any" };
+      else
+        currentType = { kind: "primitive", value: "any" };
+    }
+    return currentType;
+  }
+  isLiteral(expr) {
+    const trimmed = expr.trim();
+    if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'") || trimmed.startsWith("`") && trimmed.endsWith("`"))
+      return !0;
+    if (/^-?\d+(\.\d+)?$/.test(trimmed))
+      return !0;
+    if (trimmed === "true" || trimmed === "false")
+      return !0;
+    if (trimmed === "null" || trimmed === "undefined")
+      return !0;
+    return !1;
+  }
+  extractObjectLiteral(expr) {
+    const result = {}, inner = expr.slice(1, -1).trim();
+    if (!inner)
+      return result;
+    const parts = this.splitByComma(inner);
+    for (const part of parts) {
+      const colonIdx = part.indexOf(":");
+      if (colonIdx > 0) {
+        const key = part.slice(0, colonIdx).trim(), value = part.slice(colonIdx + 1).trim();
+        result[key] = value;
+      }
+    }
+    return result;
+  }
+  splitByComma(str) {
+    const parts = [];
+    let current = "", depth = 0, inString = null;
+    for (let i = 0;i < str.length; i++) {
+      const char = str[i], prevChar = i > 0 ? str[i - 1] : "";
+      if ((char === '"' || char === "'" || char === "`") && prevChar !== "\\") {
+        if (inString === char)
+          inString = null;
+        else if (!inString)
+          inString = char;
+      }
+      if (!inString) {
+        if (char === "{" || char === "[" || char === "(")
+          depth++;
+        if (char === "}" || char === "]" || char === ")")
+          depth--;
+        if (char === "," && depth === 0) {
+          parts.push(current.trim());
+          current = "";
+          continue;
+        }
+      }
+      current += char;
+    }
+    if (current.trim())
+      parts.push(current.trim());
+    return parts;
+  }
+  getLineNumber(position, template) {
+    return ((template || "").slice(0, position).match(/\n/g) || []).length + 1;
+  }
+  getColumn(position, template) {
+    const lastNewline = template.slice(0, position).lastIndexOf(`
+`);
+    return position - lastNewline;
+  }
+  addError(message, line, column, expression, expected, received) {
+    this.errors.push({
+      message,
+      file: this.currentFile,
+      line,
+      column,
+      expression,
+      expected,
+      received,
+      severity: "error"
+    });
+  }
+  addWarning(message, line, column, expression, expected, received) {
+    const error = {
+      message,
+      file: this.currentFile,
+      line,
+      column,
+      expression,
+      expected,
+      received,
+      severity: "warning"
+    };
+    if (this.options.strict)
+      this.errors.push(error);
+    else
+      this.warnings.push(error);
+  }
+  getResult() {
+    return {
+      valid: this.errors.length === 0,
+      errors: this.errors,
+      warnings: this.warnings,
+      variables: new Map(this.variables)
+    };
+  }
+  addVariable(name, type) {
+    this.variables.set(name, type);
+  }
+  reset() {
+    this.errors = [];
+    this.warnings = [];
+    this.variables.clear();
+    if (this.options.includeBuiltins)
+      Object.entries(builtinTypes).forEach(([name, type]) => {
+        this.variables.set(name, type);
+      });
+  }
+}
+export function createTypeChecker(options) {
+  return new TemplateTypeChecker(options);
+}
+export function checkTemplateFile(filePath, options) {
+  return createTypeChecker(options).checkFile(filePath);
+}
+export function checkTemplate(template, options) {
+  return createTypeChecker(options).checkTemplate(template);
+}
+export function formatTypeErrors(result) {
+  const lines = [];
+  for (const error of result.errors) {
+    lines.push(`\x1B[31merror\x1B[0m: ${error.message}`);
+    lines.push(`  --> ${error.file}:${error.line}:${error.column}`);
+    if (error.expression) {
+      lines.push("   |");
+      lines.push(`   | ${error.expression}`);
+      lines.push("   |");
+    }
+    if (error.expected && error.received) {
+      lines.push(`  expected: ${error.expected}`);
+      lines.push(`  received: ${error.received}`);
+    }
+    lines.push("");
+  }
+  for (const warning of result.warnings) {
+    lines.push(`\x1B[33mwarning\x1B[0m: ${warning.message}`);
+    lines.push(`  --> ${warning.file}:${warning.line}:${warning.column}`);
+    if (warning.expression) {
+      lines.push("   |");
+      lines.push(`   | ${warning.expression}`);
+      lines.push("   |");
+    }
+    lines.push("");
+  }
+  if (result.valid)
+    lines.push("\x1B[32m\u2713 No type errors found\x1B[0m");
+  else
+    lines.push(`\x1B[31m\u2717 Found ${result.errors.length} error(s) and ${result.warnings.length} warning(s)\x1B[0m`);
+  return lines.join(`
+`);
+}

package/dist/typecheck.d.ts

@@ -0,0 +1,70 @@
+import { extractScriptBlocks } from './stx-virtual-ts';
+import type { ScriptBlock, ScriptKind } from './stx-virtual-ts';
+export type { ScriptBlock, ScriptKind } from './stx-virtual-ts';
+/**
+ * Build the virtual TypeScript source for one block.
+ *
+ * The body is prefixed with blank lines so its first line lands on the same line
+ * number it occupies in the `.stx` file — which makes every diagnostic's line
+ * number directly usable with no mapping table.
+ *
+ * The trailing `export {}` makes the buffer a MODULE, and that is load-bearing.
+ * Without it a block with no imports is a global script, so every top-level
+ * declaration collides with the DOM lib: `const name = …` and `const status = …`
+ * in a `<script server>` block both reported "Cannot redeclare block-scoped
+ * variable", and those are ordinary names for server-rendered page data. It is
+ * appended rather than prepended so the line numbers above it are untouched.
+ *
+ * `originDir` is the directory the `.stx` file really lives in. The buffer is
+ * written into the state directory, and tsc resolves a relative specifier
+ * against the file containing it — so without this, `../target` was looked for
+ * next to `.stx/typecheck/` (#1928).
+ */
+export declare function buildVirtualSource(block: ScriptBlock, serverCode?: string, originDir?: string): string;
+/** Virtual path for a block, stable and traceable back to its origin. */
+export declare function virtualPathFor(filePath: string, kind: DiagnosticOrigin, index: number): string;
+/** Map a virtual path back to the `.stx` file it came from. */
+export declare function sourcePathFor(virtualPath: string): string;
+/**
+ * Locate the package's own `stx.d.ts`, which types the runtime globals.
+ *
+ * Checked rather than assumed: this module runs from `src/` in the repo and
+ * from `dist/` when installed, and both sit one level under the package root.
+ * Returns `null` when it is genuinely absent so the caller can fall back rather
+ * than hand tsc a path to nothing.
+ */
+export declare function findRuntimeTypeDeclarations(): string | null;
+export declare function typecheckStxFiles(files: string[], options?: TypecheckOptions): Promise<TypecheckResult>;
+/** Render diagnostics the way a CLI should: file:line:col, then the message. */
+export declare function formatTypecheckDiagnostics(diagnostics: TypecheckDiagnostic[]): string;
+export declare interface TypecheckDiagnostic {
+  file: string
+  line: number
+  column: number
+  code: number
+  message: string
+  category: 'error' | 'warning' | 'suggestion' | 'message'
+  blockKind: DiagnosticOrigin
+  expression?: string
+}
+export declare interface TypecheckOptions {
+  extraLibs?: string[]
+  client?: boolean
+  server?: boolean
+  templates?: boolean
+  compilerOptions?: Record<string, unknown>
+}
+export declare interface TypecheckResult {
+  diagnostics: TypecheckDiagnostic[]
+  failure?: string
+  checkedFiles: string[]
+  blockCount: number
+  expressionCount: number
+}
+/** Where a diagnostic came from: a script block, or the markup itself. */
+export type DiagnosticOrigin = ScriptKind | 'template';
+export {
+  extractScriptBlocks,
+  extractTemplateExpressions,
+  type TemplateExpression,
+} from './stx-virtual-ts';