@mdfriday/foundry 26.4.19 → 26.5.1

package/dist/types/internal/domain/paths/type.d.ts

@@ -1,119 +1,239 @@
+/**
+ * Path processor interface - main entry point for path processing
+ */
 export interface PathProcessor {
     parse(component: string, path: string): Path;
     parseIdentity(component: string, path: string): StringIdentity;
     parseBaseAndBaseNameNoIdentifier(component: string, path: string): [string, string];
 }
+/**
+ * Path represents a parsed path with all its components and metadata
+ */
 export interface Path extends PathInfo, PathOperations, PathMetadata {
+    /**
+     * Get the unnormalized version of this path (preserves original case)
+     */
     unnormalized(): Path;
 }
+/**
+ * PathInfo provides basic path information access
+ */
 export interface PathInfo {
+    /** Component returns the component for this path (e.g. "content") */
     component(): string;
+    /** Path returns the full path */
     path(): string;
+    /** Name returns the last element of path */
     name(): string;
+    /** NameNoExt returns the last element of path without any extension */
     nameNoExt(): string;
+    /** NameNoLang returns the last element of path without any language identifier */
     nameNoLang(): string;
+    /** Dir returns all but the last element of path, typically the path's directory */
     dir(): string;
+    /** Ext returns the file extension */
     ext(): string;
+    /** Lang returns the language identifier */
     lang(): string;
+    /** Section returns the first path element (section) */
     section(): string;
+    /** Sections returns all section path elements as an array */
     sections(): string[];
+    /** Container returns the base name of the container directory for this path */
     container(): string;
+    /** ContainerDir returns the container directory for this path */
     containerDir(): string;
 }
+/**
+ * PathOperations provides path manipulation operations
+ */
 export interface PathOperations {
+    /** Base returns the path without any identifiers for content files */
     base(): string;
+    /** BaseNoLeadingSlash returns the base path without the leading slash */
     baseNoLeadingSlash(): string;
+    /** BaseNameNoIdentifier returns the logical base name for a resource without any identifier */
     baseNameNoIdentifier(): string;
+    /** NameNoIdentifier returns the last element of path without any identifier */
     nameNoIdentifier(): string;
+    /** PathNoLang returns the Path but with any language identifier removed */
     pathNoLang(): string;
+    /** PathNoIdentifier returns the Path but with any identifier removed */
     pathNoIdentifier(): string;
+    /** PathRel returns the path relative to the given owner */
     pathRel(owner: Path): string;
+    /** BaseRel returns the base path relative to the given owner */
     baseRel(owner: Path): string;
+    /** TrimLeadingSlash returns a copy of the Path with the leading slash removed */
     trimLeadingSlash(): Path;
+    /** Identifier returns the identifier at the given index */
     identifier(index: number): string;
+    /** Identifiers returns all identifiers */
     identifiers(): string[];
 }
+/**
+ * PathMetadata provides metadata about the path
+ */
 export interface PathMetadata {
+    /** BundleType returns the bundle type */
     bundleType(): PathType;
+    /** IsContent returns true if the path is a content file */
     isContent(): boolean;
+    /** IsBundle returns true if this is a bundle */
     isBundle(): boolean;
+    /** IsBranchBundle returns true if this is a branch bundle */
     isBranchBundle(): boolean;
+    /** IsLeafBundle returns true if this is a leaf bundle */
     isLeafBundle(): boolean;
+    /** IsHTML returns true if the extension indicates HTML content */
     isHTML(): boolean;
+    /** Disabled returns true if the path is disabled */
     disabled(): boolean;
+    /** ForBundleType returns a copy of the path with the specified bundle type */
     forBundleType(type: PathType): Path;
 }
+/**
+ * StringIdentity represents a unique string identifier for a path
+ */
 export interface StringIdentity {
     identifierBase(): string;
 }
+/**
+ * PathType enum represents different types of paths
+ */
 export declare enum PathType {
+    /** A generic resource, e.g. a JSON file */
     File = 0,
+    /** A resource of a content type with front matter */
     ContentResource = 1,
+    /** E.g. /blog/my-post.md */
     ContentSingle = 2,
+    /** Leaf bundles, e.g. /blog/my-post/index.md */
     Leaf = 3,
+    /** Branch bundles, e.g. /blog/_index.md */
     Branch = 4
 }
