@philkrpp/phase-loader 0.1.0 → 0.1.2

package/README.md

@@ -89,9 +89,11 @@ phase-loader check --offline    # .env.example vs env reads in git-tracked files
 phase-loader check              # additionally vs the key names in Phase
 ```
 
-`check` recognises `process.env.X`, `process.env["X"]`, `import.meta.env.X`, `os.environ["X"]` and `os.getenv("X")`
-in tracked `.js/.ts/.vue/.py` files (not under `node_modules`), ignores runtime built-ins such as `NODE_ENV`, prints
-names only and exits 1 on any undocumented or orphan name. The personal app is not part of `.env.example`.
+`check` recognises `process.env.X`, `process.env["X"]`, `import.meta.env.X`, `os.environ["X"]`, `os.environ.get("X")`
+and `os.getenv("X")` in tracked `.js/.ts/.vue/.py` files (not under `node_modules`), ignores runtime built-ins such as
+`NODE_ENV`, prints names only and exits 1 on any undocumented or orphan name. A name from `.env.example` that appears
+quoted anywhere in that code (`optional('KEY')`, `env("KEY")`) counts as read, so env helpers cause no orphans; a new
+key read only through such a helper is not reported as undocumented. The personal app is not part of `.env.example`.
 
 ## API
 

package/dist/cli.js

@@ -54,8 +54,16 @@ const USAGE$1 = [
 	/process\.env\[\s*["']([A-Za-z_][A-Za-z0-9_]*)["']\s*\]/g,
 	/import\.meta\.env\.([A-Za-z_][A-Za-z0-9_]*)/g,
 	/os\.environ\[\s*["']([A-Za-z_][A-Za-z0-9_]*)["']\s*\]/g,
-	/os\.getenv\(\s*["']([A-Za-z_][A-Za-z0-9_]*)["']/g
+	/os\.getenv\(\s*["']([A-Za-z_][A-Za-z0-9_]*)["']/g,
+	/os\.environ\.get\(\s*["']([A-Za-z_][A-Za-z0-9_]*)["']/g
 ];
+/**
+* A documented name quoted anywhere in tracked code (`optional('KEY')`, `env("KEY")`, a list of names) counts as
+* read, so helpers around `process.env[name]` do not produce orphans.
+* shortcut: undocumented detection still sees only the USAGE patterns, so a new key read only through a helper is
+* not reported; upgrade with a configurable helper list if that bites.
+*/
+const QUOTED = /["'`]([A-Z_][A-Z0-9_]*)["'`]/g;
 /** Provided by the runtime or by phase-loader itself, never documented in `.env.example`. */
 const BUILT_IN = /* @__PURE__ */ new Set([
 	"NODE_ENV",
@@ -84,6 +92,7 @@ function trackedFiles(dir) {
 }
 function usedNames(dir) {
 	const used = /* @__PURE__ */ new Set();
+	const quoted = /* @__PURE__ */ new Set();
 	for (const file of trackedFiles(dir)) {
 		if (!SOURCE.test(file) || file.split("/").includes("node_modules")) continue;
 		let text;
@@ -93,8 +102,12 @@ function usedNames(dir) {
 			continue;
 		}
 		for (const pattern of USAGE$1) for (const m of text.matchAll(pattern)) if (!BUILT_IN.has(m[1])) used.add(m[1]);
+		for (const m of text.matchAll(QUOTED)) quoted.add(m[1]);
 	}
-	return used;
+	return {
+		used,
+		quoted
+	};
 }
 /**
 * Offline: names in `.env.example` against env reads in tracked source files (undocumented / orphan).
@@ -105,8 +118,8 @@ async function check(opts = {}) {
 	const file = join(dir, EXAMPLE_FILE);
 	if (!existsSync(file)) throw new PhaseLoaderError(`${EXAMPLE_FILE} not found in ${dir} (create it with "phase-loader example --write").`);
 	const documented = new Set(exampleNames(readFileSync(file, "utf8")));
-	const used = usedNames(dir);
-	const findings = [[`Used in code but undocumented in ${EXAMPLE_FILE}:`, [...used].filter((n) => !documented.has(n))], [`Orphan in ${EXAMPLE_FILE} (never read in tracked code):`, [...documented].filter((n) => !used.has(n))]];
+	const { used, quoted } = usedNames(dir);
+	const findings = [[`Used in code but undocumented in ${EXAMPLE_FILE}:`, [...used].filter((n) => !documented.has(n))], [`Orphan in ${EXAMPLE_FILE} (never read in tracked code):`, [...documented].filter((n) => !used.has(n) && !quoted.has(n))]];
 	if (!opts.offline) {
 		const inPhase = new Set((await phaseNames(opts.cwd ?? process.cwd())).sections.flatMap((s) => s.names));
 		findings.push([`In ${EXAMPLE_FILE} but not in Phase:`, [...documented].filter((n) => !inPhase.has(n))], [`In Phase but not in ${EXAMPLE_FILE}:`, [...inPhase].filter((n) => !documented.has(n))]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@philkrpp/phase-loader",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Load env values from a self-hosted Phase secrets manager into a child process or the current process, with layered apps/paths and OS keyring tokens.",
   "license": "MIT",
   "repository": {