iobroker.autodoc 0.9.35

package/lib/quickStartGuide.js

@@ -0,0 +1,180 @@
+/**
+ * Phase 5.x.2 — structured Quick Start + room guide picks from discovery (no invented facts).
+ */
+
+const MAX_SYSTEM_ITEMS = 5;
+const MAX_ROOMS = 8;
+const HIGHLIGHTS_PER_ROOM = 3;
+const MAX_SCRIPT_SNIPPET = 120;
+
+/** Caps for guest Onboarding quick start (same facts, shorter than User “at a glance”). */
+const ONBOARDING_VIEW_MAX_SYSTEM_ITEMS = 3;
+const ONBOARDING_VIEW_MAX_ROOMS = 4;
+const ONBOARDING_VIEW_HIGHLIGHTS_PER_ROOM = 2;
+
+/**
+ * Narrow the shared `quickStart` model for Onboarding HTML/Markdown (Phase 5.x.2 guest UX).
+ *
+ * @param {{ hasContent?: boolean, systemItems?: object[], roomGuides?: object[] } | null | undefined} qs Full quick-start payload from `buildQuickStartGuide`
+ * @returns {{ hasContent: boolean, systemItems: object[], roomGuides: object[] }} Shorter lists for guest presentation
+ */
+function sliceQuickStartForOnboarding(qs) {
+	if (!qs || !qs.hasContent) {
+		return { hasContent: false, systemItems: [], roomGuides: [] };
+	}
+	const systemItems = (qs.systemItems || []).slice(0, ONBOARDING_VIEW_MAX_SYSTEM_ITEMS);
+	const roomGuides = (qs.roomGuides || []).slice(0, ONBOARDING_VIEW_MAX_ROOMS).map(rg => ({
+		...rg,
+		highlights: (rg.highlights || []).slice(0, ONBOARDING_VIEW_HIGHLIGHTS_PER_ROOM),
+	}));
+	const hasContent = systemItems.length > 0 || roomGuides.some(r => (r.highlights || []).length > 0);
+	return { hasContent, systemItems, roomGuides };
+}
+
+/**
+ * @param {object} roomsBlock — return value of DocumentModel#buildRooms
+ * @param {object} scriptsBlock — { scripts: Array }
+ * @returns {{ hasContent: boolean, systemItems: object[], roomGuides: object[] }} - structured quick-start payload for the renderer
+ */
+function buildQuickStartGuide(roomsBlock, scriptsBlock) {
+	const systemItems = [];
+	const roomsB = roomsBlock || {};
+	const fnList = Array.isArray(roomsB.functions) ? [...roomsB.functions] : [];
+	fnList.sort((a, b) => (b.memberCount || 0) - (a.memberCount || 0));
+	const topFn = fnList.slice(0, 3);
+
+	if (roomsB.totalRooms > 0) {
+		systemItems.push({
+			kind: 'roomCount',
+			n: roomsB.totalRooms,
+		});
+	}
+
+	for (const f of topFn) {
+		if (systemItems.length >= MAX_SYSTEM_ITEMS) {
+			break;
+		}
+		if (f && f.name) {
+			systemItems.push({
+				kind: 'function',
+				name: f.name,
+				memberCount: f.memberCount || 0,
+			});
+		}
+	}
+
+	const scriptList = (scriptsBlock && scriptsBlock.scripts) || [];
+	const withDesc = scriptList.filter(s => s.enabled && s.desc && String(s.desc).trim());
+	withDesc.sort((a, b) => {
+		const na = String((a && a.name) || (a && a.id) || '');
+		const nb = String((b && b.name) || (b && b.id) || '');
+		return na.localeCompare(nb, undefined, { sensitivity: 'base' });
+	});
+	for (const s of withDesc) {
+		if (systemItems.length >= MAX_SYSTEM_ITEMS) {
+			break;
+		}
+		const line = String(s.desc).split('\n')[0].trim().slice(0, MAX_SCRIPT_SNIPPET);
+		if (line) {
+			systemItems.push({
+				kind: 'script',
+				name: s.name || s.id,
+				desc: line,
+			});
+		}
+	}
+
+	while (systemItems.length > MAX_SYSTEM_ITEMS) {
+		systemItems.pop();
+	}
+
+	const roomList = Array.isArray(roomsB.rooms) ? [...roomsB.rooms] : [];
+	roomList.sort((a, b) => {
+		const da = a && Array.isArray(a.devices) ? a.devices.length : 0;
+		const db = b && Array.isArray(b.devices) ? b.devices.length : 0;
+		if (db !== da) {
+			return db - da;
+		}
+		const na = a && a.name ? String(a.name) : '';
+		const nb = b && b.name ? String(b.name) : '';
+		return na.localeCompare(nb, undefined, { sensitivity: 'base' });
+	});
+	const roomGuides = [];
+	let roomIndex = 0;
+	for (const room of roomList) {
+		if (roomIndex >= MAX_ROOMS) {
+			break;
+		}
+		if (!room || !room.name) {
+			continue;
+		}
+		const devs = Array.isArray(room.devices) ? [...room.devices] : [];
+		devs.sort((a, b) => {
+			const as = a && a.currentValue != null && a.currentValue !== '' ? 1 : 0;
+			const bs = b && b.currentValue != null && b.currentValue !== '' ? 1 : 0;
+			return bs - as;
+		});
+		const byCat = new Map();
+		const rest = [];
+		for (const d of devs) {
+			if (!d) {
+				continue;
+			}
+			const cat = d.category || 'other';
+			if (!byCat.has(cat)) {
+				byCat.set(cat, d);
+			} else {
+				rest.push(d);
+			}
+		}
+		const picked = Array.from(byCat.values());
+		for (const d of rest) {
+			if (picked.length >= HIGHLIGHTS_PER_ROOM) {
+				break;
+			}
+			if (!picked.includes(d)) {
+				picked.push(d);
+			}
+		}
+		for (const d of devs) {
+			if (picked.length >= HIGHLIGHTS_PER_ROOM) {
+				break;
+			}
+			if (!picked.includes(d)) {
+				picked.push(d);
+			}
+		}
+		const highlights = picked.slice(0, HIGHLIGHTS_PER_ROOM).map(d => ({
+			deviceName: d.deviceName || '',
+			icon: d.icon || '📦',
+			category: d.category || '',
+			valueText:
+				d.currentValue != null && d.currentValue !== ''
+					? String(d.currentValue) + (d.unit ? ` ${d.unit}` : '')
+					: '',
+		}));
+
+		if (highlights.length > 0) {
+			roomGuides.push({
+				name: room.name,
+				deviceCount: room.memberCount != null ? room.memberCount : devs.length,
+				highlights,
+			});
+			roomIndex += 1;
+		}
+	}
+
+	const hasContent = systemItems.length > 0 || roomGuides.length > 0;
+	return { hasContent, systemItems, roomGuides };
+}
+
+module.exports = {
+	buildQuickStartGuide,
+	sliceQuickStartForOnboarding,
+	MAX_ROOMS,
+	HIGHLIGHTS_PER_ROOM,
+	MAX_SYSTEM_ITEMS,
+	ONBOARDING_VIEW_MAX_SYSTEM_ITEMS,
+	ONBOARDING_VIEW_MAX_ROOMS,
+	ONBOARDING_VIEW_HIGHLIGHTS_PER_ROOM,
+};

