configenvy 0.1.1 → 0.1.4

package/dist/index.d.ts

@@ -1 +1,32 @@
 #!/usr/bin/env node
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { Command } from 'commander';
+import { buildMarkdownTable, explainVariable, scanProject, toJson, toSarif, Diagnostic } from '@configenvy/core';
+
+type DoctorOptions = {
+    format?: "text" | "json" | "sarif";
+    strict?: boolean;
+    ci?: boolean;
+};
+type CliDependencies = {
+    buildMarkdownTable: typeof buildMarkdownTable;
+    error: (...values: unknown[]) => void;
+    exit: (code: number) => never | void;
+    explainVariable: typeof explainVariable;
+    log: (...values: unknown[]) => void;
+    resolvePath: typeof resolve;
+    scanProject: typeof scanProject;
+    toJson: typeof toJson;
+    toSarif: typeof toSarif;
+    writeFile: typeof writeFile;
+};
+declare function createProgram(dependencies?: CliDependencies): Command;
+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 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 };

package/dist/index.js

@@ -2,61 +2,151 @@
 
 // src/index.ts
 import { writeFile } from "fs/promises";
-import { resolve } from "path";
+import { isAbsolute, resolve } from "path";
+import { pathToFileURL } from "url";
 import { Command } from "commander";
