pub const TOPICS_INDEX: &str = "\
Built-in documentation topics (import-lint docs <topic>):
concepts The mental model: packages, importability, loopholes, re-exports
config Config file reference: discovery, all options and their defaults
fixing How to fix an import-access violation
`import-lint explain <message-id>` explains an individual diagnostic.
Full guides: https://github.com/uhyo/import-lint/tree/master/docs/guides
";
pub const EXPLAIN_INDEX: &str = "\
Diagnostic message ids (import-lint explain <message-id>):
package Cannot import a package-private export
package:reexport Cannot re-export a package-private export
private Cannot import a private export
private:reexport Cannot re-export a private export
unresolved Unresolved import specifier (with --report-unresolved)
`import-lint --format json` includes each diagnostic's id in its `messageId`
field; the default pretty format shows the message text only.
Topic guides: `import-lint docs`
";
pub const TOPIC_NAMES: &str = "concepts, config, fixing";
pub const EXPLAIN_IDS: &str = "package, package:reexport, private, private:reexport, unresolved";
pub fn topic(name: &str) -> Option<&'static str> {
match name {
"concepts" => Some(CONCEPTS),
"config" => Some(CONFIG),
"fixing" => Some(FIXING),
_ => None,
}
}
pub fn explanation(id: &str) -> Option<&'static str> {
match id {
"package" => Some(EXPLAIN_PACKAGE),
"package:reexport" => Some(EXPLAIN_PACKAGE_REEXPORT),
"private" => Some(EXPLAIN_PRIVATE),
"private:reexport" => Some(EXPLAIN_PRIVATE_REEXPORT),
"unresolved" => Some(EXPLAIN_UNRESOLVED),
_ => None,
}
}
const CONCEPTS: &str = r#"ImportLint concepts
ImportLint enforces directory-level encapsulation in TypeScript/JavaScript.
A directory is a "package" (unrelated to npm packages); its exports are
importable only from files inside it until an export is explicitly opened up.
Importability
Every export has one of three access levels:
public importable from anywhere
package importable only from files in the same package
private importable from nowhere (not even the same package)
Declared with a JSDoc tag directly above the export (case-sensitive):
/** @package */
export const token = "...";
`/** @access package */` is an equivalent spelling. Line comments
(`// @package`) are not recognized. An export with no recognized tag falls
back to the config's `defaultImportability` (built-in default: "public";
configs scaffolded by `import-lint init` set "package").
Packages and boundaries
By default every directory is its own package. Files in a child directory
may import from ancestor packages; the reverse is a violation. If the
config sets `packageDirectory` (glob patterns, e.g. "**/*.package"), only
matching directories are boundaries, and a file with no matching ancestor
belongs to a single project-root package.
Index loophole (`indexLoophole`, default: on)
A bare re-export in a package's index file, e.g.
export { issueToken } from "./token";
promotes that export one level out, to the parent's package. This is the
idiomatic way to expose a package's API without making it fully public.
Filename loophole (`filenameLoophole`, default: off)
Treats "foo/bar.ts" as in-package with the companion file "foo.ts" (one
directory level).
One-hop re-export semantics
A re-export statement's own JSDoc tag governs visibility for whoever
imports through it; ImportLint never looks a second hop further. A bare
(untagged) re-export RESETS importability to `defaultImportability` — even
if the original export was tagged @public. The re-export statement itself
is also checked against the file it re-exports from.
Internal vs. external
Only imports resolving to files inside the project are checked; npm
dependencies and Node builtins are never flagged.
Non-TS files
Imports that resolve to a project file ImportLint cannot parse as a
module (CSS modules, JSON, SVG, ...) are checked too. Such files have no
JSDoc tags, so each imported name's access level comes from the config's
`nonTsFiles` option (see `import-lint docs config`), falling back to
`defaultImportability`. The specifier must name the non-TS extension
itself ("./a.module.css"); like tsc, ImportLint never resolves an
extensionless specifier to a non-TS file.
Full guide:
https://github.com/uhyo/import-lint/blob/master/docs/guides/concepts.md
"#;
const CONFIG: &str = r#"Config file reference
File and discovery
`.importlintrc.jsonc` (JSON with comments), or `.importlintrc.json` as a
fallback when no .jsonc exists in the same directory. Discovered by walking
up from the current directory, unless `--config <path>` names one
explicitly. The directory containing the config file becomes the project
root; `include`, `exclude`, and `tsconfig` are resolved relative to it.
Without a config file, defaults apply and the current directory is the
project root. Unknown keys anywhere in the config are a hard load error
(exit code 2), never silently ignored. `import-lint init` scaffolds the
recommended setup.
Top-level keys
"include": ["."] Roots to walk for lint targets.
"exclude": [] Extra glob patterns to skip, on top of .gitignore.
"tsconfig": <path> tsconfig.json for resolver paths/baseUrl/customConditions
(default: "<project root>/tsconfig.json" if it exists).
"rules": { "package-access": { ... } }
"package-access" rule options (defaults shown)
"severity": "error"
"error" | "warn" | "off". Warnings are shown but never affect the
exit code.
"indexLoophole": true
A bare re-export in a boundary's index file promotes the export to
the parent's package.
"filenameLoophole": false
"foo.ts" is in-package with the contents of the "foo/" directory
next to it (one level).
"defaultImportability": "public"
Access level of exports with no JSDoc tag: "public" | "package" |
"private". `import-lint init` scaffolds "package".
"treatSelfReferenceAs": "external"
Imports of the project's own package.json name: "external" (never
checked) | "internal" (checked normally).
"excludeSourcePatterns": []
Glob patterns (matched against the exporting file's project-relative
path) that are never checked.
"packageDirectory": (unset)
Glob patterns naming boundary directories (matched against both the
basename and the project-relative path). Unset: every directory is
its own package. A "!"-prefixed pattern excludes an otherwise-
matching directory.
"nonTsFiles": {}
Access levels for the exports of non-TS files (CSS modules, JSON,
...). Keys are glob patterns matched against the exporting file's
resolved project-relative path (not the import specifier); values
map an export name to "public" | "package" | "private". The name
"*" covers every export except `default` (the ES `export *`
convention). Entries are tried in written order — the first entry
that assigns the imported name (directly or via "*") wins, so put
more specific patterns first. Exports no entry assigns fall back to
`defaultImportability`. Example:
"nonTsFiles": {
"**/*.module.css": { "default": "package", "*": "package" }
}
Full reference:
https://github.com/uhyo/import-lint/blob/master/README.md#config-file
"#;
const FIXING: &str = r#"Fixing an import-access violation
First locate the exporting file and its package boundary: the nearest
ancestor directory matching the config's `packageDirectory` patterns, or the
exporting file's own directory if `packageDirectory` is unset. Then pick the
first fix that fits:
1. Move the importing file into the package. If it conceptually belongs
there, no visibility change is needed at all.
2. Re-export through the package's index file (uses the index loophole,
on by default). Add a bare re-export to the boundary's index.ts:
export { issueToken } from "./token";
This exposes the export one level out — to the parent's package, not
the whole project. To widen visibility further, tag the re-export
line itself:
/** @public */
export { issueToken } from "./token";
3. Tag the original export `/** @public */`, making it importable from
anywhere. Rarely the right choice — it gives up the boundary for that
export; prefer 1 or 2.
To acknowledge a violation without fixing it yet, suppress it at the import
site with a directive comment (the equivalent of ESLint's
`eslint-disable-next-line`):
// import-lint-disable-next-line -- migrating in #123
import { issueToken } from "../auth/token";
`// import-lint-disable-line` at the end of the line works too. An optional
rule name list (`import-lint-disable-next-line package-access`) restricts
what is suppressed; text after ` -- ` is a free-form justification. Prefer a
real fix — every suppression is a hole in the boundary.
During gradual adoption, config-level changes can also be appropriate:
adjusting `packageDirectory` patterns, `defaultImportability`, or
`excludeSourcePatterns`. Do not reach for those (or `"severity": "off"`)
just to silence one diagnostic — they weaken checking project-wide.
After editing, rerun `import-lint` to confirm the diagnostic is gone and no
new ones appeared. `import-lint explain <message-id>` explains an individual
diagnostic (`--format json` reports each diagnostic's `messageId`).
Walkthrough:
https://github.com/uhyo/import-lint/blob/master/docs/guides/tutorial.md
"#;
const EXPLAIN_PACKAGE: &str = r#"package — "Cannot import a package-private export '...'"
The import resolves to a file inside your project, and that export's
importability is `package`: importable only from files within the same
package (the exporting file's boundary directory, or anywhere below it).
The importing file is outside that package.
The importability came from a `/** @package */` JSDoc tag directly above the
export, or — with no tag — from the config's `defaultImportability`.
Fixes, in order of preference:
1. Move the importing file inside the package, if it conceptually belongs
there. No visibility change needed.
2. Bare re-export from the package's index file (index loophole, on by
default):
export { theName } from "./the-module";
This promotes it one level out, to the parent's package. To widen
further, tag the re-export line itself (e.g. `/** @public */`).
3. Tag the original export `/** @public */` to allow importing from
anywhere. Rarely the right choice — prefer 1 or 2.
To acknowledge it without fixing it yet, add a directive comment above the
import: `// import-lint-disable-next-line -- reason`. Do not silence it by
setting `"severity"` to "off"/"warn", adding `excludeSourcePatterns`, or
loosening `defaultImportability` — those weaken checking project-wide. See
`import-lint docs fixing`.
"#;
const EXPLAIN_PACKAGE_REEXPORT: &str = r#"package:reexport — "Cannot re-export a package-private export '...'"
A re-export statement (e.g. `export { x } from "./mod"` or
`export * from "./mod"`) is itself checked like an import against the file
it re-exports from. Here, that file's export is package-private and the
re-exporting file is outside its package.
Fixes, in order of preference:
1. Re-export from inside instead: a bare re-export in the *owning*
package's own index file (index loophole) promotes the export one
level out; chain one level at a time rather than reaching across the
boundary from outside.
2. Move the re-exporting file into the owning package.
3. Tag the original export `/** @public */`. Rarely the right choice.
See `import-lint docs fixing` and `import-lint explain package`.
"#;
const EXPLAIN_PRIVATE: &str = r#"private — "Cannot import a private export '...'"
The export's importability is `private`: importable from nowhere, not even
from files in the same package. That comes from a `/** @private */` JSDoc
tag directly above the export, or — with no tag — from
`defaultImportability: "private"` in the config.
Fixes:
1. If the export should be usable within its package, change its tag to
`/** @package */` (or remove the tag, when the config's
`defaultImportability` allows more).
2. If it should be importable one level out, give the package's index
file a *tagged* re-export, e.g.:
/** @package */
export { theName } from "./the-module";
Note: under `defaultImportability: "private"`, a bare re-export resets
to private again — the tag on the re-export line is what opens it up.
3. If the export exists only for the exporting file itself, stop
importing it and inline or duplicate what you need.
"#;
const EXPLAIN_PRIVATE_REEXPORT: &str = r#"private:reexport — "Cannot re-export a private export '...'"
A re-export statement reaches into an export whose importability is
`private` — importable (and re-exportable) from nowhere.
Fixes: give the original export a wider access level if it is meant to be
shared — `/** @package */` at minimum — then follow the normal promotion
path (tagged re-exports from the package's index file, one level at a
time). See `import-lint explain private` and `import-lint docs fixing`.
"#;
const EXPLAIN_UNRESOLVED: &str = r#"unresolved — "Unresolved import specifier '...'"
Emitted only with `--report-unresolved`, always as a warning (never affects
the exit code). The resolver could not map this import specifier to a
project file or an external package, so ImportLint skipped checking it.
This is not an access violation — but an import that silently fails to
resolve is also never checked, so violations could hide behind it.
Common causes:
- A typo in the specifier, or the target file is missing.
- A tsconfig `paths`/`baseUrl` alias the resolver doesn't know about:
point ImportLint at the right tsconfig via `--tsconfig <path>` or the
config's `"tsconfig"` key (default: <project root>/tsconfig.json).
- The specifier only resolves through bundler-specific magic ImportLint's
resolver (oxc_resolver, Node-style) doesn't model.
"#;
#[cfg(test)]
mod tests {
use super::*;
use import_lint::MessageId;
#[test]
fn every_message_id_has_an_explanation() {
for id in [
MessageId::Package,
MessageId::PackageReexport,
MessageId::Private,
MessageId::PrivateReexport,
] {
let text =
explanation(id.as_str()).unwrap_or_else(|| panic!("no explanation for {:?}", id));
assert!(
text.starts_with(id.as_str()),
"explanation for {:?} should lead with its id",
id
);
assert!(EXPLAIN_INDEX.contains(id.as_str()));
assert!(EXPLAIN_IDS.contains(id.as_str()));
}
assert!(explanation("unresolved").is_some());
}
#[test]
fn every_topic_is_listed_in_the_index() {
for name in ["concepts", "config", "fixing"] {
assert!(topic(name).is_some());
assert!(TOPICS_INDEX.contains(name));
assert!(TOPIC_NAMES.contains(name));
}
}
}