@dev-pi2pie/word-counter 0.1.0 → 0.1.2

package/README.md

@@ -121,17 +121,25 @@ word-counter --path ./examples/test-case-multi-files-support --keep-progress
 
 Progress is transient by default, auto-disabled for single-input runs, and suppressed in `--format raw` and `--format json`.
 
-### Stable Path Resolution Contract (`#26`)
+### Stable Path Resolution Contract
 
 - Repeated `--path` values are accepted as mixed inputs (file + directory).
 - In `--path-mode auto` (default), directory inputs are expanded to files (recursive unless `--no-recursive`).
-- In `--path-mode manual`, directory inputs are not expanded and are skipped as non-regular files.
-- Extension filters apply only to files discovered from directory expansion.
-- Direct file inputs are always considered regardless of `--include-ext` / `--exclude-ext`.
+- In `--path-mode manual`, `--path` values are treated as literal file inputs; `--path <dir>` is not supported and is skipped as `not a regular file`.
+- Extension and regex filters apply only to files discovered from directory expansion.
+- Direct file inputs are always considered regardless of `--include-ext` / `--exclude-ext` / `--regex`.
 - Overlap dedupe is by resolved absolute file path.
 - If the same file is discovered multiple ways (repeated roots, nested roots, explicit file + directory), it is counted once.
 - Final processing order is deterministic: resolved files are sorted by absolute path ascending before load/count.
 
+Path mode examples:
+
+```bash
+word-counter --path ./examples/test-case-multi-files-support --path-mode auto
+word-counter --path ./examples/test-case-multi-files-support --path-mode manual
+word-counter --path ./examples/test-case-multi-files-support/a.md --path-mode manual
+```
+
 ### Extension Filters
 
 Use include/exclude filters for directory scans:
@@ -147,6 +155,28 @@ Direct file path example (filters do not block explicit file inputs):
 word-counter --path ./examples/test-case-multi-files-support/ignored.js --include-ext .md --exclude-ext .md
 ```
 
+### Regex Filter (`--regex`)
+
+Use `--regex` to include only directory-scanned files whose root-relative path matches:
+
+```bash
+word-counter --path ./examples/test-case-multi-files-support --regex '^a\\.md$'
+word-counter --path ./examples/test-case-multi-files-support --regex '^nested/.*\\.md$'
+word-counter --path ./examples/test-case-multi-files-support --path ./examples --regex '\\.md$'
+```
+
+Regex behavior contract:
+
+- `--regex` applies only to files discovered from `--path <dir>` expansion.
+- Matching is against each directory root-relative path.
+- The same regex is applied across all provided directory roots.
+- Direct file inputs are literal and are not blocked by regex filters.
+- In `--path-mode manual`, directories are not expanded, so `--include-ext`, `--exclude-ext`, and `--regex` have no effect.
+- `--regex` is single-use; repeated `--regex` flags fail fast with a misuse error.
+- Empty regex values are treated as no regex restriction.
+
+For additional usage details and troubleshooting, see [`docs/regex-usage-guide.md`](docs/regex-usage-guide.md).
+
 ### Debugging Diagnostics (`--debug`)
 
 `--debug` remains the diagnostics gate and now defaults to `compact` event volume:
@@ -426,6 +456,9 @@ Select how results are printed with `--format`:
 - `raw` – only the total count (single number).
 - `json` – machine-readable output; add `--pretty` for indentation.
 
+JSON contract reference:
+- `docs/schemas/json-output-contract.md`
+
 Examples:
 
 ```bash
@@ -465,7 +498,13 @@ Rules:
   - `symbol` -> `symbols`
   - `punction` -> `punctuation`
 
-JSON output adds `meta.totalOf` and `meta.totalOfOverride` when `--total-of` is provided.
+JSON output adds override metadata when `--total-of` is provided:
+
+- single input and merged batch: `meta.totalOf`, `meta.totalOfOverride`
+- per-file batch (`--per-file`):
+  - top-level: `meta.totalOf`, `meta.aggregateTotalOfOverride`
+  - per entry: `files[i].meta.totalOf`, `files[i].meta.totalOfOverride`
+  - applies to both sectioned and non-sectioned per-file JSON results
 
 Example JSON (trimmed):
 

package/dist/esm/bin.mjs

@@ -2,7 +2,7 @@
 
 import { Command, Option } from "commander";
 import { closeSync, createWriteStream, existsSync, mkdirSync, openSync, readFileSync, statSync } from "node:fs";
-import { basename, dirname, extname, join, relative, resolve } from "node:path";
+import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFile, readdir, stat } from "node:fs/promises";
 import { parseDocument } from "yaml";
