@mdfriday/foundry 26.4.20 → 26.5.1

package/dist/types/internal/domain/site/valueobject/menu.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Menu - A single menu item with hierarchical support
+ * Simplified structure focusing on essential properties
+ */
 export declare class Menu {
     private readonly _title;
     private readonly _url;
@@ -11,20 +15,50 @@ export declare class Menu {
         weight?: number;
         identifier?: string;
     });
+    /**
+     * Get menu entry title
+     */
     title(): string;
     get Title(): string;
+    /**
+     * Get menu entry URL
+     */
     url(): string;
     get URL(): string;
+    /**
+     * Get child menu entries
+     */
     children(): Menu[];
     get Children(): Menu[];
+    /**
+     * Get menu entry weight for sorting
+     */
     weight(): number;
+    /**
+     * Get menu entry identifier
+     */
     identifier(): string;
+    /**
+     * Check if this menu entry has children
+     */
     hasChildren(): boolean;
     get HasChildren(): boolean;
+    /**
+     * Add a child menu entry
+     */
     addChild(child: Menu): Menu;
+    /**
+     * Convert to JSON representation
+     */
     toJSON(): any;
+    /**
+     * Create a new Menu with updated children
+     */
     withChildren(children: Menu[]): Menu;
 }
+/**
+ * Menus - Simplified menu structure with nav and footer
+ */
 export declare class Menus {
     private readonly _nav;
     private readonly _footer;
@@ -32,11 +66,26 @@ export declare class Menus {
         nav?: Menu[];
         footer?: Menu[];
     });
+    /**
+     * Get navigation menu
+     */
     nav(): Menu[];
     get Nav(): Menu[];
+    /**
+     * Get footer menu
+     */
     footer(): Menu[];
     get Footer(): Menu[];
+    /**
+     * Sort menus by weight and then by title
+     */
     private sortMenus;
+    /**
+     * Convert to plain object for serialization
+     */
     toJSON(): Record<string, any[]>;
 }
+/**
+ * Create empty menus instance
+ */
 export declare function newEmptyMenus(): Menus;

package/dist/types/internal/domain/site/valueobject/organization.d.ts

@@ -10,19 +10,56 @@ export declare class Organization {
     private readonly _vision;
     private _homeOrganization;
     constructor();
+    /**
+     * Get organization name
+     */
     name(): string;
+    /**
+     * Get organization description
+     */
     description(): string;
+    /**
+     * Get organization website
+     */
     website(): string;
+    /**
+     * Set the home organization from content
+     */
     organization(organization: ContentOrganization | undefined): Organization;
+    /**
+     * Get organization name with fallback to home organization
+     */
     get Name(): string;
+    /**
+     * Get organization description with fallback to home organization
+     */
     get Description(): string;
+    /**
+     * Get organization website with fallback to home organization
+     */
     get Website(): string;
+    /**
+     * Get organization vision from home organization
+     */
     get Vision(): string;
+    /**
+     * Get organization logo from home organization
+     */
     get Logo(): string;
+    /**
+     * Get organization contact from home organization
+     */
     get Address(): string;
     get Email(): string;
+    /**
+     * Get organization social from home organization
+     */
     get Social(): import("@internal/domain/content").Social | undefined;
     SocialById(id: string): string;
     get Socials(): SocialLink[];
 }
+/**
+ * Factory function to create new Organization
+ * TypeScript equivalent of NewOrganization function from Go
+ */
 export declare function newOrganization(): Organization;

package/dist/types/internal/domain/site/valueobject/path.d.ts

@@ -1,15 +1,65 @@
+/**
+ * Path utilities for wikilink resolution (Domain Layer)
+ * Based on Quartz path.ts and links.ts transformLink function
+ * Source: quartz-src/quartz/util/path.ts lines 224-257
+ *
+ * This module provides the core link transformation logic used by PageGraph.
+ */
 export type LinkStrategy = 'absolute' | 'relative' | 'shortest';
+/**
+ * Split anchor from path: "page#anchor" -> ["page", "#anchor"]
+ * From Quartz path.ts lines 176-183
+ */
 export declare function splitAnchor(link: string): [string, string];
+/**
+ * Simplify slug: remove index suffix, strip slashes
+ * From Quartz path.ts lines 90-93
+ */
 export declare function simplifySlug(fp: string): string;
