configenvy 0.1.4 → 0.1.5

package/dist/index.d.ts

@@ -1,20 +1,26 @@
 #!/usr/bin/env node
-import { writeFile } from 'node:fs/promises';
+import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { Command } from 'commander';
-import { buildMarkdownTable, explainVariable, scanProject, toJson, toSarif, Diagnostic } from '@configenvy/core';
+import { buildMarkdownTable, explainVariable, scanProject, toJson, toSarif, ScanResult, Diagnostic } from '@configenvy/core';
 
 type DoctorOptions = {
     format?: "text" | "json" | "sarif";
     strict?: boolean;
     ci?: boolean;
 };
+type InitOptions = {
+    dryRun?: boolean;
+    envExample?: boolean;
+    force?: boolean;
+};
 type CliDependencies = {
     buildMarkdownTable: typeof buildMarkdownTable;
     error: (...values: unknown[]) => void;
     exit: (code: number) => never | void;
     explainVariable: typeof explainVariable;
     log: (...values: unknown[]) => void;
+    readFile: typeof readFile;
     resolvePath: typeof resolve;
     scanProject: typeof scanProject;
     toJson: typeof toJson;
@@ -22,11 +28,24 @@ type CliDependencies = {
     writeFile: typeof writeFile;
 };
 declare function createProgram(dependencies?: CliDependencies): Command;
+type InitFile = {
+    content: string;
+    path: string;
+};
+declare const tableBlockStart = "<!-- configenvy:start -->";
+declare const tableBlockEnd = "<!-- configenvy:end -->";
 declare function runCli(argv: string[], dependencies?: CliDependencies): Promise<void>;
 declare function runDoctor(projectPath: string, options: DoctorOptions, dependencies?: CliDependencies): Promise<void>;
-declare function runInit(projectPath: string, dependencies?: CliDependencies): Promise<void>;
+declare function runInit(projectPath: string, options?: InitOptions, dependencies?: CliDependencies): Promise<void>;
+declare function buildInitFiles(rootDir: string, result: ScanResult, includeEnvExample: boolean, resolvePath?: typeof resolve, existingEnvExample?: string): InitFile[];
+declare function runTableUpdate(rootDir: string, table: string, options: {
+    dryRun?: boolean;
+    force?: boolean;
+    update: string;
+}, dependencies?: CliDependencies): Promise<void>;
+declare function updateMarkdownTableBlock(markdown: string, table: string, force: boolean): string;
 declare function resolveOutputPath(projectPath: string, outputPath: string, resolvePath?: typeof resolve): string;
 declare function printHumanReport(diagnostics: Diagnostic[], log?: (...values: unknown[]) => void): void;
 declare function printGitHubAnnotations(diagnostics: Diagnostic[], log?: (...values: unknown[]) => void): void;
 
-export { type CliDependencies, createProgram, printGitHubAnnotations, printHumanReport, resolveOutputPath, runCli, runDoctor, runInit };
+export { type CliDependencies, buildInitFiles, createProgram, printGitHubAnnotations, printHumanReport, resolveOutputPath, runCli, runDoctor, runInit, runTableUpdate, tableBlockEnd, tableBlockStart, updateMarkdownTableBlock };

package/dist/index.js

@@ -1,17 +1,24 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { writeFile } from "fs/promises";
+import { readFile, writeFile } from "fs/promises";
 import { isAbsolute, resolve } from "path";
 import { pathToFileURL } from "url";
 import { Command } from "commander";
-import { buildMarkdownTable, explainVariable, scanProject, toJson, toSarif } from "@configenvy/core";
+import {
+  buildMarkdownTable,
+  explainVariable,
+  scanProject,
+  toJson,
+  toSarif
+} from "@configenvy/core";
 var defaultDependencies = {
   buildMarkdownTable,
   error: console.error,
   exit: process.exit,
   explainVariable,
   log: console.log,
+  readFile,
   resolvePath: resolve,
   scanProject,
   toJson,
@@ -27,19 +34,21 @@ function createProgram(dependencies = defaultDependencies) {
   program.command("check").argument("[path]", "project directory", ".").option("--ci", "fail on warnings and errors").option("--format <format>", "output format: text, json, or sarif", "text").action(async (projectPath, options) => {
     await runDoctor(projectPath, { ...options, strict: Boolean(options.ci), ci: Boolean(options.ci) }, dependencies);
   });
-  program.command("table").argument("[path]", "project directory", ".").option("--out <file>", "write markdown table to a file").action(async (projectPath, options) => {
+  program.command("table").argument("[path]", "project directory", ".").option("--out <file>", "write markdown table to a file").option("--update <file>", "replace a marked configenvy table block in a markdown file").option("--force", "append a configenvy table block when --update target has no marked block").option("--dry-run", "print the updated markdown instead of writing it").action(async (projectPath, options) => {
     const rootDir = dependencies.resolvePath(projectPath);
     const result = await dependencies.scanProject({ rootDir });
     const table = dependencies.buildMarkdownTable(result);
-    if (options.out) {
+    if (options.update) {
+      await runTableUpdate(rootDir, table, { ...options, update: options.update }, dependencies);
+    } else if (options.out) {
       await dependencies.writeFile(resolveOutputPath(rootDir, options.out, dependencies.resolvePath), `${table}
 `, "utf8");
     } else {
       dependencies.log(table);
     }
   });
-  program.command("init").argument("[path]", "project directory", ".").description("create a starter configenvy.config.json file").action(async (projectPath) => {
-    await runInit(projectPath, dependencies);
+  program.command("init").argument("[path]", "project directory", ".").description("create starter configenvy files").option("--dry-run", "print planned files instead of writing them").option("--env-example", "also create a .env.example draft from detected variables").option("--force", "overwrite generated files if they already exist").action(async (projectPath, options) => {
+    await runInit(projectPath, options, dependencies);
   });
   program.command("explain").argument("<variable>", "environment variable name").argument("[path]", "project directory", ".").action(async (variable, projectPath) => {
     const result = await dependencies.scanProject({ rootDir: dependencies.resolvePath(projectPath) });
@@ -53,6 +62,8 @@ var starterConfig = {
   ignore: ["NODE_ENV"],
   docs: ["README.md", "docs"]
 };
+var tableBlockStart = "<!-- configenvy:start -->";
+var tableBlockEnd = "<!-- configenvy:end -->";
 async function runCli(argv, dependencies = defaultDependencies) {
   const program = createProgram(dependencies);
   await program.parseAsync(argv);
@@ -77,22 +88,138 @@ async function runDoctor(projectPath, options, dependencies = defaultDependencie
   if (hasError || options.ci && hasWarning) dependencies.exit(2);
   if (hasWarning) dependencies.exit(1);
 }
-async function runInit(projectPath, dependencies = defaultDependencies) {
+async function runInit(projectPath, options = {}, dependencies = defaultDependencies) {
   const rootDir = dependencies.resolvePath(projectPath);
-  const configPath = dependencies.resolvePath(rootDir, "configenvy.config.json");
-  const content = `${JSON.stringify(starterConfig, null, 2)}
-`;
+  const result = await dependencies.scanProject({ rootDir });
+  const existingEnvExample = options.envExample && options.force ? await readOptionalText(dependencies.resolvePath(rootDir, ".env.example"), dependencies) : void 0;
+  const files = buildInitFiles(rootDir, result, Boolean(options.envExample), dependencies.resolvePath, existingEnvExample);
+  if (options.dryRun) {
+    for (const file of files) {
+      dependencies.log(`Would write ${file.path}`);
+      dependencies.log(file.content.trimEnd());
+    }
+    return;
+  }
+  if (!options.force && !await ensureInitTargetsDoNotExist(files, dependencies)) {
+    return;
+  }
+  const flag = options.force ? "w" : "wx";
+  for (const file of files) {
+    try {
+      await dependencies.writeFile(file.path, file.content, { encoding: "utf8", flag });
+    } catch (error) {
+      if (isNodeError(error) && error.code === "EEXIST") {
+        dependencies.error(`${file.path} already exists. Re-run with --force to overwrite.`);
+        dependencies.exit(1);
+        return;
+      }
+      throw error;
+    }
+    dependencies.log(`Created ${file.path}`);
+  }
+}
+function buildInitFiles(rootDir, result, includeEnvExample, resolvePath = resolve, existingEnvExample) {
+  const required = detectedRuntimeVariables(result);
+  const config = {
+    ...starterConfig,
+    required
+  };
+  const files = [
+    {
+      path: resolvePath(rootDir, "configenvy.config.json"),
+      content: `${JSON.stringify(config, null, 2)}
+`
+    }
+  ];
+  if (includeEnvExample) {
+    files.push({
+      path: resolvePath(rootDir, ".env.example"),
+      content: buildEnvExampleDraft(result, existingEnvExample)
+    });
+  }
+  return files;
+}
+async function ensureInitTargetsDoNotExist(files, dependencies) {
+  for (const file of files) {
+    const existing = await readOptionalText(file.path, dependencies);
+    if (existing !== void 0) {
+      dependencies.error(`${file.path} already exists. Re-run with --force to overwrite.`);
+      dependencies.exit(1);
+      return false;
+    }
+  }
+  return true;
+}
+async function readOptionalText(path, dependencies) {
   try {
-    await dependencies.writeFile(configPath, content, { encoding: "utf8", flag: "wx" });
+    return String(await dependencies.readFile(path, "utf8"));
   } catch (error) {
-    if (isNodeError(error) && error.code === "EEXIST") {
-      dependencies.error("configenvy.config.json already exists.");
-      dependencies.exit(1);
-      return;
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return void 0;
     }
     throw error;
   }
-  dependencies.log(`Created ${configPath}`);
+}
+function detectedRuntimeVariables(result) {
+  const runtimeKinds = /* @__PURE__ */ new Set(["code", "ci", "config"]);
+  return [...new Set(result.references.filter((reference) => runtimeKinds.has(reference.kind)).map((reference) => reference.name))].sort();
+}
+function buildEnvExampleDraft(result, existingContent) {
+  const runtimeVars = detectedRuntimeVariables(result);
+  if (existingContent !== void 0) {
+    const existingVars = extractEnvExampleNames(existingContent);
+    const missingVars = runtimeVars.filter((variable) => !existingVars.has(variable));
+    if (missingVars.length === 0) {
+      return existingContent.endsWith("\n") ? existingContent : `${existingContent}
+`;
+    }
+    return [
+      existingContent.trimEnd(),
+      "# Added by configenvy init",
+      ...missingVars.map((variable) => `${variable}=`)
+    ].filter(Boolean).join("\n") + "\n";
+  }
+  const lines = ["# Generated by configenvy init"];
+  for (const variable of runtimeVars) {
+    lines.push(`${variable}=`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function extractEnvExampleNames(content) {
+  const names = /* @__PURE__ */ new Set();
+  for (const line of content.split(/\r?\n/)) {
+    const match = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+    if (match?.[1]) {
+      names.add(match[1]);
+    }
+  }
+  return names;
+}
+async function runTableUpdate(rootDir, table, options, dependencies = defaultDependencies) {
+  const targetPath = resolveOutputPath(rootDir, options.update, dependencies.resolvePath);
+  const current = await dependencies.readFile(targetPath, "utf8");
+  const updated = updateMarkdownTableBlock(current, table, Boolean(options.force));
+  if (options.dryRun) {
+    dependencies.log(updated);
+    return;
+  }
+  await dependencies.writeFile(targetPath, updated, "utf8");
+}
+function updateMarkdownTableBlock(markdown, table, force) {
+  const block = `${tableBlockStart}
+${table}
+${tableBlockEnd}`;
+  const blockPattern = new RegExp(`${escapeRegExp(tableBlockStart)}[\\s\\S]*?${escapeRegExp(tableBlockEnd)}`);
+  if (blockPattern.test(markdown)) {
+    return markdown.replace(blockPattern, block);
+  }
+  if (force) {
+    const separator = markdown.endsWith("\n") ? "\n" : "\n\n";
+    return `${markdown}${separator}${block}
+`;
+  }
+  throw new Error(`No configenvy table block found. Add ${tableBlockStart} and ${tableBlockEnd}, or rerun with --force.`);
 }
 function resolveOutputPath(projectPath, outputPath, resolvePath = resolve) {
   if (isAbsolute(outputPath)) return outputPath;
@@ -131,6 +258,9 @@ function escapeAnnotationProperty(value) {
 function escapeAnnotationMessage(value) {
   return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
 }
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function isNodeError(error) {
   return error instanceof Error && "code" in error;
 }
@@ -142,11 +272,16 @@ if (invokedPath && import.meta.url === pathToFileURL(invokedPath).href) {
   });
 }
 export {
+  buildInitFiles,
   createProgram,
   printGitHubAnnotations,
   printHumanReport,
   resolveOutputPath,
   runCli,
   runDoctor,
-  runInit
+  runInit,
+  runTableUpdate,
+  tableBlockEnd,
+  tableBlockStart,
+  updateMarkdownTableBlock
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configenvy",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Find missing, unused, undocumented, and risky environment variables before setup breaks.",
   "type": "module",
   "engines": {
@@ -35,7 +35,7 @@
     "build": "tsup src/index.ts --format esm --dts --clean"
   },
   "dependencies": {
-    "@configenvy/core": "0.1.4",
+    "@configenvy/core": "0.1.5",
     "commander": "^12.1.0"
   },
   "keywords": [

package/src/index.ts

@@ -1,9 +1,17 @@
 #!/usr/bin/env node
-import { writeFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
 import { isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { Command } from "commander";
-import { buildMarkdownTable, explainVariable, scanProject, toJson, toSarif, type Diagnostic } from "@configenvy/core";
+import {
+  buildMarkdownTable,
+  explainVariable,
+  scanProject,
+  toJson,
+  toSarif,
+  type Diagnostic,
+  type ScanResult
+} from "@configenvy/core";
 
 type DoctorOptions = {
   format?: "text" | "json" | "sarif";
@@ -11,12 +19,19 @@ type DoctorOptions = {
   ci?: boolean;
 };
 
+type InitOptions = {
+  dryRun?: boolean;
+  envExample?: boolean;
+  force?: boolean;
+};
+
 export type CliDependencies = {
   buildMarkdownTable: typeof buildMarkdownTable;
   error: (...values: unknown[]) => void;
   exit: (code: number) => never | void;
   explainVariable: typeof explainVariable;
   log: (...values: unknown[]) => void;
+  readFile: typeof readFile;
   resolvePath: typeof resolve;
   scanProject: typeof scanProject;
   toJson: typeof toJson;
@@ -30,6 +45,7 @@ const defaultDependencies: CliDependencies = {
   exit: process.exit,
   explainVariable,
   log: console.log,
+  readFile,
   resolvePath: resolve,
   scanProject,
   toJson,
@@ -67,11 +83,16 @@ export function createProgram(dependencies: CliDependencies = defaultDependencie
     .command("table")
     .argument("[path]", "project directory", ".")
     .option("--out <file>", "write markdown table to a file")
-    .action(async (projectPath: string, options: { out?: string }) => {
+    .option("--update <file>", "replace a marked configenvy table block in a markdown file")
+    .option("--force", "append a configenvy table block when --update target has no marked block")
+    .option("--dry-run", "print the updated markdown instead of writing it")
+    .action(async (projectPath: string, options: { dryRun?: boolean; force?: boolean; out?: string; update?: string }) => {
       const rootDir = dependencies.resolvePath(projectPath);
       const result = await dependencies.scanProject({ rootDir });
       const table = dependencies.buildMarkdownTable(result);
-      if (options.out) {
+      if (options.update) {
+        await runTableUpdate(rootDir, table, { ...options, update: options.update }, dependencies);
+      } else if (options.out) {
         await dependencies.writeFile(resolveOutputPath(rootDir, options.out, dependencies.resolvePath), `${table}\n`, "utf8");
       } else {
         dependencies.log(table);
@@ -81,9 +102,12 @@ export function createProgram(dependencies: CliDependencies = defaultDependencie
   program
     .command("init")
     .argument("[path]", "project directory", ".")
-    .description("create a starter configenvy.config.json file")
-    .action(async (projectPath: string) => {
-      await runInit(projectPath, dependencies);
+    .description("create starter configenvy files")
+    .option("--dry-run", "print planned files instead of writing them")
+    .option("--env-example", "also create a .env.example draft from detected variables")
+    .option("--force", "overwrite generated files if they already exist")
+    .action(async (projectPath: string, options: InitOptions) => {
+      await runInit(projectPath, options, dependencies);
     });
 
   program
@@ -105,6 +129,14 @@ const starterConfig = {
   docs: ["README.md", "docs"]
 };
 
+type InitFile = {
+  content: string;
+  path: string;
+};
+
+export const tableBlockStart = "<!-- configenvy:start -->";
+export const tableBlockEnd = "<!-- configenvy:end -->";
+
 export async function runCli(argv: string[], dependencies: CliDependencies = defaultDependencies): Promise<void> {
   const program = createProgram(dependencies);
   await program.parseAsync(argv);
@@ -139,24 +171,170 @@ export async function runDoctor(
 
 export async function runInit(
   projectPath: string,
+  options: InitOptions = {},
   dependencies: CliDependencies = defaultDependencies
 ): Promise<void> {
   const rootDir = dependencies.resolvePath(projectPath);
-  const configPath = dependencies.resolvePath(rootDir, "configenvy.config.json");
-  const content = `${JSON.stringify(starterConfig, null, 2)}\n`;
+  const result = await dependencies.scanProject({ rootDir });
+  const existingEnvExample = options.envExample && options.force
+    ? await readOptionalText(dependencies.resolvePath(rootDir, ".env.example"), dependencies)
+    : undefined;
+  const files = buildInitFiles(rootDir, result, Boolean(options.envExample), dependencies.resolvePath, existingEnvExample);
+
+  if (options.dryRun) {
+    for (const file of files) {
+      dependencies.log(`Would write ${file.path}`);
+      dependencies.log(file.content.trimEnd());
+    }
+    return;
+  }
+
+  if (!options.force && !(await ensureInitTargetsDoNotExist(files, dependencies))) {
+    return;
+  }
 
+  const flag = options.force ? "w" : "wx";
+  for (const file of files) {
+    try {
+      await dependencies.writeFile(file.path, file.content, { encoding: "utf8", flag });
+    } catch (error) {
+      if (isNodeError(error) && error.code === "EEXIST") {
+        dependencies.error(`${file.path} already exists. Re-run with --force to overwrite.`);
+        dependencies.exit(1);
+        return;
+      }
+      throw error;
+    }
+
+    dependencies.log(`Created ${file.path}`);
+  }
+}
+
+export function buildInitFiles(
+  rootDir: string,
+  result: ScanResult,
+  includeEnvExample: boolean,
+  resolvePath: typeof resolve = resolve,
+  existingEnvExample?: string
+): InitFile[] {
+  const required = detectedRuntimeVariables(result);
+  const config = {
+    ...starterConfig,
+    required
+  };
+  const files: InitFile[] = [
+    {
+      path: resolvePath(rootDir, "configenvy.config.json"),
+      content: `${JSON.stringify(config, null, 2)}\n`
+    }
+  ];
+
+  if (includeEnvExample) {
+    files.push({
+      path: resolvePath(rootDir, ".env.example"),
+      content: buildEnvExampleDraft(result, existingEnvExample)
+    });
+  }
+
+  return files;
+}
+
+async function ensureInitTargetsDoNotExist(files: InitFile[], dependencies: CliDependencies): Promise<boolean> {
+  for (const file of files) {
+    const existing = await readOptionalText(file.path, dependencies);
+    if (existing !== undefined) {
+      dependencies.error(`${file.path} already exists. Re-run with --force to overwrite.`);
+      dependencies.exit(1);
+      return false;
+    }
+  }
+  return true;
+}
+
+async function readOptionalText(path: string, dependencies: CliDependencies): Promise<string | undefined> {
   try {
-    await dependencies.writeFile(configPath, content, { encoding: "utf8", flag: "wx" });
+    return String(await dependencies.readFile(path, "utf8"));
   } catch (error) {
-    if (isNodeError(error) && error.code === "EEXIST") {
-      dependencies.error("configenvy.config.json already exists.");
-      dependencies.exit(1);
-      return;
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return undefined;
     }
     throw error;
   }
+}
 
-  dependencies.log(`Created ${configPath}`);
+function detectedRuntimeVariables(result: ScanResult): string[] {
+  const runtimeKinds = new Set(["code", "ci", "config"]);
+  return [...new Set(result.references.filter((reference) => runtimeKinds.has(reference.kind)).map((reference) => reference.name))].sort();
+}
+
+function buildEnvExampleDraft(result: ScanResult, existingContent?: string): string {
+  const runtimeVars = detectedRuntimeVariables(result);
+  if (existingContent !== undefined) {
+    const existingVars = extractEnvExampleNames(existingContent);
+    const missingVars = runtimeVars.filter((variable) => !existingVars.has(variable));
+    if (missingVars.length === 0) {
+      return existingContent.endsWith("\n") ? existingContent : `${existingContent}\n`;
+    }
+
+    return [
+      existingContent.trimEnd(),
+      "# Added by configenvy init",
+      ...missingVars.map((variable) => `${variable}=`)
+    ].filter(Boolean).join("\n") + "\n";
+  }
+
+  const lines = ["# Generated by configenvy init"];
+
+  for (const variable of runtimeVars) {
+    lines.push(`${variable}=`);
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+function extractEnvExampleNames(content: string): Set<string> {
+  const names = new Set<string>();
+  for (const line of content.split(/\r?\n/)) {
+    const match = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+    if (match?.[1]) {
+      names.add(match[1]);
+    }
+  }
+  return names;
+}
+
+export async function runTableUpdate(
+  rootDir: string,
+  table: string,
+  options: { dryRun?: boolean; force?: boolean; update: string },
+  dependencies: CliDependencies = defaultDependencies
+): Promise<void> {
+  const targetPath = resolveOutputPath(rootDir, options.update, dependencies.resolvePath);
+  const current = await dependencies.readFile(targetPath, "utf8");
+  const updated = updateMarkdownTableBlock(current, table, Boolean(options.force));
+
+  if (options.dryRun) {
+    dependencies.log(updated);
+    return;
+  }
+
+  await dependencies.writeFile(targetPath, updated, "utf8");
+}
+
+export function updateMarkdownTableBlock(markdown: string, table: string, force: boolean): string {
+  const block = `${tableBlockStart}\n${table}\n${tableBlockEnd}`;
+  const blockPattern = new RegExp(`${escapeRegExp(tableBlockStart)}[\\s\\S]*?${escapeRegExp(tableBlockEnd)}`);
+
+  if (blockPattern.test(markdown)) {
+    return markdown.replace(blockPattern, block);
+  }
+
+  if (force) {
+    const separator = markdown.endsWith("\n") ? "\n" : "\n\n";
+    return `${markdown}${separator}${block}\n`;
+  }
+
+  throw new Error(`No configenvy table block found. Add ${tableBlockStart} and ${tableBlockEnd}, or rerun with --force.`);
 }
 
 export function resolveOutputPath(
@@ -214,6 +392,10 @@ function escapeAnnotationMessage(value: string): string {
   return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
 }
 
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 function isNodeError(error: unknown): error is NodeJS.ErrnoException {
   return error instanceof Error && "code" in error;
 }