@bfra.me/doc-sync 0.1.0

package/lib/types.d.ts

@@ -0,0 +1,388 @@
+import { Result } from '@bfra.me/es/result';
+import { z } from 'zod';
+
+/**
+ * @bfra.me/doc-sync/types - Core type definitions for documentation synchronization
+ */
+
+/**
+ * Metadata extracted from a package.json file
+ */
+interface PackageInfo {
+    /** Package name from package.json */
+    readonly name: string;
+    /** Package version from package.json */
+    readonly version: string;
+    /** Package description from package.json */
+    readonly description?: string;
+    /** Keywords for categorization */
+    readonly keywords?: readonly string[];
+    /** Path to the package directory */
+    readonly packagePath: string;
+    /** Path to the package's source directory */
+    readonly srcPath: string;
+    /** Path to the package's README file if it exists */
+    readonly readmePath?: string;
+    /** Custom documentation config from package.json "docs" field */
+    readonly docsConfig?: DocConfigSource;
+}
+/**
+ * Source configuration for documentation, from package.json or docs.config.json
+ */
+interface DocConfigSource {
+    /** Custom title override for the documentation page */
+    readonly title?: string;
+    /** Custom description override */
+    readonly description?: string;
+    /** Sidebar configuration */
+    readonly sidebar?: {
+        /** Label shown in sidebar navigation */
+        readonly label?: string;
+        /** Sort order in sidebar */
+        readonly order?: number;
+        /** Whether to hide from sidebar */
+        readonly hidden?: boolean;
+    };
+    /** Sections to exclude from auto-generation */
+    readonly excludeSections?: readonly string[];
+    /** Custom frontmatter fields to include */
+    readonly frontmatter?: Record<string, unknown>;
+}
+/**
+ * Configuration for documentation generation
+ */
+interface DocConfig {
+    /** Root directory of the monorepo */
+    readonly rootDir: string;
+    /** Output directory for generated documentation */
+    readonly outputDir: string;
+    /** Glob patterns for packages to include */
+    readonly includePatterns: readonly string[];
+    /** Glob patterns for packages to exclude */
+    readonly excludePatterns?: readonly string[];
+    /** Whether to watch for changes */
+    readonly watch?: boolean;
+    /** Debounce delay in milliseconds for watch mode */
+    readonly debounceMs?: number;
+}
+/**
+ * Error types for parse operations
+ */
+type ParseErrorCode = 'INVALID_SYNTAX' | 'FILE_NOT_FOUND' | 'READ_ERROR' | 'MALFORMED_JSON' | 'UNSUPPORTED_FORMAT';
+/**
+ * Structured error for parse operations
+ */
+interface ParseError {
+    /** Error classification code */
+    readonly code: ParseErrorCode;
+    /** Human-readable error message */
+    readonly message: string;
+    /** File path that caused the error */
+    readonly filePath?: string;
+    /** Line number where error occurred (1-indexed) */
+    readonly line?: number;
+    /** Column number where error occurred (1-indexed) */
+    readonly column?: number;
+    /** Original error if wrapping */
+    readonly cause?: unknown;
+}
+/**
+ * Result type for parse operations
+ */
+type ParseResult<T> = Result<T, ParseError>;
+/**
+ * Error types for sync operations
+ */
+type SyncErrorCode = 'WRITE_ERROR' | 'VALIDATION_ERROR' | 'GENERATION_ERROR' | 'PACKAGE_NOT_FOUND' | 'CONFIG_ERROR';
+/**
+ * Structured error for sync operations
+ */
+interface SyncError {
+    /** Error classification code */
+    readonly code: SyncErrorCode;
+    /** Human-readable error message */
+    readonly message: string;
+    /** Package name that caused the error */
+    readonly packageName?: string;
+    /** File path that caused the error */
+    readonly filePath?: string;
+    /** Original error if wrapping */
+    readonly cause?: unknown;
+}
+/**
+ * Result type for sync operations
+ */
+type SyncResult<T> = Result<T, SyncError>;
+/**
+ * Information about a single sync operation
+ */
+interface SyncInfo {
+    /** Package name that was synced */
+    readonly packageName: string;
+    /** Output file path */
+    readonly outputPath: string;
+    /** Whether the file was created or updated */
+    readonly action: 'created' | 'updated' | 'unchanged';
+    /** Timestamp of the sync operation */
+    readonly timestamp: Date;
+}
+/**
+ * Summary of a complete sync run
+ */
+interface SyncSummary {
+    /** Total number of packages processed */
+    readonly totalPackages: number;
+    /** Number of successful syncs */
+    readonly successCount: number;
+    /** Number of failed syncs */
+    readonly failureCount: number;
+    /** Number of unchanged packages */
+    readonly unchangedCount: number;
+    /** Details of each sync operation */
+    readonly details: readonly SyncInfo[];
+    /** Errors encountered during sync */
+    readonly errors: readonly SyncError[];
+    /** Duration of the sync run in milliseconds */
+    readonly durationMs: number;
+}
+/**
+ * Extracted JSDoc information
+ */
+interface JSDocInfo {
+    /** Main description from JSDoc */
+    readonly description?: string;
+    /** @param tags with name and description */
+    readonly params?: readonly JSDocParam[];
+    /** @returns description */
+    readonly returns?: string;
+    /** @example code blocks */
+    readonly examples?: readonly string[];
+    /** @deprecated message if present */
+    readonly deprecated?: string;
+    /** @since version if present */
+    readonly since?: string;
+    /** @see references */
+    readonly see?: readonly string[];
+    /** Custom tags not in standard set */
+    readonly customTags?: readonly JSDocTag[];
+}
+/**
+ * A single JSDoc @param entry
+ */
+interface JSDocParam {
+    /** Parameter name */
+    readonly name: string;
+    /** Parameter type (from JSDoc or inferred) */
+    readonly type?: string;
+    /** Parameter description */
+    readonly description?: string;
+    /** Whether the parameter is optional */
+    readonly optional?: boolean;
+    /** Default value if specified */
+    readonly defaultValue?: string;
+}
+/**
+ * A custom JSDoc tag
+ */
+interface JSDocTag {
+    /** Tag name without @ symbol */
+    readonly name: string;
+    /** Tag value/content */
+    readonly value?: string;
+}
+/**
+ * Information about an exported function
+ */
+interface ExportedFunction {
+    /** Function name */
+    readonly name: string;
+    /** JSDoc documentation */
+    readonly jsdoc?: JSDocInfo;
+    /** Function signature as string */
+    readonly signature: string;
+    /** Whether it's async */
+    readonly isAsync: boolean;
+    /** Whether it's a generator */
+    readonly isGenerator: boolean;
+    /** Parameter information */
+    readonly parameters: readonly FunctionParameter[];
+    /** Return type as string */
+    readonly returnType: string;
+    /** Whether it's the default export */
+    readonly isDefault: boolean;
+}
+/**
+ * Function parameter information
+ */
+interface FunctionParameter {
+    /** Parameter name */
+    readonly name: string;
+    /** TypeScript type */
+    readonly type: string;
+    /** Whether optional */
+    readonly optional: boolean;
+    /** Default value if provided */
+    readonly defaultValue?: string;
+}
+/**
+ * Information about an exported type or interface
+ */
+interface ExportedType {
+    /** Type name */
+    readonly name: string;
+    /** JSDoc documentation */
+    readonly jsdoc?: JSDocInfo;
+    /** Full type definition as string */
+    readonly definition: string;
+    /** Kind of type declaration */
+    readonly kind: 'interface' | 'type' | 'enum' | 'class';
+    /** Whether it's the default export */
+    readonly isDefault: boolean;
+    /** Type parameters (generics) */
+    readonly typeParameters?: readonly string[];
+}
+/**
+ * Complete API surface extracted from a package
+ */
+interface PackageAPI {
+    /** Exported functions */
+    readonly functions: readonly ExportedFunction[];
+    /** Exported types/interfaces */
+    readonly types: readonly ExportedType[];
+    /** Re-exported modules */
+    readonly reExports: readonly ReExport[];
+}
+/**
+ * Information about a re-export statement
+ */
+interface ReExport {
+    /** Module path being re-exported from */
+    readonly from: string;
+    /** Named exports being re-exported, or '*' for all */
+    readonly exports: readonly string[] | '*';
+    /** Alias if renamed during re-export */
+    readonly alias?: string;
+}
+/**
+ * Parsed README content with sections
+ */
+interface ReadmeContent {
+    /** Main title (first H1) */
+    readonly title?: string;
+    /** Content before first heading */
+    readonly preamble?: string;
+    /** Structured sections by heading */
+    readonly sections: readonly ReadmeSection[];
+    /** Raw markdown content */
+    readonly raw: string;
+}
+/**
+ * A section in the README
+ */
+interface ReadmeSection {
+    /** Section heading text */
+    readonly heading: string;
+    /** Heading level (1-6) */
+    readonly level: number;
+    /** Section content (markdown) */
+    readonly content: string;
+    /** Nested subsections */
+    readonly children: readonly ReadmeSection[];
+}
+/**
+ * MDX frontmatter for Starlight
+ */
+interface MDXFrontmatter {
+    /** Page title */
+    readonly title: string;
+    /** Page description for SEO */
+    readonly description?: string;
+    /** Sidebar configuration */
+    readonly sidebar?: {
+        readonly label?: string;
+        readonly order?: number;
+        readonly hidden?: boolean;
+        readonly badge?: string | {
+            readonly text: string;
+            readonly variant?: 'note' | 'tip' | 'caution' | 'danger' | 'success' | 'default';
+        };
+    };
+    /** Table of contents configuration */
+    readonly tableOfContents?: boolean | {
+        readonly minHeadingLevel?: number;
+        readonly maxHeadingLevel?: number;
+    };
+    /** Template to use */
+    readonly template?: 'doc' | 'splash';
+    /** Hero configuration for splash template */
+    readonly hero?: {
+        readonly title?: string;
+        readonly tagline?: string;
+        readonly image?: {
+            readonly src: string;
+            readonly alt: string;
+        };
+        readonly actions?: readonly {
+            readonly text: string;
+            readonly link: string;
+            readonly icon?: string;
+            readonly variant?: 'primary' | 'secondary' | 'minimal';
+        }[];
+    };
+}
+/**
+ * Generated MDX document
+ */
+interface MDXDocument {
+    /** Frontmatter configuration */
+    readonly frontmatter: MDXFrontmatter;
+    /** Document body content */
+    readonly content: string;
+    /** Full rendered document */
+    readonly rendered: string;
+}
+/**
+ * Sentinel markers for content preservation
+ */
+declare const SENTINEL_MARKERS: {
+    readonly AUTO_START: "{/* AUTO-GENERATED-START */}";
+    readonly AUTO_END: "{/* AUTO-GENERATED-END */}";
+    readonly MANUAL_START: "{/* MANUAL-CONTENT-START */}";
+    readonly MANUAL_END: "{/* MANUAL-CONTENT-END */}";
+};
+/**
+ * File change event from watcher
+ */
+interface FileChangeEvent {
+    /** Type of change */
+    readonly type: 'add' | 'change' | 'unlink';
+    /** Absolute path to the changed file */
+    readonly path: string;
+    /** Package name if determinable */
+    readonly packageName?: string;
+    /** Timestamp of the change */
+    readonly timestamp: Date;
+}
+/**
+ * Options for the CLI
+ */
+interface CLIOptions {
+    /** Root directory to operate from */
+    readonly root?: string;
+    /** Specific packages to sync */
+    readonly packages?: readonly string[];
+    /** Run in watch mode */
+    readonly watch?: boolean;
+    /** Dry run without writing files */
+    readonly dryRun?: boolean;
+    /** Verbose logging */
+    readonly verbose?: boolean;
+    /** Quiet mode (minimal output) */
+    readonly quiet?: boolean;
+}
+/**
+ * Zod schema type helper for runtime validation
+ */
+type InferSchema<T extends z.ZodTypeAny> = z.infer<T>;
+
+export { type CLIOptions, type DocConfig, type DocConfigSource, type ExportedFunction, type ExportedType, type FileChangeEvent, type FunctionParameter, type InferSchema, type JSDocInfo, type JSDocParam, type JSDocTag, type MDXDocument, type MDXFrontmatter, type PackageAPI, type PackageInfo, type ParseError, type ParseErrorCode, type ParseResult, type ReExport, type ReadmeContent, type ReadmeSection, SENTINEL_MARKERS, type SyncError, type SyncErrorCode, type SyncInfo, type SyncResult, type SyncSummary };

