arkcompiler_ets_frontend/docs/Linter_Knowledge_Base.md

name, description

name	description
linter-knowledge-base	Reference knowledge base for ets2panda/linter migration tool. Use when modifying TypeScriptLinter/HomeCheck rules, debugging autofix conflicts, investigating lint behavior, or setting up linter build/test. Use when working in ets2panda/linter directory.

Linter Knowledge Base

Document version: v1.1 Last updated: 2026-07-31 Scope: arkcompiler/ets_frontend/ets2panda/linter (repo-relative path: ets2panda/linter)

Summary

1. Linter is migration assistance (≠ compiler), helps ArkTS-dynamic → ArkTS-static
2. TypeScriptLinter (single-file) vs HomeCheck (cross-file) → check Decision Table first
3. Rule changes need 8-point/6-point synchronization → follow Verification Checklist
4. Dependency reproducibility is part of linter correctness → lock transitive npm behavior and verify all package layers

When to Use

• Modifying TypeScriptLinter or HomeCheck rules
• Debugging autofix conflicts or migration behavior
• Investigating false positives/negatives in lint
• Setting up linter build/test environment
• Debugging npm install/build drift, @types/node conflicts, HomeCheck/ArkAnalyzer packaging, or lockfile behavior

When NOT to use:

• Compiler semantic changes → ets2panda/Static_Frontend_Knowledge_Base.md
• Parser/lexer issues → parser KB (if exists in repo structure)
• LSP interaction → ets2panda/LSP_Knowledge_Base.md
• Obfuscation tool → ArkGuard_Knowledge_Base.md

Overview

ets2panda/linter is an ArkTS migration-oriented static analysis subsystem independent from the main compilation pipeline. Tool: easytrans/tslinter, npm package: @panda/tslinter, CLI entry: dist/tslinter.js.

Input: .ets/.ts/.js files, project config, SDK paths, rule config. Output: lint diagnostics, IDE JSON, migration results, autofix reports, statistics. Core goal: help ArkTS-dynamic/TypeScript migrate to ArkTS-static constraints by detecting syntax, type, SDK, ArkUI, interop risks and providing automatic fixes.

Naming conventions:

• HomeCheck: migration checker capability; homecheck/: directory and npm package
• ArkAnalyzer: underlying analysis capability; arkanalyzer/: directory and npm package
• TypeScriptLinter: main rule implementation (TypeScript AST + type checker)
• InteropTypescriptLinter: TS/ETS interoperability rules

Typical issues: rule false positives/negatives, autofix conflicts, unexpected migration, abnormal IDE JSON, SDK resolution errors, test expectation mismatches. Dependency issues also occur: transitive npm updates, mismatched @types/node, unstable package-lock.json, and install scripts that temporarily rewrite package metadata.

Directory Structure And Code Map

• Upstream (external): source input, SDK paths, TypeScript/ohos-typescript dependencies
• Upstream (internal): HomeCheck/ArkAnalyzer foundation, rule config
• Current module (internal): src/, homecheck/, arkanalyzer/, scripts/, docs/, test/
• Downstream (internal): lint results, migration/statistics output
• Downstream (external): IDE/DevEco consumers, npm artifacts, GN build artifacts

Data flow: CLI input → src/cli + src/lib → TypeScriptLinter (AST + type checker) or HomeCheck (Scene + CFG/VFG) → merge diagnostics → output JSON/reports/statistics → IDE/DevEco consumers.

Directory Explanations

ets2panda/linter/
├── src/cli/                  # CLI entry, argument parsing
├── src/lib/                  # TypeScript linter core
│   ├── data/                 # JSON allow/deny lists, SDK data
│   ├── utils/consts/         # Rule constants, helper tables
│   ├── autofixes/            # Autofix generation, conflict resolution
│   ├── statistics/           # Statistics and reporting
│   ├── ts-compiler/          # TypeScript program construction
│   └── ts-diagnostics/       # TSC diagnostics extraction
├── src/sdk/linter_1_1/       # SDK/Hvigor incremental lint
├── homecheck/                # Migration checker (Scene + checkers)
├── arkanalyzer/              # Underlying static analysis library
├── scripts/                  # Build/install scripts
├── docs/                     # Rule documentation
└── test/                     # Test cases and expectations

Key files: TypeScriptLinter.ts (core rules), HomeCheck.ts (adapter), QuasiEditor.ts (autofix), Problems.ts (FaultID), CookBookMsg.ts (messages), rule-config.json (IDE filtering), homecheck/ruleSet.json (16 migration rules).