package/lib/roleMapper.js

@@ -0,0 +1,90 @@
+'use strict';
+
+/**
+ * Maps ioBroker state roles to normalized device categories with icons.
+ * ioBroker roles are inconsistent across adapters — this normalizes them.
+ */
+
+const ROLE_MAP = [
+	// Licht
+	{ pattern: /^switch\.light/, category: 'light', icon: '💡' },
+	{ pattern: /^level\.dimmer/, category: 'dimmer', icon: '💡' },
+	{ pattern: /^level\.color/, category: 'light', icon: '💡' },
+	{ pattern: /^light\./, category: 'light', icon: '💡' },
+	// Rolllade / Jalousie
+	{ pattern: /^level\.blind/, category: 'blind', icon: '🪟' },
+	{ pattern: /^blind\./, category: 'blind', icon: '🪟' },
+	{ pattern: /^action\.stop/, category: 'blind', icon: '🪟' },
+	// Thermostat / Temperatur
+	{ pattern: /^level\.temperature/, category: 'thermostat', icon: '🌡️' },
+	{ pattern: /^value\.temperature/, category: 'thermostat', icon: '🌡️' },
+	{ pattern: /^thermostat\./, category: 'thermostat', icon: '🌡️' },
+	// Feuchtigkeit
+	{ pattern: /^value\.humidity/, category: 'humidity', icon: '💧' },
+	// Bewegung
+	{ pattern: /^sensor\.motion/, category: 'motion', icon: '🚶' },
+	// Tür / Fenster
+	{ pattern: /^sensor\.door/, category: 'door', icon: '🚪' },
+	{ pattern: /^sensor\.window/, category: 'window', icon: '🪟' },
+	{ pattern: /^sensor\.contact/, category: 'door', icon: '🚪' },
+	// Alarm
+	{ pattern: /^alarm/, category: 'alarm', icon: '🚨' },
+	{ pattern: /^sensor\.alarm/, category: 'alarm', icon: '🚨' },
+	// Schloss
+	{ pattern: /^switch\.lock/, category: 'lock', icon: '🔒' },
+	{ pattern: /^lock\./, category: 'lock', icon: '🔒' },
+	// Steckdose / Schalter
+	{ pattern: /^switch$/, category: 'switch', icon: '🔌' },
+	{ pattern: /^switch\./, category: 'switch', icon: '🔌' },
+	// Medien
+	{ pattern: /^media\./, category: 'media', icon: '🎵' },
+	{ pattern: /^button\.play/, category: 'media', icon: '🎵' },
+	// Kamera
+	{ pattern: /^camera\./, category: 'camera', icon: '📷' },
+	// Strom / Energie
+	{ pattern: /^value\.power/, category: 'power', icon: '⚡' },
+	{ pattern: /^value\.current/, category: 'power', icon: '⚡' },
+	{ pattern: /^value\.voltage/, category: 'power', icon: '⚡' },
+];
+
+const CATEGORY_LABEL_KEYS = {
+	light: 'catLight',
+	dimmer: 'catDimmer',
+	blind: 'catBlind',
+	thermostat: 'catThermostat',
+	humidity: 'catHumidity',
+	motion: 'catMotion',
+	door: 'catDoor',
+	window: 'catWindow',
+	alarm: 'catAlarm',
+	lock: 'catLock',
+	switch: 'catSwitch',
+	media: 'catMedia',
+	camera: 'catCamera',
+	power: 'catPower',
+	other: 'catOther',
+};
+
+/**
+ * Map an ioBroker role string to a normalized category descriptor.
+ *
+ * @param {string} role ioBroker role string (e.g. "level.temperature")
+ * @returns {{ category: string, icon: string, labelKey: string }} - normalized role category for UI
+ */
+function mapRole(role) {
+	if (!role) {
+		return { category: 'other', icon: '📦', labelKey: CATEGORY_LABEL_KEYS.other };
+	}
+	for (const entry of ROLE_MAP) {
+		if (entry.pattern.test(role)) {
+			return {
+				category: entry.category,
+				icon: entry.icon,
+				labelKey: CATEGORY_LABEL_KEYS[entry.category] || CATEGORY_LABEL_KEYS.other,
+			};
+		}
+	}
+	return { category: 'other', icon: '📦', labelKey: CATEGORY_LABEL_KEYS.other };
+}
+
+module.exports = { mapRole, CATEGORY_LABEL_KEYS };

