@nan0web/release 3.4.0 → 3.5.0

package/README.md

@@ -6,36 +6,29 @@ Project management as code, Git-native, GPG-signed, and test-driven.
 
 Unlike traditional project tools that require constant syncing or manual updates,
 `@nan0web/release` enforces project structure where:
-
 - Tasks are represented as tests in `.test.js` files.
 - Status is tracked via test outcomes.
 - Team roles and approvals are stored in structured files.
 - All changes are signed, versioned, and composable.
 
-
 This ensures:
-
 - Clear, automatable project tracking.
 - Immutable release notes and retro reflections.
 - Zero ambiguity – tasks don't exist unless tested.
 
-
 ## Installation
 
 How to install with pnpm?
-
 ```bash
 pnpm add @nan0web/release
 ```
 
 How to install with npm?
-
 ```bash
 npm install @nan0web/release
 ```
 
 How to install with yarn?
-
 ```bash
 yarn add @nan0web/release
 ```
@@ -45,7 +38,6 @@ yarn add @nan0web/release
 Start by initializing a new release:
 
 How to initialize a new release version?
-
 ```bash
 nan0release init v1.0.0
 ```
@@ -53,7 +45,6 @@ nan0release init v1.0.0
 Show release details:
 
 How to show release information?
-
 ```bash
 release show [--full]
 ```
@@ -66,7 +57,6 @@ console.info(release.version) // v1.0.0
 List all releases in the project:
 
 How to list all releases?
-
 ```bash
 nan0release list [--json]
 ```
@@ -74,7 +64,6 @@ nan0release list [--json]
 Add a chat message to the current release:
 
 How to write a release chat message?
-
 ```bash
 nan0release chat write --user alice "Issue with the build pipeline"
 ```
@@ -82,7 +71,6 @@ nan0release chat write --user alice "Issue with the build pipeline"
 Host a static server for viewing releases:
 
 How to host release UI?
-
 ```bash
 nan0release host [--webui] [--port 3000]
 ```
@@ -90,7 +78,6 @@ nan0release host [--webui] [--port 3000]
 Serve all release files for local inspection:
 
 How to serve release static assets?
-
 ```bash
 nan0release serve [--port 8080]
 ```
@@ -98,7 +85,6 @@ nan0release serve [--port 8080]
 Validate release tasks and integrity:
 
 How to validate release tasks?
-
 ```bash
 nan0release validate [--ignore-fail]
 ```
@@ -106,7 +92,6 @@ nan0release validate [--ignore-fail]
 Seal the release with retro reflection:
 
 How to seal a release?
-
 ```bash
 nan0release seal [--message "All core APIs are stable and tested"]
 ```
@@ -116,16 +101,13 @@ nan0release seal [--message "All core APIs are stable and tested"]
 ### 1. Release as Object
 
 A `Release` is a structured class containing:
-
 - `version`: release identifier (vX.Y.Z).
 - `createdAt`, `startAt`, `planAt`, `completeAt`: datetime milestones.
 - `document`: parsed markdown document with structure-aware parsing.
 
-
 Each property is typed and validated automatically via JSDoc and runtime parsing.
 
 How to instantiate a Release?