+/**
+ * Slugify file path
+ * From Quartz path.ts lines 72-88
+ */
 export declare function slugifyFilePath(fp: string, excludeExt?: boolean): string;
+/**
+ * Transform internal link
+ * From Quartz path.ts lines 95-109
+ */
 export declare function transformInternalLink(link: string): string;
+/**
+ * Resolve /a/b/c to ../..
+ * From Quartz path.ts lines 156-169
+ */
 export declare function pathToRoot(slug: string): string;
+/**
+ * Resolve relative path from current to target
+ * From Quartz path.ts lines 171-174
+ */
 export declare function resolveRelative(current: string, target: string): string;
+/**
+ * Join path segments
+ * From Quartz path.ts lines 192-213
+ */
 export declare function joinSegments(...args: string[]): string;
 export interface TransformOptions {
     strategy: LinkStrategy;
     allSlugs: string[];
 }
+/**
+ * Transform link based on strategy (CORE FUNCTION - directly from Quartz)
+ * Source: quartz-src/quartz/util/path.ts lines 229-257
+ *
+ * This is the main link resolution function that PageGraph uses.
+ * It implements three strategies:
+ * - 'shortest': Use just the filename if unique (e.g., "page" matches "notes/page")
+ * - 'absolute': Use full path from vault root (e.g., "notes/page")
+ * - 'relative': Use relative path from current page
+ *
+ * @param src - Source page slug (e.g., "posts/my-post")
+ * @param target - Target wikilink (e.g., "another-page" or "notes/another-page")
+ * @param opts - Resolution options (strategy + all site slugs)
+ * @returns Resolved relative URL
+ */
 export declare function transformLink(src: string, target: string, opts: TransformOptions): string;
 export declare function isFolderPath(fplike: string): boolean;
 export declare function endsWith(s: string, suffix: string): boolean;

package/dist/types/internal/domain/site/valueobject/version.d.ts

@@ -1,7 +1,21 @@
+/**
+ * Compiler - TypeScript equivalent of Go's Compiler valueobject
+ * Represents compiler version information
+ */
 export declare class Compiler {
     private readonly ver;
     constructor(version: string);
+    /**
+     * Get compiler version
+     */
     version(): string;
+    /**
+     * Get environment (simplified implementation)
+     */
     environment(): string;
 }
+/**
+ * Factory function to create new Compiler
+ * TypeScript equivalent of NewVersion function from Go
+ */
 export declare function newVersion(version: string): Compiler;

package/dist/types/internal/domain/template/entity/executor.d.ts

@@ -1,12 +1,28 @@
 import { Template } from '@mdfriday/text-template';
 import { TemplateExecutor, TemplateError } from '../type';
