@hyperfrontend/versioning 0.1.0 → 0.3.0

package/ARCHITECTURE.md

@@ -137,7 +137,7 @@ sequenceDiagram
     Flow->>Workspace: discoverProjects()
     Workspace-->>Flow: projects[]
 
-    Flow->>Git: getCommitsSince(lastTag)
+    Flow->>Git: getCommitsSince(publishedCommit)
     Git-->>Flow: commits[]
 
     Flow->>Commits: parseConventionalCommits(commits)
@@ -214,6 +214,55 @@ flowchart TD
     breaking2 --> result
 ```
 
+### Commit Classification Pipeline
+
+When generating changelogs for monorepo projects, commits must be classified to determine which project(s) they belong to:
+
+```mermaid
+flowchart TB
+    input["Raw Commits\n(git log)"]
+
+    subgraph engine["Commit Classification Engine"]
+        direction TB
+        subgraph filters["Filtering Strategies"]
+            scope["Scope-Based\nFiltering"]
+            file["File-Based\nFiltering"]
+        end
+        scope --> matrix
+        file --> matrix
+        matrix["Classification\nDecision Matrix"]
+    end
+
+    input --> engine
+
+    matrix --> direct
+    matrix --> indirect
+    matrix --> excluded
+
+    subgraph direct["DIRECT"]
+        d1["Matching scope OR\ntouches project files"]
+        d2["Scope: OMITTED\n(redundant)"]
+    end
+
+    subgraph indirect["INDIRECT"]
+        i1["Dependency changes OR\ninfrastructure changes"]
+        i2["Scope: PRESERVED\n(context)"]
+    end
+
+    subgraph excluded["EXCLUDED"]
+        e1["Unrelated to project"]
+        e2["Not in CHANGELOG"]
+    end
+
+    direct --> changelog["Project CHANGELOG"]
+    indirect --> changelog
+
+    style direct fill:#c8e6c9
+    style indirect fill:#fff3e0
+    style excluded fill:#ffcdd2
+    style engine fill:#e3f2fd
+```
+
 ---
 
 ## Core Types

package/CHANGELOG.md

@@ -2,34 +2,48 @@
 
 All notable changes to this project will be documented in this file.
 
-## 0.1.0 - 2026-03-16
+## [0.3.0](https://github.com/AndrewRedican/hyperfrontend/compare/31943a4b39484dba86b358e4f361abe76edc4fe1...2737bb00792930010cd0161b87b4ca80b2c155e0) - 2026-03-21
 
 ### Features
 
-- **lib-versioning:** support commit amend no edit
-- **lib-versioning:** support force bump with release as config
-- **tool-package:** improve memory management and visibility on builder executor
-- **eslint-rules:** lib-ts-config-paths
-- **e2e-lib-versioning:** test cjs and esm builds
-- **eslint-rules:** lib-e2e-project-required
-- **lib-versioning:** implement project versioning
-- **eslint-rules:** ensure publishable libraries accounted for in docs
-- **eslint-rules:** add rule to ensure pipeline is ready for publishable libraries
-- **eslint-rules:** root readme.md rule to ensure packages are listed
-- **eslint-rules:** rules to align readme.md content format
-- **docs-site:** add project-scope
-- **tool-package:** build executor now takes unpkg and jsdelivr configuration
-- **lib-json-utils:** regex pattern safety
-- **eslint-rules:** no-unsafe-regex
-- **eslint-rules:** no-deprecated-tag
-- **lib-project-scope:** complete implementation
+- add commit type to section config option
+- add changelog file name config option
+- export key configuration constants
+- make project prefixes configurable
+- add max commit fallback config option
 
 ### Bug Fixes
 
-- **lib-versioning:** remove unused %h format causing git log field misalignment
-- **lib-immutable-api-utils:** rename safe object to prevent variable shadowing on cjs module init
-- **@hyperfrontend/workspace:** prevent changelog corruption in pr ci
+- **eslint-rules:** validate github urls via url parsing
+
+## [0.2.0](https://github.com/AndrewRedican/hyperfrontend/compare/a9185d9b783d7d8d51cc4ad91eb3178eba3e3930...bdcdfe00e5c9680e7a1eb925ef69997601d0f393) - 2026-03-20
+
+### Features
+
+- support commit existence verification
+- track commits to project dependencies
+- support of indirect infra changes tht may be consider for semantic versioning
+- add core commit classification engine
+- git client now supports get remote url
+- support remote repository url comparison
+- support remote repository url parsing
+- support repository models
+- support jscutlery/semver style changelog entries
+
+### Bug Fixes
 
-### Other
+- idempotently update pre-existing unpublished change log entry
+- update calculate bump process to account for unpublished versions
 
-- **eslint-rules:** disable angle bracket typecasting on eslint-rules project
+## 0.1.0 - 2026-03-16
+
+### Features
+
+- support commit amend no edit
+- support force bump with release as config
+- implement project versioning
+
+### Bug Fixes
+
+- remove unused %h format causing git log field misalignment
+- **@hyperfrontend/workspace:** prevent changelog corruption in pr ci

package/README.md

@@ -34,6 +34,7 @@
 Versioning library with changelog parsing, conventional commits, and semver flow orchestration.
 
 • 👉 See [**documentation**](https://www.hyperfrontend.dev/docs/libraries/versioning/)
+• 👉 See [**roadmap**](https://github.com/AndrewRedican/hyperfrontend/blob/main/roadmap/versioning/)
 
 ## What is @hyperfrontend/versioning?
 
@@ -42,9 +43,11 @@ Versioning library with changelog parsing, conventional commits, and semver flow
 ### Key Features
 
 - **Changelog Parsing** - Parse CHANGELOG.md files into structured objects with lossless round-tripping
-- **Conventional Commits** - Parse commit messages following the conventional commits specification
-- **Semver Utilities** - Parse, compare, increment, and validate semantic versions
-- **Registry Client** - Query npm registry for published versions and package metadata
+- **Conventional Commits** - Parse commit messages following the [Conventional Commits](https://www.conventionalcommits.org/) specification
+- **Semver Utilities** - Parse, compare, increment, and validate [semantic versions](https://semver.org/)
+- **Registry Client** - Query [npm](https://www.npmjs.com/) registry for published versions and package metadata
+- **Compare URLs** - Generate platform-specific compare URLs for changelog entries ([GitHub](https://github.com/), [GitLab](https://about.gitlab.com/), [Bitbucket](https://bitbucket.org/), [Azure DevOps](https://azure.microsoft.com/en-us/products/devops))
+- **Monorepo Scope Filtering** - Intelligent commit classification ensures changelogs only include relevant commits
 - **Composable Operations** - Build complex versioning workflows from simple, pure functions
 - **Zero External Dependencies** - Self-contained implementation with no third-party runtime dependencies
 
@@ -62,7 +65,7 @@ Working with CHANGELOG.md files programmatically typically involves fragile stri
 
 ### Unified Versioning Primitives
 
-Version management requires coordinating semver parsing, commit analysis, changelog generation, and registry queries. This library provides all these primitives in one cohesive package with consistent APIs. Query npm for published versions, parse commit history, calculate version bumps, and generate changelog entries — all composable into custom release workflows.
+Version management requires coordinating [semver](https://semver.org/) parsing, commit analysis, changelog generation, and registry queries. This library provides all these primitives in one cohesive package with consistent APIs. Query [npm](https://www.npmjs.com/) for published versions, parse commit history, calculate version bumps, and generate changelog entries — all composable into custom release workflows.
 
 ### Zero-Dependency CI Integration
 
@@ -95,7 +98,8 @@ for (const entry of changelog.entries) {
 }
 
 // Access metadata
-console.log(changelog.metadata.format) // 'keep-a-changelog', 'conventional', etc.
+// Formats: 'keep-a-changelog' (https://keepachangelog.com), 'conventional', etc.
+console.log(changelog.metadata.format)
 ```
 
 ### Parsing Conventional Commits
