@aiready/core 0.1.0 → 0.1.2

package/CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contributing to @aiready/core
+
+Thank you for your interest in contributing to AIReady Core! We welcome bug reports, feature requests, and code contributions.
+
+## 🐛 Reporting Issues
+
+Found a bug or have a feature request? [Open an issue](https://github.com/caopengau/aiready-core/issues) with:
+- Clear description of the problem or feature
+- Steps to reproduce (for bugs)
+- Expected vs actual behavior
+- Your environment (Node version, OS)
+
+## 🔧 Development Setup
+
+```bash
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/aiready-core
+cd aiready-core
+
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Run tests
+pnpm test
+
+# Run linter
+pnpm lint
+```
+
+## 📝 Making Changes
+
+1. **Fork the repository** and create a new branch:
+   ```bash
+   git checkout -b fix/your-bug-fix
+   # or
+   git checkout -b feat/your-new-feature
+   ```
+
+2. **Make your changes** following our code style:
+   - Use TypeScript strict mode
+   - Add JSDoc comments for public APIs
+   - Write tests for new functionality
+   - Keep functions pure and focused
+
+3. **Test your changes**:
+   ```bash
+   pnpm build
+   pnpm test
+   pnpm lint
+   ```
+
+4. **Commit using conventional commits**:
+   ```bash
+   git commit -m "fix: resolve token estimation edge case"
+   git commit -m "feat: add new similarity algorithm"
+   ```
+
+5. **Push and open a PR**:
+   ```bash
+   git push origin fix/your-bug-fix
+   ```
+
+## 📋 Commit Convention
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` - New feature
+- `fix:` - Bug fix
+- `docs:` - Documentation changes
+- `chore:` - Maintenance tasks
+- `refactor:` - Code refactoring
+- `test:` - Test updates
+
+## 🧪 Testing Guidelines
+
+- Add tests for new functions in `src/__tests__/`
+- Ensure all tests pass: `pnpm test`
+- Aim for >80% code coverage
+
+## 📚 Documentation
+
+- Update README.md if adding new public APIs
+- Add JSDoc comments for exported functions
+- Include usage examples for new features
+
+## 🔍 Code Review
+
+- Automated checks must pass (build, tests, lint)
+- Maintainers will review within 2 business days
+- Address feedback and update your PR
+- Once approved, we'll merge and publish
+
+## 🎯 What to Contribute
+
+Good first contributions:
+- Fix typos in documentation
+- Add missing tests
+- Improve error messages
+- Optimize existing utilities
+
+## ❓ Questions?
+
+Open an issue or reach out to the maintainers. We're here to help!
+
+---
+
+**Thank you for contributing!** 💙

package/README.md

@@ -0,0 +1,131 @@
+# @aiready/core
+
+> **Shared utilities and types for AIReady analysis tools**
+
+This package provides common utilities, type definitions, and helper functions used across all AIReady tools. It's designed as a foundational library for building code analysis tools focused on AI-readiness.
+
+## 📦 Installation
+
+```bash
+npm install @aiready/core
+# or
+pnpm add @aiready/core
+```
+
+## 🔧 Usage
+
+### File Scanning
+
+```typescript
+import { scanFiles } from '@aiready/core';
+
+const files = await scanFiles({
+  rootDir: './src',
+  include: ['**/*.ts', '**/*.tsx'],
+  exclude: ['**/*.test.ts', '**/node_modules/**'],
+  maxDepth: 10,
+});
+
+console.log(`Found ${files.length} files`);
+```
+
+### Token Estimation
+
+```typescript
+import { estimateTokens } from '@aiready/core';
+
+const code = `
+function hello() {
+  return "world";
+}
+`;
+
+const tokenCount = estimateTokens(code);
+console.log(`Estimated tokens: ${tokenCount}`);
+```
+
+### Similarity Detection
+
+```typescript
+import { similarityScore, levenshteinDistance } from '@aiready/core';
+
+const code1 = 'function handleUser(user) { ... }';
+const code2 = 'function handlePost(post) { ... }';
+
+const similarity = similarityScore(code1, code2);
+console.log(`Similarity: ${(similarity * 100).toFixed(1)}%`);
+
+const distance = levenshteinDistance(code1, code2);
+console.log(`Edit distance: ${distance}`);
+```
+
+### TypeScript Types
+
+```typescript
+import type {
+  AnalysisResult,
+  Issue,
+  IssueType,
+  Location,
+  Metrics,
+  ScanOptions,
+  Report,
+} from '@aiready/core';
+
+const result: AnalysisResult = {
+  fileName: 'src/utils/helper.ts',
+  issues: [
+    {
+      type: 'duplicate-pattern',
+      severity: 'major',
+      message: 'Similar pattern found',
+      location: {
+        file: 'src/utils/helper.ts',
+        line: 15,
+        column: 5,
+      },
+      suggestion: 'Extract to shared utility',
+    },
+  ],
+  metrics: {
+    tokenCost: 250,
+    consistencyScore: 0.85,
+  },
+};
+```
+
+## 📚 API Reference
+
+### File Operations
+
+- **`scanFiles(options: ScanOptions): Promise<string[]>`** - Scan directory for files matching patterns
+- **`readFileContent(filePath: string): Promise<string>`** - Read file contents
+
+### Metrics
+
+- **`estimateTokens(text: string): number`** - Estimate token count (~4 chars = 1 token)
+- **`levenshteinDistance(str1: string, str2: string): number`** - Calculate edit distance
+- **`similarityScore(str1: string, str2: string): number`** - Calculate similarity (0-1)
+
+### AST Parsing
+
+- **`parseTypeScript(code: string): SourceFile`** - Parse TypeScript/JavaScript code to AST
+- **`extractFunctions(ast: SourceFile): FunctionNode[]`** - Extract function declarations
+
+### Types
+
+All shared TypeScript interfaces and types for analysis results, issues, metrics, and configuration options.
+
+## 🔗 Related Packages
+
+- **[@aiready/pattern-detect](https://www.npmjs.com/package/@aiready/pattern-detect)** - Semantic duplicate pattern detection
+- **@aiready/context-analyzer** - Token cost and context fragmentation analysis _(coming soon)_
+- **@aiready/doc-drift** - Documentation freshness tracking _(coming soon)_
+
+## 📝 License
+
+MIT - See [LICENSE](./LICENSE)
+
+---
+
+**Part of the [AIReady](https://github.com/aiready) toolkit** | [Documentation](https://aiready.dev) | [GitHub](https://github.com/caopengau/aiready-core)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Shared utilities for AIReady analysis tools",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -27,6 +27,12 @@
   "bugs": {
     "url": "https://github.com/caopengau/aiready-core/issues"
   },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CONTRIBUTING.md"
+  ],
   "devDependencies": {
     "tsup": "^8.3.5",
     "eslint": "^9.17.0"

package/.turbo/turbo-build.log

@@ -1,61 +0,0 @@
-
-
-> @aiready/core@0.1.0 build /Users/pengcao/projects/aiready/packages/core
-> tsup src/index.ts --format cjs,esm --dts
-
-CLI Building entry: src/index.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Target: es2020
-CJS Build start
-ESM Build start
-DTS Build start
-
-[12:59:20 AM]  WARN  ▲ [WARNING] The condition "types" here will never be used as it comes after both "import" and "require" [package.json]
-
-    package.json:12:6:
-      12 │       "types": "./dist/index.d.ts"
-         ╵       ~~~~~~~
-
-  The "import" condition comes earlier and will be used for all "import" statements:
-
-    package.json:11:6:
-      11 │       "import": "./dist/index.mjs",
-         ╵       ~~~~~~~~
-
-  The "require" condition comes earlier and will be used for all "require" calls:
-
-    package.json:10:6:
-      10 │       "require": "./dist/index.js",
-         ╵       ~~~~~~~~~
-
-
-
-
-[12:59:20 AM]  WARN  ▲ [WARNING] The condition "types" here will never be used as it comes after both "import" and "require" [package.json]
-
-    package.json:12:6:
-      12 │       "types": "./dist/index.d.ts"
-         ╵       ~~~~~~~
-
-  The "import" condition comes earlier and will be used for all "import" statements:
-
-    package.json:11:6:
-      11 │       "import": "./dist/index.mjs",
-         ╵       ~~~~~~~~
-
-  The "require" condition comes earlier and will be used for all "require" calls:
-
-    package.json:10:6:
-      10 │       "require": "./dist/index.js",
-         ╵       ~~~~~~~~~
-
-
-
-ESM dist/index.mjs 2.02 KB
-ESM ⚡️ Build success in 273ms
-CJS dist/index.js 3.42 KB
-CJS ⚡️ Build success in 274ms
-DTS ⚡️ Build success in 435ms
-DTS dist/index.d.ts  2.48 KB
-DTS dist/index.d.mts 2.48 KB

package/.turbo/turbo-test.log

@@ -1,13 +0,0 @@
-
-
-> @aiready/core@0.1.0 test /Users/pengcao/projects/aiready/packages/core
-> vitest run
-
-
- RUN  v2.1.9 /Users/pengcao/projects/aiready/packages/core
-
-include: **/*.{test,spec}.?(c|m)[jt]s?(x)
-exclude:  **/node_modules/**, **/dist/**, **/cypress/**, **/.{idea,git,cache,output,temp}/**, **/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build,eslint,prettier}.config.*
-
-No test files found, exiting with code 1
-[?25h ELIFECYCLE  Test failed. See above for more details.

package/src/index.ts

@@ -1,4 +0,0 @@
-export * from './types';
-export * from './utils/file-scanner';
-export * from './utils/ast-parser';
-export * from './utils/metrics';

package/src/types.ts

@@ -1,59 +0,0 @@
-export interface AnalysisResult {
-  fileName: string;
-  issues: Issue[];
-  metrics: Metrics;
-}
-
-export interface Issue {
-  type: IssueType;
-  severity: 'critical' | 'major' | 'minor' | 'info';
-  message: string;
-  location: Location;
-  suggestion?: string;
-}
-
-export type IssueType =
-  | 'duplicate-pattern'
-  | 'context-fragmentation'
-  | 'doc-drift'
-  | 'naming-inconsistency'
-  | 'dead-code'
-  | 'circular-dependency'
-  | 'missing-types';
-
-export interface Location {
-  file: string;
-  line: number;
-  column?: number;
-  endLine?: number;
-  endColumn?: number;
-}
-
-export interface Metrics {
-  tokenCost?: number;
-  complexityScore?: number;
-  consistencyScore?: number;
-  docFreshnessScore?: number;
-}
-
-export interface ScanOptions {
-  rootDir: string;
-  include?: string[];
-  exclude?: string[];
-  maxDepth?: number;
-}
-
-export interface Report {
-  summary: {
-    totalFiles: number;
-    totalIssues: number;
-    criticalIssues: number;
-    majorIssues: number;
-  };
-  results: AnalysisResult[];
-  metrics: {
-    overallScore: number;
-    tokenCostTotal: number;
-    avgConsistency: number;
-  };
-}

package/src/utils/ast-parser.ts

@@ -1,28 +0,0 @@
-// Placeholder for AST parsing utilities
-// Will be implemented with specific parsers (TypeScript, Babel, etc.)
-
-export interface ASTNode {
-  type: string;
-  loc?: {
-    start: { line: number; column: number };
-    end: { line: number; column: number };
-  };
-}
-
-export function parseCode(code: string, language: string): ASTNode | null {
-  // TODO: Implement language-specific parsing
-  // TypeScript: @typescript-eslint/parser
-  // JavaScript: @babel/parser
-  // Python: tree-sitter-python
-  return null;
-}
-
-export function extractFunctions(ast: ASTNode): ASTNode[] {
-  // TODO: Extract function declarations
-  return [];
-}
-
-export function extractImports(ast: ASTNode): string[] {
-  // TODO: Extract import statements
-  return [];
-}

package/src/utils/file-scanner.ts

@@ -1,42 +0,0 @@
-import { glob } from 'glob';
-import { readFile } from 'fs/promises';
-import { ScanOptions } from '../types';
-
-const DEFAULT_EXCLUDE = [
-  '**/node_modules/**',
-  '**/dist/**',
-  '**/build/**',
-  '**/.git/**',
-  '**/coverage/**',
-  '**/*.min.js',
-  '**/*.bundle.js',
-];
-
-export async function scanFiles(options: ScanOptions): Promise<string[]> {
-  const {
-    rootDir,
-    include = ['**/*.{ts,tsx,js,jsx,py,java}'],
-    exclude = DEFAULT_EXCLUDE,
-  } = options;
-
-  const files = await glob(include, {
-    cwd: rootDir,
-    ignore: exclude,
-    absolute: true,
-  });
-
-  return files;
-}
-
-export async function readFileContent(filePath: string): Promise<string> {
-  return readFile(filePath, 'utf-8');
-}
-
-export function getFileExtension(filePath: string): string {
-  return filePath.split('.').pop() || '';
-}
-
-export function isSourceFile(filePath: string): boolean {
-  const ext = getFileExtension(filePath);
-  return ['ts', 'tsx', 'js', 'jsx', 'py', 'java', 'go', 'rs'].includes(ext);
-}

package/src/utils/metrics.ts

@@ -1,47 +0,0 @@
-/**
- * Estimate token count for text (rough approximation)
- * ~1 token ≈ 4 characters for code
- */
-export function estimateTokens(text: string): number {
-  return Math.ceil(text.length / 4);
-}
-
-/**
- * Calculate Levenshtein distance between two strings
- * Useful for similarity detection
- */
-export function levenshteinDistance(str1: string, str2: string): number {
-  const len1 = str1.length;
-  const len2 = str2.length;
-  const matrix: number[][] = [];
-
-  for (let i = 0; i <= len1; i++) {
-    matrix[i] = [i];
-  }
-
-  for (let j = 0; j <= len2; j++) {
-    matrix[0][j] = j;
-  }
-
-  for (let i = 1; i <= len1; i++) {
-    for (let j = 1; j <= len2; j++) {
-      const cost = str1[i - 1] === str2[j - 1] ? 0 : 1;
-      matrix[i][j] = Math.min(
-        matrix[i - 1][j] + 1,
-        matrix[i][j - 1] + 1,
-        matrix[i - 1][j - 1] + cost
-      );
-    }
-  }
-
-  return matrix[len1][len2];
-}
-
-/**
- * Calculate similarity score (0-1) between two strings
- */
-export function similarityScore(str1: string, str2: string): number {
-  const distance = levenshteinDistance(str1, str2);
-  const maxLength = Math.max(str1.length, str2.length);
-  return maxLength === 0 ? 1 : 1 - distance / maxLength;
-}

package/tsconfig.json

@@ -1,20 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-    "lib": ["ES2020"],
-    "moduleResolution": "bundler",
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}