An open source, self-hosted, real-time port monitoring and discovery tool.
import Logger from './logger';
import whatsNewConfig from './whats-new-config';
const logger = new Logger('WhatsNewUtils');
const CATEGORY_KEYS = [
'security',
'dashboard',
'integrations',
'data',
'tooling',
'frontend',
'backend',
'fixes',
'misc'
];
const SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
function createFeatureBuckets() {
return CATEGORY_KEYS.reduce((acc, key) => {
acc[key] = [];
return acc;
}, { highlights: [] });
}
function cleanInlineFormatting(value = '') {
return value
.replace(/`([^`]+)`/g, '$1')
.replace(/\s+/g, ' ')
.trim();
}
function normalizeFeatureTitle(value = '') {
return cleanInlineFormatting(value)
.replace(/^\[(.+)\]$/, '$1')
.replace(/^\[sub\]\s*/i, '')
.trim();
}
function normalizeFeatureDescription(value = '') {
return cleanInlineFormatting(value)
.replace(/\s*\((?:resolves|addresses)?\s*#\d+\)/gi, '')
.replace(/\s*\(#\d+(?:\s*,\s*PR\s*#\d+)?(?:\s+by\s+@[^)]+)?\)/gi, '')
.replace(/\s+[-–—]\s+$/, '')
.trim();
}
function shouldIgnoreVersion(version) {
const ignoredVersions = Array.isArray(whatsNewConfig.ignoreVersions)
? whatsNewConfig.ignoreVersions
: [];
return ignoredVersions.includes(version) || !SEMVER_PATTERN.test(version);
}
const DIRECTIVE_PATTERN = /^<!--\s*whatsnew:([a-z]+)(?:=(.*?))?\s*-->\s*$/i;
function emptyDirectives() {
return { hide: false, title: null, description: null };
}
function parseDirectiveLine(line) {
const match = line.match(DIRECTIVE_PATTERN);
if (!match) return null;
const key = match[1].toLowerCase();
const value = match[2] !== undefined ? match[2].trim() : null;
return { key, value };
}
function applyDirectives(feature, directives) {
if (directives.hide) return null;
return {
...feature,
title: directives.title || normalizeFeatureTitle(feature.title),
description: directives.description || normalizeFeatureDescription(feature.description),
details: Array.isArray(feature.details)
? feature.details
.map((detail) => ({
title: normalizeFeatureTitle(detail.title || ''),
description: normalizeFeatureDescription(detail.description || ''),
}))
.filter((detail) => detail.title || detail.description)
: [],
};
}
const CATEGORY_MAPPINGS = [
{ match: /(security|auth|access)/i, bucket: 'security' },
{ match: /(dashboard|ui|ux|interface)/i, bucket: 'dashboard' },
{ match: /(server|collector|truenas|docker|integration)/i, bucket: 'integrations' },
{ match: /(data|db|database|infrastructure|performance|cache)/i, bucket: 'data' },
{ match: /(tooling|ops|operation|automation|deploy)/i, bucket: 'tooling' },
{ match: /(frontend|client)/i, bucket: 'frontend' },
{ match: /(backend|api)/i, bucket: 'backend' },
{ match: /(fix|bug|stability|patch)/i, bucket: 'fixes' },
];
function mapSectionToCategory(sectionName) {
const normalized = sectionName.toLowerCase();
for (const mapping of CATEGORY_MAPPINGS) {
if (mapping.match.test(normalized)) {
return mapping.bucket;
}
}
return 'misc';
}
export function parseChangelog(changelogContent) {
try {
const versions = {};
const lines = changelogContent.split('\n');
let currentVersion = null;
let currentSection = null;
let inHighlights = false;
let features = createFeatureBuckets();
let lastFeature = null;
let pendingDirectives = emptyDirectives();
for (let i = 0; i < lines.length; i++) {
const rawLine = lines[i];
const line = rawLine.trim();
const directive = parseDirectiveLine(line);
if (directive) {
if (directive.key === 'hide') pendingDirectives.hide = true;
else if (directive.key === 'title') pendingDirectives.title = directive.value;
else if (directive.key === 'description') pendingDirectives.description = directive.value;
continue;
}
if (line === '**Highlights**') {
inHighlights = true;
pendingDirectives = emptyDirectives();
continue;
}
if (inHighlights && (line === '---' || line.startsWith('###'))) {
inHighlights = false;
if (line.startsWith('###')) {
currentSection = mapSectionToCategory(line.replace(/^###\s+/, ''));
}
pendingDirectives = emptyDirectives();
continue;
}
if (inHighlights && line.startsWith('- ')) {
const highlightText = line.replace(/^-\s*/, '');
const parts = highlightText.split(/\s+[-–—]\s+/);
const title = parts[0]?.trim() || highlightText;
const description = parts[1]?.trim() || '';
features.highlights.push({ title, description });
pendingDirectives = emptyDirectives();
continue;
}
const versionMatch = line.match(/^##\s*\[([^\]]+)\]/);
if (versionMatch) {
const hasContent = Object.values(features).some(arr => arr.length > 0);
if (currentVersion && hasContent) {
versions[currentVersion] = { ...features };
}
currentVersion = versionMatch[1];
if (shouldIgnoreVersion(currentVersion)) {
currentSection = null;
features = createFeatureBuckets();
lastFeature = null;
pendingDirectives = emptyDirectives();
continue;
}
currentSection = null;
features = createFeatureBuckets();
lastFeature = null;
pendingDirectives = emptyDirectives();
continue;
}
const sectionMatch = line.match(/^###\s+(.+)$/);
if (sectionMatch && currentVersion) {
currentSection = mapSectionToCategory(sectionMatch[1]);
lastFeature = null;
pendingDirectives = emptyDirectives();
continue;
}
const featureMatch = line.match(/^-\s*\*\*(.+?)\*\*:\s*(.+)$/);
if (featureMatch && currentSection) {
const title = featureMatch[1].trim();
const description = featureMatch[2].trim();
const isSubItem = title.startsWith('[sub]');
if (isSubItem && lastFeature) {
const cleanTitle = title.replace(/^\[sub\]\s*/, '').trim();
if (!lastFeature.details) {
lastFeature.details = [];
}
lastFeature.details.push({ title: cleanTitle, description });
} else {
const nextFeature = applyDirectives({
title: isSubItem ? title.replace(/^\[sub\]\s*/, '').trim() : title,
description,
details: []
}, pendingDirectives);
if (nextFeature) {
features[currentSection].push(nextFeature);
lastFeature = nextFeature;
} else {
lastFeature = null;
}
}
pendingDirectives = emptyDirectives();
continue;
}
const subItemMatch = line.match(/^-\s*\*\*\[sub\]\*\*\s+(.+)$/);
if (subItemMatch && lastFeature && currentSection) {
const text = subItemMatch[1].trim();
if (!lastFeature.details) {
lastFeature.details = [];
}
lastFeature.details.push({ title: '', description: normalizeFeatureDescription(text) });
pendingDirectives = emptyDirectives();
}
}
const hasContent = Object.values(features).some(arr => arr.length > 0);
if (currentVersion && hasContent) {
versions[currentVersion] = { ...features };
}
logger.debug('Parsed changelog versions:', Object.keys(versions));
return versions;
} catch (error) {
logger.error('Error parsing changelog:', error);
return {};
}
}
export function getLastSeenVersion() {
try {
return localStorage.getItem('portracker_last_seen_version') || null;
} catch (error) {
logger.warn('Failed to get last seen version:', error);
return null;
}
}
export function setLastSeenVersion(version) {
try {
localStorage.setItem('portracker_last_seen_version', version);
logger.debug('Set last seen version:', version);
} catch (error) {
logger.warn('Failed to set last seen version:', error);
}
}
export function compareVersions(v1, v2) {
if (!v1 || !v2) return 0;
const parseVersion = (version) => {
return version.split('.').map(num => parseInt(num, 10) || 0);
};
const version1 = parseVersion(v1);
const version2 = parseVersion(v2);
const maxLength = Math.max(version1.length, version2.length);
for (let i = 0; i < maxLength; i++) {
const num1 = version1[i] || 0;
const num2 = version2[i] || 0;
if (num1 < num2) return -1;
if (num1 > num2) return 1;
}
return 0;
}
export function getNewVersions(parsedVersions, lastSeenVersion) {
logger.debug('getNewVersions called:', {
parsedVersionsKeys: Object.keys(parsedVersions),
lastSeenVersion,
parsedVersions: parsedVersions
});
if (!parsedVersions || Object.keys(parsedVersions).length === 0) {
logger.debug('getNewVersions: No parsed versions available');
return [];
}
const availableVersions = Object.keys(parsedVersions).sort((a, b) => compareVersions(b, a));
logger.debug('getNewVersions: Available versions sorted:', availableVersions);
if (!lastSeenVersion) {
const maxVersionsOnFirstOpen = Math.max(1, whatsNewConfig.maxVersionsOnFirstOpen || 1);
const initialVersions = availableVersions.slice(0, maxVersionsOnFirstOpen);
logger.debug('getNewVersions: No last seen version, returning newest versions only:', initialVersions);
return initialVersions;
}
const newVersions = availableVersions.filter(version => {
const comparison = compareVersions(version, lastSeenVersion);
logger.debug('getNewVersions: Comparing', version, 'vs', lastSeenVersion, '=', comparison);
return comparison > 0;
});
logger.debug('getNewVersions: Filtered new versions:', newVersions);
return newVersions;
}
export function combineVersionChanges(versions, versionKeys) {
const combined = createFeatureBuckets();
const sortedVersions = [...versionKeys].sort((a, b) => compareVersions(b, a));
for (const version of sortedVersions) {
const versionChanges = versions[version];
if (versionChanges) {
if (versionChanges.highlights?.length) {
combined.highlights.push(...versionChanges.highlights);
}
CATEGORY_KEYS.forEach(key => {
if (versionChanges[key]?.length) {
combined[key].push(...versionChanges[key]);
}
});
}
}
return combined;
}
export function groupVersionChanges(versions, versionKeys) {
const sortedVersions = [...versionKeys].sort((a, b) => compareVersions(b, a));
return sortedVersions.map(version => {
const versionChanges = versions[version];
const changes = createFeatureBuckets();
if (versionChanges) {
if (versionChanges.highlights?.length) {
changes.highlights.push(...versionChanges.highlights);
}
CATEGORY_KEYS.forEach(key => {
if (versionChanges[key]?.length) {
changes[key].push(...versionChanges[key]);
}
});
}
return {
version,
changes
};
}).filter(item => item.changes.highlights?.length > 0 || CATEGORY_KEYS.some(key => item.changes[key]?.length > 0));
}
export function shouldShowWhatsNew(currentVersion) {
if (!currentVersion) {
logger.debug('shouldShowWhatsNew: No current version provided');
return false;
}
const lastSeenVersion = localStorage.getItem('portracker_last_seen_version');
if (!lastSeenVersion) {
logger.debug('shouldShowWhatsNew: No last seen version, first time user');
return true;
}
const comparison = compareVersions(currentVersion, lastSeenVersion);
logger.debug('shouldShowWhatsNew: Version comparison:', {
currentVersion,
lastSeenVersion,
comparison,
shouldShow: comparison > 0
});
return comparison > 0;
}