skrypt-ai 0.3.4 → 0.4.1

package/dist/template/src/app/docs/generator/organizer.md

@@ -0,0 +1,779 @@
+# Organizer.ts
+
+## Functions
+
+### `organizeByTopic`
+
+```typescript
+function organizeByTopic(docs: GeneratedDoc[], config: TopicConfig = DEFAULT_TOPIC_CONFIG): Topic[]
+```
+
+Use this to group a flat list of generated documentation objects into organized topic clusters — ideal for building navigation menus, documentation sidebars, or categorized API references.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `docs` | `GeneratedDoc[]` | Yes | Array of generated documentation objects to organize |
+| `config` | `TopicConfig` | No | Configuration controlling how topics are detected and grouped. Defaults to `DEFAULT_TOPIC_CONFIG` |
+
+## Returns
+
+Returns a `Topic[]` array where each `Topic` contains a label, slug, and the subset of `GeneratedDoc` items belonging to that topic. Returns an empty array if `docs` is empty.
+
+**Example:**
+
+```typescript example.ts
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type GeneratedDoc = {
+  id: string
+  title: string
+  topic: string
+  content: string
+  slug: string
+}
+
+type Topic = {
+  label: string
+  slug: string
+  docs: GeneratedDoc[]
+}
+
+type TopicConfig = {
+  defaultTopic: string
+  topicOrder?: string[]
+  normalize?: (topic: string) => string
+}
+
+// ── Inline DEFAULT_TOPIC_CONFIG ────────────────────────────────────────────
+
+const DEFAULT_TOPIC_CONFIG: TopicConfig = {
+  defaultTopic: "General",
+  topicOrder: [],
+  normalize: (topic: string) => topic.trim().toLowerCase().replace(/\s+/g, "-"),
+}
+
+// ── Inline organizeByTopic implementation ─────────────────────────────────
+
+function organizeByTopic(
+  docs: GeneratedDoc[],
+  config: TopicConfig = DEFAULT_TOPIC_CONFIG
+): Topic[] {
+  const topicDocs = new Map<string, GeneratedDoc[]>()
+
+  for (const doc of docs) {
+    const rawTopic = doc.topic || config.defaultTopic
+    const label = rawTopic.trim()
+    const existing = topicDocs.get(label) ?? []
+    topicDocs.set(label, [...existing, doc])
+  }
+
+  const topics: Topic[] = []
+
+  // Respect topicOrder if provided
+  const ordered = config.topicOrder ?? []
+  const allLabels = [...new Set([...ordered, ...topicDocs.keys()])]
+
+  for (const label of allLabels) {
+    const docsForTopic = topicDocs.get(label)
+    if (!docsForTopic) continue
+
+    const slug = config.normalize
+      ? config.normalize(label)
+      : label.toLowerCase().replace(/\s+/g, "-")
+
+    topics.push({ label, slug, docs: docsForTopic })
+  }
+
+  return topics
+}
+
+// ── Realistic usage example ────────────────────────────────────────────────
+
+const generatedDocs: GeneratedDoc[] = [
+  {
+    id: "doc-001",
+    title: "createUser",
+    topic: "Authentication",
+    content: "Creates a new user account with the given credentials.",
+    slug: "create-user",
+  },
+  {
+    id: "doc-002",
+    title: "verifyToken",
+    topic: "Authentication",
+    content: "Validates a JWT and returns the decoded payload.",
+    slug: "verify-token",
+  },
+  {
+    id: "doc-003",
+    title: "uploadFile",
+    topic: "Storage",
+    content: "Uploads a file to the configured storage bucket.",
+    slug: "upload-file",
+  },
+  {
+    id: "doc-004",
+    title: "deleteFile",
+    topic: "Storage",
+    content: "Removes a file from storage by its key.",
+    slug: "delete-file",
+  },
+  {
+    id: "doc-005",
+    title: "sendEmail",
+    topic: "Notifications",
+    content: "Sends a transactional email via the configured provider.",
+    slug: "send-email",
+  },
+  {
+    id: "doc-006",
+    title: "getRateLimits",
+    topic: "", // falls back to defaultTopic
+    content: "Returns current rate limit status for the API key.",
+    slug: "get-rate-limits",
+  },
+]
+
+const customConfig: TopicConfig = {
+  defaultTopic: "General",
+  topicOrder: ["Authentication", "Storage", "Notifications"],
+  normalize: (topic) => topic.toLowerCase().replace(/\s+/g, "-"),
+}
+
+async function main() {
+  try {
+    const topics = organizeByTopic(generatedDocs, customConfig)
+
+    console.log(`Organized into ${topics.length} topics:\n`)
+
+    for (const topic of topics) {
+      console.log(`📂 ${topic.label} (slug: "${topic.slug}")`)
+      for (const doc of topic.docs) {
+        console.log(`   • ${doc.title} → /${topic.slug}/${doc.slug}`)
+      }
+    }
+
+    // Expected output:
+    // Organized into 4 topics:
+    //
+    // 📂 Authentication (slug: "authentication")
+    //    • createUser → /authentication/create-user
+    //    • verifyToken → /authentication/verify-token
+    // 📂 Storage (slug: "storage")
+    //    • uploadFile → /storage/upload-file
+    //    • deleteFile → /storage/delete-file
+    // 📂 Notifications (slug: "notifications")
+    //    • sendEmail → /notifications/send-email
+    // 📂 General (slug: "general")
+    //    • getRateLimits → /general/get-rate-limits
+  } catch (error) {
+    console.error("Failed to organize docs:", error)
+  }
+}
+
+main()
+```
+
+### `detectCrossReferences`
+
+```typescript
+function detectCrossReferences(docs: GeneratedDoc[]): CrossReference[]
+```
+
+Use this to automatically discover relationships between documented elements — for example, when one function references another by name in its parameters, return type, or description.
+
+Given an array of generated documentation objects, this scans each element and identifies where one doc references another by name, returning a flat list of directed cross-references you can use to build navigation links, dependency graphs, or "See Also" sections.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `docs` | `GeneratedDoc[]` | ✅ | Array of generated documentation objects. Each must have an `element` with a `name` property and associated metadata to scan for references. |
+
+## Returns
+
+Returns `CrossReference[]` — an array of cross-reference objects. Each entry describes a directed link from a **source** element to a **target** element found within it.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `from` | `string` | Name of the element that contains the reference |
+| `to` | `string` | Name of the element being referenced |
+| `type` | `string` | The kind of relationship (e.g. `"parameter"`, `"return"`, `"mention"`) |
+
+Returns an **empty array** if no cross-references are detected or if fewer than two docs are provided.
+
+**Example:**
+
+```typescript example.ts
+// ─── Inline types (do NOT import from autodocs) ───────────────────────────────
+
+type DocElement = {
+  name: string;
+  params?: { type: string }[];
+  returnType?: string;
+  description?: string;
+};
+
+type GeneratedDoc = {
+  element: DocElement;
+  topics: string[];
+};
+
+type CrossReference = {
+  from: string;
+  to: string;
+  type: "parameter" | "return" | "mention";
+};
+
+// ─── Simulated implementation of detectCrossReferences ───────────────────────
+
+function detectCrossReferences(docs: GeneratedDoc[]): CrossReference[] {
+  const refs: CrossReference[] = [];
+  const elementNames = new Set(docs.map((d) => d.element.name));
+
+  for (const doc of docs) {
+    const { element } = doc;
+
+    // Check parameter types for references to other documented elements
+    for (const param of element.params ?? []) {
+      if (elementNames.has(param.type) && param.type !== element.name) {
+        refs.push({ from: element.name, to: param.type, type: "parameter" });
+      }
+    }
+
+    // Check return type
+    if (
+      element.returnType &&
+      elementNames.has(element.returnType) &&
+      element.returnType !== element.name
+    ) {
+      refs.push({ from: element.name, to: element.returnType, type: "return" });
+    }
+
+    // Check description for mentions of other element names
+    if (element.description) {
+      for (const name of elementNames) {
+        if (name !== element.name && element.description.includes(name)) {
+          refs.push({ from: element.name, to: name, type: "mention" });
+        }
+      }
+    }
+  }
+
+  return refs;
+}
+
+// ─── Realistic example data ───────────────────────────────────────────────────
+
+const docs: GeneratedDoc[] = [
+  {
+    element: {
+      name: "UserProfile",
+      params: [],
+      returnType: undefined,
+      description: "Represents a user account in the system.",
+    },
+    topics: ["models"],
+  },
+  {
+    element: {
+      name: "fetchUserProfile",
+      params: [{ type: "string" }],
+      returnType: "UserProfile",
+      description: "Fetches a UserProfile from the remote API by user ID.",
+    },
+    topics: ["api", "users"],
+  },
+  {
+    element: {
+      name: "updateUserProfile",
+      params: [{ type: "UserProfile" }],
+      returnType: "UserProfile",
+      description: "Updates and returns the modified UserProfile record.",
+    },
+    topics: ["api", "users"],
+  },
+  {
+    element: {
+      name: "deleteUser",
+      params: [{ type: "string" }],
+      returnType: "boolean",
+      description: "Permanently removes a user. See also fetchUserProfile.",
+    },
+    topics: ["api", "users"],
+  },
+];
+
+// ─── Run and display results ──────────────────────────────────────────────────
+
+async function main() {
+  try {
+    const crossRefs = detectCrossReferences(docs);
+
+    if (crossRefs.length === 0) {
+      console.log("No cross-references detected.");
+      return;
+    }
+
+    console.log(`Detected ${crossRefs.length} cross-reference(s):\n`);
+
+    for (const ref of crossRefs) {
+      console.log(`  [${ref.type.toUpperCase()}]  ${ref.from}  →  ${ref.to}`);
+    }
+
+    // Expected output:
+    // Detected 5 cross-reference(s):
+    //
+    //   [RETURN]   fetchUserProfile  →  UserProfile
+    //   [PARAMETER] updateUserProfile  →  UserProfile
+    //   [RETURN]   updateUserProfile  →  UserProfile
+    //   [MENTION]  deleteUser  →  fetchUserProfile
+  } catch (error) {
+    console.error("detectCrossReferences failed:", error);
+  }
+}
+
+main();
+```
+
+### `getCrossRefsForElement`
+
+```typescript
+function getCrossRefsForElement(elementName: string, allRefs: CrossReference[]): CrossReference[]
+```
+
+Use this to filter a list of cross-references down to only those originating from a specific element — useful when building navigation, dependency graphs, or "see also" sections for a given function, class, or module.
+
+Given an element name and a full list of cross-references, it returns only the references where `fromElement` matches the provided name.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `elementName` | `string` | ✅ | The name of the element whose outgoing cross-references you want to retrieve |
+| `allRefs` | `CrossReference[]` | ✅ | The complete list of cross-references to filter from |
+
+### Returns
+
+`CrossReference[]` — A filtered array containing only the cross-references where `fromElement === elementName`. Returns an empty array if no matches are found.
+
+**Example:**
+
+```typescript example.ts
+// Inline the CrossReference type (matches the real shape from autodocs)
+type CrossReference = {
+  fromElement: string
+  toElement: string
+  description?: string
+}
+
+// Inline the function implementation
+function getCrossRefsForElement(
+  elementName: string,
+  allRefs: CrossReference[]
+): CrossReference[] {
+  return allRefs.filter(r => r.fromElement === elementName)
+}
+
+// Realistic cross-reference data across several elements
+const allCrossRefs: CrossReference[] = [
+  { fromElement: 'UserService',    toElement: 'AuthService',    description: 'Delegates login to AuthService' },
+  { fromElement: 'UserService',    toElement: 'UserRepository', description: 'Reads/writes user records' },
+  { fromElement: 'AuthService',    toElement: 'TokenService',   description: 'Issues JWT tokens' },
+  { fromElement: 'OrderService',   toElement: 'UserService',    description: 'Validates user before placing order' },
+  { fromElement: 'UserService',    toElement: 'EmailService',   description: 'Sends welcome email on signup' },
+]
+
+async function main() {
+  try {
+    // Get all cross-references originating from 'UserService'
+    const userServiceRefs = getCrossRefsForElement('UserService', allCrossRefs)
+    console.log('Cross-references for UserService:')
+    console.log(userServiceRefs)
+    // Output:
+    // [
+    //   { fromElement: 'UserService', toElement: 'AuthService',    description: 'Delegates login to AuthService' },
+    //   { fromElement: 'UserService', toElement: 'UserRepository', description: 'Reads/writes user records' },
+    //   { fromElement: 'UserService', toElement: 'EmailService',   description: 'Sends welcome email on signup' }
+    // ]
+
+    // Element with no outgoing references returns an empty array
+    const noRefs = getCrossRefsForElement('PaymentService', allCrossRefs)
+    console.log('\nCross-references for PaymentService:', noRefs)
+    // Output: []
+
+    // Practical use: list all "see also" targets for a given element
+    const targets = userServiceRefs.map(ref => ref.toElement)
+    console.log('\nUserService depends on:', targets)
+    // Output: [ 'AuthService', 'UserRepository', 'EmailService' ]
+  } catch (error) {
+    console.error('Failed to retrieve cross-references:', error)
+  }
+}
+
+main()
+```
+
+### `buildNavigation`
+
+```typescript
+function buildNavigation(topics: Topic[]): NavigationItem[]
+```
+
+Use this to convert a flat list of documentation topics into a hierarchical navigation structure suitable for rendering sidebars, menus, or breadcrumbs.
+
+Given an array of `Topic` objects (each containing an ID, name, and associated docs), `buildNavigation` returns a nested `NavigationItem[]` where each top-level item maps to a topic and its children map to individual documented elements.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `topics` | `Topic[]` | ✅ | Array of topic objects, each with an `id`, `name`, and `docs` array of documented elements |
+
+## Returns
+
+Returns `NavigationItem[]` — an array of navigation nodes where:
+- Each **top-level item** has a `title` (from `topic.name`) and a `path` (e.g. `"/utilities"`)
+- Each **child item** represents a documented element within that topic, nested under `children`
+
+Returns an **empty array** `[]` when given an empty `topics` input.
+
+**Example:**
+
+```typescript example.ts
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type DocElement = {
+  name: string;
+  description?: string;
+};
+
+type GeneratedDoc = {
+  element: DocElement;
+  markdown: string;
+};
+
+type Topic = {
+  id: string;
+  name: string;
+  docs: GeneratedDoc[];
+};
+
+type NavigationItem = {
+  title: string;
+  path: string;
+  children?: NavigationItem[];
+};
+
+// ── Inline implementation ──────────────────────────────────────────────────
+
+function buildNavigation(topics: Topic[]): NavigationItem[] {
+  return topics.map(topic => ({
+    title: topic.name,
+    path: `/${topic.id}`,
+    children: topic.docs.map(doc => ({
+      title: doc.element.name,
+      path: `/${topic.id}/${doc.element.name.toLowerCase().replace(/\s+/g, '-')}`,
+    })),
+  }));
+}
+
+// ── Example usage ──────────────────────────────────────────────────────────
+
+const topics: Topic[] = [
+  {
+    id: 'utilities',
+    name: 'Utilities',
+    docs: [
+      { element: { name: 'formatDate', description: 'Formats a date string' }, markdown: '...' },
+      { element: { name: 'slugify',    description: 'Converts text to a URL slug' }, markdown: '...' },
+    ],
+  },
+  {
+    id: 'auth',
+    name: 'Authentication',
+    docs: [
+      { element: { name: 'createToken',  description: 'Issues a signed JWT' }, markdown: '...' },
+      { element: { name: 'verifyToken',  description: 'Validates a JWT' },     markdown: '...' },
+    ],
+  },
+];
+
+try {
+  const nav = buildNavigation(topics);
+  console.log('Navigation structure:\n', JSON.stringify(nav, null, 2));
+  /*
+  Expected output:
+  [
+    {
+      "title": "Utilities",
+      "path": "/utilities",
+      "children": [
+        { "title": "formatDate", "path": "/utilities/formatdate" },
+        { "title": "slugify",    "path": "/utilities/slugify" }
+      ]
+    },
+    {
+      "title": "Authentication",
+      "path": "/auth",
+      "children": [
+        { "title": "createToken", "path": "/auth/createtoken" },
+        { "title": "verifyToken", "path": "/auth/verifytoken" }
+      ]
+    }
+  ]
+  */
+
+  // Edge case: empty topics list
+  const emptyNav = buildNavigation([]);
+  console.log('Empty input returns:', emptyNav); // []
+} catch (error) {
+  console.error('buildNavigation failed:', error);
+}
+```
+
+### `generateSidebarConfig`
+
+```typescript
+function generateSidebarConfig(topics: Topic[]): object
+```
+
+Use this to convert an array of documentation topics into a sidebar navigation configuration compatible with multiple documentation platforms (Mintlify, Docusaurus, etc.).
+
+The function maps each topic to a navigation group, with its documents as slugified page paths in the format `topicId/doc-name`.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `topics` | `Topic[]` | ✅ | Array of topic objects, each containing an `id`, `name`, and `docs` array of documented elements |
+
+## Returns
+
+Returns a plain `object` with a `navigation` key containing an array of group entries:
+
+```ts
+{
+  navigation: Array<{
+    group: string   // Human-readable topic name
+    pages: string[] // Slugified paths in format "topicId/element-name"
+  }>
+}
+```
+
+Returns an object with an empty `navigation` array if `topics` is empty.
+
+**Example:**
+
+```typescript example.ts
+// ── Inline types (no external imports needed) ──────────────────────────────
+type DocElement = { name: string }
+type GeneratedDoc = { element: DocElement }
+type Topic = {
+  id: string
+  name: string
+  docs: GeneratedDoc[]
+}
+
+// ── Inline slugify helper (mirrors the real implementation) ─────────────────
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+}
+
+// ── Inline generateSidebarConfig ────────────────────────────────────────────
+function generateSidebarConfig(topics: Topic[]): object {
+  return {
+    navigation: topics.map(topic => ({
+      group: topic.name,
+      pages: topic.docs.map(doc => `${topic.id}/${slugify(doc.element.name)}`)
+    }))
+  }
+}
+
+// ── Realistic example data ──────────────────────────────────────────────────
+const topics: Topic[] = [
+  {
+    id: 'authentication',
+    name: 'Authentication',
+    docs: [
+      { element: { name: 'createSession' } },
+      { element: { name: 'refreshToken' } },
+      { element: { name: 'revokeAccess' } },
+    ]
+  },
+  {
+    id: 'payments',
+    name: 'Payments & Billing',
+    docs: [
+      { element: { name: 'createCharge' } },
+      { element: { name: 'issueRefund' } },
+    ]
+  },
+  {
+    id: 'webhooks',
+    name: 'Webhooks',
+    docs: [
+      { element: { name: 'registerEndpoint' } },
+    ]
+  }
+]
+
+// ── Run it ──────────────────────────────────────────────────────────────────
+try {
+  const sidebarConfig = generateSidebarConfig(topics)
+  console.log('Sidebar config:', JSON.stringify(sidebarConfig, null, 2))
+
+  // Expected output:
+  // {
+  //   "navigation": [
+  //     {
+  //       "group": "Authentication",
+  //       "pages": [
+  //         "authentication/createsession",
+  //         "authentication/refreshtoken",
+  //         "authentication/revokeaccess"
+  //       ]
+  //     },
+  //     {
+  //       "group": "Payments & Billing",
+  //       "pages": [
+  //         "payments/createcharge",
+  //         "payments/issuerefund"
+  //       ]
+  //     },
+  //     {
+  //       "group": "Webhooks",
+  //       "pages": [
+  //         "webhooks/registerendpoint"
+  //       ]
+  //     }
+  //   ]
+  // }
+
+  // Edge case: empty topics array
+  const emptyConfig = generateSidebarConfig([])
+  console.log('Empty config:', JSON.stringify(emptyConfig))
+  // Output: { "navigation": [] }
+
+} catch (error) {
+  console.error('Failed to generate sidebar config:', error)
+}
+```
+
+### `mergeTopicConfig`
+
+```typescript
+function mergeTopicConfig(userConfig: Partial<TopicConfig>, defaults: TopicConfig = DEFAULT_TOPIC_CONFIG): TopicConfig
+```
+
+Use this to safely merge a partial user-provided topic configuration with a set of defaults, ensuring the resulting config is always complete and valid.
+
+This is useful when users supply only a subset of configuration options (e.g., overriding a few topics) and you need to fill in the rest from sensible defaults without losing any required fields.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `userConfig` | `Partial<TopicConfig>` | Yes | The user-supplied configuration. Only the fields provided will override the defaults. |
+| `defaults` | `TopicConfig` | No | The base configuration to fall back on. Defaults to `DEFAULT_TOPIC_CONFIG` if not provided. |
+
+### Returns
+
+Returns a complete `TopicConfig` object with all fields populated — user-provided values take precedence over defaults where supplied.
+
+**Example:**
+
+```typescript example.ts
+// Inline types (no external imports needed)
+type Topic = {
+  label: string
+  description: string
+  color?: string
+}
+
+type TopicConfig = {
+  topics: Record<string, Topic>
+}
+
+// Simulate DEFAULT_TOPIC_CONFIG
+const DEFAULT_TOPIC_CONFIG: TopicConfig = {
+  topics: {
+    general: {
+      label: 'General',
+      description: 'General documentation',
+      color: '#gray',
+    },
+    api: {
+      label: 'API Reference',
+      description: 'Auto-generated API docs',
+      color: '#blue',
+    },
+    guides: {
+      label: 'Guides',
+      description: 'Step-by-step tutorials',
+      color: '#green',
+    },
+  },
+}
+
+// Simulate mergeTopicConfig
+function mergeTopicConfig(
+  userConfig: Partial<TopicConfig>,
+  defaults: TopicConfig = DEFAULT_TOPIC_CONFIG
+): TopicConfig {
+  return {
+    topics: { ...defaults.topics, ...userConfig.topics },
+  }
+}
+
+// --- Usage Example ---
+
+// User only wants to override the 'api' topic and add a new 'changelog' topic
+const userConfig: Partial<TopicConfig> = {
+  topics: {
+    api: {
+      label: 'API Docs',
+      description: 'Customized API reference',
+      color: '#purple',
+    },
+    changelog: {
+      label: 'Changelog',
+      description: 'Release notes and version history',
+      color: '#orange',
+    },
+  },
+}
+
+try {
+  const finalConfig = mergeTopicConfig(userConfig)
+
+  console.log('Merged TopicConfig:')
+  console.log(JSON.stringify(finalConfig, null, 2))
+  // Expected output:
+  // {
+  //   "topics": {
+  //     "general":   { label: "General",    ... },   // from defaults
+  //     "api":       { label: "API Docs",   color: "#purple", ... }, // overridden by user
+  //     "guides":    { label: "Guides",     ... },   // from defaults
+  //     "changelog": { label: "Changelog",  ... }    // added by user
+  //   }
+  // }
+
+  // Verify override worked
+  console.log('\nAPI topic color (should be #purple):', finalConfig.topics.api.color)
+
+  // Verify defaults are preserved
+  console.log('General topic preserved:', finalConfig.topics.general.label)
+
+  // Verify new topic was added
+  console.log('Changelog topic added:', finalConfig.topics.changelog?.label)
+} catch (error) {
+  console.error('Failed to merge topic config:', error)
+}
+```
+