project-structure-lint 1.0.1

package/.validate-structurerc.example.json

@@ -0,0 +1,45 @@
+{
+  "preset": "react",
+  "rootDir": "src",
+  "rules": {
+    "componentColocation": {
+      "enabled": true,
+      "componentDirs": ["components", "pages", "features"],
+      "requiredFiles": [
+        {
+          "pattern": "*.test.{ts,tsx,js,jsx}",
+          "required": true,
+          "description": "Test file for component"
+        },
+        {
+          "pattern": "*.stories.{ts,tsx,js,jsx}",
+          "required": true,
+          "description": "Storybook story file"
+        }
+      ],
+      "namingConvention": "PascalCase"
+    },
+    "fileNaming": {
+      "components/**/*.{tsx,jsx}": {
+        "convention": "PascalCase",
+        "severity": "error"
+      },
+      "hooks/**/*.{ts,tsx,js,jsx}": {
+        "convention": "camelCase",
+        "severity": "error"
+      },
+      "utils/**/*.{ts,js}": {
+        "convention": "camelCase",
+        "severity": "error"
+      }
+    }
+  },
+  "ignore": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    "**/coverage/**"
+  ],
+  "severity": "error"
+}

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2024-12-24
+
+### Added
+- Initial release of project-structure-lint
+- Component co-location validation
+- File naming convention enforcement (PascalCase, camelCase, kebab-case, snake_case, UPPER_CASE)
+- Folder structure validation
+- React preset with sensible defaults
+- CLI commands: `check`, `init`, `presets`
+- Configurable rules via `.validate-structurerc.json`
+- Detailed error reporting with suggestions
+- Support for ignore patterns
+- Programmatic API for integration
+- Comprehensive documentation and examples
+
+### Features
+- ✅ Validates component files are co-located with tests and stories
+- ✅ Enforces naming conventions across different file types
+- ✅ Validates project folder structure
+- ✅ Configurable severity levels (error/warning)
+- ✅ CI/CD integration support
+- ✅ Colored console output
+- ✅ Glob pattern support for file matching
+
+## [Unreleased]
+
+### Planned
+- Vue.js preset
+- Angular preset
+- Node.js/Express preset
+- Auto-fix capability
+- JSON/HTML report formats
+- VS Code extension
+- GitHub Action
+- More granular configuration options

package/CONTRIBUTING.md

@@ -0,0 +1,142 @@
+# Contributing to project-structure-lint
+
+Thank you for your interest in contributing! This document provides guidelines for contributing to the project.
+
+## Development Setup
+
+1. **Clone the repository**
+```bash
+git clone https://github.com/yourusername/project-structure-lint.git
+cd project-structure-lint
+```
+
+2. **Install dependencies**
+```bash
+npm install
+```
+
+3. **Build the project**
+```bash
+npm run build
+```
+
+4. **Run tests**
+```bash
+npm test
+```
+
+## Project Structure
+
+```
+project-structure-lint/
+├── src/
+│   ├── core/           # Core validation logic
+│   ├── config/         # Configuration loading
+│   ├── presets/        # Built-in presets
+│   ├── reporters/      # Output formatters
+│   ├── utils/          # Utility functions
+│   ├── types/          # TypeScript types
+│   ├── cli.ts          # CLI entry point
+│   └── index.ts        # Library entry point
+├── tests/              # Test files
+└── dist/               # Compiled output
+```
+
+## Adding a New Preset
+
+To add a new preset (e.g., Vue, Angular):
+
+1. Create a new file in `src/presets/`:
+```typescript
+// src/presets/vue.ts
+import { Preset } from '../types';
+
+export const vuePreset: Preset = {
+  name: 'vue',
+  description: 'Vue.js project structure',
+  config: {
+    // Your configuration here
+  }
+};
+```
+
+2. Export it in `src/presets/index.ts`:
+```typescript
+import { vuePreset } from './vue';
+
+export const presets: Record<string, Preset> = {
+  react: reactPreset,
+  vue: vuePreset  // Add your preset
+};
+```
+
+3. Add tests for your preset
+
+4. Update documentation
+
+## Adding New Validation Rules
+
+1. Add the rule type to `src/types/index.ts`
+2. Implement the validation logic in `src/core/validator.ts`
+3. Add tests in `src/core/__tests__/`
+4. Update documentation
+
+## Testing
+
+- Write unit tests for all new features
+- Ensure all tests pass before submitting PR
+- Aim for high test coverage
+
+```bash
+npm test                 # Run tests
+npm test -- --coverage   # Run with coverage
+```
+
+## Code Style
+
+- Use TypeScript for all new code
+- Follow existing code style
+- Run linter before committing:
+```bash
+npm run lint
+```
+
+## Commit Messages
+
+Use clear, descriptive commit messages:
+- `feat: add Vue preset`
+- `fix: correct naming validation for hooks`
+- `docs: update README with examples`
+- `test: add tests for file scanner`
+
+## Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for your changes
+5. Ensure all tests pass
+6. Update documentation
+7. Commit your changes
+8. Push to your fork
+9. Open a Pull Request
+
+## Pull Request Guidelines
+
+- Provide a clear description of the changes
+- Reference any related issues
+- Include screenshots for UI changes
+- Ensure CI passes
+- Request review from maintainers
+
+## Questions?
+
+Feel free to open an issue for:
+- Bug reports
+- Feature requests
+- Questions about the code
+- Documentation improvements
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kiran Badave
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROJECT_SUMMARY.md