@@ -151,15 +155,16 @@ console.log(commit2.breakingDescription) // 'Response structure has changed'
 
 ## Module Documentation
 
-| Module       | Description                             | Documentation                       |
-| ------------ | --------------------------------------- | ----------------------------------- |
-| `changelog/` | Parse and manipulate CHANGELOG.md files | [README](./src/changelog/README.md) |
-| `commits/`   | Parse conventional commit messages      | [README](./src/commits/README.md)   |
-| `semver/`    | Semantic version parsing and comparison | [README](./src/semver/README.md)    |
-| `registry/`  | npm registry client                     | [README](./src/registry/README.md)  |
-| `git/`       | Git operations abstraction              | [README](./src/git/README.md)       |
-| `workspace/` | Project discovery and package.json      | [README](./src/workspace/README.md) |
-| `flow/`      | Version release workflow orchestration  | [README](./src/flow/README.md)      |
+| Module        | Description                             | Documentation                        |
+| ------------- | --------------------------------------- | ------------------------------------ |
+| `changelog/`  | Parse and manipulate CHANGELOG.md files | [README](./src/changelog/README.md)  |
+| `commits/`    | Parse conventional commit messages      | [README](./src/commits/README.md)    |
+| `semver/`     | Semantic version parsing and comparison | [README](./src/semver/README.md)     |
+| `registry/`   | npm registry client                     | [README](./src/registry/README.md)   |
+| `git/`        | Git operations abstraction              | [README](./src/git/README.md)        |
+| `workspace/`  | Project discovery and package.json      | [README](./src/workspace/README.md)  |
+| `flow/`       | Version release workflow orchestration  | [README](./src/flow/README.md)       |
+| `repository/` | Repository detection and compare URLs   | [README](./src/repository/README.md) |
 
 👉 See [ARCHITECTURE.md](./ARCHITECTURE.md) for module composition diagrams and data flow.
 

