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

package/dist/typescript-templates.js

@@ -0,0 +1,386 @@
+export function parseTypeAnnotation(typeStr) {
+  const trimmed = typeStr.trim();
+  if (["string", "number", "boolean", "null", "undefined", "any", "unknown", "never", "void"].includes(trimmed))
+    return { kind: "primitive", value: trimmed };
+  if (trimmed.endsWith("[]"))
+    return {
+      kind: "array",
+      elementType: parseTypeAnnotation(trimmed.slice(0, -2))
+    };
+  if (trimmed.startsWith("Array<") && trimmed.endsWith(">"))
+    return {
+      kind: "array",
+      elementType: parseTypeAnnotation(trimmed.slice(6, -1))
+    };
+  if (trimmed.includes("|") && !trimmed.startsWith("{") && !trimmed.startsWith("("))
+    return { kind: "union", types: splitByOperator(trimmed, "|").map((t) => parseTypeAnnotation(t)) };
+  if (trimmed.includes("&") && !trimmed.startsWith("{") && !trimmed.startsWith("("))
+    return { kind: "intersection", types: splitByOperator(trimmed, "&").map((t) => parseTypeAnnotation(t)) };
+  if (trimmed.startsWith("'") && trimmed.endsWith("'") || trimmed.startsWith('"') && trimmed.endsWith('"'))
+    return { kind: "literal", literalValue: trimmed.slice(1, -1) };
+  if (/^\d+$/.test(trimmed))
+    return { kind: "literal", literalValue: Number.parseInt(trimmed) };
+  if (trimmed === "true" || trimmed === "false")
+    return { kind: "literal", literalValue: trimmed === "true" };
+  if (trimmed.startsWith("{") && trimmed.endsWith("}"))
+    return parseObjectType(trimmed);
+  if (trimmed.includes("=>"))
+    return parseFunctionType(trimmed);
+  if (trimmed.includes("<") && trimmed.endsWith(">")) {
+    const baseEnd = trimmed.indexOf("<"), baseName = trimmed.slice(0, baseEnd), argsStr = trimmed.slice(baseEnd + 1, -1), typeArgs = splitByComma(argsStr).map((t) => parseTypeAnnotation(t));
+    return { kind: "generic", value: baseName, typeArguments: typeArgs };
+  }
+  return { kind: "reference", value: trimmed };
+}
+function parseObjectType(typeStr) {
+  const inner = typeStr.slice(1, -1).trim(), properties = {};
+  if (!inner)
+    return { kind: "object", properties };
+  const members = splitObjectMembers(inner);
+  for (const member of members) {
+    const trimmedMember = member.trim();
+    if (!trimmedMember)
+      continue;
+    const readonlyMatch = trimmedMember.startsWith("readonly "), withoutReadonly = readonlyMatch ? trimmedMember.slice(9) : trimmedMember, colonIndex = withoutReadonly.indexOf(":");
+    if (colonIndex === -1)
+      continue;
+    let propName = withoutReadonly.slice(0, colonIndex).trim();
+    const propType = withoutReadonly.slice(colonIndex + 1).trim(), optional = propName.endsWith("?");
+    if (optional)
+      propName = propName.slice(0, -1);
+    properties[propName] = {
+      type: parseTypeAnnotation(propType),
+      optional,
+      readonly: readonlyMatch
+    };
+  }
+  return { kind: "object", properties };
+}
+function parseFunctionType(typeStr) {
+  const arrowIndex = typeStr.indexOf("=>"), paramsStr = typeStr.slice(0, arrowIndex).trim(), returnStr = typeStr.slice(arrowIndex + 2).trim(), parameters = [];
+  if (paramsStr.startsWith("(") && paramsStr.endsWith(")")) {
+    const inner = paramsStr.slice(1, -1), params = splitByComma(inner);
+    for (const param of params) {
+      const trimmed = param.trim();
+      if (!trimmed)
+        continue;
+      const rest = trimmed.startsWith("..."), withoutRest = rest ? trimmed.slice(3) : trimmed, colonIndex = withoutRest.indexOf(":");
+      if (colonIndex === -1)
+        parameters.push({
+          name: withoutRest,
+          type: { kind: "primitive", value: "any" },
+          optional: !1,
+          rest
+        });
+      else {
+        let name = withoutRest.slice(0, colonIndex).trim();
+        const type = withoutRest.slice(colonIndex + 1).trim(), optional = name.endsWith("?");
+        if (optional)
+          name = name.slice(0, -1);
+        parameters.push({
+          name,
+          type: parseTypeAnnotation(type),
+          optional,
+          rest
+        });
+      }
+    }
+  }
+  return {
+    kind: "function",
+    parameters,
+    returnType: parseTypeAnnotation(returnStr)
+  };
+}
+function splitByOperator(str, operator) {
+  const results = [];
+  let current = "", depth = 0;
+  for (let i = 0;i < str.length; i++) {
+    const char = str[i];
+    if (char === "<" || char === "(" || char === "{" || char === "[") {
+      depth++;
+      current += char;
+    } else if (char === ">" || char === ")" || char === "}" || char === "]") {
+      depth--;
+      current += char;
+    } else if (char === operator && depth === 0) {
+      results.push(current.trim());
+      current = "";
+    } else
+      current += char;
+  }
+  if (current.trim())
+    results.push(current.trim());
+  return results;
+}
+function splitByComma(str) {
+  return splitByOperator(str, ",");
+}
+function splitObjectMembers(str) {
+  const results = [];
+  let current = "", depth = 0;
+  for (let i = 0;i < str.length; i++) {
+    const char = str[i];
+    if (char === "<" || char === "(" || char === "{" || char === "[") {
+      depth++;
+      current += char;
+    } else if (char === ">" || char === ")" || char === "}" || char === "]") {
+      depth--;
+      current += char;
+    } else if ((char === ";" || char === `
+`) && depth === 0) {
+      if (current.trim())
+        results.push(current.trim());
+      current = "";
+    } else
+      current += char;
+  }
+  if (current.trim())
+    results.push(current.trim());
+  return results;
+}
+function parseInterfaceDeclarations(content) {
+  const results = [], interfaceKeyword = /interface\s+(\w+)(?:\s+extends\s+([\w,\s]+))?\s*\{/g;
+  let match;
+  while ((match = interfaceKeyword.exec(content)) !== null) {
+    const name = match[1], extendsClause = match[2], startBrace = match.index + match[0].length - 1;
+    let depth = 1, pos = startBrace + 1;
+    while (pos < content.length && depth > 0) {
+      if (content[pos] === "{")
+        depth++;
+      else if (content[pos] === "}")
+        depth--;
+      pos++;
+    }
+    const body = content.slice(startBrace + 1, pos - 1);
+    results.push({
+      name,
+      body,
+      extends: extendsClause ? extendsClause.split(",").map((s) => s.trim()) : void 0
+    });
+  }
+  return results;
+}
+export function extractTypesFromTemplate(template) {
+  const interfaces = [], typeAliases = [], errors = [];
+  let contextType;
+  const typesBlockRegex = /@types\s*([\s\S]*?)@endtypes/g, typesBlocks = template.matchAll(typesBlockRegex);
+  for (const match of typesBlocks) {
+    const content = match[1], interfaceParsed = parseInterfaceDeclarations(content);
+    for (const parsed of interfaceParsed) {
+      const parsedType = parseObjectType(`{${parsed.body}}`), iface = {
+        name: parsed.name,
+        properties: parsedType.properties || {},
+        extends: parsed.extends
+      };
+      interfaces.push(iface);
+      if (parsed.name === "PageContext" || parsed.name === "TemplateContext" || parsed.name === "Context")
+        contextType = iface;
+    }
+    const typeAliasRegex = /type\s+(\w+)\s*=\s*([^;]+);?/g, typeAliasMatches = content.matchAll(typeAliasRegex);
+    for (const typeMatch of typeAliasMatches) {
+      const name = typeMatch[1], typeStr = typeMatch[2].trim();
+      typeAliases.push({
+        name,
+        type: parseTypeAnnotation(typeStr)
+      });
+    }
+  }
+  if (!contextType && interfaces.length > 0)
+    contextType = interfaces[0];
+  return { interfaces, typeAliases, contextType, errors };
+}
+export function createTypeContext(extracted, runtimeContext) {
+  const ctx = {
+    interfaces: new Map,
+    typeAliases: new Map,
+    variables: new Map,
+    errors: [],
+    warnings: []
+  };
+  for (const iface of extracted.interfaces)
+    ctx.interfaces.set(iface.name, iface);
+  for (const alias of extracted.typeAliases)
+    ctx.typeAliases.set(alias.name, alias);
+  if (extracted.contextType)
+    for (const [name, prop] of Object.entries(extracted.contextType.properties))
+      ctx.variables.set(name, prop.type);
+  if (runtimeContext && ctx.variables.size === 0)
+    for (const [name, value] of Object.entries(runtimeContext))
+      ctx.variables.set(name, inferTypeFromValue(value));
+  return ctx;
+}
+export function inferTypeFromValue(value) {
+  if (value === null)
+    return { kind: "primitive", value: "null" };
+  if (value === void 0)
+    return { kind: "primitive", value: "undefined" };
+  const type = typeof value;
+  if (type === "string")
+    return { kind: "primitive", value: "string" };
+  if (type === "number")
+    return { kind: "primitive", value: "number" };
+  if (type === "boolean")
+    return { kind: "primitive", value: "boolean" };
+  if (type === "function")
+    return { kind: "function", parameters: [], returnType: { kind: "primitive", value: "any" } };
+  if (Array.isArray(value)) {
+    if (value.length === 0)
+      return { kind: "array", elementType: { kind: "primitive", value: "any" } };
+    return { kind: "array", elementType: inferTypeFromValue(value[0]) };
+  }
+  if (type === "object") {
+    const properties = {};
+    for (const [key, val] of Object.entries(value))
+      properties[key] = {
+        type: inferTypeFromValue(val),
+        optional: !1,
+        readonly: !1
+      };
+    return { kind: "object", properties };
+  }
+  return { kind: "primitive", value: "any" };
+}
+export function typeCheckExpression(expression, context) {
+  const trimmed = expression.trim();
+  if (/^\w+$/.test(trimmed)) {
+    const varType = context.variables.get(trimmed);
+    if (!varType)
+      return {
+        message: `Unknown variable '${trimmed}'`,
+        expression: trimmed
+      };
+    return varType;
+  }
+  if (trimmed.includes(".")) {
+    const parts = trimmed.split(".");
+    let currentType = context.variables.get(parts[0]);
+    if (!currentType)
+      return {
+        message: `Unknown variable '${parts[0]}'`,
+        expression: trimmed
+      };
+    for (let i = 1;i < parts.length; i++) {
+      const prop = parts[i], propName = prop.endsWith("?") ? prop.slice(0, -1) : prop;
+      if (!currentType)
+        return {
+          message: `Cannot access property '${propName}' on undefined type`,
+          expression: trimmed
+        };
+      if (currentType.kind === "object" && currentType.properties) {
+        const propDef = currentType.properties[propName];
+        if (!propDef)
+          return {
+            message: `Property '${propName}' does not exist on type`,
+            expression: trimmed
+          };
+        currentType = propDef.type;
+      } else if (currentType.kind === "reference") {
+        const iface = context.interfaces.get(currentType.value);
+        if (iface && iface.properties[propName])
+          currentType = iface.properties[propName].type;
+        else
+          return {
+            message: `Property '${propName}' does not exist on type '${currentType.value}'`,
+            expression: trimmed
+          };
+      } else if (currentType.kind === "array" && propName === "length")
+        currentType = { kind: "primitive", value: "number" };
+      else
+        return {
+          message: `Cannot access property '${propName}' on type`,
+          expression: trimmed
+        };
+    }
+    return currentType ?? { kind: "primitive", value: "any" };
+  }
+  return { kind: "primitive", value: "any" };
+}
+export function validateTemplateTypes(template, context) {
+  const errors = [], exprRegex = /\{\{([^}]+)\}\}/g, matches = template.matchAll(exprRegex);
+  for (const match of matches) {
+    const expression = match[1].trim();
+    if (expression.includes("|"))
+      continue;
+    const result = typeCheckExpression(expression, context);
+    if ("message" in result)
+      errors.push(result);
+  }
+  return errors;
+}
+export function generateTypeDefinitions(templatePath, extracted) {
+  const lines = [
+    "// Auto-generated by stx - DO NOT EDIT",
+    `// Source: ${templatePath}`,
+    "",
+    'declare module "*.stx" {'
+  ];
+  for (const iface of extracted.interfaces) {
+    lines.push(`  export interface ${iface.name} {`);
+    for (const [propName, prop] of Object.entries(iface.properties)) {
+      const optional = prop.optional ? "?" : "", readonly = prop.readonly ? "readonly " : "";
+      lines.push(`    ${readonly}${propName}${optional}: ${typeToString(prop.type)};`);
+    }
+    lines.push("  }");
+    lines.push("");
+  }
+  for (const alias of extracted.typeAliases)
+    lines.push(`  export type ${alias.name} = ${typeToString(alias.type)};`);
+  if (extracted.contextType) {
+    lines.push("");
+    lines.push(`  export function render(context: ${extracted.contextType.name}): Promise<string>;`);
+  } else {
+    lines.push("");
+    lines.push("  export function render(context: Record<string, unknown>): Promise<string>;");
+  }
+  lines.push("}");
+  const filename = templatePath.replace(/\.stx$/, ".d.ts");
+  return {
+    content: lines.join(`
+`),
+    filename
+  };
+}
+export function typeToString(type) {
+  switch (type.kind) {
+    case "primitive":
+      return type.value || "any";
+    case "array":
+      return `Array<${typeToString(type.elementType)}>`;
+    case "object": {
+      if (!type.properties || Object.keys(type.properties).length === 0)
+        return "{}";
+      return `{ ${Object.entries(type.properties).map(([name, prop]) => {
+        const opt = prop.optional ? "?" : "";
+        return `${prop.readonly ? "readonly " : ""}${name}${opt}: ${typeToString(prop.type)}`;
+      }).join("; ")} }`;
+    }
+    case "union":
+      return type.types.map((t) => typeToString(t)).join(" | ");
+    case "intersection":
+      return type.types.map((t) => typeToString(t)).join(" & ");
+    case "literal":
+      if (typeof type.literalValue === "string")
+        return `'${type.literalValue}'`;
+      return String(type.literalValue);
+    case "function":
+      return `(${(type.parameters || []).map((p) => {
+        const opt = p.optional ? "?" : "";
+        return `${p.rest ? "..." : ""}${p.name}${opt}: ${typeToString(p.type)}`;
+      }).join(", ")}) => ${typeToString(type.returnType)}`;
+    case "generic":
+      return `${type.value}<${type.typeArguments.map((t) => typeToString(t)).join(", ")}>`;
+    case "reference":
+      return type.value || "unknown";
+    default:
+      return "unknown";
+  }
+}
+export function processTypesDirective(template) {
+  const types = extractTypesFromTemplate(template);
+  return { template: template.replace(/@types\s*[\s\S]*?@endtypes/g, ""), types };
+}
+export function compileTimeTypeCheck(template, runtimeContext) {
+  const { types } = processTypesDirective(template), context = createTypeContext(types, runtimeContext);
+  return { errors: validateTemplateTypes(template, context), warnings: context.warnings };
+}