+/**
+ * PathParser configuration interface
+ */
 export interface PathParserConfig {
+    /** Normalize paths to lowercase */
     normalize?: boolean;
+    /** Replace spaces with hyphens */
     replaceSpaces?: boolean;
+    /** Custom normalization function */
     normalizer?: (path: string) => string;
 }
+/**
+ * LowHigh represents a range with low and high positions
+ */
 export interface LowHigh {
     low: number;
     high: number;
 }
+/**
+ * PathComponents represents the parsed components of a path
+ */
 export interface PathComponents {
+    /** The original path string */
     original: string;
+    /** The normalized path string */
     normalized: string;
+    /** Position information for various path parts */
     positions: PathPositions;
+    /** Parsed identifiers (extensions, language codes, etc.) */
     identifiers: LowHigh[];
+    /** Bundle type if this is a content path */
     bundleType: PathType;
+    /** Whether this path is disabled */
     disabled: boolean;
+    /** Component type (content, static, layouts, etc.) */
     component?: string | undefined;
 }
+/**
+ * PathPositions holds position information for different parts of the path
+ */
 export interface PathPositions {
+    /** Container directory positions */
     containerLow: number;
     containerHigh: number;
+    /** Section position */
     sectionHigh: number;
+    /** Language identifier position */
     identifierLanguage: number;
 }
+/**
+ * PathNormalizer interface for custom path normalization strategies
+ */
 export interface PathNormalizer {
     normalize(path: string): string;
 }
+/**
+ * BasicPathNormalizer provides Hugo's basic normalization rules
+ */
 export interface BasicPathNormalizer extends PathNormalizer {
+    /** Normalize to lowercase */
     toLowerCase: boolean;
+    /** Replace spaces with hyphens */
     replaceSpaces: boolean;
 }
+/**
+ * PathValidator interface for validating paths
+ */
 export interface PathValidator {
     validate(path: string): ValidationResult;
 }
+/**
+ * ValidationResult represents the result of path validation
+ */
 export interface ValidationResult {
     valid: boolean;
     errors: string[];
     warnings: string[];
 }
+/**
+ * FileExtensionChecker interface for checking file extensions
+ */
 export interface FileExtensionChecker {
     isContentExt(ext: string): boolean;
     isHTML(ext: string): boolean;
     hasExt(path: string): boolean;
 }
+/**
+ * PathFactory interface for creating Path instances
+ */
 export interface PathFactory {
     create(component: string, path: string, config?: PathParserConfig): Path;
     createFromComponents(components: PathComponents): Path;
 }
+/**
+ * PathPool interface for object pooling to improve performance
+ */
 export interface PathPool {
     get(): Path;
     put(path: Path): void;
 }
+/**
+ * PathVisitor interface for visitor pattern on paths
+ */
 export interface PathVisitor<T> {
     visit(path: Path): T;
 }
+/**
+ * PathFilter interface for filtering paths
+ */
 export interface PathFilter {
     accept(path: Path): boolean;
 }
+/**
+ * PathTransformer interface for transforming paths
+ */
 export interface PathTransformer {
     transform(path: Path): Path;
 }
