@yuaone/core 0.1.0

package/dist/doc-intelligence.d.ts

@@ -0,0 +1,383 @@
+/**
+ * @module doc-intelligence
+ * @description Documentation Intelligence — analyzes code to generate, validate,
+ * and maintain documentation automatically.
+ *
+ * Features:
+ * 1. **JSDoc/TSDoc Generation** — parse function signatures, generate doc templates
+ * 2. **README Generation** — analyze project structure, generate sections
+ * 3. **Changelog Generation** — parse conventional commits, group by type
+ * 4. **API Documentation** — extract exports, generate API reference
+ * 5. **Documentation Quality Analysis** — coverage, freshness, completeness, grading
+ *
+ * Uses regex-based parsing (no AST libraries). Designed for the YUAN coding agent
+ * to automatically maintain documentation alongside code changes.
+ *
+ * @example
+ * ```typescript
+ * const di = new DocIntelligence({
+ *   projectPath: "/path/to/project",
+ *   srcDirs: ["src"],
+ *   templateStyle: "jsdoc",
+ * });
+ *
+ * // Analyze doc coverage
+ * const files = new Map<string, string>();
+ * files.set("src/index.ts", sourceCode);
+ * const coverage = di.analyzeCoverage(files);
+ * console.log(`Coverage: ${coverage.coveragePercent}% (Grade: ${coverage.grade})`);
+ *
+ * // Generate JSDoc for a function
+ * const jsdoc = di.generateJSDoc("function add(a: number, b: number): number { return a + b; }");
+ *
+ * // Generate changelog from commits
+ * const changelog = di.generateChangelog(commits);
+ * ```
+ */
+/** Documentation coverage analysis result. */
+export interface DocCoverage {
+    /** Total number of exported symbols */
+    totalExports: number;
+    /** Number of exports with JSDoc/TSDoc */
+    documentedExports: number;
+    /** Coverage percentage (0–100) */
+    coveragePercent: number;
+    /** Symbols missing documentation */
+    missing: DocMissing[];
+    /** Symbols with stale documentation */
+    stale: DocStale[];
+    /** Overall documentation grade */
+    grade: "A" | "B" | "C" | "D" | "F";
+}
+/** A symbol missing documentation. */
+export interface DocMissing {
+    /** Symbol name */
+    symbolName: string;
+    /** Symbol type (function, class, interface, etc.) */
+    symbolType: string;
+    /** File path where the symbol is defined */
+    filePath: string;
+    /** Line number (1-based) */
+    line: number;
+}
+/** A symbol with stale (outdated) documentation. */
+export interface DocStale {
+    /** Symbol name */
+    symbolName: string;
+    /** File path */
+    filePath: string;
+    /** Line number of the JSDoc comment */
+    docLine: number;
+    /** Description of what changed in the code */
+    lastCodeChange: string;
+}
+/** A generated documentation artifact. */
+export interface GeneratedDoc {
+    /** Type of documentation */
+    type: "jsdoc" | "readme" | "changelog" | "api-reference";
+    /** Generated content */
+    content: string;
+    /** Target file path */
+    targetFile: string;
+    /** Whether this is a new file (true) or update to existing (false) */
+    isNew: boolean;
+}
+/** A structured changelog entry. */
+export interface ChangelogEntry {
+    /** Version string (e.g., "1.2.0") */
+    version: string;
+    /** Date string (ISO format, e.g., "2026-03-09") */
+    date: string;
+    /** Grouped changes by type */
+    sections: {
+        breaking: string[];
+        features: string[];
+        fixes: string[];
+        refactors: string[];
+        docs: string[];
+        other: string[];
+    };
+    /** Recommended semver bump */
+    semverBump: "major" | "minor" | "patch";
+}
+/** Configuration for DocIntelligence. */
+export interface DocIntelligenceConfig {
+    /** Project root path */
+    projectPath: string;
+    /** Source directories to scan (default: ["src"]) */
+    srcDirs?: string[];
+    /** Include private/non-exported symbols (default: false) */
+    includePrivate?: boolean;
+    /** Documentation template style (default: "jsdoc") */
+    templateStyle?: "jsdoc" | "tsdoc";
+    /** Changelog format (default: "keepachangelog") */
+    changelogFormat?: "keepachangelog" | "conventional";
+}
+/** Project information for README generation. */
+export interface ProjectInfo {
+    /** Package name */
+    name: string;
+    /** Package description */
+    description: string;
+    /** Parsed package.json contents */
+    packageJson: Record<string, unknown>;
+    /** List of source file paths */
+    srcFiles: string[];
+    /** Whether the project has test files */
+    hasTests: boolean;
+    /** Whether the project has a CLI entry point */
+    hasCLI: boolean;
+}
+/** Information about an exported symbol. */
+export interface ExportInfo {
+    /** Symbol name */
+    name: string;
+    /** Symbol type */
+    type: "function" | "class" | "interface" | "type" | "enum" | "const";
+    /** File path */
+    filePath: string;
+    /** Line number (1-based) */
+    line: number;
+    /** Full signature */
+    signature: string;
+    /** Whether the symbol has JSDoc */
+    hasDoc: boolean;
+    /** Existing JSDoc content, if any */
+    docContent?: string;
+}
+/** Parsed git commit information. */
+export interface CommitInfo {
+    /** Commit hash */
+    hash: string;
+    /** Commit message */
+    message: string;
+    /** Author name */
+    author: string;
+    /** Date string */
+    date: string;
+    /** Changed file paths */
+    files: string[];
+}
+/** Parsed conventional commit message. */
+export interface ParsedCommit {
+    /** Commit type (feat, fix, etc.) */
+    type: string;
+    /** Scope (optional) */
+    scope?: string;
+    /** Commit description */
+    description: string;
+    /** Whether this is a breaking change */
+    breaking: boolean;
+    /** Commit body (optional) */
+    body?: string;
+}
+/**
+ * DocIntelligence — analyzes code to generate, validate, and maintain
+ * documentation automatically.
+ *
+ * Provides:
+ * - Coverage analysis (% of exports with docs, grading A–F)
+ * - JSDoc/TSDoc generation from function signatures
+ * - README generation from project structure
+ * - Changelog generation from conventional commits
+ * - API reference generation from exported symbols
+ * - Staleness detection (code changed but docs did not)
+ */
+export declare class DocIntelligence {
+    private readonly config;
+    /**
+     * Create a new DocIntelligence instance.
+     *
+     * @param config - Configuration options
+     */
+    constructor(config: DocIntelligenceConfig);
+    /**
+     * Analyze documentation coverage across all provided files.
+     *
+     * Scans each file for exported symbols and checks whether they have
+     * JSDoc comments. Returns coverage stats and a grade (A–F).
+     *
+     * @param files - Map of file path to file content
+     * @returns Documentation coverage analysis
+     */
+    analyzeCoverage(files: Map<string, string>): DocCoverage;
+    /**
+     * Find undocumented exported symbols in a single file.
+     *
+     * @param content - File content
+     * @param filePath - File path (for reporting)
+     * @returns List of missing documentation entries
+     */
+    findUndocumented(content: string, filePath: string): DocMissing[];
+    /**
+     * Detect stale documentation in a file.
+     *
+     * Checks for common staleness indicators:
+     * - @param tags that don't match actual parameters
+     * - @returns tag present but function returns void
+     * - @deprecated tag on active code
+     * - JSDoc description mentions types/names that no longer exist
+     *
+     * @param content - File content
+     * @param filePath - File path (for reporting)
+     * @param gitLog - Optional git log output for change detection
+     * @returns List of stale documentation entries
+     */
+    detectStaleDoc(content: string, filePath: string, gitLog?: string): DocStale[];
+    /**
+     * Generate a JSDoc comment for a function/method code snippet.
+     *
+     * Parses the function signature and produces a template with
+     * @param, @returns, @throws, and @example tags.
+     *
+     * @param functionCode - The function source code
+     * @param context - Optional surrounding context for better descriptions
+     * @returns Generated JSDoc string
+     */
+    generateJSDoc(functionCode: string, context?: string): string;
+    /**
+     * Generate a README document from project information.
+     *
+     * Creates sections: Overview, Installation, Usage, API Reference,
+     * Configuration, and License.
+     *
+     * @param projectInfo - Project metadata and structure
+     * @returns Generated README document
+     */
+    generateReadme(projectInfo: ProjectInfo): GeneratedDoc;
+    /**
+     * Generate a changelog entry from a list of commits.
+     *
+     * Parses conventional commit messages and groups them by type.
+     * Determines the recommended semver bump based on commit types.
+     *
+     * @param commits - List of commit information
+     * @returns Structured changelog entry
+     */
+    generateChangelog(commits: CommitInfo[]): ChangelogEntry;
+    /**
+     * Generate an API reference document from exported symbols.
+     *
+     * Creates a markdown document with sections for each export type
+     * (functions, classes, interfaces, types, enums, constants).
+     *
+     * @param exports - List of exported symbol information
+     * @returns Generated API reference document
+     */
+    generateAPIReference(exports: ExportInfo[]): GeneratedDoc;
+    /**
+     * Parse all exported symbols from a file's content.
+     *
+     * Uses regex patterns to detect functions, classes, interfaces,
+     * type aliases, enums, and const exports. Checks whether each
+     * symbol has a preceding JSDoc comment.
+     *
+     * @param content - File content
+     * @param filePath - File path (for reporting)
+     * @returns List of exported symbols
+     */
+    parseExports(content: string, filePath: string): ExportInfo[];
+    /**
+     * Parse a conventional commit message.
+     *
+     * Supports the format: `type(scope)!: description`
+     * where scope and `!` (breaking) are optional.
+     *
+     * @param message - Commit message (first line)
+     * @returns Parsed commit or null if not conventional format
+     */
+    parseConventionalCommit(message: string): ParsedCommit | null;
+    /**
+     * Grade documentation quality based on coverage metrics.
+     *
+     * Grading scale:
+     * - A: >= 90% coverage
+     * - B: >= 75% coverage
+     * - C: >= 60% coverage
+     * - D: >= 40% coverage
+     * - F: < 40% coverage
+     *
+     * Stale docs reduce the grade by one level per 10 stale entries.
+     *
+     * @param coverage - Documentation coverage data
+     * @returns Documentation grade
+     */
+    gradeDocumentation(coverage: DocCoverage): DocCoverage["grade"];
+    /**
+     * Execute a regex against content and invoke callback for each match.
+     * If includePrivate is false, only matches that start with `export` are included.
+     */
+    private extractWithRegex;
+    /**
+     * Parse a function/method signature from code.
+     */
+    private parseFunctionSignature;
+    /**
+     * Parse function parameters from a parameter string.
+     */
+    private parseParams;
+    /**
+     * Split parameter string respecting nested brackets/generics.
+     */
+    private splitParams;
+    /**
+     * Find a top-level character (not nested in brackets).
+     */
+    private findTopLevelChar;
+    /**
+     * Find all JSDoc blocks in content, returning their position and parsed tags.
+     */
+    private findAllJSDocBlocks;
+    /**
+     * Analyze a JSDoc comment block.
+     */
+    private analyzeJSDoc;
+    /**
+     * Infer a description from function name and context.
+     */
+    private inferDescription;
+    /**
+     * Convert camelCase/PascalCase to space-separated words.
+     */
+    private camelToWords;
+    /**
+     * Parse generic type parameters.
+     */
+    private parseGenericParams;
+    /**
+     * Check if function code might throw errors.
+     */
+    private mightThrow;
+    /**
+     * Generate an example function call.
+     */
+    private generateExampleCall;
+    /**
+     * Generate an example value for a parameter.
+     */
+    private generateExampleValue;
+    /**
+     * Generate a generic JSDoc for non-function symbols.
+     */
+    private generateGenericDoc;
+    /**
+     * Parse parameter names from a parameter string (simple extraction).
+     */
+    private parseParamNames;
+    /**
+     * Extract symbol name from a line of code.
+     */
+    private extractSymbolName;
+    /**
+     * Detect staleness using git log information.
+     */
+    private detectGitBasedStaleness;
+    /**
+     * Format a changelog entry as markdown text.
+     *
+     * @param entry - Changelog entry to format
+     * @returns Formatted markdown string
+     */
+    formatChangelog(entry: ChangelogEntry): string;
+}
+//# sourceMappingURL=doc-intelligence.d.ts.map

