configenvy 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -2,10 +2,10 @@
 import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { Command } from 'commander';
-import { buildMarkdownTable, explainVariable, scanProject, toJson, Diagnostic } from '@configenvy/core';
+import { buildMarkdownTable, explainVariable, scanProject, toJson, toSarif, Diagnostic } from '@configenvy/core';
 
 type DoctorOptions = {
-    format?: "text" | "json";
+    format?: "text" | "json" | "sarif";
     strict?: boolean;
     ci?: boolean;
 };
@@ -18,12 +18,15 @@ type CliDependencies = {
     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, printHumanReport, resolveOutputPath, runCli, runDoctor };
+export { type CliDependencies, createProgram, printGitHubAnnotations, printHumanReport, resolveOutputPath, runCli, runDoctor, runInit };

package/dist/index.js

@@ -5,7 +5,7 @@ import { writeFile } from "fs/promises";
 import { isAbsolute, resolve } from "path";
 import { pathToFileURL } from "url";
 import { Command } from "commander";
-import { buildMarkdownTable, explainVariable, scanProject, toJson } from "@configenvy/core";
+import { buildMarkdownTable, explainVariable, scanProject, toJson, toSarif } from "@configenvy/core";
 var defaultDependencies = {
   buildMarkdownTable,
   error: console.error,
@@ -15,15 +15,16 @@ var defaultDependencies = {
   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.2");
-  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) => {
+  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 or json", "text").action(async (projectPath, options) => {
+  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) => {
@@ -37,12 +38,21 @@ function createProgram(dependencies = defaultDependencies) {
       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);
@@ -54,14 +64,36 @@ async function runDoctor(projectPath, options, dependencies = defaultDependencie
   });
   if (options.format === "json") {
     dependencies.log(dependencies.toJson(result));
+  } else if (options.format === "sarif") {
+    dependencies.log(dependencies.toSarif(result));
   } else {
     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) 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 resolveOutputPath(projectPath, outputPath, resolvePath = resolve) {
   if (isAbsolute(outputPath)) return outputPath;
   return resolvePath(projectPath, outputPath);
@@ -83,6 +115,25 @@ function printHumanReport(diagnostics, log = defaultDependencies.log) {
   const warnings = diagnostics.length - errors;
   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) => {
@@ -92,8 +143,10 @@ if (invokedPath && import.meta.url === pathToFileURL(invokedPath).href) {
 }
 export {
   createProgram,
+  printGitHubAnnotations,
   printHumanReport,
   resolveOutputPath,
   runCli,
-  runDoctor
+  runDoctor,
+  runInit
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configenvy",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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.2",
+    "@configenvy/core": "0.1.4",
     "commander": "^12.1.0"
   },
   "keywords": [

package/src/index.ts

@@ -3,10 +3,10 @@ import { 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, 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;
 };
@@ -20,6 +20,7 @@ export type CliDependencies = {
   resolvePath: typeof resolve;
   scanProject: typeof scanProject;
   toJson: typeof toJson;
+  toSarif: typeof toSarif;
   writeFile: typeof writeFile;
 };
 
@@ -32,6 +33,7 @@ const defaultDependencies: CliDependencies = {
   resolvePath: resolve,
   scanProject,
   toJson,
+  toSarif,
   writeFile
 };
 
@@ -41,12 +43,12 @@ export function createProgram(dependencies: CliDependencies = defaultDependencie
   program
     .name("configenvy")
     .description("Find missing, unused, undocumented, and risky environment variables.")
-    .version("0.1.2");
+    .version("0.1.4");
 
   program
     .command("doctor")
     .argument("[path]", "project directory", ".")
-    .option("--format <format>", "output format: text or json", "text")
+    .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);
@@ -56,7 +58,7 @@ export function createProgram(dependencies: CliDependencies = defaultDependencie
     .command("check")
     .argument("[path]", "project directory", ".")
     .option("--ci", "fail on warnings and errors")
-    .option("--format <format>", "output format: text or json", "text")
+    .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);
     });
@@ -76,6 +78,14 @@ 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);
+    });
+
   program
     .command("explain")
     .argument("<variable>", "environment variable name")
@@ -88,6 +98,13 @@ export function createProgram(dependencies: CliDependencies = defaultDependencie
   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);
@@ -105,8 +122,13 @@ export async function runDoctor(
 
   if (options.format === "json") {
     dependencies.log(dependencies.toJson(result));
+  } else if (options.format === "sarif") {
+    dependencies.log(dependencies.toSarif(result));
   } else {
     printHumanReport(result.diagnostics, dependencies.log);
+    if (options.ci) {
+      printGitHubAnnotations(result.diagnostics, dependencies.log);
+    }
   }
 
   const hasError = result.diagnostics.some((diagnostic) => diagnostic.severity === "error");
@@ -115,6 +137,28 @@ export async function runDoctor(
   if (hasWarning) dependencies.exit(1);
 }
 
+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,
@@ -147,6 +191,33 @@ export function printHumanReport(
   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) => {