folderblog 0.0.2 → 0.0.3

package/dist/local/index.d.cts

@@ -0,0 +1,268 @@
+import { b as IssueReport, P as ProcessingIssue, c as IssueSummary, B as BrokenLinkIssue, S as SlugConflictIssue, s as MissingMediaIssue, m as IssueCategory, n as IssueModule, I as IssueFilterOptions, d as ProcessedPost, e as ProcessedMedia } from '../output-0P0br3Jc.cjs';
+
+declare class IssueIndex {
+    private readonly report;
+    constructor(report: IssueReport);
+    /** All issues */
+    all(): readonly ProcessingIssue[];
+    /** The summary (counts, affected files, etc.) */
+    get summary(): IssueSummary;
+    /** Build metadata (start/end time, version) */
+    get metadata(): {
+        readonly processStartTime: string;
+        readonly processEndTime: string;
+        readonly processorVersion?: string;
+    };
+    /** Total issue count */
+    get count(): number;
+    /** Whether there are any errors */
+    get hasErrors(): boolean;
+    /** Whether there are any warnings */
+    get hasWarnings(): boolean;
+    errors(): readonly ProcessingIssue[];
+    warnings(): readonly ProcessingIssue[];
+    info(): readonly ProcessingIssue[];
+    brokenLinks(): readonly BrokenLinkIssue[];
+    slugConflicts(): readonly SlugConflictIssue[];
+    missingMedia(): readonly MissingMediaIssue[];
+    /** Filter by category name */
+    byCategory(category: IssueCategory): readonly ProcessingIssue[];
+    /** Filter by module name */
+    byModule(module: IssueModule): readonly ProcessingIssue[];
+    /** Filter by file path */
+    byFile(filePath: string): readonly ProcessingIssue[];
+    /** Generic filter with multiple criteria (AND) */
+    filter(options: IssueFilterOptions): readonly ProcessingIssue[];
+    /** Get affected file paths */
+    affectedFiles(): string[];
+    /** Human-readable summary string */
+    summaryString(): string;
+}
+
+/**
+ * Types for the FolderBlogLocal client
+ */
+
+interface FolderBlogLocalOptions<TPost = ProcessedPost> {
+    /** Build output directory path (absolute or relative to cwd) */
+    dir: string;
+    /** Transform ProcessedPost into a custom type */
+    mapPost?: (post: ProcessedPost) => TPost;
+    /** Full-text search configuration */
+    search?: {
+        /** Enable search indexing (default: true) */
+        enabled?: boolean;
+        /** Field boost weights */
+        boost?: Record<string, number>;
+        /** Fuzzy matching tolerance (default: 0.2) */
+        fuzzy?: number;
+        /** Enable prefix matching (default: true) */
+        prefix?: boolean;
+    };
+    /** Similarity configuration */
+    similarity?: {
+        /** Enable similarity (default: auto — true if similarity.json exists) */
+        enabled?: boolean;
+        /** Number of similar posts to return (default: 5) */
+        topN?: number;
+    };
+    /** LRU cache configuration */
+    cache?: {
+        /** Enable caching (default: true) */
+        enabled?: boolean;
+        /** Max cache entries (default: 500) */
+        maxSize?: number;
+    };
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+interface SearchOptions {
+    /** Max results (default: 10) */
+    limit?: number;
+    /** Fuzzy tolerance override */
+    fuzzy?: number;
+    /** Enable prefix matching override */
+    prefix?: boolean;
+    /** Field boost overrides */
+    boost?: Record<string, number>;
+}
+interface SearchResult {
+    slug: string;
+    title: string;
+    excerpt: string;
+    score: number;
+}
+interface AutocompleteResult {
+    slug: string;
+    title: string;
+}
+interface SimilarResult {
+    post: ProcessedPost;
+    score: number;
+}
+interface RelatedResult {
+    post: ProcessedPost;
+    score: number;
+    reasons: string[];
+}
+/** Frontmatter key-value query. All conditions must match (AND). */
+type WhereQuery = Record<string, unknown>;
+interface TagCount {
+    tag: string;
+    count: number;
+}
+interface CategoryCount {
+    category: string;
+    count: number;
+}
+interface BlogStats {
+    posts: number;
+    media: number;
+    tags: number;
+    categories: number;
+    hasSearch: boolean;
+    hasSimilarity: boolean;
+}
+interface FolderBlogLocalClient<TPost = ProcessedPost> {
+    posts: {
+        list(): TPost[];
+        get(slug: string): TPost;
+        getByHash(hash: string): TPost;
+        getByPath(path: string): TPost;
+        recent(count?: number): TPost[];
+        filter(predicate: (post: TPost) => boolean): TPost[];
+        where(query: WhereQuery): TPost[];
+        featured(): TPost[];
+        published(): TPost[];
+        sorted(posts?: TPost[]): TPost[];
+        slugs(): string[];
+        readonly count: number;
+        readonly slugMap: Record<string, string>;
+    };
+    search(query: string, options?: SearchOptions): SearchResult[];
+    searchAutocomplete(term: string, limit?: number): AutocompleteResult[];
+    similar(slugOrHash: string, count?: number): SimilarResult[];
+    related(slugOrHash: string, count?: number): RelatedResult[];
+    tags: {
+        list(): TagCount[];
+        posts(tag: string): TPost[];
+    };
+    categories: {
+        list(): CategoryCount[];
+        posts(category: string): TPost[];
+    };
+    media: {
+        list(): ProcessedMedia[];
+        get(path: string): ProcessedMedia;
+    };
+    readonly stats: BlogStats;
+    /** Raw issue report (from processor-issues.json) */
+    readonly issues: IssueReport;
+    /** Queryable issue index with filtering by category, severity, file */
+    readonly report: IssueIndex;
+}
+
+/**
+ * PostStore — loads posts.json and provides indexed access by slug, hash, and path.
+ */
+
+/** Extract section/folder from a post's originalPath, stripping number prefixes */
+declare function extractSection(post: ProcessedPost): string;
+/** Check if a post is scheduled (date is in the future) */
+declare function isScheduled(post: ProcessedPost): boolean;
+/** Check if a post is a draft */
+declare function isDraft(post: ProcessedPost): boolean;
+/** Check if a post is hidden (excluded from public listings but still accessible) */
+declare function isHidden(post: ProcessedPost): boolean;
+/** Check if a post is published (not draft, not hidden, not future-dated) */
+declare function isPublished(post: ProcessedPost): boolean;
+
+/**
+ * Standard Post view type and mapper.
+ *
+ * Every consumer project maps ProcessedPost to a near-identical "Post" type.
+ * This module provides that standard mapping so consumers don't have to.
+ *
+ * Field renames:
+ * - content → html
+ * - plainText → plain
+ * - excerpt → firstParagraphText
+ * - originalPath → originalFilePath
+ * - toc[].slug → toc[].id
+ * - toc[].text → toc[].title
+ */
+
+interface PostTocItem {
+    id: string;
+    title: string;
+    depth: number;
+}
+interface PostFrontmatter {
+    title: string;
+    date?: string;
+    description?: string;
+    tags?: string[];
+    category?: string;
+    featured?: boolean;
+    draft?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Standard consumer-friendly Post type.
+ * Matches the shape every consumer independently creates.
+ */
+interface Post {
+    fileName: string;
+    slug: string;
+    hash: string;
+    frontmatter: PostFrontmatter;
+    firstParagraphText: string;
+    plain: string;
+    html: string;
+    toc: PostTocItem[];
+    originalFilePath: string;
+    wordCount: number;
+    firstImage?: string;
+    cover?: string;
+    links?: readonly string[];
+}
+/**
+ * Convert a ProcessedPost to the standard Post view type.
+ *
+ * @example
+ * ```ts
+ * import { createLocalClient, toPost } from 'folderblog/local';
+ * const blog = createLocalClient({ dir: './dist', mapPost: toPost });
+ * blog.posts.list() // Post[]
+ * ```
+ */
+declare function toPost(p: ProcessedPost): Post;
+
+/**
+ * FolderBlogLocal — local client that reads build output with search, similarity, and caching.
+ *
+ * @example
+ * ```ts
+ * import { createLocalClient } from 'folderblog/local';
+ *
+ * const blog = createLocalClient({ dir: './dist' });
+ * const posts = blog.posts.list();
+ * const results = blog.search('typescript');
+ * const similar = blog.similar('my-post-slug', 5);
+ * const related = blog.related('my-post-slug', 5);
+ * const autocomplete = blog.searchAutocomplete('type');
+ * ```
+ */
+
+/**
+ * Create a local client that reads from build output.
+ *
+ * @example
+ * ```ts
+ * const blog = createLocalClient({ dir: './dist' });
+ * const posts = blog.posts.list();
+ * ```
+ */
+declare function createLocalClient<TPost = ProcessedPost>(options: FolderBlogLocalOptions<TPost>): FolderBlogLocalClient<TPost>;
+
+export { type AutocompleteResult, type BlogStats, type CategoryCount, type FolderBlogLocalClient, type FolderBlogLocalOptions, IssueIndex, type Post, type PostFrontmatter, type PostTocItem, type RelatedResult, type SearchOptions, type SearchResult, type SimilarResult, type TagCount, type WhereQuery, createLocalClient, extractSection, isDraft, isHidden, isPublished, isScheduled, toPost };

package/dist/local/index.d.ts

@@ -0,0 +1,268 @@
+import { b as IssueReport, P as ProcessingIssue, c as IssueSummary, B as BrokenLinkIssue, S as SlugConflictIssue, s as MissingMediaIssue, m as IssueCategory, n as IssueModule, I as IssueFilterOptions, d as ProcessedPost, e as ProcessedMedia } from '../output-0P0br3Jc.js';
+
+declare class IssueIndex {
+    private readonly report;
+    constructor(report: IssueReport);
+    /** All issues */
+    all(): readonly ProcessingIssue[];
+    /** The summary (counts, affected files, etc.) */
+    get summary(): IssueSummary;
+    /** Build metadata (start/end time, version) */
+    get metadata(): {
+        readonly processStartTime: string;
+        readonly processEndTime: string;
+        readonly processorVersion?: string;
+    };
+    /** Total issue count */
+    get count(): number;
+    /** Whether there are any errors */
+    get hasErrors(): boolean;
+    /** Whether there are any warnings */
+    get hasWarnings(): boolean;
+    errors(): readonly ProcessingIssue[];
+    warnings(): readonly ProcessingIssue[];
+    info(): readonly ProcessingIssue[];
+    brokenLinks(): readonly BrokenLinkIssue[];
+    slugConflicts(): readonly SlugConflictIssue[];
+    missingMedia(): readonly MissingMediaIssue[];
+    /** Filter by category name */
+    byCategory(category: IssueCategory): readonly ProcessingIssue[];
+    /** Filter by module name */
+    byModule(module: IssueModule): readonly ProcessingIssue[];
+    /** Filter by file path */
+    byFile(filePath: string): readonly ProcessingIssue[];
+    /** Generic filter with multiple criteria (AND) */
+    filter(options: IssueFilterOptions): readonly ProcessingIssue[];
+    /** Get affected file paths */
+    affectedFiles(): string[];
+    /** Human-readable summary string */
+    summaryString(): string;
+}
+
+/**
+ * Types for the FolderBlogLocal client
+ */
+
+interface FolderBlogLocalOptions<TPost = ProcessedPost> {
+    /** Build output directory path (absolute or relative to cwd) */
+    dir: string;
+    /** Transform ProcessedPost into a custom type */
+    mapPost?: (post: ProcessedPost) => TPost;
+    /** Full-text search configuration */
+    search?: {
+        /** Enable search indexing (default: true) */
+        enabled?: boolean;
+        /** Field boost weights */
+        boost?: Record<string, number>;
+        /** Fuzzy matching tolerance (default: 0.2) */
+        fuzzy?: number;
+        /** Enable prefix matching (default: true) */
+        prefix?: boolean;
+    };
+    /** Similarity configuration */
+    similarity?: {
+        /** Enable similarity (default: auto — true if similarity.json exists) */
+        enabled?: boolean;
+        /** Number of similar posts to return (default: 5) */
+        topN?: number;
+    };
+    /** LRU cache configuration */
+    cache?: {
+        /** Enable caching (default: true) */
+        enabled?: boolean;
+        /** Max cache entries (default: 500) */
+        maxSize?: number;
+    };
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+interface SearchOptions {
+    /** Max results (default: 10) */
+    limit?: number;
+    /** Fuzzy tolerance override */
+    fuzzy?: number;
+    /** Enable prefix matching override */
+    prefix?: boolean;
+    /** Field boost overrides */
+    boost?: Record<string, number>;
+}
+interface SearchResult {
+    slug: string;
+    title: string;
+    excerpt: string;
+    score: number;
+}
+interface AutocompleteResult {
+    slug: string;
+    title: string;
+}
+interface SimilarResult {
+    post: ProcessedPost;
+    score: number;
+}
+interface RelatedResult {
+    post: ProcessedPost;
+    score: number;
+    reasons: string[];
+}
+/** Frontmatter key-value query. All conditions must match (AND). */
+type WhereQuery = Record<string, unknown>;
+interface TagCount {
+    tag: string;
+    count: number;
+}
+interface CategoryCount {
+    category: string;
+    count: number;
+}
+interface BlogStats {
+    posts: number;
+    media: number;
+    tags: number;
+    categories: number;
+    hasSearch: boolean;
+    hasSimilarity: boolean;
+}
+interface FolderBlogLocalClient<TPost = ProcessedPost> {
+    posts: {
+        list(): TPost[];
+        get(slug: string): TPost;
+        getByHash(hash: string): TPost;
+        getByPath(path: string): TPost;
+        recent(count?: number): TPost[];
+        filter(predicate: (post: TPost) => boolean): TPost[];
+        where(query: WhereQuery): TPost[];
+        featured(): TPost[];
+        published(): TPost[];
+        sorted(posts?: TPost[]): TPost[];
+        slugs(): string[];
+        readonly count: number;
+        readonly slugMap: Record<string, string>;
+    };
+    search(query: string, options?: SearchOptions): SearchResult[];
+    searchAutocomplete(term: string, limit?: number): AutocompleteResult[];
+    similar(slugOrHash: string, count?: number): SimilarResult[];
+    related(slugOrHash: string, count?: number): RelatedResult[];
+    tags: {
+        list(): TagCount[];
+        posts(tag: string): TPost[];
+    };
+    categories: {
+        list(): CategoryCount[];
+        posts(category: string): TPost[];
+    };
+    media: {
+        list(): ProcessedMedia[];
+        get(path: string): ProcessedMedia;
+    };
+    readonly stats: BlogStats;
+    /** Raw issue report (from processor-issues.json) */
+    readonly issues: IssueReport;
+    /** Queryable issue index with filtering by category, severity, file */
+    readonly report: IssueIndex;
+}
+
+/**
+ * PostStore — loads posts.json and provides indexed access by slug, hash, and path.
+ */
+
+/** Extract section/folder from a post's originalPath, stripping number prefixes */
+declare function extractSection(post: ProcessedPost): string;
+/** Check if a post is scheduled (date is in the future) */
+declare function isScheduled(post: ProcessedPost): boolean;
+/** Check if a post is a draft */
+declare function isDraft(post: ProcessedPost): boolean;
+/** Check if a post is hidden (excluded from public listings but still accessible) */
+declare function isHidden(post: ProcessedPost): boolean;
+/** Check if a post is published (not draft, not hidden, not future-dated) */
+declare function isPublished(post: ProcessedPost): boolean;
+
+/**
+ * Standard Post view type and mapper.
+ *
+ * Every consumer project maps ProcessedPost to a near-identical "Post" type.
+ * This module provides that standard mapping so consumers don't have to.
+ *
+ * Field renames:
+ * - content → html
+ * - plainText → plain
+ * - excerpt → firstParagraphText
+ * - originalPath → originalFilePath
+ * - toc[].slug → toc[].id
+ * - toc[].text → toc[].title
+ */
+
+interface PostTocItem {
+    id: string;
+    title: string;
+    depth: number;
+}
+interface PostFrontmatter {
+    title: string;
+    date?: string;
+    description?: string;
+    tags?: string[];
+    category?: string;
+    featured?: boolean;
+    draft?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Standard consumer-friendly Post type.
+ * Matches the shape every consumer independently creates.
+ */
+interface Post {
+    fileName: string;
+    slug: string;
+    hash: string;
+    frontmatter: PostFrontmatter;
+    firstParagraphText: string;
+    plain: string;
+    html: string;
+    toc: PostTocItem[];
+    originalFilePath: string;
+    wordCount: number;
+    firstImage?: string;
+    cover?: string;
+    links?: readonly string[];
+}
+/**
+ * Convert a ProcessedPost to the standard Post view type.
+ *
+ * @example
+ * ```ts
+ * import { createLocalClient, toPost } from 'folderblog/local';
+ * const blog = createLocalClient({ dir: './dist', mapPost: toPost });
+ * blog.posts.list() // Post[]
+ * ```
+ */
+declare function toPost(p: ProcessedPost): Post;
+
+/**
+ * FolderBlogLocal — local client that reads build output with search, similarity, and caching.
+ *
+ * @example
+ * ```ts
+ * import { createLocalClient } from 'folderblog/local';
+ *
+ * const blog = createLocalClient({ dir: './dist' });
+ * const posts = blog.posts.list();
+ * const results = blog.search('typescript');
+ * const similar = blog.similar('my-post-slug', 5);
+ * const related = blog.related('my-post-slug', 5);
+ * const autocomplete = blog.searchAutocomplete('type');
+ * ```
+ */
+
+/**
+ * Create a local client that reads from build output.
+ *
+ * @example
+ * ```ts
+ * const blog = createLocalClient({ dir: './dist' });
+ * const posts = blog.posts.list();
+ * ```
+ */
+declare function createLocalClient<TPost = ProcessedPost>(options: FolderBlogLocalOptions<TPost>): FolderBlogLocalClient<TPost>;
+
+export { type AutocompleteResult, type BlogStats, type CategoryCount, type FolderBlogLocalClient, type FolderBlogLocalOptions, IssueIndex, type Post, type PostFrontmatter, type PostTocItem, type RelatedResult, type SearchOptions, type SearchResult, type SimilarResult, type TagCount, type WhereQuery, createLocalClient, extractSection, isDraft, isHidden, isPublished, isScheduled, toPost };