@aramassa/skel-extractor

Utility CLI to generate skeleton files from TypeScript source, test files and Markdown documents, and compare skeleton files with implementations to show structural differences.

Features

• Skeleton Generation: Parses TypeScript AST to extract class and function structures, outputs skeleton files used for structural validation
• Markdown Support: Extracts heading structure and HTML comments from Markdown documents
• Diff Functionality: Compare skeleton files with implementation files to identify structural differences
• Comprehensive Structure Analysis: Detects classes, methods, properties, functions, interfaces, types, and more
• CLI and API Support: Use from command line or programmatically in your code

Installation

From npm (recommended)

The easiest way to install is from the npm registry:

npm install @aramassa/skel-extractor

From GitHub Packages

If you prefer to install from GitHub Packages, you'll need to configure npm first:

# Configure npm to use GitHub Packages for @aramassa scope
echo "@aramassa:registry=https://npm.pkg.github.com" >> .npmrc

# Authenticate with GitHub (requires personal access token with read:packages scope)
npm login --scope=@aramassa --registry=https://npm.pkg.github.com

# Install the package
npm install @aramassa/skel-extractor

For more details on GitHub Packages authentication, see GitHub's documentation.

Usage

Skeleton Generation

Generate skeleton files from TypeScript and Markdown sources:

skel-extractor extract src/**/*.ts --output skel
skel-extractor extract docs/**/*.md --output skel

# Process with limited concurrency for large codebases
skel-extractor extract src/**/*.ts --output skel --concurrency 5

Markdown documents produce skeletons with the same .md extension, containing their heading structure and HTML comments.

Diff Comparison

Compare skeleton files with implementation files to show structural differences:

# Compare specific directories
skel-extractor diff ./skel ./src

# Use with additional options
skel-extractor diff ./skel ./src --pattern "**/*.ts" --pattern "**/*.md"
skel-extractor diff ./skel ./src --verbose --debug

The diff output shows:

• + Added elements: Present in implementation but missing from skeleton
• - Removed elements: Present in skeleton but missing from implementation
• ~ Modified elements: Present in both but with different signatures

Example diff output:

=== File: src/sample.ts ===
+ [Method] newMethod() (in Sample) - added in implementation
- [Method] oldMethod() (in Sample) - removed from skel
~ [Method] modifiedMethod() (in Sample) - modified in implementation

CLI Options

Extract Command (skel-extractor extract <glob...>):

• <glob...>: File patterns to process (required)
• --output <dir>: Output directory for skeleton files (default: ./skel)
• --force: Overwrite existing skeleton files
• --concurrency <number>: Maximum number of files to process concurrently (default: 10)

Diff Command (skel-extractor diff <skel-dir> <impl-dir>):

• <skel-dir>: Directory containing skeleton files (required)
• <impl-dir>: Directory containing implementation files (required)
• --pattern <glob>: File patterns to compare (can be used multiple times, default: **/*.ts, **/*.md)
• --verbose: Enable verbose output for detailed logging
• --debug: Keep temporary directories for debugging

General:

• --help: Show help information
• extract --help: Show help for extract command
• diff --help: Show help for diff command

Programmatic API

Skeleton Generation

import { SkelExtractor } from '@aramassa/skel-extractor';

const extractor = new SkelExtractor({
  outputDir: './skel',
  overwrite: true,
  concurrency: 5  // Limit concurrent file processing
});

await extractor.generate(['src/**/*.ts', 'docs/**/*.md']);

Concurrency Control:

By default, the tool processes up to 10 files concurrently. For large codebases, you may want to reduce this to prevent memory issues:

// For processing thousands of files, reduce concurrency
const extractor = new SkelExtractor({
  outputDir: './skel',
  concurrency: 3
});

// For small projects, you can increase concurrency
const fastExtractor = new SkelExtractor({
  outputDir: './skel',
  concurrency: 20
});

Structure Extraction

import { TypeScriptSkelExtractor, MarkdownSkelExtractor } from '@aramassa/skel-extractor';

// Extract TypeScript structure
const tsExtractor = new TypeScriptSkelExtractor();
const tsElements = await tsExtractor.extractStructure('./src/sample.ts');

