pointfree-docs 0.1.0 → 0.2.0

package/dist/commands/update.d.ts

@@ -3,6 +3,8 @@
  */
 interface UpdateOptions {
     libs?: string[];
+    examples?: boolean;
+    episodes?: boolean;
 }
 export declare function updateCommand(options: UpdateOptions): Promise<void>;
 export {};

package/dist/commands/update.js

@@ -3,8 +3,8 @@
  */
 import chalk from "chalk";
 import { LIBRARIES, getLibrary } from "../config.js";
-import { updateLibrary, isLibraryCloned } from "../lib/repos.js";
-import { indexLibrary, openIndex, closeIndex } from "../lib/index.js";
+import { updateLibrary, updateExamples, updateEpisodes, isLibraryCloned, areExamplesCloned, areEpisodesCloned } from "../lib/repos.js";
+import { indexLibrary, indexExamples, indexEpisodes, openIndex, closeIndex } from "../lib/index.js";
 export async function updateCommand(options) {
     console.log(chalk.bold("\n🔄 Updating Point-Free Documentation\n"));
     // Determine which libraries to update
@@ -24,27 +24,53 @@ export async function updateCommand(options) {
             }
         }
     }
-    if (librariesToUpdate.length === 0) {
-        console.log(chalk.yellow("No libraries to update. Run 'pf-docs init' first."));
+    // Check for examples/episodes
+    const shouldUpdateExamples = options.examples && areExamplesCloned();
+    const shouldUpdateEpisodes = options.episodes && areEpisodesCloned();
+    if (options.examples && !areExamplesCloned()) {
+        console.log(chalk.yellow(`  ⚠ Examples not initialized. Run 'pf-docs init --examples' first.`));
+    }
+    if (options.episodes && !areEpisodesCloned()) {
+        console.log(chalk.yellow(`  ⚠ Episodes not initialized. Run 'pf-docs init --episodes' first.`));
+    }
+    if (librariesToUpdate.length === 0 && !shouldUpdateExamples && !shouldUpdateEpisodes) {
+        console.log(chalk.yellow("Nothing to update. Run 'pf-docs init' first."));
         return;
     }
     // Update repositories
     console.log(chalk.bold("Pulling latest changes..."));
     const updatedLibs = [];
+    let examplesUpdated = false;
+    let episodesUpdated = false;
     for (const lib of librariesToUpdate) {
         const wasUpdated = await updateLibrary(lib);
         if (wasUpdated) {
             updatedLibs.push(lib);
         }
     }
-    // Re-index updated libraries
-    if (updatedLibs.length > 0) {
-        console.log(chalk.bold("\nRe-indexing updated libraries..."));
+    if (shouldUpdateExamples) {
+        examplesUpdated = await updateExamples();
+    }
+    if (shouldUpdateEpisodes) {
+        episodesUpdated = await updateEpisodes();
+    }
+    // Re-index updated sources
+    const hasUpdates = updatedLibs.length > 0 || examplesUpdated || episodesUpdated;
+    if (hasUpdates) {
+        console.log(chalk.bold("\nRe-indexing updated sources..."));
         openIndex();
         for (const lib of updatedLibs) {
             const count = indexLibrary(lib);
             console.log(`  ✓ Re-indexed ${lib.shortName}: ${count} documents`);
         }
+        if (examplesUpdated) {
+            const count = indexExamples();
+            console.log(`  ✓ Re-indexed examples: ${count} files`);
+        }
+        if (episodesUpdated) {
+            const count = indexEpisodes();
+            console.log(`  ✓ Re-indexed episodes: ${count} files`);
+        }
         closeIndex();
     }
     console.log(chalk.green(`\n✅ Update complete!\n`));

package/dist/config.d.ts

@@ -1,6 +1,10 @@
 /**
- * Configuration for Point-Free libraries
+ * Configuration for Point-Free libraries and example sources
  */
+/**
+ * Source types for documentation
+ */
+export type SourceType = "docs" | "examples" | "episodes";
 export interface LibraryConfig {
     name: string;
     shortName: string;
@@ -8,11 +12,34 @@ export interface LibraryConfig {
     docsPaths: string[];
     description: string;
 }
+export interface ExamplesConfig {
+    name: string;
+    shortName: string;
+    repo: string;
+    paths: string[];
+    description: string;
+    filePatterns: string[];
+}
+export interface EpisodesConfig {
+    name: string;
+    shortName: string;
+    repo: string;
+    description: string;
+    filePatterns: string[];
+}
 /**
  * All available Point-Free libraries
  * Add or remove libraries here to customize what's indexed
  */
 export declare const LIBRARIES: LibraryConfig[];
+/**
+ * TCA Examples configuration (CaseStudies, SyncUps, etc.)
+ */
+export declare const EXAMPLES_CONFIG: ExamplesConfig;
+/**
+ * Episode code samples configuration
+ */
+export declare const EPISODES_CONFIG: EpisodesConfig;
 /**
  * Get library config by short name
  */
@@ -21,6 +48,10 @@ export declare function getLibrary(shortName: string): LibraryConfig | undefined
  * All library short names
  */
 export declare const LIBRARY_NAMES: string[];
+/**
+ * All valid source types
+ */
+export declare const SOURCE_TYPES: SourceType[];
 export declare const PATHS: {
     dataDir: string;
     reposDir: string;

package/dist/config.js

@@ -1,5 +1,5 @@
 /**
- * Configuration for Point-Free libraries
+ * Configuration for Point-Free libraries and example sources
  */
 import { join } from "path";
 /**
@@ -100,6 +100,35 @@ export const LIBRARIES = [
         description: "Runtime warnings & assertions",
     },
 ];
+/**
+ * TCA Examples configuration (CaseStudies, SyncUps, etc.)
+ */
+export const EXAMPLES_CONFIG = {
+    name: "tca-examples",
+    shortName: "examples",
+    repo: "pointfreeco/swift-composable-architecture",
+    paths: [
+        "Examples/CaseStudies",
+        "Examples/SyncUps",
+        "Examples/Todos",
+        "Examples/VoiceMemos",
+        "Examples/Search",
+        "Examples/TicTacToe",
+        "Examples/SpeechRecognition",
+    ],
+    description: "TCA example apps and case studies",
+    filePatterns: ["**/*.swift"],
+};
+/**
+ * Episode code samples configuration
+ */
+export const EPISODES_CONFIG = {
+    name: "episode-code-samples",
+    shortName: "episodes",
+    repo: "pointfreeco/episode-code-samples",
+    description: "Point-Free episode code samples (350+ episodes)",
+    filePatterns: ["**/*.swift", "**/*.playground/**/*.swift"],
+};
 /**
  * Get library config by short name
  */
@@ -110,6 +139,10 @@ export function getLibrary(shortName) {
  * All library short names
  */
 export const LIBRARY_NAMES = LIBRARIES.map((lib) => lib.shortName);
+/**
+ * All valid source types
+ */
+export const SOURCE_TYPES = ["docs", "examples", "episodes"];
 /**
  * Paths configuration
  */

package/dist/lib/format.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared formatting utilities
+ */
+import { SourceType } from "../config.js";
+/**
+ * Get source type label with color and brackets for search/list results
+ */
+export declare function getSourceLabel(source: SourceType): string;
+/**
+ * Get source type name with color (for stats display)
+ */
+export declare function getSourceName(source: SourceType): string;

package/dist/lib/format.js

@@ -0,0 +1,30 @@
+/**
+ * Shared formatting utilities
+ */
+import chalk from "chalk";
+/**
+ * Get source type label with color and brackets for search/list results
+ */
+export function getSourceLabel(source) {
+    switch (source) {
+        case "docs":
+            return chalk.cyan("[DOC]");
+        case "examples":
+            return chalk.magenta("[EXAMPLE]");
+        case "episodes":
+            return chalk.yellow("[EPISODE]");
+    }
+}
+/**
+ * Get source type name with color (for stats display)
+ */
+export function getSourceName(source) {
+    switch (source) {
+        case "docs":
+            return chalk.cyan("docs");
+        case "examples":
+            return chalk.magenta("examples");
+        case "episodes":
+            return chalk.yellow("episodes");
+    }
+}

package/dist/lib/index.d.ts

@@ -2,11 +2,12 @@
  * Search index using SQLite FTS5 for full-text search
  */
 import Database from "better-sqlite3";
-import { LibraryConfig } from "../config.js";
+import { LibraryConfig, SourceType } from "../config.js";
 export interface DocEntry {
     library: string;
     path: string;
     title: string;
+    source: SourceType;
 }
 export interface DocWithContent extends DocEntry {
     content: string;
@@ -14,6 +15,7 @@ export interface DocWithContent extends DocEntry {
 export interface IndexStats {
     totalDocs: number;
     byLibrary: Record<string, number>;
+    bySource: Record<SourceType, number>;
 }
 /**
  * Initialize or open the search index database
@@ -23,6 +25,14 @@ export declare function openIndex(): Database.Database;
  * Index all documentation files for a library
  */
 export declare function indexLibrary(lib: LibraryConfig): number;
+/**
+ * Index TCA examples (CaseStudies, etc.)
+ */
+export declare function indexExamples(): number;
+/**
+ * Index episode code samples
+ */
+export declare function indexEpisodes(): number;
 /**
  * Search the index
  */
@@ -32,15 +42,17 @@ export interface SearchResult {
     title: string;
     snippet: string;
     score: number;
+    source: SourceType;
 }
 export declare function search(query: string, options?: {
     lib?: string;
     limit?: number;
+    source?: SourceType | "all";
 }): SearchResult[];
 /**
  * List all indexed documents
  */
-export declare function listDocs(lib?: string): DocEntry[];
+export declare function listDocs(lib?: string, source?: SourceType | "all"): DocEntry[];
 /**
  * Get a specific document by path
  */

package/dist/lib/index.js

@@ -5,8 +5,8 @@ import Database from "better-sqlite3";
 import { existsSync, mkdirSync, readFileSync } from "fs";
 import { glob } from "glob";
 import { basename, join } from "path";
-import { PATHS } from "../config.js";
-import { getDocsPaths } from "./repos.js";
+import { PATHS, EXAMPLES_CONFIG, EPISODES_CONFIG } from "../config.js";
+import { getDocsPaths, getExamplesPaths, getEpisodesPath } from "./repos.js";
 import { cleanMarkdown, extractTitle } from "./markdown.js";
 let db = null;
 /**
@@ -28,6 +28,7 @@ export function openIndex() {
       path TEXT NOT NULL,
       title TEXT,
       content TEXT,
+      source TEXT NOT NULL DEFAULT 'docs',
       UNIQUE(library, path)
     );
 
@@ -36,26 +37,40 @@ export function openIndex() {
       content,
       library,
       path,
+      source,
       content='docs',
       content_rowid='id'
     );
+  `);
+    // Add source column if it doesn't exist (migration for existing databases)
+    try {
+        db.exec(`ALTER TABLE docs ADD COLUMN source TEXT NOT NULL DEFAULT 'docs'`);
+    }
+    catch {
+        // Column already exists, ignore
+    }
+    // Drop and recreate triggers to ensure they include the source column
+    // This handles migration from older schema versions
+    db.exec(`
+    DROP TRIGGER IF EXISTS docs_ai;
+    DROP TRIGGER IF EXISTS docs_ad;
+    DROP TRIGGER IF EXISTS docs_au;
 
-    -- Triggers to keep FTS index in sync
-    CREATE TRIGGER IF NOT EXISTS docs_ai AFTER INSERT ON docs BEGIN
-      INSERT INTO docs_fts(rowid, title, content, library, path)
-      VALUES (new.id, new.title, new.content, new.library, new.path);
+    CREATE TRIGGER docs_ai AFTER INSERT ON docs BEGIN
+      INSERT INTO docs_fts(rowid, title, content, library, path, source)
+      VALUES (new.id, new.title, new.content, new.library, new.path, new.source);
     END;
 
-    CREATE TRIGGER IF NOT EXISTS docs_ad AFTER DELETE ON docs BEGIN
-      INSERT INTO docs_fts(docs_fts, rowid, title, content, library, path)
-      VALUES ('delete', old.id, old.title, old.content, old.library, old.path);
+    CREATE TRIGGER docs_ad AFTER DELETE ON docs BEGIN
+      INSERT INTO docs_fts(docs_fts, rowid, title, content, library, path, source)
+      VALUES ('delete', old.id, old.title, old.content, old.library, old.path, old.source);
     END;
 
-    CREATE TRIGGER IF NOT EXISTS docs_au AFTER UPDATE ON docs BEGIN
-      INSERT INTO docs_fts(docs_fts, rowid, title, content, library, path)
-      VALUES ('delete', old.id, old.title, old.content, old.library, old.path);
-      INSERT INTO docs_fts(rowid, title, content, library, path)
-      VALUES (new.id, new.title, new.content, new.library, new.path);
+    CREATE TRIGGER docs_au AFTER UPDATE ON docs BEGIN
+      INSERT INTO docs_fts(docs_fts, rowid, title, content, library, path, source)
+      VALUES ('delete', old.id, old.title, old.content, old.library, old.path, old.source);
+      INSERT INTO docs_fts(rowid, title, content, library, path, source)
+      VALUES (new.id, new.title, new.content, new.library, new.path, new.source);
     END;
   `);
     return db;
@@ -67,8 +82,8 @@ export function indexLibrary(lib) {
     const db = openIndex();
     const docsPaths = getDocsPaths(lib);
     const insertStmt = db.prepare(`
-    INSERT OR REPLACE INTO docs (library, path, title, content)
-    VALUES (?, ?, ?, ?)
+    INSERT OR REPLACE INTO docs (library, path, title, content, source)
+    VALUES (?, ?, ?, ?, ?)
   `);
     let indexed = 0;
     for (const docsPath of docsPaths) {
@@ -86,7 +101,7 @@ export function indexLibrary(lib) {
                 const title = extractTitle(content) || basename(file, ".md");
                 // Logical path like "tca/Testing" or "tca/Articles/Performance"
                 const docPath = `${lib.shortName}/${file.replace(/\.md$/, "")}`;
-                insertStmt.run(lib.shortName, docPath, title, cleanedContent);
+                insertStmt.run(lib.shortName, docPath, title, cleanedContent, "docs");
                 indexed++;
             }
             catch (error) {
@@ -96,9 +111,112 @@ export function indexLibrary(lib) {
     }
     return indexed;
 }
+/**
+ * Index TCA examples (CaseStudies, etc.)
+ */
+export function indexExamples() {
+    const db = openIndex();
+    const examplesPaths = getExamplesPaths();
+    const insertStmt = db.prepare(`
+    INSERT OR REPLACE INTO docs (library, path, title, content, source)
+    VALUES (?, ?, ?, ?, ?)
+  `);
+    let indexed = 0;
+    for (const examplesPath of examplesPaths) {
+        if (!existsSync(examplesPath)) {
+            continue;
+        }
+        // Find all Swift files
+        for (const pattern of EXAMPLES_CONFIG.filePatterns) {
+            const files = glob.sync(pattern, { cwd: examplesPath });
+            for (const file of files) {
+                const fullPath = join(examplesPath, file);
+                try {
+                    const content = readFileSync(fullPath, "utf-8");
+                    // Extract title from filename or first struct/class
+                    const title = extractSwiftTitle(content) || basename(file, ".swift");
+                    // Get the example category from the path (e.g., "CaseStudies", "SyncUps")
+                    const category = basename(examplesPath);
+                    const docPath = `examples/${category}/${file}`;
+                    insertStmt.run("examples", docPath, title, content, "examples");
+                    indexed++;
+                }
+                catch (error) {
+                    console.error(`  Warning: Failed to index ${fullPath}:`, error);
+                }
+            }
+        }
+    }
+    return indexed;
+}
+/**
+ * Index episode code samples
+ */
+export function indexEpisodes() {
+    const db = openIndex();
+    const episodesPath = getEpisodesPath();
+    if (!existsSync(episodesPath)) {
+        return 0;
+    }
+    const insertStmt = db.prepare(`
+    INSERT OR REPLACE INTO docs (library, path, title, content, source)
+    VALUES (?, ?, ?, ?, ?)
+  `);
+    let indexed = 0;
+    // Find all episode directories (0001-xxx, 0002-xxx, etc.)
+    const episodeDirs = glob.sync("[0-9][0-9][0-9][0-9]-*", { cwd: episodesPath });
+    for (const episodeDir of episodeDirs) {
+        const episodePath = join(episodesPath, episodeDir);
+        // Find all Swift files in this episode
+        for (const pattern of EPISODES_CONFIG.filePatterns) {
+            const files = glob.sync(pattern, { cwd: episodePath });
+            for (const file of files) {
+                const fullPath = join(episodePath, file);
+                try {
+                    const content = readFileSync(fullPath, "utf-8");
+                    // Title: episode name + file name
+                    const episodeName = formatEpisodeName(episodeDir);
+                    const fileName = basename(file, ".swift");
+                    const title = `${episodeName}: ${fileName}`;
+                    const docPath = `episodes/${episodeDir}/${file}`;
+                    insertStmt.run("episodes", docPath, title, content, "episodes");
+                    indexed++;
+                }
+                catch (error) {
+                    console.error(`  Warning: Failed to index ${fullPath}:`, error);
+                }
+            }
+        }
+    }
+    return indexed;
+}
+/**
+ * Extract title from Swift file (first struct/class/enum name)
+ */
+function extractSwiftTitle(content) {
+    // Match struct, class, enum, or actor declarations
+    const match = content.match(/(?:struct|class|enum|actor)\s+(\w+)/);
+    return match ? match[1] : null;
+}
+/**
+ * Format episode directory name to readable title
+ * "0156-testable-state-pt1" -> "Episode 156: Testable State Pt1"
+ */
+function formatEpisodeName(dirName) {
+    const match = dirName.match(/^(\d+)-(.+)$/);
+    if (!match)
+        return dirName;
+    const num = parseInt(match[1], 10);
+    const name = match[2]
+        .split("-")
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ");
+    return `Ep${num}: ${name}`;
+}
 export function search(query, options = {}) {
     const db = openIndex();
     const limit = options.limit || 10;
+    const source = options.source || "docs"; // Default to docs only
     // Escape special FTS5 characters and format query
     const ftsQuery = query
         .replace(/['"]/g, "") // Remove quotes
@@ -115,7 +233,8 @@ export function search(query, options = {}) {
       path,
       title,
       snippet(docs_fts, 1, '**', '**', '...', 32) as snippet,
-      bm25(docs_fts) as score
+      bm25(docs_fts) as score,
+      source
     FROM docs_fts
     WHERE docs_fts MATCH ?
   `;
@@ -124,6 +243,11 @@ export function search(query, options = {}) {
         sql += ` AND library = ?`;
         params.push(options.lib);
     }
+    // Filter by source unless "all" is specified
+    if (source !== "all") {
+        sql += ` AND source = ?`;
+        params.push(source);
+    }
     sql += ` ORDER BY score LIMIT ?`;
     params.push(limit);
     try {
@@ -142,13 +266,15 @@ export function search(query, options = {}) {
 function fallbackSearch(query, options = {}) {
     const db = openIndex();
     const limit = options.limit || 10;
+    const source = options.source || "docs";
     let sql = `
     SELECT
       library,
       path,
       title,
       substr(content, 1, 200) as snippet,
-      0 as score
+      0 as score,
+      source
     FROM docs
     WHERE (title LIKE ? OR content LIKE ?)
   `;
@@ -158,6 +284,10 @@ function fallbackSearch(query, options = {}) {
         sql += ` AND library = ?`;
         params.push(options.lib);
     }
+    if (source !== "all") {
+        sql += ` AND source = ?`;
+        params.push(source);
+    }
     sql += ` LIMIT ?`;
     params.push(limit);
     try {
@@ -171,15 +301,19 @@ function fallbackSearch(query, options = {}) {
 /**
  * List all indexed documents
  */
-export function listDocs(lib) {
+export function listDocs(lib, source) {
     const db = openIndex();
-    let sql = `SELECT library, path, title FROM docs`;
+    let sql = `SELECT library, path, title, source FROM docs WHERE 1=1`;
     const params = [];
     if (lib) {
-        sql += ` WHERE library = ?`;
+        sql += ` AND library = ?`;
         params.push(lib);
     }
-    sql += ` ORDER BY library, path`;
+    if (source && source !== "all") {
+        sql += ` AND source = ?`;
+        params.push(source);
+    }
+    sql += ` ORDER BY source, library, path`;
     const stmt = db.prepare(sql);
     return stmt.all(...params);
 }
@@ -188,7 +322,7 @@ export function listDocs(lib) {
  */
 export function getDoc(path) {
     const db = openIndex();
-    const stmt = db.prepare(`SELECT library, path, title, content FROM docs WHERE path = ?`);
+    const stmt = db.prepare(`SELECT library, path, title, content, source FROM docs WHERE path = ?`);
     return stmt.get(path);
 }
 /**
@@ -201,7 +335,10 @@ export function getStats() {
     const byLibStmt = db.prepare(`SELECT library, COUNT(*) as count FROM docs GROUP BY library`);
     const byLibRows = byLibStmt.all();
     const byLibrary = Object.fromEntries(byLibRows.map((row) => [row.library, row.count]));
-    return { totalDocs: total, byLibrary };
+    const bySourceStmt = db.prepare(`SELECT source, COUNT(*) as count FROM docs GROUP BY source`);
+    const bySourceRows = bySourceStmt.all();
+    const bySource = Object.fromEntries(bySourceRows.map((row) => [row.source, row.count]));
+    return { totalDocs: total, byLibrary, bySource };
 }
 /**
  * Run a function with the index open, closing it automatically afterward.

package/dist/lib/repos.d.ts

@@ -6,15 +6,47 @@ import { LibraryConfig } from "../config.js";
  * Clone a library repository (sparse checkout, docs only)
  */
 export declare function cloneLibrary(lib: LibraryConfig): Promise<void>;
+/**
+ * Clone TCA examples (CaseStudies, SyncUps, etc.)
+ */
+export declare function cloneExamples(): Promise<void>;
+/**
+ * Clone episode code samples
+ */
+export declare function cloneEpisodes(): Promise<void>;
 /**
  * Update a library repository
  */
 export declare function updateLibrary(lib: LibraryConfig): Promise<boolean>;
+/**
+ * Update examples repository
+ */
+export declare function updateExamples(): Promise<boolean>;
+/**
+ * Update episodes repository
+ */
+export declare function updateEpisodes(): Promise<boolean>;
 /**
  * Get all local paths to a library's docs
  */
 export declare function getDocsPaths(lib: LibraryConfig): string[];
+/**
+ * Get all local paths to examples
+ */
+export declare function getExamplesPaths(): string[];
+/**
+ * Get local path to episodes
+ */
+export declare function getEpisodesPath(): string;
 /**
  * Check if a library is cloned
  */
 export declare function isLibraryCloned(lib: LibraryConfig): boolean;
+/**
+ * Check if examples are cloned
+ */
+export declare function areExamplesCloned(): boolean;
+/**
+ * Check if episodes are cloned
+ */
+export declare function areEpisodesCloned(): boolean;