Move to @import syntax

Author: bcomnes

bin.js

@@ -1,5 +1,10 @@
 #!/usr/bin/env node
 
+/**
+ * @import {DomStackOpts as DomStackOpts} from './lib/builder.js'
+ * @import { ArgscloptsParseArgsOptionsConfig } from 'argsclopts'
+ */
+
 import { readFile } from 'node:fs/promises'
 import { resolve, join, relative } from 'node:path'
 import { parseArgs } from 'node:util'
@@ -19,11 +24,6 @@ import { DomStackAggregateError } from './lib/helpers/dom-stack-aggregate-error.
 import { generateTreeData } from './lib/helpers/generate-tree-data.js'
 import { askYesNo } from './lib/helpers/cli-prompt.js'
 
-/**
- * @import {DomStackOpts as DomStackOpts} from './lib/builder.js'
- * @import { ArgscloptsParseArgsOptionsConfig } from 'argsclopts'
- */
-
 const __dirname = import.meta.dirname
 
 async function getPkg () {

dependencygraph.svg

@@ -1,11 +1,21 @@
+/**
+ * @import { DomStackOpts as DomStackOpts, Results } from './lib/builder.js'
+ * @import { FSWatcher, Stats } from 'node:fs'
+ * @import { PostVarsFunction, LayoutFunction } from './lib/build-pages/page-data.js'
+ * @import { PageFunction } from './lib/build-pages/page-builders/page-writer.js'
+ * @import { TemplateFunction } from './lib/build-pages/page-builders/template-builder.js'
+ * @import { TemplateAsyncIterator } from './lib/build-pages/page-builders/template-builder.js'
+ * @import { TemplateOutputOverride } from './lib/build-pages/page-builders/template-builder.js'
+ * @import { BuildOptions } from 'esbuild'
+*/
 import { once } from 'events'
 import assert from 'node:assert'
 import chokidar from 'chokidar'
 import { basename, relative, resolve } from 'node:path'
-// @ts-ignore
+// @ts-expect-error
 import makeArray from 'make-array'
 import ignore from 'ignore'
-// @ts-ignore
+// @ts-expect-error
 import cpx from 'cpx2'
 import { inspect } from 'util'
 import browserSync from 'browser-sync'
@@ -16,41 +26,36 @@ import { builder } from './lib/builder.js'
 import { DomStackAggregateError } from './lib/helpers/dom-stack-aggregate-error.js'
 
 /**
- * @import { DomStackOpts as DomStackOpts, Results } from './lib/builder.js'
- * @import { FSWatcher, Stats } from 'node:fs'
-*/
-
-/**
- * @typedef {import('esbuild').BuildOptions} BuildOptions
+ * @typedef {BuildOptions} BuildOptions
  */
 
 /**
  * @template {Record<string, any>} T
- * @typedef {import('./lib/build-pages/resolve-layout.js').LayoutFunction<T>} LayoutFunction
+ * @typedef {LayoutFunction<T>} LayoutFunction
  */
 
 /**
  * @template {Record<string, any>} T
- * @typedef {import('./lib/build-pages/resolve-vars.js').PostVarsFunction<T>} PostVarsFunction
+ * @typedef {PostVarsFunction<T>} PostVarsFunction
  */
 
 /**
  * @template {Record<string, any>} T
- * @typedef {import('./lib/build-pages/page-builders/page-writer.js').PageFunction<T>} PageFunction
+ * @typedef {PageFunction<T>} PageFunction
  */
 
 /**
  * @template {Record<string, any>} T
- * @typedef {import('./lib/build-pages/page-builders/template-builder.js').TemplateFunction<T>} TemplateFunction
+ * @typedef {TemplateFunction<T>} TemplateFunction
  */
 
 /**
  * @template {Record<string, any>} T
- * @typedef {import('./lib/build-pages/page-builders/template-builder.js').TemplateAsyncIterator<T>} TemplateAsyncIterator
+ * @typedef {TemplateAsyncIterator<T>} TemplateAsyncIterator
  */
 
 /**
- * @typedef {import('./lib/build-pages/page-builders/template-builder.js').TemplateOutputOverride} TemplateOutputOverride
+ * @typedef {TemplateOutputOverride} TemplateOutputOverride
  */
 
 const DEFAULT_IGNORES = /** @type {const} */ ([

index.js

@@ -1,20 +1,18 @@
-// @ts-ignore
+/**
+ * @import { BuildStepResult, BuildStep } from '../builder.js'
+ */
+
+// @ts-expect-error
 import cpx from 'cpx2'
 import { join } from 'node:path'
 const copy = cpx.copy
 
 /**
+ * @typedef {BuildStepResult<'static', CopyBuilderReport>} CopyBuildStepResult
+ * @typedef {BuildStep<'static', CopyBuilderReport>} CopyBuildStep
  * @typedef {Awaited<ReturnType<typeof copy>>} CopyBuilderReport
  */
 
-/**
- * @typedef {import('../builder.js').BuildStepResult<'static', CopyBuilderReport>} CopyBuildStepResult
- */
-
-/**
- * @typedef {import('../builder.js').BuildStep<'static', CopyBuilderReport>} CopyBuildStep
- */
-
 /**
  * @param  {string[]} copy
  * @return {string[]}

lib/build-copy/index.js

@@ -1,3 +1,7 @@
+/**
+ * @import { BuildStep } from '../builder.js'
+ */
+
 import { writeFile } from 'fs/promises'
 import { join, relative, basename } from 'path'
 import esbuild from 'esbuild'
@@ -13,7 +17,7 @@ const DOM_STACK_DEFAULTS_PREFIX = 'dom-stack-defaults'
  * @typedef {esbuild.BuildOptions} EsbuildBuildOptions
  * @typedef {Awaited<ReturnType<esbuild.build>>} EsbuildBuildResults
 
- * @typedef {import('../builder.js').BuildStep<
+ * @typedef {BuildStep<
  *          'esbuild',
  *         {
  *           buildResults?: EsbuildBuildResults
@@ -23,7 +27,8 @@ const DOM_STACK_DEFAULTS_PREFIX = 'dom-stack-defaults'
  * >} EsBuildStep
  */
 
-/** @typedef {Awaited<ReturnType<EsBuildStep>>} EsBuildStepResults
+/**
+ * @typedef {Awaited<ReturnType<EsBuildStep>>} EsBuildStepResults
  */
 
 /**

lib/build-esbuild/index.js

@@ -1,16 +1,17 @@
+/**
+ * @import { BuilderOptions } from './page-builders/page-writer.js'
+ * @import { BuildStep } from '../builder.js'
+ * @import { LayoutFunction } from './page-data.js'
+ */
+
 import { Worker } from 'worker_threads'
 import { join } from 'path'
 import pMap from 'p-map'
 import { cpus } from 'os'
-
-/**
- * @import { BuilderOptions } from './page-builders/page-writer.js'
- */
 import { keyBy } from '../helpers/key-by.js'
 import { resolveVars } from './resolve-vars.js'
-import { resolveLayout } from './resolve-layout.js'
 import { pageBuilders, templateBuilder } from './page-builders/index.js'
-import { PageData } from './page-data.js'
+import { PageData, resolveLayout } from './page-data.js'
 import { pageWriter } from './page-builders/page-writer.js'
 
 const MAX_CONCURRENCY = Math.min(cpus().length, 24)
@@ -25,21 +26,16 @@ const __dirname = import.meta.dirname
  */
 
 /**
- * @typedef {import('../builder.js').BuildStep<
+ * @typedef {BuildStep<
  *          'page',
  *          PageBuilderReport
- *          >} PageBuildStep
+ *   >} PageBuildStep
  */
 
 /**
  * @typedef {Awaited<ReturnType<PageBuildStep>>} PageBuildStepResult
  */
 
-/**
- * @template T
- * @typedef {import('./resolve-layout.js').LayoutFunction<T>} LayoutFunction
- */
-
 /**
  * @template T
  * @typedef ResolvedLayout

lib/build-pages/index.js

@@ -1,11 +1,15 @@
+/**
+ * @import { PageBuilderType } from '../page-writer.js'
+ */
+
 import assert from 'node:assert'
 import { readFile } from 'fs/promises'
 import Handlebars from 'handlebars'
 
 /**
  * Build all of the bundles using esbuild.
  * @template {Record<string, any>} T
- * @type {import('../page-writer.js').PageBuilderType<T>}
+ * @type {PageBuilderType<T>}
  */
 export async function htmlBuilder ({ pageInfo }) {
   assert(pageInfo.type === 'html', 'html builder requires a "html" page type')

lib/build-pages/page-builders/html/index.js

@@ -1,9 +1,13 @@
+/**
+ * @import { PageBuilderType } from '../page-writer.js'
+ */
+
 import assert from 'node:assert'
 
 /**
  * Build all of the bundles using esbuild.
  * @template {Record<string, any>} T
- * @type {import('../page-writer.js').PageBuilderType<T>}
+ * @type {PageBuilderType<T>}
  */
 export async function jsBuilder ({ pageInfo }) {
   assert(pageInfo.type === 'js', 'js page builder requires "js" page type')

lib/build-pages/page-builders/js/index.js

@@ -1,5 +1,6 @@
 /**
  * @import markdownIt from 'markdown-it'
+ * @import { PageBuilderType } from '../page-writer.js'
  */
 import assert from 'node:assert'
 import { readFile } from 'fs/promises'
@@ -14,7 +15,7 @@ let md = null
 /**
  * Build all of the bundles using esbuild.
  * @template {Record<string, any>} T
- * @type {import('../page-writer.js').PageBuilderType<T>}
+ * @type {PageBuilderType<T>}
  */
 export async function mdBuilder ({ pageInfo, options }) {
   assert(pageInfo.type === 'md', 'md builder requires an "md" page type')

lib/build-pages/page-builders/md/index.js

@@ -1,20 +1,19 @@
-import { join } from 'path'
-import { writeFile, mkdir } from 'fs/promises'
-
 /**
- * @typedef {import('../../identify-pages.js').PageInfo} PageInfo
- * @typedef {import('../../builder.js').SiteData} SiteData
- * @typedef {import('../../identify-pages.js').PageFileAsset} PageFileAsset
+ * @import { PageInfo } from '../../identify-pages.js'
+ * @import { PageData } from '../page-data.js'
  */
 
+import { join } from 'path'
+import { writeFile, mkdir } from 'fs/promises'
+
 /**
  * @typedef {Object} BuilderOptions
  * @property {string | null | undefined} [markdownItSettingsPath] - Path to the markdown-it settings file
  */
 
 /**
  * @template {Record<string, any>} T
- * @typedef {import('../page-data.js').PageData<T>} PageData
+ * @typedef {PageData<T>} PageData
  */
 
 /**