@@ -0,0 +1,252 @@
+# Project Summary: project-structure-lint
+
+## Overview
+
+A fully functional CLI tool and npm package for validating project folder structure and file naming conventions with configurable presets.
+
+## ✅ Completed Features
+
+### Core Functionality
+- ✅ **Component Co-location Validation** - Ensures related files (tests, stories) are in the same folder
+- ✅ **File Naming Convention Enforcement** - Supports 5 conventions (PascalCase, camelCase, kebab-case, snake_case, UPPER_CASE)
+- ✅ **Folder Structure Validation** - Enforces project directory organization
+- ✅ **React Preset** - Pre-configured rules for React projects
+- ✅ **Configurable Rules** - Fully customizable via JSON configuration
+- ✅ **Ignore Patterns** - Glob-based file/directory exclusion
+
+### CLI Commands
+- ✅ `validate-structure check` - Run validation
+- ✅ `validate-structure init` - Initialize configuration
+- ✅ `validate-structure presets` - List available presets
+
+### Developer Experience
+- ✅ **Detailed Error Reporting** - Clear messages with suggestions
+- ✅ **Colored Console Output** - Easy-to-read results
+- ✅ **Exit Codes** - CI/CD integration support
+- ✅ **Programmatic API** - Use as a library
+
+### Quality Assurance
+- ✅ **TypeScript** - Full type safety
+- ✅ **Unit Tests** - Jest test suite (15 tests passing)
+- ✅ **Build System** - TypeScript compilation
+- ✅ **Type Declarations** - Generated .d.ts files
+
+### Documentation
+- ✅ **README.md** - Comprehensive documentation
+- ✅ **QUICK_START.md** - 5-minute getting started guide
+- ✅ **CONTRIBUTING.md** - Contribution guidelines
+- ✅ **CHANGELOG.md** - Version history
+- ✅ **Example Config** - Sample configuration file
+
+## 📁 Project Structure
+
+```
+project-structure-lint-lint/
+├── src/
+│   ├── cli.ts                      # CLI entry point
+│   ├── index.ts                    # Library entry point
+│   ├── config/
+│   │   └── loader.ts               # Configuration loading & merging
+│   ├── core/
+│   │   └── validator.ts            # Main validation engine
+│   ├── presets/
+│   │   ├── index.ts                # Preset registry
+│   │   └── react.ts                # React preset configuration
+│   ├── reporters/
+│   │   └── consoleReporter.ts      # Console output formatter
+│   ├── types/
+│   │   ├── index.ts                # TypeScript type definitions
+│   │   └── micromatch.d.ts         # Third-party type declarations
+│   └── utils/
+│       ├── fileScanner.ts          # File system operations
+│       ├── naming.ts               # Naming convention validation
+│       └── __tests__/
+│           └── naming.test.ts      # Unit tests
+├── dist/                           # Compiled JavaScript output
+├── package.json                    # Package configuration
+├── tsconfig.json                   # TypeScript configuration
+├── jest.config.js                  # Jest test configuration
+├── .gitignore                      # Git ignore rules
+├── LICENSE                         # MIT License
+├── README.md                       # Main documentation
+├── QUICK_START.md                  # Quick start guide
+├── CONTRIBUTING.md                 # Contribution guide
+├── CHANGELOG.md                    # Version history
+└── .validate-structurerc.example.json  # Example config
+```
+
+## 🎯 Key Components
+
+### 1. Validation Engine (`src/core/validator.ts`)
+- Scans project directory structure
+- Validates component co-location
+- Checks file naming conventions
+- Validates folder structure rules
+- Generates detailed error reports
+
+### 2. File Scanner (`src/utils/fileScanner.ts`)
+- Recursive directory scanning
+- Glob pattern matching
+- Ignore pattern support
+- Component directory detection
+
+### 3. Naming Validator (`src/utils/naming.ts`)
+- 5 naming convention validators
+- Name conversion utilities
+- Extension handling
+- Test/spec file support
+
+### 4. Configuration System (`src/config/loader.ts`)
+- Cosmiconfig integration
+- Preset merging
+- Configuration validation
+- Default React preset
+
+### 5. Console Reporter (`src/reporters/consoleReporter.ts`)
+- Colored output (chalk)
+- Error/warning formatting
+- Suggestions display
+- Summary statistics
+
+## 📦 Package Details
+
+- **Name**: project-structure-lint
+- **Version**: 1.0.0
+- **License**: MIT
+- **Main**: dist/index.js
+- **Binary**: dist/cli.js
+- **TypeScript**: Full support with declarations
+
+## 🔧 Dependencies
+
+### Runtime
+- `chalk@^4.1.2` - Terminal colors
+- `commander@^11.1.0` - CLI framework
+- `cosmiconfig@^9.0.0` - Configuration loading
+- `glob@^10.3.10` - File pattern matching
+- `micromatch@^4.0.5` - Advanced pattern matching
+
+### Development
+- `typescript@^5.3.3` - TypeScript compiler
+- `jest@^29.7.0` - Testing framework
+- `ts-jest@^29.1.1` - TypeScript Jest integration
+- `eslint@^8.56.0` - Code linting
+
+## 🧪 Testing
+
+- **Framework**: Jest with ts-jest
+- **Coverage**: Unit tests for naming utilities
+- **Status**: All 15 tests passing ✅
+
+## 📝 Configuration Example
+
+```json
+{
+  "preset": "react",
+  "rootDir": "src",
+  "rules": {
+    "componentColocation": {
+      "enabled": true,
+      "componentDirs": ["components", "pages"],
+      "requiredFiles": [
+        {
+          "pattern": "*.test.{ts,tsx}",
+          "required": true
+        }
+      ],
+      "namingConvention": "PascalCase"
+    },
+    "fileNaming": {
+      "components/**/*.tsx": {
+        "convention": "PascalCase",
+        "severity": "error"
+      }
+    }
+  },
+  "ignore": ["**/node_modules/**"]
+}
+```
+
+## 🚀 Usage Examples
+
+### CLI Usage
+```bash
+# Initialize configuration
+npx validate-structure init
+
+# Run validation
+npx validate-structure check
+
+# List presets
+npx validate-structure presets
+```
+
+### Programmatic Usage
+```typescript
+import { ProjectValidator, loadConfig } from 'project-structure-lint';
+
+const config = await loadConfig();
+const validator = new ProjectValidator(config);
+const result = await validator.validate();
+```
+
+## 🎨 Output Example
+
+```
+Project Structure Validation Results
+──────────────────────────────────────────────────
+Files scanned: 45
+Directories scanned: 12
+
+✗ 2 Errors
+
+1. Missing required file: Test file for component
+   Directory: components/Button
+   Expected: Button.test.tsx
+   💡 Create Button.test.tsx in components/Button/
+
+2. File name doesn't follow PascalCase convention
+   File: components/myComponent/myComponent.tsx
+   Actual: myComponent.tsx
+   Expected: MyComponent.tsx
+   💡 Rename to MyComponent.tsx
+```
+
+## 🔮 Future Enhancements
+
+- Additional presets (Vue, Angular, Node.js)
+- Auto-fix capability
+- JSON/HTML report formats
+- VS Code extension
+- GitHub Action
+- Watch mode
+- Custom rule plugins
+
+## 📊 Project Status
+
+- ✅ **Build**: Successful
+- ✅ **Tests**: All passing (15/15)
+- ✅ **TypeScript**: No errors
+- ✅ **Documentation**: Complete
+- ✅ **Ready**: For npm publish
+
+## 🎓 Learning Outcomes
+
+This project demonstrates:
+- CLI tool development with Commander.js
+- TypeScript project structure
+- Configuration management with Cosmiconfig
+- File system operations in Node.js
+- Pattern matching with glob and micromatch
+- Test-driven development with Jest
+- Professional documentation practices
+- npm package publishing workflow
+
+## 📄 License
+
+MIT License - See LICENSE file for details
+
+---
+
+**Status**: ✅ Production Ready
+**Last Updated**: 2024-12-24

