stimeo-ui 0.1.0-alpha.1

package/dist/inspector/cli.js

@@ -0,0 +1,663 @@
+import { readFileSync, statSync, readdirSync } from 'fs';
+import { dirname, join, relative, extname } from 'path';
+import process from 'process';
+import { fileURLToPath } from 'url';
+
+// src/inspector/cli.ts
+
+// src/inspector/erb.ts
+function neutralizeErb(source) {
+  return source.replace(/<%[\s\S]*?%>/g, (match) => match.replace(/[^\n]/g, " "));
+}
+
+// src/inspector/extract.ts
+var NAMESPACE_PREFIX = "stimeo--";
+function dasherize(value) {
+  return value.replace(/([A-Z])/g, (_match, char) => `-${char.toLowerCase()}`);
+}
+function controllerIdentifiers(dataControllerValue) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const token of dataControllerValue.split(/\s+/)) {
+    if (token.startsWith(NAMESPACE_PREFIX)) seen.add(token);
+  }
+  return [...seen];
+}
+function parseTargetAttr(attrName) {
+  const match = /^data-(stimeo--[a-z0-9][a-z0-9-]*)-target$/.exec(attrName);
+  return match?.[1] ?? null;
+}
+function parseValueAttr(attrName, knownIdentifiers) {
+  const match = /^data-(stimeo--[a-z0-9-]+)-value$/.exec(attrName);
+  if (!match) return null;
+  const inner = match[1] ?? "";
+  let best = null;
+  for (const id of knownIdentifiers) {
+    if (inner.startsWith(`${id}-`)) {
+      const valueToken = inner.slice(id.length + 1);
+      if (valueToken.length > 0 && (!best || id.length > best.identifier.length)) {
+        best = { identifier: id, valueToken };
+      }
+    }
+  }
+  if (best) return best;
+  const rest = inner.slice(NAMESPACE_PREFIX.length);
+  const dash = rest.indexOf("-");
+  const identifierGuess = dash === -1 ? inner : `${NAMESPACE_PREFIX}${rest.slice(0, dash)}`;
+  const valueGuess = dash === -1 ? "" : rest.slice(dash + 1);
+  return { identifier: null, valueToken: valueGuess || identifierGuess };
+}
+function actionDescriptors(dataActionValue) {
+  const descriptors = [];
+  for (const descriptor of dataActionValue.split(/\s+/)) {
+    const hash = descriptor.indexOf("#");
+    if (hash === -1) continue;
+    let lhs = descriptor.slice(0, hash);
+    const arrow = lhs.indexOf("->");
+    if (arrow !== -1) lhs = lhs.slice(arrow + 2);
+    if (!lhs.startsWith(NAMESPACE_PREFIX)) continue;
+    const method = /^[a-zA-Z_$][\w$]*/.exec(descriptor.slice(hash + 1))?.[0] ?? "";
+    descriptors.push({ identifier: lhs, method });
+  }
+  return descriptors;
+}
+function isStimeoDataAttr(attrName) {
+  return attrName.startsWith(`data-${NAMESPACE_PREFIX}`);
+}
+
+// src/inspector/html_parser.ts
+var VOID_ELEMENTS = /* @__PURE__ */ new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr"
+]);
+var RAW_TEXT_ELEMENTS = /* @__PURE__ */ new Set(["script", "style", "textarea", "title"]);
+var WHITESPACE = /* @__PURE__ */ new Set([" ", "	", "\n", "\r", "\f"]);
+var PositionIndex = class {
+  #lineStarts = [0];
+  constructor(source) {
+    for (let i = 0; i < source.length; i++) {
+      if (source[i] === "\n") this.#lineStarts.push(i + 1);
+    }
+  }
+  at(offset) {
+    let lo = 0;
+    let hi = this.#lineStarts.length - 1;
+    while (lo < hi) {
+      const mid = lo + hi + 1 >> 1;
+      if ((this.#lineStarts[mid] ?? 0) <= offset) lo = mid;
+      else hi = mid - 1;
+    }
+    return { line: lo + 1, column: offset - (this.#lineStarts[lo] ?? 0) + 1 };
+  }
+};
+function parseHtml(source) {
+  const pos = new PositionIndex(source);
+  const len = source.length;
+  const ch = (k) => k >= 0 && k < len ? source[k] : "";
+  const root = {
+    tag: "#root",
+    attrs: [],
+    children: [],
+    parent: null,
+    line: 1,
+    column: 1
+  };
+  const stack = [root];
+  let i = 0;
+  const top = () => stack[stack.length - 1];
+  while (i < len) {
+    if (ch(i) !== "<") {
+      i++;
+      continue;
+    }
+    const next = ch(i + 1);
+    if (source.startsWith("<!--", i)) {
+      const end = source.indexOf("-->", i + 4);
+      i = end === -1 ? len : end + 3;
+      continue;
+    }
+    if (next === "!" || next === "?") {
+      const end = source.indexOf(">", i);
+      i = end === -1 ? len : end + 1;
+      continue;
+    }
+    if (next === "/") {
+      let j2 = i + 2;
+      let name = "";
+      while (j2 < len && ch(j2) !== ">" && !WHITESPACE.has(ch(j2))) {
+        name += ch(j2);
+        j2++;
+      }
+      const end = source.indexOf(">", j2);
+      i = end === -1 ? len : end + 1;
+      closeTag(stack, name.toLowerCase());
+      continue;
+    }
+    if (!/[a-zA-Z]/.test(next)) {
+      i++;
+      continue;
+    }
+    const tagStart = i;
+    let j = i + 1;
+    let tagName = "";
+    while (j < len && !WHITESPACE.has(ch(j)) && ch(j) !== ">" && ch(j) !== "/") {
+      tagName += ch(j);
+      j++;
+    }
+    const lowerTag = tagName.toLowerCase();
+    const attrs = [];
+    let selfClosing = false;
+    while (j < len) {
+      while (j < len && WHITESPACE.has(ch(j))) j++;
+      if (j >= len) break;
+      if (ch(j) === ">") {
+        j++;
+        break;
+      }
+      if (ch(j) === "/") {
+        selfClosing = true;
+        j++;
+        continue;
+      }
+      const nameStart = j;
+      let attrName = "";
+      while (j < len && !WHITESPACE.has(ch(j)) && ch(j) !== "=" && ch(j) !== ">" && ch(j) !== "/") {
+        attrName += ch(j);
+        j++;
+      }
+      let attrValue = "";
+      let k = j;
+      while (k < len && WHITESPACE.has(ch(k))) k++;
+      if (ch(k) === "=") {
+        k++;
+        while (k < len && WHITESPACE.has(ch(k))) k++;
+        const quote = ch(k);
+        if (quote === '"' || quote === "'") {
+          k++;
+          const valStart = k;
+          while (k < len && ch(k) !== quote) k++;
+          attrValue = source.slice(valStart, k);
+          k++;
+        } else {
+          const valStart = k;
+          while (k < len && !WHITESPACE.has(ch(k)) && ch(k) !== ">") k++;
+          attrValue = source.slice(valStart, k);
+        }
+        j = k;
+      }
+      if (attrName.length > 0) {
+        const p = pos.at(nameStart);
+        attrs.push({
+          name: attrName.toLowerCase(),
+          value: attrValue,
+          line: p.line,
+          column: p.column
+        });
+      }
+    }
+    const startPos = pos.at(tagStart);
+    const node = {
+      tag: lowerTag,
+      attrs,
+      children: [],
+      parent: top(),
+      line: startPos.line,
+      column: startPos.column
+    };
+    top().children.push(node);
+    i = j;
+    if (selfClosing || VOID_ELEMENTS.has(lowerTag)) {
+      continue;
+    }
+    if (RAW_TEXT_ELEMENTS.has(lowerTag)) {
+      const closeNeedle = `</${lowerTag}`;
+      const idx = source.toLowerCase().indexOf(closeNeedle, i);
+      if (idx === -1) {
+        i = len;
+      } else {
+        const gt = source.indexOf(">", idx);
+        i = gt === -1 ? len : gt + 1;
+      }
+      continue;
+    }
+    stack.push(node);
+  }
+  return root;
+}
+function closeTag(stack, name) {
+  for (let depth = stack.length - 1; depth >= 1; depth--) {
+    if (stack[depth]?.tag === name) {
+      stack.length = depth;
+      return;
+    }
+  }
+}
+function walk(root, visit) {
+  for (const child of root.children) {
+    visit(child);
+    walk(child, visit);
+  }
+}
+
+// src/inspector/check.ts
+function checkSource(source, manifest) {
+  const diagnostics = [];
+  const tree = parseHtml(neutralizeErb(source));
+  const known = manifest.controllers;
+  const knownIdentifiers = Object.keys(known);
+  const scopes = [];
+  const presence = /* @__PURE__ */ new Map();
+  const targetNodes = /* @__PURE__ */ new Map();
+  const recordPresence = (owner, identifier, target) => {
+    let byId = presence.get(owner);
+    if (!byId) {
+      byId = /* @__PURE__ */ new Map();
+      presence.set(owner, byId);
+    }
+    let set = byId.get(identifier);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      byId.set(identifier, set);
+    }
+    set.add(target);
+  };
+  const recordTargetNode = (owner, identifier, target, el) => {
+    let byId = targetNodes.get(owner);
+    if (!byId) {
+      byId = /* @__PURE__ */ new Map();
+      targetNodes.set(owner, byId);
+    }
+    let byName = byId.get(identifier);
+    if (!byName) {
+      byName = /* @__PURE__ */ new Map();
+      byId.set(identifier, byName);
+    }
+    const found = byName.get(target);
+    if (found) found.push(el);
+    else byName.set(target, [el]);
+  };
+  walk(tree, (node) => {
+    for (const attr of node.attrs) {
+      if (attr.name === "data-controller") {
+        for (const identifier of controllerIdentifiers(attr.value)) {
+          if (identifier in known) {
+            scopes.push({ node, identifier });
+          } else {
+            push(
+              diagnostics,
+              "unknown-controller",
+              "error",
+              `Unknown Stimeo controller "${identifier}".`,
+              attr,
+              didYouMean(identifier, knownIdentifiers)
+            );
+          }
+        }
+        continue;
+      }
+      const targetIdentifier = parseTargetAttr(attr.name);
+      if (targetIdentifier) {
+        const controller = known[targetIdentifier];
+        if (!controller) {
+          push(
+            diagnostics,
+            "unknown-controller",
+            "error",
+            `Target attribute "${attr.name}" references unknown Stimeo controller "${targetIdentifier}".`,
+            attr,
+            didYouMean(targetIdentifier, knownIdentifiers)
+          );
+          continue;
+        }
+        const targetName = attr.value.trim();
+        if (targetName.length > 0 && !controller.targets.includes(targetName)) {
+          push(
+            diagnostics,
+            "unknown-target",
+            "error",
+            `Unknown target "${targetName}" for "${targetIdentifier}". Known targets: ${list(controller.targets)}.`,
+            attr,
+            didYouMean(targetName, controller.targets)
+          );
+        }
+        const owner = findOwner(node, targetIdentifier);
+        if (owner) {
+          if (targetName.length > 0) {
+            recordPresence(owner, targetIdentifier, targetName);
+            recordTargetNode(owner, targetIdentifier, targetName, node);
+          }
+        } else {
+          push(
+            diagnostics,
+            "orphan-target",
+            "error",
+            `Target "${attr.name}" has no enclosing controller "${targetIdentifier}".`,
+            attr
+          );
+        }
+        continue;
+      }
+      if (isStimeoDataAttr(attr.name) && attr.name.endsWith("-value")) {
+        const parsed = parseValueAttr(attr.name, knownIdentifiers);
+        if (parsed) {
+          if (parsed.identifier === null) {
+            push(
+              diagnostics,
+              "unknown-controller",
+              "error",
+              `Value attribute "${attr.name}" references unknown Stimeo controller.`,
+              attr
+            );
+          } else {
+            const controller = known[parsed.identifier];
+            const valid = controller?.values.some((v) => dasherize(v) === parsed.valueToken) ?? false;
+            if (!valid) {
+              push(
+                diagnostics,
+                "unknown-value",
+                "error",
+                `Unknown value "${parsed.valueToken}" for "${parsed.identifier}". Known values: ${list((controller?.values ?? []).map(dasherize))}.`,
+                attr,
+                didYouMean(parsed.valueToken, (controller?.values ?? []).map(dasherize))
+              );
+            }
+          }
+          continue;
+        }
+      }
+      if (attr.name === "data-action") {
+        for (const { identifier, method } of actionDescriptors(attr.value)) {
+          const controller = known[identifier];
+          if (!controller) {
+            push(
+              diagnostics,
+              "unknown-action-controller",
+              "error",
+              `Action references unknown Stimeo controller "${identifier}".`,
+              attr,
+              didYouMean(identifier, knownIdentifiers)
+            );
+          } else if (method.length > 0 && !controller.actions.includes(method)) {
+            push(
+              diagnostics,
+              "unknown-action-method",
+              "error",
+              `Unknown action "${method}" for "${identifier}". Known actions: ${list(controller.actions)}.`,
+              attr,
+              didYouMean(method, controller.actions)
+            );
+          }
+        }
+      }
+    }
+  });
+  for (const { node, identifier } of scopes) {
+    const controller = known[identifier];
+    if (!controller) continue;
+    const present = presence.get(node)?.get(identifier) ?? /* @__PURE__ */ new Set();
+    for (const required of controller.requiredTargets) {
+      if (!present.has(required)) {
+        push(
+          diagnostics,
+          "missing-required-target",
+          "error",
+          `"${identifier}" is missing required target "${required}".`,
+          node
+        );
+      }
+    }
+  }
+  for (const { node, identifier } of scopes) {
+    const controller = known[identifier];
+    if (!controller) continue;
+    for (const req of controller.a11y) {
+      const elements = req.target === "" ? [node] : targetNodes.get(node)?.get(identifier)?.get(req.target) ?? [];
+      for (const el of elements) {
+        checkA11y(diagnostics, el, identifier, req);
+      }
+    }
+  }
+  diagnostics.sort((a, b) => a.line - b.line || a.column - b.column);
+  return diagnostics;
+}
+function checkA11y(out, el, identifier, req) {
+  const present = req.attrs.map((name) => el.attrs.find((a) => a.name === name)).filter((a) => a !== void 0);
+  const where = req.target === "" ? "scope element" : `"${req.target}" target`;
+  if (present.length === 0) {
+    push(
+      out,
+      "missing-aria",
+      "error",
+      `"${identifier}" requires ${describeAttrs(req.attrs)} on its ${where}.`,
+      el,
+      req.suggestion
+    );
+    return;
+  }
+  if (!req.values) return;
+  for (const attr of present) {
+    if (!req.values.includes(attr.value.trim())) {
+      push(
+        out,
+        "invalid-aria-value",
+        "error",
+        `${attr.name}="${attr.value}" is not valid on the ${where} of "${identifier}". Expected ${list(req.values)}.`,
+        attr,
+        `Set ${attr.name} to ${list(req.values)}.`
+      );
+    }
+  }
+}
+function findOwner(node, identifier) {
+  let current = node;
+  while (current && current.tag !== "#root") {
+    const dataController = current.attrs.find((a) => a.name === "data-controller");
+    if (dataController && controllerIdentifiers(dataController.value).includes(identifier)) {
+      return current;
+    }
+    current = current.parent;
+  }
+  return null;
+}
+function push(out, code, severity, message, at, suggestion) {
+  out.push({ code, severity, message, line: at.line, column: at.column, suggestion });
+}
+function list(names) {
+  return names.length > 0 ? names.map((n) => `"${n}"`).join(", ") : "(none)";
+}
+function describeAttrs(attrs) {
+  return attrs.length === 1 ? attrs[0] : attrs.join(" or ");
+}
+function didYouMean(name, candidates) {
+  if (name.length === 0) return void 0;
+  let best;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const candidate of candidates) {
+    const distance = levenshtein(name, candidate);
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = candidate;
+    }
+  }
+  const threshold = Math.min(3, Math.floor(name.length / 2) + 1);
+  return best !== void 0 && bestDistance <= threshold ? `Did you mean "${best}"?` : void 0;
+}
+function levenshtein(a, b) {
+  const rows = a.length;
+  const cols = b.length;
+  if (rows === 0) return cols;
+  if (cols === 0) return rows;
+  let prev = Array.from({ length: cols + 1 }, (_, j) => j);
+  for (let i = 1; i <= rows; i++) {
+    const curr = [i];
+    for (let j = 1; j <= cols; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(
+        curr[j - 1] + 1,
+        prev[j] + 1,
+        prev[j - 1] + cost
+      );
+    }
+    prev = curr;
+  }
+  return prev[cols];
+}
+
+// src/inspector/cli.ts
+var FILE_EXTENSIONS = /* @__PURE__ */ new Set([".erb", ".html", ".htm"]);
+function loadManifest() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const manifestPath = join(here, "manifest.json");
+  const raw = readFileSync(manifestPath, "utf8");
+  return JSON.parse(raw);
+}
+function collectFiles(target, out) {
+  const stat = statSync(target);
+  if (stat.isDirectory()) {
+    for (const entry of readdirSync(target)) {
+      collectFiles(join(target, entry), out);
+    }
+    return;
+  }
+  if (FILE_EXTENSIONS.has(extname(target))) out.push(target);
+}
+function checkFile(file, manifest) {
+  const source = readFileSync(file, "utf8");
+  return { file, diagnostics: checkSource(source, manifest) };
+}
+function formatDiagnostic(d) {
+  const where = `${d.line}:${d.column}`.padEnd(7);
+  const head = `  ${where} ${d.severity.padEnd(7)} ${d.message} [${d.code}]`;
+  return d.suggestion ? `${head}
+          \u2192 ${d.suggestion}` : head;
+}
+function buildCheckReport(reports, checkedFiles) {
+  let errorCount = 0;
+  let warningCount = 0;
+  const files = [];
+  for (const report of reports) {
+    if (report.diagnostics.length === 0) continue;
+    files.push(report);
+    for (const d of report.diagnostics) {
+      if (d.severity === "error") errorCount++;
+      else warningCount++;
+    }
+  }
+  return { ok: errorCount === 0, checkedFiles, errorCount, warningCount, files };
+}
+function catalogSummary(manifest) {
+  const ids = Object.keys(manifest.controllers).sort();
+  const lines = [
+    `Stimeo UI catalog \u2014 ${ids.length} controller(s) (schema v${manifest.schemaVersion}, package ${manifest.packageVersion})`,
+    ""
+  ];
+  for (const id of ids) {
+    const c = manifest.controllers[id];
+    if (!c) continue;
+    lines.push(id);
+    if (c.targets.length > 0) lines.push(`  targets:  ${c.targets.join(", ")}`);
+    if (c.values.length > 0) lines.push(`  values:   ${c.values.join(", ")}`);
+    if (c.actions.length > 0) lines.push(`  actions:  ${c.actions.join(", ")}`);
+    if (c.events.length > 0) lines.push(`  events:   ${c.events.join(", ")}`);
+  }
+  return lines;
+}
+var USAGE = `stimeo \u2014 static checker and catalog for Stimeo UI markup
+
+Usage:
+  stimeo check [--json] <path...>   Check HTML/ERB files (or directories) for
+                                     unknown or misused stimeo--* controllers,
+                                     targets, values and action methods.
+  stimeo catalog [--json]           Print the official controller catalog
+                                     (identifiers, targets, values, actions,
+                                     events).
+
+--json makes either command emit machine-readable JSON (for tooling / MCP):
+check prints a CheckReport, catalog prints the raw manifest.
+Exit code is 1 when any error is found.`;
+function runCli(argv, write = console.log, load = loadManifest) {
+  const [command, ...rest] = argv;
+  if (command === void 0 || command === "--help" || command === "-h") {
+    write(USAGE);
+    return command === void 0 ? 2 : 0;
+  }
+  const json = rest.includes("--json");
+  if (command === "catalog") {
+    const manifest2 = load();
+    if (json) {
+      write(JSON.stringify(manifest2, null, 2));
+    } else {
+      for (const line of catalogSummary(manifest2)) write(line);
+    }
+    return 0;
+  }
+  if (command !== "check") {
+    write(`Unknown command "${command}".
+
+${USAGE}`);
+    return 2;
+  }
+  const paths = rest.filter((arg) => !arg.startsWith("-"));
+  if (paths.length === 0) {
+    write(`No paths given.
+
+${USAGE}`);
+    return 2;
+  }
+  const files = [];
+  for (const path of paths) {
+    try {
+      collectFiles(path, files);
+    } catch (err) {
+      const code = err.code;
+      const reason = code === "ENOENT" ? "no such file or directory" : code === "EACCES" ? "permission denied" : err.message ?? "cannot access path";
+      write(`Cannot read path "${path}": ${reason}.
+
+${USAGE}`);
+      return 2;
+    }
+  }
+  const manifest = load();
+  const cwd = process.cwd();
+  const reports = [];
+  for (const file of files.sort()) {
+    reports.push({
+      file: relative(cwd, file) || file,
+      diagnostics: checkFile(file, manifest).diagnostics
+    });
+  }
+  const summary = buildCheckReport(reports, files.length);
+  if (json) {
+    write(JSON.stringify(summary, null, 2));
+    return summary.errorCount > 0 ? 1 : 0;
+  }
+  for (const report of summary.files) {
+    write(report.file);
+    for (const d of report.diagnostics) write(formatDiagnostic(d));
+    write("");
+  }
+  const total = summary.errorCount + summary.warningCount;
+  if (total === 0) {
+    write(`\u2713 Checked ${summary.checkedFiles} file(s); no problems found.`);
+    return 0;
+  }
+  write(
+    `\u2716 ${total} problem(s) (${summary.errorCount} error(s), ${summary.warningCount} warning(s)).`
+  );
+  return summary.errorCount > 0 ? 1 : 0;
+}
+
+export { buildCheckReport, catalogSummary, runCli };
+//# sourceMappingURL=cli.js.map
+//# sourceMappingURL=cli.js.map