feat(cli): add --verbose flag and logger.debug; document Babel ESM interop (#47)

- Add --verbose CLI flag (also activated by REACT_SPEC_GEN_DEBUG env var)

- Implement logger.debug() that no-ops unless verbose mode is on

- Trace key pipeline events from runGenerate

- Document the @babel/traverse default-export ESM interop in component.ts and props.ts

- Add .gitattributes (eol=lf) to stop CRLF/LF churn between Windows dev and CI

- Update README flags table

Author: matieydjato

.gitattributes

@@ -0,0 +1,13 @@
+# Force LF line endings for text files across all platforms.
+# Prevents EOL churn between Windows (autocrlf=true) and CI Linux runners.
+* text=auto eol=lf
+
+# Binary assets — never normalize.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.svg text eol=lf
+*.woff binary
+*.woff2 binary

README.md

@@ -55,6 +55,7 @@ Expected output:
 |---|---|
 | `-y`, `--yes` | Skip overwrite prompts |
 | `--ai` | Enhance inferred values and edge cases using an AI provider (optional) |
+| `--verbose` | Print debug traces (also enabled by `REACT_SPEC_GEN_DEBUG=1`) |
 
 The CLI prints a verification checklist after writing — review inferred prop values, assertion meaningfulness, and event-handler coverage before committing.
 

src/cli/commands/generate.ts

@@ -15,10 +15,14 @@ export interface GenerateOptions {
 
 export async function runGenerate(file: string, opts: GenerateOptions): Promise<number> {
   try {
+    logger.debug(`runGenerate: file=${file}, ai=${opts.ai}, yes=${opts.yes}`);
     const enhancer = opts.ai ? withSpinner(buildEnhancer(new MockProvider())) : undefined;
 
     const result = await run(file, { enhancer });
     const { testFilePath, testSource, storyFilePath, storySource } = result.outputs;
+    logger.debug(
+      `pipeline result: component=${result.model.name}, props=${result.model.props.length}, warnings=${result.model.warnings.length}`,
+    );
 
     for (const w of result.model.warnings) logger.warn(w);
 

src/cli/index.ts

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import pkg from "../../package.json" with { type: "json" };
+import { logger } from "../utils/logger.js";
 import { runGenerate } from "./commands/generate.js";
 
 export function buildProgram(): Command {
@@ -12,7 +13,9 @@ export function buildProgram(): Command {
     .argument("<file>", "Path to a .tsx or .jsx component file")
     .option("--ai", "Enable AI-powered enhancement (mock provider for now)", false)
     .option("-y, --yes", "Overwrite existing files without prompting", false)
-    .action(async (file: string, opts: { ai: boolean; yes: boolean }) => {
+    .option("--verbose", "Print debug traces (also enabled by REACT_SPEC_GEN_DEBUG=1)", false)
+    .action(async (file: string, opts: { ai: boolean; yes: boolean; verbose: boolean }) => {
+      logger.setVerbose(opts.verbose);
       const code = await runGenerate(file, opts);
       process.exit(code);
     });

src/core/analyzer/component.ts

@@ -4,7 +4,9 @@ import * as t from "@babel/types";
 import { AnalysisError } from "../errors.js";
 import type { ParsedSource } from "./parser.js";
 
-// @babel/traverse default export interop under ESM.
+// @babel/traverse ships as CJS but exposes its function as `module.exports.default`
+// when consumed from ESM, so we unwrap the default export at runtime. The
+// `?? _traverse` fallback covers older bundlers that already give us the function.
 const traverse = (_traverse as unknown as { default: typeof _traverse }).default ?? _traverse;
 
 export interface ComponentInfo {

src/core/analyzer/props.ts

@@ -4,6 +4,9 @@ import type { PropDescriptor, PropKind } from "../model.js";
 import type { ComponentInfo } from "./component.js";
 import type { ParsedSource } from "./parser.js";
 
+// @babel/traverse ships as CJS but exposes its function as `module.exports.default`
+// when consumed from ESM, so we unwrap the default export at runtime. The
+// `?? _traverse` fallback covers older bundlers that already give us the function.
 const traverse = (_traverse as unknown as { default: typeof _traverse }).default ?? _traverse;
 
 const EVENT_HANDLER_RE = /^on[A-Z]/;

src/utils/logger.ts

@@ -1,6 +1,19 @@
 import chalk from "chalk";
 
+/**
+ * Verbose mode: enabled by --verbose CLI flag or by setting the
+ * REACT_SPEC_GEN_DEBUG environment variable to a non-empty value.
+ * When disabled, `logger.debug()` is a no-op.
+ */
+let verboseEnabled = Boolean(process.env.REACT_SPEC_GEN_DEBUG);
+
 export const logger = {
+  setVerbose(enabled: boolean): void {
+    verboseEnabled = enabled || Boolean(process.env.REACT_SPEC_GEN_DEBUG);
+  },
+  isVerbose(): boolean {
+    return verboseEnabled;
+  },
   info(msg: string): void {
     console.log(msg);
   },
@@ -16,4 +29,7 @@ export const logger = {
   dim(msg: string): void {
     console.log(chalk.dim(msg));
   },
+  debug(msg: string): void {
+    if (verboseEnabled) console.log(chalk.gray("[debug] ") + msg);
+  },
 };