@lsst/pik-core

Core library for pik - provides parsing, switching, config loading, and plugin types.

Installation

npm install @lsst/pik-core

Parsing and Switching

Parse and switch @pik config markers in source files:

import { Parser, SingleSwitcher } from '@lsst/pik-core';

const content = `
// @pik:select Environment
// const env = 'DEV';    // @pik:option DEV
const env = 'LOCAL';     // @pik:option LOCAL
`;

// Parse content
const parser = Parser.forExtension('ts');
const { selectors } = parser.parse(content);

// Switch option
const switcher = SingleSwitcher.forExtension('ts');
const newContent = switcher.switch(content, selectors[0], 'DEV');

Config Loading

Load pik configuration from project files:

import { loadConfig, defineConfig } from '@lsst/pik-core';

// Load config (looks for pik.config.ts, .pik.config.ts, etc.)
const config = await loadConfig();

// Type-safe config definition
export default defineConfig({
  select: { include: ['src/**/*.ts'] },
  worktree: { baseDir: '../' },
});

Creating Plugins

Create custom plugins using the PikPlugin interface:

import type { Command } from 'commander';
import type { PikPlugin } from '@lsst/pik-core';

interface MyPluginConfig {
  apiKey: string;
}

export function myPlugin(config: MyPluginConfig): PikPlugin {
  return {
    name: 'My Plugin',
    description: 'Does something cool',
    command: 'my',
    aliases: ['m'],

    register(program: Command) {
      program
        .command('my')
        .alias('m')
        .description('My custom command')
        .action(() => {
          console.log(`Using: ${config.apiKey}`);
        });
    },
  };
}

API

Parser

// Create parser for file extension
const parser = Parser.forExtension('ts');

// Parse content
const result = parser.parse(content);
// result.selectors: Selector[]
// result.content: string

SingleSwitcher

// Create switcher for file extension
const switcher = SingleSwitcher.forExtension('ts');

// Switch to option (deactivates all others)
const newContent = switcher.switch(content, selector, 'optionName');

CommentStyle

import { CommentStyle } from '@lsst/pik-core';

// Get comment style for extension
const style = CommentStyle.fromExtension('py'); // { lineComment: '#' }

// Register custom style
CommentStyle.register('custom', new CommentStyle(';;'));

isValidPlugin

import { isValidPlugin } from '@lsst/pik-core';

// Validate a plugin object
if (isValidPlugin(obj)) {
  // obj is PikPlugin
}

Types

interface Selector {
  name: string;
  line: number;
  options: Option[];
}

interface Option {
  name: string;
  line: number;
  content: string;
  isActive: boolean;
}

interface PikPlugin {
  name: string;
  description: string;
  command: string;
  aliases?: string[];
  register: (program: Command) => void;
}

interface PikConfig {
  plugins?: PikPlugin[];
  [pluginName: string]: unknown;
}

License

MIT