package/QUICK_START.md

@@ -0,0 +1,164 @@
+# Quick Start Guide
+
+Get started with `project-structure-lint` in 5 minutes!
+
+## Installation
+
+```bash
+npm install --save-dev project-structure-lint
+```
+
+## Step 1: Initialize Configuration
+
+Run the init command to create a configuration file:
+
+```bash
+npx validate-structure init
+```
+
+This creates `.validate-structurerc.json` with the React preset:
+
+```json
+{
+  "preset": "react",
+  "rules": {
+    "componentColocation": {
+      "enabled": true
+    }
+  }
+}
+```
+
+## Step 2: Run Validation
+
+```bash
+npx validate-structure check
+```
+
+## Step 3: Add to package.json Scripts
+
+```json
+{
+  "scripts": {
+    "validate": "validate-structure check",
+    "precommit": "validate-structure check"
+  }
+}
+```
+
+## Example Project Structure
+
+For a React project, the tool validates this structure:
+
+```
+src/
+├── components/
+│   ├── Button/
+│   │   ├── Button.tsx          ✓ Component file
+│   │   ├── Button.test.tsx     ✓ Test file
+│   │   ├── Button.stories.tsx  ✓ Story file
+│   │   └── index.ts            ✓ Export file
+│   └── Card/
+│       ├── Card.tsx
+│       ├── Card.test.tsx
+│       └── Card.stories.tsx
+├── hooks/
+│   ├── useAuth.ts              ✓ camelCase
+│   └── useAuth.test.ts
+└── utils/
+    ├── formatDate.ts           ✓ camelCase
+    └── formatDate.test.ts
+```
+
+## Common Validation Errors
+
+### Missing Test File
+```
+✗ Missing required file: Test file for component
+  Directory: components/Button
+  Expected: Button.test.tsx
+  💡 Create Button.test.tsx in components/Button/
+```
+
+### Wrong Naming Convention
+```
+✗ File name doesn't follow PascalCase convention
+  File: components/button/button.tsx
+  Actual: button.tsx
+  Expected: Button.tsx
+  💡 Rename to Button.tsx
+```
+
+## Customization
+
+Edit `.validate-structurerc.json` to customize:
+
+```json
+{
+  "preset": "react",
+  "rules": {
+    "componentColocation": {
+      "enabled": true,
+      "componentDirs": ["components", "pages", "features"],
+      "requiredFiles": [
+        {
+          "pattern": "*.test.{ts,tsx}",
+          "required": true
+        },
+        {
+          "pattern": "*.stories.{ts,tsx}",
+          "required": false
+        }
+      ]
+    }
+  },
+  "ignore": [
+    "**/node_modules/**",
+    "**/dist/**"
+  ]
+}
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Validate Structure
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - run: npm ci
+      - run: npx validate-structure check
+```
+
+### Pre-commit Hook
+
+Using Husky:
+
+```json
+{
+  "husky": {
+    "hooks": {
+      "pre-commit": "validate-structure check"
+    }
+  }
+}
+```
+
+## Next Steps
+
+- Read the full [README.md](README.md) for detailed documentation
+- Check [CONTRIBUTING.md](CONTRIBUTING.md) to add new presets
+- View [CHANGELOG.md](CHANGELOG.md) for version history
+
+## Need Help?
+
+- 📖 [Full Documentation](README.md)
+- 🐛 [Report Issues](https://github.com/yourusername/project-structure-lint/issues)
+- 💬 [Discussions](https://github.com/yourusername/project-structure-lint/discussions)