@stoneforge/smithy 0.1.0

package/dist/services/docs-steward-service.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Docs Steward Service
+ *
+ * This service provides documentation verification and auto-fix capabilities
+ * for the orchestration system. The Docs Steward scans documentation for issues
+ * like broken file paths, stale links, and outdated references, then fixes
+ * low/medium complexity issues automatically.
+ *
+ * Key features:
+ * - Scan docs for file path references that don't exist
+ * - Verify internal markdown links resolve
+ * - Check documented exports match actual package exports
+ * - Verify CLI command documentation matches implementation
+ * - Check type field documentation matches TypeScript definitions
+ * - Verify API method documentation matches class definitions
+ * - Session lifecycle: worktree creation, commits, self-merge, cleanup
+ *
+ * @module
+ */
+/**
+ * Type of documentation issue detected
+ */
+export type DocIssueType = 'file_path' | 'internal_link' | 'export' | 'cli' | 'type_field' | 'api_method';
+/**
+ * Confidence level in the suggested fix
+ */
+export type FixConfidence = 'high' | 'medium' | 'low';
+/**
+ * Complexity level for triage
+ */
+export type IssueComplexity = 'low' | 'medium' | 'high';
+/**
+ * A documentation issue detected by the steward
+ */
+export interface DocIssue {
+    /** Type of issue */
+    readonly type: DocIssueType;
+    /** Documentation file containing the issue */
+    readonly file: string;
+    /** Line number where the issue was found */
+    readonly line: number;
+    /** Description of what's wrong */
+    readonly description: string;
+    /** The current value in the documentation */
+    readonly currentValue: string;
+    /** Suggested fix (if determinable) */
+    readonly suggestedFix?: string;
+    /** Confidence in the suggested fix */
+    readonly confidence: FixConfidence;
+    /** Surrounding text for context */
+    readonly context: string;
+    /** Complexity classification */
+    readonly complexity: IssueComplexity;
+}
+/**
+ * Result of a verification scan
+ */
+export interface VerificationResult {
+    /** Issues found during verification */
+    readonly issues: DocIssue[];
+    /** Number of files scanned */
+    readonly filesScanned: number;
+    /** Duration of scan in ms */
+    readonly durationMs: number;
+}
+/**
+ * Information about the session worktree
+ */
+export interface SessionWorktreeInfo {
+    /** Path to the worktree */
+    readonly path: string;
+    /** Branch name */
+    readonly branch: string;
+    /** Whether the worktree was newly created */
+    readonly created: boolean;
+}
+/**
+ * Result of a merge attempt
+ */
+export interface DocsMergeResult {
+    /** Whether merge succeeded */
+    readonly success: boolean;
+    /** Merge commit hash if successful */
+    readonly commitHash?: string;
+    /** Error message if failed */
+    readonly error?: string;
+    /** Whether there was a conflict */
+    readonly hasConflict: boolean;
+}
+/**
+ * Configuration for the Docs Steward service
+ */
+export interface DocsStewardConfig {
+    /** Workspace root directory */
+    readonly workspaceRoot: string;
+    /** Docs directory relative to workspace root (default: 'docs') */
+    readonly docsDir?: string;
+    /** Source directories to verify against (default: ['packages', 'apps']) */
+    readonly sourceDirs?: string[];
+    /** Whether to auto-push after merge (default: true) */
+    readonly autoPush?: boolean;
+    /** Target branch to merge into (default: auto-detect) */
+    readonly targetBranch?: string;
+}
+/**
+ * Docs Steward Service interface for documentation verification and auto-fix.
+ */
+export interface DocsStewardService {
+    /**
+     * Runs all verification checks and returns combined issues.
+     */
+    scanAll(): Promise<VerificationResult>;
+    /**
+     * Verifies file paths referenced in documentation exist.
+     */
+    verifyFilePaths(): Promise<DocIssue[]>;
+    /**
+     * Verifies internal markdown links resolve.
+     */
+    verifyInternalLinks(): Promise<DocIssue[]>;
+    /**
+     * Verifies documented exports exist in package index files.
+     */
+    verifyExports(): Promise<DocIssue[]>;
+    /**
+     * Verifies CLI command documentation matches implementation.
+     */
+    verifyCliCommands(): Promise<DocIssue[]>;
+    /**
+     * Verifies type field documentation matches TypeScript definitions.
+     */
+    verifyTypeFields(): Promise<DocIssue[]>;
+    /**
+     * Verifies API method documentation matches class definitions.
+     */
+    verifyApiMethods(): Promise<DocIssue[]>;
+    /**
+     * Creates a session worktree and branch for documentation updates.
+     *
+     * @param stewardName - Name of the steward agent
+     * @returns Worktree information
+     */
+    createSessionWorktree(stewardName: string): Promise<SessionWorktreeInfo>;
+    /**
+     * Commits a fix to the session worktree.
+     *
+     * @param message - Commit message
+     * @param files - Files to stage and commit
+     */
+    commitFix(message: string, files: string[]): Promise<void>;
+    /**
+     * Merges the session branch to the target branch and cleans up.
+     *
+     * @param branchName - The branch to merge
+     * @param commitMessage - Squash commit message
+     * @returns Merge result
+     */
+    mergeAndCleanup(branchName: string, commitMessage: string): Promise<DocsMergeResult>;
+    /**
+     * Cleans up the session worktree without merging.
+     *
+     * @param worktreePath - Path to the worktree to remove
+     * @param branchName - Branch to delete
+     */
+    cleanupSession(worktreePath: string, branchName: string): Promise<void>;
+}
+/**
+ * Implementation of the Docs Steward Service
+ */
+export declare class DocsStewardServiceImpl implements DocsStewardService {
+    private readonly config;
+    private targetBranch;
+    private sessionWorktreePath;
+    constructor(config: DocsStewardConfig);
+    scanAll(): Promise<VerificationResult>;
+    verifyFilePaths(): Promise<DocIssue[]>;
+    verifyInternalLinks(): Promise<DocIssue[]>;
+    verifyExports(): Promise<DocIssue[]>;
+    verifyCliCommands(): Promise<DocIssue[]>;
+    verifyTypeFields(): Promise<DocIssue[]>;
+    verifyApiMethods(): Promise<DocIssue[]>;
+    createSessionWorktree(stewardName: string): Promise<SessionWorktreeInfo>;
+    commitFix(message: string, files: string[]): Promise<void>;
+    mergeAndCleanup(branchName: string, commitMessage: string): Promise<DocsMergeResult>;
+    cleanupSession(worktreePath: string, branchName: string): Promise<void>;
+    private findMarkdownFiles;
+    private countMarkdownFiles;
+    private findSimilarFile;
+    private findIndexFiles;
+    private getCliCommands;
+    private anchorExistsInContent;
+    private getContext;
+    private getTargetBranch;
+}
+/**
+ * Creates a DocsStewardService instance
+ */
+export declare function createDocsStewardService(config: DocsStewardConfig): DocsStewardService;
+//# sourceMappingURL=docs-steward-service.d.ts.map

package/dist/services/docs-steward-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-steward-service.d.ts","sourceRoot":"","sources":["../../src/services/docs-steward-service.ts"],"names":[],"mappings":"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"}