Core Files And Responsibilities

File	Responsibility
TypeScriptLinter.ts	Core rule implementation (AST + type checker)
InteropTypescriptLinter.ts	TS/ETS interoperability rules
HomeCheck.ts	Adapter, converts FileIssues to ProblemInfo
QuasiEditor.ts	Autofix sorting, conflict handling, source replacement
Problems.ts	FaultID enum - stable rule index
FaultAttrs.ts	Maps FaultID to recipe number, severity
CookBookMsg.ts	User-visible messages, rule name in final parentheses
Autofixer.ts	Tool for rules to generate replacements
LinterRunner.ts	Main executor: file filtering, rule execution, migration
rule-config.json	IDE/migration rule classification
homecheck/ruleSet.json	HomeCheck rule set (16 rules currently)
package.json / package-lock.json	Reproducible npm dependency graph for linter, HomeCheck, ArkAnalyzer
scripts/install-ohos-typescript-and-homecheck.mjs	Packs and installs ohos-typescript, ArkAnalyzer, HomeCheck into the linter package

Responsibility Boundaries

Responsible for: rule checking, static analysis for migration, migration suggestions, autofix candidates, reports, statistics, IDE JSON protocol.

NOT responsible for: real ArkTS-static type relations → ets2panda/checker; AST structural changes → ets2panda/lowering or ets2panda/parser; runtime semantics → companion runtime repos (outside this KB scope).

Do not copy complete compiler type system into linter layer.

Why TypeScriptLinter ≠ Compiler

Motivation: Linter uses TypeScript's type checker (external dependency ohos-typescript), while compiler owns ArkTS-static type system. Copying compiler semantics creates:

• Version mismatch risk (ohos-typescript ≠ ArkTS-static version)
• Dual maintenance burden (update both compiler + linter)
• False authority (linter suggestions ≠ compiler facts, designed differences exist)

Example: Linter may warn "conservative" for migration safety, while compiler allows. Check Decision Table first before modifying compiler.

Code Anchors (First Files to Inspect)

By symptom, start with these files in order:

