@viberails/config 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,314 @@
+import { ConfigRules, ScanResult, ViberailsConfig } from '@viberails/types';
+
+/**
+ * Default rule thresholds and toggles for a new viberails config.
+ * These values are intentionally conservative to build trust on first run.
+ */
+declare const DEFAULT_RULES: ConfigRules;
+/**
+ * Default glob patterns for files and directories to ignore.
+ */
+declare const DEFAULT_IGNORE: string[];
+
+/**
+ * Generate a ViberailsConfig from scan results.
+ *
+ * Maps the scanner's DetectedStack, DetectedStructure, and conventions
+ * into the config format with smart defaults. Low-confidence conventions
+ * are omitted. The project name is derived from the root directory basename.
+ *
+ * @param scanResult - The output of scanning a project
+ * @returns A complete ViberailsConfig ready to be written as JSON
+ */
+declare function generateConfig(scanResult: ScanResult): ViberailsConfig;
+
+/**
+ * Load and parse a viberails config file.
+ *
+ * Reads the JSON file at the given path, validates that it contains
+ * the required fields (version, name, stack, rules), and returns
+ * the parsed config.
+ *
+ * @param configPath - Absolute or relative path to viberails.config.json
+ * @returns The parsed ViberailsConfig
+ * @throws If the file doesn't exist, contains invalid JSON, or is missing required fields
+ */
+declare function loadConfig(configPath: string): Promise<ViberailsConfig>;
+/**
+ * Safely load a viberails config file, returning null on any error.
+ *
+ * Used by the CLI for "does config already exist?" checks where
+ * failure is an expected case, not an error.
+ *
+ * @param configPath - Absolute or relative path to viberails.config.json
+ * @returns The parsed ViberailsConfig, or null if loading fails
+ */
+declare function loadConfigSafe(configPath: string): Promise<ViberailsConfig | null>;
+
+/**
+ * Merge a new scan result into an existing config for `viberails sync`.
+ *
+ * Preserves all developer-confirmed values from the existing config.
+ * Adds newly detected conventions with a `_detected: true` annotation
+ * so the developer can review them. Never removes rules or values
+ * the developer has set.
+ *
+ * @param existing - The current ViberailsConfig (from viberails.config.json)
+ * @param scanResult - Fresh scan results from re-scanning the project
+ * @returns A merged config that preserves existing values and adds new detections
+ */
+declare function mergeConfig(existing: ViberailsConfig, scanResult: ScanResult): ViberailsConfig;
+
+/**
+ * JSON Schema (draft-07) definition for viberails.config.json.
+ *
+ * This schema will eventually be hosted at https://viberails.sh/schema/v1.json.
+ * For now it is exported as a TypeScript object that can be serialized to JSON.
+ */
+declare const configSchema: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly $id: "https://viberails.sh/schema/v1.json";
+    readonly title: "viberails configuration";
+    readonly description: "Configuration file for viberails — guardrails for vibe coding.";
+    readonly type: "object";
+    readonly required: readonly ["version", "name", "stack", "rules"];
+    readonly properties: {
+        readonly $schema: {
+            readonly type: "string";
+            readonly description: "JSON Schema URL for editor validation.";
+        };
+        readonly version: {
+            readonly type: "number";
+            readonly const: 1;
+            readonly description: "Config format version. Always 1 for V1.0.";
+        };
+        readonly name: {
+            readonly type: "string";
+            readonly description: "Project name, typically from package.json.";
+        };
+        readonly enforcement: {
+            readonly type: "string";
+            readonly enum: readonly ["warn", "enforce"];
+            readonly default: "warn";
+            readonly description: "Whether conventions are warned about or enforced as errors.";
+        };
+        readonly stack: {
+            readonly type: "object";
+            readonly required: readonly ["language", "packageManager"];
+            readonly properties: {
+                readonly framework: {
+                    readonly type: "string";
+                    readonly description: "Primary framework identifier (e.g. \"nextjs@15\", \"remix@2\").";
+                };
+                readonly language: {
+                    readonly type: "string";
+                    readonly description: "Primary language (e.g. \"typescript\", \"javascript\").";
+                };
+                readonly styling: {
+                    readonly type: "string";
+                    readonly description: "Styling solution (e.g. \"tailwindcss@4\", \"css-modules\").";
+                };
+                readonly backend: {
+                    readonly type: "string";
+                    readonly description: "Backend framework (e.g. \"express@5\", \"fastify\").";
+                };
+                readonly packageManager: {
+                    readonly type: "string";
+                    readonly description: "Package manager (e.g. \"pnpm\", \"npm\", \"yarn\").";
+                };
+                readonly linter: {
+                    readonly type: "string";
+                    readonly description: "Linter (e.g. \"eslint@9\", \"biome\").";
+                };
+                readonly testRunner: {
+                    readonly type: "string";
+                    readonly description: "Test runner (e.g. \"vitest\", \"jest\").";
+                };
+            };
+            readonly additionalProperties: false;
+            readonly description: "Detected or configured technology stack.";
+        };
+        readonly structure: {
+            readonly type: "object";
+            readonly properties: {
+                readonly srcDir: {
+                    readonly type: "string";
+                    readonly description: "Source directory (e.g. \"src\"), or omit for flat structure.";
+                };
+                readonly pages: {
+                    readonly type: "string";
+                    readonly description: "Pages or routes directory (e.g. \"src/app\").";
+                };
+                readonly components: {
+                    readonly type: "string";
+                    readonly description: "Components directory (e.g. \"src/components\").";
+                };
+                readonly hooks: {
+                    readonly type: "string";
+                    readonly description: "Hooks directory (e.g. \"src/hooks\").";
+                };
+                readonly utils: {
+                    readonly type: "string";
+                    readonly description: "Utilities directory (e.g. \"src/utils\", \"src/lib\").";
+                };
+                readonly types: {
+                    readonly type: "string";
+                    readonly description: "Type definitions directory (e.g. \"src/types\").";
+                };
+                readonly tests: {
+                    readonly type: "string";
+                    readonly description: "Tests directory (e.g. \"tests\", \"__tests__\").";
+                };
+                readonly testPattern: {
+                    readonly type: "string";
+                    readonly description: "Test file naming pattern (e.g. \"*.test.ts\", \"*.spec.ts\").";
+                };
+            };
+            readonly additionalProperties: false;
+            readonly description: "Detected or configured directory structure.";
+        };
+        readonly conventions: {
+            readonly type: "object";
+            readonly properties: {
+                readonly fileNaming: {
+                    readonly $ref: "#/definitions/conventionValue";
+                };
+                readonly componentNaming: {
+                    readonly $ref: "#/definitions/conventionValue";
+                };
+                readonly hookNaming: {
+                    readonly $ref: "#/definitions/conventionValue";
+                };
+                readonly importAlias: {
+                    readonly $ref: "#/definitions/conventionValue";
+                };
+            };
+            readonly additionalProperties: false;
+            readonly description: "Detected or configured coding conventions.";
+        };
+        readonly rules: {
+            readonly type: "object";
+            readonly required: readonly ["maxFileLines", "maxFunctionLines", "requireTests", "enforceNaming", "enforceBoundaries"];
+            readonly properties: {
+                readonly maxFileLines: {
+                    readonly type: "number";
+                    readonly default: 300;
+                    readonly description: "Maximum number of lines allowed per file.";
+                };
+                readonly maxFunctionLines: {
+                    readonly type: "number";
+                    readonly default: 50;
+                    readonly description: "Maximum number of lines allowed per function.";
+                };
+                readonly requireTests: {
+                    readonly type: "boolean";
+                    readonly default: true;
+                    readonly description: "Whether to require test files for source modules.";
+                };
+                readonly enforceNaming: {
+                    readonly type: "boolean";
+                    readonly default: true;
+                    readonly description: "Whether to enforce detected file naming conventions.";
+                };
+                readonly enforceBoundaries: {
+                    readonly type: "boolean";
+                    readonly default: false;
+                    readonly description: "Whether to enforce module boundary rules.";
+                };
+            };
+            readonly additionalProperties: false;
+            readonly description: "Rule thresholds and toggles for enforcement.";
+        };
+        readonly ignore: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Glob patterns for files and directories to ignore.";
+        };
+        readonly boundaries: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["from", "to", "allow"];
+                readonly properties: {
+                    readonly from: {
+                        readonly type: "string";
+                        readonly description: "Source package or directory pattern.";
+                    };
+                    readonly to: {
+                        readonly type: "string";
+                        readonly description: "Target package or directory pattern.";
+                    };
+                    readonly allow: {
+                        readonly type: "boolean";
+                        readonly description: "Whether this import direction is allowed or disallowed.";
+                    };
+                    readonly reason: {
+                        readonly type: "string";
+                        readonly description: "Human-readable explanation of why this boundary exists.";
+                    };
+                };
+                readonly additionalProperties: false;
+            };
+            readonly description: "Module boundary rules for import enforcement.";
+        };
+        readonly workspace: {
+            readonly type: "object";
+            readonly required: readonly ["packages", "isMonorepo"];
+            readonly properties: {
+                readonly packages: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Relative paths to workspace packages.";
+                };
+                readonly isMonorepo: {
+                    readonly type: "boolean";
+                    readonly description: "Whether this project is a monorepo with multiple packages.";
+                };
+            };
+            readonly additionalProperties: false;
+            readonly description: "Workspace configuration for monorepo projects.";
+        };
+    };
+    readonly additionalProperties: false;
+    readonly definitions: {
+        readonly conventionValue: {
+            readonly description: "A convention value — either a plain string (user-confirmed) or an object with scanner metadata.";
+            readonly oneOf: readonly [{
+                readonly type: "string";
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["value", "_confidence", "_consistency"];
+                readonly properties: {
+                    readonly value: {
+                        readonly type: "string";
+                        readonly description: "The convention value.";
+                    };
+                    readonly _confidence: {
+                        readonly type: "string";
+                        readonly enum: readonly ["high", "medium", "low"];
+                        readonly description: "Scanner confidence level.";
+                    };
+                    readonly _consistency: {
+                        readonly type: "number";
+                        readonly minimum: 0;
+                        readonly maximum: 100;
+                        readonly description: "Scanner consistency percentage.";
+                    };
+                    readonly _detected: {
+                        readonly type: "boolean";
+                        readonly description: "Set by mergeConfig when a convention is newly detected during sync.";
+                    };
+                };
+                readonly additionalProperties: false;
+            }];
+        };
+    };
+};
+
+declare const VERSION = "0.1.0";
+
+export { DEFAULT_IGNORE, DEFAULT_RULES, VERSION, configSchema, generateConfig, loadConfig, loadConfigSafe, mergeConfig };

