Change to require file, return nothing

*   you must pass an actual vfile yourself
*   you get nothing back, the file you pass is modified

lib/index.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import('vfile').VFileCompatible} VFileCompatible
+ * @typedef {import('vfile').VFile} VFile
  * @typedef {import('vfile').VFileOptions} VFileOptions
  */
 
@@ -38,7 +38,7 @@
  *   Move.
  * @param {VFile} file
  *   File to change.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
  */
 
@@ -55,8 +55,6 @@
  *       `Spec`
  */
 
-import {VFile} from 'vfile'
-
 const own = {}.hasOwnProperty
 
 // Order of renaming properties.
@@ -70,25 +68,21 @@ const order = /** @type {const} */ ([
   'dirname'
 ])
 
-// To do: next major: only allow actual vfiles.
-// To do: next major: don’t return given file.
 /**
  * Rename a file.
  *
  * When given something, returns a vfile from that, and changes its path
  * properties.
  *
- * @param {VFileCompatible | null | undefined} [value]
+ * @param {VFile} file
  *   File to rename.
  * @param {Renames | null | undefined} [renames]
  *   Rename instructions.
- * @returns {VFile}
- *   The renamed `file`.
+ * @returns {undefined}
+ *   Nothing.
  */
-export function rename(value, renames) {
-  const file = value instanceof VFile ? value : new VFile(value)
+export function rename(file, renames) {
   convert(renames)(file)
-  return file
 }
 
 /**

readme.md

@@ -113,7 +113,7 @@ properties.
 
 ###### Returns
 
-The renamed `file` (`VFile`).
+Nothing (`undefined`).
 
 ### `convert(renames)`
 
@@ -140,7 +140,7 @@ Move (TypeScript type).
 
 ###### Returns
 
-Nothing (`void`).
+Nothing (`undefined`).
 
 ### `Renames`
 

test.js

@@ -16,73 +16,60 @@ test('rename', async function () {
   )
 
   let file = toVFile('index.js')
-  assert.equal(rename(file, 'main.js'), file, 'should return the file')
+  assert.equal(rename(file, 'main.js'), undefined, 'should return nothing')
 
   file = toVFile('index.js')
-  assert.equal(
-    rename(file, 'main.js').path,
-    'main.js',
-    'should rename the file'
-  )
+  rename(file, 'main.js')
+  assert.equal(file.path, 'main.js', 'should rename the file')
 
   file = toVFile('index.js')
-  assert.equal(rename(file).path, 'index.js', 'should ignore a missing rename')
+  rename(file)
+  assert.equal(file.path, 'index.js', 'should ignore a missing rename')
 
-  assert.equal(String(rename()), '', 'should create a toVFile (#1)')
-  assert.equal(String(rename('!')), '!', 'should create a toVFile (#2)')
-  assert.equal(rename({path: '/'}).path, '/', 'should create a toVFile (#3)')
+  // .
+  // assert.equal(String(rename()), '', 'should create a toVFile (#1)')
+  // assert.equal(String(rename('!')), '!', 'should create a toVFile (#2)')
+  // assert.equal(rename({path: '/'}).path, '/', 'should create a toVFile (#3)')
 
   file = toVFile('index.js')
-  assert.equal(rename(file, '.ts').path, 'index.ts', 'should set extname')
+  rename(file, '.ts')
+  assert.equal(file.path, 'index.ts', 'should set extname')
 
   file = toVFile('.dot')
-  assert.equal(rename(file, '.js').path, '.dot.js', 'should support dotfiles')
+  rename(file, '.js')
+  assert.equal(file.path, '.dot.js', 'should support dotfiles')
 
   file = toVFile('index.js')
-  assert.equal(
-    rename(file, move).path,
-    'main.js',
-    'should support a function (#1)'
-  )
+  rename(file, move)
+  assert.equal(file.path, 'main.js', 'should support a function (#1)')
 
   file = toVFile()
-  assert.equal(
-    rename(file, move).path,
-    'main',
-    'should support a function (#2)'
-  )
+  rename(file, move)
+  assert.equal(file.path, 'main', 'should support a function (#2)')
 
   file = toVFile('index.js')
-  assert.equal(
-    rename(file, {stem: 'main'}).path,
-    'main.js',
-    'should support a spec (#1)'
-  )
+  rename(file, {stem: 'main'})
+  assert.equal(file.path, 'main.js', 'should support a spec (#1)')
 
   file = toVFile('index.js')
-  assert.equal(
-    rename(file, {stem: 'readme', extname: '.md'}).path,
-    'readme.md',
-    'should support a spec (#2)'
-  )
+  rename(file, {stem: 'readme', extname: '.md'})
+  assert.equal(file.path, 'readme.md', 'should support a spec (#2)')
 
   file = toVFile({basename: 'index.js', dirname: 'example'})
+  rename(file, {stem: {suffix: '-1'}, dirname: {prefix: 'an-'}})
   assert.equal(
-    rename(file, {stem: {suffix: '-1'}, dirname: {prefix: 'an-'}}).path,
+    file.path,
     path.join('an-example', 'index-1.js'),
     'should support a spec (#3)'
   )
 
   file = toVFile('main.md')
-  assert.equal(
-    rename(file, ['readme.htm', {stem: 'index', extname: {suffix: 'l'}}]).path,
-    'index.html',
-    'should support multiple renames'
-  )
+  rename(file, ['readme.htm', {stem: 'index', extname: {suffix: 'l'}}])
+  assert.equal(file.path, 'index.html', 'should support multiple renames')
 
   assert.throws(
     function () {
-      // @ts-expect-error runtime.
+      // @ts-expect-error check that a runtime error is thrown.
       rename(toVFile(), 1)
     },
     /Expected function, string, array, or object as renames/,
@@ -91,7 +78,7 @@ test('rename', async function () {
 
   assert.throws(
     function () {
-      // @ts-expect-error runtime.
+      // @ts-expect-error check that a runtime error is thrown.
       rename(toVFile(), {other: '!'})
     },
     /Cannot rename `other`: it’s not a path property/,