Symptom	First files (inspect order)
Rule false positive	TypeScriptLinter.ts → TsUtils.ts → CookBookMsg.ts → check FaultID and recipe
Autofix conflict	QuasiEditor.ts → RulePriority.ts → check offset calculation and priority
HomeCheck missing	HomeCheck.ts → CheckerIndex.ts → ruleSet.json → verify registration and description
IDE protocol abnormal	LinterCLI.ts → ProblemInfo.ts → check indictor field and JSON structure
SDK resolution error	ResolveSdks.ts → src/lib/data/*.json → verify SDK path and declarations
Test expectation mismatch	test/**/results/*.diff → inspect actual output → fix logic → then update
Dependency/install drift	nearest package.json → nearest package-lock.json → scripts/install-ohos-typescript-and-homecheck.mjs

Top Don'ts (Critical)

Do NOT:

1. Modify compiler for linter issues → Check Decision Table first, linter is migration assistance
2. Update test expectations before fixing logic → Inspect .diff first → fix logic → then update
3. Skip rule-config.json → IDE won't filter rule, must synchronize ALL 8/6 points
4. Rebuild Scene in HomeCheck → Exponentially slower, use Utils.ts helpers
5. Calculate autofix offsets from token text → Corrupt replacements, must use original source offsets
6. Hardcode SDK paths → Change across versions, use ResolveSdks.ts mechanisms
7. Change IDE protocol without verifying consumer → Break IDE/DevEco integration
8. Copy compiler type system → Linter uses TypeScript's checker, not ArkTS-static
9. Forget synchronization points → Incomplete rule changes, verify checklist
10. Treat diagnostic differences as bugs → Designed differences exist (IDE mode disables strict diagnostics)
11. Ignore lockfiles in linter package layers → Transitive npm drift can break builds without source changes
12. Assume semver patch updates are harmless → Type declarations can change compatibility, especially through @types/node

Core Data Flow Or Control Flow

Normal CLI Scan

1. Parse arguments → collect input files, tsconfig
2. Construct TypeScript programs (strict + non-strict by default)
3. Filter input files → run TypeScriptLinter or InteropTypescriptLinter
4. Merge TSC diagnostics with linter diagnostics → set exit code

Performance note: Dual program improves accuracy but increases memory. IDE mode disables strict diagnostics (disableStrictDiagnostics=true).

IDE Interactive Mode

1. --ide-interactive → followSdkSettings=true, disableStrictDiagnostics=true
2. HomeCheck runs if --arkts-2 --homecheck enabled
3. TypeScriptLinter → merge problems → filterLintProblems() filters interop directions
4. Output: scan-report.json, per-file JSON on stdout, progress on stderr

Progress field: indictor not indicator (consumer dependency, do not change).

Migration / Autofix

1. --migrate → migratorMode=true, enableAutofix=true
2. Merge fixable problems → QuasiEditor.sortAndRemoveIntersections()
3. Sort patches by offset → check intersections → handle conflicts by priority
4. Apply patches → write backups → generate reports

Critical constraints:

• Autofix offsets MUST be based on original source text
• Conflict condition: !(lhs.end < rhs.start || rhs.end < lhs.start) (endpoint touching = conflict)
• Single-patch conflict: resolved by RulePriority (higher replaces lower)
• Multi-patch conflict: marked not fixable (cannot auto-resolve)

Autofix data structure:

interface Autofix {
  start: number;  // MUST be original source offset
  end: number;    // MUST be original source offset
  text: string;   // replacement
}

HomeCheck Migration Flow

1. HomeCheck.ts constructs config → MigrationTool.buildCheckEntry()
2. checkEntryBuilder() filters files → builds Scene → inferTypes() → scopes
3. CheckerIndex.ts divides rules (file-level / project-level) → runs checkers
4. transferIssues2ProblemInfo() converts to ProblemInfo → QuasiEditor writes files

Common failures: empty projectPath, paths outside project, incorrect SDK list, languageTags not covering files, missing built-in SDK, no files after filtering.

Knowledge Routing

• Lint tools, rules, migration → start with this document
• CLI arguments, modes → src/cli/CommandLineParser.ts, src/cli/LinterCLI.ts
• AST/type rules → src/lib/TypeScriptLinter.ts, src/lib/BaseTypeScriptLinter.ts
• Rule names, recipes → src/lib/Problems.ts, src/lib/FaultAttrs.ts, src/lib/CookBookMsg.ts
• Rule classification → rule-config.json, src/lib/utils/functions/ConfiguredRulesProcess.ts
• Autofix, migration → src/lib/autofixes/QuasiEditor.ts, src/lib/autofixes/Autofixer.ts
• HomeCheck rules → homecheck/src/checker/migration/*, homecheck/src/utils/common/CheckerIndex.ts
• SDK paths, resolution → src/lib/ts-compiler/ResolveSdks.ts
• Dependency drift, lockfiles, npm packaging → package.json, package-lock.json, scripts/install-ohos-typescript-and-homecheck.mjs
• Compiler type system → ets2panda/Static_Frontend_Knowledge_Base.md
• LSP interaction → ets2panda/LSP_Knowledge_Base.md
• Build/test → see Build section below

Output Protocol

IDE mode outputs:

• stdout: one JSON per line { "filePath": string, "problems": ProblemInfo[] }
• stderr: progress JSON { "content", "messageType": 1, "indicator": number }
• finish marker: {"content":"report finish","messageType":1,"indictor":1} (field is indictor)

ProblemInfo fields: line, column, endLine, endColumn, start, end, type, severity, faultId, problem, suggest, rule, ruleTag, autofixable, autofix, autofixTitle.

Reports: scan-report.json (per-file problems), scan-problems-statistics.json (counts, timing), autofix-report.html (fix details, field colum/endColum intentional).

Rule System

TypeScriptLinter path:

FaultID (Problems.ts) → FaultAttrs[FaultID].cookBookRef → cookBookTag[recipe] (CookBookMsg.ts)
  → user-visible "rule" (final parentheses) → rule-config.json (IDE filtering)

HomeCheck path (no FaultID):

metaData.description → findRuleTagByDesc() extracts rule name from parentheses
  → searches cookBookTag[1..N] → if match fails, ruleTag = -1 (IDE/statistics lose recipe)

Critical constraint: User-visible text must put stable rule name in final parentheses. Regex: /.*\(([^)]+)\)[^(]*$/. Other parentheses before rule name → lookup failure.

Modification Synchronization Points (Critical)

TypeScriptLinter rule (8 points):

1. Problems.ts: Add/reuse FaultID
2. FaultAttrs.ts: Bind recipe number and severity
3. CookBookMsg.ts: User-visible text with rule name in final parentheses
4. TypeScriptLinter.ts: Implement detection
5. Autofixer.ts / AutofixTitles.ts: Autofix if needed
6. rule-config.json: Classification for IDE filtering
7. docs/rules-cn / docs/rules-en: Documentation
8. test/: Test cases (*.json, *.arkts2.json, *.autofix.json, *.migrate.json, *.migrate.ets)

HomeCheck rule (6 points):

1. homecheck/src/checker/migration/: Implement BaseChecker methods
2. homecheck/src/utils/common/CheckerIndex.ts: Register under fileRules or projectRules
3. homecheck/ruleSet.json: Add @migration/* rule to plugin:@migration/all
4. Verify metaData.description matches findRuleTagByDesc() in src/lib/HomeCheck.ts
5. Reuse helpers in homecheck/src/checker/migration/Utils.ts for cross-file data
6. Add HomeCheck vitest cases or linter-side integration tests

Build, Run, And Package

⚠️ Drift-prone content: Commands, scripts, and versions may change. Verify against current tree before use.

Build Modes (drift-prone, verify current version)

There are two different linter build modes. Do not mix their assumptions.

Pipeline build:

• Uses build_linter.py
• Must use the pipeline-specified Node.js and npm versions
• Known pipeline versions: Node.js v14.21.1, npm 6.14.17
• Before running build_linter.py, run npm install with the specified npm executable in each package layer: arkanalyzer, homecheck, then linter root
• Pass absolute paths from the current build environment; do not copy a developer machine path into scripts or documentation

Example command shape:

cd <repo>/ets2panda/linter/arkanalyzer
<node-v14.21.1>/bin/npm install

cd <repo>/ets2panda/linter/homecheck
<node-v14.21.1>/bin/npm install

cd <repo>/ets2panda/linter
<node-v14.21.1>/bin/npm install

python3 build_linter.py \
  --source-path <repo>/ets2panda/linter \
  --output-path <output-dir> \
  --npm <node-v14.21.1>/bin/npm \
  --typescript <repo>/ets2panda/linter/<ohos-typescript-package>.tgz \
  --version <linter-version>

Local developer build:

• Follow ets2panda/linter/README.md
• Does not require the pipeline Node.js/npm versions unless reproducing a pipeline-only issue
• Run npm install, then npm run install-ohos-typescript
• Run npm run build when build/package validation is needed

Common Commands

Command	Purpose	When to use
npm install	Install dependencies	Local setup, or pipeline preinstall when run with the specified npm
npm run install-ohos-typescript	Install ohos-typescript, arkanalyzer, homecheck	Local developer setup after dependency update
python3 build_linter.py ...	Pipeline-style package build	Reproducing pipeline package behavior
npm run build	Local build (clean → compile → webpack → pack)	Local validation before testing
npm test	Full test suite (runs npm run fix first)	Regression
npm run testrunner -- -d test/rules -p 'rule-name*'	Single rule test	Debugging
npm run testrunner -- -d test/main --sdk	SDK-dependent tests	SDK scenarios
npm run coverage	Coverage report	Measurement
npm run update-tests	Update test expectations	Only after confirming correctness

Test File Conventions

Test files: case-name.ets (input), case-name.json (default expectation), case-name.arkts2.json (--arkts-2), case-name.autofix.json (autofix), case-name.migrate.json (migration diagnostics), case-name.migrate.ets (migrated source). Results in test/**/results/, failures generate .diff.

