@cullit/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cullit (Matt)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,306 @@
+type AIProvider = 'anthropic' | 'openai' | 'gemini' | 'ollama' | 'openclaw' | 'none';
+type Audience = 'developer' | 'end-user' | 'executive';
+type Tone = 'professional' | 'casual' | 'terse';
+type OutputFormat = 'markdown' | 'html' | 'json';
+type PublisherType = 'stdout' | 'github-release' | 'slack' | 'discord' | 'file';
+type EnrichmentType = 'jira' | 'linear';
+interface AIConfig {
+    provider: AIProvider;
+    model?: string;
+    apiKey?: string;
+    audience: Audience;
+    tone: Tone;
+    categories: string[];
+    maxTokens?: number;
+}
+interface SourceConfig {
+    type: 'local' | 'jira' | 'linear';
+    owner?: string;
+    repo?: string;
+    enrichment?: EnrichmentType[];
+}
+interface PublishTarget {
+    type: PublisherType;
+    channel?: string;
+    webhookUrl?: string;
+    path?: string;
+}
+interface JiraConfig {
+    domain: string;
+    email?: string;
+    apiToken?: string;
+}
+interface LinearConfig {
+    apiKey?: string;
+}
+interface OpenClawConfig {
+    baseUrl?: string;
+    token?: string;
+}
+interface CullConfig {
+    ai: AIConfig;
+    source: SourceConfig;
+    publish: PublishTarget[];
+    jira?: JiraConfig;
+    linear?: LinearConfig;
+    openclaw?: OpenClawConfig;
+}
+interface GitCommit {
+    hash: string;
+    shortHash: string;
+    author: string;
+    date: string;
+    message: string;
+    body?: string;
+    prNumber?: number;
+    issueKeys?: string[];
+}
+interface GitDiff {
+    from: string;
+    to: string;
+    commits: GitCommit[];
+    filesChanged?: number;
+}
+interface EnrichedTicket {
+    key: string;
+    title: string;
+    description?: string;
+    type?: string;
+    labels?: string[];
+    priority?: string;
+    status?: string;
+    source: EnrichmentType;
+}
+interface EnrichedContext {
+    diff: GitDiff;
+    tickets: EnrichedTicket[];
+}
+type ChangeCategory = 'features' | 'fixes' | 'breaking' | 'improvements' | 'chores' | 'other';
+interface ChangeEntry {
+    description: string;
+    category: ChangeCategory;
+    ticketKey?: string;
+    commits?: string[];
+}
+interface ReleaseNotes {
+    version: string;
+    date: string;
+    summary?: string;
+    changes: ChangeEntry[];
+    contributors?: string[];
+    metadata?: {
+        commitCount: number;
+        prCount: number;
+        ticketCount: number;
+        generatedBy: string;
+        generatedAt: string;
+    };
+}
+interface Collector {
+    collect(from: string, to: string): Promise<GitDiff>;
+}
+interface Enricher {
+    enrich(diff: GitDiff): Promise<EnrichedTicket[]>;
+}
+interface Generator {
+    generate(context: EnrichedContext, config: AIConfig): Promise<ReleaseNotes>;
+}
+interface Publisher {
+    publish(notes: ReleaseNotes, format: OutputFormat): Promise<void>;
+}
+interface PipelineResult {
+    notes: ReleaseNotes;
+    formatted: string;
+    publishedTo: string[];
+    duration: number;
+}
+
+declare const VERSION = "0.1.0";
+declare const DEFAULT_CATEGORIES: string[];
+declare const DEFAULT_MODELS: Record<string, string>;
+
+/**
+ * Collects git log data between two refs (tags, branches, or commit SHAs).
+ * Extracts commits, PR numbers, and issue keys from commit messages.
+ */
+declare class GitCollector implements Collector {
+    private cwd;
+    constructor(cwd?: string);
+    collect(from: string, to: string): Promise<GitDiff>;
+    private getLog;
+    private parseLog;
+    /**
+     * Extracts PR number from commit messages.
+     * Matches patterns like: (#123), Merge pull request #123, PR #123
+     */
+    private extractPRNumber;
+    /**
+     * Extracts issue keys from commit messages.
+     * Matches patterns like: PROJ-123, FIX-456, LIN-789
+     */
+    private extractIssueKeys;
+    private getFilesChanged;
+}
+/**
+ * Gets list of available tags, most recent first.
+ */
+declare function getRecentTags(cwd?: string, count?: number): string[];
+/**
+ * Gets the latest tag on current branch.
+ */
+declare function getLatestTag(cwd?: string): string | null;
+
+/**
+ * Collects release data directly from Jira (no git required).
+ * Queries completed issues by JQL (project, sprint, date range, etc.)
+ * and converts them into the GitDiff format for the pipeline.
+ *
+ * Usage:
+ *   --from "project = PROJ AND sprint = 'Sprint 42'"
+ *   --from "project = PROJ AND resolved >= '2025-03-01'"
+ *   --from "project = PROJ AND fixVersion = 'v2.0'"
+ */
+declare class JiraCollector implements Collector {
+    private config;
+    constructor(config: JiraConfig);
+    collect(from: string, to: string): Promise<GitDiff>;
+    private buildJQL;
+    private fetchIssues;
+}
+
+/**
+ * Collects release data directly from Linear (no git required).
+ * Queries completed issues by project, cycle, or team.
+ *
+ * Usage:
+ *   --from "team:ENG"              (completed issues from team ENG, last 30 days)
+ *   --from "project:Project Name"  (completed issues from a project)
+ *   --from "cycle:current"         (current cycle's completed issues)
+ *   --from "label:release-v2"      (issues with a specific label)
+ */
+declare class LinearCollector implements Collector {
+    private apiKey;
+    constructor(apiKey?: string);
+    collect(from: string, to: string): Promise<GitDiff>;
+    private parseFilter;
+    private fetchIssues;
+    private buildFilterClause;
+}
+
+/**
+ * Generates release notes using AI.
+ * Supports Anthropic, OpenAI, Gemini, Ollama, OpenClaw — BYOK.
+ */
+declare class AIGenerator implements Generator {
+    private openclawConfig?;
+    private timeoutMs;
+    constructor(openclawConfig?: OpenClawConfig, timeoutMs?: number);
+    private fetchWithTimeout;
+    generate(context: EnrichedContext, config: AIConfig): Promise<ReleaseNotes>;
+    private resolveApiKey;
+    private buildPrompt;
+    private callAnthropic;
+    private callOpenAI;
+    private callGemini;
+    private callOllama;
+    private callOpenClaw;
+    private parseResponse;
+}
+
+/**
+ * Template-based release notes generator — no AI required.
+ * Groups commits by conventional commit prefix and ticket type.
+ * Useful as a free demo, CI fallback, or air-gapped environments.
+ */
+declare class TemplateGenerator implements Generator {
+    generate(context: EnrichedContext, config: AIConfig): Promise<ReleaseNotes>;
+    private categorize;
+    private cleanMessage;
+    private isTrivial;
+    private deduplicateByTicket;
+    private buildSummary;
+}
+
+declare function formatNotes(notes: ReleaseNotes, format: OutputFormat): string;
+
+/**
+ * Outputs release notes to stdout (default).
+ */
+declare class StdoutPublisher implements Publisher {
+    publish(notes: ReleaseNotes, format: OutputFormat): Promise<void>;
+}
+/**
+ * Writes release notes to a file.
+ */
+declare class FilePublisher implements Publisher {
+    private path;
+    constructor(path: string);
+    publish(notes: ReleaseNotes, format: OutputFormat): Promise<void>;
+}
+/**
+ * Posts release notes to a Slack channel via webhook.
+ */
+declare class SlackPublisher implements Publisher {
+    private webhookUrl;
+    constructor(webhookUrl: string);
+    publish(notes: ReleaseNotes, _format: OutputFormat): Promise<void>;
+    private buildSlackMessage;
+}
+/**
+ * Posts release notes to Discord via webhook.
+ */
+declare class DiscordPublisher implements Publisher {
+    private webhookUrl;
+    constructor(webhookUrl: string);
+    publish(notes: ReleaseNotes, _format: OutputFormat): Promise<void>;
+    private buildDiscordMessage;
+}
+/**
+ * Creates or updates a GitHub Release via the GitHub API.
+ * Requires GITHUB_TOKEN env var (provided automatically in GitHub Actions).
+ */
+declare class GitHubReleasePublisher implements Publisher {
+    private token;
+    private owner;
+    private repo;
+    constructor();
+    publish(notes: ReleaseNotes, format: OutputFormat): Promise<void>;
+    private getRelease;
+    private createRelease;
+    private updateRelease;
+    private headers;
+}
+
+/**
+ * Enriches git diff with Jira ticket details.
+ * Extracts PROJ-123 style keys from commit messages and fetches from Jira REST API.
+ */
+declare class JiraEnricher implements Enricher {
+    private config;
+    constructor(config: JiraConfig);
+    enrich(diff: GitDiff): Promise<EnrichedTicket[]>;
+    private extractUniqueKeys;
+    private fetchTicket;
+}
+
+/**
+ * Enriches git diff with Linear issue details.
+ * Extracts issue identifiers from commit messages and branch names.
+ */
+declare class LinearEnricher implements Enricher {
+    private apiKey;
+    constructor(apiKey?: string);
+    enrich(diff: GitDiff): Promise<EnrichedTicket[]>;
+    private extractUniqueKeys;
+    private fetchIssue;
+}
+
+/**
+ * Main pipeline: Collect → Enrich → Generate → Format → Publish
+ */
+declare function runPipeline(from: string, to: string, config: CullConfig, options?: {
+    format?: OutputFormat;
+    dryRun?: boolean;
+}): Promise<PipelineResult>;
+
+export { type AIConfig, AIGenerator, type AIProvider, type Audience, type ChangeCategory, type ChangeEntry, type Collector, type CullConfig, DEFAULT_CATEGORIES, DEFAULT_MODELS, DiscordPublisher, type EnrichedContext, type EnrichedTicket, type Enricher, type EnrichmentType, FilePublisher, type Generator, GitCollector, type GitCommit, type GitDiff, GitHubReleasePublisher, JiraCollector, type JiraConfig, JiraEnricher, LinearCollector, type LinearConfig, LinearEnricher, type OpenClawConfig, type OutputFormat, type PipelineResult, type PublishTarget, type Publisher, type PublisherType, type ReleaseNotes, SlackPublisher, type SourceConfig, StdoutPublisher, TemplateGenerator, type Tone, VERSION, formatNotes, getLatestTag, getRecentTags, runPipeline };