package/lib/types.js

@@ -0,0 +1,7 @@
+import {
+  SENTINEL_MARKERS
+} from "./chunk-ROLA7SBB.js";
+export {
+  SENTINEL_MARKERS
+};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@bfra.me/doc-sync",
+  "version": "0.1.0",
+  "description": "Intelligent documentation synchronization engine for automatic Astro Starlight site updates",
+  "keywords": [
+    "astro",
+    "bfra.me",
+    "documentation",
+    "generator",
+    "jsdoc",
+    "mdx",
+    "starlight",
+    "sync",
+    "typescript",
+    "works"
+  ],
+  "homepage": "https://github.com/bfra-me/works/tree/main/packages/doc-sync#readme",
+  "bugs": "https://github.com/bfra-me/works/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bfra-me/works.git",
+    "directory": "packages/doc-sync"
+  },
+  "license": "MIT",
+  "author": "Marcus R. Brown <contact@bfra.me>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "source": "./src/index.ts",
+      "import": "./lib/index.js"
+    },
+    "./generators": {
+      "types": "./lib/generators/index.d.ts",
+      "source": "./src/generators/index.ts",
+      "import": "./lib/generators/index.js"
+    },
+    "./parsers": {
+      "types": "./lib/parsers/index.d.ts",
+      "source": "./src/parsers/index.ts",
+      "import": "./lib/parsers/index.js"
+    },
+    "./types": {
+      "types": "./lib/types.d.ts",
+      "source": "./src/types.ts",
+      "import": "./lib/types.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "bin": {
+    "doc-sync": "./lib/cli/index.js"
+  },
+  "files": [
+    "!**/*.map",
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "@clack/prompts": "0.11.0",
+    "cac": "6.7.14",
+    "consola": "3.4.2",
+    "escape-html": "^1.0.3",
+    "fast-glob": "3.3.3",
+    "remark-mdx": "3.1.1",
+    "remark-parse": "11.0.0",
+    "ts-morph": "26.0.0",
+    "unified": "11.0.5",
+    "zod": "4.1.13",
+    "@bfra.me/es": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/escape-html": "^1.0.4",
+    "chokidar": "5.0.0",
+    "memfs": "4.51.1",
+    "@bfra.me/works": "0.0.0-development"
+  },
+  "peerDependencies": {
+    "chokidar": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "chokidar": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli/index.ts",
+    "start": "node lib/cli/index.js",
+    "test": "vitest run",
+    "lint": "eslint",
+    "test:watch": "vitest"
+  }
+}

