@viberails/types 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Casasola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,90 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FRAMEWORK_NAMES: () => FRAMEWORK_NAMES,
+  LIBRARY_NAMES: () => LIBRARY_NAMES,
+  ROLE_DESCRIPTIONS: () => ROLE_DESCRIPTIONS,
+  STYLING_NAMES: () => STYLING_NAMES,
+  VERSION: () => VERSION,
+  confidenceFromConsistency: () => confidenceFromConsistency
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/confidence.ts
+function confidenceFromConsistency(consistency) {
+  if (consistency >= 90) return "high";
+  if (consistency >= 70) return "medium";
+  return "low";
+}
+
+// src/display-names.ts
+var FRAMEWORK_NAMES = {
+  nextjs: "Next.js",
+  remix: "Remix",
+  nuxt: "Nuxt",
+  sveltekit: "SvelteKit",
+  astro: "Astro",
+  vite: "Vite",
+  gatsby: "Gatsby",
+  express: "Express",
+  fastify: "Fastify",
+  hono: "Hono"
+};
+var STYLING_NAMES = {
+  tailwindcss: "Tailwind CSS",
+  "css-modules": "CSS Modules",
+  "styled-components": "styled-components",
+  emotion: "Emotion",
+  sass: "Sass"
+};
+var LIBRARY_NAMES = {
+  "react-query": "React Query",
+  "tanstack-query": "TanStack Query",
+  zod: "Zod",
+  trpc: "tRPC",
+  prisma: "Prisma",
+  drizzle: "Drizzle"
+};
+var ROLE_DESCRIPTIONS = {
+  pages: "Pages / Routes",
+  components: "Components",
+  hooks: "Hooks",
+  utils: "Utilities",
+  types: "Type definitions",
+  tests: "Tests",
+  styles: "Styles",
+  api: "API routes",
+  config: "Configuration"
+};
+
+// src/index.ts
+var VERSION = "0.1.0";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FRAMEWORK_NAMES,
+  LIBRARY_NAMES,
+  ROLE_DESCRIPTIONS,
+  STYLING_NAMES,
+  VERSION,
+  confidenceFromConsistency
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/confidence.ts","../src/display-names.ts"],"sourcesContent":["export const VERSION = '0.1.0';\n\nexport type { BoundaryRule, BoundaryViolation } from './boundary.js';\nexport type { CheckResult, CheckRule, CheckViolation } from './check-result.js';\nexport type { Confidence, DetectedConvention } from './confidence.js';\nexport { confidenceFromConsistency } from './confidence.js';\nexport type {\n  ConfigConventions,\n  ConfigRules,\n  ConfigStack,\n  ConfigStructure,\n  ConventionValue,\n  ViberailsConfig,\n  WorkspaceConfig,\n} from './config.js';\nexport {\n  FRAMEWORK_NAMES,\n  LIBRARY_NAMES,\n  ROLE_DESCRIPTIONS,\n  STYLING_NAMES,\n} from './display-names.js';\nexport type {\n  ImportEdge,\n  ImportGraph,\n  ImportGraphNode,\n  ImportKind,\n  WorkspacePackage,\n} from './graph.js';\nexport type {\n  CodebaseStatistics,\n  DetectedStack,\n  DetectedStructure,\n  DetectedWorkspace,\n  DirectoryInfo,\n  DirectoryRole,\n  FileStatistic,\n  ScanResult,\n  StackItem,\n} from './scan-result.js';\n","/**\n * Confidence level for a detected convention or pattern.\n *\n * - `'high'` — ≥90% consistency across analyzed files. Enforced by default.\n * - `'medium'` — 70–89% consistency. Included in config but not enforced.\n * - `'low'` — <70% consistency. Omitted from config entirely.\n */\nexport type Confidence = 'high' | 'medium' | 'low';\n\n/**\n * A convention or pattern detected by the scanner, with metadata\n * about how confidently it was identified.\n *\n * @typeParam T - The type of the detected value. Defaults to `string`.\n */\nexport interface DetectedConvention<T = string> {\n  /** The detected value (e.g. a naming pattern, file extension, or path). */\n  value: T;\n\n  /** How confident the scanner is in this detection. */\n  confidence: Confidence;\n\n  /** Number of files analyzed to determine this convention. */\n  sampleSize: number;\n\n  /** Percentage (0–100) of files that follow this convention. */\n  consistency: number;\n}\n\n/**\n * Derives a confidence level from a consistency percentage.\n *\n * @param consistency - A number from 0 to 100 representing the percentage\n *   of files that follow a given convention.\n * @returns The corresponding confidence level:\n *   - `'high'` for consistency ≥ 90\n *   - `'medium'` for consistency ≥ 70 and < 90\n *   - `'low'` for consistency < 70\n */\nexport function confidenceFromConsistency(consistency: number): Confidence {\n  if (consistency >= 90) return 'high';\n  if (consistency >= 70) return 'medium';\n  return 'low';\n}\n","/** Display names for framework identifiers. */\nexport const FRAMEWORK_NAMES: Record<string, string> = {\n  nextjs: 'Next.js',\n  remix: 'Remix',\n  nuxt: 'Nuxt',\n  sveltekit: 'SvelteKit',\n  astro: 'Astro',\n  vite: 'Vite',\n  gatsby: 'Gatsby',\n  express: 'Express',\n  fastify: 'Fastify',\n  hono: 'Hono',\n};\n\n/** Display names for styling libraries. */\nexport const STYLING_NAMES: Record<string, string> = {\n  tailwindcss: 'Tailwind CSS',\n  'css-modules': 'CSS Modules',\n  'styled-components': 'styled-components',\n  emotion: 'Emotion',\n  sass: 'Sass',\n};\n\n/** Display names for notable libraries. */\nexport const LIBRARY_NAMES: Record<string, string> = {\n  'react-query': 'React Query',\n  'tanstack-query': 'TanStack Query',\n  zod: 'Zod',\n  trpc: 'tRPC',\n  prisma: 'Prisma',\n  drizzle: 'Drizzle',\n};\n\n/** Display names for directory roles. */\nexport const ROLE_DESCRIPTIONS: Record<string, string> = {\n  pages: 'Pages / Routes',\n  components: 'Components',\n  hooks: 'Hooks',\n  utils: 'Utilities',\n  types: 'Type definitions',\n  tests: 'Tests',\n  styles: 'Styles',\n  api: 'API routes',\n  config: 'Configuration',\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACuCO,SAAS,0BAA0B,aAAiC;AACzE,MAAI,eAAe,GAAI,QAAO;AAC9B,MAAI,eAAe,GAAI,QAAO;AAC9B,SAAO;AACT;;;AC1CO,IAAM,kBAA0C;AAAA,EACrD,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,MAAM;AAAA,EACN,WAAW;AAAA,EACX,OAAO;AAAA,EACP,MAAM;AAAA,EACN,QAAQ;AAAA,EACR,SAAS;AAAA,EACT,SAAS;AAAA,EACT,MAAM;AACR;AAGO,IAAM,gBAAwC;AAAA,EACnD,aAAa;AAAA,EACb,eAAe;AAAA,EACf,qBAAqB;AAAA,EACrB,SAAS;AAAA,EACT,MAAM;AACR;AAGO,IAAM,gBAAwC;AAAA,EACnD,eAAe;AAAA,EACf,kBAAkB;AAAA,EAClB,KAAK;AAAA,EACL,MAAM;AAAA,EACN,QAAQ;AAAA,EACR,SAAS;AACX;AAGO,IAAM,oBAA4C;AAAA,EACvD,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,OAAO;AAAA,EACP,OAAO;AAAA,EACP,OAAO;AAAA,EACP,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,KAAK;AAAA,EACL,QAAQ;AACV;;;AF5CO,IAAM,UAAU;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,402 @@
+/** A boundary rule defining allowed or disallowed imports. */
+interface BoundaryRule {
+    /** Source package or directory pattern. */
+    from: string;
+    /** Target package or directory pattern. */
+    to: string;
+    /** Whether this import direction is allowed (`true`) or disallowed (`false`). */
+    allow: boolean;
+    /** Human-readable explanation of why this boundary exists. */
+    reason?: string;
+}
+/** A boundary violation detected during checking. */
+interface BoundaryViolation {
+    /** File containing the violating import. */
+    file: string;
+    /** Line number of the violating import. */
+    line: number;
+    /** The import specifier that violated the boundary. */
+    specifier: string;
+    /** What the specifier resolved to. */
+    resolvedTo: string;
+    /** The boundary rule that was violated. */
+    rule: BoundaryRule;
+}
+
+/**
+ * The type of rule that was violated.
+ */
+type CheckRule = 'file-size' | 'file-naming' | 'missing-test' | 'boundary-violation';
+/**
+ * A single rule violation detected by `viberails check`.
+ */
+interface CheckViolation {
+    /** Relative path to the offending file. */
+    file: string;
+    /** Which rule was violated. */
+    rule: CheckRule;
+    /** Human-readable description of the violation. */
+    message: string;
+    /** Severity derived from config.enforcement. */
+    severity: 'error' | 'warn';
+}
+/**
+ * The result of running `viberails check`.
+ */
+interface CheckResult {
+    /** All violations found. */
+    violations: CheckViolation[];
+    /** Number of files that were checked. */
+    checkedFiles: number;
+    /** The enforcement mode from config. */
+    enforcement: 'enforce' | 'warn';
+}
+
+/**
+ * Confidence level for a detected convention or pattern.
+ *
+ * - `'high'` — ≥90% consistency across analyzed files. Enforced by default.
+ * - `'medium'` — 70–89% consistency. Included in config but not enforced.
+ * - `'low'` — <70% consistency. Omitted from config entirely.
+ */
+type Confidence = 'high' | 'medium' | 'low';
+/**
+ * A convention or pattern detected by the scanner, with metadata
+ * about how confidently it was identified.
+ *
+ * @typeParam T - The type of the detected value. Defaults to `string`.
+ */
+interface DetectedConvention<T = string> {
+    /** The detected value (e.g. a naming pattern, file extension, or path). */
+    value: T;
+    /** How confident the scanner is in this detection. */
+    confidence: Confidence;
+    /** Number of files analyzed to determine this convention. */
+    sampleSize: number;
+    /** Percentage (0–100) of files that follow this convention. */
+    consistency: number;
+}
+/**
+ * Derives a confidence level from a consistency percentage.
+ *
+ * @param consistency - A number from 0 to 100 representing the percentage
+ *   of files that follow a given convention.
+ * @returns The corresponding confidence level:
+ *   - `'high'` for consistency ≥ 90
+ *   - `'medium'` for consistency ≥ 70 and < 90
+ *   - `'low'` for consistency < 70
+ */
+declare function confidenceFromConsistency(consistency: number): Confidence;
+
+/**
+ * The top-level configuration shape for `viberails.config.json`.
+ * Generated from scan results and optionally edited by the user.
+ */
+interface ViberailsConfig {
+    /** JSON Schema URL for editor validation. */
+    $schema?: string;
+    /** Config format version. Always `1` for V1.0. */
+    version: number;
+    /** Project name, typically from package.json. */
+    name: string;
+    /** Whether conventions are warned about or enforced as errors. */
+    enforcement: 'warn' | 'enforce';
+    /** Detected or configured technology stack. */
+    stack: ConfigStack;
+    /** Detected or configured directory structure. */
+    structure: ConfigStructure;
+    /** Detected or configured coding conventions. */
+    conventions: ConfigConventions;
+    /** Rule thresholds and toggles for enforcement. */
+    rules: ConfigRules;
+    /** Glob patterns for files and directories to ignore. */
+    ignore: string[];
+    /** Module boundary rules for import enforcement (V1.1+). */
+    boundaries?: BoundaryRule[];
+    /** Workspace configuration for monorepo support (V1.1+). */
+    workspace?: WorkspaceConfig;
+}
+/**
+ * Workspace configuration for monorepo projects.
+ */
+interface WorkspaceConfig {
+    /** Relative paths to workspace packages (e.g. `"packages/scanner"`). */
+    packages: string[];
+    /** Whether this project is a monorepo with multiple packages. */
+    isMonorepo: boolean;
+}
+/**
+ * Technology stack configuration. Each field is a string identifier,
+ * optionally with a version suffix (e.g. `"nextjs@15"`, `"typescript"`).
+ */
+interface ConfigStack {
+    /** Primary framework identifier (e.g. `"nextjs@15"`, `"remix@2"`). */
+    framework?: string;
+    /** Primary language (e.g. `"typescript"`, `"javascript"`). */
+    language: string;
+    /** Styling solution (e.g. `"tailwindcss@4"`, `"css-modules"`). */
+    styling?: string;
+    /** Backend framework (e.g. `"express@5"`, `"fastify"`). */
+    backend?: string;
+    /** Package manager (e.g. `"pnpm"`, `"npm"`, `"yarn"`). */
+    packageManager: string;
+    /** Linter (e.g. `"eslint@9"`, `"biome"`). */
+    linter?: string;
+    /** Test runner (e.g. `"vitest"`, `"jest"`). */
+    testRunner?: string;
+}
+/**
+ * Directory structure configuration. Each field is a path relative
+ * to the project root.
+ */
+interface ConfigStructure {
+    /** Source directory (e.g. `"src"`), or undefined for flat structure. */
+    srcDir?: string;
+    /** Pages or routes directory (e.g. `"src/app"`, `"pages"`). */
+    pages?: string;
+    /** Components directory (e.g. `"src/components"`). */
+    components?: string;
+    /** Hooks directory (e.g. `"src/hooks"`). */
+    hooks?: string;
+    /** Utilities directory (e.g. `"src/utils"`, `"src/lib"`). */
+    utils?: string;
+    /** Type definitions directory (e.g. `"src/types"`). */
+    types?: string;
+    /** Tests directory (e.g. `"tests"`, `"__tests__"`). */
+    tests?: string;
+    /** Test file naming pattern (e.g. `"*.test.ts"`, `"*.spec.ts"`). */
+    testPattern?: string;
+}
+/**
+ * A convention value that may carry scanner metadata.
+ * When generated from a scan, includes confidence and consistency info.
+ * When manually set, is just a plain string.
+ */
+type ConventionValue = string | {
+    /** The convention value. */
+    value: string;
+    /** Scanner confidence level. Prefixed with `_` to signal metadata. */
+    _confidence: Confidence;
+    /** Scanner consistency percentage. Prefixed with `_` to signal metadata. */
+    _consistency: number;
+    /** Set by mergeConfig when a convention is newly detected during sync. */
+    _detected?: boolean;
+};
+/**
+ * Coding convention configuration. Each field can be a plain string
+ * (confirmed by user) or an object with scanner metadata (auto-detected).
+ */
+interface ConfigConventions {
+    /** File naming convention (e.g. `"kebab-case"`, `"camelCase"`). */
+    fileNaming?: ConventionValue;
+    /** Component naming convention (e.g. `"PascalCase"`). */
+    componentNaming?: ConventionValue;
+    /** Hook naming convention (e.g. `"useXxx"`). */
+    hookNaming?: ConventionValue;
+    /** Import alias pattern (e.g. `"@/*"`, `"~/*"`). */
+    importAlias?: ConventionValue;
+}
+/**
+ * Rule thresholds and toggles for convention enforcement.
+ */
+interface ConfigRules {
+    /**
+     * Maximum number of lines allowed per file.
+     * @default 300
+     */
+    maxFileLines: number;
+    /**
+     * Maximum number of lines allowed per function.
+     * @default 50
+     */
+    maxFunctionLines: number;
+    /**
+     * Whether to require test files for source modules.
+     * @default true
+     */
+    requireTests: boolean;
+    /**
+     * Whether to enforce detected file naming conventions.
+     * @default true
+     */
+    enforceNaming: boolean;
+    /**
+     * Whether to enforce module boundary rules.
+     * @default false (V1.1+ feature)
+     */
+    enforceBoundaries: boolean;
+}
+
+/** Display names for framework identifiers. */
+declare const FRAMEWORK_NAMES: Record<string, string>;
+/** Display names for styling libraries. */
+declare const STYLING_NAMES: Record<string, string>;
+/** Display names for notable libraries. */
+declare const LIBRARY_NAMES: Record<string, string>;
+/** Display names for directory roles. */
+declare const ROLE_DESCRIPTIONS: Record<string, string>;
+
+/** A node in the import graph, representing one source file. */
+interface ImportGraphNode {
+    /** Absolute path to the file. */
+    filePath: string;
+    /** Path relative to the project or package root. */
+    relativePath: string;
+    /** Workspace package this file belongs to, if any. */
+    packageName?: string;
+}
+/** A single resolved import edge. */
+interface ImportEdge {
+    /** Absolute path of the importing file. */
+    source: string;
+    /** Absolute path or package name for externals. */
+    target: string;
+    /** Raw import specifier as written in source code. */
+    specifier: string;
+    /** Whether this is a type-only import (`import type { ... }`). */
+    typeOnly: boolean;
+    /** Whether this is a dynamic import (`await import('...')`). */
+    dynamic: boolean;
+    /** Line number of the import statement. */
+    line: number;
+}
+/** Classification of a resolved import. */
+type ImportKind = 'internal' | 'workspace' | 'external' | 'builtin' | 'unresolved';
+/** The complete import graph for a project. */
+interface ImportGraph {
+    /** All source file nodes in the graph. */
+    nodes: ImportGraphNode[];
+    /** All import edges between nodes. */
+    edges: ImportEdge[];
+    /** Detected workspace packages. */
+    packages: WorkspacePackage[];
+    /** Detected import cycles, each as a list of file paths. */
+    cycles: string[][];
+}
+/** A detected workspace package. */
+interface WorkspacePackage {
+    /** Package name from package.json. */
+    name: string;
+    /** Absolute path to the package root. */
+    path: string;
+    /** Path relative to the workspace root. */
+    relativePath: string;
+    /** Names of other workspace packages this package depends on. */
+    internalDeps: string[];
+}
+
+/**
+ * The complete output of scanning a project. Consumed by the config
+ * generator and context generator to produce AI context files.
+ */
+interface ScanResult {
+    /** Absolute path to the project root directory. */
+    root: string;
+    /** Detected technology stack (framework, language, tooling). */
+    stack: DetectedStack;
+    /** Detected directory structure and organization. */
+    structure: DetectedStructure;
+    /** Detected coding conventions, keyed by convention name. */
+    conventions: Record<string, DetectedConvention>;
+    /** Quantitative statistics about the codebase. */
+    statistics: CodebaseStatistics;
+    /** Detected workspace information for monorepo projects (V1.1+). */
+    workspace?: DetectedWorkspace;
+}
+/**
+ * Workspace information detected by scanning the project root
+ * for pnpm-workspace.yaml or package.json workspaces field.
+ */
+interface DetectedWorkspace {
+    /** Workspace glob patterns from configuration (e.g. `["packages/*"]`). */
+    patterns: string[];
+    /** Resolved workspace packages. */
+    packages: WorkspacePackage[];
+}
+/**
+ * The detected technology stack of a project, extracted primarily
+ * from package.json dependencies and configuration files.
+ */
+interface DetectedStack {
+    /** Primary framework (e.g. Next.js, Remix, Astro). */
+    framework?: StackItem;
+    /** Primary language (e.g. TypeScript, JavaScript). */
+    language: StackItem;
+    /** Styling solution (e.g. Tailwind CSS, CSS Modules). */
+    styling?: StackItem;
+    /** Backend framework or runtime (e.g. Express, Fastify). */
+    backend?: StackItem;
+    /** Package manager used (e.g. pnpm, npm, yarn). */
+    packageManager: StackItem;
+    /** Linter in use (e.g. ESLint, Biome). */
+    linter?: StackItem;
+    /** Test runner in use (e.g. Vitest, Jest). */
+    testRunner?: StackItem;
+    /** Notable libraries detected (e.g. Zod, tRPC, React Query). */
+    libraries: StackItem[];
+}
+/**
+ * A single technology or tool detected in the project.
+ */
+interface StackItem {
+    /** Identifier name of the tool or technology. */
+    name: string;
+    /** Detected version, if available. */
+    version?: string;
+}
+/**
+ * The detected directory structure and organization of a project.
+ */
+interface DetectedStructure {
+    /** Source directory name (e.g. `'src'`), or undefined if the project uses a flat structure. */
+    srcDir?: string;
+    /** Detected meaningful directories with their roles. */
+    directories: DirectoryInfo[];
+    /** Detected test file naming pattern (e.g. `*.test.ts`, `*.spec.ts`). */
+    testPattern?: DetectedConvention<string>;
+}
+/**
+ * Information about a detected directory and its inferred role.
+ */
+interface DirectoryInfo {
+    /** Path relative to the project root. */
+    path: string;
+    /** The inferred role of this directory. */
+    role: DirectoryRole;
+    /** Number of files in this directory (non-recursive). */
+    fileCount: number;
+    /** How confident the scanner is in the role assignment. */
+    confidence: Confidence;
+}
+/**
+ * The inferred role of a directory in the project structure.
+ */
+type DirectoryRole = 'pages' | 'components' | 'hooks' | 'utils' | 'types' | 'tests' | 'styles' | 'api' | 'config' | 'unknown';
+/**
+ * Quantitative statistics about the codebase.
+ */
+interface CodebaseStatistics {
+    /** Total number of source files. */
+    totalFiles: number;
+    /** Total number of lines across all source files. */
+    totalLines: number;
+    /** Average number of lines per file. */
+    averageFileLines: number;
+    /** Top 5 largest files by line count. */
+    largestFiles: FileStatistic[];
+    /** File count grouped by extension (e.g. `{ '.ts': 42, '.tsx': 18 }`). */
+    filesByExtension: Record<string, number>;
+}
+/**
+ * Line count information for a single file.
+ */
+interface FileStatistic {
+    /** Path relative to the project root. */
+    path: string;
+    /** Number of lines in the file. */
+    lines: number;
+}
+
+declare const VERSION = "0.1.0";
+
+export { type BoundaryRule, type BoundaryViolation, type CheckResult, type CheckRule, type CheckViolation, type CodebaseStatistics, type Confidence, type ConfigConventions, type ConfigRules, type ConfigStack, type ConfigStructure, type ConventionValue, type DetectedConvention, type DetectedStack, type DetectedStructure, type DetectedWorkspace, type DirectoryInfo, type DirectoryRole, FRAMEWORK_NAMES, type FileStatistic, type ImportEdge, type ImportGraph, type ImportGraphNode, type ImportKind, LIBRARY_NAMES, ROLE_DESCRIPTIONS, STYLING_NAMES, type ScanResult, type StackItem, VERSION, type ViberailsConfig, type WorkspaceConfig, type WorkspacePackage, confidenceFromConsistency };

package/dist/index.d.ts

@@ -0,0 +1,402 @@
+/** A boundary rule defining allowed or disallowed imports. */
+interface BoundaryRule {
+    /** Source package or directory pattern. */
+    from: string;
+    /** Target package or directory pattern. */
+    to: string;
+    /** Whether this import direction is allowed (`true`) or disallowed (`false`). */
+    allow: boolean;
+    /** Human-readable explanation of why this boundary exists. */
+    reason?: string;
+}
+/** A boundary violation detected during checking. */
+interface BoundaryViolation {
+    /** File containing the violating import. */
+    file: string;
+    /** Line number of the violating import. */
+    line: number;
+    /** The import specifier that violated the boundary. */
+    specifier: string;
+    /** What the specifier resolved to. */
+    resolvedTo: string;
+    /** The boundary rule that was violated. */
+    rule: BoundaryRule;
+}
+
+/**
+ * The type of rule that was violated.
+ */
+type CheckRule = 'file-size' | 'file-naming' | 'missing-test' | 'boundary-violation';
+/**
+ * A single rule violation detected by `viberails check`.
+ */
+interface CheckViolation {
+    /** Relative path to the offending file. */
+    file: string;
+    /** Which rule was violated. */
+    rule: CheckRule;
+    /** Human-readable description of the violation. */
+    message: string;
+    /** Severity derived from config.enforcement. */
+    severity: 'error' | 'warn';
+}
+/**
+ * The result of running `viberails check`.
+ */
+interface CheckResult {
+    /** All violations found. */
+    violations: CheckViolation[];
+    /** Number of files that were checked. */
+    checkedFiles: number;
+    /** The enforcement mode from config. */
+    enforcement: 'enforce' | 'warn';
+}
+
+/**
+ * Confidence level for a detected convention or pattern.
+ *
+ * - `'high'` — ≥90% consistency across analyzed files. Enforced by default.
+ * - `'medium'` — 70–89% consistency. Included in config but not enforced.
+ * - `'low'` — <70% consistency. Omitted from config entirely.
+ */
+type Confidence = 'high' | 'medium' | 'low';
+/**
+ * A convention or pattern detected by the scanner, with metadata
+ * about how confidently it was identified.
+ *
+ * @typeParam T - The type of the detected value. Defaults to `string`.
+ */
+interface DetectedConvention<T = string> {
+    /** The detected value (e.g. a naming pattern, file extension, or path). */
+    value: T;
+    /** How confident the scanner is in this detection. */
+    confidence: Confidence;
+    /** Number of files analyzed to determine this convention. */
+    sampleSize: number;
+    /** Percentage (0–100) of files that follow this convention. */
+    consistency: number;
+}
+/**
+ * Derives a confidence level from a consistency percentage.
+ *
+ * @param consistency - A number from 0 to 100 representing the percentage
+ *   of files that follow a given convention.
+ * @returns The corresponding confidence level:
+ *   - `'high'` for consistency ≥ 90
+ *   - `'medium'` for consistency ≥ 70 and < 90
+ *   - `'low'` for consistency < 70
+ */
+declare function confidenceFromConsistency(consistency: number): Confidence;
+
+/**
+ * The top-level configuration shape for `viberails.config.json`.
+ * Generated from scan results and optionally edited by the user.
+ */
+interface ViberailsConfig {
+    /** JSON Schema URL for editor validation. */
+    $schema?: string;
+    /** Config format version. Always `1` for V1.0. */
+    version: number;
+    /** Project name, typically from package.json. */
+    name: string;
+    /** Whether conventions are warned about or enforced as errors. */
+    enforcement: 'warn' | 'enforce';
+    /** Detected or configured technology stack. */
+    stack: ConfigStack;
+    /** Detected or configured directory structure. */
+    structure: ConfigStructure;
+    /** Detected or configured coding conventions. */
+    conventions: ConfigConventions;
+    /** Rule thresholds and toggles for enforcement. */
+    rules: ConfigRules;
+    /** Glob patterns for files and directories to ignore. */
+    ignore: string[];
+    /** Module boundary rules for import enforcement (V1.1+). */
+    boundaries?: BoundaryRule[];
+    /** Workspace configuration for monorepo support (V1.1+). */
+    workspace?: WorkspaceConfig;
+}
+/**
+ * Workspace configuration for monorepo projects.
+ */
+interface WorkspaceConfig {
+    /** Relative paths to workspace packages (e.g. `"packages/scanner"`). */
+    packages: string[];
+    /** Whether this project is a monorepo with multiple packages. */
+    isMonorepo: boolean;
+}
+/**
+ * Technology stack configuration. Each field is a string identifier,
+ * optionally with a version suffix (e.g. `"nextjs@15"`, `"typescript"`).
+ */
+interface ConfigStack {
+    /** Primary framework identifier (e.g. `"nextjs@15"`, `"remix@2"`). */
+    framework?: string;
+    /** Primary language (e.g. `"typescript"`, `"javascript"`). */
+    language: string;
+    /** Styling solution (e.g. `"tailwindcss@4"`, `"css-modules"`). */
+    styling?: string;
+    /** Backend framework (e.g. `"express@5"`, `"fastify"`). */
+    backend?: string;
+    /** Package manager (e.g. `"pnpm"`, `"npm"`, `"yarn"`). */
+    packageManager: string;
+    /** Linter (e.g. `"eslint@9"`, `"biome"`). */
+    linter?: string;
+    /** Test runner (e.g. `"vitest"`, `"jest"`). */
+    testRunner?: string;
+}
+/**
+ * Directory structure configuration. Each field is a path relative
+ * to the project root.
+ */
+interface ConfigStructure {
+    /** Source directory (e.g. `"src"`), or undefined for flat structure. */
+    srcDir?: string;
+    /** Pages or routes directory (e.g. `"src/app"`, `"pages"`). */
+    pages?: string;
+    /** Components directory (e.g. `"src/components"`). */
+    components?: string;
+    /** Hooks directory (e.g. `"src/hooks"`). */
+    hooks?: string;
+    /** Utilities directory (e.g. `"src/utils"`, `"src/lib"`). */
+    utils?: string;
+    /** Type definitions directory (e.g. `"src/types"`). */
+    types?: string;
+    /** Tests directory (e.g. `"tests"`, `"__tests__"`). */
+    tests?: string;
+    /** Test file naming pattern (e.g. `"*.test.ts"`, `"*.spec.ts"`). */
+    testPattern?: string;
+}
+/**
+ * A convention value that may carry scanner metadata.
+ * When generated from a scan, includes confidence and consistency info.
+ * When manually set, is just a plain string.
+ */
+type ConventionValue = string | {
+    /** The convention value. */
+    value: string;
+    /** Scanner confidence level. Prefixed with `_` to signal metadata. */
+    _confidence: Confidence;
+    /** Scanner consistency percentage. Prefixed with `_` to signal metadata. */
+    _consistency: number;
+    /** Set by mergeConfig when a convention is newly detected during sync. */
+    _detected?: boolean;
+};
+/**
+ * Coding convention configuration. Each field can be a plain string
+ * (confirmed by user) or an object with scanner metadata (auto-detected).
+ */
+interface ConfigConventions {
+    /** File naming convention (e.g. `"kebab-case"`, `"camelCase"`). */
+    fileNaming?: ConventionValue;
+    /** Component naming convention (e.g. `"PascalCase"`). */
+    componentNaming?: ConventionValue;
+    /** Hook naming convention (e.g. `"useXxx"`). */
+    hookNaming?: ConventionValue;
+    /** Import alias pattern (e.g. `"@/*"`, `"~/*"`). */
+    importAlias?: ConventionValue;
+}
+/**
+ * Rule thresholds and toggles for convention enforcement.
+ */
+interface ConfigRules {
+    /**
+     * Maximum number of lines allowed per file.
+     * @default 300
+     */
+    maxFileLines: number;
+    /**
+     * Maximum number of lines allowed per function.
+     * @default 50
+     */
+    maxFunctionLines: number;
+    /**
+     * Whether to require test files for source modules.
+     * @default true
+     */
+    requireTests: boolean;
+    /**
+     * Whether to enforce detected file naming conventions.
+     * @default true
+     */
+    enforceNaming: boolean;
+    /**
+     * Whether to enforce module boundary rules.
+     * @default false (V1.1+ feature)
+     */
+    enforceBoundaries: boolean;
+}
+
+/** Display names for framework identifiers. */
+declare const FRAMEWORK_NAMES: Record<string, string>;
+/** Display names for styling libraries. */
+declare const STYLING_NAMES: Record<string, string>;
+/** Display names for notable libraries. */
+declare const LIBRARY_NAMES: Record<string, string>;
+/** Display names for directory roles. */
+declare const ROLE_DESCRIPTIONS: Record<string, string>;
+
+/** A node in the import graph, representing one source file. */
+interface ImportGraphNode {
+    /** Absolute path to the file. */
+    filePath: string;
+    /** Path relative to the project or package root. */
+    relativePath: string;
+    /** Workspace package this file belongs to, if any. */
+    packageName?: string;
+}
+/** A single resolved import edge. */
+interface ImportEdge {
+    /** Absolute path of the importing file. */
+    source: string;
+    /** Absolute path or package name for externals. */
+    target: string;
+    /** Raw import specifier as written in source code. */
+    specifier: string;
+    /** Whether this is a type-only import (`import type { ... }`). */
+    typeOnly: boolean;
+    /** Whether this is a dynamic import (`await import('...')`). */
+    dynamic: boolean;
+    /** Line number of the import statement. */
+    line: number;
+}
+/** Classification of a resolved import. */
+type ImportKind = 'internal' | 'workspace' | 'external' | 'builtin' | 'unresolved';
+/** The complete import graph for a project. */
+interface ImportGraph {
+    /** All source file nodes in the graph. */
+    nodes: ImportGraphNode[];
+    /** All import edges between nodes. */
+    edges: ImportEdge[];
+    /** Detected workspace packages. */
+    packages: WorkspacePackage[];
+    /** Detected import cycles, each as a list of file paths. */
+    cycles: string[][];
+}
+/** A detected workspace package. */
+interface WorkspacePackage {
+    /** Package name from package.json. */
+    name: string;
+    /** Absolute path to the package root. */
+    path: string;
+    /** Path relative to the workspace root. */
+    relativePath: string;
+    /** Names of other workspace packages this package depends on. */
+    internalDeps: string[];
+}
+
+/**
+ * The complete output of scanning a project. Consumed by the config
+ * generator and context generator to produce AI context files.
+ */
+interface ScanResult {
+    /** Absolute path to the project root directory. */
+    root: string;
+    /** Detected technology stack (framework, language, tooling). */
+    stack: DetectedStack;
+    /** Detected directory structure and organization. */
+    structure: DetectedStructure;
+    /** Detected coding conventions, keyed by convention name. */
+    conventions: Record<string, DetectedConvention>;
+    /** Quantitative statistics about the codebase. */
+    statistics: CodebaseStatistics;
+    /** Detected workspace information for monorepo projects (V1.1+). */
+    workspace?: DetectedWorkspace;
+}
+/**
+ * Workspace information detected by scanning the project root
+ * for pnpm-workspace.yaml or package.json workspaces field.
+ */
+interface DetectedWorkspace {
+    /** Workspace glob patterns from configuration (e.g. `["packages/*"]`). */
+    patterns: string[];
+    /** Resolved workspace packages. */
+    packages: WorkspacePackage[];
+}
+/**
+ * The detected technology stack of a project, extracted primarily
+ * from package.json dependencies and configuration files.
+ */
+interface DetectedStack {
+    /** Primary framework (e.g. Next.js, Remix, Astro). */
+    framework?: StackItem;
+    /** Primary language (e.g. TypeScript, JavaScript). */
+    language: StackItem;
+    /** Styling solution (e.g. Tailwind CSS, CSS Modules). */
+    styling?: StackItem;
+    /** Backend framework or runtime (e.g. Express, Fastify). */
+    backend?: StackItem;
+    /** Package manager used (e.g. pnpm, npm, yarn). */
+    packageManager: StackItem;
+    /** Linter in use (e.g. ESLint, Biome). */
+    linter?: StackItem;
+    /** Test runner in use (e.g. Vitest, Jest). */
+    testRunner?: StackItem;
+    /** Notable libraries detected (e.g. Zod, tRPC, React Query). */
+    libraries: StackItem[];
+}
+/**
+ * A single technology or tool detected in the project.
+ */
+interface StackItem {
+    /** Identifier name of the tool or technology. */
+    name: string;
+    /** Detected version, if available. */
+    version?: string;
+}
+/**
+ * The detected directory structure and organization of a project.
+ */
+interface DetectedStructure {
+    /** Source directory name (e.g. `'src'`), or undefined if the project uses a flat structure. */
+    srcDir?: string;
+    /** Detected meaningful directories with their roles. */
+    directories: DirectoryInfo[];
+    /** Detected test file naming pattern (e.g. `*.test.ts`, `*.spec.ts`). */
+    testPattern?: DetectedConvention<string>;
+}
+/**
+ * Information about a detected directory and its inferred role.
+ */
+interface DirectoryInfo {
+    /** Path relative to the project root. */
+    path: string;
+    /** The inferred role of this directory. */
+    role: DirectoryRole;
+    /** Number of files in this directory (non-recursive). */
+    fileCount: number;
+    /** How confident the scanner is in the role assignment. */
+    confidence: Confidence;
+}
+/**
+ * The inferred role of a directory in the project structure.
+ */
+type DirectoryRole = 'pages' | 'components' | 'hooks' | 'utils' | 'types' | 'tests' | 'styles' | 'api' | 'config' | 'unknown';
+/**
+ * Quantitative statistics about the codebase.
+ */
+interface CodebaseStatistics {
+    /** Total number of source files. */
+    totalFiles: number;
+    /** Total number of lines across all source files. */
+    totalLines: number;
+    /** Average number of lines per file. */
+    averageFileLines: number;
+    /** Top 5 largest files by line count. */
+    largestFiles: FileStatistic[];
+    /** File count grouped by extension (e.g. `{ '.ts': 42, '.tsx': 18 }`). */
+    filesByExtension: Record<string, number>;
+}
+/**
+ * Line count information for a single file.
+ */
+interface FileStatistic {
+    /** Path relative to the project root. */
+    path: string;
+    /** Number of lines in the file. */
+    lines: number;
+}
+
+declare const VERSION = "0.1.0";
+
+export { type BoundaryRule, type BoundaryViolation, type CheckResult, type CheckRule, type CheckViolation, type CodebaseStatistics, type Confidence, type ConfigConventions, type ConfigRules, type ConfigStack, type ConfigStructure, type ConventionValue, type DetectedConvention, type DetectedStack, type DetectedStructure, type DetectedWorkspace, type DirectoryInfo, type DirectoryRole, FRAMEWORK_NAMES, type FileStatistic, type ImportEdge, type ImportGraph, type ImportGraphNode, type ImportKind, LIBRARY_NAMES, ROLE_DESCRIPTIONS, STYLING_NAMES, type ScanResult, type StackItem, VERSION, type ViberailsConfig, type WorkspaceConfig, type WorkspacePackage, confidenceFromConsistency };

package/dist/index.js

@@ -0,0 +1,58 @@
+// src/confidence.ts
+function confidenceFromConsistency(consistency) {
+  if (consistency >= 90) return "high";
+  if (consistency >= 70) return "medium";
+  return "low";
+}
+
+// src/display-names.ts
+var FRAMEWORK_NAMES = {
+  nextjs: "Next.js",
+  remix: "Remix",
+  nuxt: "Nuxt",
+  sveltekit: "SvelteKit",
+  astro: "Astro",
+  vite: "Vite",
+  gatsby: "Gatsby",
+  express: "Express",
+  fastify: "Fastify",
+  hono: "Hono"
+};
+var STYLING_NAMES = {
+  tailwindcss: "Tailwind CSS",
+  "css-modules": "CSS Modules",
+  "styled-components": "styled-components",
+  emotion: "Emotion",
+  sass: "Sass"
+};
+var LIBRARY_NAMES = {
+  "react-query": "React Query",
+  "tanstack-query": "TanStack Query",
+  zod: "Zod",
+  trpc: "tRPC",
+  prisma: "Prisma",
+  drizzle: "Drizzle"
+};
+var ROLE_DESCRIPTIONS = {
+  pages: "Pages / Routes",
+  components: "Components",
+  hooks: "Hooks",
+  utils: "Utilities",
+  types: "Type definitions",
+  tests: "Tests",
+  styles: "Styles",
+  api: "API routes",
+  config: "Configuration"
+};
+
+// src/index.ts
+var VERSION = "0.1.0";
+export {
+  FRAMEWORK_NAMES,
+  LIBRARY_NAMES,
+  ROLE_DESCRIPTIONS,
+  STYLING_NAMES,
+  VERSION,
+  confidenceFromConsistency
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/confidence.ts","../src/display-names.ts","../src/index.ts"],"sourcesContent":["/**\n * Confidence level for a detected convention or pattern.\n *\n * - `'high'` — ≥90% consistency across analyzed files. Enforced by default.\n * - `'medium'` — 70–89% consistency. Included in config but not enforced.\n * - `'low'` — <70% consistency. Omitted from config entirely.\n */\nexport type Confidence = 'high' | 'medium' | 'low';\n\n/**\n * A convention or pattern detected by the scanner, with metadata\n * about how confidently it was identified.\n *\n * @typeParam T - The type of the detected value. Defaults to `string`.\n */\nexport interface DetectedConvention<T = string> {\n  /** The detected value (e.g. a naming pattern, file extension, or path). */\n  value: T;\n\n  /** How confident the scanner is in this detection. */\n  confidence: Confidence;\n\n  /** Number of files analyzed to determine this convention. */\n  sampleSize: number;\n\n  /** Percentage (0–100) of files that follow this convention. */\n  consistency: number;\n}\n\n/**\n * Derives a confidence level from a consistency percentage.\n *\n * @param consistency - A number from 0 to 100 representing the percentage\n *   of files that follow a given convention.\n * @returns The corresponding confidence level:\n *   - `'high'` for consistency ≥ 90\n *   - `'medium'` for consistency ≥ 70 and < 90\n *   - `'low'` for consistency < 70\n */\nexport function confidenceFromConsistency(consistency: number): Confidence {\n  if (consistency >= 90) return 'high';\n  if (consistency >= 70) return 'medium';\n  return 'low';\n}\n","/** Display names for framework identifiers. */\nexport const FRAMEWORK_NAMES: Record<string, string> = {\n  nextjs: 'Next.js',\n  remix: 'Remix',\n  nuxt: 'Nuxt',\n  sveltekit: 'SvelteKit',\n  astro: 'Astro',\n  vite: 'Vite',\n  gatsby: 'Gatsby',\n  express: 'Express',\n  fastify: 'Fastify',\n  hono: 'Hono',\n};\n\n/** Display names for styling libraries. */\nexport const STYLING_NAMES: Record<string, string> = {\n  tailwindcss: 'Tailwind CSS',\n  'css-modules': 'CSS Modules',\n  'styled-components': 'styled-components',\n  emotion: 'Emotion',\n  sass: 'Sass',\n};\n\n/** Display names for notable libraries. */\nexport const LIBRARY_NAMES: Record<string, string> = {\n  'react-query': 'React Query',\n  'tanstack-query': 'TanStack Query',\n  zod: 'Zod',\n  trpc: 'tRPC',\n  prisma: 'Prisma',\n  drizzle: 'Drizzle',\n};\n\n/** Display names for directory roles. */\nexport const ROLE_DESCRIPTIONS: Record<string, string> = {\n  pages: 'Pages / Routes',\n  components: 'Components',\n  hooks: 'Hooks',\n  utils: 'Utilities',\n  types: 'Type definitions',\n  tests: 'Tests',\n  styles: 'Styles',\n  api: 'API routes',\n  config: 'Configuration',\n};\n","export const VERSION = '0.1.0';\n\nexport type { BoundaryRule, BoundaryViolation } from './boundary.js';\nexport type { CheckResult, CheckRule, CheckViolation } from './check-result.js';\nexport type { Confidence, DetectedConvention } from './confidence.js';\nexport { confidenceFromConsistency } from './confidence.js';\nexport type {\n  ConfigConventions,\n  ConfigRules,\n  ConfigStack,\n  ConfigStructure,\n  ConventionValue,\n  ViberailsConfig,\n  WorkspaceConfig,\n} from './config.js';\nexport {\n  FRAMEWORK_NAMES,\n  LIBRARY_NAMES,\n  ROLE_DESCRIPTIONS,\n  STYLING_NAMES,\n} from './display-names.js';\nexport type {\n  ImportEdge,\n  ImportGraph,\n  ImportGraphNode,\n  ImportKind,\n  WorkspacePackage,\n} from './graph.js';\nexport type {\n  CodebaseStatistics,\n  DetectedStack,\n  DetectedStructure,\n  DetectedWorkspace,\n  DirectoryInfo,\n  DirectoryRole,\n  FileStatistic,\n  ScanResult,\n  StackItem,\n} from './scan-result.js';\n"],"mappings":";AAuCO,SAAS,0BAA0B,aAAiC;AACzE,MAAI,eAAe,GAAI,QAAO;AAC9B,MAAI,eAAe,GAAI,QAAO;AAC9B,SAAO;AACT;;;AC1CO,IAAM,kBAA0C;AAAA,EACrD,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,MAAM;AAAA,EACN,WAAW;AAAA,EACX,OAAO;AAAA,EACP,MAAM;AAAA,EACN,QAAQ;AAAA,EACR,SAAS;AAAA,EACT,SAAS;AAAA,EACT,MAAM;AACR;AAGO,IAAM,gBAAwC;AAAA,EACnD,aAAa;AAAA,EACb,eAAe;AAAA,EACf,qBAAqB;AAAA,EACrB,SAAS;AAAA,EACT,MAAM;AACR;AAGO,IAAM,gBAAwC;AAAA,EACnD,eAAe;AAAA,EACf,kBAAkB;AAAA,EAClB,KAAK;AAAA,EACL,MAAM;AAAA,EACN,QAAQ;AAAA,EACR,SAAS;AACX;AAGO,IAAM,oBAA4C;AAAA,EACvD,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,OAAO;AAAA,EACP,OAAO;AAAA,EACP,OAAO;AAAA,EACP,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,KAAK;AAAA,EACL,QAAQ;AACV;;;AC5CO,IAAM,UAAU;","names":[]}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@viberails/types",
+  "version": "0.1.0",
+  "description": "Shared type definitions for viberails",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "biome check src/",
+    "clean": "rm -rf dist"
+  }
+}