package/changelog/index.cjs.js

@@ -72,6 +72,8 @@ function createChangelogItem(description, options) {
         commits: options?.commits ?? [],
         references: options?.references ?? [],
         breaking: options?.breaking ?? false,
+        source: options?.source,
+        indirect: options?.indirect,
     };
 }
 /**
@@ -2086,6 +2088,25 @@ function parseVersionFromHeading(heading) {
     if (trimmed[pos] === ']') {
         pos++;
     }
+    // Handle markdown link format [version](url) - jscutlery/semver style
+    // This extracts the compare URL from patterns like [0.0.4](https://github.com/.../compare/...)
+    if (trimmed[pos] === '(') {
+        const urlStart = pos + 1;
+        let depth = 1;
+        pos++;
+        // Find matching closing parenthesis (handles nested parens in URLs)
+        while (pos < trimmed.length && depth > 0) {
+            if (trimmed[pos] === '(')
+                depth++;
+            else if (trimmed[pos] === ')')
+                depth--;
+            pos++;
+        }
+        // Extract URL if we found the closing paren
+        if (depth === 0) {
+            compareUrl = trimmed.slice(urlStart, pos - 1);
+        }
+    }
     // Skip whitespace and separator
     while (pos < trimmed.length && (trimmed[pos] === ' ' || trimmed[pos] === '-' || trimmed[pos] === '–')) {
         pos++;
@@ -2102,8 +2123,8 @@ function parseVersionFromHeading(heading) {
     while (pos < trimmed.length && trimmed[pos] === ' ') {
         pos++;
     }
-    // Check for link at end: [compare](url)
-    if (pos < trimmed.length) {
+    // Check for link at end: [compare](url) - only if no URL was already extracted
+    if (pos < trimmed.length && !compareUrl) {
         const linkMatch = extractLink(trimmed.slice(pos));
         if (linkMatch?.url) {
             compareUrl = linkMatch.url;
@@ -2821,11 +2842,22 @@ function isWhitespace$1(char) {
 }
 
 /**
- * Changelog Parser
+ * Validates that a URL is actually a GitHub URL by parsing it properly.
+ * This prevents SSRF attacks where 'github.com' could appear in path/query.
  *
- * Parses a changelog markdown string into a structured Changelog object.
- * Uses a state machine tokenizer for ReDoS-safe parsing.
+ * @param url - The URL string to validate
+ * @returns True if the URL host is github.com or a subdomain
  */
+function isGitHubUrl(url) {
+    try {
+        const parsed = createURL(url);
+        // Check that the host is exactly github.com or ends with .github.com
+        return parsed.host === 'github.com' || parsed.host.endsWith('.github.com');
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Parses a changelog markdown string into a Changelog object.
  *
@@ -2893,7 +2925,7 @@ function parseHeader(state) {
                 description.push(`[${token.value}](${nextToken.value})`);
                 links.push({ label: token.value, url: nextToken.value });
                 // Try to detect repository URL
-                if (!state.repositoryUrl && nextToken.value.includes('github.com')) {
+                if (!state.repositoryUrl && isGitHubUrl(nextToken.value)) {
                     state.repositoryUrl = extractRepoUrl(nextToken.value);
                 }
                 advance(state); // skip link-text