nuxt-spec 0.4.0-alpha.2 → 0.4.0-alpha.3

package/config/utils/warnings.mjs

@@ -1,38 +1,38 @@
-const messageFilters = [
-  // Node+Windows false positive
-  // https://github.com/nuxt/icon/issues/140
-  'Use of deprecated trailing slash pattern mapping',
-  // remove once Vue stops considering <Suspense> experimental
-  '<Suspense> is an experimental feature',
-]
-
-// merge user-defined filters (`spec.messageFilters` / NUXT_SPEC_MESSAGE_FILTERS) with defaults
-export function addMessageFilters(filters) {
-  for (const filter of filters) {
-    if (filter && !messageFilters.includes(filter)) {
-      messageFilters.push(filter)
-    }
-  }
-}
-
-// 1) filter-out unnecessary stderr/stdout logs coming from Vitest
-// (applied as side-effect on import)
-
-const _stderrWrite = process.stderr.write.bind(process.stderr)
-process.stderr.write = (chunk, ...args) => {
-  if (typeof chunk === 'string' && messageFilters.some(f => chunk.includes(f))) return true
-  return _stderrWrite(chunk, ...args)
-}
-
-const _stdoutWrite = process.stdout.write.bind(process.stdout)
-process.stdout.write = (chunk, ...args) => {
-  if (typeof chunk === 'string' && messageFilters.some(f => chunk.includes(f))) return true
-  return _stdoutWrite(chunk, ...args)
-}
-
-// 2) filter-out unnecessary console logs coming from Vitest
-// (used as Vitest onConsoleLog hook)
-
-export function onConsoleLog(log) {
-  if (messageFilters.some(f => log.includes(f))) return false
-}
+const messageFilters = [
+  // Node+Windows false positive
+  // https://github.com/nuxt/icon/issues/140
+  'Use of deprecated trailing slash pattern mapping',
+  // remove once Vue stops considering <Suspense> experimental
+  '<Suspense> is an experimental feature',
+]
+
+// merge user-defined filters (`spec.messageFilters` / NUXT_SPEC_MESSAGE_FILTERS) with defaults
+export function addMessageFilters(filters) {
+  for (const filter of filters) {
+    if (filter && !messageFilters.includes(filter)) {
+      messageFilters.push(filter)
+    }
+  }
+}
+
+// 1) filter-out unnecessary stderr/stdout logs coming from Vitest
+// (applied as side-effect on import)
+
+const _stderrWrite = process.stderr.write.bind(process.stderr)
+process.stderr.write = (chunk, ...args) => {
+  if (typeof chunk === 'string' && messageFilters.some(f => chunk.includes(f))) return true
+  return _stderrWrite(chunk, ...args)
+}
+
+const _stdoutWrite = process.stdout.write.bind(process.stdout)
+process.stdout.write = (chunk, ...args) => {
+  if (typeof chunk === 'string' && messageFilters.some(f => chunk.includes(f))) return true
+  return _stdoutWrite(chunk, ...args)
+}
+
+// 2) filter-out unnecessary console logs coming from Vitest
+// (used as Vitest onConsoleLog hook)
+
+export function onConsoleLog(log) {
+  if (messageFilters.some(f => log.includes(f))) return false
+}

package/modules/spec-options.ts

