docvars 0.3.2 → 0.4.0

package/README.md

@@ -1,25 +1,17 @@
 # docvars
 
-A CLI tool to replace `{{variables}}` in document templates with values from a YAML file.
-
-Supports any text-based files: Markdown, HTML, TXT, and more.
-
-## Installation
+![docvars logo](./logo.jpeg)
 
-```bash
-npm install -g docvars
-```
+[日本語版 README はこちら](./README_ja.md)
 
-Or use with npx:
+A CLI tool to replace `{{variables}}` in document templates with values from a YAML file.
 
-```bash
-npx docvars ./templates ./output
-```
+Supports any text-based files: Markdown, HTML, TXT, and more.
 
 ## Usage
 
 ```bash
-docvars <input> <output> [options]
+npx docvars <input> <output> [options]
 ```
 
 ### Arguments
@@ -37,8 +29,8 @@ docvars <input> <output> [options]
 | `--only`        | `-o`  | `**/*`           | Glob pattern to filter files (e.g. **/*.md)         |
 | `--exclude`     | `-e`  | -                | Glob pattern to exclude specific files              |
 | `--watch`       | `-w`  | `false`          | Watch for file changes and rebuild automatically    |
-| `--rename-from` | `-r`  | -                | Variable name to rename from (use with --rename-to) |
-| `--rename-to`   | `-t`  | -                | Variable name to rename to (use with --rename-from) |
+| `--rename-from` | `-F`  | -                | Variable name to rename from (use with --rename-to) |
+| `--rename-to`   | `-T`  | -                | Variable name to rename to (use with --rename-from) |
 | `--list-vars`   | `-l`  | `false`          | List all variables used in templates                |
 | `--dry-run`     | `-d`  | `false`          | Preview changes without writing files               |
 
@@ -47,29 +39,29 @@ docvars <input> <output> [options]
 ### Basic usage
 
 ```bash
-docvars ./templates ./output
+npx docvars ./templates ./output
 ```
 
 ### Custom variables file
 
 ```bash
-docvars ./templates ./output --vars production.yaml
+npx docvars ./templates ./output --vars production.yaml
 ```
 
 ### Filter files
 
 ```bash
 # Process only markdown files
-docvars ./templates ./output --only "**/*.md"
+npx docvars ./templates ./output --only "**/*.md"
 
 # Process multiple file types
-docvars ./templates ./output --only "**/*.{md,html,txt}"
+npx docvars ./templates ./output --only "**/*.{md,html,txt}"
 
 # Process only files matching pattern
-docvars ./templates ./output --only "api-*.md"
+npx docvars ./templates ./output --only "api-*.md"
 
 # Exclude files matching pattern
-docvars ./templates ./output --exclude "draft-*.md"
+npx docvars ./templates ./output --exclude "draft-*.md"
 ```
 
 By default, all text files are processed (binary files like images are automatically excluded).
@@ -77,7 +69,7 @@ By default, all text files are processed (binary files like images are automatic
 ### Watch mode
 
 ```bash
-docvars ./templates ./output --watch
+npx docvars ./templates ./output --watch
 ```
 
 Output:
@@ -111,26 +103,33 @@ Rename a variable across all template files and the variables YAML file:
 
 ```bash
 # Simple rename
-docvars ./templates ./output --rename-from "name" --rename-to "title"
+npx docvars ./templates ./output --rename-from "name" --rename-to "title"
 
 # Rename nested variable
-docvars ./templates ./output --rename-from "database.host" --rename-to "db.host"
+npx docvars ./templates ./output --rename-from "database.host" --rename-to "db.host"
+
+# Prefix rename - renames all variables with matching prefix
+# {{database}} → {{db}}
+# {{database.host}} → {{db.host}}
+# {{database.port}} → {{db.port}}
+npx docvars ./templates ./output --rename-from "database" --rename-to "db"
 ```
 
 Output:
 
 ```
 ✏️  Rename complete
-   database.host → db.host
+   database → db
 
 ┌────────────────┬───────────┐
 │ File           │ Status    │
 ├────────────────┼───────────┤
 │ variables.yaml │ ✓ updated │
 │ README.md      │ ✓ updated │
+│ config.md      │ ✓ updated │
 └────────────────┴───────────┘
 
-Updated: 2 file(s)
+Updated: 3 file(s)
 ```
 
 ### List variables
@@ -138,7 +137,7 @@ Updated: 2 file(s)
 Show all variables used in templates and their status:
 
 ```bash
-docvars ./templates ./output --list-vars
+npx docvars ./templates ./output --list-vars
 ```
 
 Output:
@@ -165,7 +164,7 @@ Summary: 1 defined · 1 undefined · 1 unused
 Preview what files would be created or updated without actually writing them:
 
 ```bash
-docvars ./templates ./output --dry-run
+npx docvars ./templates ./output --dry-run
 ```
 
 Output:
@@ -237,6 +236,36 @@ database:
 Database: localhost:5432
 ```
 
+### Array Variables
+
+You can use arrays in your variables file and access them with index notation:
+
+**Template:**
+```markdown
+## Features
+
+1. {{features.0}}
+2. {{features.1}}
+3. {{features.2}}
+```
+
+**Variables (variables.yaml):**
+```yaml
+features:
+  - User authentication
+  - Data analytics
+  - API integration
+```
+
+**Output:**
+```markdown
+## Features
+
+1. User authentication
+2. Data analytics
+3. API integration
+```
+
 ## Error Handling
 
 | Case                        | Behavior                                            |

package/dist/application/use-cases/list-variables.d.ts

@@ -6,11 +6,16 @@ export interface ListVariablesOptions {
 }
 export interface VariableUsage {
     name: string;
+    value?: string;
     files: string[];
     isDefined: boolean;
 }
+export interface UnusedVariable {
+    name: string;
+    value: string;
+}
 export interface ListVariablesResult {
     variables: VariableUsage[];
-    unusedVariables: string[];
+    unusedVariables: UnusedVariable[];
 }
 export declare function listVariables(options: ListVariablesOptions): Promise<ListVariablesResult>;

package/dist/application/use-cases/list-variables.js

@@ -34,6 +34,7 @@ export async function listVariables(options) {
     for (const [name, files] of variableUsageMap) {
         variables.push({
             name,
+            value: definedVars[name],
             files: Array.from(files).sort(),
             isDefined: definedVarNames.has(name),
         });
@@ -43,6 +44,7 @@ export async function listVariables(options) {
     // Find unused variables (defined but not used)
     const unusedVariables = Array.from(definedVarNames)
         .filter((name) => !usedVarNames.has(name))
-        .sort();
+        .sort()
+        .map((name) => ({ name, value: definedVars[name] }));
     return { variables, unusedVariables };
 }

package/dist/application/use-cases/rename-variable.js

@@ -16,7 +16,8 @@ export async function renameVariable(options) {
     };
     // Rename in template files
     const templateFiles = await scanTemplates(input, { only, exclude });
-    const pattern = new RegExp(`\\{\\{${escapeRegex(from)}(\\}\\}|\\|)`, "g");
+    // Match exact variable or prefix (e.g., "database" matches "{{database}}" and "{{database.host}}")
+    const pattern = new RegExp(`\\{\\{${escapeRegex(from)}(\\.|\\}\\}|\\|)`, "g");
     for (const file of templateFiles) {
         const content = readFileSync(file, "utf-8");
         const newContent = content.replace(pattern, `{{${to}$1`);

package/dist/domain/value-objects/variables.d.ts

@@ -2,8 +2,8 @@ import { z } from "zod";
 declare const PrimitiveValueSchema: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
 type NestedValue = z.infer<typeof PrimitiveValueSchema> | {
     [key: string]: NestedValue;
-};
+} | NestedValue[];
 export declare const VariablesSchema: z.ZodRecord<z.ZodString, z.ZodType<NestedValue, z.ZodTypeDef, NestedValue>>;
 export type Variables = Record<string, string>;
-export declare function flattenVariables(obj: Record<string, NestedValue>, prefix?: string): Variables;
+export declare function flattenVariables(obj: Record<string, NestedValue> | NestedValue[], prefix?: string): Variables;
 export {};

package/dist/domain/value-objects/variables.js

@@ -1,16 +1,30 @@
 import { z } from "zod";
 const PrimitiveValueSchema = z.union([z.string(), z.number(), z.boolean()]);
-const NestedValueSchema = z.lazy(() => z.union([PrimitiveValueSchema, z.record(z.string(), NestedValueSchema)]));
+const NestedValueSchema = z.lazy(() => z.union([PrimitiveValueSchema, z.array(NestedValueSchema), z.record(z.string(), NestedValueSchema)]));
 export const VariablesSchema = z.record(z.string(), NestedValueSchema);
 export function flattenVariables(obj, prefix = "") {
     const result = {};
-    for (const [key, value] of Object.entries(obj)) {
-        const fullKey = prefix ? `${prefix}.${key}` : key;
-        if (typeof value === "object" && value !== null) {
-            Object.assign(result, flattenVariables(value, fullKey));
+    if (Array.isArray(obj)) {
+        for (let i = 0; i < obj.length; i++) {
+            const value = obj[i];
+            const fullKey = prefix ? `${prefix}.${i}` : String(i);
+            if (typeof value === "object" && value !== null) {
+                Object.assign(result, flattenVariables(value, fullKey));
+            }
+            else {
+                result[fullKey] = String(value);
+            }
         }
-        else {
-            result[fullKey] = String(value);
+    }
+    else {
+        for (const [key, value] of Object.entries(obj)) {
+            const fullKey = prefix ? `${prefix}.${key}` : key;
+            if (typeof value === "object" && value !== null) {
+                Object.assign(result, flattenVariables(value, fullKey));
+            }
+            else {
+                result[fullKey] = String(value);
+            }
         }
     }
     return result;

package/dist/presentation/cli/commands/main.js

@@ -3,6 +3,11 @@ import { resolve } from "node:path";
 import pc from "picocolors";
 import Table from "cli-table3";
 import { watch } from "chokidar";
+function truncate(str, maxLength) {
+    if (str.length <= maxLength)
+        return str;
+    return str.slice(0, maxLength - 1) + "…";
+}
 import { processTemplates } from "../../../application/use-cases/process-templates.js";
 import { renameVariable } from "../../../application/use-cases/rename-variable.js";
 import { listVariables } from "../../../application/use-cases/list-variables.js";
@@ -111,12 +116,12 @@ export const mainCommand = defineCommand({
         },
         "rename-from": {
             type: "string",
-            alias: "r",
+            alias: "F",
             description: "Variable name to rename from (use with --rename-to)",
         },
         "rename-to": {
             type: "string",
-            alias: "t",
+            alias: "T",
             description: "Variable name to rename to (use with --rename-from)",
         },
         "list-vars": {
@@ -212,22 +217,29 @@ export const mainCommand = defineCommand({
                 }
                 if (result.variables.length > 0) {
                     const table = new Table({
-                        head: [pc.bold("Variable"), pc.bold("Status"), pc.bold("Used in")],
+                        head: [pc.bold("Variable"), pc.bold("Value"), pc.bold("Used in")],
                         style: { head: [], border: [] },
                         wordWrap: true,
+                        colWidths: [null, 30, null],
                     });
                     for (const v of result.variables) {
-                        const status = v.isDefined ? pc.green("✓ defined") : pc.red("✗ undefined");
+                        const value = v.isDefined ? pc.green(truncate(v.value || "", 25)) : pc.red("✗ undefined");
                         const files = v.files.map((f) => pc.gray(f)).join("\n");
-                        table.push([v.name, status, files]);
+                        table.push([v.name, value, files]);
                     }
                     console.log(table.toString());
                 }
                 if (result.unusedVariables.length > 0) {
                     console.log(pc.bold(pc.yellow("\n⚠ Unused variables (defined but not used):\n")));
-                    for (const name of result.unusedVariables) {
-                        console.log(pc.gray(`  ${name}`));
+                    const unusedTable = new Table({
+                        head: [pc.bold("Variable"), pc.bold("Value")],
+                        style: { head: [], border: [] },
+                        colWidths: [null, 40],
+                    });
+                    for (const v of result.unusedVariables) {
+                        unusedTable.push([pc.gray(v.name), pc.gray(truncate(v.value, 35))]);
                     }
+                    console.log(unusedTable.toString());
                 }
                 console.log();
                 const defined = result.variables.filter((v) => v.isDefined).length;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docvars",
   "author": "Shunta Toda",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Replace {{variables}} in document templates with YAML values",
   "type": "module",
   "main": "./dist/application/use-cases/process-templates.js",