@nan0web/release 3.3.0 → 3.4.0

package/src/domain/CheckCommand.story.js

@@ -0,0 +1,92 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import DB from '@nan0web/db'
+import CheckCommand from './CheckCommand.js'
+
+describe('CheckCommand OLMUI Scenario & Validator', () => {
+	it('validates a compliant project release structure without errors', async () => {
+		const pkgJson = { name: '@nan0web/sample-pkg', version: '1.0.0' }
+		const releaseMd = `# v1.0.0 - 2026-09-01
+## Tasks
+- [x] Implement initial feature
+`
+		const userMd = `---
+name: user-feedback
+version: 1.0.0
+---
+## ⏱ 1. Метрики Виконання
+- **Витрачений час розробки (Годин):** \`4.5h\`
+- **Кількість ітерацій (Test Runs / Refactors):** \`10\`
+- **Фінальний бал RRS (Release Readiness Score):** \`324\`
+`
+		const taskSpec = `import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+describe('sample contract', () => {
+	it('works', () => assert.ok(true))
+})
+`
+		const db = new DB({
+			predefined: [
+				['packages/sample-pkg/package.json', pkgJson],
+				['packages/sample-pkg/releases/1/0/v1.0.0/release.md', releaseMd],
+				['packages/sample-pkg/releases/1/0/v1.0.0/user.md', userMd],
+				['packages/sample-pkg/releases/1/0/v1.0.0/task.spec.js', taskSpec],
+			],
+		})
+		await db.connect()
+
+		const cmd = new CheckCommand({ target: 'packages/sample-pkg' }, { db })
+		const gen = cmd.run()
+
+		let step = await gen.next()
+		const outputs = []
+		while (!step.done) {
+			outputs.push(step.value)
+			step = await gen.next()
+		}
+
+		const res = step.value?.data || step.value
+		assert.ok(res.success)
+		assert.equal(res.diagnostics.length, 0)
+		assert.equal(res.checkedProjects.length, 1)
+	})
+
+	it('detects missing user.md metrics and missing contracts with actionable recommendations', async () => {
+		const pkgJson = { name: '@nan0web/broken-pkg', version: '2.0.0' }
+		const releaseMd = `# v2.0.0 - 2026-09-01
+## Tasks
+- [ ] Incomplete task
+`
+		const db = new DB({
+			predefined: [
+				['packages/broken-pkg/package.json', pkgJson],
+				['packages/broken-pkg/releases/2/0/v2.0.0/release.md', releaseMd],
+			],
+		})
+		await db.connect()
+
+		const cmd = new CheckCommand({ target: 'packages/broken-pkg' }, { db })
+		const gen = cmd.run()
+
+		let step = await gen.next()
+		const outputs = []
+		while (!step.done) {
+			outputs.push(step.value)
+			step = await gen.next()
+		}
+
+		const res = step.value?.data || step.value
+		assert.equal(res.success, false)
+		assert.ok(res.diagnostics.length >= 2)
+
+		// Check for missing user.md diagnostic
+		const userDiag = res.diagnostics.find((d) => d.code === 'MISSING_USER_MD' || d.type === 'missing_user_md')
+		assert.ok(userDiag)
+		assert.ok(userDiag.fix.includes('user.md'))
+
+		// Check for missing contract diagnostic
+		const contractDiag = res.diagnostics.find((d) => d.code === 'MISSING_CONTRACT' || d.type === 'missing_contract')
+		assert.ok(contractDiag)
+		assert.ok(contractDiag.fix.includes('task.spec.js'))
+	})
+})

package/src/domain/CloseCommand.js