package/lib/scriptGroups.js

@@ -0,0 +1,78 @@
+/**
+ * Group JavaScript adapter scripts by folder path (from script.js.* object id).
+ * Used for HTML/Markdown export: same ordering as in ioBroker Admin tree.
+ */
+'use strict';
+
+/**
+ * @param {string|null|undefined} folder Folder segment from script id (e.g. "global", "Wohnung/Licht")
+ * @returns {string} Internal map key (__root__ for scripts directly under script.js.)
+ */
+function folderStorageKey(folder) {
+	return folder == null || folder === '' ? '__root__' : folder;
+}
+
+/**
+ * @param {string} key folderStorageKey result
+ * @returns {boolean} true if the folder is the global script tree
+ */
+function isGlobalFolderKey(key) {
+	return key === 'global' || key.startsWith('global/');
+}
+
+/**
+ * @param {string} a - first folder key
+ * @param {string} b - second folder key
+ * @returns {number} localeCompare-style sort delta
+ */
+function compareFolderStorageKeys(a, b) {
+	const rank = key => {
+		if (key === 'global' || key.startsWith('global/')) {
+			return 0;
+		}
+		if (key === 'common' || key.startsWith('common/')) {
+			return 1;
+		}
+		if (key === '__root__') {
+			return 9;
+		}
+		return 5;
+	};
+	const ra = rank(a);
+	const rb = rank(b);
+	if (ra !== rb) {
+		return ra - rb;
+	}
+	return String(a).localeCompare(String(b), undefined, { sensitivity: 'base' });
+}
+
+/**
+ * @param {Array<{ folder?: string|null, name?: string }>} scripts - flat script list from discovery
+ * @returns {Array<{ folderKey: string, folder: string|null, scripts: object[] }>} groups for export ordering
+ */
+function groupScriptsByFolder(scripts) {
+	const map = new Map();
+	for (const s of scripts) {
+		const key = folderStorageKey(s.folder);
+		if (!map.has(key)) {
+			map.set(key, []);
+		}
+		map.get(key).push(s);
+	}
+	const sortedKeys = [...map.keys()].sort(compareFolderStorageKeys);
+	return sortedKeys.map(key => ({
+		folderKey: key,
+		folder: key === '__root__' ? null : key,
+		scripts: map
+			.get(key)
+			.sort((a, b) =>
+				String(a.name || '').localeCompare(String(b.name || ''), undefined, { sensitivity: 'base' }),
+			),
+	}));
+}
+
+module.exports = {
+	groupScriptsByFolder,
+	isGlobalFolderKey,
+	folderStorageKey,
+};

