{"_id":"@aramassa/skel-extractor","name":"@aramassa/skel-extractor","dist-tags":{"latest":"0.0.5"},"versions":{"0.0.5":{"name":"@aramassa/skel-extractor","version":"0.0.5","description":"Utility to generate skeleton files from TypeScript sources and tests","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./testing":{"types":"./dist/testing.d.ts","import":"./dist/testing.js"}},"scripts":{"test":"vitest run --environment node","build":"tsc -p tsconfig.build.json","build:clean":"rm -rf dist && npm run build","clean":"rm -rf dist","prepublishOnly":"npm run build:clean && npm test"},"bin":{"skel-extractor":"dist/cli.js"},"type":"module","engines":{"node":">=18.0.0"},"dependencies":{"@types/node":"^24.0.14","@types/yargs":"^17.0.33","glob":"^11.0.3","markdown-it":"^14.1.0","p-limit":"^6.2.0","prettier":"^3.5.3","ts-node":"^10.9.2","typescript":"^5.8.3","yargs":"^18.0.0"},"devDependencies":{"@types/markdown-it":"^14.1.1","vitest":"^3.1.3"},"_id":"@aramassa/skel-extractor@0.0.5","gitHead":"208598461096fd8b38eed5651b5edcaa37ac1a08","_nodeVersion":"20.19.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-qsnNGBigGf5JeU7B2FhoYTItNPvZv7Lg8mXqudld7Kn3kmE+P/RVbT9wnKz7uHfV4gP5GmUJgy/RDIpAbwUPqg==","shasum":"fafa25157df26909de19ff408e840e45b38706be","tarball":"https://registry.npmjs.org/@aramassa/skel-extractor/-/skel-extractor-0.0.5.tgz","fileCount":78,"unpackedSize":277367,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCZyVZXMZ4oyGOBy1l2mdm6IBWGrilRR4YX3jdoizE3EAIhAJnO1rYIKzmEWEmFpsxFUMuf4pnin63cFRdDf/zWShPo"}]},"_npmUser":{"name":"aramassa","email":"mobi.ysk.zusa@gmail.com"},"directories":{},"maintainers":[{"name":"aramassa","email":"mobi.ysk.zusa@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/skel-extractor_0.0.5_1761297607021_0.32054333288080206"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-24T09:20:06.948Z","0.0.5":"2025-10-24T09:20:07.233Z","modified":"2025-10-24T09:20:07.472Z"},"maintainers":[{"name":"aramassa","email":"mobi.ysk.zusa@gmail.com"}],"description":"Utility to generate skeleton files from TypeScript sources and tests","readme":"# @aramassa/skel-extractor\n\nUtility CLI to generate skeleton files from TypeScript source, test files and Markdown documents, and compare skeleton files with implementations to show structural differences.\n\n## Features\n\n- **Skeleton Generation**: Parses TypeScript AST to extract class and function structures, outputs skeleton files used for structural validation\n- **Markdown Support**: Extracts heading structure and HTML comments from Markdown documents\n- **Diff Functionality**: Compare skeleton files with implementation files to identify structural differences\n- **Comprehensive Structure Analysis**: Detects classes, methods, properties, functions, interfaces, types, and more\n- **CLI and API Support**: Use from command line or programmatically in your code\n\n## Installation\n\n### From npm (recommended)\n\nThe easiest way to install is from the npm registry:\n\n```bash\nnpm install @aramassa/skel-extractor\n```\n\n### From GitHub Packages\n\nIf you prefer to install from GitHub Packages, you'll need to configure npm first:\n\n```bash\n# Configure npm to use GitHub Packages for @aramassa scope\necho \"@aramassa:registry=https://npm.pkg.github.com\" >> .npmrc\n\n# Authenticate with GitHub (requires personal access token with read:packages scope)\nnpm login --scope=@aramassa --registry=https://npm.pkg.github.com\n\n# Install the package\nnpm install @aramassa/skel-extractor\n```\n\nFor more details on GitHub Packages authentication, see [GitHub's documentation](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry).\n\n## Usage\n\n### Skeleton Generation\n\nGenerate skeleton files from TypeScript and Markdown sources:\n\n```bash\nskel-extractor extract src/**/*.ts --output skel\nskel-extractor extract docs/**/*.md --output skel\n\n# Process with limited concurrency for large codebases\nskel-extractor extract src/**/*.ts --output skel --concurrency 5\n```\n\nMarkdown documents produce skeletons with the same `.md` extension, containing their heading structure and HTML comments.\n\n### Diff Comparison\n\nCompare skeleton files with implementation files to show structural differences:\n\n```bash\n# Compare specific directories\nskel-extractor diff ./skel ./src\n\n# Use with additional options\nskel-extractor diff ./skel ./src --pattern \"**/*.ts\" --pattern \"**/*.md\"\nskel-extractor diff ./skel ./src --verbose --debug\n```\n\nThe diff output shows:\n- `+` **Added elements**: Present in implementation but missing from skeleton\n- `-` **Removed elements**: Present in skeleton but missing from implementation  \n- `~` **Modified elements**: Present in both but with different signatures\n\nExample diff output:\n```\n=== File: src/sample.ts ===\n+ [Method] newMethod() (in Sample) - added in implementation\n- [Method] oldMethod() (in Sample) - removed from skel\n~ [Method] modifiedMethod() (in Sample) - modified in implementation\n```\n\n### CLI Options\n\n**Extract Command (`skel-extractor extract <glob...>`):**\n- `<glob...>`: File patterns to process (required)\n- `--output <dir>`: Output directory for skeleton files (default: `./skel`)\n- `--force`: Overwrite existing skeleton files\n- `--concurrency <number>`: Maximum number of files to process concurrently (default: `10`)\n\n**Diff Command (`skel-extractor diff <skel-dir> <impl-dir>`):**\n- `<skel-dir>`: Directory containing skeleton files (required)\n- `<impl-dir>`: Directory containing implementation files (required)\n- `--pattern <glob>`: File patterns to compare (can be used multiple times, default: `**/*.ts`, `**/*.md`)\n- `--verbose`: Enable verbose output for detailed logging\n- `--debug`: Keep temporary directories for debugging\n\n**General:**\n- `--help`: Show help information\n- `extract --help`: Show help for extract command\n- `diff --help`: Show help for diff command\n\n## Programmatic API\n\n### Skeleton Generation\n\n```typescript\nimport { SkelExtractor } from '@aramassa/skel-extractor';\n\nconst extractor = new SkelExtractor({\n  outputDir: './skel',\n  overwrite: true,\n  concurrency: 5  // Limit concurrent file processing\n});\n\nawait extractor.generate(['src/**/*.ts', 'docs/**/*.md']);\n```\n\n**Concurrency Control:**\n\nBy default, the tool processes up to 10 files concurrently. For large codebases, you may want to reduce this to prevent memory issues:\n\n```typescript\n// For processing thousands of files, reduce concurrency\nconst extractor = new SkelExtractor({\n  outputDir: './skel',\n  concurrency: 3\n});\n\n// For small projects, you can increase concurrency\nconst fastExtractor = new SkelExtractor({\n  outputDir: './skel',\n  concurrency: 20\n});\n```\n\n### Structure Extraction\n\n```typescript\nimport { TypeScriptSkelExtractor, MarkdownSkelExtractor } from '@aramassa/skel-extractor';\n\n// Extract TypeScript structure\nconst tsExtractor = new TypeScriptSkelExtractor();\nconst tsElements = await tsExtractor.extractStructure('./src/sample.ts');\n\n// Extract Markdown structure  \nconst mdExtractor = new MarkdownSkelExtractor();\nconst mdElements = await mdExtractor.extractStructure('./docs/README.md');\n```\n\n### Directory Diff\n\n```typescript\nimport { DirectoryDiffer } from '@aramassa/skel-extractor';\n\nconst differ = new DirectoryDiffer();\nconst result = await differ.compareDirectories({\n  skelDir: './skel',\n  implDir: './src',\n  patterns: ['**/*.ts', '**/*.md']\n});\n\nconsole.log(differ.formatDirectoryDiff(result));\n```\n\n### Testing Helpers\n\nFor easier skeleton structure validation in tests, use the simplified testing API:\n\n```typescript\nimport { validateTestStructure } from '@aramassa/skel-extractor/testing';\n\ndescribe('Test Structure Validation', () => {\n  it('should match skeleton structure', async () => {\n    await validateTestStructure({\n      skelDir: 'skel/test',\n      testDir: 'test'\n    });\n  });\n});\n```\n\n**Simplified API Benefits:**\n- **One-line validation**: Replaces complex DirectoryDiffer setup\n- **Automatic path resolution**: Resolves relative paths from project root\n- **Clear error messages**: Shows detailed diff output when validation fails\n- **Test framework integration**: Works seamlessly with vitest, jest, etc.\n\n**Available functions:**\n- `validateTestStructure(options)`: Throws error if differences found\n- `expectTestStructureToMatch(options)`: Assertion-style helper for test frameworks\n- `TestStructureValidationError`: Custom error class with diff output\n\n**Options:**\n```typescript\ninterface ValidateTestStructureOptions {\n  skelDir: string;        // e.g., \"skel/test\"\n  testDir: string;        // e.g., \"test\"\n  patterns?: string[];    // defaults to [\"**/*.test.ts\"]\n  baseDir?: string;       // defaults to process.cwd()\n}\n```\n\n**Before (complex usage):**\n```typescript\nconst repoRoot = path.resolve(__dirname, \"..\");\nconst skelTestDir = path.join(repoRoot, \"skel/test\");\nconst testDir = path.join(repoRoot, \"test\");\n\nconst differ = new DirectoryDiffer();\nconst result = await differ.compareDirectories({\n  skelDir: skelTestDir,\n  implDir: testDir,\n  patterns: [\"**/*.test.ts\"]\n});\nconst diffText = differ.formatDirectoryDiff(result);\nexpect(diffText.trim() === \"\" || diffText.trim() === \"No differences found.\").toBe(true);\n```\n\n**After (simplified usage):**\n```typescript\nawait validateTestStructure({\n  skelDir: \"skel/test\",\n  testDir: \"test\"\n});\n```\n\n### Structure Diff\n\n```typescript\nimport { StructureDiffer } from '@aramassa/skel-extractor';\n\nconst differ = new StructureDiffer();\nconst diffs = differ.compare(skelElements, implElements);\nconst formatted = differ.formatDiff(diffs);\n```\n\n## Structure Elements\n\nThe tool recognizes these structural elements:\n\n**TypeScript:**\n- Classes with methods, constructors, properties, getters/setters\n- Functions and arrow functions\n- Interfaces and type aliases\n- Variables and constants\n- Export declarations\n- Test structures (describe, it, beforeEach, afterEach)\n\n**Markdown:**\n- Headers (H1-H6)\n- HTML comments\n\n## Use Cases\n\n- **Design Validation**: Ensure implementations match their intended structure\n- **Code Review**: Quickly identify structural changes between versions\n- **Documentation**: Generate structural overviews of codebases\n- **Testing**: Validate that test files cover expected functionality\n- **Architecture**: Monitor structural evolution of projects\n\n## Publishing\n\nThis package is published to both npm registry and GitHub Packages.\n\n### Publishing a Stable Release\n\n1. Go to **Actions** > **\"Publish @aramassa/skel-extractor package (Dual Registry)\"**\n2. Click **\"Run workflow\"**\n3. Select:\n   - **Release type**: `stable`\n   - **Target registry**: Choose based on your needs:\n     - `both` - Publish to both npm and GitHub Packages (recommended for stable releases)\n     - `npm` - Publish to npm registry only\n     - `github` - Publish to GitHub Packages only\n\n### Publishing Pre-releases\n\nPre-release versions (`pre-build`, `pre-distribution`) are **always published to GitHub Packages only**, regardless of the registry selection:\n\n1. Go to **Actions** > **\"Publish @aramassa/skel-extractor package (Dual Registry)\"**\n2. Click **\"Run workflow\"**\n3. Select:\n   - **Release type**: `pre-build` or `pre-distribution`\n   - **Target registry**: (ignored for pre-releases)\n\n### Registry Setup\n\n**For npm registry**: Ensure `NPM_TOKEN` is configured in repository secrets with publish permissions.\n\n**For GitHub Packages**: Uses `GITHUB_TOKEN` automatically (no additional setup needed).\n\n### Version Management\n\n- Stable releases use the version from `package.json`\n- Pre-releases append a timestamp: `<version>-<release_type>.<timestamp>`\n  - Example: `0.0.5-pre-build.20251024123456`\n","readmeFilename":"README.md","_rev":"1-dce0048a814e95eb3c4ca26a065ef3ba"}