-import { buildMarkdownTable, explainVariable, scanProject, toJson } from "@configenvy/core";
-var program = new Command();
-program.name("configenvy").description("Find missing, unused, undocumented, and risky environment variables.").version("0.1.1");
-program.command("doctor").argument("[path]", "project directory", ".").option("--format <format>", "output format: text or json", "text").option("--strict", "treat documentation warnings as errors").action(async (projectPath, options) => {
-  await runDoctor(projectPath, options);
-});
-program.command("check").argument("[path]", "project directory", ".").option("--ci", "fail on warnings and errors").option("--format <format>", "output format: text or json", "text").action(async (projectPath, options) => {
-  await runDoctor(projectPath, { ...options, strict: Boolean(options.ci), ci: Boolean(options.ci) });
-});
-program.command("table").argument("[path]", "project directory", ".").option("--out <file>", "write markdown table to a file").action(async (projectPath, options) => {
-  const result = await scanProject({ rootDir: resolve(projectPath) });
-  const table = buildMarkdownTable(result);
-  if (options.out) {
-    await writeFile(resolve(options.out), `${table}
+import { buildMarkdownTable, explainVariable, scanProject, toJson, toSarif } from "@configenvy/core";
+var defaultDependencies = {
+  buildMarkdownTable,
+  error: console.error,
+  exit: process.exit,
+  explainVariable,
+  log: console.log,
+  resolvePath: resolve,
+  scanProject,
+  toJson,
+  toSarif,
+  writeFile
+};
+function createProgram(dependencies = defaultDependencies) {
+  const program = new Command();
+  program.name("configenvy").description("Find missing, unused, undocumented, and risky environment variables.").version("0.1.4");
+  program.command("doctor").argument("[path]", "project directory", ".").option("--format <format>", "output format: text, json, or sarif", "text").option("--strict", "treat documentation warnings as errors").action(async (projectPath, options) => {
+    await runDoctor(projectPath, options, dependencies);
+  });
+  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) => {
+    const rootDir = dependencies.resolvePath(projectPath);
+    const result = await dependencies.scanProject({ rootDir });
+    const table = dependencies.buildMarkdownTable(result);
+    if (options.out) {
+      await dependencies.writeFile(resolveOutputPath(rootDir, options.out, dependencies.resolvePath), `${table}
 `, "utf8");
-  } else {
-    console.log(table);
-  }
-});
-program.command("explain").argument("<variable>", "environment variable name").argument("[path]", "project directory", ".").action(async (variable, projectPath) => {
-  const result = await scanProject({ rootDir: resolve(projectPath) });
-  console.log(explainVariable(result, variable));
-});
-program.parseAsync(process.argv).catch((error) => {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(3);
-});
-async function runDoctor(projectPath, options) {
-  const result = await scanProject({ rootDir: resolve(projectPath), strict: Boolean(options.strict) });
+    } 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("explain").argument("<variable>", "environment variable name").argument("[path]", "project directory", ".").action(async (variable, projectPath) => {
+    const result = await dependencies.scanProject({ rootDir: dependencies.resolvePath(projectPath) });
+    dependencies.log(dependencies.explainVariable(result, variable));
+  });
+  return program;
+}
+var starterConfig = {
+  required: [],
+  optional: [],
+  ignore: ["NODE_ENV"],
+  docs: ["README.md", "docs"]
+};
+async function runCli(argv, dependencies = defaultDependencies) {
+  const program = createProgram(dependencies);
+  await program.parseAsync(argv);
+}
+async function runDoctor(projectPath, options, dependencies = defaultDependencies) {
+  const result = await dependencies.scanProject({
+    rootDir: dependencies.resolvePath(projectPath),
+    strict: Boolean(options.strict)
+  });
   if (options.format === "json") {
-    console.log(toJson(result));
+    dependencies.log(dependencies.toJson(result));
+  } else if (options.format === "sarif") {
+    dependencies.log(dependencies.toSarif(result));
   } else {
-    printHumanReport(result.diagnostics);
+    printHumanReport(result.diagnostics, dependencies.log);
+    if (options.ci) {
+      printGitHubAnnotations(result.diagnostics, dependencies.log);
+    }
   }
   const hasError = result.diagnostics.some((diagnostic) => diagnostic.severity === "error");
   const hasWarning = result.diagnostics.some((diagnostic) => diagnostic.severity === "warning");
-  if (hasError || options.ci && hasWarning) process.exit(2);
-  if (hasWarning) process.exit(1);
+  if (hasError || options.ci && hasWarning) dependencies.exit(2);
+  if (hasWarning) dependencies.exit(1);
+}
+async function runInit(projectPath, dependencies = defaultDependencies) {
+  const rootDir = dependencies.resolvePath(projectPath);
+  const configPath = dependencies.resolvePath(rootDir, "configenvy.config.json");
+  const content = `${JSON.stringify(starterConfig, null, 2)}
+`;
+  try {
+    await dependencies.writeFile(configPath, content, { encoding: "utf8", flag: "wx" });
+  } catch (error) {
+    if (isNodeError(error) && error.code === "EEXIST") {
+      dependencies.error("configenvy.config.json already exists.");
+      dependencies.exit(1);
+      return;
+    }
+    throw error;
+  }
+  dependencies.log(`Created ${configPath}`);
 }
-function printHumanReport(diagnostics) {
+function resolveOutputPath(projectPath, outputPath, resolvePath = resolve) {
+  if (isAbsolute(outputPath)) return outputPath;
+  return resolvePath(projectPath, outputPath);
+}
+function printHumanReport(diagnostics, log = defaultDependencies.log) {
   if (diagnostics.length === 0) {
-    console.log("PASS configenvy found no environment variable issues.");
+    log("PASS configenvy found no environment variable issues.");
     return;
   }
   for (const diagnostic of diagnostics) {
     const label = diagnostic.severity === "error" ? "FAIL" : "WARN";
-    console.log(`${label} ${diagnostic.code} ${diagnostic.variable}`);
-    console.log(`  ${diagnostic.message}`);
+    log(`${label} ${diagnostic.code} ${diagnostic.variable}`);
+    log(`  ${diagnostic.message}`);
     if (diagnostic.files.length > 0) {
-      console.log(`  files: ${diagnostic.files.join(", ")}`);
+      log(`  files: ${diagnostic.files.join(", ")}`);
     }
   }
   const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error").length;
   const warnings = diagnostics.length - errors;
-  console.log(`Summary: ${errors} error(s), ${warnings} warning(s).`);
+  log(`Summary: ${errors} error(s), ${warnings} warning(s).`);
+}
+function printGitHubAnnotations(diagnostics, log = defaultDependencies.log) {
+  for (const diagnostic of diagnostics) {
+    const command = diagnostic.severity === "error" ? "error" : "warning";
+    const properties = [
+      diagnostic.files[0] ? `file=${escapeAnnotationProperty(diagnostic.files[0])}` : void 0,
+      `title=${escapeAnnotationProperty(`${diagnostic.code} ${diagnostic.variable}`)}`
+    ].filter(Boolean);
+    log(`::${command} ${properties.join(",")}::${escapeAnnotationMessage(diagnostic.message)}`);
+  }
+}
+function escapeAnnotationProperty(value) {
+  return escapeAnnotationMessage(value).replace(/:/g, "%3A").replace(/,/g, "%2C");
+}
+function escapeAnnotationMessage(value) {
+  return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+function isNodeError(error) {
+  return error instanceof Error && "code" in error;
+}
+var invokedPath = process.argv[1];
+if (invokedPath && import.meta.url === pathToFileURL(invokedPath).href) {
+  runCli(process.argv).catch((error) => {
+    defaultDependencies.error(error instanceof Error ? error.message : String(error));
+    defaultDependencies.exit(3);
+  });
 }
+export {
+  createProgram,
+  printGitHubAnnotations,
+  printHumanReport,
+  resolveOutputPath,
+  runCli,
+  runDoctor,
+  runInit
+};

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "configenvy",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "Find missing, unused, undocumented, and risky environment variables before setup breaks.",
   "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/sonsriver4815/configenvy.git",
@@ -32,7 +35,7 @@
     "build": "tsup src/index.ts --format esm --dts --clean"
   },
   "dependencies": {
-    "@configenvy/core": "0.1.1",
+    "@configenvy/core": "0.1.4",
     "commander": "^12.1.0"
   },
   "keywords": [

package/src/index.ts

@@ -1,99 +1,227 @@
 #!/usr/bin/env node
 import { writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
+import { isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 import { Command } from "commander";
-import { buildMarkdownTable, explainVariable, scanProject, toJson, type Diagnostic } from "@configenvy/core";
+import { buildMarkdownTable, explainVariable, scanProject, toJson, toSarif, type Diagnostic } from "@configenvy/core";
 
 type DoctorOptions = {
-  format?: "text" | "json";
+  format?: "text" | "json" | "sarif";
   strict?: boolean;
   ci?: boolean;
 };
 
-const program = new Command();
+export type CliDependencies = {
+  buildMarkdownTable: typeof buildMarkdownTable;
+  error: (...values: unknown[]) => void;
+  exit: (code: number) => never | void;
+  explainVariable: typeof explainVariable;
+  log: (...values: unknown[]) => void;
+  resolvePath: typeof resolve;
+  scanProject: typeof scanProject;
+  toJson: typeof toJson;
+  toSarif: typeof toSarif;
+  writeFile: typeof writeFile;
+};
 
-program
-  .name("configenvy")
-  .description("Find missing, unused, undocumented, and risky environment variables.")
-  .version("0.1.1");
+const defaultDependencies: CliDependencies = {
+  buildMarkdownTable,
+  error: console.error,
+  exit: process.exit,
+  explainVariable,
+  log: console.log,
+  resolvePath: resolve,
+  scanProject,
+  toJson,
+  toSarif,
+  writeFile
+};
 
-program
-  .command("doctor")
-  .argument("[path]", "project directory", ".")
-  .option("--format <format>", "output format: text or json", "text")
-  .option("--strict", "treat documentation warnings as errors")
-  .action(async (projectPath: string, options: DoctorOptions) => {
-    await runDoctor(projectPath, options);
-  });
+export function createProgram(dependencies: CliDependencies = defaultDependencies): Command {
+  const program = new Command();
 
-program
-  .command("check")
-  .argument("[path]", "project directory", ".")
-  .option("--ci", "fail on warnings and errors")
-  .option("--format <format>", "output format: text or json", "text")
-  .action(async (projectPath: string, options: DoctorOptions) => {
-    await runDoctor(projectPath, { ...options, strict: Boolean(options.ci), ci: Boolean(options.ci) });
-  });
+  program
+    .name("configenvy")
+    .description("Find missing, unused, undocumented, and risky environment variables.")
+    .version("0.1.4");
 
-program
-  .command("table")
-  .argument("[path]", "project directory", ".")
-  .option("--out <file>", "write markdown table to a file")
-  .action(async (projectPath: string, options: { out?: string }) => {
-    const result = await scanProject({ rootDir: resolve(projectPath) });
-    const table = buildMarkdownTable(result);
-    if (options.out) {
-      await writeFile(resolve(options.out), `${table}\n`, "utf8");
-    } else {
-      console.log(table);
-    }
-  });
+  program
+    .command("doctor")
+    .argument("[path]", "project directory", ".")
+    .option("--format <format>", "output format: text, json, or sarif", "text")
+    .option("--strict", "treat documentation warnings as errors")
+    .action(async (projectPath: string, options: DoctorOptions) => {
+      await runDoctor(projectPath, options, dependencies);
+    });
 
-program
-  .command("explain")
-  .argument("<variable>", "environment variable name")
-  .argument("[path]", "project directory", ".")
-  .action(async (variable: string, projectPath: string) => {
-    const result = await scanProject({ rootDir: resolve(projectPath) });
-    console.log(explainVariable(result, variable));
-  });
+  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: string, options: DoctorOptions) => {
+      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: string, options: { out?: string }) => {
+      const rootDir = dependencies.resolvePath(projectPath);
+      const result = await dependencies.scanProject({ rootDir });
+      const table = dependencies.buildMarkdownTable(result);
+      if (options.out) {
+        await dependencies.writeFile(resolveOutputPath(rootDir, options.out, dependencies.resolvePath), `${table}\n`, "utf8");
+      } else {
+        dependencies.log(table);
+      }
+    });
+
+  program
+    .command("init")
+    .argument("[path]", "project directory", ".")
+    .description("create a starter configenvy.config.json file")
+    .action(async (projectPath: string) => {
+      await runInit(projectPath, dependencies);
+    });
+
+  program
+    .command("explain")
+    .argument("<variable>", "environment variable name")
+    .argument("[path]", "project directory", ".")
+    .action(async (variable: string, projectPath: string) => {
+      const result = await dependencies.scanProject({ rootDir: dependencies.resolvePath(projectPath) });
+      dependencies.log(dependencies.explainVariable(result, variable));
+    });
 
-program.parseAsync(process.argv).catch((error: unknown) => {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(3);
-});
+  return program;
+}
+
+const starterConfig = {
+  required: [],
+  optional: [],
+  ignore: ["NODE_ENV"],
+  docs: ["README.md", "docs"]
+};
+
+export async function runCli(argv: string[], dependencies: CliDependencies = defaultDependencies): Promise<void> {
+  const program = createProgram(dependencies);
+  await program.parseAsync(argv);
+}
 
-async function runDoctor(projectPath: string, options: DoctorOptions): Promise<void> {
-  const result = await scanProject({ rootDir: resolve(projectPath), strict: Boolean(options.strict) });
+export async function runDoctor(
+  projectPath: string,
+  options: DoctorOptions,
+  dependencies: CliDependencies = defaultDependencies
+): Promise<void> {
+  const result = await dependencies.scanProject({
+    rootDir: dependencies.resolvePath(projectPath),
+    strict: Boolean(options.strict)
+  });
 
   if (options.format === "json") {
-    console.log(toJson(result));
+    dependencies.log(dependencies.toJson(result));
+  } else if (options.format === "sarif") {
+    dependencies.log(dependencies.toSarif(result));
   } else {
-    printHumanReport(result.diagnostics);
+    printHumanReport(result.diagnostics, dependencies.log);
+    if (options.ci) {
+      printGitHubAnnotations(result.diagnostics, dependencies.log);
+    }
   }
 
   const hasError = result.diagnostics.some((diagnostic) => diagnostic.severity === "error");
   const hasWarning = result.diagnostics.some((diagnostic) => diagnostic.severity === "warning");
-  if (hasError || (options.ci && hasWarning)) process.exit(2);
-  if (hasWarning) process.exit(1);
+  if (hasError || (options.ci && hasWarning)) dependencies.exit(2);
+  if (hasWarning) dependencies.exit(1);
 }
 
-function printHumanReport(diagnostics: Diagnostic[]): void {
+export async function runInit(
+  projectPath: string,
+  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`;
+
+  try {
+    await dependencies.writeFile(configPath, content, { encoding: "utf8", flag: "wx" });
+  } catch (error) {
+    if (isNodeError(error) && error.code === "EEXIST") {
+      dependencies.error("configenvy.config.json already exists.");
+      dependencies.exit(1);
+      return;
+    }
+    throw error;
+  }
+
+  dependencies.log(`Created ${configPath}`);
+}
+
+export function resolveOutputPath(
+  projectPath: string,
+  outputPath: string,
+  resolvePath: typeof resolve = resolve
+): string {
+  if (isAbsolute(outputPath)) return outputPath;
+  return resolvePath(projectPath, outputPath);
+}
+
+export function printHumanReport(
+  diagnostics: Diagnostic[],
+  log: (...values: unknown[]) => void = defaultDependencies.log
+): void {
   if (diagnostics.length === 0) {
-    console.log("PASS configenvy found no environment variable issues.");
+    log("PASS configenvy found no environment variable issues.");
     return;
   }
 
   for (const diagnostic of diagnostics) {
     const label = diagnostic.severity === "error" ? "FAIL" : "WARN";
-    console.log(`${label} ${diagnostic.code} ${diagnostic.variable}`);
-    console.log(`  ${diagnostic.message}`);
+    log(`${label} ${diagnostic.code} ${diagnostic.variable}`);
+    log(`  ${diagnostic.message}`);
     if (diagnostic.files.length > 0) {
-      console.log(`  files: ${diagnostic.files.join(", ")}`);
+      log(`  files: ${diagnostic.files.join(", ")}`);
     }
   }
 
   const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error").length;
   const warnings = diagnostics.length - errors;
-  console.log(`Summary: ${errors} error(s), ${warnings} warning(s).`);
+  log(`Summary: ${errors} error(s), ${warnings} warning(s).`);
+}
+
+export function printGitHubAnnotations(
+  diagnostics: Diagnostic[],
+  log: (...values: unknown[]) => void = defaultDependencies.log
+): void {
+  for (const diagnostic of diagnostics) {
+    const command = diagnostic.severity === "error" ? "error" : "warning";
+    const properties = [
+      diagnostic.files[0] ? `file=${escapeAnnotationProperty(diagnostic.files[0])}` : undefined,
+      `title=${escapeAnnotationProperty(`${diagnostic.code} ${diagnostic.variable}`)}`
+    ].filter(Boolean);
+
+    log(`::${command} ${properties.join(",")}::${escapeAnnotationMessage(diagnostic.message)}`);
+  }
+}
+
+function escapeAnnotationProperty(value: string): string {
+  return escapeAnnotationMessage(value).replace(/:/g, "%3A").replace(/,/g, "%2C");
+}
+
+function escapeAnnotationMessage(value: string): string {
+  return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error;
+}
+
+const invokedPath = process.argv[1];
+if (invokedPath && import.meta.url === pathToFileURL(invokedPath).href) {
+  runCli(process.argv).catch((error: unknown) => {
+    defaultDependencies.error(error instanceof Error ? error.message : String(error));
+    defaultDependencies.exit(3);
+  });
 }