@leanspec/core

Platform-agnostic spec parsing and validation library for LeanSpec.

Overview

@leanspec/core provides the core functionality for parsing and validating LeanSpec specifications without dependencies on Node.js file system operations. This enables the same parsing and validation logic to work across different platforms (CLI, web, etc.).

Installation

pnpm add @leanspec/core

Features

• Type Definitions: SpecInfo, SpecFrontmatter, SpecStatus, SpecPriority, etc.
• Frontmatter Parsing: Parse and validate YAML frontmatter from markdown content
• Validators: Frontmatter validation, structure validation, line count checks
• Utilities: Spec statistics, insights generation, filtering
• Storage Interface: Abstract SpecStorage interface for platform-specific I/O

Usage

Parsing Frontmatter

import { parseFrontmatterFromString } from '@leanspec/core';

const markdownContent = `---
status: in-progress
created: 2025-01-15
tags: [feature, api]
priority: high
---

# My Spec
...
`;

const frontmatter = parseFrontmatterFromString(markdownContent);
console.log(frontmatter);
// {
//   status: 'in-progress',
//   created: '2025-01-15',
//   tags: ['feature', 'api'],
//   priority: 'high'
// }

Updating Frontmatter

import { createUpdatedFrontmatter } from '@leanspec/core';

const existingContent = await storage.readFile('spec.md');
const { content, frontmatter } = createUpdatedFrontmatter(existingContent, {
  status: 'complete',
  completed: '2025-01-20'
});

await storage.writeFile('spec.md', content);

Validation

import { 
  FrontmatterValidator,
  StructureValidator,
  LineCountValidator 
} from '@leanspec/core';

const spec: SpecInfo = {
  path: '001-example',
  fullPath: '/path/to/specs/001-example',
  filePath: '/path/to/specs/001-example/README.md',
  name: '001-example',
  frontmatter: { status: 'planned', created: '2025-01-15' },
  content: '...'
};

// Validate frontmatter
const fmValidator = new FrontmatterValidator();
const fmResult = await fmValidator.validate(spec);

// Validate structure
const structValidator = new StructureValidator();
const structResult = await structValidator.validate(spec);

// Validate line count (Context Economy principle)
const lcValidator = new LineCountValidator({ maxLines: 400, warningThreshold: 300 });
const lcResult = await lcValidator.validate(spec);

Utilities

import { 
  countSpecsByStatusAndPriority,
  generateInsights,
  matchesFilter 
} from '@leanspec/core';

// Count specs by status and priority
const { statusCounts, priorityCounts, tagCounts } = countSpecsByStatusAndPriority(specs);

// Generate insights
const insights = generateInsights(specs);
console.log(insights); // Array of insight objects

// Filter specs
const inProgressSpecs = specs.filter(spec => 
  matchesFilter(spec.frontmatter, { status: 'in-progress' })
);

Storage Interface

The core package uses an abstract SpecStorage interface for platform independence:

export interface SpecStorage {
  readFile(path: string): Promise<string>;
  writeFile(path: string, content: string): Promise<void>;
  exists(path: string): Promise<boolean>;
  listFiles(dirPath: string): Promise<string[]>;
  listDirs(dirPath: string): Promise<string[]>;
  getFileStats?(path: string): Promise<{ size: number; modified: Date }>;
}

Implementations

FileSystemStorage (Node.js):

// In @leanspec/cli
import { FileSystemStorage } from './adapters/fs-storage.js';

const storage = new FileSystemStorage();
const content = await storage.readFile('/path/to/spec.md');

GitHubStorage (Web - future):

// In @leanspec/web
import { GitHubStorage } from '@leanspec/web/adapters';

const storage = new GitHubStorage(octokit, 'owner', 'repo');
const content = await storage.readFile('specs/001-example/README.md');

Type Definitions

SpecInfo

interface SpecInfo {
  path: string;           // Relative path
  fullPath: string;       // Absolute path to spec directory
  filePath: string;       // Absolute path to spec file
  name: string;           // Spec name (e.g., "001-example")
  date?: string;          // Optional date (for dated patterns)
  frontmatter: SpecFrontmatter;
  content?: string;       // Full file content (optional)
  subFiles?: SubFileInfo[]; // Sub-documents and assets
}

SpecFrontmatter

interface SpecFrontmatter {
  // Required
  status: SpecStatus;     // 'planned' | 'in-progress' | 'complete' | 'archived'
  created: string;        // YYYY-MM-DD

  // Recommended
  tags?: string[];
  priority?: SpecPriority; // 'low' | 'medium' | 'high' | 'critical'

  // Optional
  related?: string[];
  depends_on?: string[];
  assignee?: string;
  // ... and more
}

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

License

MIT - See LICENSE file in repository root