package/src/cli/commands/index.ts

@@ -0,0 +1,3 @@
+export {runSync} from './sync.js'
+export {runValidate} from './validate.js'
+export {runWatch} from './watch.js'

package/src/cli/commands/sync.ts

@@ -0,0 +1,146 @@
+import type {SyncError} from '../../types.js'
+import type {GlobalOptions, PackageSelectionOption} from '../types.js'
+import type {Logger} from '../ui.js'
+
+import path from 'node:path'
+import process from 'node:process'
+
+import {createPackageScanner} from '../../orchestrator/package-scanner.js'
+import {createSyncOrchestrator} from '../../orchestrator/sync-orchestrator.js'
+import {
+  createLogger,
+  createProgressCallback,
+  createSpinner,
+  formatDuration,
+  formatPackageList,
+  handleCancel,
+  selectPackages,
+  showCancel,
+  showIntro,
+  showOutro,
+} from '../ui.js'
+
+export async function runSync(packages: string[], options: GlobalOptions): Promise<void> {
+  const logger = createLogger(options)
+  const rootDir = path.resolve(options.root)
+  const outputDir = path.join(rootDir, 'docs', 'src', 'content', 'docs', 'packages')
+
+  if (options.quiet !== true) {
+    showIntro('📚 doc-sync')
+  }
+
+  let selectedPackages: readonly string[] = packages
+
+  if (options.interactive === true && packages.length === 0) {
+    const scanner = createPackageScanner({
+      rootDir,
+      parseSourceFiles: false,
+      parseReadme: false,
+    })
+
+    const scanResult = await scanner.scan()
+    const availablePackages: PackageSelectionOption[] = scanResult.packages.map(pkg => ({
+      value: pkg.info.name,
+      label: pkg.info.name,
+      hint: pkg.needsDocumentation ? 'needs docs' : 'up to date',
+    }))
+
+    const selection = await selectPackages(availablePackages)
+
+    if (handleCancel(selection)) {
+      showCancel()
+      process.exit(0)
+    }
+
+    selectedPackages = selection
+  }
+
+  const spinner = options.quiet === true ? undefined : createSpinner()
+  const errors: SyncError[] = []
+
+  const orchestrator = createSyncOrchestrator({
+    config: {
+      rootDir,
+      outputDir,
+      includePatterns: ['packages/*'],
+      excludePatterns: [],
+    },
+    dryRun: options.dryRun ?? false,
+    verbose: options.verbose ?? false,
+    onProgress: createProgressCallback(options),
+    onError(error: SyncError): void {
+      errors.push(error)
+      logger.error(`Error syncing ${error.packageName ?? 'unknown'}: ${error.message}`)
+    },
+  })
+
+  const actionPrefix = options.dryRun === true ? '[DRY RUN] ' : ''
+
+  if (selectedPackages.length > 0) {
+    spinner?.start(`${actionPrefix}Syncing ${formatPackageList(selectedPackages)}...`)
+    const result = await orchestrator.syncPackages(selectedPackages)
+    spinner?.stop(`${actionPrefix}Sync complete`)
+
+    reportSyncResult(result, logger, options)
+  } else {
+    spinner?.start(`${actionPrefix}Syncing all packages...`)
+    const result = await orchestrator.syncAll()
+    spinner?.stop(`${actionPrefix}Sync complete`)
+
+    reportSyncResult(result, logger, options)
+  }
+
+  if (errors.length > 0) {
+    if (options.quiet !== true) {
+      showOutro(`⚠️  Completed with ${errors.length} error${errors.length === 1 ? '' : 's'}`)
+    }
+    process.exit(1)
+  }
+
+  if (options.quiet !== true) {
+    showOutro('✨ Documentation sync complete!')
+  }
+}
+
+interface SyncResult {
+  readonly totalPackages: number
+  readonly successCount: number
+  readonly failureCount: number
+  readonly unchangedCount: number
+  readonly durationMs: number
+  readonly details: readonly {
+    readonly packageName: string
+    readonly action: 'created' | 'updated' | 'unchanged'
+    readonly outputPath: string
+  }[]
+}
+
+function reportSyncResult(result: SyncResult, logger: Logger, options: GlobalOptions): void {
+  const {successCount, failureCount, unchangedCount, durationMs, details} = result
+
+  if (options.verbose === true) {
+    for (const detail of details) {
+      switch (detail.action) {
+        case 'created':
+          logger.success(`Created: ${detail.packageName}`)
+          break
+        case 'updated':
+          logger.info(`Updated: ${detail.packageName}`)
+          break
+        case 'unchanged':
+          logger.debug(`Unchanged: ${detail.packageName}`)
+          break
+      }
+    }
+  }
+
+  const summary = [
+    successCount > 0 ? `${successCount} synced` : null,
+    unchangedCount > 0 ? `${unchangedCount} unchanged` : null,
+    failureCount > 0 ? `${failureCount} failed` : null,
+  ]
+    .filter(Boolean)
+    .join(', ')
+
+  logger.info(`${summary} in ${formatDuration(durationMs)}`)
+}