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

package/dist/docs.js

@@ -0,0 +1,567 @@
+import fs from "node:fs";
+import path from "node:path";
+import { config } from "./config.js";
+import { fileExists } from "./utils.js";
+export async function extractComponentProps(componentPath) {
+  try {
+    const scriptMatch = (await Bun.file(componentPath).text()).match(/<script\b[^>]*>([\s\S]*?)<\/script>/i);
+    if (!scriptMatch)
+      return [];
+    const scriptContent = scriptMatch[1], props = [], propRegex = /\/\*\*\s*([\s\S]*?)\s*\*\/\s*(?:(?:const|let|var)\s*)?(?:([\w$]+)\s*=|module\.exports\.([\w$]+)\s*=|\s*([\w$]+)\s*:)/g;
+    let match;
+    while ((match = propRegex.exec(scriptContent)) !== null) {
+      const commentBlock = match[1], propName = match[2] || match[3] || match[4];
+      if (!propName)
+        continue;
+      const propDoc = { name: propName }, typeMatch = commentBlock.match(/@type\s+\{([^}]+)\}/i);
+      if (typeMatch)
+        propDoc.type = typeMatch[1].trim();
+      if (commentBlock.match(/@required/i))
+        propDoc.required = !0;
+      const defaultMatch = commentBlock.match(/@default\s+(.+?)(?:\s+|$)/i);
+      if (defaultMatch)
+        propDoc.default = defaultMatch[1].trim();
+      const descLines = commentBlock.split(`
+`).map((line) => line.trim().replace(/^\*\s*/, "")).filter((line) => !line.startsWith("@") && line.length > 0);
+      propDoc.description = descLines.join(" ").trim();
+      props.push(propDoc);
+    }
+    if (props.length === 0) {
+      const exportsMatch = scriptContent.match(/module\.exports\s*=\s*\{([^}]+)\}/i);
+      if (exportsMatch) {
+        const propLines = exportsMatch[1].split(",").map((line) => line.trim()).filter(Boolean);
+        for (const propLine of propLines) {
+          const [propName] = propLine.split(":").map((part) => part.trim());
+          if (propName)
+            props.push({ name: propName });
+        }
+      }
+    }
+    return props;
+  } catch (error) {
+    console.error(`Error extracting props from ${componentPath}:`, error);
+    return [];
+  }
+}
+export async function extractComponentDescription(componentPath) {
+  try {
+    const content = await Bun.file(componentPath).text(), commentMatch = content.match(/^\s*<!--\s*([\s\S]*?)\s*-->/) || content.match(/^\s*\/\*\*\s*([\s\S]*?)\s*\*\//);
+    if (commentMatch)
+      return commentMatch[1].split(`
+`).map((line) => line.trim().replace(/^\*\s*/, "")).join(" ").trim();
+    return "";
+  } catch {
+    return "";
+  }
+}
+export async function generateComponentDoc(componentPath, isWebComponent = !1, webComponentTag) {
+  const name = path.basename(componentPath, ".stx"), props = await extractComponentProps(componentPath), description = await extractComponentDescription(componentPath);
+  let example = "";
+  if (isWebComponent && webComponentTag)
+    example = `<${webComponentTag}></${webComponentTag}>`;
+  else {
+    const propsExample = props.map((prop) => {
+      if (prop.type === "boolean")
+        return `:${prop.name}="true"`;
+      return `${prop.name}="value"`;
+    }).join(`
+  `);
+    example = `<${name}
+  ${propsExample}
+/>`;
+  }
+  return {
+    name,
+    path: componentPath,
+    description,
+    props,
+    example,
+    isWebComponent,
+    tag: webComponentTag
+  };
+}
+export async function findComponentFiles(componentsDir) {
+  try {
+    if (!await fileExists(componentsDir)) {
+      console.warn(`Components directory does not exist: ${componentsDir}`);
+      return [];
+    }
+    const entries = await fs.promises.readdir(componentsDir, { withFileTypes: !0 }), componentFiles = [];
+    for (const entry of entries) {
+      const entryPath = path.join(componentsDir, entry.name);
+      if (entry.isDirectory()) {
+        const subComponents = await findComponentFiles(entryPath);
+        componentFiles.push(...subComponents);
+      } else if (entry.isFile() && entry.name.endsWith(".stx"))
+        componentFiles.push(entryPath);
+    }
+    return componentFiles;
+  } catch (error) {
+    console.error(`Error finding component files in ${componentsDir}:`, error);
+    return [];
+  }
+}
+export async function generateComponentsDocs(componentsDir, webComponentsConfig) {
+  try {
+    if (!await fileExists(componentsDir))
+      return [];
+    const componentFiles = await findComponentFiles(componentsDir), componentDocs = [], webComponentsMap = new Map;
+    if (webComponentsConfig?.components?.length)
+      for (const component of webComponentsConfig.components)
+        webComponentsMap.set(component.file, component);
+    for (const componentFile of componentFiles) {
+      const webComponent = webComponentsMap.get(componentFile), isWebComponent = !!webComponent, webComponentTag = webComponent?.tag, doc = await generateComponentDoc(componentFile, isWebComponent, webComponentTag);
+      componentDocs.push(doc);
+    }
+    return componentDocs;
+  } catch (error) {
+    console.error("Error generating component docs:", error);
+    return [];
+  }
+}
+export async function generateTemplatesDocs(templatesDir) {
+  try {
+    if (!await fileExists(templatesDir))
+      return [];
+    const entries = await fs.promises.readdir(templatesDir, { withFileTypes: !0 }), templateDocs = [];
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".stx"))
+        continue;
+      const templatePath = path.join(templatesDir, entry.name), content = await Bun.file(templatePath).text(), name = path.basename(templatePath, ".stx"), descriptionMatch = content.match(/^\s*<!--\s*([\s\S]*?)\s*-->/) || content.match(/^\s*\/\*\*\s*([\s\S]*?)\s*\*\//), description = descriptionMatch ? descriptionMatch[1].split(`
+`).map((line) => line.trim().replace(/^\*\s*/, "")).join(" ").trim() : "", componentRegex = /@component\(\s*['"]([^'"]+)['"]/g, componentTags = /<([A-Z][a-zA-Z0-9]*|[a-z]+-[a-z0-9-]+)(?:\s[^>]*)?\/?>|\{\{\s*slot\s*\}\}/g, components = new Set;
+      let match;
+      while ((match = componentRegex.exec(content)) !== null)
+        components.add(match[1]);
+      while ((match = componentTags.exec(content)) !== null)
+        if (match[1] && match[1] !== "slot")
+          components.add(match[1]);
+      const directiveRegex = /@([a-z]+)(?:\s*\(|\s+|$)/g, directives = new Set;
+      while ((match = directiveRegex.exec(content)) !== null)
+        directives.add(match[1]);
+      templateDocs.push({
+        name,
+        path: templatePath,
+        description,
+        components: [...components],
+        directives: [...directives]
+      });
+    }
+    return templateDocs;
+  } catch (error) {
+    console.error("Error generating template docs:", error);
+    return [];
+  }
+}
+export async function generateDirectivesDocs(customDirectives = []) {
+  try {
+    const directiveDocs = [
+      {
+        name: "if",
+        description: "Conditionally render content based on a condition",
+        hasEndTag: !0,
+        example: `@if(user.isLoggedIn)
+  <p>Welcome, {{ user.name }}!</p>
+@endif`
+      },
+      {
+        name: "else",
+        description: "Provides an alternative if a condition is not met",
+        hasEndTag: !1,
+        example: `@if(user.isLoggedIn)
+  <p>Welcome back!</p>
+@else
+  <p>Please log in</p>
+@endif`
+      },
+      {
+        name: "elseif",
+        description: "Provides an alternative condition",
+        hasEndTag: !1,
+        example: `@if(score > 90)
+  <p>A</p>
+@elseif(score > 80)
+  <p>B</p>
+@elseif(score > 70)
+  <p>C</p>
+@endif`
+      },
+      {
+        name: "unless",
+        description: "Conditionally render content if a condition is false",
+        hasEndTag: !0,
+        example: `@unless(user.isLoggedIn)
+  <p>Please log in</p>
+@endunless`
+      },
+      {
+        name: "for",
+        description: "Loop through an array or object",
+        hasEndTag: !0,
+        example: `@for(item of items)
+  <li>{{ item.name }}</li>
+@endfor`
+      },
+      {
+        name: "while",
+        description: "Loop while a condition is true",
+        hasEndTag: !0,
+        example: `@while(page < totalPages)
+  <p>Page {{ page }}</p>
+@endwhile`
+      },
+      {
+        name: "component",
+        description: "Include a component in the template",
+        hasEndTag: !1,
+        example: '@component("alert", { type: "warning", title: "Warning", message: "This is a warning" })'
+      },
+      {
+        name: "include",
+        description: "Include a partial template",
+        hasEndTag: !1,
+        example: '@include("partials/header")'
+      },
+      {
+        name: "raw",
+        description: "Display content without processing expressions",
+        hasEndTag: !0,
+        example: `@raw
+  {{ This will be displayed as-is }}
+@endraw`
+      },
+      {
+        name: "translate",
+        description: "Translate a string using the i18n system",
+        hasEndTag: !1,
+        example: '@translate("welcome.message", { name: user.name })'
+      },
+      {
+        name: "t",
+        description: "Short alias for translate directive",
+        hasEndTag: !1,
+        example: '@t("welcome.message", { name: user.name })'
+      }
+    ];
+    for (const directive of customDirectives)
+      directiveDocs.push({
+        name: directive.name,
+        description: directive.description || "",
+        hasEndTag: directive.hasEndTag || !1,
+        example: ""
+      });
+    return directiveDocs;
+  } catch (error) {
+    console.error("Error generating directive docs:", error);
+    return [];
+  }
+}
+export function formatDocsAsMarkdown(componentDocs = [], templateDocs = [], directiveDocs = [], extraContent) {
+  let markdown = `# stx Documentation
+
+`;
+  if (extraContent)
+    markdown += `${extraContent}
+
+`;
+  if (componentDocs.length > 0) {
+    markdown += `## Components
+
+`;
+    for (const doc of componentDocs) {
+      markdown += `### ${doc.name}
+
+`;
+      if (doc.description)
+        markdown += `${doc.description}
+
+`;
+      if (doc.isWebComponent)
+        markdown += `**Web Component Tag:** \`${doc.tag}\`
+
+`;
+      if (doc.props.length > 0) {
+        markdown += `#### Properties
+
+`;
+        markdown += `| Name | Type | Required | Default | Description |
+`;
+        markdown += `| ---- | ---- | -------- | ------- | ----------- |
+`;
+        for (const prop of doc.props)
+          markdown += `| ${prop.name} | ${prop.type || "any"} | ${prop.required ? "Yes" : "No"} | ${prop.default || "-"} | ${prop.description || "-"} |
+`;
+        markdown += `
+`;
+      }
+      if (doc.example) {
+        markdown += `#### Example
+
+`;
+        markdown += "```html\n";
+        markdown += doc.example;
+        markdown += "\n```\n\n";
+      }
+    }
+  }
+  if (templateDocs.length > 0) {
+    markdown += `## Templates
+
+`;
+    for (const doc of templateDocs) {
+      markdown += `### ${doc.name}
+
+`;
+      if (doc.description)
+        markdown += `${doc.description}
+
+`;
+      if (doc.components && doc.components.length > 0)
+        markdown += `**Components Used:** ${doc.components.join(", ")}
+
+`;
+      if (doc.directives && doc.directives.length > 0)
+        markdown += `**Directives Used:** ${doc.directives.join(", ")}
+
+`;
+    }
+  }
+  if (directiveDocs.length > 0) {
+    markdown += `## Directives
+
+`;
+    markdown += `| Directive | Description | Has End Tag |
+`;
+    markdown += `| --------- | ----------- | ----------- |
+`;
+    for (const doc of directiveDocs)
+      markdown += `| @${doc.name} | ${doc.description || "-"} | ${doc.hasEndTag ? "Yes" : "No"} |
+`;
+    markdown += `
+`;
+    for (const doc of directiveDocs)
+      if (doc.example) {
+        markdown += `### @${doc.name}
+
+`;
+        markdown += `${doc.description || ""}
+
+`;
+        markdown += `#### Example
+
+`;
+        markdown += "```html\n";
+        markdown += doc.example;
+        markdown += "\n```\n\n";
+      }
+  }
+  return markdown;
+}
+export function formatDocsAsHtml(componentDocs = [], templateDocs = [], directiveDocs = [], extraContent) {
+  let html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>stx Documentation</title>
+  <style>
+    body {
+      font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
+      line-height: 1.6;
+      color: #333;
+      max-width: 1200px;
+      margin: 0 auto;
+      padding: 2rem;
+    }
+    h1, h2, h3, h4 { margin-top: 2rem; }
+    table {
+      border-collapse: collapse;
+      width: 100%;
+      margin: 1rem 0;
+    }
+    th, td {
+      text-align: left;
+      padding: 0.5rem;
+      border-bottom: 1px solid #ddd;
+    }
+    th { border-bottom: 2px solid #ddd; }
+    pre {
+      background: #f5f5f5;
+      padding: 1rem;
+      border-radius: 4px;
+      overflow-x: auto;
+    }
+    code {
+      background: #f5f5f5;
+      padding: 0.2rem 0.4rem;
+      border-radius: 4px;
+      font-size: 0.9em;
+    }
+  </style>
+</head>
+<body>
+  <h1>stx Documentation</h1>
+  `;
+  if (extraContent)
+    html += `<div>${extraContent}</div>`;
+  if (componentDocs.length > 0) {
+    html += "<h2>Components</h2>";
+    for (const doc of componentDocs) {
+      html += `<h3>${doc.name}</h3>`;
+      if (doc.description)
+        html += `<p>${doc.description}</p>`;
+      if (doc.isWebComponent)
+        html += `<p><strong>Web Component Tag:</strong> <code>${doc.tag}</code></p>`;
+      if (doc.props.length > 0) {
+        html += "<h4>Properties</h4>";
+        html += `<table>
+          <thead>
+            <tr>
+              <th>Name</th>
+              <th>Type</th>
+              <th>Required</th>
+              <th>Default</th>
+              <th>Description</th>
+            </tr>
+          </thead>
+          <tbody>`;
+        for (const prop of doc.props)
+          html += `<tr>
+            <td>${prop.name}</td>
+            <td>${prop.type || "any"}</td>
+            <td>${prop.required ? "Yes" : "No"}</td>
+            <td>${prop.default || "-"}</td>
+            <td>${prop.description || "-"}</td>
+          </tr>`;
+        html += "</tbody></table>";
+      }
+      if (doc.example) {
+        html += "<h4>Example</h4>";
+        html += `<pre><code>${doc.example.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;")}</code></pre>`;
+      }
+    }
+  }
+  if (templateDocs.length > 0) {
+    html += "<h2>Templates</h2>";
+    for (const doc of templateDocs) {
+      html += `<h3>${doc.name}</h3>`;
+      if (doc.description)
+        html += `<p>${doc.description}</p>`;
+      if (doc.components && doc.components.length > 0)
+        html += `<p><strong>Components Used:</strong> ${doc.components.join(", ")}</p>`;
+      if (doc.directives && doc.directives.length > 0)
+        html += `<p><strong>Directives Used:</strong> ${doc.directives.join(", ")}</p>`;
+    }
+  }
+  if (directiveDocs.length > 0) {
+    html += "<h2>Directives</h2>";
+    html += `<table>
+      <thead>
+        <tr>
+          <th>Directive</th>
+          <th>Description</th>
+          <th>Has End Tag</th>
+        </tr>
+      </thead>
+      <tbody>`;
+    for (const doc of directiveDocs)
+      html += `<tr>
+        <td>@${doc.name}</td>
+        <td>${doc.description || "-"}</td>
+        <td>${doc.hasEndTag ? "Yes" : "No"}</td>
+      </tr>`;
+    html += "</tbody></table>";
+    for (const doc of directiveDocs)
+      if (doc.example) {
+        html += `<h3>@${doc.name}</h3>`;
+        html += `<p>${doc.description || ""}</p>`;
+        html += "<h4>Example</h4>";
+        html += `<pre><code>${doc.example.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;")}</code></pre>`;
+      }
+  }
+  html += "</body></html>";
+  return html;
+}
+export function formatDocsAsJson(componentDocs = [], templateDocs = [], directiveDocs = [], extraContent) {
+  return JSON.stringify({
+    components: componentDocs,
+    templates: templateDocs,
+    directives: directiveDocs,
+    extraContent: extraContent || ""
+  }, null, 2);
+}
+export async function generateDocs(options) {
+  try {
+    const { componentsDir, templatesDir, webComponentsConfig, customDirectives, config: docConfig } = options;
+    if (!docConfig.enabled)
+      return !1;
+    const outputDir = docConfig.outputDir || "docs";
+    await fs.promises.mkdir(outputDir, { recursive: !0 });
+    console.log("Generating documentation...");
+    if (componentsDir)
+      console.log(`Components directory: ${componentsDir}`);
+    if (templatesDir)
+      console.log(`Templates directory: ${templatesDir}`);
+    console.log(`Output directory: ${outputDir}`);
+    let componentDocs = [];
+    if (docConfig.components !== !1 && componentsDir) {
+      console.log("Generating component documentation...");
+      componentDocs = await generateComponentsDocs(componentsDir, webComponentsConfig);
+      console.log(`Found ${componentDocs.length} components`);
+    }
+    let templateDocs = [];
+    if (docConfig.templates !== !1 && templatesDir) {
+      console.log("Generating template documentation...");
+      templateDocs = await generateTemplatesDocs(templatesDir);
+      console.log(`Found ${templateDocs.length} templates`);
+    }
+    let directiveDocs = [];
+    if (docConfig.directives !== !1) {
+      console.log("Generating directive documentation...");
+      directiveDocs = await generateDirectivesDocs(customDirectives);
+      console.log(`Found ${directiveDocs.length} directives`);
+    }
+    const format = docConfig.format || "markdown", extraContent = docConfig.extraContent;
+    let docContent = "", extension = "";
+    switch (format) {
+      case "markdown":
+        docContent = formatDocsAsMarkdown(componentDocs, templateDocs, directiveDocs, extraContent);
+        extension = "md";
+        break;
+      case "html":
+        docContent = formatDocsAsHtml(componentDocs, templateDocs, directiveDocs, extraContent);
+        extension = "html";
+        break;
+      case "json":
+        docContent = formatDocsAsJson(componentDocs, templateDocs, directiveDocs, extraContent);
+        extension = "json";
+        break;
+      default:
+        throw Error(`Unsupported documentation format: ${format}`);
+    }
+    const outputPath = path.join(outputDir, `stx-docs.${extension}`);
+    await Bun.write(outputPath, docContent);
+    console.log(`Documentation generated: ${outputPath}`);
+    return !0;
+  } catch (error) {
+    console.error("Error generating documentation:", error);
+    return !1;
+  }
+}
+export async function docsCommand(options) {
+  const docsConfig = {
+    enabled: !0,
+    outputDir: options.output || "docs",
+    format: options.format || "markdown",
+    components: options.components !== !1,
+    templates: options.templates !== !1,
+    directives: options.directives !== !1,
+    extraContent: options.extraContent
+  }, componentsDir = options.componentsDir || config.componentsDir, templatesDir = options.templatesDir || ".";
+  return generateDocs({
+    componentsDir,
+    templatesDir,
+    webComponentsConfig: config.webComponents,
+    customDirectives: config.customDirectives,
+    config: docsConfig
+  });
+}

package/dist/doctor.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Walk up from `cwd` looking for a `pantry/@stacksjs/<name>` directory.
+ * Returns its absolute path, or null when there's no pantry (a standard install
+ * or running inside the stx repo itself).
+ */
+export declare function findPantryPackage(cwd: string, name?: string): string | null;
+/**
+ * Run the resolution/staleness diagnostics. Pure-ish: only reads the filesystem
+ * and (optionally) generates the runtime — never mutates anything.
+ */
+export declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;
+/** Render a {@link DoctorReport} as an aligned, icon-prefixed terminal block. */
+export declare function formatDoctorReport(report: DoctorReport): string;
+export declare interface DoctorCheck {
+  name: string
+  status: CheckStatus
+  detail: string
+  fix?: string
+}
+export declare interface DoctorReport {
+  checks: DoctorCheck[]
+  ok: boolean
+}
+export declare interface DoctorOptions {
+  cwd?: string
+  generateRuntime?: () => string
+  resolve?: (specifier: string, from: string) => string | null
+}
+export type CheckStatus = 'ok' | 'warn' | 'error' | 'info';