// Extract Markdown structure  
const mdExtractor = new MarkdownSkelExtractor();
const mdElements = await mdExtractor.extractStructure('./docs/README.md');

Directory Diff

import { DirectoryDiffer } from '@aramassa/skel-extractor';

const differ = new DirectoryDiffer();
const result = await differ.compareDirectories({
  skelDir: './skel',
  implDir: './src',
  patterns: ['**/*.ts', '**/*.md']
});

console.log(differ.formatDirectoryDiff(result));

Testing Helpers

For easier skeleton structure validation in tests, use the simplified testing API:

import { validateTestStructure } from '@aramassa/skel-extractor/testing';

describe('Test Structure Validation', () => {
  it('should match skeleton structure', async () => {
    await validateTestStructure({
      skelDir: 'skel/test',
      testDir: 'test'
    });
  });
});

Simplified API Benefits:

• One-line validation: Replaces complex DirectoryDiffer setup
• Automatic path resolution: Resolves relative paths from project root
• Clear error messages: Shows detailed diff output when validation fails
• Test framework integration: Works seamlessly with vitest, jest, etc.

Available functions:

• validateTestStructure(options): Throws error if differences found
• expectTestStructureToMatch(options): Assertion-style helper for test frameworks
• TestStructureValidationError: Custom error class with diff output

Options:

interface ValidateTestStructureOptions {
  skelDir: string;        // e.g., "skel/test"
  testDir: string;        // e.g., "test"
  patterns?: string[];    // defaults to ["**/*.test.ts"]
  baseDir?: string;       // defaults to process.cwd()
}

Before (complex usage):

const repoRoot = path.resolve(__dirname, "..");
const skelTestDir = path.join(repoRoot, "skel/test");
const testDir = path.join(repoRoot, "test");

const differ = new DirectoryDiffer();
const result = await differ.compareDirectories({
  skelDir: skelTestDir,
  implDir: testDir,
  patterns: ["**/*.test.ts"]
});
const diffText = differ.formatDirectoryDiff(result);
expect(diffText.trim() === "" || diffText.trim() === "No differences found.").toBe(true);

After (simplified usage):

await validateTestStructure({
  skelDir: "skel/test",
  testDir: "test"
});

Structure Diff

import { StructureDiffer } from '@aramassa/skel-extractor';

const differ = new StructureDiffer();
const diffs = differ.compare(skelElements, implElements);
const formatted = differ.formatDiff(diffs);

Structure Elements

The tool recognizes these structural elements:

TypeScript:

• Classes with methods, constructors, properties, getters/setters
• Functions and arrow functions
• Interfaces and type aliases
• Variables and constants
• Export declarations
• Test structures (describe, it, beforeEach, afterEach)

Markdown:

• Headers (H1-H6)
• HTML comments

Use Cases

• Design Validation: Ensure implementations match their intended structure
• Code Review: Quickly identify structural changes between versions
• Documentation: Generate structural overviews of codebases
• Testing: Validate that test files cover expected functionality
• Architecture: Monitor structural evolution of projects

Publishing

This package is published to both npm registry and GitHub Packages.

Publishing a Stable Release

1. Go to Actions > "Publish @aramassa/skel-extractor package (Dual Registry)"
2. Click "Run workflow"
3. Select:
   • Release type: stable
   • Target registry: Choose based on your needs:
     • both - Publish to both npm and GitHub Packages (recommended for stable releases)
     • npm - Publish to npm registry only
     • github - Publish to GitHub Packages only

Publishing Pre-releases

Pre-release versions (pre-build, pre-distribution) are always published to GitHub Packages only, regardless of the registry selection:

1. Go to Actions > "Publish @aramassa/skel-extractor package (Dual Registry)"
2. Click "Run workflow"
3. Select:
   • Release type: pre-build or pre-distribution
   • Target registry: (ignored for pre-releases)

Registry Setup

For npm registry: Ensure NPM_TOKEN is configured in repository secrets with publish permissions.

For GitHub Packages: Uses GITHUB_TOKEN automatically (no additional setup needed).

Version Management

• Stable releases use the version from package.json
• Pre-releases append a timestamp: <version>-<release_type>.<timestamp>
  • Example: 0.0.5-pre-build.20251024123456