create-thally-docs 0.10.69 → 0.10.70

package/dist/{chunk-4JW7VBXN.js → chunk-UL4XFPLQ.js}

@@ -140,12 +140,40 @@ import { parse as parseYaml3 } from "yaml";
 var METHODS = ["get", "post", "put", "patch", "delete", "options", "head", "trace"];
 var isObj = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
 var flagged = (value) => value === true || value === "true";
-function parseDocOperation(raw) {
+function unquote(value) {
+  const trimmed = value.trim();
+  const quote = trimmed[0];
+  return (quote === '"' || quote === "'") && trimmed.length >= 2 && trimmed.endsWith(quote) ? trimmed.slice(1, -1).trim() : trimmed;
+}
+function parseDocReference(raw) {
   if (typeof raw !== "string") return null;
-  const parts = raw.trim().split(/\s+/);
-  if (parts.length < 2) return null;
-  const path = parts.slice(1).join(" ");
-  return path.startsWith("/") ? { method: parts[0].toUpperCase(), path } : null;
+  const trimmed = unquote(raw);
+  if (!trimmed) return null;
+  const webhook = /^(?:(.*?\S)\s+)?webhook\s+([^\s/]\S*)$/i.exec(trimmed);
+  if (webhook) {
+    const specRef2 = webhook[1] ? unquote(webhook[1]) : void 0;
+    return { ...specRef2 ? { specRef: specRef2 } : {}, method: "WEBHOOK", path: webhook[2], webhook: true };
+  }
+  const operation = /^(?:(.*?\S)\s+)?([A-Za-z]+)\s+(\/.*)$/.exec(trimmed);
+  if (!operation) return null;
+  const specRef = operation[1] ? unquote(operation[1]) : void 0;
+  return { ...specRef ? { specRef } : {}, method: operation[2].toUpperCase(), path: operation[3].trim().split(/\s+/).join(" ") };
+}
+var canonicalRef = (value) => value.trim().replace(/\\/g, "/").replace(/^(?:\.\/)+/, "").replace(/^\/+/, "").replace(/^[a-z][a-z0-9+.-]*:\/\/[^/?#]*/i, (origin) => origin.toLowerCase());
+var baseName = (value) => canonicalRef(value).split(/[?#]/, 1)[0].split("/").filter(Boolean).pop() ?? "";
+function pageState(ref, specs) {
+  const judge = (spec) => spec.document === void 0 ? "unknown" : ref.webhook ? webhookState(spec.document, ref.path, spec.overrides) : operationState(spec.document, ref.method, ref.path, spec.overrides);
+  if (ref.specRef) {
+    const wanted = canonicalRef(ref.specRef);
+    if (!wanted) return "unknown";
+    const wantedBase = baseName(ref.specRef);
+    const spec = specs.find((entry) => canonicalRef(entry.source) === wanted) ?? specs.find((entry) => canonicalRef(entry.source).toLowerCase() === wanted.toLowerCase()) ?? (wantedBase ? specs.find((entry) => baseName(entry.source) === wantedBase) : void 0) ?? (wantedBase ? specs.find((entry) => baseName(entry.source).toLowerCase() === wantedBase.toLowerCase()) : void 0);
+    return spec ? judge(spec) : "unknown";
+  }
+  const states = specs.map(judge);
+  if (states.includes("published")) return "published";
+  if (specs.some((spec) => spec.document === void 0)) return "unknown";
+  return states.find((state) => state === "hidden" || state === "excluded") ?? "unknown";
 }
 function resolveLocalRef(document, ref) {
   if (ref !== "#" && !ref.startsWith("#/")) return void 0;
@@ -161,11 +189,7 @@ function resolveLocalRef(document, ref) {
   }
   return node;
 }
-function operationState(document, method, path, overrides) {
-  const verb = method.toLowerCase();
-  if (!METHODS.includes(verb) || !isObj(document) || !isObj(document.paths)) return "unknown";
-  const entry = document.paths[path];
-  if (!isObj(entry)) return "unknown";
+function viewEntry(document, entry) {
   const chain = [entry];
   const seen = /* @__PURE__ */ new Set([entry]);
   for (let current = entry; typeof current.$ref === "string"; ) {
@@ -175,13 +199,142 @@ function operationState(document, method, path, overrides) {
     chain.push(target);
     current = target;
   }
-  const item = Object.assign({}, ...[...chain].reverse());
-  const operation = item[verb];
-  if (!isObj(operation)) return "unknown";
+  return { chain, item: Object.assign({}, ...[...chain].reverse()) };
+}
+function visibility(chain, operation, override) {
   if (chain.some((level) => flagged(level["x-excluded"])) || flagged(operation["x-excluded"])) return "excluded";
-  const override = isObj(overrides) ? overrides[`${verb.toUpperCase()} ${path}`] : void 0;
   const hidden = isObj(override) && typeof override.hidden === "boolean" ? override.hidden : chain.some((level) => flagged(level["x-hidden"])) || flagged(operation["x-hidden"]);
-  return hidden ? "hidden" : "published";
+  return hidden ? "hidden" : "visible";
+}
+function operationState(document, method, path, overrides) {
+  const verb = method.toLowerCase();
+  if (!METHODS.includes(verb) || !isObj(document) || !isObj(document.paths)) return "unknown";
+  const entry = document.paths[path];
+  if (!isObj(entry)) return "unknown";
+  const { chain, item } = viewEntry(document, entry);
+  const operation = item[verb];
+  if (!isObj(operation)) return "unknown";
+  const result = visibility(chain, operation, isObj(overrides) ? overrides[`${verb.toUpperCase()} ${path}`] : void 0);
+  return result === "visible" ? "published" : result;
+}
+function webhookState(document, name, overrides) {
+  if (!isObj(document) || !isObj(document.webhooks) || !Object.hasOwn(document.webhooks, name)) return "unknown";
+  const entry = document.webhooks[name];
+  if (!isObj(entry)) return "unknown";
+  const { chain, item } = viewEntry(document, entry);
+  const states = METHODS.filter((verb) => isObj(item[verb])).map((verb) => visibility(chain, item[verb], isObj(overrides) ? overrides[`WEBHOOK ${verb.toUpperCase()} ${name}`] : void 0));
+  if (states.length === 0) return "unknown";
+  return states.includes("visible") ? "published" : states[0];
+}
+
+// src/manual-api-check.ts
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkMdx from "remark-mdx";
+var METHODS2 = /* @__PURE__ */ new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]);
+function normalizeServerUrl(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!/^https?:\/\/[^\s]+$/i.test(trimmed)) return null;
+  let url;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    return null;
+  }
+  if (url.username || url.password || url.search || url.hash || !url.hostname) return null;
+  return trimmed.replace(/\/+$/, "");
+}
+function parseManualApi(raw) {
+  if (typeof raw !== "string") return null;
+  const value = raw.trim().replace(/^(["'])([\s\S]*)\1$/, "$2").trim();
+  const match = /^([A-Za-z]+)\s+(\S+)$/.exec(value);
+  if (!match) return null;
+  const method = match[1].toUpperCase();
+  if (!METHODS2.has(method)) return null;
+  const split = /^(https?:\/\/[^/?#]*)?([^?#]*)(?:\?([^#]*))?(?:#.*)?$/i.exec(match[2]);
+  if (!split || !split[1] && !split[2].startsWith("/")) return null;
+  let server;
+  if (split[1]) {
+    const origin = normalizeServerUrl(split[1]);
+    if (!origin || split[1].includes("@")) return null;
+    server = origin;
+  }
+  const query = {};
+  if (split[3]) {
+    for (const [key, entry] of new URLSearchParams(split[3])) if (key) query[key] = entry;
+  }
+  return { method, ...server ? { server } : {}, path: split[2] || "/", query };
+}
+function attributeValue(attribute) {
+  if (!attribute) return void 0;
+  const value = attribute.value;
+  if (value === null || value === void 0) return true;
+  if (typeof value === "string") return value;
+  const expression = (value.value ?? "").trim();
+  try {
+    const parsed = JSON.parse(expression);
+    if (typeof parsed === "string" || typeof parsed === "boolean") return parsed;
+    if (typeof parsed === "number") return String(parsed);
+    return expression;
+  } catch {
+    return expression;
+  }
+}
+function paramFieldPathNames(mdx) {
+  let tree;
+  try {
+    tree = unified().use(remarkParse).use(remarkMdx).parse(mdx);
+  } catch {
+    return [];
+  }
+  const names = [];
+  const seen = /* @__PURE__ */ new Set();
+  const visit = (node) => {
+    if ((node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") && node.name === "ParamField") {
+      const attrs = /* @__PURE__ */ new Map();
+      for (const attribute of node.attributes ?? []) {
+        if (attribute.type === "mdxJsxAttribute" && attribute.name) attrs.set(attribute.name, attribute);
+      }
+      const located = ["path", "query", "header", "body"].find((key) => {
+        const value = attributeValue(attrs.get(key));
+        return value !== void 0 && value !== false && value !== "false";
+      });
+      const locatedName = located ? attributeValue(attrs.get(located)) : void 0;
+      const explicit = attributeValue(attrs.get("name"));
+      const name = typeof locatedName === "string" && locatedName ? locatedName : typeof explicit === "string" && explicit ? explicit : "";
+      const location = located ?? "body";
+      if (name && !seen.has(`${location}:${name}`)) {
+        seen.add(`${location}:${name}`);
+        if (location === "path") names.push(name);
+      }
+    }
+    for (const child of node.children ?? []) visit(child);
+  };
+  visit(tree);
+  return names;
+}
+function mdxServers(docsApi) {
+  const mdx = docsApi?.mdx;
+  const raw = mdx?.server === void 0 ? [] : Array.isArray(mdx.server) ? mdx.server : [mdx.server];
+  return [...new Set(raw.flatMap((entry) => normalizeServerUrl(entry) ?? []))];
+}
+function manualApiProblems(file, data, hasOpenApiReference, mdx, docsApi) {
+  if (data.api === void 0 || data.api === null) return [];
+  if (hasOpenApiReference) return [`page ${file}: both "openapi" and "api" are set; "api" is ignored`];
+  const target = parseManualApi(data.api);
+  if (!target) {
+    return [`page ${file}: "api" frontmatter is not "METHOD https://host/path" or "METHOD /path"; the page renders without an API playground`];
+  }
+  const problems = [];
+  if (!target.server && mdxServers(docsApi).length === 0) {
+    problems.push(`page ${file}: "api" is a path and docs.json has no server: set docs.json "api.mdx.server" or use a full URL, or the playground is disabled`);
+  }
+  const template = new Set([...target.path.matchAll(/{([^{}/]+)}/g)].map((match) => match[1]));
+  for (const name of paramFieldPathNames(mdx)) {
+    if (!template.has(name)) problems.push(`page ${file}: <ParamField path="${name}"> has no matching {${name}} in the "api" path; it is ignored in the playground`);
+  }
+  return problems;
 }
 
 // src/check.ts
@@ -444,25 +597,28 @@ function checkPublicSpecs(projectDir, tabs, issues) {
   }
 }
 function checkUnpublishedOperationPages(projectDir, tabs, pages, issues) {
-  const api = tabs.find((tab) => !tab.hidden && tab.api?.source)?.api;
-  const source = api?.source;
-  if (!source || pages.length === 0 || /^https?:/i.test(source)) return;
-  const specPath = source.startsWith("/") ? join2(projectDir, "public", source.slice(1)) : join2(projectDir, source);
-  let spec;
-  try {
-    const raw = readFileSync2(specPath, "utf8");
-    spec = /\.json$/i.test(source) ? JSON.parse(raw) : parseYaml3(raw);
-  } catch {
-    return;
-  }
-  const overrides = api.overrides;
-  for (const { file, method, path } of pages) {
-    const state = operationState(spec, method, path, overrides);
+  if (pages.length === 0) return;
+  const specs = tabs.filter((tab) => !tab.hidden && typeof tab.api?.source === "string").map((tab) => {
+    const source = tab.api.source;
+    const overrides = tab.api.overrides;
+    if (/^https?:/i.test(source)) return { source, overrides };
+    const specPath = source.startsWith("/") ? join2(projectDir, "public", source.slice(1)) : join2(projectDir, source);
+    try {
+      const raw = readFileSync2(specPath, "utf8");
+      return { source, overrides, document: /\.json$/i.test(source) ? JSON.parse(raw) : parseYaml3(raw) };
+    } catch {
+      return { source, overrides };
+    }
+  });
+  if (specs.length === 0) return;
+  for (const { file, reference } of pages) {
+    const state = pageState(reference, specs);
     if (state === "hidden" || state === "excluded") {
+      const operation = `${reference.specRef ? `${reference.specRef} ` : ""}${reference.method} ${reference.path}`;
       issues.push({
         severity: "warning",
         file,
-        message: `page ${file} points at ${state} operation ${method} ${path} and is not published: it returns 404 and is left out of navigation, search, sitemap and llms.txt. Publish the operation or point the page at another one`
+        message: `page ${file} points at ${state} operation ${operation} and is not published: it returns 404 and is left out of navigation, search, sitemap and llms.txt. Publish the operation or point the page at another one`
       });
     }
   }
@@ -595,8 +751,11 @@ async function runCheck(projectDir, options) {
     if (typeof data.openapi !== "string" && content.trim().length < 50) {
       issues.push({ severity: "warning", message: `Very short body (${content.trim().length} chars) \u2014 page may be empty`, file: rel2 });
     }
-    const operation = parseDocOperation(data.openapi);
-    if (operation) operationPages.push({ file: rel2, ...operation });
+    const reference = parseDocReference(data.openapi);
+    if (reference) operationPages.push({ file: rel2, reference });
+    for (const message of manualApiProblems(rel2, data, Boolean(reference), content, config.api)) {
+      issues.push({ severity: "warning", file: rel2, message });
+    }
     if (options.drift) checkDrift(projectDir, rel2, data, issues);
     const path = pageIdToPath(pageId, secondaryLocales);
     const anchors = extractHeadingAnchors(content);

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   migrateDocs,
   parseFrontmatter,
   runCheck
-} from "./chunk-4JW7VBXN.js";
+} from "./chunk-UL4XFPLQ.js";
 import {
   logo,
   scaffold,

package/dist/migrate/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   migrateDocs
-} from "../chunk-4JW7VBXN.js";
+} from "../chunk-UL4XFPLQ.js";
 import "../chunk-KCBUOBEF.js";
 import "../chunk-XYRM4GAT.js";
 import "../chunk-UBIX5ISG.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-thally-docs",
-  "version": "0.10.69",
+  "version": "0.10.70",
   "description": "Scaffold an open-source Thally docs site for people, search engines, and AI tools.",
   "type": "module",
   "engines": {
@@ -45,7 +45,7 @@
     "@anthropic-ai/sdk": "^0.36.0",
     "@inquirer/prompts": "^7.0.0",
     "@thallylabs/core": "0.2.9",
-    "@thallylabs/migrate": "0.2.18",
+    "@thallylabs/migrate": "0.2.19",
     "p-limit": "^6.1.0",
     "remark-mdx": "^3.1.1",
     "remark-parse": "^11.0.0",