package/dist/doc-intelligence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-intelligence.d.ts","sourceRoot":"","sources":["../src/doc-intelligence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAMH,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kCAAkC;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,uCAAuC;IACvC,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,kCAAkC;IAClC,KAAK,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;CACpC;AAED,sCAAsC;AACtC,MAAM,WAAW,UAAU;IACzB,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,oDAAoD;AACpD,MAAM,WAAW,QAAQ;IACvB,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,eAAe,CAAC;IACzD,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,oCAAoC;AACpC,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,KAAK,EAAE,MAAM,EAAE,CAAC;KACjB,CAAC;IACF,8BAA8B;IAC9B,UAAU,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;CACzC;AAED,yCAAyC;AACzC,MAAM,WAAW,qBAAqB;IACpC,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,sDAAsD;IACtD,aAAa,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAClC,mDAAmD;IACnD,eAAe,CAAC,EAAE,gBAAgB,GAAG,cAAc,CAAC;CACrD;AAED,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,gCAAgC;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,yCAAyC;IACzC,QAAQ,EAAE,OAAO,CAAC;IAClB,gDAAgD;IAChD,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,4CAA4C;AAC5C,MAAM,WAAW,UAAU;IACzB,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB;IAClB,IAAI,EAAE,UAAU,GAAG,OAAO,GAAG,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACrE,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,MAAM,EAAE,OAAO,CAAC;IAChB,qCAAqC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qCAAqC;AACrC,MAAM,WAAW,UAAU;IACzB,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,QAAQ,EAAE,OAAO,CAAC;IAClB,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAgHD;;;;;;;;;;;GAWG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IAEzD;;;;OAIG;gBACS,MAAM,EAAE,qBAAqB;IAYzC;;;;;;;;OAQG;IACH,eAAe,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,WAAW;IA8CxD;;;;;;OAMG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE;IAYjE;;;;;;;;;;;;;OAaG;IACH,cAAc,CACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,GACd,QAAQ,EAAE;IAgFb;;;;;;;;;OASG;IACH,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM;IA4D7D;;;;;;;;OAQG;IACH,cAAc,CAAC,WAAW,EAAE,WAAW,GAAG,YAAY;IA+ItD;;;;;;;;OAQG;IACH,iBAAiB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,cAAc;IAmExD;;;;;;;;OAQG;IACH,oBAAoB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,YAAY;IAoFzD;;;;;;;;;;OAUG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE;IA4L7D;;;;;;;;OAQG;IACH,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAuB7D;;;;;;;;;;;;;;OAcG;IACH,kBAAkB,CAAC,QAAQ,EAAE,WAAW,GAAG,WAAW,CAAC,OAAO,CAAC;IAgB/D;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IA0BxB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAgD9B;;OAEG;IACH,OAAO,CAAC,WAAW;IAmDnB;;OAEG;IACH,OAAO,CAAC,WAAW;IA2BnB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAaxB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAiC1B;;OAEG;IACH,OAAO,CAAC,YAAY;IA+DpB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAwExB;;OAEG;IACH,OAAO,CAAC,YAAY;IAOpB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;OAEG;IACH,OAAO,CAAC,UAAU;IASlB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAU3B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAoB5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAwB1B;;OAEG;IACH,OAAO,CAAC,eAAe;IAkBvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA+C/B;;;;;OAKG;IACH,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM;CAiC/C"}