@caleuche/core 0.4.0 → 0.5.0

package/README.md

@@ -1,12 +1,28 @@
 # Caleuche Library
 
-This package provides core logic for compiling code samples and generating project files for multiple languages. It is designed to be consumed by the CLI or other tools.
+Caleuche is a template-based code generation library that compiles code samples with dynamic inputs into runnable code files across multiple programming languages. It enables you to create reusable code templates using EJS-style syntax (`<%= %>`) and generate complete, executable projects with language-specific project files and dependency manifests.
+
+The library acts as the core engine for tools like the Caleuche CLI, providing a programmatic API for template compilation, input validation, and multi-language code generation. Whether you're building code snippet generators, documentation systems with runnable examples, or developer tools that need to produce working code samples, Caleuche simplifies the process of transforming templates into fully functional code.
 
 ## Features
 
-- Compile code samples for C#, Go, Java, Python, and JavaScript.
-- Generate language-specific project files (e.g., `Sample.csproj`, `go.mod`, `pom.xml`, `requirements.txt`, `package.json`).
-- Supports template input validation and dependency injection.
+- **Multi-Language Support**: Compile code templates for C#, Go, Java, Python, and JavaScript
+- **EJS-Style Templating**: Use familiar `<%= variable %>` syntax with support for JavaScript expressions and control flow
+- **Project File Generation**: Automatically generate language-specific project files including dependency manifests:
+  - C#: `Sample.csproj`
+  - Go: `go.mod`
+  - Java: `pom.xml`
+  - Python: `requirements.txt`
+  - JavaScript: `package.json`
+- **Rich Input Types**: Define template inputs with strong typing support:
+  - Primitives: `string`, `number`, `boolean`
+  - Complex types: `object`, `array` (with typed items)
+  - Required/optional fields with default values
+- **Template Helper Functions**: Built-in language-specific helpers for common code generation tasks:
+  - Import/using statement generation
+  - Environment variable handling with runtime validation
+- **Metadata Support**: Attach custom tags to samples for categorization and filtering
+- **Input Validation**: Automatic validation of required inputs with clear error messages
 
 ## Installation
 