package/dist/unresolved-identifiers.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Diagnose an identifier a client script calls that will not exist in the browser.
+ *
+ * `packages/stx/src/composables/` exports 149 functions. Only 29 of them reach
+ * the client runtime; the other 120 are module exports with no counterpart on
+ * `window.stx`. They type-check, they autocomplete, and calling one from a
+ * `<script client>` block throws `ReferenceError` — which used to take down the
+ * whole page (fixed in the DOMContentLoaded handler, stacksjs/stx#1805).
+ *
+ * Containing the throw stops one bad name costing the document, but the author
+ * still has to work out WHY a documented, exported, type-checking composable is
+ * not defined. This turns that into a message at compile time naming the
+ * identifier, the file, and the fix.
+ *
+ * Deliberately a warning, not a build failure. #1810 is a report of the dev
+ * server aborting on one bad view with no filename; adding a second way to abort
+ * the build would be solving one complaint by creating another.
+ */
+/**
+ * Functions `composables/index.ts` exports that the client runtime does NOT
+ * provide.
+ *
+ * Generated — `test/unresolved-identifiers.test.ts` recomputes it from the real
+ * module surface and fails when this drifts, so it cannot silently rot the way
+ * the auto-import list did (#1804).
+ */
+export declare const SERVER_ONLY_COMPOSABLES: readonly string[];
+export interface UnresolvedIdentifier {
+    /** The identifier as written. */
+    name: string;
+    /** Human-readable explanation, including the fix. */
+    message: string;
+}
+/**
+ * Find identifiers a script CALLS that resolve to nothing in the browser.
+ *
+ * Restricted to names we can name a cause for — exports of `composables/` with
+ * no runtime counterpart. A broader "looks like a hook and is not in scope"
+ * heuristic would fire on legitimate local helpers and app composables, and a
+ * warning people learn to ignore is worse than no warning.
+ *
+ * @param source the script body, after imports have been transformed
+ * @param provided names already in scope (runtime globals, locals, imports)
+ */
+export declare function findUnresolvedIdentifiers(source: string, provided: Iterable<string>): UnresolvedIdentifier[];
+/**
+ * Report unresolved identifiers against a file, once each.
+ *
+ * Returns the diagnostics so callers can assert on them without capturing
+ * console output.
+ */
+export declare function reportUnresolvedIdentifiers(source: string, provided: Iterable<string>, filePath: string): UnresolvedIdentifier[];

package/dist/unresolved-identifiers.js

@@ -0,0 +1,148 @@
+export const SERVER_ONLY_COMPOSABLES = [
+  "broadcast",
+  "calculateDistance",
+  "canNotify",
+  "clearCookies",
+  "clearFetchCache",
+  "clearStorage",
+  "copyToClipboard",
+  "createShareableFile",
+  "defineForm",
+  "getBatteryLevel",
+  "getCookie",
+  "getCurrentPosition",
+  "getStorageKeys",
+  "getStorageSize",
+  "getVoices",
+  "hasBattery",
+  "hasCameraPermission",
+  "hasGeolocationPermission",
+  "hasMicrophonePermission",
+  "hasNotificationPermission",
+  "hasResizeObserver",
+  "hexToHsl",
+  "hexToRgb",
+  "isBroadcastChannelSupported",
+  "isCharging",
+  "isDeviceMotionSupported",
+  "isDeviceOrientationSupported",
+  "isEventSourceSupported",
+  "isEyeDropperSupported",
+  "isInFullscreen",
+  "isMutationObserverSupported",
+  "isPermissionGranted",
+  "isSpeechRecognitionSupported",
+  "isSpeechSynthesisSupported",
+  "isWakeLockSupported",
+  "isWebSocketSupported",
+  "notify",
+  "parseCookies",
+  "pickColor",
+  "prefetch",
+  "removeCookie",
+  "requestMediaPermissions",
+  "requestMotionPermission",
+  "requestNotificationPermission",
+  "requestOrientationPermission",
+  "setCookie",
+  "share",
+  "shareCurrentPage",
+  "shareFiles",
+  "shareText",
+  "shareURL",
+  "shareWithFallback",
+  "speak",
+  "stopSpeaking",
+  "toggleFullscreen",
+  "useAsyncData",
+  "useAttributeObserver",
+  "useAutoLogout",
+  "useAutoWakeLock",
+  "useBattery",
+  "useBreakpoint",
+  "useBroadcastChannel",
+  "useChannel",
+  "useChildListObserver",
+  "useClipboard",
+  "useColorHistory",
+  "useConditionalWakeLock",
+  "useCookies",
+  "useCopySelection",
+  "useDeviceMotion",
+  "useDeviceOrientation",
+  "useElementSize",
+  "useElementTextSelection",
+  "useElementVisibility",
+  "useEventSource",
+  "useEyeDropper",
+  "useFavicon",
+  "useForm",
+  "useFullscreen",
+  "useGeolocation",
+  "useGeolocationWatch",
+  "useHotkey",
+  "useIdle",
+  "useIdleState",
+  "useInfiniteScroll",
+  "useIntersectionObserver",
+  "useIntersectionObserverMultiple",
+  "useIsDesktop",
+  "useIsMobile",
+  "useIsTablet",
+  "useKeyPressed",
+  "useKeySequence",
+  "useKeyboard",
+  "useLastActive",
+  "useLazyLoad",
+  "useMeta",
+  "useMouse",
+  "useMouseInElement",
+  "useMutationObserver",
+  "useNetwork",
+  "useNotification",
+  "useOnline",
+  "useParallax",
+  "usePermission",
+  "usePermissions",
+  "usePointer",
+  "usePost",
+  "useResizeObserver",
+  "useResizeObserverMultiple",
+  "useSSE",
+  "useScroll",
+  "useSelectionPopup",
+  "useShare",
+  "useSpeechRecognition",
+  "useSpeechSynthesis",
+  "useStorage",
+  "useTextObserver",
+  "useTextSelection",
+  "useTitle",
+  "useVisibility",
+  "useWakeLock",
+  "useWindowSize"
+];
+const SERVER_ONLY = new Set(SERVER_ONLY_COMPOSABLES);
+export function findUnresolvedIdentifiers(source, provided) {
+  const inScope = provided instanceof Set ? provided : new Set(provided), found = new Map;
+  for (const match of source.matchAll(/\b([A-Za-z_$][\w$]*)\s*\(/g)) {
+    const name = match[1];
+    if (found.has(name) || inScope.has(name) || !SERVER_ONLY.has(name))
+      continue;
+    if (new RegExp(`(?:const|let|var|function|class)\\s+${name}\\b`).test(source))
+      continue;
+    if (new RegExp(`import\\s[^;]*\\b${name}\\b[^;]*from`).test(source))
+      continue;
+    found.set(name, {
+      name,
+      message: `"${name}" is exported by @stacksjs/stx/composables but is not available in the browser \u2014 ` + `it is a server-only module export, so this call throws ReferenceError at runtime. Import it explicitly (import { ${name} } from '@stacksjs/stx/composables') so the bundler inlines it, or use a runtime equivalent from window.stx.`
+    });
+  }
+  return [...found.values()];
+}
+export function reportUnresolvedIdentifiers(source, provided, filePath) {
+  const unresolved = findUnresolvedIdentifiers(source, provided);
+  for (const item of unresolved)
+    console.warn(`[stx] ${filePath}: ${item.message}`);
+  return unresolved;
+}