fix: preserve comments and format in package.yaml (#225)

* fix: preserve comments and format in package.yaml

* test: fixes to package.yaml tests

* chore: update deps

---------

Co-authored-by: Anthony Fu <github@antfu.me>

Author: danielbayley

src/io/packageYaml.ts

@@ -1,10 +1,11 @@
+import type { Document as DocumentType } from 'yaml'
 import type { CommonOptions, DepType, PackageMeta, RawDep } from '../types'
 import * as fs from 'node:fs/promises'
 import detectIndent from 'detect-indent'
 import { resolve } from 'pathe'
-import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
+import { Document, parseDocument as parseYaml, stringify as stringifyYaml } from 'yaml'
 import { builtinAddons } from '../addons'
-import { dumpDependencies, getByPath, parseDependencies, parseDependency, setByPath } from './dependencies'
+import { dumpDependencies, getByPath, parseDependencies, parseDependency } from './dependencies'
 
 const allDepsFields = [
   'dependencies',
@@ -21,20 +22,21 @@ function isDepFieldEnabled(key: DepType, options: CommonOptions): boolean {
   return key === 'peerDependencies' ? !!options.peer : options.depFields?.[key] !== false
 }
 
-export async function readYAML(filepath: string): Promise<Record<string, unknown>> {
+export async function readYAML(filepath: string): Promise<DocumentType> {
   const content = await fs.readFile(filepath, 'utf-8')
   if (!content)
-    return {}
+    return new Document({})
 
-  const parsed = parseYaml(content)
+  const document = parseYaml(content, { merge: true })
+  const parsed = document.toJS()
 
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+  if (document.errors.length || typeof parsed !== 'object' || Array.isArray(parsed))
     throw new TypeError(`Invalid package.yaml structure in ${filepath}`)
 
-  return parsed as Record<string, unknown>
+  return document
 }
 
-export async function writeYAML(filepath: string, data: Record<string, unknown>) {
+export async function writeYAML(filepath: string, data: DocumentType | Record<string, unknown>) {
   const { amount, type } = await fs.readFile(filepath, 'utf-8')
     .then(detectIndent)
     .catch(Object.create)
@@ -64,22 +66,23 @@ export async function loadPackageYAML(
       continue
 
     if (key === 'packageManager') {
-      if (raw.packageManager && typeof raw.packageManager === 'string') {
-        const [name, version] = raw.packageManager.split('@')
+      const packageManager = raw.get(key)
+      if (typeof packageManager === 'string') {
+        const [name, version] = packageManager.split('@')
         // `+` sign can be used to pin the hash of the package manager, we remove it to be semver compatible.
         deps.push(parseDependency(name, `^${version.split('+')[0]}`, 'packageManager', shouldUpdate))
       }
     }
     else {
-      deps.push(...parseDependencies(raw, key, shouldUpdate))
+      deps.push(...parseDependencies(raw.toJS(), key, shouldUpdate))
     }
   }
 
   return [
     {
-      name: typeof raw.name === 'string' ? raw.name : '',
-      private: !!raw.private,
-      version: typeof raw.version === 'string' ? raw.version : '',
+      name: raw.get('name') as string ?? '',
+      private: !!raw.get('private'),
+      version: raw.get('version') as string ?? '',
       type: 'package.yaml',
       relative,
       filepath,
@@ -101,16 +104,18 @@ export async function writePackageYAML(
       continue
 
     if (key === 'packageManager') {
-      const value = Object.entries(dumpDependencies(pkg.resolved, 'packageManager'))[0]
+      const [value] = Object.entries(dumpDependencies(pkg.resolved, 'packageManager'))
       if (value) {
-        pkg.raw ||= {}
-        pkg.raw.packageManager = `${value[0]}@${value[1].replace('^', '')}`
+        pkg.raw ??= new Document({})
+        pkg.raw.set('packageManager', `${value[0]}@${value[1].replace('^', '')}`)
         changed = true
       }
     }
     else {
-      if (getByPath(pkg.raw, key)) {
-        setByPath(pkg.raw, key, dumpDependencies(pkg.resolved, key))
+      if (getByPath(pkg.raw?.toJS?.(), key)) {
+        const values = Object.entries(dumpDependencies(pkg.resolved, key))
+        values.forEach(([lastKey, value]) =>
+          pkg.raw?.setIn([...key.split('.'), lastKey], value))
         changed = true
       }
     }

src/types.ts

@@ -1,5 +1,6 @@
 import type { Agent } from 'package-manager-detector'
 import type { PnpmWorkspaceYaml } from 'pnpm-workspace-yaml'
+import type { Document } from 'yaml'
 import type { MODE_CHOICES } from './constants'
 import type { SortOption } from './utils/sort'
 
@@ -241,9 +242,9 @@ export interface PackageYamlMeta extends BasePackageMeta {
    */
   type: 'package.yaml'
   /**
-   * Raw package.yaml Object
+   * Raw package.yaml Document
    */
-  raw: Record<string, unknown>
+  raw: Document
 }
 
 export type PackageMeta

test/packageYaml.test.ts

@@ -1,6 +1,8 @@
+import type { Document as DocumentType } from 'yaml'
 import type { CheckOptions, PackageYamlMeta } from '../src/types'
 import process from 'node:process'
 import { afterEach, beforeEach, describe, expect, it, vi, vitest } from 'vitest'
+import { Document } from 'yaml'
 import { CheckPackages } from '../src'
 import * as packageYaml from '../src/io/packageYaml'
 
@@ -111,7 +113,7 @@ describe('package.yaml functionality', () => {
       type: 'package.yaml',
       filepath: '/tmp/package.yaml',
       relative: 'package.yaml',
-      raw: {
+      raw: new Document({
         name: '@taze/package-yaml-example',
         version: '1.0.0',
         dependencies: {
@@ -122,7 +124,7 @@ describe('package.yaml functionality', () => {
           '@types/lodash': '^4.14.0',
           'typescript': '3.5',
         },
-      },
+      }),
       deps: [],
       resolved: [
         {
@@ -165,8 +167,8 @@ describe('package.yaml functionality', () => {
 version: "1.0.0"
 # This is a comment
 dependencies:
-  lodash: "^4.13.19"  # inline comment
-  express: "4.12.x"
+  lodash: ^4.13.19 # inline comment
+  express: 4.12.x
 
 devDependencies:
   typescript: "3.5"
@@ -177,12 +179,43 @@ devDependencies:
     // Mock readFile to return our YAML content
     vi.mocked(await import('node:fs/promises')).readFile = vi.fn().mockResolvedValue(yamlContent)
 
-    const raw = await packageYaml.readYAML(filepath)
+    const doc: DocumentType = await packageYaml.readYAML(filepath)
+    const raw = doc.toJS()
+
     expect(raw.name).toBe('@taze/test')
     expect(raw.dependencies).toEqual({
       lodash: '^4.13.19',
       express: '4.12.x',
     })
+
+    const pkgYaml: PackageYamlMeta = {
+      name: raw.name,
+      version: raw.version,
+      private: false,
+      type: 'package.yaml',
+      filepath: '/tmp/package.yaml',
+      relative: 'package.yaml',
+      raw: doc,
+      deps: [],
+      resolved: [
+        {
+          name: 'lodash',
+          currentVersion: '^4.13.19',
+          targetVersion: '^4.17.21',
+          source: 'dependencies',
+          update: true,
+          diff: 'minor',
+          pkgData: { tags: { latest: '4.17.21' }, versions: ['4.17.21'] },
+          provenanceDowngraded: false,
+        },
+      ],
+    }
+
+    await packageYaml.writePackageYAML(pkgYaml, {})
+
+    expect(output).toContain('# This is a comment')
+    expect(output).toContain('# inline comment')
+    expect(output).toBe(yamlContent.replace('4.13.19', '4.17.21'))
   })
 
   it('should detect package.yaml as higher priority than package.json', async () => {