@@ -1,23 +1,23 @@
-import { defineNuxtModule } from 'nuxt/kit'
-import type { ModuleDependencies, NuxtModule } from 'nuxt/schema'
-import { resolveSpecOptions } from '../config/utils/options.mjs'
-import type { NuxtSpecOptions } from '../config/utils/options.mjs'
-
-// registers typed `spec` key for nuxt.config.ts and applies its Nuxt-related options
-// options related to Vitest are resolved in `loadVitestConfig` (config/index.mjs)
-// (explicit types break circular reference with module types generated by Nuxt)
-const specOptionsModule: NuxtModule<NuxtSpecOptions> = defineNuxtModule<NuxtSpecOptions>({
-  meta: {
-    name: 'nuxt-spec',
-    configKey: 'spec',
-    // used as `@see` link in generated types (fallback would be a broken npm URL)
-    docs: 'https://nuxt-spec.netlify.app/2-1-configuration.html#nuxt-spec-options',
-  },
-  moduleDependencies: (nuxt): ModuleDependencies => {
-    // `spec` is typed only after Nuxt generates module types
-    const { spec } = nuxt.options as unknown as { spec?: NuxtSpecOptions | false }
-    return resolveSpecOptions(spec).hints ? { '@nuxt/hints': {} } : {}
-  },
-})
-
-export default specOptionsModule
+import { defineNuxtModule } from 'nuxt/kit'
+import type { ModuleDependencies, NuxtModule } from 'nuxt/schema'
+import { resolveSpecOptions } from '../config/utils/options.mjs'
+import type { NuxtSpecOptions } from '../config/utils/options.mjs'
+
+// registers typed `spec` key for nuxt.config.ts and applies its Nuxt-related options
+// options related to Vitest are resolved in `loadVitestConfig` (config/index.mjs)
+// (explicit types break circular reference with module types generated by Nuxt)
+const specOptionsModule: NuxtModule<NuxtSpecOptions> = defineNuxtModule<NuxtSpecOptions>({
+  meta: {
+    name: 'nuxt-spec',
+    configKey: 'spec',
+    // used as `@see` link in generated types (fallback would be a broken npm URL)
+    docs: 'https://nuxt-spec.netlify.app/2-1-configuration.html#nuxt-spec-options',
+  },
+  moduleDependencies: (nuxt): ModuleDependencies => {
+    // `spec` is typed only after Nuxt generates module types
+    const { spec } = nuxt.options as unknown as { spec?: NuxtSpecOptions | false }
+    return resolveSpecOptions(spec).hints ? { '@nuxt/hints': {} } : {}
+  },
+})
+
+export default specOptionsModule

package/nuxt.config.ts