Test directories: test/main, test/rules, test/regression (main rules), test/interop (interop rules), test/sdkwhite, test/sdkcommonapi (SDK rules), test/builtin, test/concurrent (dedicated domains).

Common Run Commands

Normal scan: node dist/tslinter.js --arkts-2 path/to/file.ets

IDE + HomeCheck + migration: node dist/tslinter.js --ide-interactive --arkts-2 --autofix --homecheck --migrate --sdk-default-api-path /path/to/sdk ...

Critical parameters: --project <tsconfig> (construct program), --project-folder <dir> (collect files), --check-ts-and-js (allow .ts/.js), --rule-config <path> (rule classification), --sdk-default-api-path (must contain build-tools/ets-loader/declarations).

Dependency And Packaging Stability

ets2panda/linter is a multi-package npm workspace in practice, even though it is arranged as repo subdirectories instead of a formal npm workspace. The root linter package depends on local homecheck, and homecheck depends on local arkanalyzer. A build or packaging issue may come from any of these layers:

ets2panda/linter/package.json
  → homecheck/package.json
    → arkanalyzer/package.json
  → build_linter.py
  → scripts/install-ohos-typescript-and-homecheck.mjs
  → package-lock.json files generated for each package layer

Dependency Drift Rules

Treat dependency reproducibility as a compatibility boundary for the migration tool. A dependency-only change can break npm run compile, generated package contents, IDE integration, or downstream SDK builds even when linter TypeScript source code is unchanged.

