@hyperfrontend/workspace/lintlint
The projects rule family for @hyperfrontend/linter: three rules that read the workspace graph, and the readers a workspace's own rules share with them.
import { PROJECTS_FAMILY } from '@hyperfrontend/workspace/lint'
export default [
{ families: { projects: PROJECTS_FAMILY } },
{ files: ['**/*.ts'], rules: { 'projects/module-boundaries': ['error', { depConstraints: [] }] } },
{ files: ['**/package.json'], rules: { 'projects/dependency-checks': 'error' } },
{ files: ['**/project.json'], rules: { 'projects/command-lines': 'error' } },
]
| Rule | Checks |
|---|---|
projects/module-boundaries | Imports between projects: aliases, cycles, tags, buildable dependencies |
projects/dependency-checks | A buildable project's manifest against what its files import |
projects/command-lines | Shell lines of a project's targets for what sh and cmd.exe read apart |
The readers resolve what a rule of your own needs about the file it lints: the workspace root and project that own it (workspaceRootOf, projectRootOf), its project file and manifest (readProjectFile, readPackageFile), the aliases of tsconfig.base.json (pathAliases) and the exports of a module (moduleExports).
Their options, messages and fixes are those of Nx's ESLint plugin (see licenses/nx.txt), reduced to the options a workspace configures, and they reach the same verdicts while loading nothing from Nx.
The project graph
The graph entry builds, once per lint process, the graph Nx would build, and the rules read it:
- Projects: every directory holding a
project.jsonor apackage.jsonamong the files Git tracks or would track, less what.hfignoreexcludes. Names, types, tags and targets follow Nx: apackage.jsonbeside aproject.jsonadds its scripts as targets andnpm:tags from itsprivateflag and its keywords. - npm packages: the root
package-lock.json, one node per name and version. - Dependencies: each code file's imports, read with the linter's own parser under Nx's rules, so a
requireinside a function or animport()counts as dynamic exactly when Nx counts it so; eachpackage.json's dependencies; and the implicit dependencies a project declares.
Imports are remembered in node_modules/.cache/hyperfrontend-lint/imports.json: a file whose size and modification time are unchanged is not read again, and one whose content hash is unchanged is not parsed again. Like Nx's cached graph, the graph reflects the files on disk, not unsaved editor buffers.
module-boundaries
Reports an import that:
- reaches another project by a relative or absolute path instead of its alias, with a fix that rewrites it to the alias when the imported names can be traced through the project's entry points;
- names its own project's alias, with a fix that rewrites it to a relative path;
- closes a cycle between projects, or imports an application;
- statically imports a library the project loads lazily elsewhere;
- from a buildable library, names a library without a build target (
enforceBuildableLibDependency); - reaches a project whose tags the
depConstraintsdo not allow (sourceTagwithonlyDependOnLibsWithTags).
Options: allow (patterns of specifiers never reported), depConstraints and enforceBuildableLibDependency, the ones this workspace sets. The base sets them in lint.base.config.ts, with narrower allow lists for apps/package-e2e in the root lint.config.ts and for apps/docs-site in its own config; the shipped demos turn the rule off.
dependency-checks
For a project with a build target, compares the dependencies, peerDependencies and optionalDependencies of its package.json with the packages the files of the build's inputs import, at the versions installed where they import them from. It reports and fixes missing packages, packages nothing imports, ranges the installed version does not satisfy, and a manifest with no dependency section at all.
Options: ignoredDependencies and ignoredFiles. Each project's lint.config.ts lists what its build bundles or never imports, with the reason beside each entry; the library generator's template starts every new library with @hyperfrontend/testing ignored.
command-lines
The workspace runner starts every @hyperfrontend/workspace:run-commands line through the platform shell (src/runner/commands.ts): sh on Linux and macOS, cmd.exe on Windows. In a project.json, each target's command, the command of its options, and every entry of their commands (a string, or an object's command) is checked for what the two shells read differently:
| Message | Reported when |
|---|---|
| singleQuote | A ' outside double quotes: cmd.exe passes it through as part of the argument |
| envPrefix | The line starts with NAME=value, which cmd.exe does not read as an assignment |
| variable | A $NAME, ${NAME}, $(…) or %NAME%, which only one shell expands, quoted or not |
| separator | A ; or a lone & outside double quotes; &&, ||, | and 2>&1 mean the same in both |
| glob | A * or ? outside double quotes, which only sh expands |
| backslash | A \ outside double quotes, which sh reads as an escape |
A line with several problems is reported once for each. Nothing is fixed: the replacement is a judgement about the command, such as moving a variable into the target's env or quoting a pattern so the program matches it.
Options: include, the selectors of the workspace/cross-platform rule, defaulting to every publishable library. The workspace selects publishable libraries, the root project.json, tools/** and apps/package-e2e/**: the projects whose targets the Windows and macOS legs run, or a contributor runs on their own machine. The docs site and the demos build on Linux alone, and their cp lines are left as they are.
API Reference§
ƒ Functions
tsconfig.base.json.Parameters
| Name | Type | Description |
|---|---|---|
§directory | string | Where to start |
Returns
stringExample
Finding the workspace from the file a rule is checking
baseConfigRootOf('/repo/libs/features/src/host') // => '/repo'
baseConfigRootOf('/tmp') // => nullParameters
Returns
stringExample
The default selector against a rule's `include` option
checkedProject('/repo/libs/features/project.json', [{ publishableLibraries: true }]) // => '/repo/libs/features'
checkedProject('/repo/apps/docs-site/project.json', [{ publishableLibraries: true }]) // => null
checkedProject('/repo/apps/docs-site/project.json', [{ files: ['apps/**/project.json'] }]) // => '/repo/apps/docs-site'Parameters
| Name | Type | Description |
|---|---|---|
§root | string | The absolute directory of the project |
Returns
booleannode: moduleExample
A spec's `node:` import does not make a browser library a Node project
isNodeProject('/repo/libs/workspace') // => true
isNodeProject('/repo/libs/features') // => false, even with `import { tmpdir } from 'node:os'` in a *.spec.tsParameters
| Name | Type | Description |
|---|---|---|
§directory | string | The absolute directory that would hold project.json |
Returns
booleanbuild and publish targetsExample
Gating a rule to publishable libraries
const root = projectRootOf(dirname(context.file.path))
if (root === null || !isPublishableLibrary(root)) return {}build and publish targets.Parameters
| Name | Type | Description |
|---|---|---|
§project | ProjectFile | The parsed file |
Returns
booleanExample
A library needs both targets
isPublishableProject({ projectType: 'library', targets: { build: {}, publish: {} } }) // => true
isPublishableProject({ projectType: 'library', targets: { build: {} } }) // => false
isPublishableProject({ projectType: 'application', targets: { build: {}, publish: {} } }) // => false
isPublishableProject(null) // => falseParameters
| Name | Type | Description |
|---|---|---|
§file | string | The absolute path |
Returns
unknownExample
A name exported through a list is marked exported
// const helper = () => 1
// export const { a, b } = pair
// export { helper }
moduleDeclarations('/repo/libs/features/src/util.ts').map(({ name, kind, exported }) => ({ name, kind, exported }))
// => [{ name: 'helper', kind: 'variable', exported: true }, { name: 'a', kind: 'variable', exported: true }, { name: 'b', kind: 'variable', exported: true }]export * and export { x } from are followed, a cycle is cut, and an exported name whose declaration is not found is kept with an unknown kind.Parameters
| Name | Type | Description |
|---|---|---|
§file | string | The absolute path |
Returns
unknownExample
Following a re-export to the file that declares the name
// libs/features/src/index.ts: export { open as openHost } from './host/open'
// export * from './types'
const exports = moduleExports('/repo/libs/features/src/index.ts')
exports.find((item) => item.name === 'openHost')
// => { name: 'openHost', kind: 'function', node: <FunctionDeclaration>, file: '/repo/libs/features/src/host/open.ts' }
exports.some((item) => item.name === 'open') // => false, the local name is not exported
exports.find((item) => item.name === 'HostOptions')?.kind // => 'interface', brought in by the star re-exportParameters
| Name | Type | Description |
|---|---|---|
§file | string | The absolute path |
Returns
NodeExample
The same program on every call
const program = parsedModule('/repo/libs/features/src/index.ts')
program?.kind // => 'Program'
parsedModule('/repo/libs/features/src/index.ts') === program // => true
parsedModule('/repo/libs/features/src/missing.ts') // => nullParameters
| Name | Type | Description |
|---|---|---|
§workspaceRoot | string | The directory holding tsconfig.base.json |
Returns
unknownExample
The first target of each alias, made absolute
pathAliases('/repo')
// => [
// { alias: '@hyperfrontend/features', source: '/repo/libs/features/src/index.ts' },
// { alias: '@hyperfrontend/features/*', source: '/repo/libs/features/src/*' },
// { alias: '@scope/empty', source: null }, // paths: { '@scope/empty': [] }
// ]project.json, or a manifest that looks like a project's.Parameters
| Name | Type | Description |
|---|---|---|
§directory | string | Where to start |
Returns
stringExample
The project, not the workspace, that holds a file
projectRootOf('/repo/libs/features/src/host') // => '/repo/libs/features'
projectRootOf('/repo/libs/features/e2e/src') // => '/repo/libs/features/e2e', the nearest project.json
projectRootOf('/repo/tools') // => '/repo', the workspace is its own projectpackage.json.Parameters
| Name | Type | Description |
|---|---|---|
§directory | string | The absolute directory |
Returns
PackageFileExample
The fields are untyped until checked
const manifest = readPackageFile('/repo/libs/features')
const name = typeof manifest?.name === 'string' ? manifest.name : null // => '@hyperfrontend/features'project.json.Parameters
| Name | Type | Description |
|---|---|---|
§directory | string | The absolute directory |
Returns
ProjectFileExample
Reading a target's existence from a rule
const project = readProjectFile('/repo/libs/features')
project?.name // => 'lib-features'
project?.targets?.['publish'] !== undefined // => true
readProjectFile('/repo/libs/vendored') // => null, a package.json alone has no project.jsonParameters
Returns
stringExample
An emitted extension finds its source first
const from = '/repo/libs/features/src/index.ts'
resolveModule(from, './host/open.js') // => '/repo/libs/features/src/host/open.ts'
resolveModule(from, './host') // => '/repo/libs/features/src/host/index.ts'
resolveModule(from, '@hyperfrontend/nexus') // => null, bare specifiers are not resolved herehf.json, else a manifest declaring workspaces, else the nearest manifest.Parameters
| Name | Type | Description |
|---|---|---|
§directory | string | Where to start |
Returns
stringExample
Making a checked file's path workspace-relative
const root = workspaceRootOf(dirname(context.file.path)) // => '/repo'
relative(root!, context.file.path) // => 'libs/features/src/index.ts'
workspaceRootOf('/tmp') // => null◈ Interfaces
Properties
readonly include?:unknownThe project files checked; replaces the default of every publishable library.Properties
Properties
Properties
Properties
Properties
package.json the rules read from disk.Properties
Properties
project.json the rules read.Properties
Properties
◆ Types
type DeclarationKind = "function" | "class" | "interface" | "type" | "enum" | "variable" | "namespace" | "unknown"● Variables
projects in a configuration: { families: { projects: PROJECTS_FAMILY } }.