mdzilla 0.1.0 → 0.2.1

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-//#region src/docs/nav.d.ts
+//#region src/nav.d.ts
 interface NavEntry {
   /** URL-friendly path segment (without numeric prefix) */
   slug: string;
@@ -20,38 +20,116 @@ interface NavEntry {
   [key: string]: unknown;
 }
 //#endregion
-//#region src/docs/sources/_base.d.ts
-declare abstract class DocsSource {
+//#region src/sources/_base.d.ts
+type WatchCallback = (event: {
+  path: string;
+}) => void;
+declare abstract class Source {
   abstract load(): Promise<{
     tree: NavEntry[];
     fileMap: Map<string, string>;
   }>;
   abstract readContent(filePath: string): Promise<string>;
+  /** Start watching for file changes. Override in sources that support it. */
+  watch(_callback: WatchCallback): void;
+  /** Stop watching. Override in sources that support it. */
+  unwatch(): void;
 }
 //#endregion
-//#region src/docs/sources/fs.d.ts
-declare class DocsSourceFS extends DocsSource {
+//#region src/collection.d.ts
+interface ContentMatch {
+  line: number;
+  text: string;
+  context: string[];
+}
+interface SearchResult {
+  flat: FlatEntry;
+  score: number;
+  titleMatch: boolean;
+  heading?: string;
+  contentMatches: ContentMatch[];
+}
+interface FlatEntry {
+  entry: NavEntry;
+  depth: number;
+  filePath?: string;
+}
+declare class Collection {
+  source: Source;
+  tree: NavEntry[];
+  flat: FlatEntry[];
+  private _fileMap;
+  private _contentCache;
+  private _changeListeners;
+  private _reloadTimer?;
+  constructor(source: Source);
+  load(): Promise<void>;
+  reload(): Promise<void>;
+  /** Start watching source for changes. Debounces, reloads collection, and notifies listeners. */
+  watch(): void;
+  /** Stop watching source. */
+  unwatch(): void;
+  /** Register a change listener. Returns unsubscribe function. */
+  onChange(listener: (path: string) => void): () => void;
+  /** Get raw file content for a flat entry (cached). */
+  getContent(entry: FlatEntry): Promise<string | undefined>;
+  /** Invalidate cached content for a specific file path. */
+  invalidate(filePath: string): void;
+  /** Fuzzy filter flat entries by query string (title and path only). */
+  filter(query: string): FlatEntry[];
+  /** Search flat entries by query string, including page contents. Yields scored results as found. */
+  search(query: string): AsyncIterable<SearchResult>;
+  /** Flat entries that are navigable pages (excludes directory stubs). */
+  get pages(): FlatEntry[];
+  /** Find a flat entry by path (exact or with trailing slash). */
+  findByPath(path: string): FlatEntry | undefined;
+  /**
+   * Resolve a page path to its content, trying:
+   * 1. Exact match in the navigation tree
+   * 2. Stripped common prefix (e.g., /docs/guide/... → /guide/...)
+   * 3. Direct source fetch (for HTTP sources with uncrawled paths)
+   */
+  resolvePage(path: string): Promise<{
+    entry?: FlatEntry;
+    raw?: string;
+  }>;
+  /** Suggest related pages for a query (fuzzy + keyword fallback). */
+  suggest(query: string, max?: number): FlatEntry[];
+}
+//#endregion
+//#region src/utils.d.ts
+/** Extract short text snippets around matching terms. */
+declare function extractSnippets(content: string, terms: string[], opts?: {
+  maxSnippets?: number;
+  radius?: number;
+}): string[];
+//#endregion
+//#region src/sources/fs.d.ts
+declare class FSSource extends Source {
   dir: string;
+  private _watcher?;
   constructor(dir: string);
   load(): Promise<{
     tree: NavEntry[];
     fileMap: Map<string, string>;
   }>;
   readContent(filePath: string): Promise<string>;
+  watch(callback: WatchCallback): void;
+  unwatch(): void;
 }
 //#endregion
-//#region src/docs/sources/git.d.ts
-interface DocsSourceGitOptions {
+//#region src/sources/git.d.ts
+interface GitSourceOptions {
   /** Authorization token for private repos */
   auth?: string;
   /** Subdirectory within the repo containing docs */
   subdir?: string;
 }
-declare class DocsSourceGit extends DocsSource {
+declare class GitSource extends Source {
   src: string;
-  options: DocsSourceGitOptions;
+  options: GitSourceOptions;
   private _fs?;
-  constructor(src: string, options?: DocsSourceGitOptions);
+  constructor(src: string, options?: GitSourceOptions);
   load(): Promise<{
     tree: NavEntry[];
     fileMap: Map<string, string>;
@@ -59,19 +137,19 @@ declare class DocsSourceGit extends DocsSource {
   readContent(filePath: string): Promise<string>;
 }
 //#endregion
-//#region src/docs/sources/http.d.ts
-interface DocsSourceHTTPOptions {
+//#region src/sources/http.d.ts
+interface HTTPSourceOptions {
   /** Additional headers to send with each request */
   headers?: Record<string, string>;
 }
-declare class DocsSourceHTTP extends DocsSource {
+declare class HTTPSource extends Source {
   url: string;
-  options: DocsSourceHTTPOptions;
+  options: HTTPSourceOptions;
   private _contentCache;
   private _tree;
   private _fileMap;
   private _npmPackage?;
-  constructor(url: string, options?: DocsSourceHTTPOptions);
+  constructor(url: string, options?: HTTPSourceOptions);
   load(): Promise<{
     tree: NavEntry[];
     fileMap: Map<string, string>;
@@ -86,16 +164,16 @@ declare class DocsSourceHTTP extends DocsSource {
   private _fetch;
 }
 //#endregion
-//#region src/docs/sources/npm.d.ts
-interface DocsSourceNpmOptions {
+//#region src/sources/npm.d.ts
+interface NpmSourceOptions {
   /** Subdirectory within the package containing docs */
   subdir?: string;
 }
-declare class DocsSourceNpm extends DocsSource {
+declare class NpmSource extends Source {
   src: string;
-  options: DocsSourceNpmOptions;
+  options: NpmSourceOptions;
   private _fs?;
-  constructor(src: string, options?: DocsSourceNpmOptions);
+  constructor(src: string, options?: NpmSourceOptions);
   load(): Promise<{
     tree: NavEntry[];
     fileMap: Map<string, string>;
@@ -103,46 +181,15 @@ declare class DocsSourceNpm extends DocsSource {
   readContent(filePath: string): Promise<string>;
 }
 //#endregion
-//#region src/docs/manager.d.ts
-interface FlatEntry {
-  entry: NavEntry;
-  depth: number;
-  filePath?: string;
-}
-declare class DocsManager {
-  source: DocsSource;
-  tree: NavEntry[];
-  flat: FlatEntry[];
-  private _fileMap;
-  private _contentCache;
-  constructor(source: DocsSource);
-  load(): Promise<void>;
-  reload(): Promise<void>;
-  /** Get raw file content for a flat entry (cached). */
-  getContent(entry: FlatEntry): Promise<string | undefined>;
-  /** Invalidate cached content for a specific file path. */
-  invalidate(filePath: string): void;
-  /** Fuzzy filter flat entries by query string. */
-  filter(query: string): FlatEntry[];
-  /** Flat entries that are navigable pages (excludes directory stubs). */
-  get pages(): FlatEntry[];
-  /** Find a flat entry by path (exact or with trailing slash). */
-  findByPath(path: string): FlatEntry | undefined;
-  /**
-   * Resolve a page path to its content, trying:
-   * 1. Exact match in the navigation tree
-   * 2. Stripped common prefix (e.g., /docs/guide/... → /guide/...)
-   * 3. Direct source fetch (for HTTP sources with uncrawled paths)
-   */
-  resolvePage(path: string): Promise<{
-    entry?: FlatEntry;
-    raw?: string;
-  }>;
-  /** Return indices of matching flat entries (case-insensitive substring). */
-  matchIndices(query: string): number[];
-}
+//#region src/source.d.ts
+/**
+ * Resolve a source string to the appropriate Source instance.
+ *
+ * Supports: local paths, `gh:owner/repo`, `npm:package`, `http(s)://...`
+ */
+declare function resolveSource(input: string): Source;
 //#endregion
-//#region src/docs/exporter.d.ts
+//#region src/exporter.d.ts
 interface ExportOptions {
   /** Custom filter callback. Return false to skip an entry. Default: skip stubs (page === false) */
   filter?: (entry: FlatEntry) => boolean;
@@ -153,15 +200,27 @@ interface ExportOptions {
   /** Title for the table of contents. Default: root entry title or "Table of Contents" */
   title?: string;
 }
+/**
+ * High-level export: resolve source, load, and export in one call.
+ *
+ * ```ts
+ * await exportSource("./docs", "./dist/docs");
+ * await exportSource("gh:unjs/h3", "./dist/h3-docs");
+ * await exportSource("npm:h3", "./dist/h3-docs", { plainText: true });
+ * await exportSource("https://h3.unjs.io", "./dist/h3-docs");
+ * ```
+ */
+declare function exportSource(input: string | Source, dir: string, options?: ExportOptions): Promise<Collection>;
 /**
  * Export documentation entries to a local filesystem directory as flat `.md` files.
  *
- * Each entry is written to `<dir>/<path>.md` (or `<dir>/<path>/index.md` for directory
- * index pages). Navigation order is preserved via `order` frontmatter in pages and
- * `.navigation.yml` files in directories.
+ * Each entry is written to `<dir>/<prefix>.<slug>.md` (or `<dir>/<prefix>.<slug>/index.md`
+ * for directory index pages). Navigation order is preserved via numeric prefixes on
+ * directories and files (e.g., `1.guide/`, `2.getting-started.md`) so the nav scanner
+ * can infer order without additional metadata files.
  *
  * A `README.md` table of contents is generated at the root of the output directory.
  */
-declare function exportDocsToFS(manager: DocsManager, dir: string, options?: ExportOptions): Promise<void>;
+declare function writeCollection(collection: Collection, dir: string, options?: ExportOptions): Promise<void>;
 //#endregion
-export { DocsManager, DocsSource, DocsSourceFS, DocsSourceGit, type DocsSourceGitOptions, DocsSourceHTTP, type DocsSourceHTTPOptions, DocsSourceNpm, type DocsSourceNpmOptions, type ExportOptions, type FlatEntry, type NavEntry, exportDocsToFS };
+export { Collection, type ExportOptions, FSSource, type FlatEntry, GitSource, type GitSourceOptions, HTTPSource, type HTTPSourceOptions, type NavEntry, NpmSource, type NpmSourceOptions, type SearchResult, Source, exportSource, extractSnippets, resolveSource, writeCollection };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { a as DocsSourceFS, i as DocsSourceGit, n as DocsSourceNpm, o as DocsSource, r as DocsSourceHTTP, s as DocsManager, t as exportDocsToFS } from "./_chunks/exporter.mjs";
-export { DocsManager, DocsSource, DocsSourceFS, DocsSourceGit, DocsSourceHTTP, DocsSourceNpm, exportDocsToFS };
+import { a as HTTPSource, c as Source, i as NpmSource, l as extractSnippets, n as writeCollection, o as GitSource, r as resolveSource, s as FSSource, t as exportSource, u as Collection } from "./_chunks/exporter.mjs";
+export { Collection, FSSource, GitSource, HTTPSource, NpmSource, Source, exportSource, extractSnippets, resolveSource, writeCollection };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdzilla",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "",
   "license": "MIT",
   "repository": "pi0/mdzilla",
@@ -31,22 +31,22 @@
   },
   "dependencies": {
     "@speed-highlight/core": "^1.2.15",
-    "giget": "^3.1.2",
+    "giget": "^3.2.0",
     "md4x": "^0.0.25",
     "srvx": "^0.11.13",
     "std-env": "^4.0.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
-    "@typescript/native-preview": "^7.0.0-dev.20260324.1",
-    "@vitest/coverage-v8": "^4.1.1",
+    "@typescript/native-preview": "^7.0.0-dev.20260327.2",
+    "@vitest/coverage-v8": "^4.1.2",
     "automd": "^0.4.3",
     "changelogen": "^0.6.2",
     "obuild": "^0.4.32",
-    "oxfmt": "^0.41.0",
-    "oxlint": "^1.56.0",
+    "oxfmt": "^0.42.0",
+    "oxlint": "^1.57.0",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.1"
+    "vitest": "^4.1.2"
   },
-  "packageManager": "pnpm@10.32.1"
+  "packageManager": "pnpm@10.33.0"
 }