@apimatic/cli 2.0.0-beta.1 → 2.0.0-beta.3

package/portal-template/src/lib/navigation.ts

@@ -26,11 +26,7 @@ const REST_TOKEN = '...';
 /** The API reference, positioned as one node. */
 const API_REFERENCE_TOKEN = 'apimatic:api';
 
-/**
- * The folders the CLI generates, each a tab of its own, by the token that positions it and in
- * the order they take when the root `nav.json` names none of them. The CLI's
- * `GENERATED_SECTIONS` lists the same, and a test holds the two together.
- */
+/** The folders the CLI generates, by the token that positions each; the CLI's `GENERATED_SECTIONS` lists the same. */
 export const GENERATED_SECTIONS = [
   { token: 'apimatic:sdks', folder: 'sdks' },
   { token: 'apimatic:plugin', folder: 'context-plugin' }
@@ -43,15 +39,15 @@ const API_REFERENCE_TITLE = 'API Reference';
 /** Where the home page is served, which is how its node is told apart from every other page. */
 const HOME_URL = docsRoute;
 
-/** Fixed, as tab matching goes by id after serialisation; Fumadocs' ids never start with a slash. */
-const HOME_TAB_ID = '/tab/home';
-
 /** The Home tab's name when the root `nav.json` gives none, and the fallback home page's. */
 const HOME_NAME = 'Home';
 
 /** The node the fallback home page gets when there is no index page; see `withFallbackHomePage`. */
 const SYNTHETIC_HOME_ID = '/page/home';
 
+/** The Home tab's id. Fixed, as tab matching goes by id after serialisation; Fumadocs' ids never start with a slash. */
+const HOME_TAB_ID = '/tab/home';
+
 /**
  * The key the generated pages are passed to `loader()` under, which the storage stamps onto
  * every file of that source.
@@ -82,16 +78,10 @@ export function navigationTransformer<S extends ContentStorage>(): PageTreeTrans
       // folder whose only page is its index is not empty: the folder itself links to it.
       node.children = node.children.filter((child) => !isEmptyFolder(child));
 
-      // The root is ordered even with no file of its own: naming nothing still puts the
-      // generated sections and the API reference at their defaults, and Fumadocs' own order
-      // would not. It sorts folders by path, so `api` lands above a user folder called anything
-      // later in the alphabet, and a generated folder lands in the middle of the user's pages.
-      // Below the root those defaults do not apply, so a folder with no file keeps Fumadocs'
-      // order untouched, which is every tag folder of every specification.
+      // A directory with no order keeps Fumadocs' own, the root included.
       const settings = readSettings(this, folderPath);
-      const order = settings?.pages;
-      if (folderPath === '' || order !== undefined) {
-        node.children = reorder(this, node, folderPath, order ?? []);
+      if (settings?.pages !== undefined) {
+        node.children = reorder(this, node, folderPath, settings.pages);
       }
       if (folderPath === apiBaseDir) {
         applyApiStructure(this, node);
@@ -105,7 +95,7 @@ export function navigationTransformer<S extends ContentStorage>(): PageTreeTrans
   };
 }
 
-/** A tab per folder the root `nav.json` lists, the API reference and each generated folder; the rest is Home. */
+/** A tab per entry of the root `nav.json`'s `tabs`, in its order; everything else is Home. */
 export function tabsTransformer<S extends ContentStorage>(): PageTreeTransformer<S> {
   return {
     root(root) {
@@ -119,6 +109,8 @@ export function tabsTransformer<S extends ContentStorage>(): PageTreeTransformer
 interface NavigationSettings {
   pages: string[] | undefined;
   title: string | undefined;
+  /** Read at the root only; the CLI refuses it anywhere else. */
+  tabs: string[] | undefined;
 }
 
 function readSettings(context: NavigationContext, folderPath: string): NavigationSettings | undefined {
@@ -130,41 +122,36 @@ function readSettings(context: NavigationContext, folderPath: string): Navigatio
     return undefined;
   }
 
-  const { pages, title } = file.data as { pages?: unknown; title?: unknown };
+  const { pages, tabs, title } = file.data as { pages?: unknown; tabs?: unknown; title?: unknown };
   // A half-typed title reloads to here as an empty string, which would blank the folder in
   // the sidebar with nothing to click. The CLI refuses one; the preview keeps the default
   // name until the file is worth reading again.
   const named = typeof title === 'string' ? title.trim() : '';
   return {
-    pages: Array.isArray(pages) ? pages.filter((entry): entry is string => typeof entry === 'string') : undefined,
+    pages: stringsOf(pages),
+    tabs: stringsOf(tabs),
     title: named.length > 0 ? named : undefined
   };
 }
 
-function isTabFolder(rootSettings: NavigationSettings | undefined, folder: Folder): boolean {
-  const folderPath = folder.$ref?.folder;
-  return (
-    folderPath !== undefined &&
-    folderPath !== apiBaseDir &&
-    lists(rootSettings, folderPath) &&
-    // The home page is the Home tab's, whichever `(group)` folder serves it.
-    !containsUrl([folder], HOME_URL)
-  );
+function stringsOf(entries: unknown): string[] | undefined {
+  return Array.isArray(entries) ? entries.filter((entry): entry is string => typeof entry === 'string') : undefined;
 }
 
+/** The nodes the root `tabs` names become the tabs, in its order; everything else is Home. */
 function groupIntoTabs(context: NavigationContext, children: Node[]): Node[] {
   const settings = readSettings(context, '');
+  const remaining = new Set(children);
   const tabs: Folder[] = [];
-  const loose: Node[] = [];
-
-  for (const child of children) {
-    if (
-      child.type === 'folder' &&
-      (isApiReference(child) || isTabFolder(settings, child) || isInjected(context, child))
-    ) {
-      tabs.push(asTab(child));
-    } else {
-      loose.push(child);
+
+  // Resolved as `reorder` resolves an entry, before the tabs lose their `$ref`. A page is no
+  // tab, and the home page is the Home tab's whichever `(group)` folder serves it; the CLI
+  // refuses both entries, and an entry naming nothing is left to it as well.
+  for (const raw of settings?.tabs ?? []) {
+    const node = nodeNamed(context, [...remaining], '', raw.trim());
+    if (node?.type === 'folder' && !containsUrl([node], HOME_URL)) {
+      remaining.delete(node);
+      tabs.push(asTab(node));
     }
   }
 
@@ -181,7 +168,7 @@ function groupIntoTabs(context: NavigationContext, children: Node[]): Node[] {
     $id: HOME_TAB_ID,
     name: settings?.title ?? HOME_NAME,
     root: true,
-    children: withFallbackHomePage(loose)
+    children: withFallbackHomePage([...remaining])
   };
   // Home opens the site, so it leads wherever the file lists its pages; `index` orders them only.
   return [home, ...tabs];
@@ -209,10 +196,6 @@ function asTab(folder: Folder): Folder {
   return folder;
 }
 
-function lists(settings: NavigationSettings | undefined, name: string): boolean {
-  return settings?.pages?.some((entry) => entry.trim() === name) ?? false;
-}
-
 /**
  * Titles the wrapper and, for a single specification, lifts its section away.
  *
@@ -268,66 +251,51 @@ function firstPageIn(folder: Folder): Node | undefined {
   return undefined;
 }
 
+/**
+ * `node`'s children with the ones `order` names first, in its order, and the rest where its
+ * rest token stands, or after everything named when it has none. The rest keep Fumadocs' own
+ * order: pages before folders, each by path.
+ */
 function reorder(context: NavigationContext, node: Folder, folderPath: string, order: string[]): Node[] {
   const remaining = new Set(node.children);
-  // Asked once per child: the token, both bands and the anchor all want to know, and each
-  // answer is a storage read.
-  const injectedChildren = new Set(node.children.filter((child) => isInjected(context, child)));
-  const isInjectedChild = (child: Node): boolean => injectedChildren.has(child);
   const named: Node[] = [];
   let restIndex: number | undefined;
 
-  const claim = (child: Node | undefined): void => {
-    if (child !== undefined) {
-      remaining.delete(child);
-      named.push(child);
-    }
-  };
-
-  // Every token names a node that lives at the content root, and the CLI refuses each one
-  // anywhere else. Honouring them in a nested directory would let the two halves of the
-  // format disagree about a file only one of them had rejected.
-  const isContentRoot = folderPath === '';
-
   for (const raw of order) {
     const entry = raw.trim();
-    const section = GENERATED_SECTIONS.find((candidate) => candidate.token === entry);
     if (entry === REST_TOKEN) {
       restIndex = named.length;
-    } else if (entry === API_REFERENCE_TOKEN) {
-      if (isContentRoot) {
-        claim([...remaining].find((child) => isApiReference(child)));
-      }
-    } else if (section !== undefined) {
-      if (isContentRoot) {
-        claim([...remaining].find((child) => isInjectedChild(child) && isSectionFolder(child, section)));
-      }
-    } else {
-      claim(matching(context, [...remaining], folderPath, entry));
+      continue;
+    }
+    const child = nodeNamed(context, [...remaining], folderPath, entry);
+    if (child !== undefined) {
+      remaining.delete(child);
+      named.push(child);
     }
   }
 
-  // What is left keeps its default order, in three bands. The generated sections and the API
-  // reference have defaults of their own rather than travelling with the content, so that
-  // a later release adding a section never splits the band or reorders a sidebar nobody
-  // touched. The sections keep the CLI's order: Fumadocs' own is by path, which would put
-  // `context-plugin` above `sdks`.
-  const rest = [...remaining];
-  const api = rest.filter((child) => isApiReference(child));
-  const injected = rest.filter(isInjectedChild).sort((left, right) => sectionRank(left) - sectionRank(right));
-  const content = rest.filter((child) => !isApiReference(child) && !isInjectedChild(child));
-
-  // With no rest token, unnamed content joins the user's own pages: after the last one the
-  // file named. Appending at the end instead would drop it below the whole API reference,
-  // and inserting before the reference would lift it above one the file deliberately put
-  // first.
-  const at = restIndex ?? afterNamedContent(named, isInjectedChild);
-  const ordered = [...named.slice(0, at), ...content, ...named.slice(at)];
-
-  // Before the API reference, but never above the user's own pages: when the file puts the
-  // reference first, the band follows the content instead.
-  const anchor = Math.max(anchorIn(ordered), at + content.length);
-  return [...ordered.slice(0, anchor), ...injected, ...ordered.slice(anchor), ...api];
+  const at = restIndex ?? named.length;
+  return [...named.slice(0, at), ...remaining, ...named.slice(at)];
+}
+
+/**
+ * The child an entry names, or undefined. A token names a node that lives at the content root,
+ * and the CLI refuses each one anywhere else; honouring it in a nested directory would let the
+ * two halves of the format disagree about a file only one of them had rejected.
+ */
+function nodeNamed(context: NavigationContext, children: Node[], folderPath: string, entry: string): Node | undefined {
+  const isContentRoot = folderPath === '';
+  const section = GENERATED_SECTIONS.find((candidate) => candidate.token === entry);
+  if (entry === API_REFERENCE_TOKEN) {
+    return isContentRoot ? children.find((child) => isApiReference(child)) : undefined;
+  }
+  if (section !== undefined) {
+    // The cheap path check first: `isInjected` reads storage.
+    return isContentRoot
+      ? children.find((child) => isSectionFolder(child, section) && isInjected(context, child))
+      : undefined;
+  }
+  return matching(context, children, folderPath, entry);
 }
 
 /**
@@ -346,22 +314,6 @@ function matching(context: NavigationContext, children: Node[], folderPath: stri
   return children.find((child) => child.type === 'page' && child.$ref === pagePath);
 }
 
-function afterNamedContent(named: Node[], isInjectedChild: (child: Node) => boolean): number {
-  for (let index = named.length - 1; index >= 0; index -= 1) {
-    if (!isApiReference(named[index]) && !isInjectedChild(named[index])) {
-      return index + 1;
-    }
-  }
-  // Nothing named is the user's own, so everything named is what the CLI adds, and the
-  // user's pages keep their default place above all of it.
-  return 0;
-}
-
-function anchorIn(children: Node[]): number {
-  const index = children.findIndex((child) => isApiReference(child));
-  return index === -1 ? children.length : index;
-}
-
 function isApiReference(child: Node): child is Folder {
   return child.type === 'folder' && child.$ref?.folder === apiBaseDir;
 }
@@ -383,15 +335,6 @@ function isInjected(context: NavigationContext, child: Node): boolean {
   return isFromSource(context, child, GENERATED_SOURCE);
 }
 
-/**
- * Where a generated folder comes in `GENERATED_SECTIONS`. Anything else sorts after them, which
- * only a loose generated page could be, and the CLI writes none.
- */
-function sectionRank(child: Node): number {
-  const rank = GENERATED_SECTIONS.findIndex((section) => isSectionFolder(child, section));
-  return rank === -1 ? GENERATED_SECTIONS.length : rank;
-}
-
 function isSectionFolder(child: Node, section: (typeof GENERATED_SECTIONS)[number]): boolean {
   return child.type === 'folder' && child.$ref?.folder === section.folder;
 }

package/portal-template/src/lib/request-examples.ts

@@ -1,11 +1,9 @@
-import type { useOperationContext } from 'fumadocs-openapi/ui';
+import type { ParameterObject } from 'fumadocs-openapi';
+import type { ExampleRequest, OperationParameters } from 'fumadocs-openapi/operation';
 import { isJsonObject } from './json';
 
-export type RequestExample = Pick<
-  ReturnType<typeof useOperationContext>['examples'][number],
-  'id' | 'name' | 'description'
->;
-type Location = 'path' | 'query' | 'header' | 'cookie';
+export type RequestExample = Pick<ExampleRequest, 'id' | 'name' | 'description'>;
+type Location = OperationParameters['in'];
 type Resolve = (node: unknown) => unknown;
 
 interface Example {
@@ -25,22 +23,16 @@ export class Parameter {
     private readonly examples: Map<string, Example>
   ) {}
 
-  public static listIn(operation: unknown, pathItem: unknown, resolve: Resolve): Parameter[] {
-    return [...parametersOf(operation), ...parametersOf(pathItem)].flatMap(
-      (entry) => Parameter.from(resolve(entry), resolve) ?? []
-    );
+  // Takes the parameters Fumadocs has already resolved, deduplicated and grouped by location.
+  public static listIn(groups: OperationParameters[], resolve: Resolve): Parameter[] {
+    return groups.flatMap((group) => group.items.map((item) => Parameter.from(group.in, item, resolve)));
   }
 
-  private static from(entry: unknown, resolve: Resolve): Parameter | undefined {
-    if (!isJsonObject(entry) || !isLocation(entry.in) || typeof entry.name !== 'string') {
-      return undefined;
-    }
-    const examples = isJsonObject(entry.examples)
-      ? Object.entries(entry.examples)
-          .map(([id, example]): [string, unknown] => [id, resolve(example)])
-          .filter(isExampleEntry)
-      : [];
-    return new Parameter(entry.in, new Map(examples));
+  private static from(location: Location, item: ParameterObject, resolve: Resolve): Parameter {
+    const examples = Object.entries(item.examples ?? {})
+      .map(([id, example]): [string, unknown] => [id, resolve(example)])
+      .filter(isExampleEntry);
+    return new Parameter(location, new Map(examples));
   }
 
   public namedExamples(): [string, Example][] {
@@ -58,14 +50,6 @@ export function requestExamples(bodyExamples: RequestExample[], parameters: Para
   return named.map(([id, { summary, description }]) => ({ id, name: summary || id, description }));
 }
 
-function parametersOf(node: unknown): unknown[] {
-  return isJsonObject(node) && Array.isArray(node.parameters) ? node.parameters : [];
-}
-
-function isLocation(value: unknown): value is Location {
-  return value === 'path' || value === 'query' || value === 'header' || value === 'cookie';
-}
-
 function isExampleEntry(entry: [string, unknown]): entry is [string, Example] {
   return isJsonObject(entry[1]) && 'value' in entry[1];
 }

package/portal-template/src/lib/source.ts

@@ -3,6 +3,7 @@ import { applyMdxPreset } from 'fumadocs-mdx/config';
 import { rehypeCodeDefaultOptions } from 'fumadocs-core/mdx-plugins';
 import rehypeRaw from 'rehype-raw';
 import { rehypeCodeTitles, rehypeKeepCodeMeta } from './rehype-code-titles';
+import { navigationSchema } from './navigation-schema';
 
 // What `rehype-raw` must hand on untouched, being MDX's own nodes rather than HTML.
 const MDX_NODE_TYPES = ['mdxFlowExpression', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxTextExpression', 'mdxjsEsm'];
@@ -18,8 +19,8 @@ export const docs = defineDocs({
   // Restricted to our own file, replacing the default of every .json and .yaml in the
   // content directory. Without it a leftover `meta.json` is loaded as a folder's metadata
   // and applied before the transformer runs -- and since a metadata file hides whatever it
-  // does not name, the transformer could not put those pages back.
-  meta: { files: ['**/nav.json'] }
+  // does not name, the transformer could not put those pages back. The schema keeps `tabs`.
+  meta: { files: ['**/nav.json'], schema: navigationSchema }
 });
 
 // The pages the CLI writes into this project, resolved against the Vite root like `content`.

package/portal-template/src/lib/tabs.ts

@@ -7,10 +7,10 @@ import { containsUrl, docsRoute } from './shared';
  * transformer has run. Given to the layout rather than left to Fumadocs, which links a tab to
  * its folder's first direct page and so leaves out a tab holding only folders -- as the API
  * reference does whenever its operations are grouped. Each stays bound to its folder, which is
- * how the active tab is found.
+ * how the active tab is found. A switcher with one choice switches nothing, so one tab is none.
  */
 export function portalTabs(tree: PageTree.Root): LayoutTab[] {
-  return tree.children.flatMap((node) => {
+  const tabs = tree.children.flatMap((node) => {
     if (node.type !== 'folder' || node.root !== true) return [];
     // Home keeps the order the root nav.json gives, which need not put the home page first.
     const url = containsUrl([node], docsRoute) ? docsRoute : firstPageUrl(node);
@@ -18,6 +18,7 @@ export function portalTabs(tree: PageTree.Root): LayoutTab[] {
       ? []
       : [{ title: node.name, description: node.description, icon: node.icon, url, $folder: node }];
   });
+  return tabs.length > 1 ? tabs : [];
 }
 
 /**

package/portal-template/src/components/code-block.tsx

@@ -1,9 +0,0 @@
-import { DynamicCodeBlock } from 'fumadocs-ui/components/dynamic-codeblock.core';
-import { useRenderContext } from 'fumadocs-openapi/ui';
-
-// Fumadocs passes `JSON.stringify(example.value)`, which is undefined for an example with no `value`.
-export function CodeBlock({ lang, code }: Readonly<{ lang: string; code: string | undefined }>) {
-  const { shiki, shikiOptions } = useRenderContext();
-  if (code === undefined) return null;
-  return <DynamicCodeBlock lang={lang} code={code} highlighter={() => shiki.getOrInit()} options={shikiOptions} />;
-}