package/dist/index.d.ts

@@ -0,0 +1,314 @@
+import { ConfigRules, ScanResult, ViberailsConfig } from '@viberails/types';
+
+/**
+ * Default rule thresholds and toggles for a new viberails config.
+ * These values are intentionally conservative to build trust on first run.
+ */
+declare const DEFAULT_RULES: ConfigRules;
+/**
+ * Default glob patterns for files and directories to ignore.
+ */
+declare const DEFAULT_IGNORE: string[];
+
+/**
+ * Generate a ViberailsConfig from scan results.
+ *
+ * Maps the scanner's DetectedStack, DetectedStructure, and conventions
+ * into the config format with smart defaults. Low-confidence conventions
+ * are omitted. The project name is derived from the root directory basename.
+ *
+ * @param scanResult - The output of scanning a project
+ * @returns A complete ViberailsConfig ready to be written as JSON
+ */
+declare function generateConfig(scanResult: ScanResult): ViberailsConfig;
+
+/**
+ * Load and parse a viberails config file.
+ *
+ * Reads the JSON file at the given path, validates that it contains
+ * the required fields (version, name, stack, rules), and returns
+ * the parsed config.
+ *
+ * @param configPath - Absolute or relative path to viberails.config.json
+ * @returns The parsed ViberailsConfig
+ * @throws If the file doesn't exist, contains invalid JSON, or is missing required fields
+ */
+declare function loadConfig(configPath: string): Promise<ViberailsConfig>;
+/**
+ * Safely load a viberails config file, returning null on any error.
+ *
+ * Used by the CLI for "does config already exist?" checks where
+ * failure is an expected case, not an error.
+ *
+ * @param configPath - Absolute or relative path to viberails.config.json
+ * @returns The parsed ViberailsConfig, or null if loading fails
+ */
+declare function loadConfigSafe(configPath: string): Promise<ViberailsConfig | null>;
+
+/**
+ * Merge a new scan result into an existing config for `viberails sync`.
+ *
+ * Preserves all developer-confirmed values from the existing config.
+ * Adds newly detected conventions with a `_detected: true` annotation
+ * so the developer can review them. Never removes rules or values
+ * the developer has set.
+ *
+ * @param existing - The current ViberailsConfig (from viberails.config.json)
+ * @param scanResult - Fresh scan results from re-scanning the project
+ * @returns A merged config that preserves existing values and adds new detections
+ */
+declare function mergeConfig(existing: ViberailsConfig, scanResult: ScanResult): ViberailsConfig;
+
+/**
+ * JSON Schema (draft-07) definition for viberails.config.json.
+ *
+ * This schema will eventually be hosted at https://viberails.sh/schema/v1.json.
+ * For now it is exported as a TypeScript object that can be serialized to JSON.
+ */
+declare const configSchema: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly $id: "https://viberails.sh/schema/v1.json";
+    readonly title: "viberails configuration";
+    readonly description: "Configuration file for viberails — guardrails for vibe coding.";
+    readonly type: "object";
+    readonly required: readonly ["version", "name", "stack", "rules"];
+    readonly properties: {
+        readonly $schema: {
+            readonly type: "string";
+            readonly description: "JSON Schema URL for editor validation.";
+        };
+        readonly version: {
+            readonly type: "number";
+            readonly const: 1;
+            readonly description: "Config format version. Always 1 for V1.0.";
+        };
+        readonly name: {
+            readonly type: "string";
+            readonly description: "Project name, typically from package.json.";
+        };
+        readonly enforcement: {
+            readonly type: "string";
+            readonly enum: readonly ["warn", "enforce"];
+            readonly default: "warn";
+            readonly description: "Whether conventions are warned about or enforced as errors.";
+        };
+        readonly stack: {
+            readonly type: "object";
+            readonly required: readonly ["language", "packageManager"];
+            readonly properties: {
+                readonly framework: {
+                    readonly type: "string";
+                    readonly description: "Primary framework identifier (e.g. \"nextjs@15\", \"remix@2\").";
+                };
+                readonly language: {
+                    readonly type: "string";
+                    readonly description: "Primary language (e.g. \"typescript\", \"javascript\").";
+                };
+                readonly styling: {
+                    readonly type: "string";
+                    readonly description: "Styling solution (e.g. \"tailwindcss@4\", \"css-modules\").";
+                };
+                readonly backend: {
+                    readonly type: "string";
+                    readonly description: "Backend framework (e.g. \"express@5\", \"fastify\").";
+                };
+                readonly packageManager: {
+                    readonly type: "string";
+                    readonly description: "Package manager (e.g. \"pnpm\", \"npm\", \"yarn\").";
+                };
+                readonly linter: {
+                    readonly type: "string";
+                    readonly description: "Linter (e.g. \"eslint@9\", \"biome\").";
+                };
+                readonly testRunner: {
+                    readonly type: "string";
+                    readonly description: "Test runner (e.g. \"vitest\", \"jest\").";
+                };
+            };
+            readonly additionalProperties: false;
+            readonly description: "Detected or configured technology stack.";
+        };
+        readonly structure: {
+            readonly type: "object";
+            readonly properties: {
+                readonly srcDir: {
+                    readonly type: "string";
+                    readonly description: "Source directory (e.g. \"src\"), or omit for flat structure.";
+                };
+                readonly pages: {
+                    readonly type: "string";
+                    readonly description: "Pages or routes directory (e.g. \"src/app\").";
+                };
+                readonly components: {
+                    readonly type: "string";
+                    readonly description: "Components directory (e.g. \"src/components\").";
+                };
+                readonly hooks: {
+                    readonly type: "string";
+                    readonly description: "Hooks directory (e.g. \"src/hooks\").";
+                };
+                readonly utils: {
+                    readonly type: "string";
+                    readonly description: "Utilities directory (e.g. \"src/utils\", \"src/lib\").";
+                };
+                readonly types: {
+                    readonly type: "string";
+                    readonly description: "Type definitions directory (e.g. \"src/types\").";
+                };
+                readonly tests: {
+                    readonly type: "string";
+                    readonly description: "Tests directory (e.g. \"tests\", \"__tests__\").";
+                };
+                readonly testPattern: {
+                    readonly type: "string";
+                    readonly description: "Test file naming pattern (e.g. \"*.test.ts\", \"*.spec.ts\").";
+                };
+            };
+            readonly additionalProperties: false;
+            readonly description: "Detected or configured directory structure.";
+        };
+        readonly conventions: {
+            readonly type: "object";
+            readonly properties: {
+                readonly fileNaming: {
+                    readonly $ref: "#/definitions/conventionValue";
+                };
+                readonly componentNaming: {
+                    readonly $ref: "#/definitions/conventionValue";
+                };
+                readonly hookNaming: {
+                    readonly $ref: "#/definitions/conventionValue";
+                };
+                readonly importAlias: {
+                    readonly $ref: "#/definitions/conventionValue";
+                };
+            };
+            readonly additionalProperties: false;
+            readonly description: "Detected or configured coding conventions.";
+        };
+        readonly rules: {
+            readonly type: "object";
+            readonly required: readonly ["maxFileLines", "maxFunctionLines", "requireTests", "enforceNaming", "enforceBoundaries"];
+            readonly properties: {
+                readonly maxFileLines: {
+                    readonly type: "number";
+                    readonly default: 300;
+                    readonly description: "Maximum number of lines allowed per file.";
+                };
+                readonly maxFunctionLines: {
+                    readonly type: "number";
+                    readonly default: 50;
+                    readonly description: "Maximum number of lines allowed per function.";
+                };
+                readonly requireTests: {
+                    readonly type: "boolean";
+                    readonly default: true;
+                    readonly description: "Whether to require test files for source modules.";
+                };
+                readonly enforceNaming: {
+                    readonly type: "boolean";
+                    readonly default: true;
+                    readonly description: "Whether to enforce detected file naming conventions.";
+                };
+                readonly enforceBoundaries: {
+                    readonly type: "boolean";
+                    readonly default: false;
+                    readonly description: "Whether to enforce module boundary rules.";
+                };
+            };
+            readonly additionalProperties: false;
+            readonly description: "Rule thresholds and toggles for enforcement.";
+        };
+        readonly ignore: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Glob patterns for files and directories to ignore.";
+        };
+        readonly boundaries: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["from", "to", "allow"];
+                readonly properties: {
+                    readonly from: {
+                        readonly type: "string";
+                        readonly description: "Source package or directory pattern.";
+                    };
+                    readonly to: {
+                        readonly type: "string";
+                        readonly description: "Target package or directory pattern.";
+                    };
+                    readonly allow: {
+                        readonly type: "boolean";
+                        readonly description: "Whether this import direction is allowed or disallowed.";
+                    };
+                    readonly reason: {
+                        readonly type: "string";
+                        readonly description: "Human-readable explanation of why this boundary exists.";
+                    };
+                };
+                readonly additionalProperties: false;
+            };
+            readonly description: "Module boundary rules for import enforcement.";
+        };
+        readonly workspace: {
+            readonly type: "object";
+            readonly required: readonly ["packages", "isMonorepo"];
+            readonly properties: {
+                readonly packages: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Relative paths to workspace packages.";
+                };
+                readonly isMonorepo: {
+                    readonly type: "boolean";
+                    readonly description: "Whether this project is a monorepo with multiple packages.";
+                };
+            };
+            readonly additionalProperties: false;
+            readonly description: "Workspace configuration for monorepo projects.";
+        };
+    };
+    readonly additionalProperties: false;
+    readonly definitions: {
+        readonly conventionValue: {
+            readonly description: "A convention value — either a plain string (user-confirmed) or an object with scanner metadata.";
+            readonly oneOf: readonly [{
+                readonly type: "string";
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["value", "_confidence", "_consistency"];
+                readonly properties: {
+                    readonly value: {
+                        readonly type: "string";
+                        readonly description: "The convention value.";
+                    };
+                    readonly _confidence: {
+                        readonly type: "string";
+                        readonly enum: readonly ["high", "medium", "low"];
+                        readonly description: "Scanner confidence level.";
+                    };
+                    readonly _consistency: {
+                        readonly type: "number";
+                        readonly minimum: 0;
+                        readonly maximum: 100;
+                        readonly description: "Scanner consistency percentage.";
+                    };
+                    readonly _detected: {
+                        readonly type: "boolean";
+                        readonly description: "Set by mergeConfig when a convention is newly detected during sync.";
+                    };
+                };
+                readonly additionalProperties: false;
+            }];
+        };
+    };
+};
+
+declare const VERSION = "0.1.0";
+
+export { DEFAULT_IGNORE, DEFAULT_RULES, VERSION, configSchema, generateConfig, loadConfig, loadConfigSafe, mergeConfig };