Repository navigation
Releases
v0.9.1
What changed
@perfectpan/lint-config/doc-translations now handles documentation-site pages (#14):
- A code block's language and body must still match, but the rest of the info string, such as a
title="…"caption, may be translated. The mismatch message sayslanguagewhere it saidinfo string. - YAML frontmatter that opens a document is not compared on either side, and a translation's
headeris the first line after it. - With
stamp: true, a translation that has frontmatter keeps the stamp there as asource-blob: <hash>key, which--writeadds before the closing---or replaces; a key written by hand in another form (quoted, other spacing, a malformed or multi-line value, a repeat) is reported and replaced, never kept beside a second key. Before,--writeput the<!-- source-blob: … -->comment above the frontmatter of a page without a header, and MDX does not compile HTML comments. A site whose page schema rejects unknown keys declaressource-blob; fumadocs' default schema strips it.
Translations without frontmatter are checked and recorded exactly as before.
What newly fails
Nothing: both changes accept more. Read-only runs: PerfectPan/estela 0 findings before and after (15 pairs); PerfectPan/rivus-agent the same 6 findings as v0.9.0; PerfectPan/agent-kit, not yet a consumer, goes from 5 findings (translated code titles) to 1 (a translated comment inside a code block, which the check was hiding behind the title report).
Upgrade
Change github:PerfectPan/lint-config#v0.9.0 to #v0.9.1 and reinstall.
v0.9.0
What changed
New opt-in export @perfectpan/lint-config/doc-translations (#13): a zero-dependency check for translated Markdown documents, called from a repository script with runDocTranslations(options, process.argv.slice(2)). It works with a translation beside each document (foo.zh-CN.md) or a tree per language (docs/en → docs/zh-CN), chosen through translationOf, and checks per pair:
- the translation exists, every translation has a source in scope, and
translationOfgives each source its own path insidetranslations; - an optional header line;
- headings (levels in order), code blocks (unchanged), tables (rows and columns), list items (kind and indent) and links in order, with links to translated documents pointing to their translations and every fragment naming a GitHub heading anchor or
idof its target; - with
stamp: true, a<!-- source-blob: <hash> -->line holding the source's Git blob hash, so an edited source fails until its translation is updated and recorded with--write <path>....
Usage is in the README ("Documentation translations"); the reasons and the line scan's limits are in docs/decisions.md#documentation-translations.
What newly fails
Nothing. No shared lint, format, tsconfig, jscpd or Knip setting changed, and the new module runs only in a repository that calls it, so the impact on every existing consumer is 0 findings.
Upgrade
Change github:PerfectPan/lint-config#v0.8.0 to #v0.9.0 and reinstall. To adopt the check, add a script like the README example and run it in CI and the pre-commit hook.
v0.8.0
What changed
- Two path-free jscpd profiles.
@perfectpan/lint-config/jscpd.jsonis the gate:minLines: 6,minTokens: 40,threshold: 0,mode: "mild"andfailOnEmpty: true, so any reported clone fails the run and so does a scan that filters out every file.@perfectpan/lint-config/jscpd-audit.jsonis the audit: the same floor plus consistent identifier renaming, preserved literals and function-level AST similarity (similarity: 0.8,minNodes: 20), with no threshold and a JSON report whosekindandmethodfields classify each candidate. Scan roots, formats, ignores and output paths stay in the consuming repository. @perfectpan/lint-config/knipexports the shared Knip policy as plain data:treatConfigHintsAsErrorsandtreatTagHintsAsErrorsare on, so an unresolved configuration or tag hint fails the run. Spread it into the repository's ownknip.ts; entries, projects, paths, workspaces and exceptions stay there.jscpd(>=5.4.2 <6) andknip(>=6.45.1 <7) are new optional peers. No runtime dependency was added, and the oxlint, oxfmt, tsconfig andvite-plusexports are unchanged.docs/decisions.mdrecords why each profile value and the Knip policy were chosen.
What newly fails
Nothing for an existing consumer: the profiles and the Knip policy apply only to commands that reference them. A repository that adopts the gate fails on any clone of at least six lines and forty tokens, and on an empty scan; narrow its roots or ignores rather than raising the threshold. A repository that spreads the Knip policy fails on configuration or tag hints; resolve the hint in its knip.ts. The audit profile reports candidates and has no failing threshold.
Impact
Existing lint, format and type-check results are unchanged for every consumer. In PerfectPan/rivus-agent, the first adopter, the existing gate keeps 548 files and 0 clones, the audit reports 1,538 candidates across 1,018 files, and Knip reports findings with no configuration or tag hints.
Upgrade
Change #v0.7.1 to #v0.8.0 in the @perfectpan/lint-config dependency, then reinstall. To adopt the duplicate checks, install jscpd and pass --config node_modules/@perfectpan/lint-config/jscpd.json (or jscpd-audit.json) with the repository's own roots and ignores. To adopt the Knip policy, install knip and spread knip from @perfectpan/lint-config/knip into knip.ts.
v0.7.1
What changed
- The shared oxfmt options ignore
CHANGELOG.*, the changelogs that release tools generate. This coversoxfmt.jsonandfmtfrom@perfectpan/lint-config/vite-plus. Changesets writesCHANGELOG.md, and@changesets/changelog-githubindents the blank lines of multi-paragraph summaries, which failed format checks in version pull requests. Rush also writesCHANGELOG.json. - A repository config that spreads
fmtskips these files at any depth below it. This works for vite-plusfmtand foroxfmt.config.ts. oxfmt resolvesignorePatternsfrom the config file's directory, sooxfmt -c node_modules/@perfectpan/lint-config/oxfmt.jsondoes not apply the ignore. - The exported
fmttype declaresignorePatterns. The reason is recorded indocs/decisions.md. AGENTS.md names this as the one shared ignore.
What newly fails
Nothing. The change only stops checking generated changelogs. A config that sets its own ignorePatterns still replaces the shared list; spread ...fmt.ignorePatterns first to keep the changelog ignore.
Impact
Format checks only. Some consumers already ignore CHANGELOG.* themselves: project-template-pnpm, project-template-rush, agent-kit and snorlax. For them, nothing changes, and they can drop their own pattern.
Upgrade
Change #v0.7.0 to #v0.7.1 in the @perfectpan/lint-config dependency, then reinstall. If a package config ignored only CHANGELOG.*, use plain fmt. Otherwise use ignorePatterns: [...fmt.ignorePatterns, ...].
v0.7.0
What changed
defineLint(config)in@perfectpan/lint-config/vite-plusmerges a repository's lint config into the shared one:categories,optionsandrulesmerge key by key,pluginsare added, andoverridesapply after the shared ones and the opt-in checks.lintandfmtare unchanged.- Two opt-in checks, off unless given:
tailwind: { stylesheets: [{ entryPoint, files, excludeFiles }], literalValues }:eslint-plugin-better-tailwindcssrules for unknown, conflicting, duplicate, non-canonical and concatenated classes and stray whitespace, plus literal colours or lengths in arbitrary values. Needs the plugin (new optional peer,>=4.10.0).shadcn: { ui, elements }: the listed elements and Radix primitives only inside the shadcn/ui files (@radix-ui/react-slotallowed everywhere), andreact/no-multi-compoff in those files.
- The rule rationale moved from the README to
docs/decisions.md; overrides and path exemptions todocs/overrides.md.
What newly fails
Nothing, unless a repository turns an opt-in check on. With tailwind, arbitrary values such as text-[14px], bg-[#fff] or shadow-[0_1px_rgb(0_0_0/0.1)] fail; set literalValues: false while adding theme tokens. With shadcn, a listed element or a Radix import outside ui fails; list only elements whose shadcn/ui component is installed.
Impact
PerfectPan/agent-kit apps/website, which already runs the first five Tailwind rules: no-restricted-classes 43 hits in 20 files, no-concatenated-classes 3 hits (all in src/lib/utils.test.ts); shadcn with elements: ["button"] 0 hits.
Upgrade
Change #v0.6.1 to #v0.7.0 in the @perfectpan/lint-config dependency, then reinstall.
v0.6.1
What changed
promise/valid-paramsis now off. The rule counts the arguments of calls to methods namedthen,catchandfinallywithout type information, so it reported APIs that only share the name, such as zod/mini'sz.catch(schema, fallback). TypeScript already rejects a wrong argument count on a real Promise method (TS2554), and oxlint's rule page says the rule is generally unnecessary with TypeScript.
What newly fails
Nothing new is reported. Because reportUnusedDisableDirectives is an error, a // oxlint-disable-next-line promise/valid-params comment left in a consumer becomes an unused-directive error after the upgrade: delete those comments when you bump.
Impact
Directives to delete per consumer (main branches, 2026-10-22): agent-kit 4 (the lenient helpers); none in the other consumers checked.
Upgrade
github:PerfectPan/lint-config#v0.6.0 → #v0.6.1, then reinstall.
v0.6.0
What changed
oxlint.json now runs no-use-before-define with { "functions": true } (was false):
- Fails now: a function declaration referenced above its declaration, including a call from inside another function's body. Every kind of name —
const,let,var,class,enumand nowfunction— is declared before it is used, so a file reads in one direction: helpers first, the entry last. - Stays allowed: type-only references (default
ignoreTypeReferences).
The README's Decisions entry and the self-test are updated; no other rule changed.
What newly fails
export function main(): number {
return helper();
// error eslint(no-use-before-define): 'helper' was used before it was defined.
}
function helper(): number {
return 1;
}How to fix
- Move the function declaration (with its comments) above its first use. Moving a
functiondeclaration never changes behavior: declarations are hoisted. - oxlint has no autofix for this rule.
- Two functions that call each other cannot both come first: keep the order and put
// oxlint-disable-next-line no-use-before-defineon the use, with the reason, or restructure.
How to exempt
// oxlint-disable-next-line no-use-before-definereportUnusedDisableDirectives: "error" fails the comment once it is no longer needed. A repository can also set "functions": false in its own config.
Impact on consumers
Measured with oxlint 1.87.0 and a config that enables only this rule:
| Repository | Hits |
|---|---|
| agent-kit | 417 (reordered before adopting the tag) |
| project-template-rush | 0 |
The other consumers are measured when they adopt the tag.
v0.5.0
What changed
oxlint.json enables no-unnecessary-condition as an error with { "allowConstantLoopConditions": "always" } (type-aware; it runs through the existing typeAware pass):
- Fails: a condition, optional chain or
??whose outcome the types already decide —?.on a value that is never nullish,??on a non-nullable left-hand side, anifon a value that is always truthy or always falsy. - Stays allowed:
?.and??on genuinely optional values, andwhile (true)as the intentional infinite-loop idiom (allowConstantLoopConditions: "always").checkTypePredicateskeeps its default (false).
vite-plus.d.ts describes the new rule; the version bump and README are updated. No other rule changed.
What newly fails
interface Config {
name: string;
}
export function label(config: Config): string {
return config?.name ?? "unnamed";
// error typescript(no-unnecessary-condition): Unnecessary optional chain on a non-nullish value.
// error typescript(no-unnecessary-condition): Unnecessary conditional, expected left-hand side of `??` operator to be possibly null or undefined.
}How to fix
- Drop the
?.or??when the type says the value is always present. - If the value really can be missing, make the type say so (
name?: string, or a schema that marks the field optional); the rule then accepts the check. - An always-true or always-false
ifusually means a stale branch: delete it, or fix the type that made it constant.
How to exempt
// oxlint-disable-next-line no-unnecessary-conditionreportUnusedDisableDirectives: "error" fails the comment once the code no longer needs it. A repository can also turn the rule off in its own config; local settings win over the shared ones.
Impact on consumers
Measured with oxlint 1.86.0 and a type-aware config that enables only this rule, over authored sources on each default branch:
| Repository | Hits |
|---|---|
| agent-kit | 12 |
| project-template-rush | 0 |
The other consumers are measured when they adopt the tag.
v0.4.0
What changed
oxlint.json enables no-use-before-define as an error with { "functions": false }:
- Fails: a
const,let,var,classorenumin any scope — including an arrow-function constant and a
name in anexport { name }list — referenced above its declaration. TypeScript already rejected a direct
top-level read in the temporal dead zone; the new hits are mostly references inside function bodies. - Stays allowed: function declarations (
functions: false— they hoist, and an entry function above its
helpers is the intended top-down reading order) and type-only references (defaultignoreTypeReferences).
vite-plus.d.ts describes the new rule; the version bump and README are updated. No other rule changed.
What newly fails
export function headline(): string {
return status;
}
const status = "ready";
// error eslint(no-use-before-define): 'status' was used before it was defined.Arrow-function constants behave like variables, so this fails too:
const run = () => helper(); // error: 'helper' was used before it was defined
const helper = () => 1;How to fix
- Move the declaration above its first use.
- Or turn an arrow-function constant into a
functiondeclaration, which is exempt underfunctions: false. - For two callbacks that reference each other (a timer and its cleanup), declare the one used first as a
function, or declarelet timerfirst and assign it afterwards.
How to exempt
// oxlint-disable-next-line no-use-before-defineUse it only where the order is genuinely load-bearing. The shared config sets
reportUnusedDisableDirectives: "error", so the comment fails once the code no longer needs it. A repository can
also turn the rule off (or restrict it to directories) in its own config; local settings win over the shared ones.
Impact on consumers
Measured with oxlint 1.86.0 and a config that enables only this rule, over each consumer's default branch (authored
code only; Rush's vendored common/scripts/install-run*.js is not linted by these repositories):
| Repository | Hits |
|---|---|
| agent-kit | 18 |
| agent-task-loop | 16 |
| agent-presence | 1 |
| project-template-rush | 0 |
| two private repositories | 54 and 5 |
Upgrade
Change the dependency specifier from github:PerfectPan/lint-config#v0.3.2 to
github:PerfectPan/lint-config#v0.4.0 and reinstall. vite-plus consumers keep spreading ...lint.rules and
...lint.overrides as before; the new rule arrives through lint.rules.
v0.3.2
tsconfig/base.jsonno longer enablesexactOptionalPropertyTypes. A repository that already separates absent fromundefinedproperties enables it in its own tsconfig; repositories that widened optional types to?: T | undefinedto satisfy it can revert that.
Upgrade: change #v0.3.1 to #v0.3.2, then reinstall.