@@ -24,7 +40,7 @@ Import the main API in your TypeScript/JavaScript project:
 import { compileSample, Sample, CompileOptions, CompileOutput } from "caleuche";
 ```
 
-### Example
+### Basic Example
 
 ```ts
 const sample: Sample = {
@@ -38,36 +54,298 @@ const options: CompileOptions = { project: true };
 
 const output: CompileOutput = compileSample(sample, { name: "World" }, options);
 // output.items will contain the generated files
+// - sample.js: contains compiled code
+// - package.json: contains project metadata and dependencies
+```
+
+### Working with Input Types
+
+Caleuche supports various input types with validation and defaults:
+
+```ts
+const sample: Sample = {
+  template: `
+const config = {
+  name: "<%= name %>",
+  port: <%= port %>,
+  debug: <%= debug %>,
+  features: <%= JSON.stringify(features) %>
+};
+  `,
+  type: "javascript",
+  dependencies: [{ name: "express", version: "^4.18.0" }],
+  input: [
+    { name: "name", type: "string", required: true },
+    { name: "port", type: "number", required: false, default: 3000 },
+    { name: "debug", type: "boolean", required: false, default: false },
+    {
+      name: "features",
+      type: "array",
+      itemsType: "string",
+      required: false,
+      default: ["logging"],
+    },
+  ],
+};
+
+const output = compileSample(
+  sample,
+  {
+    name: "MyApp",
+    port: 8080,
+    features: ["auth", "logging", "metrics"],
+  },
+  { project: true },
+);
+```
+
+### Using Template Helpers
+
+Templates can use language-specific helper functions for common tasks:
+
+```ts
+// Go sample with import management
+const goSample: Sample = {
+  template: `
+package main
+
+<%- go.includes("fmt", "os", { module: "github.com/joho/godotenv", condition: useEnv }) %>
+
+func main() {
+    <%- go.valueOrEnvironment(useEnv, "apiKey", "API_KEY", hardcodedKey) %>
+    fmt.Println(apiKey)
+}
+  `,
+  type: "go",
+  dependencies: [],
+  input: [
+    { name: "useEnv", type: "boolean", required: true },
+    {
+      name: "hardcodedKey",
+      type: "string",
+      required: false,
+      default: "default-key",
+    },
+  ],
+};
+```
+
+### Adding Metadata with Tags
+
+Attach custom metadata to samples for organization and filtering:
+
+```ts
+const sample: Sample = {
+  template: 'print("Hello, <%= name %>!")',
+  type: "python",
+  dependencies: [],
+  input: [{ name: "name", type: "string", required: true }],
+  tags: {
+    category: "basic",
+    difficulty: "beginner",
+    version: "1.0.0",
+  },
+};
+
+const output = compileSample(sample, { name: "World" }, { project: false });
+// Output includes tags.yaml file with metadata
 ```
 
 ### Template Built-ins
 
-For use in authoring templates. All functions described below are ingested by Caleuche when compiling code files.
+Template helper functions are available within templates to generate language-specific boilerplate code. These functions are accessed via the language namespace (e.g., `go.includes()`, `csharp.usings()`).
+
+#### Universal Helpers
+
+Available for all supported languages:
+
+- **`<language>.valueOrEnvironment(useEnvironmentVariable, variableName, environmentVariable, value, indentationLevel?)`**
+
+  Generates code to assign a variable either from an environment variable at runtime (with validation) or from a provided static value.
+
+  - `useEnvironmentVariable` (boolean): If true, generates code to read from environment variable
+  - `variableName` (string): Name of the variable to create
+  - `environmentVariable` (string): Name of the environment variable to read from
+  - `value` (string, optional): Static value to use if not reading from environment
+  - `indentationLevel` (number, optional): Indentation level for generated code (default varies by language)
+
+  **Example:**
+
+  ```ts
+  // In a Go template:
+  <%- go.valueOrEnvironment(true, "apiKey", "API_KEY") %>
+  // Generates:
+  // apiKey := os.Getenv("API_KEY")
+  // if len(apiKey) == 0 {
+  //     fmt.Println("Please set the API_KEY environment variable.")
+  //     os.Exit(1)
+  // }
+  ```
+
+#### Language-Specific Helpers
+
+**Go**
+
+- **`go.includes(...items)`**
 
-#### Universal
+  Generates Go import statements with automatic grouping (standard library vs. external packages).
 
-- `<language>.valueOrEnvironment(useEnvironmentVariable: boolean, variableName: string, environmentVariable: string, value: string)` Generates code to assign a variable from a specified environment variable `environmentVariable` at runtime or from a provided value `value`.
+  - `items`: Rest parameter accepting strings or objects with `{ module: string, condition?: boolean }`
 
-#### Language Specific
-- `go.includes(...items: string | {module: string; condition?: boolean})` Generates go import statement from list of dependencies. Exclude a dependency by setting condition to false.
+  **Example:**
 
-- `csharp.usings(...items: string | {namespace: string; condition?: boolean})` Generates C# using statements from a list of namespaces. Exclude a namespace by setting condition to false.
+  ```ts
+  <%- go.includes("fmt", "os", { module: "github.com/joho/godotenv", condition: needsDotenv }) %>
+  // Generates:
+  // import (
+  //     "fmt"
+  //     "os"
+  //
+  //     "github.com/joho/godotenv"
+  // )
+  ```
+
+**C#**
+
+- **`csharp.usings(...items)`**
+
+  Generates C# using statements.
+
+  - `items`: Rest parameter accepting strings or objects with `{ namespace: string, condition?: boolean }`
+
+  **Example:**
+
+  ```ts
+  <%- csharp.usings("System", "System.IO", { namespace: "System.Net.Http", condition: needsHttp }) %>
+  // Generates:
+  // using System;
+  // using System.IO;
+  // using System.Net.Http;
+  ```
+
+**Java, Python, JavaScript**
+
+These languages have the `valueOrEnvironment` helper available but no additional language-specific helpers at this time.
 
 ## API
 
 ### Types
 
-- `Language`: `"csharp" | "java" | "python" | "go" | "javascript"`
-- `Dependency`: `{ name: string; version: string }`
-- `TemplateInput`: Input parameter definition for templates.
-- `Sample`: Describes a code sample, its language, dependencies, and inputs.
-- `CompileOptions`: `{ project: boolean }`
-- `CompileOutput`: `{ items: Array<{ fileName: string; content: string }> }`
+**`Language`**
+
+```ts
+type Language = "csharp" | "java" | "python" | "go" | "javascript";
+```
+
+**`Dependency`**
+
+```ts
+interface Dependency {
+  name: string;
+  version: string;
+}
+```
+
+**`TemplateInput`**
+
+Defines an input parameter for a template. Supports multiple types:
+
+```ts
+type TemplateInput =
+  | {
+      name: string;
+      type: "string";
+      required: boolean;
+      default?: string;
+    }
+  | {
+      name: string;
+      type: "number";
+      required: boolean;
+      default?: number;
+    }
+  | {
+      name: string;
+      type: "boolean";
+      required: boolean;
+      default?: boolean;
+    }
+  | {
+      name: string;
+      type: "object";
+      required: boolean;
+      default?: Record<string, any>;
+    }
+  | {
+      name: string;
+      type: "array";
+      itemsType: "string" | "number" | "boolean" | "object";
+      required: boolean;
+      default?: Array<string | number | boolean | Record<string, any>>;
+    };
+```
+
+**`Sample`**
+
+Describes a code sample with its template, language, dependencies, inputs, and optional metadata:
+
+```ts
+interface Sample {
+  template: string; // EJS-style template string
+  type: Language; // Target language
+  dependencies: Dependency[]; // Package dependencies
+  input: TemplateInput[]; // Template input definitions
+  tags?: Record<string, any>; // Optional metadata tags
+}
+```
+
+**`CompileOptions`**
+
+```ts
+interface CompileOptions {
+  project: boolean; // If true, generates language-specific project file
+}
+```
+
+**`CompileOutput`**
+
+```ts
+interface CompileOutput {
+  items: Array<{
+    fileName: string; // Generated file name
+    content: string; // File content
+  }>;
+}
+```
 
 ### Functions
 
-- `compileSample(sample, input, options): CompileOutput`
-  Compiles a code sample and returns generated files.
+**`compileSample(sample: Sample, input: Record<string, any>, options: CompileOptions): CompileOutput`**
+
+Compiles a code sample template with provided input data and returns generated files.
+
+- **`sample`**: Sample definition including template, language, dependencies, and input schema
+- **`input`**: Object containing values for template variables (must satisfy required inputs)
+- **`options`**: Compilation options (e.g., whether to generate project files)
+- **Returns**: Object containing array of generated files with names and content
+
+**Example:**
+
+```ts
+const output = compileSample(
+  {
+    template: 'console.log("<%= message %>");',
+    type: "javascript",
+    dependencies: [],
+    input: [{ name: "message", type: "string", required: true }],
+  },
+  { message: "Hello World" },
+  { project: false },
+);
+
+// output.items[0].fileName === "sample.js"
+// output.items[0].content === 'console.log("Hello World");'
+```
 
 ## License
 

package/dist/index.cjs.js

@@ -7658,6 +7658,8 @@ function getProjectFileTemplate(sample) {
                 targetFileName: `requirements.txt`,
                 template: preprocessTemplate(requirementsTxt),
             };
+        case "shell":
+            throw new Error(`Shell language does not support project file generation.`);
         default:
             throw new Error(`Unsupported language: ${language}. Cannot generate project file.`);
     }
@@ -7694,6 +7696,8 @@ function getTargetFileName(sample) {
             return "Sample.java";
         case "python":
             return "sample.py";
+        case "shell":
+            return "sample.sh";
         default:
             throw new Error(`Unsupported language: ${language}. Cannot generate sample file.`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caleuche/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "main": "dist/index.cjs.js",
   "exports": {
     ".": {