Rules:

• Keep package-lock.json tracked for linter package layers that participate in build/package reproduction; do not hide them with .gitignore.
• When an install script temporarily mutates a managed package.json, back up and restore the matching package-lock.json as well.
• Treat an absent, ignored, or accidentally regenerated lockfile as dependency graph drift until proven intentional.
• Prefer explicit pins or npm overrides for transitive packages known to affect TypeScript declaration, runtime, or package-export compatibility.
• After changing dependencies or package scripts, inspect the resolved transitive versions in package-lock.json, not only direct dependencies in package.json.
• Verify the full package chain with the relevant build mode: pipeline uses specified Node.js/npm plus build_linter.py; local development follows README.md with npm install and npm run install-ohos-typescript.

General pattern: If lockfiles are missing or not restored after temporary installs, transitive packages can move under the same direct dependency declarations. The failure may appear as an unrelated TypeScript compile error, changed package contents, or SDK build break. Fix the reproducibility boundary first: restore or commit the correct lockfiles, then add pins/overrides only for dependencies whose resolved versions must remain constrained.

Install Script Safety

build_linter.py and scripts/install-ohos-typescript-and-homecheck.mjs run npm install, npm pack, and local package installation across arkanalyzer, homecheck, and linter. These scripts can create or rewrite package metadata as a side effect.

When touching these scripts:

• Treat package.json and package-lock.json as a pair.
• If a lockfile did not exist before a temporary install, restore by removing the generated lockfile after packaging.
• If a lockfile existed before a temporary install, restore the original file after packaging.
• Confirm the final worktree contains only intentional dependency metadata changes.
• For pipeline behavior, reproduce with the specified Node.js/npm versions and build_linter.py.
• For local developer behavior, run npm run install-ohos-typescript and then npm run build when dependency/package behavior changes.

Dependency Debugging Checklist

For npm compile/install failures, check in this order:

1. Identify which package layer fails: linter root, homecheck, or arkanalyzer
2. Compare direct dependencies in the nearest package.json
3. Inspect resolved transitive versions in the nearest package-lock.json
4. Check whether @types/node or another type package is resolved through multiple incompatible paths
5. Check whether overrides or exact pins are needed for known fragile transitive packages
6. Re-run the package chain from the lowest failing layer upward, using the same build mode that failed

Useful commands:

npm ls <package> @types/node
npm explain <package>
npm explain @types/node
npm --prefix arkanalyzer run compile
npm --prefix homecheck run compile
npm run compile
python3 build_linter.py --source-path <repo>/ets2panda/linter --output-path <output-dir> --npm <node-v14.21.1>/bin/npm --typescript <repo>/ets2panda/linter/<ohos-typescript-package>.tgz --version <linter-version>

Expert Experience

Common rationalizations (anti-excuses):

