majiayu000 Auditing Libraries
Analyze existing libraries for convention violations and report issues.
CRITICAL
Read Conventions Before Auditing
The authoritative convention documents are:
~/.claude/docs/conventions/namespace-module.md— Core_.ts/__.tspattern~/.claude/docs/conventions/library-local.md— Local library context (src/lib/)~/.claude/docs/conventions/library-package.md— Package-level context
Read these before auditing to understand the full rules.
Operations
Audit Single Library
Check a specific library for violations.
Steps:
- Identify library type (local lib, package lib)
- Check file structure matches expected pattern
- Validate
_.tscontent - Validate
__.tscontent (if exists) - Check import patterns in code modules
- Verify test file imports
- Report all violations found
Audit All Libraries
Scan project for all libraries and check each.
Steps:
- Find all directories containing
_.tsfiles - Categorize each (local lib at
src/lib/*, package lib atsrc/*) - Audit each library individually
- Summarize violations by category
Fix Violations
After auditing, fix identified issues.
Steps:
- Present violations to user
- Propose fixes for each
- Apply fixes with user approval
- Re-audit to confirm resolution
Violation Categories
Structure Violations
| Violation | Description | Fix |
|---|---|---|
Missing _.ts |
Library has no namespace module | Create _.ts with correct export |
Missing __.ts |
Multiple impl files but no barrel | Create __.ts with re-exports |
Extra __.ts |
Single impl file with barrel | Remove __.ts, update _.ts |
| Wrong location | Library not in src/lib/ |
Move to correct location |
Namespace Module (_.ts) Violations
| Violation | Description | Fix |
|---|---|---|
| Wrong export target | Points to wrong file | Fix export path |
| Has imports | Contains import statements | Remove imports |
| Wrong namespace name | Doesn't match directory | Fix namespace name |
| Missing barrel reference | Has __.ts but exports from impl |
Change to from './__.js' |
Barrel Module (__.ts) Violations
| Violation | Description | Fix |
|---|---|---|
Imports from _.ts |
Circular dependency | Remove import |
| Value imports | Has import { x } not re-export |
Convert to export { x } from |
| External imports | Imports from outside library | Move to code module |
| Parent imports | Imports from ../ |
Remove or restructure |
Import Pattern Violations
| Violation | Description | Fix |
|---|---|---|
| Destructured namespace | import { Foo } from '#lib' |
Use import { Lib } from '#lib' then Lib.Foo |
| Self namespace import | Code imports own _.ts |
Use relative imports |
| Self barrel import | Code imports own __.ts |
Use relative imports |
| Relative cross-lib | import from '../other-lib' |
Use #other-lib |
Test Violations
| Violation | Description | Fix |
|---|---|---|
| Wrong import | Test imports from impl file | Import from ./_.js |
| Destructured | Test destructures namespace | Use namespace directly |
| Missing fixture namespace | Fixture doesn't export Fx |
Add export namespace Fx |
Audit Checklist
## Library: <name>
### Structure
* [ ] Located at correct path (src/lib/<name>/ or src/<name>/)
* [ ] Has _.ts namespace module
* [ ] Has __.ts barrel (if multiple impl files)
* [ ] No __.ts (if single impl file)
### Namespace Module (_.ts)
* [ ] Correct export pattern
* [ ] Namespace name matches directory (PascalCase)
* [ ] No import statements
* [ ] Points to __.ts (if exists) or impl file
### Barrel Module (__.ts) - if exists
* [ ] Only contains re-exports
* [ ] No imports from _.ts
* [ ] No external package imports
* [ ] All exports from local files
### Code Modules
* [ ] No imports from own _.ts
* [ ] No imports from own __.ts
* [ ] Cross-lib imports use #<name>
* [ ] Sibling imports use relative paths
### Tests (_.test.ts)
* [ ] Imports from ./_.js only
* [ ] Uses namespace, no destructuring
* [ ] No top-level describe wrapping all tests
### Config
* [ ] package.json has imports entry
* [ ] tsconfig.json has paths entry
Examples
Violation Report Format
Library: src/lib/parser/
VIOLATIONS FOUND: 3
1. [NAMESPACE] _.ts has wrong export
Current: export * from './parser.js'
Expected: export * as Parser from './__.js'
Reason: __.ts exists, so _.ts must export namespace from barrel
2. [IMPORT] tokenizer.ts imports from own namespace
Line 3: import { Parser } from './_.js'
Fix: Use relative import: import { helper } from './helper.js'
3. [TEST] _.test.ts destructures namespace
Line 1: import { tokenize, lex } from './_.js'
Fix: import { Parser } from './_.js' then use Parser.tokenize
Notes
- Run
/fix-conventionscommand for automated fixing - Some violations require architectural decisions (restructuring)
- Package-level libraries have different path expectations