-
 ```js
 import { Release } from '@nan0web/release'
 const release = new Release({
@@ -138,14 +120,11 @@ console.info(release.createdAt instanceof Date) // ← true
 ### 2. Release Document Parsing
 
 A `ReleaseDocument` extends `@nan0web/markdown` with:
-
 - Structured parsing of markdown release notes
 - Extraction of sections and tasks
 - Team and role parsing from markdown frontmatter or code
 
-
 How to parse release notes markdown into structured data?
-
 ```js
 import { ReleaseDocument } from '@nan0web/release'
 const md = `# v1.0.0 - 2025-08-20
@@ -162,14 +141,11 @@ console.info(doc.document.children instanceof Array) // ← true
 ### 3. Person & Team Structures
 
 A `Person` instance includes:
-
 - `name`: HumanName
 - `gender`: HumanGender
 - `contacts`: array of HumanContact
 
-
 How to create a Person with typed properties?
-
 ```js
 import { Person } from '@nan0web/release'
 const person = new Person({
@@ -190,7 +166,6 @@ Tasks are registered as `taskId` → `testFilePath` in `ProjectManagement`.
 Their status is derived by running `node:test` suites.
 
 How to register and validate tasks as tests?
-
 ```js
 import { ProjectManagement } from '@nan0web/release'
 const pm = new ProjectManagement()
@@ -210,14 +185,11 @@ console.info(results.pending.includes('task-2')) // ← true
 
 The `ReleaseManager` coordinates releases and validates readiness.
 It ensures:
-
 - All registered tests pass
 - Version is correctly incremented
 - Git tag is applied if all validations succeed
 
-
 How to execute a release after validation?
-
 ```js
 import { ReleaseManager, ProjectManagement } from '@nan0web/release'
 const pm = new ProjectManagement()
@@ -231,14 +203,11 @@ console.info(result.published) // ← true
 ### Changelog Integration
 
 Using `ChangelogTaskManager`, you can:
-
 - Extract task definitions from changelog entries
 - Generate corresponding test files
 - Automate task progression in CI
 
-
 How to parse changelog and extract tasks?
-
 ```js
 import { ChangelogTaskManager } from '@nan0web/release'
 const ctm = new ChangelogTaskManager()
@@ -260,7 +229,6 @@ Uses JSDoc and .d.ts files for autocompletion
 Try the package in the terminal:
 
 How to run playground demo?
-
 ```bash
 git clone https://github.com/nan0web/release.git
 cd release
@@ -273,7 +241,6 @@ pnpm run playground
 To verify the project is ready, run:
 
 How to check project status before publishing?
-
 ```bash
 npm test
 npm run test:coverage
@@ -287,5 +254,3 @@ How to contribute? - [check here](./CONTRIBUTING.md)
 ## License
 
 How to license ISC? - [check here](./LICENSE)
-
-

package/bin/nan0release.js

@@ -28,10 +28,10 @@ if (process.cwd() !== root && existsSync(resolve(root, 'releases.txt'))) {
 	process.chdir(root)
 }
 
-const db = new DBFS()
+const db = new DBFS({ root: '.' })
 await db.connect()
 
-bootstrapApp(ReleaseApp, { db }).catch((err) => {
+bootstrapApp(ReleaseApp, { db, root: '.' }).catch((err) => {
 	console.error(err)
 	process.exit(1)
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nan0web/release",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Project Management as Code, Git-Native, GPG-Signed, Test-Driven",
   "main": "src/index.js",
   "types": "types/index.d.ts",
@@ -37,16 +37,17 @@
   },
   "dependencies": {
     "@nan0web/changelog": "3.4.0",
-    "@nan0web/db": "3.4.0",
+    "@nan0web/csv0": "3.6.0",
+    "@nan0web/co": "3.5.0",
+    "@nan0web/db-fs": "3.6.0",
+    "@nan0web/db": "3.5.0",
+    "@nan0web/inspect": "3.7.0",
     "@nan0web/log": "3.4.0",
     "@nan0web/logos": "3.4.0",
-    "@nan0web/co": "3.4.0",
-    "@nan0web/inspect": "3.4.0",
+    "@nan0web/markdown": "3.4.0",
+    "@nan0web/ui": "3.5.0",
     "@nan0web/types": "3.4.0",
-    "@nan0web/ui": "3.4.0",
-    "@nan0web/ui-cli": "3.4.0",
-    "@nan0web/db-fs": "3.4.0",
-    "@nan0web/markdown": "3.4.0"
+    "@nan0web/ui-cli": "3.5.0"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",

package/src/domain/App.js

@@ -12,6 +12,7 @@ import PreviewCommand from './PreviewCommand.js'
 import ViewCommand from './ViewCommand.js'
 import ListCommand from './ListCommand.js'
 import ServeCommand from './ServeCommand.js'
+import ValidateCommand from './ValidateCommand.js'
 
 export class ReleaseApp extends ModelAsApp {
 	static alias = 'release'
@@ -25,6 +26,7 @@ export class ReleaseApp extends ModelAsApp {
 		options: [
 			InitCommand,
 			CheckCommand,
+			ValidateCommand,
 			CloseCommand,
 			DepsCommand,
 			PublishCommand,

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)
+	}
+}
+