nojibake 0.1.0

package/dist/cli.js

@@ -0,0 +1,1054 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFileSync as readFileSync4, realpathSync as realpathSync2 } from "fs";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { Command } from "commander";
+
+// src/config.ts
+import { existsSync, readFileSync } from "fs";
+import { join, resolve } from "path";
+var allowedPolicies = ["unsafe", "ambiguous", "mixed-eol", "non-utf8", "disallowed-encoding"];
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parsePositiveInteger(value, key) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+    throw new Error(`${key} must be a positive integer.`);
+  }
+  return value;
+}
+function parseBoolean(value, key) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "boolean") throw new Error(`${key} must be a boolean.`);
+  return value;
+}
+function parseStringArray(value, key) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error(`${key} must be an array of strings.`);
+  }
+  return value.map((item) => item.trim()).filter(Boolean);
+}
+function parsePolicies(value) {
+  const items = parseStringArray(value, "failOn");
+  if (items === void 0) return void 0;
+  const policies = [];
+  for (const item of items) {
+    if (!allowedPolicies.includes(item)) {
+      throw new Error(`Unknown guard policy in config: ${item}`);
+    }
+    policies.push(item);
+  }
+  return [...new Set(policies)];
+}
+function parseConfigText(text, source) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid JSON.";
+    throw new Error(`Could not parse ${source}: ${message}`);
+  }
+  if (!isRecord(parsed)) throw new Error(`${source} must contain a JSON object.`);
+  const config = {};
+  const maxFiles = parsePositiveInteger(parsed.maxFiles, "maxFiles");
+  if (maxFiles !== void 0) config.maxFiles = maxFiles;
+  const maxBytes = parsePositiveInteger(parsed.maxBytes, "maxBytes");
+  if (maxBytes !== void 0) config.maxBytes = maxBytes;
+  const includeIgnored = parseBoolean(parsed.includeIgnored, "includeIgnored");
+  if (includeIgnored !== void 0) config.includeIgnored = includeIgnored;
+  const ignore = parseStringArray(parsed.ignore, "ignore");
+  if (ignore !== void 0) config.ignore = ignore;
+  const failOn = parsePolicies(parsed.failOn);
+  if (failOn !== void 0) config.failOn = failOn;
+  const allowEncodings = parseStringArray(parsed.allowEncodings, "allowEncodings");
+  if (allowEncodings !== void 0) config.allowEncodings = allowEncodings.map((encoding) => encoding.toLowerCase());
+  return config;
+}
+function loadConfig(root) {
+  const configPath = join(resolve(root), ".nojibakerc.json");
+  if (!existsSync(configPath)) return {};
+  return parseConfigText(readFileSync(configPath, "utf8"), configPath);
+}
+
+// src/encoding.ts
+import { createHash } from "crypto";
+import { TextDecoder } from "util";
+import iconv from "iconv-lite";
+
+// src/result.ts
+import { randomUUID } from "crypto";
+import { readFileSync as readFileSync2 } from "fs";
+import { dirname, join as join2 } from "path";
+import { fileURLToPath } from "url";
+
+// src/types.ts
+var schemaVersion = "1.0.0";
+
+// src/result.ts
+function loadPackage() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [join2(here, "..", "package.json"), join2(here, "..", "..", "package.json")];
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(readFileSync2(candidate, "utf8"));
+      if (typeof parsed.name === "string" && typeof parsed.version === "string") {
+        return { name: parsed.name, version: parsed.version };
+      }
+    } catch (error) {
+      if (!(error instanceof Error)) throw error;
+      continue;
+    }
+  }
+  return { name: "nojibake", version: "0.0.0" };
+}
+var packageInfo = loadPackage();
+function makeError(code, message, details) {
+  return details === void 0 ? { code, message } : { code, message, details };
+}
+function envelope(input) {
+  return {
+    schemaVersion,
+    toolVersion: packageInfo.version,
+    invocationId: randomUUID(),
+    ok: input.ok,
+    command: input.command,
+    summary: input.summary,
+    data: input.data,
+    errors: input.errors ?? [],
+    warnings: input.warnings ?? []
+  };
+}
+
+// src/encoding.ts
+function hasPrefix(bytes, prefix) {
+  return prefix.every((value, index) => bytes[index] === value);
+}
+function detectBom(bytes) {
+  if (hasPrefix(bytes, [239, 187, 191])) return { bom: "utf-8", offset: 3, encoding: "utf-8" };
+  if (hasPrefix(bytes, [255, 254])) return { bom: "utf-16le", offset: 2, encoding: "utf-16le" };
+  if (hasPrefix(bytes, [254, 255])) return { bom: "utf-16be", offset: 2, encoding: "utf-16be" };
+  return { bom: "none", offset: 0, encoding: null };
+}
+function strictDecode(bytes, encoding) {
+  return new TextDecoder(encoding, { fatal: true, ignoreBOM: true }).decode(bytes);
+}
+function firstInvalidUtf8Offset(bytes) {
+  for (let i = 0; i < bytes.length; i += 1) {
+    const value = bytes[i];
+    if (value === void 0) return i;
+    if (value <= 127) continue;
+    let needed = 0;
+    let min = 0;
+    if (value >= 194 && value <= 223) {
+      needed = 1;
+      min = 128;
+    } else if (value >= 224 && value <= 239) {
+      needed = 2;
+      min = value === 224 ? 160 : 128;
+    } else if (value >= 240 && value <= 244) {
+      needed = 3;
+      min = value === 240 ? 144 : 128;
+    } else {
+      return i;
+    }
+    if (i + needed >= bytes.length) return i;
+    const firstContinuation = bytes[i + 1];
+    if (firstContinuation === void 0 || firstContinuation < min || firstContinuation > 191) return i + 1;
+    for (let j = 2; j <= needed; j += 1) {
+      const continuation = bytes[i + j];
+      if (continuation === void 0 || continuation < 128 || continuation > 191) return i + j;
+    }
+    if (value === 237) {
+      const second = bytes[i + 1];
+      if (second !== void 0 && second >= 160) return i;
+    }
+    if (value === 244) {
+      const second = bytes[i + 1];
+      if (second !== void 0 && second > 143) return i;
+    }
+    i += needed;
+  }
+  return -1;
+}
+function isCp949RoundTrip(bytes) {
+  const decoded = iconv.decode(bytes, "windows-949");
+  if (decoded.includes("\uFFFD")) return false;
+  return iconv.encode(decoded, "windows-949").equals(bytes);
+}
+function makeEolSummary(text) {
+  let crlf = 0;
+  let lf = 0;
+  let cr = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    const char = text[i];
+    if (char === "\r") {
+      if (text[i + 1] === "\n") {
+        crlf += 1;
+        i += 1;
+      } else {
+        cr += 1;
+      }
+    } else if (char === "\n") {
+      lf += 1;
+    }
+  }
+  const kinds = [crlf, lf, cr].filter((count) => count > 0).length;
+  return { crlf, lf, cr, mixed: kinds > 1, finalNewline: text.endsWith("\n") || text.endsWith("\r") };
+}
+function emptyEol() {
+  return { crlf: 0, lf: 0, cr: 0, mixed: false, finalNewline: false };
+}
+function isAscii(bytes) {
+  return bytes.every((byte) => byte <= 127);
+}
+function sha256(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+function analyzeBytes(bytes) {
+  const bom = detectBom(bytes);
+  const payload = bytes.subarray(bom.offset);
+  const nulOffset = bytes.indexOf(0);
+  if (nulOffset >= 0 && bom.encoding === null) {
+    return {
+      bom: bom.bom,
+      encoding: "binary",
+      decision: "binary",
+      asciiCompatible: false,
+      safeRead: false,
+      eol: emptyEol(),
+      candidates: [],
+      errors: [makeError("NOJIBAKE_BINARY_NUL", "Binary NUL byte detected.", { offset: nulOffset })]
+    };
+  }
+  if (bom.encoding !== null) {
+    if ((bom.encoding === "utf-16le" || bom.encoding === "utf-16be") && payload.length % 2 !== 0) {
+      return {
+        bom: bom.bom,
+        encoding: bom.encoding,
+        decision: "invalid",
+        asciiCompatible: false,
+        safeRead: false,
+        eol: emptyEol(),
+        candidates: [{ encoding: bom.encoding, valid: false, confidence: "confirmed" }],
+        errors: [makeError("NOJIBAKE_INVALID_UTF16_TRUNCATED", "UTF-16 payload has an odd byte length.", { encoding: bom.encoding })]
+      };
+    }
+    try {
+      const text = strictDecode(payload, bom.encoding);
+      return {
+        bom: bom.bom,
+        encoding: bom.encoding,
+        decision: "confirmed",
+        asciiCompatible: bom.encoding === "utf-8",
+        safeRead: true,
+        eol: makeEolSummary(text),
+        candidates: [{ encoding: bom.encoding, valid: true, confidence: "confirmed" }],
+        errors: []
+      };
+    } catch {
+      return {
+        bom: bom.bom,
+        encoding: bom.encoding,
+        decision: "invalid",
+        asciiCompatible: false,
+        safeRead: false,
+        eol: emptyEol(),
+        candidates: [{ encoding: bom.encoding, valid: false, confidence: "confirmed" }],
+        errors: [makeError("NOJIBAKE_INVALID_CONFIRMED_ENCODING", "BOM-confirmed text failed strict validation.", { encoding: bom.encoding })]
+      };
+    }
+  }
+  if (isAscii(bytes)) {
+    const text = strictDecode(bytes, "utf-8");
+    return {
+      bom: "none",
+      encoding: "ascii",
+      decision: "ascii",
+      asciiCompatible: true,
+      safeRead: true,
+      eol: makeEolSummary(text),
+      candidates: [
+        { encoding: "utf-8", valid: true, confidence: "candidate" },
+        { encoding: "windows-949", valid: true, confidence: "candidate" }
+      ],
+      errors: []
+    };
+  }
+  const candidates = [];
+  let utf8Text = null;
+  try {
+    utf8Text = strictDecode(bytes, "utf-8");
+    candidates.push({ encoding: "utf-8", valid: true, confidence: "candidate" });
+  } catch {
+    candidates.push({ encoding: "utf-8", valid: false, confidence: "candidate" });
+  }
+  const cp949Valid = isCp949RoundTrip(bytes);
+  candidates.push({ encoding: "windows-949", valid: cp949Valid, confidence: "candidate" });
+  const validCandidates = candidates.filter((candidate) => candidate.valid);
+  if (validCandidates.length > 1) {
+    return {
+      bom: "none",
+      encoding: "ambiguous",
+      decision: "ambiguous",
+      asciiCompatible: true,
+      safeRead: true,
+      eol: makeEolSummary(utf8Text ?? iconv.decode(bytes, "windows-949")),
+      candidates,
+      errors: []
+    };
+  }
+  if (utf8Text !== null) {
+    return {
+      bom: "none",
+      encoding: "utf-8",
+      decision: "candidate",
+      asciiCompatible: true,
+      safeRead: true,
+      eol: makeEolSummary(utf8Text),
+      candidates,
+      errors: []
+    };
+  }
+  if (cp949Valid) {
+    return {
+      bom: "none",
+      encoding: "windows-949",
+      decision: "candidate",
+      asciiCompatible: true,
+      safeRead: true,
+      eol: makeEolSummary(iconv.decode(bytes, "windows-949")),
+      candidates,
+      errors: []
+    };
+  }
+  return {
+    bom: "none",
+    encoding: "unknown",
+    decision: "invalid",
+    asciiCompatible: false,
+    safeRead: false,
+    eol: emptyEol(),
+    candidates,
+    errors: [
+      makeError("NOJIBAKE_INVALID_BYTES", "Bytes are not valid UTF-8 or windows-949.", {
+        utf8InvalidOffset: firstInvalidUtf8Offset(bytes)
+      })
+    ]
+  };
+}
+function buildInspectData(input) {
+  const analysis = analyzeBytes(input.bytes);
+  return {
+    path: input.path,
+    root: input.root,
+    length: input.bytes.length,
+    sha256: sha256(input.bytes),
+    bom: analysis.bom,
+    encoding: analysis.encoding,
+    decision: analysis.decision,
+    asciiCompatible: analysis.asciiCompatible,
+    eol: analysis.eol,
+    safeRead: analysis.safeRead,
+    safeRewrite: false,
+    candidates: analysis.candidates
+  };
+}
+function encodingErrors(bytes) {
+  return analyzeBytes(bytes).errors;
+}
+
+// src/format.ts
+import { relative, sep } from "path";
+function portable(path) {
+  return path.split(sep).join("/");
+}
+function displayInspectPath(data) {
+  if (data.root === null) return data.path;
+  const rel = relative(data.root, data.path);
+  return rel === "" ? "." : portable(rel);
+}
+function compactInspectData(data) {
+  return {
+    p: displayInspectPath(data),
+    l: data.length,
+    h: data.sha256,
+    bom: data.bom,
+    e: data.encoding,
+    d: data.decision,
+    sr: data.safeRead,
+    sw: data.safeRewrite,
+    mix: data.eol.mixed
+  };
+}
+function compactSummary(summary) {
+  return {
+    ok: summary.ok,
+    n: summary.totalFiles,
+    bytes: summary.totalBytes,
+    safe: summary.safeRead,
+    unsafe: summary.unsafeRead,
+    amb: summary.ambiguous,
+    mix: summary.mixedEol,
+    err: summary.errorFiles,
+    skip: summary.skipped,
+    d: summary.byDecision,
+    e: summary.byEncoding,
+    why: summary.byReason
+  };
+}
+function compactFile(file) {
+  const output = {
+    p: file.path,
+    l: file.length,
+    e: file.encoding,
+    d: file.decision,
+    sr: file.safeRead,
+    sw: file.safeRewrite
+  };
+  if (file.eol?.mixed === true) output.mix = true;
+  if (file.reasons.length > 0) output.why = file.reasons;
+  if (file.errors.length > 0) output.err = file.errors.map((error) => error.code);
+  return output;
+}
+function compactScanData(data) {
+  return { r: data.root, s: compactSummary(data.summary), f: data.files.map(compactFile) };
+}
+function compactGuardData(data) {
+  return {
+    r: data.root,
+    p: data.policies,
+    s: compactSummary(data.summary),
+    fail: data.failures.map((failure) => ({ p: failure.path, pol: failure.policies, why: failure.reasons }))
+  };
+}
+function formatInspectLine(data, errors) {
+  const status = errors.length === 0 && data.safeRead ? "OK" : "RISK";
+  const eol = data.eol.mixed ? "mixed-eol" : "stable-eol";
+  return `${status}	${data.encoding}	${data.decision}	${data.length}B	${eol}	${displayInspectPath(data)}`;
+}
+function formatScanLines(data) {
+  const lines = [
+    `root: ${data.root}`,
+    `files: ${data.summary.totalFiles}, safe: ${data.summary.safeRead}, unsafe: ${data.summary.unsafeRead}, ambiguous: ${data.summary.ambiguous}, mixed-eol: ${data.summary.mixedEol}, skipped: ${data.summary.skipped}, bytes: ${data.summary.totalBytes}`
+  ];
+  for (const file of data.files) {
+    const status = file.errors.length === 0 && file.safeRead ? "OK" : "RISK";
+    const reasons = file.reasons.length > 0 ? `	${file.reasons.join(",")}` : "";
+    lines.push(`${status}	${file.encoding ?? "unknown"}	${file.decision}	${file.length ?? 0}B	${file.path}${reasons}`);
+  }
+  return lines;
+}
+function formatGuardLines(data) {
+  const lines = [
+    `root: ${data.root}`,
+    `policies: ${data.policies.join(",")}`,
+    `failures: ${data.failures.length}`
+  ];
+  for (const failure of data.failures) {
+    lines.push(`FAIL	${failure.policies.join(",")}	${failure.reasons.join(",")}	${failure.path}`);
+  }
+  return lines;
+}
+
+// src/pathSafety.ts
+import { lstatSync, realpathSync, statSync } from "fs";
+import { isAbsolute, parse, resolve as resolve2, relative as relative2, sep as sep2 } from "path";
+function hasAdsNotation(inputPath) {
+  const parsed = parse(inputPath);
+  const withoutDrive = parsed.root.startsWith(parsed.root[0] ?? "") && /^[A-Za-z]:[\\/]?$/.test(parsed.root) ? inputPath.slice(2) : inputPath;
+  return withoutDrive.includes(":");
+}
+function isInsideRoot(realPath, realRoot) {
+  const rel = relative2(realRoot, realPath);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+function linkedComponent(path) {
+  const parsed = parse(path);
+  const parts = relative2(parsed.root, path).split(/[\\/]+/).filter((part) => part.length > 0);
+  let current = parsed.root;
+  for (const part of parts) {
+    current = resolve2(current, part);
+    if (lstatSync(current).isSymbolicLink()) return current;
+  }
+  return null;
+}
+function linkedDescendant(path, root) {
+  const rel = relative2(root, path);
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return null;
+  let current = root;
+  for (const part of rel.split(/[\\/]+/).filter((entry) => entry.length > 0)) {
+    current = resolve2(current, part);
+    if (lstatSync(current).isSymbolicLink()) return current;
+  }
+  return null;
+}
+function resolveSafePath(inputPath, root) {
+  const resolvedRoot = root === void 0 ? null : resolve2(root);
+  const base = resolvedRoot ?? process.cwd();
+  const resolvedPath = resolve2(base, inputPath);
+  const errors = [];
+  if (hasAdsNotation(inputPath)) {
+    errors.push(makeError("NOJIBAKE_PATH_ADS_REJECTED", "Windows alternate data stream notation is rejected."));
+  }
+  if (resolvedRoot !== null) {
+    try {
+      if (lstatSync(resolvedRoot).isSymbolicLink()) {
+        errors.push(makeError("NOJIBAKE_ROOT_LINK_REJECTED", "Symlink or reparse root is rejected for MVP safety.", { root: resolvedRoot }));
+        return { ok: false, path: resolvedPath, root: resolvedRoot, errors };
+      }
+    } catch {
+      errors.push(makeError("NOJIBAKE_ROOT_NOT_FOUND", "Root does not exist.", { root: resolvedRoot }));
+      return { ok: false, path: resolvedPath, root: resolvedRoot, errors };
+    }
+  }
+  let pathLstat;
+  try {
+    pathLstat = lstatSync(resolvedPath);
+  } catch {
+    errors.push(makeError("NOJIBAKE_PATH_NOT_FOUND", "Path does not exist.", { path: resolvedPath }));
+    return { ok: false, path: resolvedPath, root: resolvedRoot, errors };
+  }
+  if (pathLstat.isSymbolicLink()) {
+    errors.push(makeError("NOJIBAKE_PATH_LINK_REJECTED", "Symlink or reparse traversal is rejected for MVP safety.", { path: resolvedPath }));
+    return { ok: false, path: resolvedPath, root: resolvedRoot, errors };
+  }
+  const pathLink = resolvedRoot === null ? linkedComponent(resolvedPath) : linkedDescendant(resolvedPath, resolvedRoot);
+  if (pathLink !== null) {
+    errors.push(makeError("NOJIBAKE_PATH_LINK_REJECTED", "Symlink or reparse traversal is rejected for MVP safety.", { path: pathLink }));
+    return { ok: false, path: resolvedPath, root: resolvedRoot, errors };
+  }
+  const pathStat = statSync(resolvedPath);
+  if (pathStat.isDirectory()) {
+    errors.push(makeError("NOJIBAKE_PATH_DIRECTORY_REJECTED", "Directories cannot be inspected as files.", { path: resolvedPath }));
+  } else if (!pathStat.isFile()) {
+    errors.push(makeError("NOJIBAKE_PATH_NOT_FILE", "Only regular files can be inspected.", { path: resolvedPath }));
+  }
+  if (resolvedRoot !== null) {
+    const realRoot = realpathSync(resolvedRoot);
+    const realTarget = realpathSync(resolvedPath);
+    if (!isInsideRoot(realTarget, realRoot)) {
+      errors.push(makeError("NOJIBAKE_PATH_OUTSIDE_ROOT", "Path resolves outside the configured root boundary.", { path: realTarget, root: realRoot }));
+    }
+  }
+  return { ok: errors.length === 0, path: resolvedPath.split(sep2).join("/"), root: resolvedRoot, errors };
+}
+
+// src/scan.ts
+import { readFileSync as readFileSync3, readdirSync, statSync as statSync2 } from "fs";
+import { relative as relative3, resolve as resolve3, sep as sep3 } from "path";
+var defaultIgnoredDirs = /* @__PURE__ */ new Set([".git", "node_modules", "dist", "coverage"]);
+var allowedPolicies2 = /* @__PURE__ */ new Set(["unsafe", "ambiguous", "mixed-eol", "non-utf8", "disallowed-encoding"]);
+function portable2(path) {
+  return path.split(sep3).join("/");
+}
+function relativeToRoot(root, path) {
+  const rel = relative3(root, path);
+  return rel === "" ? "." : portable2(rel);
+}
+function emptySummary(skipped) {
+  return {
+    ok: true,
+    totalFiles: 0,
+    totalBytes: 0,
+    safeRead: 0,
+    unsafeRead: 0,
+    safeRewrite: 0,
+    ambiguous: 0,
+    mixedEol: 0,
+    errorFiles: 0,
+    skipped,
+    byDecision: {},
+    byEncoding: {},
+    byReason: {}
+  };
+}
+function addCount(record, key) {
+  record[key] = (record[key] ?? 0) + 1;
+}
+function summarize(files, skipped) {
+  const summary = emptySummary(skipped.length);
+  for (const file of files) {
+    summary.totalFiles += 1;
+    summary.totalBytes += file.length ?? 0;
+    if (file.safeRead && file.errors.length === 0) {
+      summary.safeRead += 1;
+    } else {
+      summary.unsafeRead += 1;
+    }
+    if (file.safeRewrite) summary.safeRewrite += 1;
+    if (file.decision === "ambiguous") summary.ambiguous += 1;
+    if (file.eol?.mixed === true) summary.mixedEol += 1;
+    if (file.errors.length > 0) summary.errorFiles += 1;
+    addCount(summary.byDecision, file.decision);
+    addCount(summary.byEncoding, file.encoding ?? "unknown");
+    for (const reason of file.reasons) addCount(summary.byReason, reason);
+  }
+  summary.ok = summary.unsafeRead === 0;
+  return summary;
+}
+function normalizeIgnorePattern(pattern) {
+  return pattern.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\//, "");
+}
+function escapeRegexChar(char) {
+  return /[|\\{}()[\]^$+?.]/.test(char) ? `\\${char}` : char;
+}
+function globToRegex(pattern) {
+  let source = "^";
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index];
+    if (char === "*") {
+      if (pattern[index + 1] === "*") {
+        source += ".*";
+        index += 1;
+      } else {
+        source += "[^/]*";
+      }
+    } else {
+      source += escapeRegexChar(char ?? "");
+    }
+  }
+  return new RegExp(`${source}$`);
+}
+function isIgnored(path, patterns) {
+  const normalizedPath = normalizeIgnorePattern(path);
+  return patterns.some((rawPattern) => {
+    const pattern = normalizeIgnorePattern(rawPattern);
+    if (pattern === "") return false;
+    if (pattern.endsWith("/**")) {
+      const prefix = pattern.slice(0, -3);
+      return normalizedPath === prefix || normalizedPath.startsWith(`${prefix}/`);
+    }
+    if (!pattern.includes("*")) {
+      return normalizedPath === pattern || normalizedPath.startsWith(`${pattern}/`);
+    }
+    return globToRegex(pattern).test(normalizedPath);
+  });
+}
+function collectRecursive(root, maxFiles, includeIgnored, ignore) {
+  const paths = [];
+  const skipped = [];
+  const pending = [root];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (current === void 0) continue;
+    const entries = readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const fullPath = resolve3(current, entry.name);
+      const relPath = relativeToRoot(root, fullPath);
+      if (isIgnored(relPath, ignore)) {
+        skipped.push({ path: relPath, reason: "ignored-path" });
+        continue;
+      }
+      if (entry.isSymbolicLink()) {
+        skipped.push({ path: relPath, reason: "symlink" });
+        continue;
+      }
+      if (entry.isDirectory()) {
+        if (!includeIgnored && defaultIgnoredDirs.has(entry.name)) {
+          skipped.push({ path: relPath, reason: "ignored-directory" });
+          continue;
+        }
+        pending.push(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) {
+        skipped.push({ path: relPath, reason: "not-regular-file" });
+        continue;
+      }
+      if (paths.length >= maxFiles) {
+        skipped.push({ path: relPath, reason: "max-files-exceeded" });
+        continue;
+      }
+      paths.push(relPath);
+    }
+  }
+  return { paths: paths.sort(), skipped: skipped.sort((a, b) => a.path.localeCompare(b.path)) };
+}
+function uniqueReasons(reasons) {
+  return [...new Set(reasons)];
+}
+function reasonCodesFor(file, allowEncodings) {
+  const reasons = [];
+  if (file.errors.some((error) => error.code.startsWith("NOJIBAKE_PATH_"))) reasons.push("path:error");
+  if (file.errors.some((error) => error.code === "NOJIBAKE_FILE_READ_FAILED")) reasons.push("file:read-failed");
+  if (file.errors.some((error) => error.code === "NOJIBAKE_FILE_TOO_LARGE")) reasons.push("large:file");
+  if (!file.safeRead || file.errors.length > 0) reasons.push("read:unsafe");
+  if (file.decision === "binary" || file.errors.some((error) => error.code === "NOJIBAKE_BINARY_NUL")) reasons.push("encoding:binary");
+  if (file.decision === "invalid") reasons.push("encoding:invalid");
+  if (file.decision === "ambiguous") reasons.push("encoding:ambiguous");
+  if (file.encoding !== null && file.encoding !== "utf-8" && file.encoding !== "ascii") reasons.push("encoding:non-utf8");
+  if (allowEncodings !== null && file.encoding !== null && !allowEncodings.has(file.encoding)) reasons.push("encoding:disallowed");
+  if (file.eol?.mixed === true) reasons.push("eol:mixed");
+  return uniqueReasons(reasons);
+}
+function withReasons(file, allowEncodings) {
+  const complete = { ...file, reasons: [] };
+  return { ...complete, reasons: reasonCodesFor(complete, allowEncodings) };
+}
+function inspectOne(root, inputPath, options) {
+  const safe = resolveSafePath(inputPath, root);
+  const displayPath = safe.root === null ? safe.path : relativeToRoot(safe.root, safe.path);
+  if (!safe.ok) {
+    return withReasons({
+      path: displayPath,
+      ok: false,
+      length: null,
+      sha256: null,
+      bom: null,
+      encoding: null,
+      decision: "error",
+      asciiCompatible: null,
+      eol: null,
+      safeRead: false,
+      safeRewrite: false,
+      candidates: [],
+      errors: safe.errors
+    }, options.allowEncodings);
+  }
+  const fileSize = statSync2(safe.path).size;
+  if (options.maxBytes !== void 0 && fileSize > options.maxBytes) {
+    return withReasons({
+      path: displayPath,
+      ok: false,
+      length: fileSize,
+      sha256: null,
+      bom: null,
+      encoding: null,
+      decision: "error",
+      asciiCompatible: null,
+      eol: null,
+      safeRead: false,
+      safeRewrite: false,
+      candidates: [],
+      errors: [makeError("NOJIBAKE_FILE_TOO_LARGE", "File exceeds maxBytes and was not read.", { path: displayPath, length: fileSize, maxBytes: options.maxBytes })]
+    }, options.allowEncodings);
+  }
+  let bytes;
+  try {
+    bytes = readFileSync3(safe.path);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "File read failed.";
+    return withReasons({
+      path: displayPath,
+      ok: false,
+      length: null,
+      sha256: null,
+      bom: null,
+      encoding: null,
+      decision: "error",
+      asciiCompatible: null,
+      eol: null,
+      safeRead: false,
+      safeRewrite: false,
+      candidates: [],
+      errors: [makeError("NOJIBAKE_FILE_READ_FAILED", message, { path: displayPath })]
+    }, options.allowEncodings);
+  }
+  const data = buildInspectData({ path: safe.path, root: safe.root, bytes });
+  const errors = encodingErrors(bytes);
+  return withReasons({
+    path: displayPath,
+    ok: errors.length === 0,
+    length: data.length,
+    sha256: data.sha256,
+    bom: data.bom,
+    encoding: data.encoding,
+    decision: data.decision,
+    asciiCompatible: data.asciiCompatible,
+    eol: data.eol,
+    safeRead: data.safeRead,
+    safeRewrite: data.safeRewrite,
+    candidates: data.candidates,
+    errors
+  }, options.allowEncodings);
+}
+function normalizeInputPaths(paths) {
+  return [...new Set((paths ?? []).flatMap((value) => value.split(/\r?\n/)).map((value) => value.trim()).filter(Boolean))];
+}
+function parsePositiveInteger2(value) {
+  if (value === void 0) return void 0;
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed < 1) return void 0;
+  return parsed;
+}
+function scanPaths(options = {}) {
+  const root = resolve3(options.root ?? process.cwd());
+  const rootStat = statSync2(root);
+  if (!rootStat.isDirectory()) {
+    throw new Error(`Scan root is not a directory: ${root}`);
+  }
+  const ignore = (options.ignore ?? []).map(normalizeIgnorePattern).filter(Boolean);
+  const inputPaths = normalizeInputPaths(options.paths);
+  const skippedInputs = [];
+  const activeInputPaths = inputPaths.filter((path) => {
+    if (!isIgnored(path, ignore)) return true;
+    skippedInputs.push({ path: normalizeIgnorePattern(path), reason: "ignored-path" });
+    return false;
+  });
+  const useExplicitPaths = options.useExplicitPaths === true || activeInputPaths.length > 0;
+  const collected = useExplicitPaths ? { paths: activeInputPaths, skipped: skippedInputs } : collectRecursive(root, options.maxFiles ?? 5e3, options.includeIgnored === true, ignore);
+  const allowEncodings = options.allowEncodings === void 0 ? null : new Set(options.allowEncodings.map((encoding) => encoding.toLowerCase()));
+  const inspectOptions = { allowEncodings };
+  if (options.maxBytes !== void 0) inspectOptions.maxBytes = options.maxBytes;
+  const files = collected.paths.map((path) => inspectOne(root, path, inspectOptions));
+  return { root: portable2(root), files, skipped: collected.skipped, summary: summarize(files, collected.skipped) };
+}
+function policyReasons(policy, file) {
+  if (policy === "unsafe") return file.reasons.filter((reason) => ["path:error", "file:read-failed", "large:file", "read:unsafe", "encoding:binary", "encoding:invalid"].includes(reason));
+  if (policy === "ambiguous" && file.reasons.includes("encoding:ambiguous")) return ["encoding:ambiguous"];
+  if (policy === "mixed-eol" && file.reasons.includes("eol:mixed")) return ["eol:mixed"];
+  if (policy === "non-utf8" && file.reasons.includes("encoding:non-utf8")) return ["encoding:non-utf8"];
+  if (policy === "disallowed-encoding" && file.reasons.includes("encoding:disallowed")) return ["encoding:disallowed"];
+  return [];
+}
+function parseGuardPolicies(value) {
+  const raw = Array.isArray(value) ? value : value === void 0 ? ["unsafe"] : value.split(",").map((item) => item.trim()).filter(Boolean);
+  const policies = [];
+  for (const item of raw) {
+    if (!allowedPolicies2.has(item)) {
+      throw new Error(`Unknown guard policy: ${item}`);
+    }
+    policies.push(item);
+  }
+  return policies.length > 0 ? [...new Set(policies)] : ["unsafe"];
+}
+function guardScan(scan, policies) {
+  const failures = [];
+  for (const file of scan.files) {
+    const matchedPolicies = policies.filter((policy) => policyReasons(policy, file).length > 0);
+    const reasons = uniqueReasons(matchedPolicies.flatMap((policy) => policyReasons(policy, file)));
+    if (matchedPolicies.length > 0) failures.push({ path: file.path, policies: matchedPolicies, reasons });
+  }
+  return { root: scan.root, policies, summary: scan.summary, failures };
+}
+
+// src/schema.ts
+var resultSchema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://github.com/don9x2E/nojibake/schemas/result-envelope.json",
+  title: "Nojibake Result Envelope",
+  type: "object",
+  required: ["schemaVersion", "toolVersion", "invocationId", "ok", "command", "summary", "data", "errors", "warnings"],
+  properties: {
+    schemaVersion: { type: "string" },
+    toolVersion: { type: "string" },
+    invocationId: { type: "string" },
+    ok: { type: "boolean" },
+    command: { type: "string" },
+    summary: { type: "string" },
+    data: {},
+    errors: { type: "array" },
+    warnings: { type: "array" }
+  },
+  additionalProperties: false
+};
+
+// src/cli.ts
+function writeJson(value, compact = false) {
+  process.stdout.write(`${JSON.stringify(value, null, compact ? 0 : 2)}
+`);
+}
+function writeLines(lines) {
+  process.stdout.write(`${lines.join("\n")}
+`);
+}
+function writeUsageError(command, code, message) {
+  writeJson(envelope({
+    ok: false,
+    command,
+    summary: "CLI usage error.",
+    data: null,
+    errors: [{ code, message }]
+  }));
+  process.exitCode = 2;
+}
+function requireJsonOption(json, command) {
+  if (json !== true) {
+    writeUsageError(command, "NOJIBAKE_JSON_REQUIRED", "Pass --json.");
+    return false;
+  }
+  return true;
+}
+function requireStructuredOutput(options, command) {
+  if (options.pretty === true) return "pretty";
+  if (options.json === true) return "json";
+  writeUsageError(command, "NOJIBAKE_JSON_REQUIRED", "Pass --json, or pass --pretty for human-readable output.");
+  return null;
+}
+function parseCommand(argv) {
+  return argv.slice(2).filter((arg) => !arg.startsWith("-")).join(" ");
+}
+function configureCommand(command) {
+  return command.helpOption(false).showHelpAfterError(false).showSuggestionAfterError(false);
+}
+function collectPath(value, previous) {
+  previous.push(value);
+  return previous;
+}
+function readStdinPaths() {
+  if (process.stdin.isTTY === true) return [];
+  return readFileSync4(0, "utf8").split(/\r?\n/).map((value) => value.trim()).filter(Boolean);
+}
+function mergeStrings(configValues, cliValues) {
+  const merged = [...configValues ?? [], ...cliValues ?? []].map((value) => value.trim()).filter(Boolean);
+  return merged.length > 0 ? [...new Set(merged)] : void 0;
+}
+function applyNumberOption(target, key, cliValue, configValue) {
+  const parsed = parsePositiveInteger2(cliValue);
+  const value = parsed ?? configValue;
+  if (value !== void 0) target[key] = value;
+}
+function scanCommandOptions(options) {
+  const root = options.root ?? process.cwd();
+  const config = loadConfig(root);
+  const scanOptions = { root };
+  const paths = [...options.path ?? []];
+  const useStdinPaths = options.stdinPaths === true;
+  if (useStdinPaths) paths.push(...readStdinPaths());
+  if (paths.length > 0) scanOptions.paths = paths;
+  if (paths.length > 0 || useStdinPaths) scanOptions.useExplicitPaths = true;
+  applyNumberOption(scanOptions, "maxFiles", options.maxFiles, config.maxFiles);
+  applyNumberOption(scanOptions, "maxBytes", options.maxBytes, config.maxBytes);
+  if (options.includeIgnored === true || config.includeIgnored === true) scanOptions.includeIgnored = true;
+  const ignore = mergeStrings(config.ignore, options.ignore);
+  if (ignore !== void 0) scanOptions.ignore = ignore;
+  const allowEncodings = mergeStrings(config.allowEncodings, options.allowEncoding);
+  if (allowEncodings !== void 0) scanOptions.allowEncodings = allowEncodings;
+  return { scanOptions, config };
+}
+function runScanCommand(options) {
+  const command = "scan";
+  const output = requireStructuredOutput(options, command);
+  if (output === null) return;
+  try {
+    const { scanOptions } = scanCommandOptions(options);
+    const scan = scanPaths(scanOptions);
+    if (output === "pretty") {
+      writeLines(formatScanLines(scan));
+      return;
+    }
+    writeJson(envelope({ ok: true, command, summary: `Scanned ${scan.summary.totalFiles} files.`, data: options.compact ? compactScanData(scan) : scan }), options.compact === true);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Scan failed.";
+    writeUsageError(command, "NOJIBAKE_SCAN_FAILED", message);
+  }
+}
+function runGuardCommand(options) {
+  const command = "guard";
+  const output = requireStructuredOutput(options, command);
+  if (output === null) return;
+  try {
+    const { scanOptions, config } = scanCommandOptions(options);
+    const scan = scanPaths(scanOptions);
+    const policies = parseGuardPolicies(options.failOn ?? config.failOn);
+    const guard = guardScan(scan, policies);
+    const ok = guard.failures.length === 0;
+    if (output === "pretty") {
+      writeLines(formatGuardLines(guard));
+    } else {
+      writeJson(envelope({ ok, command, summary: ok ? "Guard passed." : `Guard failed for ${guard.failures.length} files.`, data: options.compact ? compactGuardData(guard) : guard }), options.compact === true);
+    }
+    if (!ok) process.exitCode = 1;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Guard failed.";
+    writeUsageError(command, "NOJIBAKE_GUARD_FAILED", message);
+  }
+}
+function createProgram() {
+  const program = configureCommand(new Command());
+  program.name("nojibake").description("Read-only text encoding inspection CLI.").exitOverride().configureOutput({ writeOut: () => void 0, writeErr: () => void 0 });
+  program.action(() => {
+    writeUsageError("", "NOJIBAKE_CLI_USAGE", "Missing command.");
+  });
+  configureCommand(program.command("version").option("--json", "emit JSON").action((options) => {
+    if (!requireJsonOption(options.json, "version")) return;
+    const data = { name: packageInfo.name, version: packageInfo.version };
+    writeJson(envelope({ ok: true, command: "version", summary: `Nojibake ${packageInfo.version}`, data }));
+  }));
+  const schema = configureCommand(program.command("schema"));
+  schema.action(() => {
+    writeUsageError("schema", "NOJIBAKE_CLI_USAGE", "Missing schema command.");
+  });
+  configureCommand(schema.command("result").option("--json", "emit JSON").action((options) => {
+    if (!requireJsonOption(options.json, "schema result")) return;
+    writeJson(envelope({ ok: true, command: "schema result", summary: "Result envelope schema.", data: resultSchema }));
+  }));
+  const inspect = configureCommand(program.command("inspect"));
+  inspect.action(() => {
+    writeUsageError("inspect", "NOJIBAKE_CLI_USAGE", "Missing inspect command.");
+  });
+  configureCommand(inspect.command("path").option("--root <root>", "optional root boundary").option("--path <file>", "file to inspect").option("--json", "emit JSON").option("--compact", "emit compact JSON for agent contexts").option("--pretty", "emit human-readable one-line summary").action((options) => {
+    const command = "inspect path";
+    const output = requireStructuredOutput(options, command);
+    if (output === null) return;
+    if (options.path === void 0) {
+      writeUsageError(command, "NOJIBAKE_PATH_REQUIRED", "Pass --path <file>.");
+      return;
+    }
+    const safe = resolveSafePath(options.path, options.root);
+    if (!safe.ok) {
+      writeJson(envelope({ ok: false, command, summary: "Path rejected.", data: null, errors: safe.errors }), options.compact === true);
+      process.exitCode = 2;
+      return;
+    }
+    let bytes;
+    try {
+      bytes = readFileSync4(safe.path);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "File read failed.";
+      writeJson(envelope({
+        ok: false,
+        command,
+        summary: "File could not be read.",
+        data: null,
+        errors: [{ code: "NOJIBAKE_FILE_READ_FAILED", message, details: { path: safe.path } }]
+      }), options.compact === true);
+      process.exitCode = 2;
+      return;
+    }
+    const data = buildInspectData({ path: safe.path, root: safe.root, bytes });
+    const errors = encodingErrors(bytes);
+    if (output === "pretty") {
+      writeLines([formatInspectLine(data, errors)]);
+    } else {
+      writeJson(envelope({
+        ok: errors.length === 0,
+        command,
+        summary: errors.length === 0 ? `Inspected ${data.length} bytes.` : "File bytes failed encoding validation.",
+        data: options.compact === true ? compactInspectData(data) : data,
+        errors
+      }), options.compact === true);
+    }
+    if (errors.length > 0) process.exitCode = 1;
+  }));
+  configureCommand(program.command("scan").option("--root <root>", "root directory to scan", process.cwd()).option("--path <file>", "specific file to scan; can be repeated", collectPath, []).option("--stdin-paths", "read newline-separated paths from stdin").option("--max-files <n>", "maximum files for recursive scan").option("--max-bytes <n>", "maximum bytes to read per file").option("--include-ignored", "include default ignored directories such as node_modules and dist").option("--ignore <pattern>", "ignore pattern; can be repeated", collectPath, []).option("--allow-encoding <encoding>", "allowed encoding; can be repeated", collectPath, []).option("--json", "emit JSON").option("--compact", "emit compact JSON for agent contexts").option("--pretty", "emit human-readable summary").action(runScanCommand));
+  configureCommand(program.command("guard").option("--root <root>", "root directory to scan", process.cwd()).option("--path <file>", "specific file to guard; can be repeated", collectPath, []).option("--stdin-paths", "read newline-separated paths from stdin").option("--max-files <n>", "maximum files for recursive scan").option("--max-bytes <n>", "maximum bytes to read per file").option("--include-ignored", "include default ignored directories such as node_modules and dist").option("--ignore <pattern>", "ignore pattern; can be repeated", collectPath, []).option("--allow-encoding <encoding>", "allowed encoding; can be repeated", collectPath, []).option("--fail-on <policies>", "comma-separated policies: unsafe,ambiguous,mixed-eol,non-utf8,disallowed-encoding").option("--json", "emit JSON").option("--compact", "emit compact JSON for agent contexts").option("--pretty", "emit human-readable summary").action(runGuardCommand));
+  return program;
+}
+function run(argv = process.argv) {
+  try {
+    createProgram().parse(argv);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "CLI parse failed.";
+    writeUsageError(parseCommand(argv), "NOJIBAKE_CLI_USAGE", message);
+  }
+}
+function isDirectCliInvocation(argv = process.argv) {
+  const argvPath = argv[1];
+  if (argvPath === void 0) return false;
+  try {
+    return realpathSync2(fileURLToPath2(import.meta.url)) === realpathSync2(argvPath);
+  } catch {
+    return import.meta.url === `file://${argvPath.replace(/\\/g, "/")}` || argvPath.endsWith("cli.js");
+  }
+}
+if (isDirectCliInvocation()) {
+  run();
+}
+export {
+  createProgram,
+  run
+};