From e41842f14708ba6ae099e6df137756662a1d892e Mon Sep 17 00:00:00 2001 From: btea <2356281422@qq.com> Date: Mon, 17 Aug 2026 08:50:45 +0800 Subject: [PATCH 1/2] refactor(core): replace parent-relative imports with `#` package imports --- packages/core/package.json | 18 ++++++++++++++++++ .../core/src/generators/ast-js/generate.mjs | 2 +- packages/core/src/generators/ast/generate.mjs | 9 +++++---- .../src/generators/json-simple/generate.mjs | 6 +++--- .../core/src/generators/metadata/generate.mjs | 5 +++-- .../src/generators/metadata/utils/parse.mjs | 17 +++++++++-------- .../generators/metadata/utils/resolveTypes.mjs | 5 +++-- .../src/generators/metadata/utils/slugger.mjs | 2 +- .../generators/metadata/utils/transformers.mjs | 9 +++++---- .../src/generators/metadata/utils/visitors.mjs | 7 ++++--- .../src/generators/metadata/utils/yaml.mjs | 2 +- .../core/src/logger/transports/console.mjs | 4 ++-- packages/core/src/logger/transports/github.mjs | 6 +++--- packages/core/src/logger/utils/colors.mjs | 2 +- packages/core/src/parsers/markdown.mjs | 2 +- packages/core/src/threading/chunk-worker.mjs | 4 ++-- packages/core/src/threading/index.mjs | 2 +- packages/core/src/threading/parallel.mjs | 2 +- .../core/src/utils/configuration/index.mjs | 12 ++++++------ .../core/src/utils/configuration/types.d.ts | 2 +- packages/core/src/utils/queries/index.mjs | 3 ++- .../core/src/utils/signature/parseList.mjs | 7 ++++--- .../core/src/utils/type-annotations/hast.mjs | 2 +- 23 files changed, 78 insertions(+), 52 deletions(-) diff --git a/packages/core/package.json b/packages/core/package.json index 301b441b3..50741dd9b 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -30,6 +30,24 @@ "./src/*.d.ts" ] }, + "imports": { + "#generators/*": [ + "./src/generators/*", + "./src/generators/*.d.ts" + ], + "#logger/*": [ + "./src/logger/*", + "./src/logger/*.d.ts" + ], + "#parsers/*": [ + "./src/parsers/*", + "./src/parsers/*.d.ts" + ], + "#utils/*": [ + "./src/utils/*", + "./src/utils/*.d.ts" + ] + }, "files": [ "src", "!src/**/*.test.mjs", diff --git a/packages/core/src/generators/ast-js/generate.mjs b/packages/core/src/generators/ast-js/generate.mjs index 303e5ec05..2581a22f3 100644 --- a/packages/core/src/generators/ast-js/generate.mjs +++ b/packages/core/src/generators/ast-js/generate.mjs @@ -6,7 +6,7 @@ import { extname } from 'node:path'; import { parse } from 'acorn'; import { globSync } from 'tinyglobby'; -import getConfig from '../../utils/configuration/index.mjs'; +import getConfig from '#utils/configuration/index.mjs'; /** * Process a chunk of JavaScript files in a worker thread. diff --git a/packages/core/src/generators/ast/generate.mjs b/packages/core/src/generators/ast/generate.mjs index 1808c6b11..81ef3f4ca 100644 --- a/packages/core/src/generators/ast/generate.mjs +++ b/packages/core/src/generators/ast/generate.mjs @@ -7,11 +7,12 @@ import globParent from 'glob-parent'; import { globSync } from 'tinyglobby'; import { parse as parseYaml } from 'yaml'; +import getConfig from '#utils/configuration/index.mjs'; +import { withExt } from '#utils/file.mjs'; +import { QUERIES } from '#utils/queries/index.mjs'; +import { getRemark as remark, getRemarkMdx } from '#utils/remark.mjs'; + import { STABILITY_INDEX_URL } from './constants.mjs'; -import getConfig from '../../utils/configuration/index.mjs'; -import { withExt } from '../../utils/file.mjs'; -import { QUERIES } from '../../utils/queries/index.mjs'; -import { getRemark as remark, getRemarkMdx } from '../../utils/remark.mjs'; /** * Determines whether a file should be parsed as MDX. A `.mdx` extension opts in diff --git a/packages/core/src/generators/json-simple/generate.mjs b/packages/core/src/generators/json-simple/generate.mjs index 116b93626..093bf82ef 100644 --- a/packages/core/src/generators/json-simple/generate.mjs +++ b/packages/core/src/generators/json-simple/generate.mjs @@ -4,9 +4,9 @@ import { join } from 'node:path'; import { remove } from 'unist-util-remove'; -import getConfig from '../../utils/configuration/index.mjs'; -import { writeFile } from '../../utils/file.mjs'; -import { UNIST } from '../../utils/queries/index.mjs'; +import getConfig from '#utils/configuration/index.mjs'; +import { writeFile } from '#utils/file.mjs'; +import { UNIST } from '#utils/queries/index.mjs'; /** * Generates the simplified JSON version of the API docs diff --git a/packages/core/src/generators/metadata/generate.mjs b/packages/core/src/generators/metadata/generate.mjs index b5691258d..b35fa134f 100644 --- a/packages/core/src/generators/metadata/generate.mjs +++ b/packages/core/src/generators/metadata/generate.mjs @@ -1,8 +1,9 @@ 'use strict'; +import getConfig from '#utils/configuration/index.mjs'; +import { loadFromURL } from '#utils/loaders.mjs'; + import { parseApiDoc } from './utils/parse.mjs'; -import getConfig from '../../utils/configuration/index.mjs'; -import { loadFromURL } from '../../utils/loaders.mjs'; /** * Process a chunk of API doc files in a worker thread. diff --git a/packages/core/src/generators/metadata/utils/parse.mjs b/packages/core/src/generators/metadata/utils/parse.mjs index 72f0dd705..42d05664f 100644 --- a/packages/core/src/generators/metadata/utils/parse.mjs +++ b/packages/core/src/generators/metadata/utils/parse.mjs @@ -9,6 +9,15 @@ import { remove } from 'unist-util-remove'; import { selectAll } from 'unist-util-select'; import { SKIP, visit } from 'unist-util-visit'; +import { + DEPRECATION_HEADING_REGEX, + IGNORE_STABILITY_STEMS, +} from '#generators/metadata/constants.mjs'; +import { UNIST } from '#utils/queries/index.mjs'; +import { getRemark as remark } from '#utils/remark.mjs'; +import { relative } from '#utils/url.mjs'; + +import { resolveTypeAnnotations } from './resolveTypes.mjs'; import createNodeSlugger from './slugger.mjs'; import { transformNodeToHeading } from './transformers.mjs'; import { @@ -18,14 +27,6 @@ import { visitTextWithUnixManualNode, visitYAML, } from './visitors.mjs'; -import { UNIST } from '../../../utils/queries/index.mjs'; -import { getRemark as remark } from '../../../utils/remark.mjs'; -import { relative } from '../../../utils/url.mjs'; -import { - DEPRECATION_HEADING_REGEX, - IGNORE_STABILITY_STEMS, -} from '../constants.mjs'; -import { resolveTypeAnnotations } from './resolveTypes.mjs'; /** * This generator generates a flattened list of metadata entries from a API doc diff --git a/packages/core/src/generators/metadata/utils/resolveTypes.mjs b/packages/core/src/generators/metadata/utils/resolveTypes.mjs index fe850e98b..aea5536af 100644 --- a/packages/core/src/generators/metadata/utils/resolveTypes.mjs +++ b/packages/core/src/generators/metadata/utils/resolveTypes.mjs @@ -1,9 +1,10 @@ import { parseSync } from '@swc/wasm'; import { visit } from 'unist-util-visit'; +import logger from '#logger/index.mjs'; +import { walk } from '#utils/swc.mjs'; + import { lookupTypeName, resolveTypeReference } from './transformers.mjs'; -import logger from '../../../logger/index.mjs'; -import { walk } from '../../../utils/swc.mjs'; // `null` is a keyword kind in SWC, unlike most parsers which treat it as a literal type const KEYWORDS = new Set([ diff --git a/packages/core/src/generators/metadata/utils/slugger.mjs b/packages/core/src/generators/metadata/utils/slugger.mjs index 40c7ec7c8..89fe09e9e 100644 --- a/packages/core/src/generators/metadata/utils/slugger.mjs +++ b/packages/core/src/generators/metadata/utils/slugger.mjs @@ -2,7 +2,7 @@ import GitHubSlugger, { slug as defaultSlugFn } from 'github-slugger'; -import { DOC_API_SLUGS_REPLACEMENTS } from '../constants.mjs'; +import { DOC_API_SLUGS_REPLACEMENTS } from '#generators/metadata/constants.mjs'; /** * Creates a modified version of the GitHub Slugger diff --git a/packages/core/src/generators/metadata/utils/transformers.mjs b/packages/core/src/generators/metadata/utils/transformers.mjs index 5eddf5927..7cf7c85d7 100644 --- a/packages/core/src/generators/metadata/utils/transformers.mjs +++ b/packages/core/src/generators/metadata/utils/transformers.mjs @@ -2,11 +2,12 @@ import { DOC_MAN_BASE_URL, DOC_API_HEADING_TYPES, MODULE_QUALIFIED_NAME, -} from '../constants.mjs'; +} from '#generators/metadata/constants.mjs'; +import BUILTIN_TYPE_MAP from '#generators/metadata/maps/builtin.json' with { type: 'json' }; +import MDN_TYPE_MAP from '#generators/metadata/maps/mdn.json' with { type: 'json' }; +import { transformNodesToString } from '#utils/unist.mjs'; + import { slug } from './slugger.mjs'; -import { transformNodesToString } from '../../../utils/unist.mjs'; -import BUILTIN_TYPE_MAP from '../maps/builtin.json' with { type: 'json' }; -import MDN_TYPE_MAP from '../maps/mdn.json' with { type: 'json' }; /** * @param {string} text The inner text diff --git a/packages/core/src/generators/metadata/utils/visitors.mjs b/packages/core/src/generators/metadata/utils/visitors.mjs index b3c9f6945..6fa2d66d4 100644 --- a/packages/core/src/generators/metadata/utils/visitors.mjs +++ b/packages/core/src/generators/metadata/utils/visitors.mjs @@ -2,11 +2,12 @@ import { SKIP } from 'unist-util-visit'; +import { QUERIES } from '#utils/queries/index.mjs'; +import { getRemark as remark } from '#utils/remark.mjs'; +import { transformNodesToString } from '#utils/unist.mjs'; + import { transformUnixManualToLink } from './transformers.mjs'; import { extractYamlContent, parseYAMLIntoMetadata } from './yaml.mjs'; -import { QUERIES } from '../../../utils/queries/index.mjs'; -import { getRemark as remark } from '../../../utils/remark.mjs'; -import { transformNodesToString } from '../../../utils/unist.mjs'; /** * Updates a Markdown link into a HTML link for API docs diff --git a/packages/core/src/generators/metadata/utils/yaml.mjs b/packages/core/src/generators/metadata/utils/yaml.mjs index 6b9ba9d91..aec478ea6 100644 --- a/packages/core/src/generators/metadata/utils/yaml.mjs +++ b/packages/core/src/generators/metadata/utils/yaml.mjs @@ -2,7 +2,7 @@ import yaml from 'yaml'; -import { QUERIES } from '../../../utils/queries/index.mjs'; +import { QUERIES } from '#utils/queries/index.mjs'; /** * Extracts raw YAML content from a node diff --git a/packages/core/src/logger/transports/console.mjs b/packages/core/src/logger/transports/console.mjs index 0edd50f14..c741c268f 100644 --- a/packages/core/src/logger/transports/console.mjs +++ b/packages/core/src/logger/transports/console.mjs @@ -2,8 +2,8 @@ import { styleText } from 'node:util'; -import { prettifyLevel } from '../utils/colors.mjs'; -import { prettifyTimestamp } from '../utils/time.mjs'; +import { prettifyLevel } from '#logger/utils/colors.mjs'; +import { prettifyTimestamp } from '#logger/utils/time.mjs'; /** * Logs a formatted message to stdout for human-friendly CLI output. diff --git a/packages/core/src/logger/transports/github.mjs b/packages/core/src/logger/transports/github.mjs index 8b5fb5127..673146ccb 100644 --- a/packages/core/src/logger/transports/github.mjs +++ b/packages/core/src/logger/transports/github.mjs @@ -2,9 +2,9 @@ import { debug, notice, warning, error } from '@actions/core'; -import { LogLevel } from '../constants.mjs'; -import { prettifyLevel } from '../utils/colors.mjs'; -import { prettifyTimestamp } from '../utils/time.mjs'; +import { LogLevel } from '#logger/constants.mjs'; +import { prettifyLevel } from '#logger/utils/colors.mjs'; +import { prettifyTimestamp } from '#logger/utils/time.mjs'; const actions = { [LogLevel.debug]: debug, diff --git a/packages/core/src/logger/utils/colors.mjs b/packages/core/src/logger/utils/colors.mjs index ebdcb165d..1f9607968 100644 --- a/packages/core/src/logger/utils/colors.mjs +++ b/packages/core/src/logger/utils/colors.mjs @@ -2,7 +2,7 @@ import { styleText } from 'node:util'; -import { levelTags, levelToColorMap } from '../constants.mjs'; +import { levelTags, levelToColorMap } from '#logger/constants.mjs'; /** * Returns a styled, uppercase log level tag for CLI output with color mapping diff --git a/packages/core/src/parsers/markdown.mjs b/packages/core/src/parsers/markdown.mjs index f0bbe1a2f..97fa20bc7 100644 --- a/packages/core/src/parsers/markdown.mjs +++ b/packages/core/src/parsers/markdown.mjs @@ -2,7 +2,7 @@ import { coerce } from 'semver'; -import { loadFromURL } from '../utils/loaders.mjs'; +import { loadFromURL } from '#utils/loaders.mjs'; // A ReGeX for retrieving Node.js version headers from the CHANGELOG.md const NODE_VERSIONS_REGEX = /\* \[Node\.js ([0-9.]+)\]\S+ (.*)\r?\n/g; diff --git a/packages/core/src/threading/chunk-worker.mjs b/packages/core/src/threading/chunk-worker.mjs index 02e30189a..cf324fb6d 100644 --- a/packages/core/src/threading/chunk-worker.mjs +++ b/packages/core/src/threading/chunk-worker.mjs @@ -1,5 +1,5 @@ -import { loadGenerator } from '../generators/loader.mjs'; -import { setConfig } from '../utils/configuration/index.mjs'; +import { loadGenerator } from '#generators/loader.mjs'; +import { setConfig } from '#utils/configuration/index.mjs'; /** * Processes a chunk of items using the specified generator's processChunk method. diff --git a/packages/core/src/threading/index.mjs b/packages/core/src/threading/index.mjs index 98ba22f49..a158f89bd 100644 --- a/packages/core/src/threading/index.mjs +++ b/packages/core/src/threading/index.mjs @@ -1,6 +1,6 @@ import Piscina from 'piscina'; -import logger from '../logger/index.mjs'; +import logger from '#logger/index.mjs'; const poolLogger = logger.child('WorkerPool'); diff --git a/packages/core/src/threading/parallel.mjs b/packages/core/src/threading/parallel.mjs index b0e59f6c7..04f38d9f2 100644 --- a/packages/core/src/threading/parallel.mjs +++ b/packages/core/src/threading/parallel.mjs @@ -1,6 +1,6 @@ 'use strict'; -import logger from '../logger/index.mjs'; +import logger from '#logger/index.mjs'; const parallelLogger = logger.child('parallel'); diff --git a/packages/core/src/utils/configuration/index.mjs b/packages/core/src/utils/configuration/index.mjs index 5d00ee537..54f6c5d25 100644 --- a/packages/core/src/utils/configuration/index.mjs +++ b/packages/core/src/utils/configuration/index.mjs @@ -11,12 +11,12 @@ import { coerce } from 'semver'; import { loadGenerators, resolveGeneratorSpecifier, -} from '../../generators/loader.mjs'; -import logger from '../../logger/index.mjs'; -import { parseChangelog, parseIndex } from '../../parsers/markdown.mjs'; -import { enforceArray } from '../array.mjs'; -import { leftHandAssign } from '../generators.mjs'; -import { deepMerge } from '../misc.mjs'; +} from '#generators/loader.mjs'; +import logger from '#logger/index.mjs'; +import { parseChangelog, parseIndex } from '#parsers/markdown.mjs'; +import { enforceArray } from '#utils/array.mjs'; +import { leftHandAssign } from '#utils/generators.mjs'; +import { deepMerge } from '#utils/misc.mjs'; const configExplorer = cosmiconfig('doc-kit'); diff --git a/packages/core/src/utils/configuration/types.d.ts b/packages/core/src/utils/configuration/types.d.ts index d3b0c4028..1c29326cd 100644 --- a/packages/core/src/utils/configuration/types.d.ts +++ b/packages/core/src/utils/configuration/types.d.ts @@ -1,5 +1,5 @@ import type { SemVer } from 'semver'; -import type { ReleaseEntry } from '../../parsers/types'; +import type { ReleaseEntry } from '#parsers/types'; export type Configuration = { global: GlobalConfiguration; diff --git a/packages/core/src/utils/queries/index.mjs b/packages/core/src/utils/queries/index.mjs index 488ce6f5a..f574e9784 100644 --- a/packages/core/src/utils/queries/index.mjs +++ b/packages/core/src/utils/queries/index.mjs @@ -1,6 +1,7 @@ 'use strict'; -import { transformNodesToString } from '../unist.mjs'; +import { transformNodesToString } from '#utils/unist.mjs'; + import { isTypedListItem, isTypedList } from './utils.mjs'; // This defines the actual REGEX Queries diff --git a/packages/core/src/utils/signature/parseList.mjs b/packages/core/src/utils/signature/parseList.mjs index a9ca2cad2..529a2e87b 100644 --- a/packages/core/src/utils/signature/parseList.mjs +++ b/packages/core/src/utils/signature/parseList.mjs @@ -1,12 +1,13 @@ +import { leftHandAssign } from '#utils/generators.mjs'; +import { QUERIES, UNIST } from '#utils/queries/index.mjs'; +import { transformNodesToString } from '#utils/unist.mjs'; + import { DEFAULT_EXPRESSION, LEADING_HYPHEN, NAME_EXPRESSION, } from './constants.mjs'; import parseSignature from './parseSignature.mjs'; -import { leftHandAssign } from '../generators.mjs'; -import { QUERIES, UNIST } from '../queries/index.mjs'; -import { transformNodesToString } from '../unist.mjs'; /** * Extracts and removes a specific pattern from a text string while storing the result in a key of the `current` object. diff --git a/packages/core/src/utils/type-annotations/hast.mjs b/packages/core/src/utils/type-annotations/hast.mjs index cd867c2d8..1eff0f2e4 100644 --- a/packages/core/src/utils/type-annotations/hast.mjs +++ b/packages/core/src/utils/type-annotations/hast.mjs @@ -1,6 +1,6 @@ 'use strict'; -import { highlighter } from '../highlighter.mjs'; +import { highlighter } from '#utils/highlighter.mjs'; const [lightTheme, darkTheme] = highlighter.shiki.getLoadedThemes(); From a440782b0e50616a5b989fb97a592e78075d915f Mon Sep 17 00:00:00 2001 From: btea <2356281422@qq.com> Date: Mon, 17 Aug 2026 08:56:15 +0800 Subject: [PATCH 2/2] chore: update --- packages/core/package.json | 15 +++------------ 1 file changed, 3 insertions(+), 12 deletions(-) diff --git a/packages/core/package.json b/packages/core/package.json index 50741dd9b..e7b5b62c8 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -31,22 +31,13 @@ ] }, "imports": { - "#generators/*": [ - "./src/generators/*", - "./src/generators/*.d.ts" - ], - "#logger/*": [ - "./src/logger/*", - "./src/logger/*.d.ts" - ], + "#generators/*": "./src/generators/*", + "#logger/*": "./src/logger/*", "#parsers/*": [ "./src/parsers/*", "./src/parsers/*.d.ts" ], - "#utils/*": [ - "./src/utils/*", - "./src/utils/*.d.ts" - ] + "#utils/*": "./src/utils/*" }, "files": [ "src",