@nan0web/release 3.3.0 → 3.5.0

package/src/domain/PMaCParser.js

@@ -0,0 +1,418 @@
+import Markdown, {
+	MDHeading1,
+	MDHeading2,
+	MDHeading3,
+	MDTaskList,
+	MDTable,
+	MDTableRow,
+	MDList,
+	MDParagraph,
+} from '@nan0web/markdown'
+import {
+	ReleaseModel,
+	ReleaseMemberModel,
+	ReleaseTaskModel,
+	ReleaseParityModel,
+	ReleaseIssueModel,
+} from './models/index.js'
+
+/**
+ * Clean text from emoji, symbols, markdown formatting and trim.
+ * @param {string} text
+ * @returns {string}
+ */
+export function cleanSectionTitle(text) {
+	return String(text || '')
+		.replace(/[\u{1F300}-\u{1FAFF}\u{2600}-\u{27BF}]/gu, '')
+		.replace(/^[#\s*_-]+|[#\s*_-]+$/g, '')
+		.trim()
+		.toLowerCase()
+}
+
+/**
+ * Match section title against known synonyms in ReleaseModel.SECTIONS.
+ * @param {string} headingText
+ * @param {typeof ReleaseModel} ModelClass
+ * @returns {string | null} Recognized section key or null
+ */
+export function identifySection(headingText, ModelClass = ReleaseModel) {
+	const cleaned = cleanSectionTitle(headingText)
+	if (!cleaned) return null
+
+	for (const [sectionKey, synonyms] of Object.entries(ModelClass.SECTIONS)) {
+		for (const synonym of synonyms) {
+			const synCleaned = synonym.trim().toLowerCase()
+			if (cleaned === synCleaned || cleaned.startsWith(synCleaned) || cleaned.endsWith(synCleaned)) {
+				return sectionKey
+			}
+		}
+	}
+	return null
+}
+
+/**
+ * Resolve external tracker URL for a task or issue ID using template URL.
+ * Example: trackerUrl = "https://github.com/org/repo/issues/{id}", rawId = "[#142]" -> "https://github.com/org/repo/issues/142"
+ * @param {string} id
+ * @param {string} trackerTemplate
+ * @returns {string}
+ */
+export function resolveTrackerUrl(id, trackerTemplate) {
+	if (!trackerTemplate || !id) return ''
+	const cleanId = String(id).replace(/^\[#?|\]$/g, '').trim()
+	return trackerTemplate.replace(/\{id\}/g, cleanId)
+}
+
+/**
+ * PMaCParser - Parses PMaC Release/Task specification documents into ReleaseModel instances.
+ */
+export class PMaCParser {
+	/**
+	 * @param {typeof ReleaseModel} [modelClass]
+	 */
+	constructor(modelClass = ReleaseModel) {
+		this.ModelClass = modelClass
+	}
+
+	/**
+	 * Parse markdown content into a ReleaseModel instance.
+	 * @param {string} markdownContent
+	 * @returns {ReleaseModel}
+	 */
+	parse(markdownContent) {
+		const md = new Markdown(markdownContent)
+		const frontmatter = md.vars || {}
+		const elements = md.document?.children || []
+
+		// 1. Identify H1 for version and title
+		let version = ''
+		let title = ''
+
+		const h1 = elements.find((el) => el instanceof MDHeading1)
+		if (h1) {
+			const rawTitle = h1.content?.trim() || ''
+			// Matches formats like: "# v0.1.0 — Core Release Engine" or "# v0.1.0 - Core Release" or "# v1.0.0"
+			const h1Match = rawTitle.match(/^(v\d+\.\d+\.\d+(?:-[\w.]+)?)\s*(?:[—–-]\s*(.+))?$/i)
+			if (h1Match) {
+				version = h1Match[1]
+				title = (h1Match[2] || '').trim()
+			} else {
+				// Fallback: check if starts with version
+				const vMatch = rawTitle.match(/^(v\d+\.\d+\.\d+(?:-[\w.]+)?)/i)
+				if (vMatch) {
+					version = vMatch[1]
+					title = rawTitle.slice(vMatch[0].length).replace(/^[—–-\s]+/, '').trim()
+				} else {
+					title = rawTitle
+				}
+			}
+		}
+
+		const trackerTemplate = frontmatter.tracker || ''
+
+		// Build release data
+		const releaseData = {
+			version: frontmatter.version || version,
+			title: frontmatter.title || title,
+			status: frontmatter.status || 'todo',
+			type: frontmatter.type || 'minor',
+			epic: frontmatter.epic,
+			sprint: frontmatter.sprint,
+			tracker: trackerTemplate,
+			summary: '',
+			team: [],
+			tasks: [],
+			criteria: [],
+			parity: [],
+			issues: [],
+			files: [],
+			meta: { ...frontmatter },
+		}
+
+		// 2. Iterate through sections delimited by MDHeading2
+		let currentSection = null
+		let currentTaskGroup = ''
+
+		for (const el of elements) {
+			if (el instanceof MDHeading2) {
+				currentSection = identifySection(el.content, this.ModelClass)
+				currentTaskGroup = ''
+				continue
+			}
+
+			if (el instanceof MDHeading3) {
+				currentTaskGroup = el.content?.trim() || ''
+				continue
+			}
+
+			if (!currentSection) continue
+
+			if (currentSection === 'summary') {
+				if (el instanceof MDParagraph) {
+					const text = el.content?.trim()
+					if (text) {
+						releaseData.summary = releaseData.summary
+							? `${releaseData.summary}\n\n${text}`
+							: text
+					}
+				}
+			} else if (currentSection === 'team') {
+				this._parseTeamSection(el, releaseData.team)
+			} else if (currentSection === 'tasks') {
+				this._parseTasksSection(el, releaseData.tasks, currentTaskGroup, trackerTemplate)
+			} else if (currentSection === 'criteria') {
+				this._parseTasksSection(el, releaseData.criteria, currentTaskGroup, trackerTemplate)
+			} else if (currentSection === 'parity') {
+				this._parseParitySection(el, releaseData.parity)
+			} else if (currentSection === 'issues') {
+				this._parseIssuesSection(el, releaseData.issues)
+			} else if (currentSection === 'artifacts') {
+				this._parseArtifactsSection(el, releaseData.files)
+			}
+		}
+
+		return new this.ModelClass(releaseData)
+	}
+
+	/**
+	 * @private
+	 */
+	_parseTeamSection(el, teamList) {
+		const items = []
+		if (el instanceof MDList) {
+			for (const child of el.children) {
+				items.push(child.content?.trim() || '')
+			}
+		} else if (el.content) {
+			const lines = el.content.split('\n')
+			for (const line of lines) {
+				const trimmed = line.trim()
+				if (trimmed.startsWith('- ') || trimmed.startsWith('* ')) {
+					items.push(trimmed.slice(2).trim())
+				}
+			}
+		}
+
+		for (const item of items) {
+			// Matches: "**Lead / Architect:** Олександр Снігірьов (@snigirev)"
+			// or "**Посада:** Ім'я (@handle)"
+			const match = item.match(/^\*\*([^*]+)\*\*\s*(.*)$/)
+			if (match) {
+				const role = match[1].replace(/:$/, '').trim()
+				const rest = match[2].trim()
+				const handleMatch = rest.match(/\(@([^)]+)\)/)
+				const handle = handleMatch ? handleMatch[1].trim() : ''
+				const name = rest.replace(/\(@[^)]+\)/, '').trim()
+				teamList.push(new ReleaseMemberModel({ role, name, handle }))
+			} else {
+				teamList.push(new ReleaseMemberModel({ role: '', name: item, handle: '' }))
+			}
+		}
+	}
+
+	/**
+	 * @private
+	 */
+	_parseTasksSection(el, tasksList, taskGroup, trackerTemplate) {
+		const items = []
+		if (el instanceof MDTaskList || el instanceof MDList) {
+			for (const child of el.children) {
+				items.push(child.content?.trim() || '')
+			}
+		} else if (el.content && el.content.includes('- [')) {
+			const lines = el.content.split('\n')
+			for (const line of lines) {
+				const trimmed = line.trim()
+				if (trimmed.startsWith('- [')) {
+					items.push(trimmed.slice(2).trim())
+				}
+			}
+		}
+
+		for (const rawItem of items) {
+			// e.g. "[x] [#101-1] Винести базову модель ReleaseModel у пакет @nan0web/release"
+			// or "- [x] [#101-1] ..." or "[ ] [#101-3] ..."
+			let line = rawItem
+			if (line.startsWith('- ')) line = line.slice(2).trim()
+
+			const boxMatch = line.match(/^\[([ xX])\]\s*(.*)$/)
+			let isDone = false
+			let text = line
+
+			if (boxMatch) {
+				isDone = boxMatch[1].toLowerCase() === 'x'
+				text = boxMatch[2].trim()
+			}
+
+			// Extract task ID like [#101-1] or [101-1] or [CORE-101]
+			let id = ''
+			const idMatch = text.match(/^\[#?([A-Za-z0-9_-]+)\]\s*(.*)$/)
+			if (idMatch) {
+				id = idMatch[1]
+				text = idMatch[2].trim()
+			} else {
+				// Fallback: derive ID from group or random
+				id = `task-${tasksList.length + 1}`
+			}
+
+			// Check for notes or assignee or hours in parens/brackets
+			let notes = ''
+			if (taskGroup) {
+				notes = taskGroup
+			}
+
+			tasksList.push(
+				new ReleaseTaskModel({
+					id,
+					title: text,
+					status: isDone ? 'done' : 'todo',
+					notes,
+				})
+			)
+		}
+	}
+
+	/**
+	 * @private
+	 */
+	_parseParitySection(el, parityList) {
+		let rows = []
+		if (el instanceof MDTable) {
+			rows = el.children || []
+		} else if (el instanceof MDTableRow) {
+			rows = [el]
+		}
+		if (rows.length === 0) return
+
+		for (const row of rows) {
+			const rowContent = row.content?.trim() || ''
+			// Skip separator rows like | :--- | :---: |
+			if (/^\|[\s|:-]+\|$/.test(rowContent)) continue
+
+			const cells = rowContent
+				.split('|')
+				.map((c) => c.trim())
+				.filter((c, idx, arr) => idx > 0 && idx < arr.length - 1)
+
+			// Skip header row
+			if (cells.length >= 3) {
+				if (cells[0].toLowerCase() === 'колекція' || cells[0].toLowerCase() === 'collection') {
+					continue
+				}
+				const collection = cells[0].replace(/`/g, '')
+				const expected = parseInt(cells[1], 10) || 0
+				const actual = parseInt(cells[2], 10) || 0
+				const statusText = cells[3] || ''
+				const comment = cells[4] || ''
+				const synced = statusText.includes('OK') || statusText.includes('✅') || expected === actual
+
+				parityList.push(
+					new ReleaseParityModel({
+						collection,
+						expected,
+						actual,
+						synced,
+						comment,
+					})
+				)
+			}
+		}
+	}
+
+	/**
+	 * @private
+	 */
+	_parseIssuesSection(el, issuesList) {
+		const items = []
+		if (el instanceof MDList) {
+			for (const child of el.children) {
+				items.push(child.content?.trim() || '')
+			}
+		} else if (el.content) {
+			const lines = el.content.split('\n')
+			for (const line of lines) {
+				const trimmed = line.trim()
+				if (trimmed.startsWith('- ') || trimmed.startsWith('* ')) {
+					items.push(trimmed.slice(2).trim())
+				}
+			}
+		}
+
+		for (const item of items) {
+			// Check if this is a sub-detail line (e.g. "Джерело: `@nan0web/payload-release/admin.jsx:L85`" or "Source: ...")
+			const sourceMatch = item.match(/^(?:Джерело|Source|File):\s*`?([^`]+)`?/i)
+			if (sourceMatch && issuesList.length > 0) {
+				const lastIssue = issuesList[issuesList.length - 1]
+				lastIssue.source = sourceMatch[1].trim()
+				lastIssue.file = sourceMatch[1].split(':')[0].trim()
+				continue
+			}
+
+			// Example: "**[WARN-001]** (Performance) Файли розміром > 2MB не повинні відкриватися"
+			const codeMatch = item.match(/^\*\*\[?([A-Za-z0-9_-]+)\]?\*\*\s*(.*)$/)
+			let code = ''
+			let rest = item
+			if (codeMatch) {
+				code = codeMatch[1]
+				rest = codeMatch[2].trim()
+			}
+
+			let level = 'warning'
+			const upperCode = code.toUpperCase()
+			if (upperCode.includes('ERR') || upperCode.includes('BLOCK')) level = 'error'
+			else if (upperCode.includes('INFO')) level = 'info'
+
+			issuesList.push(
+				new ReleaseIssueModel({
+					code,
+					message: rest,
+					level,
+				})
+			)
+		}
+	}
+
+	/**
+	 * @private
+	 */
+	_parseArtifactsSection(el, filesList) {
+		let rows = []
+		if (el instanceof MDTable) {
+			rows = el.children || []
+		} else if (el instanceof MDTableRow) {
+			rows = [el]
+		}
+		if (rows.length === 0) return
+
+		for (const row of rows) {
+			const rowContent = row.content?.trim() || ''
+			if (/^\|[\s|:-]+\|$/.test(rowContent)) continue
+
+			const cells = rowContent
+				.split('|')
+				.map((c) => c.trim())
+				.filter((c, idx, arr) => idx > 0 && idx < arr.length - 1)
+
+			if (cells.length >= 1) {
+				if (cells[0].toLowerCase() === 'файл' || cells[0].toLowerCase() === 'file') {
+					continue
+				}
+				const file = cells[0].replace(/`/g, '')
+				const size = cells[1] || ''
+				const hash = cells[2] ? cells[2].replace(/`/g, '') : ''
+				const type = cells[3] || ''
+				filesList.push({ file, size, hash, type })
+			}
+		}
+	}
+
+	/**
+	 * Static shortcut to parse specification
+	 * @param {string} markdownContent
+	 * @returns {ReleaseModel}
+	 */
+	static parse(markdownContent) {
+		return new PMaCParser().parse(markdownContent)
+	}
+}
+

package/src/domain/PMaCParser.story.js

@@ -0,0 +1,152 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert'
+import {
+	ReleaseModel,
+	ReleaseTaskModel,
+	ReleaseParityModel,
+	ReleaseIssueModel,
+} from './models/index.js'
+import { PMaCParser, resolveTrackerUrl } from './PMaCParser.js'
+
+describe('PMaC Parser & Release Models Contract', () => {
+	const sampleMarkdown = `---
+status: work
+type: minor
+epic: EPIC-CORE-42
+sprint: Sprint 42
+tracker: https://github.com/nan0web/nan.web/issues/{id}
+---
+
+# v0.1.0 — Core Release Engine & Payload CMS Plugin Integration
+
+## Опис та Мета
+Плагін @nan0web/payload-release для Payload CMS 3.x, що забезпечує автоматичну фіксацію запусків релізів.
+
+## Команда
+- **Lead / Architect:** Олександр Снігірьов (@snigirev)
+- **AI Lead Developer:** Agent Antigravity (@agy)
+
+## Робочий План та Задачі
+
+### 1. Архітектурна ізоляція моделей [#101]
+- [x] [#101-1] Винести базову модель ReleaseModel у пакет @nan0web/release
+- [x] [#101-2] Реалізувати уніфікований AST-парсер специфікацій на базі @nan0web/markdown
+- [ ] [#101-3] Забезпечити 100% покриття контрактними тестами
+
+### 2. Payload CMS Адаптер [#102]
+- [x] [#102-1] Реалізувати колекцію releases з табами
+- [ ] [#102-3] Перегляд вмісту специфікацій через модальне вікно
+
+## Аудит та Паритет Даних
+| Колекція | Очікувано | Фактично | Статус | Коментар |
+| :--- | :---: | :---: | :---: | :--- |
+| \`users\` | 12 | 12 | ✅ OK | Синхронізовано |
+| \`media\` | 45 | 44 | ⚠️ Mismatch | Відсутній аватар для demo |
+
+## Зауваження та Ризики
+- **[WARN-001]** (Performance) Файли розміром > 2MB не повинні відкриватися без пагінації.
+- **[INFO-002]** (Environment) Node.js v20.x є мінімально підтримуваною версією.
+
+## Артефакти
+| Файл | Розмір | SHA-256 | Тип |
+| :--- | :---: | :--- | :--- |
+| \`task.md\` | 6.0 KB | \`e3b0c442...\` | ТЗ / Специфікація |
+`
+
+	it('ReleaseModel instantiates with schema defaults and validates', () => {
+		const release = new ReleaseModel({
+			version: 'v0.1.0',
+			title: 'Core Release Engine',
+		})
+
+		assert.strictEqual(release.version, 'v0.1.0')
+		assert.strictEqual(release.title, 'Core Release Engine')
+		assert.strictEqual(release.status, 'todo')
+		assert.strictEqual(release.type, 'minor')
+		assert.deepStrictEqual(release.tasks, [])
+		assert.deepStrictEqual(release.parity, [])
+		assert.deepStrictEqual(release.issues, [])
+		assert.strictEqual(release.validate(), true)
+	})
+
+	it('PMaCParser extracts version, title and metadata from H1 and frontmatter', () => {
+		const release = PMaCParser.parse(sampleMarkdown)
+
+		assert.strictEqual(release.version, 'v0.1.0')
+		assert.strictEqual(release.title, 'Core Release Engine & Payload CMS Plugin Integration')
+		assert.strictEqual(release.status, 'work')
+		assert.strictEqual(release.type, 'minor')
+		assert.strictEqual(release.epic, 'EPIC-CORE-42')
+		assert.strictEqual(release.sprint, 'Sprint 42')
+		assert.strictEqual(release.tracker, 'https://github.com/nan0web/nan.web/issues/{id}')
+		assert.ok(release.summary.includes('Плагін @nan0web/payload-release'))
+	})
+
+	it('PMaCParser parses tasks with status and IDs', () => {
+		const release = PMaCParser.parse(sampleMarkdown)
+
+		assert.strictEqual(release.tasks.length, 5)
+		const task1 = release.tasks[0]
+		assert.strictEqual(task1.id, '101-1')
+		assert.strictEqual(task1.title, 'Винести базову модель ReleaseModel у пакет @nan0web/release')
+		assert.strictEqual(task1.status, 'done')
+
+		const task3 = release.tasks[2]
+		assert.strictEqual(task3.id, '101-3')
+		assert.strictEqual(task3.status, 'todo')
+	})
+
+	it('PMaCParser parses data parity table into ReleaseParityModel items', () => {
+		const release = PMaCParser.parse(sampleMarkdown)
+
+		assert.strictEqual(release.parity.length, 2)
+		const p1 = release.parity[0]
+		assert.strictEqual(p1.collection, 'users')
+		assert.strictEqual(p1.expected, 12)
+		assert.strictEqual(p1.actual, 12)
+		assert.strictEqual(p1.synced, true)
+
+		const p2 = release.parity[1]
+		assert.strictEqual(p2.collection, 'media')
+		assert.strictEqual(p2.expected, 45)
+		assert.strictEqual(p2.actual, 44)
+		assert.strictEqual(p2.synced, false)
+	})
+
+	it('PMaCParser parses issues and risks into ReleaseIssueModel items', () => {
+		const release = PMaCParser.parse(sampleMarkdown)
+
+		assert.strictEqual(release.issues.length, 2)
+		const issue1 = release.issues[0]
+		assert.strictEqual(issue1.code, 'WARN-001')
+		assert.strictEqual(issue1.level, 'warning')
+		assert.ok(issue1.message.includes('(Performance)'))
+
+		const issue2 = release.issues[1]
+		assert.strictEqual(issue2.code, 'INFO-002')
+		assert.strictEqual(issue2.level, 'info')
+	})
+
+	it('PMaCParser parses artifacts table into files array', () => {
+		const release = PMaCParser.parse(sampleMarkdown)
+
+		assert.strictEqual(release.files.length, 1)
+		assert.strictEqual(release.files[0].file, 'task.md')
+		assert.strictEqual(release.files[0].size, '6.0 KB')
+	})
+
+	it('resolveTrackerUrl resolves templated ticket URLs', () => {
+		const url = resolveTrackerUrl('[#142]', 'https://github.com/nan0web/nan.web/issues/{id}')
+		assert.strictEqual(url, 'https://github.com/nan0web/nan.web/issues/142')
+
+		const url2 = resolveTrackerUrl('PROJ-99', 'https://jira.company.com/browse/{id}')
+		assert.strictEqual(url2, 'https://jira.company.com/browse/PROJ-99')
+	})
+
+	it('ReleaseModel.addLocaleSections extends recognized synonyms', () => {
+		ReleaseModel.addLocaleSections({
+			tasks: ['aufgaben', 'arbeitsplan'],
+		})
+		assert.ok(ReleaseModel.SECTIONS.tasks.includes('aufgaben'))
+	})
+})

package/src/domain/PreviewCommand.js

@@ -0,0 +1,39 @@
+import WebCommand from './WebCommand.js'
+
+/**
+ * PreviewCommand - ModelAsApp Subcommand to generate, serve and preview PM-as-Code Web Dashboard.
+ */
+export default class PreviewCommand extends WebCommand {
+	static alias = 'preview'
+
+	static UI = {
+		title: 'preview',
+		help: 'Generate, serve and preview PM-as-Code Web Dashboard',
+		loading: 'Aggregating release telemetry and preparing Web Dashboard preview...',
+		generated: '✨ Web Dashboard успішно згенеровано: {$path}',
+		serving: '🌐 Web Dashboard запущено: http://localhost:{$port} (Натисніть Ctrl+C для зупинки)',
+	}
+
+	static port = {
+		help: 'Port to serve HTML dashboard over HTTP',
+		default: 3333,
+		type: 'number',
+		alias: 'p',
+	}
+
+	static open = {
+		help: 'Automatically open in browser',
+		default: true,
+		type: 'boolean',
+	}
+
+	/**
+	 * @param {Partial<PreviewCommand>} [data]
+	 * @param {import('@nan0web/types').ModelOptions} [options]
+	 */
+	constructor(data = {}, options = {}) {
+		super({ port: 3333, open: true, ...data }, options)
+	}
+}
+
+export { PreviewCommand }

package/src/domain/PublishCommand.js

@@ -2,6 +2,13 @@ import { ModelAsApp, result, show } from '@nan0web/ui'
 import { runSpawn } from '@nan0web/test'
 
 export default class PublishCommand extends ModelAsApp {
+	/** @type {boolean} Bump major version */
+	major = false
+	/** @type {boolean} Bump minor version */
+	minor = false
+	/** @type {boolean} Bump patch version */
+	patch = false
+
 	static major = {
 		help: 'Bump major version',
 		default: false,
@@ -25,9 +32,6 @@ export default class PublishCommand extends ModelAsApp {
 	 */
 	constructor(data = {}, options = {}) {
 		super(data, options)
-		/** @type {boolean} Bump major version */ this.major
-		/** @type {boolean} Bump minor version */ this.minor
-		/** @type {boolean} Bump patch version */ this.patch
 	}
 
 	/**