@shibanet0/datamitsu-config 0.0.1-alpha-29 → 0.0.1-alpha-30

package/datamitsu.js

@@ -1840,7 +1840,7 @@ var mapOfApps = {
 
 // package.json
 var name = "@shibanet0/datamitsu-config";
-var version = "0.0.1-alpha-29";
+var version = "0.0.1-alpha-30";
 var dependencies = {
   "@antebudimir/eslint-plugin-vanilla-extract": "1.16.0",
   "@commander-js/extra-typings": "14.0.0",

package/dist/datamitsu.d.ts

@@ -0,0 +1,692 @@
+// prettier-ignore
+declare global {
+  function getConfig(config: config.Config): config.Config;
+
+  namespace SysList {
+    type ArchType = "aarch64" | "amd64" | "arm64";
+
+    type OsType = "darwin" | "freebsd" | "linux" | "openbsd" | "windows";
+  }
+
+  /**
+   * Tools namespace with utility functions
+   */
+  namespace tools {
+    /**
+     * Path utilities for working with file paths
+     */
+    namespace Path {
+      /**
+       * Get absolute path from relative path
+       * @param path - Path to convert to absolute
+       * @returns Absolute path
+       * @throws Error if path cannot be resolved
+       * @example
+       * const absPath = tools.Path.abs("./file.txt");
+       * // Returns: "/current/working/directory/file.txt"
+       */
+      function abs(path: string): string;
+
+      /**
+       * Join path segments together using the OS-specific separator
+       * @param paths - Path segments to join
+       * @returns Joined path
+       * @example
+       * const fullPath = tools.Path.join("/home", "user", "file.txt");
+       * // Returns: "/home/user/file.txt" on Unix, "\\home\\user\\file.txt" on Windows
+       */
+      function join(...paths: string[]): string;
+
+      /**
+       * Get relative path from base to target
+       * @param targetPath - Target path
+       * @param basePath - Base path (defaults to current working directory from facts().cwd)
+       * @returns Relative path from base to target
+       * @throws Error if relative path cannot be computed
+       * @example
+       * // Relative to cwd
+       * const relPath = tools.Path.rel("/home/user/project/file.txt");
+       * // If cwd is "/home/user", returns: "project/file.txt"
+       *
+       * @example
+       * // Relative to custom base
+       * const relPath = tools.Path.rel("/home/user/project/file.txt", "/home");
+       * // Returns: "user/project/file.txt"
+       */
+      function rel(targetPath: string, basePath?: string): string;
+    }
+
+    /**
+     * .gitignore parser and stringifier
+     */
+    namespace Ignore {
+      type IgnoreMap<T extends string = string> = { [K in T]?: string[] };
+
+      interface ParseResult<T extends string = string> {
+        groupOrder: T[];
+        groups: IgnoreMap<T>;
+      }
+
+      /**
+       * Parse .gitignore file to grouped structure with preserved order
+       * @param content - .gitignore file content
+       * @returns Object with groups and their original order
+       * @example
+       * const { groups, groupOrder } = tools.Ignore.parse(fileContent);
+       * // groups: { "Dependencies": ["node_modules/"], "Build": ["dist/"] }
+       * // groupOrder: ["Dependencies", "Build"]
+       *
+       * // Use the original order when saving back
+       * const updated = tools.Ignore.stringify(groups, groupOrder);
+       */
+      function parse<T extends string = string>(content: string): ParseResult<T>;
+
+      /**
+       * Convert grouped structure back to .gitignore format
+       * @param groups - Object with group names as keys and rule arrays as values
+       * @param groupOrder - Optional partial array specifying the priority order of groups.
+       *                     Groups in this array will appear first in the specified order.
+       *                     Remaining groups will follow in alphabetical order.
+       * @returns Formatted .gitignore content
+       * @example
+       * // All groups in alphabetical order
+       * const content1 = tools.Ignore.stringify({
+       *   "Testing": ["coverage/"],
+       *   "Build": ["dist/"],
+       *   "Dependencies": ["node_modules/"]
+       * });
+       * // Result order: Build, Dependencies, Testing
+       *
+       * @example
+       * // Priority groups first, then alphabetical
+       * const content2 = tools.Ignore.stringify(
+       *   {
+       *     "Testing": ["coverage/"],
+       *     "Build": ["dist/"],
+       *     "Dependencies": ["node_modules/"],
+       *     "IDE": [".vscode/"]
+       *   },
+       *   ["Dependencies", "Build"]
+       * );
+       * // Result order: Dependencies, Build, IDE, Testing
+       *
+       * @example
+       * // Preserve original order
+       * const { groups, groupOrder } = tools.Ignore.parse(original);
+       * groups["New Group"] = ["new/rule"];
+       * const updated = tools.Ignore.stringify(groups, groupOrder);
+       */
+      function stringify<T extends string>(groups: IgnoreMap<T>, groupOrder?: T[]): string;
+    }
+  }
+
+  namespace config {
+    // ========================================
+    // Project Type Detection
+    // ========================================
+
+    interface Config {
+      /**
+       * Binary/app definitions
+       */
+      apps?: BinManager.MapOfApps;
+
+      /**
+       * Config file initialization
+       */
+      init?: MapOfConfigInit;
+
+      /**
+       * Init commands to run after setup
+       */
+      initCommands?: MapOfInitCommands;
+
+      /**
+       * Project type definitions
+       */
+      projectTypes?: MapOfProjectTypes;
+
+      /**
+       * Tool definitions
+       */
+      tools?: MapOfTools;
+    }
+
+    /**
+     * Context passed to config content generator
+     */
+    interface ConfigContext {
+      /**
+       * Current working directory
+       */
+      cwdPath: string;
+
+      /**
+       * Content of existing file (if it exists)
+       * This may be modified content from previous merge operations
+       */
+      existingContent?: string;
+
+      /**
+       * Path to existing file (if it exists)
+       */
+      existingPath?: string;
+
+      /**
+       * Whether the current working directory is the git root
+       */
+      isRoot: boolean;
+
+      /**
+       * Original content of the file as it exists on disk
+       * This is always the unmodified content, even when existingContent has been transformed
+       */
+      originalContent?: string;
+
+      /**
+       * Detected project types
+       */
+      projectTypes: string[];
+
+      /**
+       * Git root path
+       */
+      rootPath: string;
+    }
+
+    // ========================================
+    // Tool Execution Configuration
+    // ========================================
+
+    /**
+     * Configuration file initialization (enhanced from existing)
+     */
+    interface ConfigInit {
+      /**
+       * Function that generates file content
+       * Receives context about the project including existing file content if present
+       * Optional when deleteOnly is true
+       */
+      content?: (context: ConfigContext) => string;
+
+      /**
+       * If true, only delete files from otherFileNameList without creating any new file
+       * Content function is ignored when deleteOnly is true
+       * @default false
+       */
+      deleteOnly?: boolean;
+
+      /**
+       * All other known filenames for this config
+       * These will be DELETED during install to avoid conflicts
+       * @example [".eslintrc.js", ".eslintrc.json", ".eslintrc.yml", "eslint.config.js"]
+       */
+      otherFileNameList?: string[];
+
+      /**
+       * Which project type this config applies to
+       * If not specified, applies to all projects
+       */
+      projectTypes?: string[];
+
+      /**
+       * Only create in project root
+       * @default false
+       */
+      rootOnly?: boolean;
+    }
+
+    /**
+     * Initialization command to run after clone/install
+     */
+    interface InitCommand {
+      /**
+       * Arguments
+       */
+      args: string[];
+
+      /**
+       * Command to execute (app name from MapOfApps)
+       */
+      command: string;
+
+      /**
+       * Description
+       */
+      description?: string;
+
+      /**
+       * Which project types this applies to
+       * Empty = all project types
+       */
+      projectTypes?: string[];
+
+      /**
+       * Only run if this file/directory exists
+       */
+      when?: string;
+    }
+
+    /**
+     * Map of configuration init with mainFilename as key
+     * @example
+     * {
+     *   ".gitignore": { content: () => "..." },
+     *   "lefthook.yaml": { content: () => "..." },
+     *   ".vscode/settings.json": { content: () => "..." }
+     * }
+     */
+    type MapOfConfigInit = Record<string, ConfigInit>;
+
+    // ========================================
+    // Init Commands
+    // ========================================
+
+    type MapOfInitCommands = Record<string, InitCommand>;
+
+    type MapOfProjectTypes = Record<string, ProjectType>;
+
+    // ========================================
+    // Config File Management (ENHANCED)
+    // ========================================
+
+    type MapOfTools = Record<string, Tool>;
+
+    /**
+     * Operation type
+     */
+    type OperationType = "fix" | "lint";
+
+    /**
+     * Project type detector - defines when this project type is detected
+     */
+    interface ProjectType {
+      /**
+       * Human-readable description
+       */
+      description?: string;
+
+      /**
+       * Marker files that indicate this project type
+       * If ANY of these files exist in the root, project type is detected
+       * Supports glob patterns in repo root
+       * @example ["package.json", "yarn.lock"]
+       * @example ["go.mod"]
+       * @example ["*.tf"]
+       */
+      markers: string[];
+    }
+
+    // ========================================
+    // Git Hook Configuration
+    // ========================================
+
+    /**
+     * Tool definition - what operations a tool supports
+     */
+    interface Tool {
+      /**
+       * Tool name/description
+       */
+      name: string;
+
+      /**
+       * Operations this tool supports
+       */
+      operations: Partial<Record<OperationType, ToolOperation>>;
+
+      /**
+       * Which project types this tool applies to
+       * Empty array or undefined = applies to all project types
+       * @example ["npm-package", "typescript-project"]
+       */
+      projectTypes?: string[];
+    }
+
+    /**
+     * Tool operation configuration - how to run a tool for a specific operation
+     */
+    interface ToolOperation {
+      /**
+       * Arguments to pass to the command
+       * Special placeholders:
+       * - {file} - replaced with file path (per-file scope)
+       * - {files} - replaced with space-separated file list (batch mode)
+       * - {root} - replaced with project root path
+       * @example ["--fix", "{file}"]
+       * @example ["--noEmit", "--project", "{root}"]
+       */
+      args: string[];
+
+      /**
+       * Batch mode - обрабатывать файлы группами или по одному
+       * Используется только для scope: "per-project" или "repository"
+       * @default true для "per-project" и "repository", false для "per-file"
+       */
+      batch?: boolean;
+
+      /**
+       * Command to execute (app name from MapOfApps)
+       */
+      command: string;
+
+      /**
+       * File glob patterns this tool operates on
+       * Uses gitignore-style patterns
+       * @example ["**\/*.ts", "**\/*.tsx"]
+       * @example ["**\/*.md"]
+       */
+      globs: string[];
+
+      /**
+       * Files that should invalidate the cache when changed
+       * Paths are relative to project root
+       * @example ["eslint.config.js", "tsconfig.json"]
+       * @example [".prettierrc", "package.json"]
+       */
+      invalidateOn?: string[];
+
+      /**
+       * Priority/order when tools have overlapping globs
+       * Lower number = runs first
+       * Tools with same priority and overlapping globs run sequentially in definition order
+       * Tools with different globs or no overlap run in parallel
+       * @default 0
+       */
+      priority?: number;
+
+      /**
+       * Scope определяет область выполнения и working directory
+       * - "repository": запуск один раз из git root для всего репозитория
+       * - "per-project": запуск для каждого detected project в его директории
+       * - "per-file": запуск для каждого файла в его директории
+       * @default "per-project"
+       * @example
+       * // ESLint - запускается в каждом проекте
+       * {
+       *   scope: "per-project",
+       *   command: "eslint",
+       *   args: ["--quiet", "{files}"],
+       *   globs: ["**\/*.ts", "**\/*.js"]
+       * }
+       * @example
+       * // syncpack - запускается один раз для всего монорепо
+       * {
+       *   scope: "repository",
+       *   command: "syncpack",
+       *   args: ["lint"],
+       *   globs: ["**\/package.json"]
+       * }
+       * @example
+       * // shfmt - форматирует каждый shell файл отдельно
+       * {
+       *   scope: "per-file",
+       *   command: "shfmt",
+       *   args: ["-w", "{file}"],
+       *   globs: ["**\/*.sh"]
+       * }
+       */
+      scope: ToolScope;
+    }
+
+    /**
+     * Scope определяет область выполнения инструмента и автоматически определяет working directory
+     */
+    type ToolScope =
+      | "per-file" // Запуск для каждого файла в его директории
+      | "per-project" // Запуск для каждого detected project в его директории
+      | "repository"; // Запуск один раз из git root для всего репозитория
+
+    // ========================================
+    // Main Config (ENHANCED)
+    // ========================================
+  }
+
+  namespace BinManager {
+    interface App {
+      binary?: AppConfigBinary;
+      pnpm?: AppConfigPNPM;
+      required?: boolean;
+      shell?: AppConfigShell;
+      uvx?: AppConfigUVX;
+    }
+
+    interface AppConfigBinary {
+      binaries: MapOfBinaries;
+    }
+
+    interface AppConfigPNPM {
+      packageName: string;
+      version: string;
+    }
+
+    interface AppConfigShell {
+      args?: string[];
+      env?: Record<string, string>;
+      name: string;
+    }
+
+    interface AppConfigUVX {
+      packageName: string;
+      version: string;
+    }
+
+    interface BinaryOsArchInfo {
+      binaryPath?: string;
+      contentType: BinContentType;
+
+      hash: string;
+      /** @default sha256 */
+      hashType?: BinHashType;
+      url: string;
+    }
+
+    type BinContentType =
+      | "binary"
+      | "bz2"
+      | "gz"
+      | "tar"
+      | "tar.bz2"
+      | "tar.gz"
+      | "tar.xz"
+      | "tar.zst"
+      | "xz"
+      | "zip"
+      | "zst";
+
+    type BinHashType = "blake2b" | "md5" | "sha1" | "sha256" | "sha384" | "sha512";
+
+    type MapOfApps = Record<string, App>;
+
+    type MapOfBinaries = Partial<
+      Record<SysList.OsType, Partial<Record<SysList.ArchType, BinaryOsArchInfo>>>
+    >;
+  }
+
+  /**
+   * Facts about the project environment
+   * Collected automatically on engine initialization
+   */
+  interface Facts {
+    /**
+     * CPU architecture (amd64, arm64, aarch64)
+     */
+    arch: SysList.ArchType;
+
+    /**
+     * Command to run this binary (can be overridden via --binary-command flag or DATAMITSU_BINARY_COMMAND env var)
+     * Useful for npm package wrappers that need to call the actual binary
+     */
+    binaryCommand: string;
+
+    /**
+     * Absolute path to the currently running binary
+     */
+    binaryPath: string;
+
+    /**
+     * Current working directory where the tool was invoked
+     */
+    cwd: string;
+
+    /**
+     * Environment variables with the package prefix (e.g., CHANGE_ME_*)
+     * Only includes variables that start with the prefix defined in ldflags.EnvPrefix
+     * @example { "CHANGE_ME_DEBUG": "true", "CHANGE_ME_LOG_LEVEL": "info" }
+     */
+    env: Record<string, string>;
+
+    /**
+     * Root directory of the git repository (handles submodules)
+     * Empty string if not in a git repository
+     */
+    gitRoot: string;
+
+    /**
+     * Whether we're inside a git repository
+     */
+    isInGitRepo: boolean;
+
+    /**
+     * Whether we're in a subdirectory of git root (potential monorepo)
+     */
+    isMonorepo: boolean;
+
+    /**
+     * Operating system (darwin, linux, windows, freebsd, openbsd)
+     */
+    os: SysList.OsType;
+
+    /**
+     * Package name from ldflags
+     */
+    packageName: string;
+
+    /**
+     * Project root (same as gitRoot or cwd if not in git)
+     */
+    projectRoot: string;
+  }
+
+  /**
+   * Function that returns Facts object
+   * Facts are collected once during engine initialization
+   */
+  const facts: () => Facts;
+
+  /**
+   * YAML parser and stringifier
+   */
+  namespace YAML {
+    /**
+     * Parse YAML string to JavaScript object
+     * @param text - YAML string to parse
+     * @returns Parsed object
+     * @throws Error if YAML is invalid
+     */
+    function parse(text: string): any;
+
+    /**
+     * Convert JavaScript object to YAML string
+     * @param value - Object to stringify
+     * @returns YAML string
+     * @throws Error if object cannot be serialized
+     */
+    function stringify(value: any): string;
+  }
+
+  /**
+   * TOML parser and stringifier
+   */
+  namespace TOML {
+    /**
+     * Parse TOML string to JavaScript object
+     * @param text - TOML string to parse
+     * @returns Parsed object
+     * @throws Error if TOML is invalid
+     */
+    function parse(text: string): any;
+
+    /**
+     * Convert JavaScript object to TOML string
+     * @param value - Object to stringify
+     * @returns TOML string
+     * @throws Error if object cannot be serialized
+     */
+    function stringify(value: any): string;
+  }
+
+  /**
+   * INI parser and stringifier
+   */
+  namespace INI {
+    /**
+     * INI section structure
+     */
+    type Section = Record<string, string>;
+
+    /**
+     * INI section entry with name and properties
+     */
+    interface SectionEntry {
+      name: string;
+      properties: Section;
+    }
+
+    /**
+     * Parse INI string to array of sections
+     * @param text - INI string to parse
+     * @returns Array of sections (preserves order and allows duplicate section names)
+     * @throws Error if INI is invalid
+     * @example
+     * const ini = INI.parse(`
+     * [database]
+     * host = localhost
+     * port = 5432
+     * [*.py]
+     * indent_size = 4
+     * [*.py]
+     * indent_size = 2
+     * `);
+     * // Returns: [
+     * //   { name: "database", properties: { host: "localhost", port: "5432" } },
+     * //   { name: "*.py", properties: { indent_size: "4" } },
+     * //   { name: "*.py", properties: { indent_size: "2" } }
+     * // ]
+     */
+    function parse(text: string): Array<SectionEntry>;
+
+    /**
+     * Convert array of sections to INI string
+     * @param sections - Array of section entries
+     * @returns INI string
+     * @throws Error if object cannot be serialized
+     * @example
+     * const sections = [
+     *   { name: "database", properties: { host: "localhost", port: "5432" } },
+     *   { name: "*.py", properties: { indent_size: "2" } }
+     * ];
+     * console.log(INI.stringify(sections));
+     */
+    function stringify(sections: Array<SectionEntry>): string;
+
+    /**
+     * Convert array of sections to a record, merging sections with the same name
+     * @param sections - Array of section entries from INI.parse
+     * @returns Record mapping section names to their merged properties
+     * @example
+     * const sections = INI.parse(`
+     * [*.py]
+     * indent_size = 4
+     * [*.py]
+     * indent_size = 2
+     * `);
+     * const record = INI.toRecord(sections);
+     * // Returns: { "*.py": { indent_size: "2" } }
+     * // Later values override earlier ones for the same section name
+     */
+    function toRecord(sections: Array<SectionEntry>): Record<string, Section>;
+  }
+}
+
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shibanet0/datamitsu-config",
-  "version": "0.0.1-alpha-29",
+  "version": "0.0.1-alpha-30",
   "description": "",
   "keywords": [],
   "license": "MIT",