@@ -1,20 +1,20 @@
-export default defineNuxtConfig({
-  modules: [
-    '@nuxt/eslint',
-    '@nuxt/test-utils/module',
-    // @nuxt/hints module is handled in `modules/spec-options.ts`
-  ],
-
-  // exclude file used for explicit exports (nuxt-spec/components) from Nuxt resolution
-  components: {
-    dirs: [{ path: '~/components', ignore: ['index.ts'] }],
-  },
-
-  compatibilityDate: '2026-10-13',
-
-  eslint: {
-    config: {
-      stylistic: true,
-    },
-  },
-})
+export default defineNuxtConfig({
+  modules: [
+    '@nuxt/eslint',
+    '@nuxt/test-utils/module',
+    // @nuxt/hints module is handled in `modules/spec-options.ts`
+  ],
+
+  // exclude file used for explicit exports (nuxt-spec/components) from Nuxt resolution
+  components: {
+    dirs: [{ path: '~/components', ignore: ['index.ts'] }],
+  },
+
+  compatibilityDate: '2026-10-13',
+
+  eslint: {
+    config: {
+      stylistic: true,
+    },
+  },
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-spec",
-  "version": "0.4.0-alpha.2",
+  "version": "0.4.0-alpha.3",
   "description": "Test-pack layer for Nuxt Applications",
   "repository": {
     "type": "git",
@@ -9,24 +9,6 @@
   "license": "MIT",
   "type": "module",
   "main": "./nuxt.config.ts",
-  "scripts": {
-    "analyze": "nuxt analyze",
-    "eslint": "eslint .",
-    "typecheck": "nuxi typecheck",
-    "build": "nuxt build",
-    "dev": "nuxt dev",
-    "generate": "nuxt generate",
-    "prepublishOnly": "node bin/_internal/prepublish-check.js",
-    "preview": "nuxt preview",
-    "start": "nuxt start",
-    "test": "vitest run",
-    "test-u": "vitest run -u",
-    "test-c": "vitest run --coverage",
-    "test-i": "vitest"
-  },
-  "bin": {
-    "nuxt-spec": "bin/cli.js"
-  },
   "exports": {
     ".": "./nuxt.config.ts",
     "./config": {
@@ -46,7 +28,6 @@
   },
   "files": [
     "app",
-    "bin",
     "config",
     "modules",
     "public",
@@ -65,7 +46,6 @@
     "@vitest/coverage-v8": "5.0.3",
     "@vitest/ui": "5.0.3",
     "@vue/test-utils": "2.5.1",
-    "elrh-cosca": "0.4.3",
     "fast-png": "~8.0.0",
     "happy-dom": "~20.14.5",
     "nuxt": "4.6.1",
@@ -79,5 +59,19 @@
     "vue-router": "~5.3.1",
     "vue-tsc": "~3.3.12"
   },
-  "packageManager": "pnpm@12.11.2"
-}
+  "scripts": {
+    "analyze": "nuxt analyze",
+    "eslint": "eslint .",
+    "typecheck": "nuxi typecheck",
+    "build": "nuxt build",
+    "dev": "nuxt dev",
+    "generate": "nuxt generate",
+    "preview": "nuxt preview",
+    "release": "node scripts/release.js",
+    "start": "nuxt start",
+    "test": "vitest run",
+    "test-u": "vitest run -u",
+    "test-c": "vitest run --coverage",
+    "test-i": "vitest"
+  }
+}

package/utils/e2e.ts

@@ -1,131 +1,131 @@
-import { createPage, url } from '@nuxt/test-utils/e2e'
-import type { GotoOptions, NuxtPage } from '@nuxt/test-utils'
-import { checkPageParam, checkStringParam } from './helpers/check-params'
-
-/**
- * Extra settings object for `gotoPage()` function.
- * All properties are optional.
- */
-export type GotoPageOptions = {
-  /** Event to be awaited before NuxtPage instance is returned (defaults to `'hydration'`) */
-  waitUntil?: GotoOptions['waitUntil']
-}
-
-/**
- * Visit a specified URL and return the page instance for further interaction.
- *
- * @param pageName - Path segment appended to the base URL (e.g. `'about'` → `/<about>`)
- * @param options - Optional extra settings (see `GotoPageOptions`)
- * @returns Playwright page instance after navigation and `hydration` event
- */
-export async function gotoPage(pageName: string, options?: GotoPageOptions): Promise<NuxtPage> {
-  const { waitUntil } = options ?? {}
-
-  // verify params
-  checkStringParam('gotoPage:pageName', pageName)
-  if (waitUntil) {
-    checkStringParam('gotoPage:options.waitUntil', waitUntil)
-  }
-
-  // construct NuxtPage instance
-  const page = await createPage()
-  const urlPath = pageName.startsWith('/') ? url(pageName) : url(`/${pageName}`)
-  await page.goto(urlPath, { waitUntil: waitUntil ?? 'hydration' })
-
-  return page
-}
-
-/**
- * Extra settings object for `getDataHtml()` function.
- * All properties are optional.
- */
-export type GetDataHtmlOptions = {
-  /** Event to be awaited before NuxtPage instance is returned (defaults to `'hydration'`) */
-  waitUntil?: GotoOptions['waitUntil']
-  /** CSS selector identifying the target element (defaults to `<body>` tag) */
-  element?: string
-}
-
-/**
- * Extract inner HTML content from a specified element on a given page.
- * If no element is specified via `options.element`, the entire `<body>` content is returned.
- *
- * @param page - Playwright page instance, or a page name string (will call `gotoPage` internally)
- * @param options - Optional extra settings (see `GetDataHtmlOptions`)
- * @returns The inner HTML of the matched element
- */
-export async function getDataHtml(page: NuxtPage | string, options?: GetDataHtmlOptions): Promise<string> {
-  const { waitUntil, element } = options ?? {}
-
-  // verify params
-  if (typeof page === 'string') {
-    checkStringParam('getDataHtml:page', page)
-  }
-  if (waitUntil) {
-    checkStringParam('getDataHtml:options.waitUntil', waitUntil)
-  }
-  if (element) {
-    checkStringParam('getDataHtml:options.element', element)
-  }
-
-  // get NuxtPage instance
-  const pageInstance = typeof page === 'string' ? await gotoPage(page, { waitUntil }) : page
-  checkPageParam('getDataHtml:pageInstance', pageInstance)
-
-  // extract target HTML
-  const dataElement = pageInstance.locator(element ?? 'body')
-  return await dataElement.innerHTML()
-}
-
-/**
- * Extra settings object for `getAPIResultHtml()` function.
- * Due to nature of the function, `triggerElement`, `targetUrl`, and `responseElement` are required.
- */
-export type GetAPIResultHtmlOptions = {
-  /** Event to be awaited before NuxtPage instance is returned (defaults to `'hydration'`) */
-  waitUntil?: GotoOptions['waitUntil']
-  /** CSS selector for the clickable element that triggers the API request (required) */
-  triggerElement: string
-  /** Substring matched against the response URL to identify the expected API call (required) */
-  targetUrl: string
-  /** CSS selector for the element displaying the API response (required) */
-  responseElement: string
-}
-
-/**
- * Execute an API call by clicking a trigger element, wait for a successful
- * response matching the target URL, then extract the inner HTML from the
- * response element.
- *
- * @param page - Playwright page instance, or a page name string (will call `gotoPage` internally)
- * @param options - Extra settings (see `GetAPIResultHtmlOptions`)
- * @returns The inner HTML of the response element
- */
-export async function getAPIResultHtml(page: NuxtPage | string, options: GetAPIResultHtmlOptions) {
-  const { waitUntil, triggerElement, targetUrl, responseElement } = options
-
-  // verify params
-  if (typeof page === 'string') {
-    checkStringParam('getAPIResultHtml:page', page)
-  }
-  if (waitUntil) {
-    checkStringParam('getAPIResultHtml:options.waitUntil', waitUntil)
-  }
-  checkStringParam('getAPIResultHtml:triggerElement', triggerElement)
-  checkStringParam('getAPIResultHtml:targetUrl', targetUrl)
-  checkStringParam('getAPIResultHtml:responseElement', responseElement)
-
-  // get NuxtPage instance
-  const pageInstance = typeof page === 'string' ? await gotoPage(page, { waitUntil }) : page
-  checkPageParam('getAPIResultHtml:pageInstance', pageInstance)
-
-  // trigger API call
-  await pageInstance.click(triggerElement)
-  await pageInstance.waitForResponse(response =>
-    response.url().includes(targetUrl) && response.ok(),
-  )
-
-  // extract target HTML
-  const dataElement = pageInstance.locator(responseElement)
-  return await dataElement.innerHTML()
-}
+import { createPage, url } from '@nuxt/test-utils/e2e'
+import type { GotoOptions, NuxtPage } from '@nuxt/test-utils'
+import { checkPageParam, checkStringParam } from './helpers/check-params'
+
+/**
+ * Extra settings object for `gotoPage()` function.
+ * All properties are optional.
+ */
+export type GotoPageOptions = {
+  /** Event to be awaited before NuxtPage instance is returned (defaults to `'hydration'`) */
+  waitUntil?: GotoOptions['waitUntil']
+}
+
+/**
+ * Visit a specified URL and return the page instance for further interaction.
+ *
+ * @param pageName - Path segment appended to the base URL (e.g. `'about'` → `/<about>`)
+ * @param options - Optional extra settings (see `GotoPageOptions`)
+ * @returns Playwright page instance after navigation and `hydration` event
+ */
+export async function gotoPage(pageName: string, options?: GotoPageOptions): Promise<NuxtPage> {
+  const { waitUntil } = options ?? {}
+
+  // verify params
+  checkStringParam('gotoPage:pageName', pageName)
+  if (waitUntil) {
+    checkStringParam('gotoPage:options.waitUntil', waitUntil)
+  }
+
+  // construct NuxtPage instance
+  const page = await createPage()
+  const urlPath = pageName.startsWith('/') ? url(pageName) : url(`/${pageName}`)
+  await page.goto(urlPath, { waitUntil: waitUntil ?? 'hydration' })
+
+  return page
+}
+
+/**
+ * Extra settings object for `getDataHtml()` function.
+ * All properties are optional.
+ */
+export type GetDataHtmlOptions = {
+  /** Event to be awaited before NuxtPage instance is returned (defaults to `'hydration'`) */
+  waitUntil?: GotoOptions['waitUntil']
+  /** CSS selector identifying the target element (defaults to `<body>` tag) */
+  element?: string
+}
+
+/**
+ * Extract inner HTML content from a specified element on a given page.
+ * If no element is specified via `options.element`, the entire `<body>` content is returned.
+ *
+ * @param page - Playwright page instance, or a page name string (will call `gotoPage` internally)
+ * @param options - Optional extra settings (see `GetDataHtmlOptions`)
+ * @returns The inner HTML of the matched element
+ */
+export async function getDataHtml(page: NuxtPage | string, options?: GetDataHtmlOptions): Promise<string> {
+  const { waitUntil, element } = options ?? {}
+
+  // verify params
+  if (typeof page === 'string') {
+    checkStringParam('getDataHtml:page', page)
+  }
+  if (waitUntil) {
+    checkStringParam('getDataHtml:options.waitUntil', waitUntil)
+  }
+  if (element) {
+    checkStringParam('getDataHtml:options.element', element)
+  }
+
+  // get NuxtPage instance
+  const pageInstance = typeof page === 'string' ? await gotoPage(page, { waitUntil }) : page
+  checkPageParam('getDataHtml:pageInstance', pageInstance)
+
+  // extract target HTML
+  const dataElement = pageInstance.locator(element ?? 'body')
+  return await dataElement.innerHTML()
+}
+
+/**
+ * Extra settings object for `getAPIResultHtml()` function.
+ * Due to nature of the function, `triggerElement`, `targetUrl`, and `responseElement` are required.
+ */
+export type GetAPIResultHtmlOptions = {
+  /** Event to be awaited before NuxtPage instance is returned (defaults to `'hydration'`) */
+  waitUntil?: GotoOptions['waitUntil']
+  /** CSS selector for the clickable element that triggers the API request (required) */
+  triggerElement: string
+  /** Substring matched against the response URL to identify the expected API call (required) */
+  targetUrl: string
+  /** CSS selector for the element displaying the API response (required) */
+  responseElement: string
+}
+
+/**
+ * Execute an API call by clicking a trigger element, wait for a successful
+ * response matching the target URL, then extract the inner HTML from the
+ * response element.
+ *
+ * @param page - Playwright page instance, or a page name string (will call `gotoPage` internally)
+ * @param options - Extra settings (see `GetAPIResultHtmlOptions`)
+ * @returns The inner HTML of the response element
+ */
+export async function getAPIResultHtml(page: NuxtPage | string, options: GetAPIResultHtmlOptions) {
+  const { waitUntil, triggerElement, targetUrl, responseElement } = options
+
+  // verify params
+  if (typeof page === 'string') {
+    checkStringParam('getAPIResultHtml:page', page)
+  }
+  if (waitUntil) {
+    checkStringParam('getAPIResultHtml:options.waitUntil', waitUntil)
+  }
+  checkStringParam('getAPIResultHtml:triggerElement', triggerElement)
+  checkStringParam('getAPIResultHtml:targetUrl', targetUrl)
+  checkStringParam('getAPIResultHtml:responseElement', responseElement)
+
+  // get NuxtPage instance
+  const pageInstance = typeof page === 'string' ? await gotoPage(page, { waitUntil }) : page
+  checkPageParam('getAPIResultHtml:pageInstance', pageInstance)
+
+  // trigger API call
+  await pageInstance.click(triggerElement)
+  await pageInstance.waitForResponse(response =>
+    response.url().includes(targetUrl) && response.ok(),
+  )
+
+  // extract target HTML
+  const dataElement = pageInstance.locator(responseElement)
+  return await dataElement.innerHTML()
+}

package/utils/helpers/check-params.ts

@@ -1,44 +1,44 @@
-import type { NuxtPage } from '@nuxt/test-utils'
-import { locationHint } from './location-hint'
-
-// given string param must be an actual non-empty string
-export function checkStringParam(paramName: string, paramValue?: string) {
-  if (!paramValue) {
-    console.warn(`[Nuxt Spec] Passed value '${paramName}' is missing or empty.\n${locationHint()}`)
-    return
-  }
-  if (typeof paramValue !== 'string') {
-    console.warn(`[Nuxt Spec] Passed value '${paramName}' is not a string.\n${locationHint()}`)
-  }
-}
-
-// given string param must be an actual number
-export function checkNumberParam(paramName: string, paramValue?: number) {
-  if (paramValue === undefined || paramValue === null) {
-    console.warn(`[Nuxt Spec] Passed value '${paramName}' is missing or empty.\n${locationHint()}`)
-    return
-  }
-  if (typeof paramValue !== 'number') {
-    console.warn(`[Nuxt Spec] Passed value '${paramName}' is not a number.\n${locationHint()}`)
-  }
-}
-
-// given NuxtPage param must be an actual non-nullish NuxtPage instance
-export function checkPageParam(paramName: string, paramValue?: NuxtPage) {
-  if (!paramValue) {
-    console.warn(`[Nuxt Spec] Passed value '${paramName}' is missing or empty.\n${locationHint()}`)
-    return
-  }
-  if (typeof paramValue !== 'object') {
-    console.warn(`[Nuxt Spec] Passed value '${paramName}' is not a NuxtPage.\n${locationHint()}`)
-  } else {
-    const pageInstance = paramValue as unknown as Record<string, unknown>
-    if (
-      typeof pageInstance.goto !== 'function'
-      || typeof pageInstance.locator !== 'function'
-      || typeof pageInstance.waitForResponse !== 'function'
-    ) {
-      console.warn(`[Nuxt Spec] Passed value '${paramName}' is not a NuxtPage.\n${locationHint()}`)
-    }
-  }
-}
+import type { NuxtPage } from '@nuxt/test-utils'
+import { locationHint } from './location-hint'
+
+// given string param must be an actual non-empty string
+export function checkStringParam(paramName: string, paramValue?: string) {
+  if (!paramValue) {
+    console.warn(`[Nuxt Spec] Passed value '${paramName}' is missing or empty.\n${locationHint()}`)
+    return
+  }
+  if (typeof paramValue !== 'string') {
+    console.warn(`[Nuxt Spec] Passed value '${paramName}' is not a string.\n${locationHint()}`)
+  }
+}
+
+// given string param must be an actual number
+export function checkNumberParam(paramName: string, paramValue?: number) {
+  if (paramValue === undefined || paramValue === null) {
+    console.warn(`[Nuxt Spec] Passed value '${paramName}' is missing or empty.\n${locationHint()}`)
+    return
+  }
+  if (typeof paramValue !== 'number') {
+    console.warn(`[Nuxt Spec] Passed value '${paramName}' is not a number.\n${locationHint()}`)
+  }
+}
+
+// given NuxtPage param must be an actual non-nullish NuxtPage instance
+export function checkPageParam(paramName: string, paramValue?: NuxtPage) {
+  if (!paramValue) {
+    console.warn(`[Nuxt Spec] Passed value '${paramName}' is missing or empty.\n${locationHint()}`)
+    return
+  }
+  if (typeof paramValue !== 'object') {
+    console.warn(`[Nuxt Spec] Passed value '${paramName}' is not a NuxtPage.\n${locationHint()}`)
+  } else {
+    const pageInstance = paramValue as unknown as Record<string, unknown>
+    if (
+      typeof pageInstance.goto !== 'function'
+      || typeof pageInstance.locator !== 'function'
+      || typeof pageInstance.waitForResponse !== 'function'
+    ) {
+      console.warn(`[Nuxt Spec] Passed value '${paramName}' is not a NuxtPage.\n${locationHint()}`)
+    }
+  }
+}

package/utils/helpers/location-hint.ts

@@ -1,30 +1,30 @@
-import { createRequire } from 'node:module'
-import { dirname } from 'node:path'
-
-// shows "(at path-to-file:line:column)" hint to locate cause from stack trace
-// this syntax allow tools like VS Code to create clickable link directly to the source
-export function locationHint(): string {
-  return `  (at ${getCallSite()})`
-}
-
-// path to nuxt-spec/utils directory computed on runtime
-const pkgUtilsDir = normalizePath(dirname(createRequire(import.meta.url).resolve('nuxt-spec/utils')))
-
-// handle possible Win backslashes
-function normalizePath(path: string): string {
-  return path.replace(/^file:\/\//, '').replace(/\\/g, '/')
-}
-
-// locate first stack frame outside of nuxt-spec utils
-// which will the place where the utility function is being called from
-function getCallSite(): string | undefined {
-  const stack = new Error().stack?.split('\n').slice(1) ?? []
-  for (const raw of stack) {
-    const match = raw.match(/\(?((?:file:\/\/)?[^()\s]+:\d+:\d+)\)?\s*$/)
-    if (!match?.[1]) continue
-    const location = normalizePath(match[1])
-    if (location.includes(pkgUtilsDir)) continue
-    return location
-  }
-  return undefined
-}
+import { createRequire } from 'node:module'
+import { dirname } from 'node:path'
+
+// shows "(at path-to-file:line:column)" hint to locate cause from stack trace
+// this syntax allow tools like VS Code to create clickable link directly to the source
+export function locationHint(): string {
+  return `  (at ${getCallSite()})`
+}
+
+// path to nuxt-spec/utils directory computed on runtime
+const pkgUtilsDir = normalizePath(dirname(createRequire(import.meta.url).resolve('nuxt-spec/utils')))
+
+// handle possible Win backslashes
+function normalizePath(path: string): string {
+  return path.replace(/^file:\/\//, '').replace(/\\/g, '/')
+}
+
+// locate first stack frame outside of nuxt-spec utils
+// which will the place where the utility function is being called from
+function getCallSite(): string | undefined {
+  const stack = new Error().stack?.split('\n').slice(1) ?? []
+  for (const raw of stack) {
+    const match = raw.match(/\(?((?:file:\/\/)?[^()\s]+:\d+:\d+)\)?\s*$/)
+    if (!match?.[1]) continue
+    const location = normalizePath(match[1])
+    if (location.includes(pkgUtilsDir)) continue
+    return location
+  }
+  return undefined
+}