package/lib/versionTracker.js

@@ -0,0 +1,312 @@
+/**
+ * Version Tracking Module
+ * Manages documentation version history and changelog
+ */
+
+/** Max entries kept in state `versioning.changelog` (newest first). */
+const CHANGELOG_MAX_ENTRIES = 6;
+
+/**
+ * @param {object} docModel Document model
+ * @returns {Map<string, { version: string, title: string, adapter: string }>} - instance id to version metadata
+ */
+function buildInstanceVersionMap(docModel) {
+	const map = new Map();
+	const root = docModel && docModel.adapters;
+	if (!root || !Array.isArray(root.adapters)) {
+		return map;
+	}
+	for (const ag of root.adapters) {
+		for (const inst of ag.instances || []) {
+			if (!inst || !inst.id) {
+				continue;
+			}
+			map.set(inst.id, {
+				version: inst.version != null ? String(inst.version) : '',
+				title: inst.title || inst.adapter || inst.name || '',
+				adapter: inst.adapter || '',
+			});
+		}
+	}
+	return map;
+}
+
+/**
+ * Detect adapter instance version bumps (same instance id, different common.version).
+ *
+ * @param {Map} prevMap Previous id → meta
+ * @param {Map} currMap Current id → meta
+ * @returns {Array<object>} Change entries compatible with compareVersions
+ */
+function diffAdapterInstanceVersions(prevMap, currMap) {
+	const out = [];
+	for (const [id, curr] of currMap) {
+		if (!prevMap.has(id)) {
+			continue;
+		}
+		const prev = prevMap.get(id);
+		if (prev.version === curr.version) {
+			continue;
+		}
+		const label = (curr.title || curr.adapter || id).trim() || id;
+		out.push({
+			type: 'adapter_version',
+			instanceId: id,
+			adapterTitle: label,
+			previous: prev.version,
+			current: curr.version,
+			/** Stored for Markdown export / JSON; HTML uses i18n `changelogMsgAdapterVersion` when adapterTitle is set */
+			message: `Adapter "${label}" (${id}): ${prev.version || '?'} → ${curr.version || '?'}`,
+		});
+	}
+	out.sort((a, b) => a.instanceId.localeCompare(b.instanceId));
+	return out;
+}
+
+/**
+ * Tracks documentation generation versions and changelog entries.
+ */
+class VersionTracker {
+	/**
+	 * @param {object} adapter ioBroker adapter instance
+	 */
+	constructor(adapter) {
+		this.adapter = adapter;
+		this.storagePrefix = `${adapter.namespace}.versioning`;
+	}
+
+	/**
+	 * Generate semantic version
+	 * Format: YYYY.MM.DD.HH
+	 *
+	 * @returns {string} Version string
+	 */
+	generateVersion() {
+		const now = new Date();
+		const year = now.getFullYear();
+		const month = String(now.getMonth() + 1).padStart(2, '0');
+		const day = String(now.getDate()).padStart(2, '0');
+		const hour = String(now.getHours()).padStart(2, '0');
+		return `${year}.${month}.${day}.${hour}`;
+	}
+
+	/**
+	 * Get version comparison data
+	 *
+	 * @param {object} currentDocModel Current document model
+	 * @param {object} previousDocModel Previous document model
+	 * @returns {object} Change summary
+	 */
+	compareVersions(currentDocModel, previousDocModel) {
+		if (!previousDocModel || !previousDocModel.system || !previousDocModel.system.statistics) {
+			return {
+				isInitial: true,
+				changes: [],
+				summary: 'Initial documentation generation',
+			};
+		}
+
+		const changes = [];
+		const current = (currentDocModel.system && currentDocModel.system.statistics) || {};
+		const previous = previousDocModel.system.statistics;
+
+		// Adapter instance version changes (explains many enabled_instances / state_objects deltas)
+		const prevInst = buildInstanceVersionMap(previousDocModel);
+		const currInst = buildInstanceVersionMap(currentDocModel);
+		changes.push(...diffAdapterInstanceVersions(prevInst, currInst));
+
+		// Check instance count changes
+		if (current.instanceCount !== previous.instanceCount) {
+			changes.push({
+				type: 'instance_count',
+				previous: previous.instanceCount,
+				current: current.instanceCount,
+				message: `Adapter instances changed from ${previous.instanceCount} to ${current.instanceCount}`,
+			});
+		}
+
+		// Check enabled instances changes
+		if (current.enabledInstanceCount !== previous.enabledInstanceCount) {
+			changes.push({
+				type: 'enabled_instances',
+				previous: previous.enabledInstanceCount,
+				current: current.enabledInstanceCount,
+				message: `Enabled instances changed from ${previous.enabledInstanceCount} to ${current.enabledInstanceCount}`,
+			});
+		}
+
+		// Check state object count changes
+		if (current.totalStateObjects !== previous.totalStateObjects) {
+			changes.push({
+				type: 'state_objects',
+				previous: previous.totalStateObjects,
+				current: current.totalStateObjects,
+				message: `State objects changed from ${previous.totalStateObjects} to ${current.totalStateObjects}`,
+			});
+		}
+
+		// Check project name changes
+		if (currentDocModel.system.projectName !== previousDocModel.system.projectName) {
+			changes.push({
+				type: 'project_name',
+				previous: previousDocModel.system.projectName,
+				current: currentDocModel.system.projectName,
+				message: `Project name changed from "${previousDocModel.system.projectName}" to "${currentDocModel.system.projectName}"`,
+			});
+		}
+
+		return {
+			isInitial: false,
+			changes: changes,
+			summary: changes.length === 0 ? 'No significant changes detected' : `${changes.length} change(s) detected`,
+		};
+	}
+
+	/**
+	 * Build changelog entry
+	 *
+	 * @param {string} version Version number
+	 * @param {object} changeData Changes from compareVersions
+	 * @returns {object} Changelog entry
+	 */
+	buildChangelogEntry(version, changeData) {
+		return {
+			version: version,
+			timestamp: new Date().toISOString(),
+			summary: changeData.summary,
+			isInitial: changeData.isInitial,
+			changes: changeData.changes,
+			changeCount: changeData.changes.length,
+		};
+	}
+
+	/**
+	 * Get previous version data from state
+	 *
+	 * @returns {Promise<object|null>} Previous document model or null
+	 */
+	async getPreviousVersion() {
+		try {
+			const state = await this.adapter.getStateAsync(`${this.storagePrefix}.lastDocumentModel`);
+			if (state && state.val) {
+				return JSON.parse(String(state.val));
+			}
+			return null;
+		} catch (error) {
+			this.adapter.log.warn(`Could not retrieve previous version: ${error.message}`);
+			return null;
+		}
+	}
+
+	/**
+	 * Store current version for comparison
+	 *
+	 * @param {object} docModel Document model to store
+	 * @returns {Promise<void>}
+	 */
+	async storeCurrentVersion(docModel) {
+		try {
+			await this.adapter.setStateAsync(`${this.storagePrefix}.lastDocumentModel`, {
+				val: JSON.stringify(docModel),
+				ack: true,
+			});
+		} catch (error) {
+			this.adapter.log.warn(`Could not store current version: ${error.message}`);
+		}
+	}
+
+	/**
+	 * Add changelog entry to history
+	 *
+	 * @param {object} entry Changelog entry
+	 * @returns {Promise<void>}
+	 */
+	async appendChangelog(entry) {
+		try {
+			const state = await this.adapter.getStateAsync(`${this.storagePrefix}.changelog`);
+			let changelog = [];
+
+			if (state && state.val) {
+				try {
+					changelog = JSON.parse(String(state.val));
+					if (!Array.isArray(changelog)) {
+						changelog = [];
+					}
+				} catch {
+					changelog = [];
+				}
+			}
+
+			changelog.unshift(entry);
+			changelog = changelog.slice(0, CHANGELOG_MAX_ENTRIES);
+
+			await this.adapter.setStateAsync(`${this.storagePrefix}.changelog`, {
+				val: JSON.stringify(changelog, null, 2),
+				ack: true,
+			});
+
+			await this.adapter.setStateAsync(`${this.storagePrefix}.latestVersion`, {
+				val: entry.version,
+				ack: true,
+			});
+
+			await this.adapter.setStateAsync(`${this.storagePrefix}.changeCount`, {
+				val: entry.changeCount,
+				ack: true,
+			});
+		} catch (error) {
+			this.adapter.log.warn(`Could not append changelog: ${error.message}`);
+		}
+	}
+
+	/**
+	 * Get current changelog
+	 *
+	 * @returns {Promise<Array>} Array of changelog entries
+	 */
+	async getChangelog() {
+		try {
+			const state = await this.adapter.getStateAsync(`${this.storagePrefix}.changelog`);
+			if (state && state.val) {
+				return JSON.parse(String(state.val));
+			}
+			return [];
+		} catch (error) {
+			this.adapter.log.warn(`Could not retrieve changelog: ${error.message}`);
+			return [];
+		}
+	}
+
+	/**
+	 * Format changelog to markdown
+	 *
+	 * @param {Array} changelog Changelog entries
+	 * @returns {string} Markdown formatted changelog
+	 */
+	formatChangelogMarkdown(changelog) {
+		if (!changelog || changelog.length === 0) {
+			return '# Version History\n\nNo versions recorded yet.\n';
+		}
+
+		let markdown = '# Version History\n\n';
+
+		for (const entry of changelog) {
+			markdown += `## Version ${entry.version}\n`;
+			markdown += `**Date:** ${new Date(entry.timestamp).toLocaleString()}\n`;
+			markdown += `**Summary:** ${entry.summary}\n`;
+
+			if (entry.changes.length > 0) {
+				markdown += '\n### Changes\n';
+				for (const change of entry.changes) {
+					markdown += `- **${change.type}**: ${change.message}\n`;
+				}
+			}
+
+			markdown += '\n';
+		}
+
+		return markdown;
+	}
+}
+
+module.exports = VersionTracker;