+/**
+ * Executor entity for executing templates
+ * TypeScript version of Go's Executor struct
+ */
 export declare class Executor implements TemplateExecutor {
+    /**
+     * Execute template with data
+     */
     execute(tmpl: Template, data: any): Promise<string>;
+    /**
+     * Execute template with timeout
+     */
     executeWithTimeout(tmpl: Template, data: any, timeoutMs: number): Promise<string>;
+    /**
+     * Execute template safely with error handling
+     */
     executeSafely(tmpl: Template, data: any): Promise<{
         result: string | null;
         error: TemplateError | null;
     }>;
+    /**
+     * Execute multiple templates in batch
+     */
     executeBatch(templates: Array<{
         name: string;
         template: Template;
@@ -16,10 +32,16 @@ export declare class Executor implements TemplateExecutor {
         result: string | null;
         error: TemplateError | null;
     }>>;
+    /**
+     * Execute template with context and cancellation support
+     */
     executeWithContext(tmpl: Template, data: any, context: {
         signal?: AbortSignal;
         timeout?: number;
         metadata?: Record<string, any>;
     }): Promise<string>;
 }
+/**
+ * Create a new Executor instance
+ */
 export declare function newExecutor(): Executor;

package/dist/types/internal/domain/template/entity/lookup.d.ts

@@ -1,29 +1,84 @@
 import { Template } from '@mdfriday/text-template';
 import { TemplateLookup, TemplateNamespace, TemplateInfo, TemplateLookupFunc, TemplateFuncMap, RegularTemplateNamespaceInterface, PartialTemplateNamespaceInterface, ShortcodeTemplateNamespaceInterface } from '../type';
 import { BaseOf } from '../vo/baseof';
+/**
+ * Lookup entity for finding templates and managing dependencies
+ * TypeScript version of Go's Lookup struct
+ */
 export declare class Lookup implements TemplateLookup {
     private baseOf;
     private funcsv;
     constructor(baseOf?: BaseOf, funcMap?: TemplateFuncMap);
+    /**
+     * Find template with no dependencies (legacy method)
+     */
     findNoDependence(name: string, ns: TemplateNamespace): [Template | null, boolean, Error | null];
+    /**
+     * Find regular template with baseof dependency support
+     */
     findTemplate(name: string, templateNS: RegularTemplateNamespaceInterface): [Template | null, boolean, Error | null];
+    /**
+     * Find partial template (simple lookup, no dependencies)
+     */
     findPartial(name: string, partialNS: PartialTemplateNamespaceInterface): [Template | null, boolean, Error | null];
+    /**
+     * Find shortcode template (simplest lookup)
+     */
     findShortcode(name: string, shortcodeNS: ShortcodeTemplateNamespaceInterface): [Template | null, boolean, Error | null];
+    /**
+     * Find dependent template information
+     */
     findDependentInfo(name: string): [TemplateInfo | null, TemplateInfo | null, boolean];
+    /**
+     * Get function by name
+     */
     getFunc(name: string): any;
+    /**
+     * Set function
+     */
     setFunc(name: string, fn: any): void;
+    /**
+     * Set function map
+     */
     setFuncMap(funcMap: TemplateFuncMap): void;
+    /**
+     * Get function map
+     */
     getFuncMap(): TemplateFuncMap;
+    /**
+     * Create template lookup function for namespace
+     */
     newTemplateLookup(ns: TemplateNamespace): TemplateLookupFunc;
+    /**
+     * Get base template manager
+     */
     getBaseOf(): BaseOf;
+    /**
+     * Set base template manager
+     */
     setBaseOf(baseOf: BaseOf): void;
+    /**
+     * Check if template has dependencies
+     */
     hasDependencies(name: string): boolean;
+    /**
+     * Get all available functions
+     */
     getAllFunctions(): string[];
+    /**
+     * Clear all functions
+     */
     clearFunctions(): void;
+    /**
+     * Get lookup statistics
+     */
     getStats(): {
         functionCount: number;
         baseTemplateCount: number;
         dependentTemplateCount: number;
     };
 }
+/**
+ * Create a new Lookup instance
+ */
 export declare function newLookup(baseOf?: BaseOf, funcMap?: TemplateFuncMap): Lookup;

package/dist/types/internal/domain/template/entity/parser.d.ts

@@ -1,5 +1,9 @@
 import { Template } from '@mdfriday/text-template';
 import { TemplateParser, TemplateState, TemplateInfo, TemplateLookupFunc, TemplateFuncMap } from '../type';
+/**
+ * Parser entity for parsing templates
+ * TypeScript version of Go's Parser struct
+ */
 export declare class Parser implements TemplateParser {
     private prototypeText;
     private prototypeTextClone?;
@@ -7,16 +11,52 @@ export declare class Parser implements TemplateParser {
     private funcMap;
     private parseOverlapCache;
     constructor(funcMap?: TemplateFuncMap);
+    /**
+     * Mark parser as ready and create clone
+     */
     markReady(): Promise<void>;
+    /**
+     * Parse template info into template state
+     */
     parse(info: TemplateInfo): Promise<TemplateState>;
+    /**
+     * Parse template with lock (for thread safety)
+     */
     parseWithLock(name: string, tpl: string): Promise<Template>;
+    /**
+     * Parse template with overlay and base template
+     */
     parseOverlap(overlay: TemplateInfo, base: TemplateInfo, lookup: TemplateLookupFunc): Promise<[TemplateState | null, boolean, Error | null]>;
+    /**
+     * Apply base template to overlay
+     */
     private applyBaseTemplate;
+    /**
+     * Get template dependencies using syntax tree traversal (与Go版本一致的遍历方法)
+     */
     private getDependencies;
+    /**
+     * Set function map
+     */
     setFuncMap(funcMap: TemplateFuncMap): void;
+    /**
+     * Get function map
+     */
     getFuncMap(): TemplateFuncMap;
+    /**
+     * Parse multiple templates
+     */
     parseMultiple(templates: TemplateInfo[]): Promise<TemplateState[]>;
+    /**
+     * Clear the parse overlap cache
+     */
     clearCache(): void;
+    /**
+     * Get cache statistics
+     */
     getCacheStats(): import("@pkg/cahce/cache").CacheStats;
 }
+/**
+ * Create a new Parser instance
+ */
 export declare function newParser(funcMap?: TemplateFuncMap): Parser;

package/dist/types/internal/domain/template/entity/template.d.ts

@@ -4,6 +4,10 @@ import { Executor } from './executor';
 import { Parser } from './parser';
 import { Lookup } from './lookup';
 import { RegularTemplateNamespace, PartialTemplateNamespace, ShortcodeTemplateNamespace } from '../vo/namespace';
+/**
+ * Template entity - main template engine with separated template management
+ * TypeScript version of Go's Template struct
+ */
 export declare class TemplateEngine implements ITemplateEngine {
     private executor;
     private lookup;
@@ -13,37 +17,120 @@ export declare class TemplateEngine implements ITemplateEngine {
     private shortcodeNamespace;
     private fs;
     constructor(executor: Executor, lookup: Lookup, parser: Parser, templateNamespace: RegularTemplateNamespace, partialNamespace: PartialTemplateNamespace, shortcodeNamespace: ShortcodeTemplateNamespace, fs: TemplateFs);
+    /**
+     * Mark template engine as ready
+     */
     markReady(): Promise<void>;
+    /**
+     * Get regular template by name with baseof dependency support
+     */
     getTemplate(name: string): Promise<[Template | null, boolean, Error | null]>;
+    /**
+     * Get partial template by name (simple lookup)
+     */
     getPartial(name: string): Promise<[Template | null, boolean, Error | null]>;
+    /**
+     * Get shortcode template by name
+     */
     getShortcode(name: string): Promise<[Template | null, boolean, Error | null]>;
+    /**
+     * Get template by name (unified method that routes to appropriate namespace)
+     */
     get(name: string): Promise<[Template | null, boolean, Error | null]>;
+    /**
+     * Find first available template from a list of template names by priority
+     * Returns the first template found, its name, whether it was found, and any error
+     */
     findFirst(names: string[]): Promise<[Template | null, string | null, boolean, Error | null]>;
+    /**
+     * Check if a shortcode exists
+     * @param name - The shortcode name
+     * @returns true if the shortcode exists, false otherwise
+     */
     hasShortcode(name: string): boolean;
+    /**
+     * Get all available shortcode names
+     * @returns Array of shortcode names
+     */
     getShortcodeNames(): string[];
+    /**
+     * Get shortcode count
+     * @returns Number of loaded shortcodes
+     */
     getShortcodeCount(): number;
+    /**
+     * Load templates from file system (unified for all template types)
+     */
     loadTemplates(): Promise<void>;
+    /**
+     * Add template from file info (routes to appropriate namespace)
+     */
     private addTemplateFileInfo;
+    /**
+     * Add template to appropriate namespace based on type
+     */
     private addTemplate;
+    /**
+     * Execute template with data
+     */
     execute(templateName: string, data: any): Promise<string>;
     executeRaw(templateName: string, rawContent: string, data: any): Promise<string>;
+    /**
+     * Execute shortcode template with data
+     */
     executeShortcode(shortcodeName: string, data: any): Promise<string>;
+    /**
+     * Execute template safely
+     */
     executeSafely(templateName: string, data: any): Promise<{
         result: string | null;
         error: TemplateError | null;
     }>;
+    /**
+     * Execute shortcode safely
+     */
     executeShortcodeSafely(shortcodeName: string, data: any): Promise<{
         result: string | null;
         error: TemplateError | null;
     }>;
+    /**
+     * Check if template exists
+     */
     hasTemplate(name: string): Promise<boolean>;
+    /**
+     * Get all template names
+     */
     getTemplateNames(): string[];
+    /**
+     * Get all partial template names
+     */
     getPartialTemplateNames(): string[];
+    /**
+     * Get all template names from all namespaces
+     */
     getAllTemplateNames(): string[];
+    /**
+     * Get partial namespace (for internal use by partial function)
+     */
     getPartialNamespace(): PartialTemplateNamespace;
+    /**
+     * Get shortcode namespace (for internal use)
+     */
     getShortcodeNamespace(): ShortcodeTemplateNamespace;
+    /**
+     * Get template namespace (for internal use)
+     */
     getTemplateNamespace(): RegularTemplateNamespace;
+    /**
+     * Clear all templates including shortcodes
+     */
     clear(): void;
+    /**
+     * Get template by pattern
+     */
     getTemplatesByPattern(pattern: RegExp): string[];
 }
+/**
+ * Create a new TemplateEngine instance
+ */
 export declare function newTemplateEngine(executor: Executor, lookup: Lookup, parser: Parser, templateNamespace: RegularTemplateNamespace, partialNamespace: PartialTemplateNamespace, shortcodeNamespace: ShortcodeTemplateNamespace, fs: TemplateFs): TemplateEngine;

package/dist/types/internal/domain/template/factory/template.d.ts

@@ -1,11 +1,30 @@
 import { TemplateFactory, TemplateFs, TemplateFactoryConfig, TemplateFuncMap, CustomizedFunctions } from '../type';
 import { TemplateEngine } from '../entity/template';
 import { RegularTemplateNamespace, PartialTemplateNamespace, ShortcodeTemplateNamespace } from '../vo/namespace';
+/**
+ * Template factory implementation
+ * TypeScript version of Go's template factory
+ * Following Go's factory pattern with service injection
+ */
 export declare class Factory implements TemplateFactory {
+    /**
+     * Create template engine with file system (core functions only)
+     */
     create(fs: TemplateFs): Promise<TemplateEngine>;
+    /**
+     * Create template engine with configuration
+     */
     createWithConfig(fs: TemplateFs, config: TemplateFactoryConfig): Promise<TemplateEngine>;
+    /**
+     * Create template engine with services
+     * TypeScript equivalent of Go's New(fs, cfs) function
+     */
     createWithServices(fs: TemplateFs, services: CustomizedFunctions): Promise<TemplateEngine>;
 }
+/**
+ * Builder for constructing template engine with dependencies
+ * TypeScript equivalent of Go's builder pattern
+ */
 export declare class Builder {
     private funcMap;
     private services?;
@@ -16,16 +35,58 @@ export declare class Builder {
     private lookup?;
     private parser?;
     private executor?;
+    /**
+     * Set file system
+     */
     withFs(fs: TemplateFs): Builder;
+    /**
+     * Set namespaces
+     */
     withNamespaces(templateNamespace: RegularTemplateNamespace, partialNamespace: PartialTemplateNamespace, shortcodeNamespace: ShortcodeTemplateNamespace): Builder;
+    /**
+     * Set function map directly
+     */
     withFuncMap(funcMap: TemplateFuncMap): Builder;
+    /**
+     * Set services (will generate function map from services)
+     * TypeScript equivalent of Go's withCfs()
+     */
     withServices(services: CustomizedFunctions): Builder;
+    /**
+     * Build lookup component
+     * TypeScript equivalent of Go's buildLookup()
+     */
     buildLookup(): Builder;
+    /**
+     * Build parser component
+     * TypeScript equivalent of Go's buildParser()
+     */
     buildParser(): Builder;
+    /**
+     * Build executor component
+     * TypeScript equivalent of Go's buildExecutor()
+     */
     buildExecutor(): Builder;
+    /**
+     * Build final template engine
+     * TypeScript equivalent of Go's build()
+     */
     build(): Promise<TemplateEngine>;
 }
+/**
+ * Create a new template factory
+ */
 export declare function newTemplateFactory(): Factory;
+/**
+ * Create a new builder
+ */
 export declare function newBuilder(): Builder;
+/**
+ * Convenience function to create template engine with defaults
+ */
 export declare function createTemplateEngine(fs: TemplateFs, funcMap?: TemplateFuncMap): Promise<TemplateEngine>;
+/**
+ * Convenience function to create template engine with services
+ * TypeScript equivalent of Go's factory.New()
+ */
 export declare function createTemplateEngineWithServices(fs: TemplateFs, services: CustomizedFunctions): Promise<TemplateEngine>;