@@ -55,8 +55,9 @@ function withCollisionSuffix(pathValue, sequence) {
 function resolveReportPath(report, now, pid) {
 	const cwd = report.cwd ?? process.cwd();
 	const defaultName = `wc-debug-${formatDebugReportTimestamp(now)}-${pid}.jsonl`;
-	const explicitPath = typeof report.path === "string";
-	const basePath = explicitPath ? resolve(cwd, report.path) : resolve(cwd, defaultName);
+	const explicitPathValue = typeof report.path === "string" ? report.path : void 0;
+	const explicitPath = explicitPathValue !== void 0;
+	const basePath = resolve(cwd, explicitPathValue ?? defaultName);
 	mkdirSync(dirname(basePath), { recursive: true });
 	if (explicitPath) {
 		if (existsSync(basePath) && statSync(basePath).isDirectory()) throw new Error(`debug report path must be a file: ${basePath}`);
@@ -191,6 +192,34 @@ function shouldIncludeFromDirectory(filePath, filter) {
 	const extension = extname(filePath).toLowerCase();
 	return filter.effectiveIncludeExtensions.has(extension);
 }
+function buildDirectoryRegexFilter(pattern) {
+	if (pattern === void 0) return {
+		sourcePattern: void 0,
+		regex: void 0
+	};
+	if (pattern.trim().length === 0) return {
+		sourcePattern: pattern,
+		regex: void 0
+	};
+	try {
+		return {
+			sourcePattern: pattern,
+			regex: new RegExp(pattern)
+		};
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Invalid --regex pattern: ${message}`);
+	}
+}
+function toDirectoryRelativePath(rootPath, filePath) {
+	const relativePath = relative(rootPath, filePath);
+	if (sep === "/") return relativePath;
+	return relativePath.split(sep).join("/");
+}
+function shouldIncludeFromDirectoryRegex(relativePath, filter) {
+	if (!filter.regex) return true;
+	return filter.regex.test(relativePath);
+}
 
 //#endregion
 //#region src/cli/total-of.ts
@@ -314,7 +343,7 @@ function collectPathValue(value, previous = []) {
 	return [...previous, value];
 }
 function configureProgramOptions(program, parseMode) {
-	program.addOption(new Option("-m, --mode <mode>", "breakdown mode").choices(MODE_CHOICES).argParser(parseMode).default("chunk")).addOption(new Option("-f, --format <format>", "output format").choices(FORMAT_CHOICES).default("standard")).addOption(new Option("--section <section>", "document section mode").choices(SECTION_CHOICES).default("all")).addOption(new Option("--path-mode <mode>", "path resolution mode").choices(PATH_MODE_CHOICES).default("auto")).option("--latin-language <language>", "hint a language tag for Latin script text").option("--latin-tag <tag>", "hint a BCP 47 tag for Latin script text").option("--latin-locale <locale>", "legacy alias of --latin-language").option("--han-language <language>", "hint a language tag for Han script text").option("--han-tag <tag>", "hint a BCP 47 tag for Han script text").option("--non-words", "collect emoji, symbols, and punctuation (excludes whitespace)").option("--include-whitespace", "include whitespace counts (implies with --non-words; same as --misc)").option("--misc", "collect non-words plus whitespace (alias for --include-whitespace)").option("--total-of <parts>", "override total composition (comma-separated): words,emoji,symbols,punctuation,whitespace", parseTotalOfOption).option("--pretty", "pretty print JSON output", false).option("--debug", "enable debug diagnostics on stderr").option("--verbose", "emit verbose per-file debug diagnostics (requires --debug)").option("--debug-report [path]", "write debug diagnostics to a report file").option("--debug-report-tee", "mirror debug diagnostics to both report file and stderr").option("--debug-tee", "alias of --debug-report-tee").option("--merged", "show merged aggregate output (default)").option("--per-file", "show per-file output plus merged summary").option("--no-progress", "disable batch progress indicator").option("--keep-progress", "keep final batch progress line visible in standard mode").option("--no-recursive", "disable recursive directory traversal").option("--quiet-skips", "hide skip diagnostics (applies when --debug is enabled)").option("--include-ext <exts>", "comma-separated extensions to include during directory scanning", collectExtensionOption, []).option("--exclude-ext <exts>", "comma-separated extensions to exclude during directory scanning", collectExtensionOption, []).option("-p, --path <path>", "read input from file or directory", collectPathValue, []).argument("[text...]", "text to count").showHelpAfterError();
+	program.addOption(new Option("-m, --mode <mode>", "breakdown mode").choices(MODE_CHOICES).argParser(parseMode).default("chunk")).addOption(new Option("-f, --format <format>", "output format").choices(FORMAT_CHOICES).default("standard")).addOption(new Option("--section <section>", "document section mode").choices(SECTION_CHOICES).default("all")).addOption(new Option("--path-mode <mode>", "path resolution mode: auto (default) expands directories; manual treats --path values as literal files").choices(PATH_MODE_CHOICES).default("auto")).option("--latin-language <language>", "hint a language tag for Latin script text").option("--latin-tag <tag>", "hint a BCP 47 tag for Latin script text").option("--latin-locale <locale>", "legacy alias of --latin-language").option("--han-language <language>", "hint a language tag for Han script text").option("--han-tag <tag>", "hint a BCP 47 tag for Han script text").option("--non-words", "collect emoji, symbols, and punctuation (excludes whitespace)").option("--include-whitespace", "include whitespace counts (implies with --non-words; same as --misc)").option("--misc", "collect non-words plus whitespace (alias for --include-whitespace)").option("--total-of <parts>", "override total composition (comma-separated): words,emoji,symbols,punctuation,whitespace", parseTotalOfOption).option("--pretty", "pretty print JSON output", false).option("--debug", "enable debug diagnostics on stderr").option("--verbose", "emit verbose per-file debug diagnostics (requires --debug)").option("--debug-report [path]", "write debug diagnostics to a report file").option("--debug-report-tee", "mirror debug diagnostics to both report file and stderr").option("--debug-tee", "alias of --debug-report-tee").option("--merged", "show merged aggregate output (default)").option("--per-file", "show per-file output plus merged summary").option("--no-progress", "disable batch progress indicator").option("--keep-progress", "keep final batch progress line visible in standard mode").option("--no-recursive", "disable recursive directory traversal").option("--quiet-skips", "hide skip diagnostics (applies when --debug is enabled)").option("--include-ext <exts>", "comma-separated extensions to include during directory scanning", collectExtensionOption, []).option("--exclude-ext <exts>", "comma-separated extensions to exclude during directory scanning", collectExtensionOption, []).option("--regex <pattern>", "regex filter for directory-scanned paths (applies to --path directories only)").option("-p, --path <path>", "read input from file or directory (directories expand in auto mode by default)", collectPathValue, []).argument("[text...]", "text to count").showHelpAfterError();
 }
 
 //#endregion
@@ -387,8 +416,12 @@ var require_picocolors = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 }));
 
 //#endregion
-//#region src/cli/program/version.ts
+//#region src/cli/program/version-embedded.ts
 var import_picocolors = /* @__PURE__ */ __toESM(require_picocolors(), 1);
+const EMBEDDED_PACKAGE_VERSION = "0.1.2";
+
+//#endregion
+//#region src/cli/program/version.ts
 function* candidateSearchRoots() {
 	yield dirname(fileURLToPath(import.meta.url));
 	const argvPath = process.argv[1];
@@ -412,13 +445,23 @@ function resolveVersionFromPath(start, maxLevels) {
 	} catch {}
 	return null;
 }
-function resolvePackageVersion() {
-	const maxLevels = 8;
+function normalizeVersion(value) {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	if (!trimmed) return null;
+	return trimmed;
+}
+function resolvePackageVersion(options = {}) {
+	const embeddedVersion = normalizeVersion(options.embeddedVersion ?? EMBEDDED_PACKAGE_VERSION);
+	if (embeddedVersion) return embeddedVersion;
+	const maxLevels = options.maxLevels ?? 8;
+	const resolveFromPath = options.resolveFromPath ?? resolveVersionFromPath;
+	const roots = options.candidateRoots ?? [...candidateSearchRoots()];
 	const seen = /* @__PURE__ */ new Set();
-	for (const root of candidateSearchRoots()) {
+	for (const root of roots) {
 		if (seen.has(root)) continue;
 		seen.add(root);
-		const version = resolveVersionFromPath(root, maxLevels);
+		const version = normalizeVersion(resolveFromPath(root, maxLevels));
 		if (version) return version;
 	}
 	return "0.0.0";
@@ -485,7 +528,7 @@ async function loadBatchInputs(filePaths) {
 
 //#endregion
 //#region src/cli/path/resolve.ts
-async function expandDirectory(directoryPath, recursive, filter, skipped, debug, stats) {
+async function expandDirectory(rootPath, directoryPath, recursive, extensionFilter, regexFilter, skipped, recordRegexExcluded, debug, stats) {
 	let entries;
 	try {
 		entries = await readdir(directoryPath, {
@@ -514,7 +557,7 @@ async function expandDirectory(directoryPath, recursive, filter, skipped, debug,
 	for (const entry of sortedEntries) {
 		const entryPath = resolve(directoryPath, entry.name);
 		if (entry.isFile()) {
-			if (!shouldIncludeFromDirectory(entryPath, filter)) {
+			if (!shouldIncludeFromDirectory(entryPath, extensionFilter)) {
 				skipped.push({
 					path: entryPath,
 					reason: "extension excluded"
@@ -526,6 +569,19 @@ async function expandDirectory(directoryPath, recursive, filter, skipped, debug,
 				stats.filterExcluded += 1;
 				continue;
 			}
+			const relativePath = toDirectoryRelativePath(rootPath, entryPath);
+			if (!shouldIncludeFromDirectoryRegex(relativePath, regexFilter)) {
+				if (recordRegexExcluded(entryPath)) {
+					debug.emit("path.resolve.regex.excluded", {
+						path: entryPath,
+						relativePath,
+						pattern: regexFilter.sourcePattern,
+						reason: "regex excluded"
+					}, { verbosity: "verbose" });
+					stats.regexExcluded += 1;
+				}
+				continue;
+			}
 			files.push(entryPath);
 			stats.directoryIncluded += 1;
 			debug.emit("path.resolve.expand.include", {
@@ -535,7 +591,7 @@ async function expandDirectory(directoryPath, recursive, filter, skipped, debug,
 			continue;
 		}
 		if (!entry.isDirectory() || !recursive) continue;
-		appendAll(files, await expandDirectory(entryPath, recursive, filter, skipped, debug, stats));
+		appendAll(files, await expandDirectory(rootPath, entryPath, recursive, extensionFilter, regexFilter, skipped, recordRegexExcluded, debug, stats));
 	}
 	debug.emit("path.resolve.expand.complete", {
 		directory: directoryPath,
@@ -545,14 +601,17 @@ async function expandDirectory(directoryPath, recursive, filter, skipped, debug,
 }
 async function resolveBatchFilePaths(pathInputs, options) {
 	const skipped = [];
+	const regexExcludedPaths = /* @__PURE__ */ new Set();
 	const resolvedFiles = /* @__PURE__ */ new Set();
 	const stats = {
 		dedupeAccepted: 0,
 		dedupeDuplicates: 0,
 		filterExcluded: 0,
+		regexExcluded: 0,
 		directoryIncluded: 0
 	};
 	const extensionFilter = options.extensionFilter ?? buildDirectoryExtensionFilter(void 0, void 0);
+	let regexFilter;
 	const debug = options.debug ?? {
 		enabled: false,
 		verbosity: "compact",
@@ -562,9 +621,11 @@ async function resolveBatchFilePaths(pathInputs, options) {
 	debug.emit("path.resolve.inputs", {
 		inputs: pathInputs.length,
 		pathMode: options.pathMode,
-		recursive: options.recursive
+		recursive: options.recursive,
+		hasRegex: Boolean(options.directoryRegexPattern)
 	});
 	const addResolvedFile = (filePath, details) => {
+		regexExcludedPaths.delete(filePath);
 		if (resolvedFiles.has(filePath)) {
 			stats.dedupeDuplicates += 1;
 			debug.emit("path.resolve.dedupe.duplicate", {
@@ -582,6 +643,15 @@ async function resolveBatchFilePaths(pathInputs, options) {
 			input: details.input
 		}, { verbosity: "verbose" });
 	};
+	const getRegexFilter = () => {
+		if (!regexFilter) regexFilter = buildDirectoryRegexFilter(options.directoryRegexPattern);
+		return regexFilter;
+	};
+	const recordRegexExcluded = (filePath) => {
+		if (resolvedFiles.has(filePath)) return false;
+		regexExcludedPaths.add(filePath);
+		return true;
+	};
 	for (const rawPath of pathInputs) {
 		const targetPath = resolve(rawPath);
 		debug.emit("path.resolve.input", {
@@ -604,11 +674,13 @@ async function resolveBatchFilePaths(pathInputs, options) {
 			continue;
 		}
 		if (metadata.isDirectory() && options.pathMode === "auto") {
+			const effectiveRegexFilter = getRegexFilter();
 			debug.emit("path.resolve.root.expand", {
 				root: targetPath,
-				recursive: options.recursive
+				recursive: options.recursive,
+				regex: effectiveRegexFilter.sourcePattern ?? null
 			});
-			const files = await expandDirectory(targetPath, options.recursive, extensionFilter, skipped, debug, stats);
+			const files = await expandDirectory(targetPath, targetPath, options.recursive, extensionFilter, effectiveRegexFilter, skipped, recordRegexExcluded, debug, stats);
 			for (const file of files) addResolvedFile(file, {
 				source: "directory",
 				input: targetPath
@@ -631,9 +703,15 @@ async function resolveBatchFilePaths(pathInputs, options) {
 			input: targetPath
 		});
 	}
+	for (const path of regexExcludedPaths) skipped.push({
+		path,
+		reason: "regex excluded"
+	});
 	const files = [...resolvedFiles].sort((left, right) => left.localeCompare(right));
 	debug.emit("path.resolve.filter.summary", {
-		excluded: stats.filterExcluded,
+		excluded: stats.filterExcluded + stats.regexExcluded,
+		extensionExcluded: stats.filterExcluded,
+		regexExcluded: stats.regexExcluded,
 		included: stats.directoryIncluded
 	});
 	debug.emit("path.resolve.dedupe.summary", {
@@ -2086,6 +2164,7 @@ async function runBatchCount(options) {
 		pathMode: options.batchOptions.pathMode,
 		recursive: options.batchOptions.recursive,
 		extensionFilter: options.extensionFilter,
+		directoryRegexPattern: options.batchOptions.directoryRegexPattern,
 		debug: options.debug
 	});
 	const resolveElapsedMs = Date.now() - resolveStartedAtMs;
@@ -2362,6 +2441,27 @@ function normalizeBatchSummaryBase(summary) {
 function hasPathInput(pathValues) {
 	return Array.isArray(pathValues) && pathValues.length > 0;
 }
+function countLongOptionOccurrences(argv, optionName) {
+	let count = 0;
+	for (let index = 2; index < argv.length; index += 1) {
+		const token = argv[index];
+		if (!token) continue;
+		if (token === "--") break;
+		if (token === optionName) {
+			count += 1;
+			index += 1;
+			continue;
+		}
+		if (token.startsWith(`${optionName}=`)) {
+			count += 1;
+			continue;
+		}
+	}
+	return count;
+}
+function validateSingleRegexOptionUsage(argv) {
+	if (countLongOptionOccurrences(argv, "--regex") > 1) throw new Error("`--regex` can only be provided once.");
+}
 function resolveBatchScope(argv) {
 	let scope = "merged";
 	for (const token of argv) {
@@ -2413,7 +2513,8 @@ async function executeBatchCount({ argv, options, runtime, resolved, debug, teeE
 		scope: resolveBatchScope(argv),
 		pathMode: options.pathMode,
 		recursive: options.recursive,
-		quietSkips: Boolean(options.quietSkips)
+		quietSkips: Boolean(options.quietSkips),
+		directoryRegexPattern: options.regex
 	};
 	const extensionFilter = buildDirectoryExtensionFilter(options.includeExt, options.excludeExt);
 	const debugEnabled = Boolean(options.debug);
@@ -2471,16 +2572,29 @@ async function executeBatchCount({ argv, options, runtime, resolved, debug, teeE
 		const spacing = options.pretty ? 2 : 0;
 		if (batchOptions.scope === "per-file") {
 			const skipped = showSkipDiagnostics ? summary.skipped : void 0;
+			const fileEntries = summary.files.map((file) => {
+				const base = {
+					path: file.path,
+					result: file.result
+				};
+				if (!resolved.totalOfParts || resolved.totalOfParts.length === 0) return base;
+				const fileOverride = totalOfOverridesByResult?.get(file.result) ?? resolveTotalOfOverride(file.result, resolved.totalOfParts);
+				if (!fileOverride) return base;
+				return {
+					...base,
+					meta: {
+						totalOf: fileOverride.parts,
+						totalOfOverride: fileOverride.total
+					}
+				};
+			});
 			const meta = resolved.totalOfParts && resolved.totalOfParts.length > 0 ? {
 				totalOf: resolved.totalOfParts,
 				aggregateTotalOfOverride: aggregateTotalOfOverride?.total ?? summary.aggregate.total
 			} : void 0;
 			const payload = {
 				scope: "per-file",
-				files: summary.files.map((file) => ({
-					path: file.path,
-					result: file.result
-				})),
+				files: fileEntries,
 				...skipped ? { skipped } : {},
 				aggregate: summary.aggregate,
 				...meta ? { meta } : {}
@@ -2601,6 +2715,13 @@ async function runCli(argv = process.argv, runtime = {}) {
 			program.error(import_picocolors.default.red("`--debug-report-tee` (alias: `--debug-tee`) requires `--debug-report`."));
 			return;
 		}
+		try {
+			validateSingleRegexOptionUsage(argv);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			program.error(import_picocolors.default.red(message));
+			return;
+		}
 		let debug;
 		try {
 			debug = createDebugChannel({