+/**
+ * Error types for path processing
+ */
 export declare class PathError extends Error {
     readonly path?: string | undefined;
     constructor(message: string, path?: string | undefined);
@@ -125,6 +245,9 @@ export declare class PathValidationError extends PathError {
     readonly validationErrors?: string[] | undefined;
     constructor(message: string, path?: string, validationErrors?: string[] | undefined);
 }
+/**
+ * Utility type for path processing results
+ */
 export type PathResult<T> = {
     success: true;
     data: T;
@@ -132,6 +255,9 @@ export type PathResult<T> = {
     success: false;
     error: PathError;
 };
+/**
+ * Constants for common file extensions and patterns
+ */
 export declare const PATH_CONSTANTS: {
     readonly CONTENT_EXTENSIONS: readonly [".md", ".markdown", ".mdown", ".mkd", ".mkdn", ".html", ".htm", ".xml"];
     readonly HTML_EXTENSIONS: readonly [".html", ".htm"];
@@ -139,7 +265,7 @@ export declare const PATH_CONSTANTS: {
     readonly PATH_SEPARATOR: "/";
     readonly EXTENSION_SEPARATOR: ".";
     readonly LANGUAGE_SEPARATOR: ".";
-    readonly SYSTEM_PATH_SEPARATOR: any;
+    readonly SYSTEM_PATH_SEPARATOR: "/" | "\\";
     readonly COMPONENT_FOLDER_CONTENT: "content";
     readonly COMPONENT_FOLDER_STATIC: "static";
     readonly COMPONENT_FOLDER_LAYOUTS: "layouts";
@@ -149,5 +275,11 @@ export declare const PATH_CONSTANTS: {
     readonly COMPONENT_FOLDER_I18N: "i18n";
     readonly normalizePath: (path: string) => string;
 };
+/**
+ * Helper function type for checking if a path has an extension
+ */
 export type HasExtFunction = (path: string) => boolean;
+/**
+ * Helper function type for normalizing path strings
+ */
 export type NormalizePathFunction = (path: string) => string;

package/dist/types/internal/domain/paths/vo/pathcomponents.d.ts

@@ -1,4 +1,8 @@
 import { PathComponents, PathPositions, LowHigh, PathType } from '../type';
+/**
+ * PathComponentsImpl implements the PathComponents interface
+ * Represents the parsed components of a path with position information
+ */
 export declare class PathComponentsImpl implements PathComponents {
     readonly original: string;
     readonly normalized: string;
@@ -8,46 +12,136 @@ export declare class PathComponentsImpl implements PathComponents {
     readonly disabled: boolean;
     readonly component?: string | undefined;
     constructor(original: string, normalized: string, positions: PathPositions, identifiers: LowHigh[], bundleType: PathType, disabled?: boolean, component?: string | undefined);
+    /**
+     * Create a new PathComponents with updated bundle type
+     */
     withBundleType(bundleType: PathType): PathComponents;
+    /**
+     * Create a new PathComponents with disabled flag
+     */
     withDisabled(disabled: boolean): PathComponents;
+    /**
+     * Check if this path has any identifiers
+     */
     hasIdentifiers(): boolean;
+    /**
+     * Get the first identifier (usually the file extension)
+     */
     firstIdentifier(): LowHigh | null;
+    /**
+     * Get the last identifier
+     */
     lastIdentifier(): LowHigh | null;
+    /**
+     * Get identifier at specific index
+     */
     getIdentifier(index: number): LowHigh | null;
+    /**
+     * Check if this is a content component
+     */
     isContentComponent(component: string): boolean;
+    /**
+     * Create a copy of PathComponents
+     */
     clone(): PathComponents;
+    /**
+     * Convert to string representation for debugging
+     */
     toString(): string;
 }
+/**
+ * PathPositionsImpl implements the PathPositions interface
+ */
 export declare class PathPositionsImpl implements PathPositions {
     containerLow: number;
     containerHigh: number;
     sectionHigh: number;
     identifierLanguage: number;
     constructor(containerLow?: number, containerHigh?: number, sectionHigh?: number, identifierLanguage?: number);
+    /**
+     * Reset all positions to default values
+     */
     reset(): void;
+    /**
+     * Check if container positions are set
+     */
     hasContainer(): boolean;
+    /**
+     * Check if section position is set
+     */
     hasSection(): boolean;
+    /**
+     * Check if language identifier position is set
+     */
     hasLanguageIdentifier(): boolean;
+    /**
+     * Create a copy of PathPositions
+     */
     clone(): PathPositions;
 }
+/**
+ * LowHighImpl implements the LowHigh interface
+ */
 export declare class LowHighImpl implements LowHigh {
     readonly low: number;
     readonly high: number;
     constructor(low: number, high: number);
+    /**
+     * Get the length of the range
+     */
     length(): number;
+    /**
+     * Check if the range is empty
+     */
     isEmpty(): boolean;
+    /**
+     * Check if a position is within this range
+     */
     contains(position: number): boolean;
+    /**
+     * Create a substring from the given string using this range
+     */
     substring(str: string): string;
+    /**
+     * Convert to string representation
+     */
     toString(): string;
 }
+/**
+ * Factory functions for creating path components
+ */
 export declare class PathComponentsFactory {
+    /**
+     * Create empty PathComponents
+     */
     static createEmpty(original?: string, bundleType?: PathType): PathComponents;
+    /**
+     * Create PathComponents from basic information
+     */
     static create(original: string, normalized?: string, bundleType?: PathType): PathComponents;
+    /**
+     * Create PathComponents with full information
+     */
     static createFull(original: string, normalized: string, positions: PathPositions, identifiers: LowHigh[], bundleType: PathType, disabled?: boolean): PathComponents;
 }
+/**
+ * Utility functions for working with path components
+ */
 export declare class PathComponentsUtils {
+    /**
+     * Extract string value using LowHigh range
+     */
     static extractString(str: string, range: LowHigh): string;
+    /**
+     * Extract multiple string values using LowHigh ranges
+     */
     static extractStrings(str: string, ranges: LowHigh[]): string[];
+    /**
+     * Find identifier index by position
+     */
     static findIdentifierIndex(identifiers: LowHigh[], position: number): number;
+    /**
+     * Merge two PathComponents (useful for inheritance scenarios)
+     */
     static merge(base: PathComponents, override: Partial<PathComponents>): PathComponents;
 }

package/dist/types/internal/domain/paths/vo/pathparser.d.ts

@@ -1,54 +1,131 @@
 import { PathProcessor, PathParserConfig, PathNormalizer, FileExtensionChecker, StringIdentity } from '../type';
 import { Path } from '../entity/path';
+/**
+ * PathProcessorImpl implements the PathProcessor interface
+ * Main entry point for path processing operations
+ */
 export declare class PathProcessorImpl implements PathProcessor {
     private normalizer;
     private extChecker;
     constructor(normalizer?: PathNormalizer, extChecker?: FileExtensionChecker);
+    /**
+     * Parse a path with component information
+     */
     parse(component: string, path: string): Path;
+    /**
+     * Parse and return only the identity
+     */
     parseIdentity(component: string, path: string): StringIdentity;
+    /**
+     * Parse and return base and base name without identifier
+     */
     parseBaseAndBaseNameNoIdentifier(component: string, path: string): [string, string];
+    /**
+     * Create PathComponents from path information
+     */
     private createPathComponents;
+    /**
+     * Detect bundle type based on filename and component
+     */
     private detectBundleType;
+    /**
+     * Check if file is a content file based on extension
+     */
     private isContentFile;
+    /**
+     * Get file extension without dot
+     */
     private getFileExtension;
+    /**
+     * Calculate positions for different path parts
+     * Exact replica of Go version - parse from right to left
+     */
     private calculatePathPositions;
+    /**
+     * Extract identifiers from filename (only file extensions)
+     * Treats only the last dot-separated part as the file extension
+     * This preserves dots in the base filename (e.g., "my.article.md" -> base="my.article", ext=".md")
+     */
     private extractIdentifiers;
 }
+/**
+ * PathParsingNormalizer implements normalization rules specifically for path parsing
+ * Uses per-space-to-dash conversion for maintaining exact Hugo path behavior
+ */
 export declare class PathParsingNormalizer implements PathNormalizer {
     readonly toLowerCase: boolean;
     readonly replaceSpaces: boolean;
     constructor(toLowerCase?: boolean, replaceSpaces?: boolean);
     normalize(path: string): string;
 }
+/**
+ * BasicPathNormalizer implements Hugo's basic normalization rules
+ */
 export declare class BasicPathNormalizer implements PathNormalizer {
     readonly toLowerCase: boolean;
     readonly replaceSpaces: boolean;
     constructor(toLowerCase?: boolean, replaceSpaces?: boolean);
     normalize(path: string): string;
 }
+/**
+ * DefaultFileExtensionChecker implements basic file extension checking
+ */
 export declare class DefaultFileExtensionChecker implements FileExtensionChecker {
     isContentExt(ext: string): boolean;
     isHTML(ext: string): boolean;
     hasExt(path: string): boolean;
 }
+/**
+ * ConfigurablePathNormalizer allows custom normalization rules
+ */
 export declare class ConfigurablePathNormalizer implements PathNormalizer {
     private rules;
     constructor(config?: PathParserConfig);
     normalize(path: string): string;
+    /**
+     * Add a custom normalization rule
+     */
     addRule(rule: (path: string) => string): void;
+    /**
+     * Clear all rules
+     */
     clearRules(): void;
 }
+/**
+ * Path parsing utilities
+ */
 export declare class PathParserUtils {
+    /**
+     * Parse a path string into basic components
+     */
     static parseBasic(path: string): {
         dir: string;
         name: string;
         ext: string;
         nameWithoutExt: string;
     };
+    /**
+     * Join path segments
+     */
     static join(...segments: string[]): string;
+    /**
+     * Normalize a path string using basic rules
+     */
     static normalizeBasic(path: string): string;
+    /**
+     * Check if a path represents a bundle
+     */
     static isBundle(path: string): boolean;
+    /**
+     * Extract section from path
+     */
     static extractSection(path: string): string;
+    /**
+     * Remove extension from path
+     */
     static removeExtension(path: string): string;
+    /**
+     * Check if path has extension
+     */
     static hasExtension(path: string): boolean;
 }

package/dist/types/internal/domain/publish/entity/publisher.d.ts

@@ -1,5 +1,10 @@
 import { Publisher, PublishType, AnyPublishConfig, PublishResult, PublishProgressCallback } from '../type';
 import { ManifestRepository } from '../repository/manifest-repository';
+/**
+ * Publisher Aggregator (聚合根)
+ *
+ * 使用策略模式，将具体发布逻辑委托给策略实现
+ */
 export declare class PublisherAggregator implements Publisher {
     private readonly projectId;
     private readonly projectPath;
@@ -7,18 +12,39 @@ export declare class PublisherAggregator implements Publisher {
     private readonly strategy;
     private readonly manifestRepo;
     constructor(projectId: string, projectPath: string, config: AnyPublishConfig, strategy: Publisher, manifestRepo: ManifestRepository);
+    /**
+     * Execute publish (委托给策略)
+     */
     publish(sourceDir: string, options?: {
         incremental?: boolean;
         force?: boolean;
         onProgress?: PublishProgressCallback;
     }): Promise<PublishResult>;
+    /**
+     * Test connection (委托给策略)
+     */
     testConnection(): Promise<{
         success: boolean;
         error?: string;
     }>;
+    /**
+     * Get config
+     */
     getConfig(): AnyPublishConfig;
+    /**
+     * Get type
+     */
     getType(): PublishType;
+    /**
+     * Get project ID
+     */
     getProjectId(): string;
+    /**
+     * Get project path
+     */
     getProjectPath(): string;
+    /**
+     * Get remote config for manifest
+     */
     private getRemoteConfig;
 }

package/dist/types/internal/domain/publish/factory/publisher-factory.d.ts

@@ -2,12 +2,29 @@ import { PublisherAggregator } from '../entity/publisher';
 import { AnyPublishConfig } from '../type';
 import { ManifestRepository } from '../repository/manifest-repository';
 import { HttpClient } from '../repository/http-client';
+/**
+ * Publisher Factory
+ *
+ * 根据配置创建对应的 Publisher 聚合根
+ */
 export declare class PublisherFactory {
     private readonly manifestRepo;
     private readonly httpClient;
     constructor(manifestRepo: ManifestRepository, httpClient: HttpClient);
+    /**
+     * Create Publisher Aggregator with appropriate strategy
+     */
     create(projectId: string, projectPath: string, config: AnyPublishConfig): PublisherAggregator;
+    /**
+     * Create FTP Publisher strategy
+     */
     private createFtpPublisher;
+    /**
+     * Create Netlify Publisher strategy
+     */
     private createNetlifyPublisher;
+    /**
+     * Create MDFriday Publisher strategy
+     */
     private createMDFridayPublisher;
 }

package/dist/types/internal/domain/publish/repository/http-client.d.ts

@@ -1,9 +1,30 @@
+/**
+ * HTTP Client Interface for Publish Domain
+ *
+ * 定义发布域需要的 HTTP 能力
+ * 由基础设施层实现
+ */
 export interface HttpClient {
+    /**
+     * POST JSON data
+     */
     postJSON(url: string, data: any, headers?: Record<string, string>): Promise<HttpResponse>;
+    /**
+     * POST multipart form data (for file uploads)
+     */
     postMultipart(url: string, formData: Record<string, any>, headers?: Record<string, string>): Promise<HttpResponse>;
+    /**
+     * PUT binary data
+     */
     putBinary(url: string, data: Buffer | Uint8Array, headers?: Record<string, string>): Promise<HttpResponse>;
+    /**
+     * GET request
+     */
     get(url: string, headers?: Record<string, string>): Promise<HttpResponse>;
 }
+/**
+ * HTTP Response
+ */
 export interface HttpResponse {
     status: number;
     ok: boolean;