Rationalization	Reality
"I'll modify the compiler"	Linter is for migration, not compiler semantics. Check decision table first.
"I'll update test expectations"	Inspect .diff first → fix logic → only update after confirming correctness. Migration test counts are hard constraints.
"I'll skip rule-config.json"	Rule won't be filtered in IDE mode. Synchronize ALL 8 or 6 points.
"I'll add tests later"	Rule may not be found in test runner. Add test cases immediately.
"I'll reuse compiler type system"	Linter uses TypeScript's type checker, not ArkTS-static. Do not copy compiler type relations.
"I'll rebuild Scene in my checker"	Makes project-level rules exponentially slower. Use Utils.ts helpers.
"I'll calculate offsets from token text"	QuasiEditor applies patches by original source offsets. Shifted offsets corrupt all later replacements.
"I'll hardcode SDK paths"	SDK directories change across versions. Use ResolveSdks.ts and src/lib/data/*.json.
"It's only a transitive npm patch update"	Type declarations and package exports can change build compatibility. Check lockfile resolution and compile every package layer.
"The script only changes package.json temporarily"	npm install can also rewrite package-lock.json; back up and restore both files.

Anti-Patterns

• Treating linter issues as compiler bugs → modifying main compilation pipeline
• Copying compiler semantic implementations into linter layer
• Updating test expectations without checking rule design purpose
• Adding FaultID but forgetting FaultAttrs.ts, CookBookMsg.ts, rule-config.json, docs
• Writing HomeCheck checker but not registering in CheckerIndex.ts / ruleSet.json
• Rebuilding Scene, call graph, DVFG inside HomeCheck checker
• Calculating autofix offsets from token text or intermediate text
• Hardcoding SDK API allowlist paths
• Changing stdout/stderr protocol in IDE mode without verifying consumer side
• Ignoring generated or updated package-lock.json files after package/install scripts
• Fixing a dependency build failure only in the root linter package while homecheck or arkanalyzer still resolves a different transitive graph

Debugging And Verification

Verification Checklist

When modifying linter rules or documentation:

• Decision table checked: TypeScriptLinter vs HomeCheck vs Compiler
• All synchronization points updated (8 for TypeScriptLinter, 6 for HomeCheck)
• Rule name in CookBookMsg.ts final parentheses: "... (rule-name)"
• Rule registered in rule-config.json (IDE filtering) or homecheck/ruleSet.json (HomeCheck)
• Test directory exists under test/, test cases added
• Build commands run successfully: npm run build or GN build
• Test commands run successfully: npm run testrunner -- -d test/rules -p 'rule-name*'
• No compiler files modified (unless intentional cross-component change)
• HomeCheck rule count verified against homecheck/ruleSet.json
• Dependency changes verified across linter, homecheck, and arkanalyzer package layers
• package-lock.json changes are intentional, reviewed, and restored when produced only by temporary install steps

Common Issues Diagnosis

Issue	Quick diagnosis
Migration doesn't modify source	Check: 1) autofix array exists, 2) not filtered by --autofix-rule-config, 3) no intersection conflict, 4) written to results/ mapped path
IDE doesn't show rule	Check: 1) rule-config.json contains rule, 2) final parentheses rule name matches, 3) ruleConfigTags not filtered
HomeCheck results missing	Check: 1) --ide-interactive --arkts-2 --homecheck all passed, 2) file not filtered by removeOutOfRangeFiles(), 3) interop direction not filtered
HomeCheck rule tag -1	Check: final parentheses rule name in metaData.description can be found in cookBookTag (regex: desc.match(/\(([^)]+)\)/))
Test line/column differ	Check: 1) TsUtils.getHighlightRange() logic, 2) node getStart() method, 3) autofix range calculation, 4) TSC diagnostics merge order changed
npm run compile fails after dependency refresh	Check: 1) failing package layer, 2) missing/rewritten package-lock.json, 3) transitive version drift, 4) type package compatibility, 5) npm overrides/pins
Package script leaves dirty lockfiles	Check: 1) temporary npm install paths, 2) backup/restore of both package.json and package-lock.json, 3) final git status --short
Unexpected .d.ts type errors	Check: whether an unlocked transitive dependency changed its declarations or pulled a different @types/* version; restore lockfile stability before changing source code

FAQ

1. Lint results differ from compiler → Check if designed difference or preceding semantic judgment error
2. Migration/statistics script abnormal → Check script input format, rule set, analyzer output chain
3. Command line can scan, but IDE doesn't show rule → Check rule-config.json contains rule, final parentheses rule name matches
4. Migration doesn't modify source → See Common Issues table above
5. HomeCheck results missing → See Common Issues table above
6. SDK API rules miss reports → Confirm --sdk-default-api-path points to openharmony/ets and contains build-tools/ets-loader/declarations
7. Test fails but line/column differ slightly → Do not update expectations first. Check TsUtils.getHighlightRange(), node getStart(), autofix range
8. HomeCheck rule tag -1 → See Common Issues table above
9. Rule counts missing from statistics → Confirm ProblemInfo.rule contains final parentheses rule name, rule-config.json contains rule
10. Dependency install or compile suddenly fails → Check lockfiles and transitive type packages first; semver-compatible updates can still change .d.ts compatibility
11. Why track linter lockfiles? → The linter package chain depends on transitive npm resolution. Lockfiles preserve the tested graph for root linter, HomeCheck, and ArkAnalyzer.

Related Documents

• AGENTS.md -- repository-level routing and constraints
• ets2panda/Static_Frontend_Knowledge_Base.md -- static frontend pipeline boundaries
• ets2panda/LSP_Knowledge_Base.md -- LSP interaction surface and downstream consumers
• ArkGuard_Knowledge_Base.md -- obfuscation and migration-adjacent tooling context