@@ -3,6 +3,9 @@ import { runSpawn } from '@nan0web/test'
 import Scanner from '../Release/Scanner.js'
 
 export default class CloseCommand extends ModelAsApp {
+	/** @type {string} Release version */
+	version = ''
+
 	static version = {
 		help: 'Release version',
 		default: '',
@@ -18,16 +21,13 @@ export default class CloseCommand extends ModelAsApp {
 	 */
 	constructor(data = {}, options = {}) {
 		super(data, options)
-		/** @type {string} Release version */ this.version
 	}
 
 	/**
 	 * @returns {AsyncGenerator<import('@nan0web/ui').Intent, import('@nan0web/ui').ResultIntent, any>}
 	 */
 	async *run() {
-		const { renameSync, mkdirSync } = await import('node:fs')
-		const { join, dirname } = await import('node:path')
-
+		const db = this._.db
 		const v = this.version || ''
 		yield show(`🛜 nan0release close ${v || 'all'}`)
 
@@ -51,18 +51,22 @@ export default class CloseCommand extends ModelAsApp {
 
 		let movedCount = 0
 		for (const spec of specs) {
-			const relativePath = spec.path.substring(process.cwd().length + 1)
+			const relativePath = spec.path.replace(/^.*?releases\//, 'releases/')
 			const destRelative = relativePath
 				.replace(/^releases\//, 'src/releases/')
 				.replace('.spec.js', '.test.js')
-			const destPath = join(process.cwd(), destRelative)
 
-			mkdirSync(dirname(destPath), { recursive: true })
-			renameSync(spec.path, destPath)
+			if (db) {
+				const content = await db.loadDocument(relativePath, null)
+				if (content !== null) {
+					await db.saveDocument(destRelative, content)
+					await db.dropDocument(relativePath)
+				}
+			}
 			movedCount++
 		}
 
 		yield show(`✅ Successfully closed ${movedCount} specs and moved to src/releases/`, 'success')
-		return result({})
+		return result({ movedCount })
 	}
 }

package/src/domain/Dashboard/Dashboard.story.js

@@ -0,0 +1,155 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import DB from '@nan0web/db'
+import { DashboardModel } from './DashboardModel.js'
+
+describe('DashboardModel OLMUI Scenario', () => {
+	it('aggregates projects, computes summary metrics and RRS readiness', async () => {
+		const rawReleasesTxt = `# Registry
+packages/sample-pkg
+apps/sample-app
+`
+		const samplePkgUserMd = `---
+name: user-feedback
+version: 1.0.0
+---
+## ⏱ 1. Метрики Виконання
+- **Витрачений час розробки (Годин):** \`4.5h\`
+- **Кількість ітерацій (Test Runs / Refactors):** \`10\`
+- **Фінальний бал RRS (Release Readiness Score):** \`324\`
+`
+		const sampleAppUserMd = `---
+name: user-feedback
+version: 0.1.0
+---
+## ⏱ 1. Метрики Виконання
+- **Витрачений час розробки (Годин):** \`2.0h\`
+- **Кількість ітерацій (Test Runs / Refactors):** \`5\`
+- **Фінальний бал RRS (Release Readiness Score):** \`300\`
+`
+		const samplePkgReleaseMd = `# v1.0.0 - 2026-09-01
+## Tasks
+### Done **Feature A** [feat.a]
+### InProgress **Feature B** [feat.b]
+`
+		const db = new DB({
+			predefined: [
+				['releases.txt', rawReleasesTxt],
+				['packages/sample-pkg/package.json', { name: '@nan0web/sample-pkg', version: '1.0.0' }],
+				['packages/sample-pkg/releases/1/0/v1.0.0/user.md', samplePkgUserMd],
+				['packages/sample-pkg/releases/1/0/v1.0.0/release.md', samplePkgReleaseMd],
+				['packages/sample-pkg/releases/1/0/v1.0.0/task.spec.js', '/* spec contract */'],
+				['apps/sample-app/package.json', { name: 'sample-app', version: '0.1.0' }],
+				['apps/sample-app/releases/0/1/v0.1.0/user.md', sampleAppUserMd],
+				['apps/sample-app/releases/0/1/v0.1.0/task.test.js', '/* closed test */'],
+			],
+		})
+		await db.connect()
+
+		const dashboard = new DashboardModel({ registryFile: 'releases.txt' }, { db })
+		const data = await dashboard.aggregate()
+
+		assert.equal(data.projects.length, 2)
+
+		// First project check
+		const p1 = data.projects.find((p) => p.name === '@nan0web/sample-pkg')
+		assert.ok(p1)
+		assert.equal(p1.hours, 4.5)
+		assert.equal(p1.iterations, 10)
+		assert.equal(p1.rrs, 324)
+		assert.equal(p1.status, 'wip') // has task.spec.js
+		assert.equal(p1.tasks.length, 2)
+		assert.equal(p1.tasks[0].slug, 'feat.a')
+
+		// Second project check
+		const p2 = data.projects.find((p) => p.name === 'sample-app')
+		assert.ok(p2)
+		assert.equal(p2.hours, 2.0)
+		assert.equal(p2.iterations, 5)
+		assert.equal(p2.rrs, 300)
+		assert.equal(p2.status, 'closed') // only task.test.js
+
+		// Summary check
+		assert.equal(data.summary.totalProjects, 2)
+		assert.equal(data.summary.totalHours, 6.5)
+		assert.equal(data.summary.totalIterations, 15)
+		assert.equal(data.summary.wipCount, 1)
+		assert.equal(data.summary.closedCount, 1)
+	})
+
+	it('yields progress and show intents when executed via async *run() generator', async () => {
+		const rawReleasesTxt = `packages/sample-pkg\n`
+		const samplePkgUserMd = `---
+name: user-feedback
+version: 1.0.0
+---
+- **Витрачений час розробки (Годин):** \`3.0h\`
+- **Кількість ітерацій (Test Runs / Refactors):** \`4\`
+- **Фінальний бал RRS (Release Readiness Score):** \`200\`
+`
+		const db = new DB({
+			predefined: [
+				['releases.txt', rawReleasesTxt],
+				['packages/sample-pkg/package.json', { name: '@nan0web/sample-pkg', version: '1.0.0' }],
+				['packages/sample-pkg/releases/1/0/v1.0.0/user.md', samplePkgUserMd],
+				['packages/sample-pkg/releases/1/0/v1.0.0/release.md', '# v1.0.0\n### Done Init [init]\n'],
+				['packages/sample-pkg/releases/1/0/v1.0.0/task.test.js', '/* closed */'],
+			],
+		})
+		await db.connect()
+
+		const dashboard = new DashboardModel({ registryFile: 'releases.txt' }, { db })
+		const intents = []
+		const gen = dashboard.run()
+
+		let next = await gen.next()
+		while (!next.done) {
+			intents.push(next.value)
+			next = await gen.next()
+		}
+		const finalResult = next.value
+
+		assert.ok(intents.length >= 2, 'Expected progress and show intents to be yielded')
+		assert.ok(intents.some((i) => i.type === 'progress'))
+		assert.ok(intents.some((i) => i.type === 'show'))
+		assert.equal(finalResult.type, 'result')
+		assert.equal(finalResult.data.projects.length, 1)
+		assert.equal(finalResult.data.projects[0].name, '@nan0web/sample-pkg')
+	})
+
+	it('supports injected gitTelemetry adapter', async () => {
+		const rawReleasesTxt = `packages/no-rel\n`
+		const db = new DB({
+			predefined: [
+				['releases.txt', rawReleasesTxt],
+				['packages/no-rel/package.json', { name: '@nan0web/no-rel', version: '0.0.1' }],
+			],
+		})
+		await db.connect()
+
+		const mockGit = {
+			getGitInfo: () => ({ branch: 'feature/zen', gitStatus: 'dirty' }),
+			getGitCommitTelemetry: () => ({ hours: 0, iterations: 0 }),
+		}
+
+		const dashboard = new DashboardModel(
+			{ registryFile: 'releases.txt' },
+			{ db, gitTelemetry: mockGit }
+		)
+		const data = await dashboard.aggregate()
+		assert.equal(data.projects[0].branch, 'feature/zen')
+		assert.equal(data.projects[0].gitStatus, 'dirty')
+	})
+
+	it('parses user.md metrics correctly with static parseUserMetrics', () => {
+		const text = `
+- **Витрачений час розробки (Годин):** \`12.5h\`
+- **Кількість ітерацій (Test Runs / Refactors):** \`42\`
+- **Фінальний бал RRS (Release Readiness Score):** \`350+\`
+`
+		const metrics = DashboardModel.parseUserMetrics(text)
+		assert.equal(metrics.hours, 12.5)
+		assert.equal(metrics.iterations, 42)
+		assert.equal(metrics.rrs, 350)
+	})
+})

package/src/domain/Dashboard/DashboardModel.js

@@ -0,0 +1,308 @@
+import { ModelAsApp, progress, show, result } from '@nan0web/ui'
+import { RegistryModel } from '../Registry/RegistryModel.js'
+import {
+	parseFrontmatter,
+	calculateDaysRemaining,
+	parseUserMetrics,
+	normalizePriority,
+	resolvePriority,
+	sortTasks,
+	determineReleaseStatus,
+} from './ReleaseParser.js'
+import {
+	versionToPath,
+	discoverReleases,
+	documentExists,
+	loadReleaseDoc,
+} from './ReleaseDiscovery.js'
+
+/**
+ * @typedef {import('./ReleaseParser.js').TaskItem} TaskItem
+ * @typedef {Object} ProjectDashboardEntry
+ * @property {string} path - Relative project path
+ * @property {string} name - Project name
+ * @property {string} version - Current release version
+ * @property {number} hours - Development hours spent
+ * @property {number} iterations - Test runs / refactor iterations
+ * @property {number} rrs - Release Readiness Score
+ * @property {'wip' | 'closed' | 'unknown'} status - Release state
+ * @property {TaskItem[]} tasks - Parsed tasks from release.md
+ * @property {string} branch - Git branch name
+ * @property {'clean' | 'dirty'} gitStatus - Git workspace status
+ * @property {string} userContent - Raw user.md content
+ * @property {string} releaseContent - Raw release.md content
+ * @property {string} sourceDoc - Relative path to the parsed release document
+ * @property {string} sourceUserDoc - Relative path to user.md
+ * @property {string?} deadline - Project release deadline
+ * @property {number?} daysRemaining - Days remaining until deadline
+ * @property {string?} priority - Priority (0 | 1 | 2 | 3)
+ * @property {number} [releasesCount] - Number of releases found
+ * @property {number} [totalHours] - Total hours across all releases
+ * @property {number} [totalIterations] - Total iterations across all releases
+ * @property {Array<any>} [allReleases] - List of all releases for project
+ *
+ * @typedef {Object} DashboardSummary
+ * @property {number} totalProjects - Total tracked projects
+ * @property {number} totalHours - Sum of hours across projects
+ * @property {number} totalIterations - Sum of iterations
+ * @property {number} wipCount - Active WIP releases
+ * @property {number} closedCount - Closed releases
+ * @property {number} [totalReleases] - Total releases counted
+ */
+
+/**
+ * DashboardModel - Aggregates release telemetry, tasks and readiness across projects.
+ */
+export class DashboardModel extends ModelAsApp {
+	static registryFile = {
+		help: 'Path to releases.txt registry file',
+		default: 'releases.txt',
+		type: 'string',
+	}
+	static summary = {
+		help: 'Aggregated metrics summary',
+		default: { totalProjects: 0, totalHours: 0, totalIterations: 0, wipCount: 0, closedCount: 0 },
+		type: 'object',
+	}
+	static projects = { help: 'List of projects with metrics', default: () => [], type: 'array' }
+	static UI = {
+		aggregating: 'Aggregating release metrics for all projects...',
+		done: 'Dashboard aggregation complete: {$total} projects scanned',
+	}
+
+	/**
+	 * @param {Partial<DashboardModel>} [data={}]
+	 * @param {Partial<import('@nan0web/ui').ModelAsAppOptions & { gitTelemetry?: any }>} [options={}]
+	 */
+	constructor(data = {}, options = {}) {
+		super(data, options)
+		/** @type {string} Path to releases.txt registry file */ this.registryFile
+		/** @type {DashboardSummary} Aggregated metrics summary */ this.summary
+		/** @type {ProjectDashboardEntry[]} List of projects with metrics */ this.projects
+		/** @type {any} Optional git telemetry adapter */
+		this._gitTelemetry = options.gitTelemetry ?? null
+	}
+
+	static parseUserMetrics = parseUserMetrics
+	static normalizePriority = normalizePriority
+	static sortTasks = sortTasks
+	static versionToPath = versionToPath
+
+	/**
+	 * Canonical OLMUI Generator: Yields progress, show, and returns result.
+	 * @returns {AsyncGenerator<import('@nan0web/ui').Intent, any, any>}
+	 */
+	async *run() {
+		yield progress(this.constructor.UI.aggregating)
+		for await (const p of this.aggregateStream()) {
+			yield progress(`${p.project} (${p.current}/${p.total})`)
+		}
+		const t = this._?.t
+		const doneMsg = t
+			? t(this.constructor.UI.done, { total: this.projects.length })
+			: this.constructor.UI.done.replace('{$total}', String(this.projects.length))
+		yield show(doneMsg, 'success')
+		return result({ summary: this.summary, projects: this.projects })
+	}
+
+	/**
+	 * Programmatic aggregation helper
+	 * @param {Function} [onProgress]
+	 * @returns {Promise<{ summary: DashboardSummary, projects: ProjectDashboardEntry[] }>}
+	 */
+	async aggregate(onProgress) {
+		for await (const p of this.aggregateStream()) {
+			if (typeof onProgress === 'function') onProgress(p.current, p.total, p.project)
+		}
+		return { summary: this.summary, projects: this.projects }
+	}
+
+	async *aggregateStream() {
+		const db = this.$db
+		const gitTelem = this._gitTelemetry
+
+		const registry = new RegistryModel({ filePath: this.registryFile }, { db })
+		const registeredProjects = await registry.loadProjects()
+
+		const projectEntries = []
+		let totalHours = 0,
+			totalIterations = 0,
+			wipCount = 0,
+			closedCount = 0
+		const totalProjects = registeredProjects.length
+		let currentIdx = 0
+
+		for (const proj of registeredProjects) {
+			currentIdx++
+			yield { current: currentIdx, total: totalProjects, project: proj.name || proj.path }
+
+			const projectRoot = proj.path === '.' ? '' : `${proj.path.replace(/\/+$/, '')}/`
+			const discovered = await discoverReleases(db, projectRoot)
+
+			if (discovered.length === 0) {
+				const gitInfo = gitTelem?.getGitInfo ? gitTelem.getGitInfo(proj.path) : { branch: 'main', gitStatus: 'clean' }
+				projectEntries.push(this.#createEmptyEntry(proj, gitInfo))
+				continue
+			}
+
+			const primaryRel = discovered[0]
+			const effectiveVersion = primaryRel.version
+			const matchedReleaseDir = primaryRel.path
+
+			let userContent = ''
+			const matchedUserDoc = `${matchedReleaseDir}/user.md`
+			try {
+				userContent = (await db.loadDocument(matchedUserDoc, '')) || ''
+			} catch {}
+
+			const metrics = parseUserMetrics(String(userContent || ''))
+			if (metrics.hours === 0 && metrics.iterations === 0 && gitTelem?.getGitCommitTelemetry) {
+				const telem = gitTelem.getGitCommitTelemetry(proj.path, matchedReleaseDir)
+				if (telem?.hours > 0) {
+					metrics.hours = telem.hours
+					metrics.iterations = telem.iterations
+				}
+			}
+
+			const { releaseContent, sourceDoc, tasks } = await loadReleaseDoc(db, matchedReleaseDir)
+			const fm = parseFrontmatter(releaseContent || userContent)
+			const deadline = fm.deadline || null
+			const daysRemaining = calculateDaysRemaining(deadline)
+			const priority = resolvePriority(fm, daysRemaining)
+
+			const hasSpec = await documentExists(db, `${matchedReleaseDir}/task.spec.js`)
+			const hasTest = await documentExists(db, `${matchedReleaseDir}/task.test.js`)
+			const status = determineReleaseStatus({
+				fmStatus: fm.status,
+				hasSpec,
+				hasTest,
+				tasks,
+				userStr: String(userContent || ''),
+				metrics,
+			})
+
+			if (status === 'wip') wipCount++
+			else if (status === 'closed') closedCount++
+
+			const { allReleases, projectTotalHours, projectTotalIterations } =
+				await this.#scanAllReleases(db, discovered, metrics)
+			totalHours += projectTotalHours
+			totalIterations += projectTotalIterations
+
+			const gitInfo = gitTelem?.getGitInfo ? gitTelem.getGitInfo(proj.path) : { branch: 'main', gitStatus: 'clean' }
+			projectEntries.push({
+				path: proj.path,
+				name: proj.name,
+				version: effectiveVersion,
+				hours: metrics.hours,
+				iterations: metrics.iterations,
+				totalHours: Math.round(projectTotalHours * 10) / 10,
+				totalIterations: projectTotalIterations,
+				releasesCount: Math.max(discovered.length, 1),
+				allReleases,
+				rrs: metrics.rrs,
+				status,
+				tasks,
+				branch: gitInfo.branch,
+				gitStatus: gitInfo.gitStatus,
+				userContent: String(userContent || ''),
+				releaseContent: String(releaseContent || ''),
+				sourceDoc:
+					sourceDoc || `${projectRoot}releases/${versionToPath(effectiveVersion)}/release.md`,
+				sourceUserDoc:
+					matchedUserDoc || `${projectRoot}releases/${versionToPath(effectiveVersion)}/user.md`,
+				deadline,
+				daysRemaining,
+				priority,
+			})
+		}
+
+		this.summary = {
+			totalProjects: registeredProjects.length,
+			totalReleases: projectEntries.reduce((sum, p) => sum + (p.releasesCount || 1), 0),
+			totalHours: Math.round(totalHours * 10) / 10,
+			totalIterations,
+			wipCount,
+			closedCount,
+		}
+		this.projects = projectEntries
+		return { summary: this.summary, projects: projectEntries }
+	}
+
+	#createEmptyEntry(proj, gitInfo) {
+		return {
+			name: proj.name,
+			version: proj.version || '0.0.0',
+			path: proj.path,
+			status: 'unknown',
+			hours: 0,
+			iterations: 0,
+			rrs: 0,
+			branch: gitInfo.branch,
+			gitStatus: gitInfo.gitStatus,
+			tasks: [],
+			deadline: null,
+			daysRemaining: null,
+			priority: '1',
+			releasesCount: 0,
+			totalHours: 0,
+			totalIterations: 0,
+			allReleases: [],
+			sourceDoc: '',
+			sourceUserDoc: '',
+			userContent: '',
+			releaseContent: '',
+		}
+	}
+
+	async #scanAllReleases(db, discovered, primaryMetrics) {
+		let projectTotalHours = 0,
+			projectTotalIterations = 0
+		const allReleases = []
+
+		for (const rel of discovered) {
+			let relUser = ''
+			try {
+				relUser = (await db.loadDocument(`${rel.path}/user.md`, '')) || ''
+			} catch {}
+			const rm = parseUserMetrics(String(relUser || ''))
+			projectTotalHours += rm.hours
+			projectTotalIterations += rm.iterations
+
+			const {
+				releaseContent: relDocContent,
+				sourceDoc: relDocPath,
+				tasks: relTasks,
+			} = await loadReleaseDoc(db, rel.path)
+			const relFm = parseFrontmatter(relDocContent || relUser)
+			const hasRelSpec = await documentExists(db, `${rel.path}/task.spec.js`)
+			const hasRelTest = await documentExists(db, `${rel.path}/task.test.js`)
+
+			const relStatus = determineReleaseStatus({
+				fmStatus: relFm.status,
+				hasSpec: hasRelSpec,
+				hasTest: hasRelTest,
+				tasks: relTasks,
+				userStr: String(relUser || ''),
+				metrics: rm,
+			})
+
+			allReleases.push({
+				version: rel.version,
+				path: rel.path,
+				hours: rm.hours,
+				iterations: rm.iterations,
+				rrs: rm.rrs,
+				status: relStatus,
+				tasks: relTasks,
+				sourceDoc: relDocPath,
+			})
+		}
+
+		if (projectTotalHours === 0 && primaryMetrics.hours > 0)
+			projectTotalHours = primaryMetrics.hours
+		if (projectTotalIterations === 0 && primaryMetrics.iterations > 0)
+			projectTotalIterations = primaryMetrics.iterations
+		return { allReleases, projectTotalHours, projectTotalIterations }
+	}
+}