@versu/core 0.4.0

package/README.md

@@ -0,0 +1,241 @@
+# @versu/core - Core Library
+
+The core business logic powering VERSU (Version Engine for Repo Semantic Evolution). This package is completely framework-agnostic and can be integrated into any TypeScript/JavaScript project, CI/CD system, or custom tooling.
+
+## Installation
+
+```bash
+npm install @versu/core
+```
+
+## Quick Start
+
+```typescript
+import { VersuRunner } from '@versu/core';
+
+const runner = new VersuRunner({
+  repoRoot: '/path/to/repository',
+  adapter: 'gradle', // Optional - auto-detected if not specified
+  dryRun: false,
+  pushTags: true,
+  pushChanges: true,
+  generateChangelog: true
+});
+
+const result = await runner.run();
+
+console.log(`Bumped: ${result.bumped}`);
+console.log(`Changed modules:`, result.changedModules);
+console.log(`Created tags:`, result.createdTags);
+```
+
+For detailed pre-release configuration and examples, see [PRERELEASE.md](./PRERELEASE.md).
+
+## VersuRunner API
+
+### Options
+
+```typescript
+interface RunnerOptions {
+  repoRoot: string;                    // Path to repository root
+  adapter?: string;                    // Language adapter (auto-detected if not specified)
+  dryRun?: boolean;                    // Preview changes without writing (default: false)
+  pushTags?: boolean;                  // Push version tags (default: true)
+  prereleaseMode?: boolean;            // Generate pre-release versions (default: false)
+  prereleaseId?: string;               // Pre-release identifier: alpha, beta, rc, etc. (default: 'alpha')
+  bumpUnchanged?: boolean;             // Bump modules with no changes in prerelease mode (default: false)
+  addBuildMetadata?: boolean;          // Add build metadata with short SHA (default: false)
+  timestampVersions?: boolean;         // Use timestamp-based prerelease IDs (default: false)
+  appendSnapshot?: boolean;            // Add -SNAPSHOT suffix (Gradle only) (default: false)
+  pushChanges?: boolean;               // Commit and push version changes (default: true)
+  generateChangelog?: boolean;         // Generate changelogs (default: true)
+}
+```
+
+### Result
+
+```typescript
+interface RunnerResult {
+  bumped: boolean;                     // Whether any version was updated
+  changedModules: Array<{
+    name: string;                      // Module name
+    from: string;                      // Previous version
+    to: string;                        // New version
+  }>;
+  createdTags: string[];              // Git tags that were created
+  changelogPaths: string[];           // Generated changelog file paths
+}
+```
+
+## Configuration
+
+VERSU core uses [cosmiconfig](https://github.com/davidtheclark/cosmiconfig) for configuration loading and [Zod](https://github.com/colinhacks/zod) for validation.
+
+### Supported Configuration Files
+
+1. `package.json` (in a `"versu"` property)
+2. `.versurc.json`
+3. `.versurc.yaml` / `.versurc.yml`
+4. `.versurc.js` or `versu.config.js` (JavaScript)
+
+### Configuration Example
+
+```json
+{
+  "defaultBump": "patch",
+  "commitTypes": {
+    "feat": "minor",
+    "fix": "patch",
+    "perf": "patch",
+    "docs": "ignore"
+  },
+  "dependencyRules": {
+    "onMajorOfDependency": "minor",
+    "onMinorOfDependency": "patch",
+    "onPatchOfDependency": "none"
+  }
+}
+```
+
+## Adapters
+
+### Gradle Adapter
+
+Built-in support for Gradle projects (Groovy & Kotlin DSL).
+
+**Features:**
+
+- Multi-module project detection
+- Version management through root `gradle.properties`
+- Dependency detection
+- Both Groovy and Kotlin DSL support
+
+**Version Format:**
+
+```properties
+# Root module
+version=1.0.0
+
+# Submodules
+core.version=2.1.0
+api.version=1.5.0
+```
+
+### Creating Custom Adapters
+
+To add support for new project types, implement a language adapter following the pattern in `src/adapters/gradle/`:
+
+```typescript
+import { 
+  AdapterIdentifier,
+  ModuleDetector,
+  VersionUpdateStrategy,
+  ModuleSystemFactory,
+  AdapterMetadata,
+  RawProjectInformation,
+  ProcessedModuleChange
+} from '@versu/core';
+
+// 1. Adapter identifier for auto-detection
+class MyAdapterIdentifier implements AdapterIdentifier {
+  readonly metadata: AdapterMetadata = {
+    id: 'my-adapter',
+    capabilities: { supportsSnapshots: false }
+  };
+
+  async accept(projectRoot: string): Promise<boolean> {
+    // Check for adapter-specific files
+    return await fileExists(path.join(projectRoot, 'my-build-file'));
+  }
+}
+
+// 2. Module detector for discovering project structure
+class MyModuleDetector implements ModuleDetector {
+  async detectModules(projectRoot: string): Promise<RawProjectInformation> {
+    // Discover and return modules and dependencies
+    return {
+      modules: [
+        { name: 'root', path: projectRoot, version: '1.0.0' },
+        { name: 'module-a', path: join(projectRoot, 'module-a'), version: '2.0.0' }
+      ],
+      dependencies: [
+        { from: 'module-a', to: 'root' }
+      ]
+    };
+  }
+}
+
+// 3. Version update strategy for applying changes
+class MyVersionUpdateStrategy implements VersionUpdateStrategy {
+  async applyVersionUpdates(
+    changes: ProcessedModuleChange[],
+    projectRoot: string
+  ): Promise<void> {
+    // Apply version changes to build files
+    for (const change of changes) {
+      // Update version in your project's format
+    }
+  }
+}
+
+// 4. Module system factory to tie it all together
+class MyModuleSystemFactory implements ModuleSystemFactory {
+  createDetector(): ModuleDetector {
+    return new MyModuleDetector();
+  }
+  
+  createVersionUpdateStrategy(): VersionUpdateStrategy {
+    return new MyVersionUpdateStrategy();
+  }
+}
+```
+
+Then register your adapter:
+
+1. Add to `src/factories/module-system-factory.ts` in the `createModuleSystemFactory` function
+2. Add to `src/services/adapter-identifier-registry.ts` in the registry initialization
+
+## Development
+
+### Building
+
+```bash
+# From monorepo root
+npm run build
+
+# Or from core package
+cd packages/core
+npm run build
+```
+
+### Testing
+
+```bash
+# From monorepo root
+npm test
+
+# Or from core package
+cd packages/core
+npm test
+npm run test:coverage
+```
+
+### Publishing
+
+```bash
+npm publish --workspace packages/core --access public
+```
+
+## Related Packages
+
+- **[@versu/cli](../cli)** - Command-line interface
+- **[@versu/action](../action)** - GitHub Actions integration
+
+## Requirements
+
+- **Node.js**: >= 20
+- **TypeScript**: >= 5.0 (if using TypeScript)
+
+## License
+
+MIT License - see [LICENSE](../../LICENSE) for details.

package/dist/adapters/gradle/constants.d.ts

@@ -0,0 +1,13 @@
+/** Standard filename for Gradle project properties file ('gradle.properties'). */
+export declare const GRADLE_PROPERTIES_FILE = "gradle.properties";
+/** Standard filename for Gradle build script using Groovy DSL ('build.gradle'). */
+export declare const GRADLE_BUILD_FILE = "build.gradle";
+/** Standard filename for Gradle build script using Kotlin DSL ('build.gradle.kts'). */
+export declare const GRADLE_BUILD_KTS_FILE = "build.gradle.kts";
+/** Standard filename for Gradle settings file using Groovy DSL ('settings.gradle'). */
+export declare const GRADLE_SETTINGS_FILE = "settings.gradle";
+/** Standard filename for Gradle settings file using Kotlin DSL ('settings.gradle.kts'). */
+export declare const GRADLE_SETTINGS_KTS_FILE = "settings.gradle.kts";
+/** Unique identifier for the Gradle adapter ('gradle'). */
+export declare const GRADLE_ID = "gradle";
+//# sourceMappingURL=constants.d.ts.map

package/dist/adapters/gradle/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/adapters/gradle/constants.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAE1D,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAEhD,uFAAuF;AACvF,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD,uFAAuF;AACvF,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AAEtD,2FAA2F;AAC3F,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAE9D,2DAA2D;AAC3D,eAAO,MAAM,SAAS,WAAW,CAAC"}

package/dist/adapters/gradle/constants.js

@@ -0,0 +1,12 @@
+/** Standard filename for Gradle project properties file ('gradle.properties'). */
+export const GRADLE_PROPERTIES_FILE = 'gradle.properties';
+/** Standard filename for Gradle build script using Groovy DSL ('build.gradle'). */
+export const GRADLE_BUILD_FILE = 'build.gradle';
+/** Standard filename for Gradle build script using Kotlin DSL ('build.gradle.kts'). */
+export const GRADLE_BUILD_KTS_FILE = 'build.gradle.kts';
+/** Standard filename for Gradle settings file using Groovy DSL ('settings.gradle'). */
+export const GRADLE_SETTINGS_FILE = 'settings.gradle';
+/** Standard filename for Gradle settings file using Kotlin DSL ('settings.gradle.kts'). */
+export const GRADLE_SETTINGS_KTS_FILE = 'settings.gradle.kts';
+/** Unique identifier for the Gradle adapter ('gradle'). */
+export const GRADLE_ID = 'gradle';

package/dist/adapters/gradle/gradle-project-information.d.ts

@@ -0,0 +1,19 @@
+import { ProjectInformation, RawProjectInformation } from '../project-information.js';
+/**
+ * Executes Gradle to collect raw project structure information.
+ * Runs gradlew with init script to output JSON containing module hierarchy, versions, and dependencies.
+ * @param projectRoot - Absolute path to the Gradle project root directory
+ * @param outputFile - Path to output JSON file to be generated
+ * @returns Promise resolving to raw project information as JSON
+ * @throws {Error} If initialization script not found or Gradle execution fails
+ */
+export declare function getRawProjectInformation(projectRoot: string, outputFile: string): Promise<RawProjectInformation>;
+/**
+ * Transforms raw project information into structured, queryable format.
+ * Normalizes modules, identifies root, parses versions, and maps dependencies.
+ * @param projectInformation - Raw project information from Gradle
+ * @returns Structured ProjectInformation with normalized data
+ * @throws {Error} If no root module found in hierarchy
+ */
+export declare function getProjectInformation(projectInformation: RawProjectInformation): ProjectInformation;
+//# sourceMappingURL=gradle-project-information.d.ts.map

package/dist/adapters/gradle/gradle-project-information.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gradle-project-information.d.ts","sourceRoot":"","sources":["../../../src/adapters/gradle/gradle-project-information.ts"],"names":[],"mappings":"AAGA,OAAO,EAAsB,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AA4H1G;;;;;;;GAOG;AACH,wBAAsB,wBAAwB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAuEtH;AA2CD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,kBAAkB,EAAE,qBAAqB,GAAG,kBAAkB,CA6CnG"}

package/dist/adapters/gradle/gradle-project-information.js

@@ -0,0 +1,233 @@
+import path, { join } from 'path';
+import { createInitialVersion, parseSemVer } from '../../semver/index.js';
+import { exists } from '../../utils/file.js';
+import { fileURLToPath } from 'url';
+import { execa } from 'execa';
+import fs from 'fs/promises';
+import crypto from 'crypto';
+import fg from 'fast-glob';
+import { parseProperties } from '../../utils/properties.js';
+import { logger } from '../../utils/logger.js';
+/**
+ * Name of the Gradle wrapper script file.
+ * Ensures consistent builds without requiring pre-installed Gradle.
+ */
+const GRADLE_WRAPPER = 'gradlew';
+/**
+ * Relative path to the Gradle initialization script within the action.
+ * Injected into Gradle to collect project structure information as JSON.
+ */
+const GRADLE_INIT_SCRIPT = './init-project-information.gradle.kts';
+/**
+ * Finds all Gradle build files recursively under the project root.
+ * Searches for settings.gradle, settings.gradle.kts, build.gradle, and build.gradle.kts files.
+ * @param projectRoot - Absolute path to the Gradle project root directory
+ * @returns Promise resolving to array of relative paths to Gradle build files
+ */
+async function findGradleFiles(projectRoot) {
+    const patterns = [
+        '**/settings.gradle',
+        '**/settings.gradle.kts',
+        '**/build.gradle',
+        '**/build.gradle.kts'
+    ];
+    const files = await fg(patterns, {
+        cwd: projectRoot,
+        absolute: false,
+        ignore: ['**/node_modules/**', '**/build/**', '**/.gradle/**']
+    });
+    // Sort for consistent ordering
+    return files.sort();
+}
+/**
+ * Computes SHA-256 hash of all Gradle build files.
+ * Used to detect changes in project configuration that would invalidate cached information.
+ * @param projectRoot - Absolute path to the Gradle project root directory
+ * @returns Promise resolving to hexadecimal hash string
+ */
+async function computeGradleFilesHash(projectRoot) {
+    const files = await findGradleFiles(projectRoot);
+    const hash = crypto.createHash('sha256');
+    for (const file of files) {
+        const content = await fs.readFile(join(projectRoot, file), 'utf-8');
+        hash.update(file); // Include file path for uniqueness
+        hash.update(content);
+    }
+    return hash.digest('hex');
+}
+/**
+ * Executes the Gradle wrapper script to generate project information.
+ * Runs gradlew with initialization script to create the project-information.json file.
+ * @param projectRoot - Absolute path to the Gradle project root directory
+ * @param outputFile - Path to output JSON file to be generated
+ * @throws {Error} If initialization script not found or Gradle execution fails
+ */
+async function executeGradleScript(projectRoot, outputFile) {
+    logger.info(`⚙️ Executing Gradle to collect project information...`);
+    const gradlew = join(projectRoot, GRADLE_WRAPPER);
+    const dirname = path.dirname(fileURLToPath(import.meta.url));
+    const initScriptPath = join(dirname, GRADLE_INIT_SCRIPT);
+    // Check if init script exists
+    const scriptExists = await exists(initScriptPath);
+    if (!scriptExists) {
+        throw new Error(`Init script not found at ${initScriptPath}. ` +
+            `Please create the ${GRADLE_INIT_SCRIPT} file.`);
+    }
+    // Prepare Gradle command arguments
+    const args = [
+        '--quiet', // Suppress non-error output for clean JSON
+        '--console=plain', // Disable ANSI formatting
+        '--init-script', // Inject initialization script
+        initScriptPath,
+        'structure', // Custom task that outputs project structure
+        `-PprojectInfoOutput=${outputFile}`
+    ];
+    // Execute Gradle wrapper with the prepared arguments
+    const result = await execa(gradlew, args, {
+        cwd: projectRoot, // Run from project root
+        reject: false // Handle non-zero exit codes ourselves
+    });
+    // Check for Gradle execution failure
+    if (result.exitCode !== 0) {
+        throw new Error(`Gradle command failed with exit code ${result.exitCode}: ${result.stderr}`);
+    }
+    logger.info(`✅ Gradle project information generated at ${outputFile}.`);
+}
+/**
+ * Executes Gradle to collect raw project structure information.
+ * Runs gradlew with init script to output JSON containing module hierarchy, versions, and dependencies.
+ * @param projectRoot - Absolute path to the Gradle project root directory
+ * @param outputFile - Path to output JSON file to be generated
+ * @returns Promise resolving to raw project information as JSON
+ * @throws {Error} If initialization script not found or Gradle execution fails
+ */
+export async function getRawProjectInformation(projectRoot, outputFile) {
+    // Step 1: Check if project-information.json exists
+    const fileExists = await exists(outputFile);
+    let data = {};
+    let executeScript = true;
+    // Compute hash of all Gradle build files
+    const currentHash = await computeGradleFilesHash(projectRoot);
+    logger.debug(`🔍 Computed Gradle files hash: ${currentHash}`);
+    if (fileExists) {
+        logger.info(`💾 Cached project information found at ${outputFile}. Validating cache...`);
+        // Step 2: File exists, check cache validity
+        try {
+            const fileContent = await fs.readFile(outputFile, 'utf-8');
+            const cachedData = JSON.parse(fileContent);
+            // Step 2.1: Compare hashes
+            if (cachedData.hash === currentHash) {
+                logger.info(`✅ Cache is valid. Using cached project information.`);
+                // Cache hit - use cached data
+                executeScript = false;
+                data = cachedData.data;
+            }
+            else {
+                logger.debug(`❌ Cache is invalid. Cached hash: ${cachedData.hash}`);
+                logger.info(`🔄 Gradle files changed, regenerating project information...`);
+            }
+            // Cache miss - hash mismatch, need to regenerate
+        }
+        catch (error) {
+            // If there's any error reading/parsing cached file, regenerate
+            logger.warning(`⚠️ Failed to read cached project information: ${error}`);
+        }
+    }
+    if (executeScript) {
+        // Step 3: File doesn't exist or cache is invalid - execute Gradle script
+        const outputFile = join(projectRoot, 'build', 'project-information.json');
+        await executeGradleScript(projectRoot, outputFile);
+        // Verify that the output file was created
+        const fileExistsAfterExec = await exists(outputFile);
+        if (!fileExistsAfterExec) {
+            throw new Error(`Expected output file not found at ${outputFile}. ` +
+                `Ensure that the Gradle init script is correctly generating the project information.`);
+        }
+        // Read the output file content
+        const fileContent = await fs.readFile(outputFile, 'utf-8');
+        // Parse JSON output from Gradle
+        data = JSON.parse(fileContent.trim() || '{}');
+    }
+    // Compute hash and save with cache information
+    const cachedData = {
+        hash: currentHash,
+        data
+    };
+    // Read gradle.properites and add version
+    const projectInformation = await getInformationWithVersions(projectRoot, data);
+    if (executeScript) {
+        // Write back to file with hash for future cache validation
+        await fs.writeFile(outputFile, JSON.stringify(cachedData, null, 2), 'utf-8');
+    }
+    return projectInformation;
+}
+/**
+ * Reads gradle.properties to extract module versions and augment raw project information.
+ * @param projectRoot - Absolute path to the Gradle project root directory
+ * @param projectInformation - Gradle project information without versions
+ * @returns Promise resolving to augmented RawProjectInformation with versions
+ */
+async function getInformationWithVersions(projectRoot, projectInformation) {
+    const gradlePropertiesFile = join(projectRoot, 'gradle.properties');
+    const gradlePropertiesExists = await exists(gradlePropertiesFile);
+    const result = {};
+    let moduleVersions = new Map();
+    if (gradlePropertiesExists) {
+        moduleVersions = await parseProperties(gradlePropertiesFile);
+        for (const [moduleId, module] of Object.entries(projectInformation)) {
+            const version = moduleVersions.get(module.versionProperty);
+            const resultVersion = version ? version : undefined;
+            result[moduleId] = {
+                ...module,
+                version: resultVersion,
+                declaredVersion: resultVersion !== undefined
+            };
+        }
+    }
+    return result;
+}
+/**
+ * Transforms raw project information into structured, queryable format.
+ * Normalizes modules, identifies root, parses versions, and maps dependencies.
+ * @param projectInformation - Raw project information from Gradle
+ * @returns Structured ProjectInformation with normalized data
+ * @throws {Error} If no root module found in hierarchy
+ */
+export function getProjectInformation(projectInformation) {
+    const moduleIds = Object.keys(projectInformation);
+    const modules = new Map();
+    // Find root module by looking for the one with type 'root'
+    let rootModule;
+    for (const [moduleId, rawModule] of Object.entries(projectInformation)) {
+        if (rawModule.type === 'root') {
+            rootModule = moduleId;
+        }
+        // Create normalized Module object
+        const module = {
+            id: moduleId,
+            name: rawModule.name,
+            path: rawModule.path,
+            type: rawModule.type,
+            affectedModules: new Set(rawModule.affectedModules),
+            // Parse version if present, otherwise create initial version
+            version: rawModule.version === undefined ?
+                createInitialVersion() :
+                parseSemVer(rawModule.version),
+            declaredVersion: rawModule.declaredVersion,
+        };
+        if ('versionProperty' in rawModule) {
+            module['versionProperty'] = rawModule.versionProperty;
+        }
+        modules.set(moduleId, module);
+    }
+    // Validate that a root module was found
+    if (!rootModule) {
+        throw new Error('No root module found in hierarchy. ' +
+            'Every project hierarchy must contain exactly one module with type "root".');
+    }
+    return {
+        moduleIds,
+        modules,
+        rootModule
+    };
+}