branch-never 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# branch-never
+
+`branch-never` is a static-analysis CLI for TypeScript and JavaScript projects. It scans source files for high-value conditional branches and flags the ones whose key tokens never appear in any test file.
+
+It is intentionally heuristic-based: no runtime instrumentation, no AST parser, and no execution. The goal is to quickly surface risky branches that look untested.
+
+## Install
+
+```bash
+pnpm add -D branch-never
+```
+
+Or run it locally in this repository:
+
+```bash
+pnpm install
+pnpm build
+node dist/index.js src --tests test
+```
+
+## Usage
+
+```bash
+branch-never <src-dir> [options]
+
+Options:
+  --tests <dir>     Test directory (default: test/)
+  --json            JSON output
+  --no-fail         Don't exit 1 when uncovered branches found
+  --pattern <type>  Only check: env|retry|error|feature|all (default: all)
+  --threshold <pct> Fail if coverage below N% (default: 0, fail on any)
+```
+
+Example output:
+
+```text
+Analyzing import graph and branches...
+
+Uncovered branches (never referenced in any test):
+  src/api.ts:42    if (process.env.NODE_ENV === 'production')  <- env branch, no test
+
+Covered branches:
+  src/auth.ts:15   if (!token)  <- referenced in test/auth.test.ts
+
+Summary: 1 uncovered branches, 1 covered. Coverage: 50%
+```
+
+## What It Detects
+
+The extractor looks for these branch shapes using regex:
+
+- `if (...)`
+- `catch (...) { ... }` blocks with error property checks
+- Ternary conditions like `condition ? a : b`
+- Short-circuit expressions like `a && b` or `a || b` when they include env/config checks
+
+It only reports branches whose condition matches one of these interesting patterns:
+
+- `process.env.*` and `NODE_ENV === "..."` checks
+- Retry and timeout logic such as `retries > 3`, `attempts >= 2`, `timeout`
+- Error type/status/code checks such as `err.code === "EXPIRED"`
+- Feature flags such as `feature.someFlag`
+
+Coverage is approximated by extracting tokens from each condition and checking whether any test file contains them.
+
+## Compared To Istanbul or c8
+
+`branch-never` is not a replacement for Istanbul or `c8`.
+
+- `branch-never` is static and heuristic-based, so it can run without executing tests.
+- Istanbul and `c8` are runtime coverage tools, so they produce precise statement and branch coverage from real execution.
+- `branch-never` is useful when you want a fast signal about suspicious branches before full runtime coverage is available.
+
+The tradeoff is precision: runtime coverage is more accurate, while `branch-never` is faster to adopt and easier to run in lightweight environments.

package/dist/extractor.d.ts

@@ -0,0 +1,12 @@
+export type PatternType = "env" | "retry" | "error" | "feature";
+export interface BranchMatch {
+    file: string;
+    line: number;
+    conditionText: string;
+    pattern: PatternType;
+    kind: "if" | "catch" | "ternary" | "short-circuit";
+}
+export declare function extractInterestingBranches(code: string, file?: string): BranchMatch[];
+export declare function extractBranchesFromDirectory(srcDir: string, patternType?: PatternType | "all"): Promise<BranchMatch[]>;
+export declare function detectPattern(conditionText: string, kind?: BranchMatch["kind"]): PatternType | null;
+export declare function normalizeCondition(conditionText: string): string;

package/dist/extractor.js

@@ -0,0 +1,124 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { glob } from "glob";
+const PATTERN_DESCRIPTORS = [
+    {
+        type: "env",
+        regexes: [
+            /process\.env\.\w+/,
+            /\bNODE_ENV\s*===?\s*['"`]\w+['"`]/,
+            /\b(?:config|cfg)\.\w+/i
+        ]
+    },
+    {
+        type: "retry",
+        regexes: [
+            /\bretries?\s*[><=!]/i,
+            /\battempts?\s*[><=!]/i,
+            /\btimeout\b/i
+        ]
+    },
+    {
+        type: "error",
+        regexes: [
+            /\berr(?:or)?\.(?:code|status|type)\s*[=!]/i,
+            /\be\.(?:code|status|type)\s*[=!]/i
+        ]
+    },
+    {
+        type: "feature",
+        regexes: [
+            /\bfeature\s*\.\s*\w+/i
+        ]
+    }
+];
+const FILE_GLOB = "**/*.{ts,tsx,js,jsx,mjs,cjs}";
+export function extractInterestingBranches(code, file = "<memory>") {
+    const branches = [];
+    const seen = new Set();
+    const addBranch = (conditionText, index, kind) => {
+        const normalized = normalizeCondition(conditionText);
+        const pattern = detectPattern(normalized, kind);
+        if (!pattern) {
+            return;
+        }
+        const line = indexToLine(code, index);
+        const key = `${line}:${kind}:${normalized}`;
+        if (seen.has(key)) {
+            return;
+        }
+        seen.add(key);
+        branches.push({
+            file,
+            line,
+            conditionText: normalized,
+            pattern,
+            kind
+        });
+    };
+    for (const match of code.matchAll(/\bif\s*\(([\s\S]*?)\)/g)) {
+        addBranch(match[1] ?? "", match.index ?? 0, "if");
+    }
+    for (const match of code.matchAll(/\bcatch\s*\(([\s\S]*?)\)\s*\{([\s\S]*?)\}/g)) {
+        const errorName = (match[1] ?? "").trim();
+        const body = match[2] ?? "";
+        if (errorName) {
+            for (const nested of body.matchAll(new RegExp(`\\b${escapeRegExp(errorName)}\\.(?:code|status|type)\\s*[=!]==?\\s*([\\w"'"\`.-]+)`, "g"))) {
+                addBranch(nested[0] ?? "", (match.index ?? 0) + (nested.index ?? 0), "catch");
+            }
+        }
+    }
+    for (const match of code.matchAll(/([^\n;]+?)\?([^\n;]+?):([^\n;]+?)(?=[;\n])/g)) {
+        addBranch(match[1] ?? "", match.index ?? 0, "ternary");
+    }
+    for (const match of code.matchAll(/([^\n;]+?(?:&&|\|\|)[^\n;]+)(?=[;\n])/g)) {
+        const expression = normalizeCondition(match[1] ?? "");
+        if (/(process\.env\.|NODE_ENV|config\.|cfg\.)/i.test(expression)) {
+            addBranch(expression, match.index ?? 0, "short-circuit");
+        }
+    }
+    return branches.sort((left, right) => left.line - right.line);
+}
+export async function extractBranchesFromDirectory(srcDir, patternType = "all") {
+    const absoluteDir = path.resolve(srcDir);
+    const files = await glob(FILE_GLOB, {
+        absolute: true,
+        cwd: absoluteDir,
+        nodir: true,
+        ignore: ["**/*.d.ts"]
+    });
+    const branches = await Promise.all(files.map(async (file) => {
+        const code = await readFile(file, "utf8");
+        return extractInterestingBranches(code, path.relative(process.cwd(), file));
+    }));
+    return branches
+        .flat()
+        .filter((branch) => patternType === "all" || branch.pattern === patternType)
+        .sort((left, right) => {
+        if (left.file === right.file) {
+            return left.line - right.line;
+        }
+        return left.file.localeCompare(right.file);
+    });
+}
+export function detectPattern(conditionText, kind) {
+    for (const descriptor of PATTERN_DESCRIPTORS) {
+        if (descriptor.regexes.some((regex) => regex.test(conditionText))) {
+            return descriptor.type;
+        }
+    }
+    if (kind === "short-circuit" && /(process\.env\.|NODE_ENV|config\.|cfg\.)/i.test(conditionText)) {
+        return "env";
+    }
+    return null;
+}
+export function normalizeCondition(conditionText) {
+    return conditionText.replace(/\s+/g, " ").trim();
+}
+function indexToLine(code, index) {
+    return code.slice(0, index).split("\n").length;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//# sourceMappingURL=extractor.js.map

package/dist/extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractor.js","sourceRoot":"","sources":["../src/extractor.ts"],"names":[],"mappings":"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"}

package/dist/formatter.d.ts

@@ -0,0 +1,9 @@
+import type { BranchCoverage } from "./matcher.js";
+import type { CoverageSummary } from "./scorer.js";
+export interface FormatPayload {
+    covered: BranchCoverage[];
+    uncovered: BranchCoverage[];
+    summary: CoverageSummary;
+}
+export declare function formatText(payload: FormatPayload): string;
+export declare function formatJson(payload: FormatPayload): string;

package/dist/formatter.js

@@ -0,0 +1,47 @@
+import chalk from "chalk";
+export function formatText(payload) {
+    const lines = [];
+    lines.push(chalk.bold("Analyzing import graph and branches..."));
+    lines.push("");
+    lines.push(chalk.bold.red("Uncovered branches (never referenced in any test):"));
+    if (payload.uncovered.length === 0) {
+        lines.push(`  ${chalk.green("None")}`);
+    }
+    else {
+        for (const branch of payload.uncovered) {
+            lines.push(`  ${chalk.red(`${branch.file}:${branch.line}`)}    ${branch.conditionText}  ${chalk.dim(`\u2190 ${describeUncovered(branch)}`)}`);
+        }
+    }
+    lines.push("");
+    lines.push(chalk.bold.green("Covered branches:"));
+    if (payload.covered.length === 0) {
+        lines.push(`  ${chalk.yellow("None")}`);
+    }
+    else {
+        for (const branch of payload.covered) {
+            const referencedBy = branch.matchedTestFiles[0] ?? "test";
+            lines.push(`  ${chalk.green(`${branch.file}:${branch.line}`)}    ${branch.conditionText}  ${chalk.dim(`\u2190 referenced in ${referencedBy}`)}`);
+        }
+    }
+    lines.push("");
+    lines.push(`Summary: ${payload.summary.uncoveredCount} uncovered branches, ${payload.summary.coveredCount} covered. Coverage: ${payload.summary.coveragePercent}%`);
+    return lines.join("\n");
+}
+export function formatJson(payload) {
+    return JSON.stringify(payload, null, 2);
+}
+function describeUncovered(branch) {
+    switch (branch.pattern) {
+        case "env":
+            return "env branch, no test";
+        case "retry":
+            return "retry logic, no test";
+        case "error":
+            return "error branch, no test";
+        case "feature":
+            return "feature flag, no test";
+        default:
+            return "no test";
+    }
+}
+//# sourceMappingURL=formatter.js.map

package/dist/formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.js","sourceRoot":"","sources":["../src/formatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAU1B,MAAM,UAAU,UAAU,CAAC,OAAsB;IAC/C,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC,CAAC;IACjE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,oDAAoD,CAAC,CAAC,CAAC;IACjF,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACzC,CAAC;SAAM,CAAC;QACN,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACvC,KAAK,CAAC,IAAI,CACR,KAAK,KAAK,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,OAAO,MAAM,CAAC,aAAa,KAAK,KAAK,CAAC,GAAG,CACtF,UAAU,iBAAiB,CAAC,MAAM,CAAC,EAAE,CACtC,EAAE,CACJ,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAAC;IAClD,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1C,CAAC;SAAM,CAAC;QACN,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACrC,MAAM,YAAY,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC;YAC1D,KAAK,CAAC,IAAI,CACR,KAAK,KAAK,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,OAAO,MAAM,CAAC,aAAa,KAAK,KAAK,CAAC,GAAG,CACxF,wBAAwB,YAAY,EAAE,CACvC,EAAE,CACJ,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CACR,YAAY,OAAO,CAAC,OAAO,CAAC,cAAc,wBAAwB,OAAO,CAAC,OAAO,CAAC,YAAY,uBAAuB,OAAO,CAAC,OAAO,CAAC,eAAe,GAAG,CACxJ,CAAC;IAEF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,OAAsB;IAC/C,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED,SAAS,iBAAiB,CAAC,MAAsB;IAC/C,QAAQ,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,KAAK,KAAK;YACR,OAAO,qBAAqB,CAAC;QAC/B,KAAK,OAAO;YACV,OAAO,sBAAsB,CAAC;QAChC,KAAK,OAAO;YACV,OAAO,uBAAuB,CAAC;QACjC,KAAK,SAAS;YACZ,OAAO,uBAAuB,CAAC;QACjC;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { extractBranchesFromDirectory } from "./extractor.js";
+import { formatJson, formatText } from "./formatter.js";
+import { loadTestFiles, matchBranchesToTests } from "./matcher.js";
+import { calculateCoverage } from "./scorer.js";
+const program = new Command();
+program
+    .name("branch-never")
+    .argument("<src-dir>", "Source directory to analyze")
+    .option("--tests <dir>", "Test directory", "test/")
+    .option("--json", "Emit JSON output", false)
+    .option("--no-fail", "Don't exit 1 when uncovered branches found")
+    .option("--pattern <type>", "Only check: env|retry|error|feature|all", "all")
+    .option("--threshold <pct>", "Fail if coverage below N% (default: 0, fail on any)", "0")
+    .action(async (srcDir, options) => {
+    const threshold = Number(options.threshold);
+    if (!Number.isFinite(threshold) || threshold < 0 || threshold > 100) {
+        console.error("Invalid --threshold value. Expected a number between 0 and 100.");
+        process.exitCode = 2;
+        return;
+    }
+    if (!["env", "retry", "error", "feature", "all"].includes(options.pattern)) {
+        console.error("Invalid --pattern value. Expected env|retry|error|feature|all.");
+        process.exitCode = 2;
+        return;
+    }
+    const branches = await extractBranchesFromDirectory(srcDir, options.pattern);
+    const testFiles = await loadTestFiles(options.tests);
+    const results = matchBranchesToTests(branches, testFiles);
+    const covered = results.filter((result) => result.covered);
+    const uncovered = results.filter((result) => !result.covered);
+    const summary = calculateCoverage(results);
+    const payload = { covered, uncovered, summary };
+    if (options.json) {
+        console.log(formatJson(payload));
+    }
+    else {
+        console.log(formatText(payload));
+    }
+    const thresholdTriggered = threshold > 0 ? summary.coveragePercent < threshold : uncovered.length > 0;
+    if (options.fail && thresholdTriggered) {
+        process.exitCode = 1;
+    }
+});
+await program.parseAsync(process.argv);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/matcher.d.ts

@@ -0,0 +1,15 @@
+import type { BranchMatch } from "./extractor.js";
+export interface BranchCoverage extends BranchMatch {
+    covered: boolean;
+    matchedTokens: string[];
+    matchedTestFiles: string[];
+    tokens: string[];
+}
+export interface TestFileRecord {
+    contents: string;
+    tokens: Set<string>;
+}
+export declare function extractConditionTokens(conditionText: string): string[];
+export declare function collectTestTokens(contents: string): Set<string>;
+export declare function loadTestFiles(testDir: string): Promise<Map<string, TestFileRecord>>;
+export declare function matchBranchesToTests(branches: BranchMatch[], testFiles: Map<string, string | TestFileRecord>): BranchCoverage[];

package/dist/matcher.js

@@ -0,0 +1,101 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { glob } from "glob";
+const FILE_GLOB = "**/*.{ts,tsx,js,jsx,mjs,cjs}";
+const RESERVED = new Set([
+    "if",
+    "else",
+    "catch",
+    "true",
+    "false",
+    "null",
+    "undefined",
+    "return",
+    "throw",
+    "new",
+    "typeof",
+    "instanceof",
+    "process",
+    "env"
+]);
+export function extractConditionTokens(conditionText) {
+    const tokens = new Set();
+    for (const match of conditionText.matchAll(/process\.env\.([A-Z0-9_]+)/g)) {
+        tokens.add(match[1]);
+    }
+    for (const match of conditionText.matchAll(/["'`]([^"'`]{2,})["'`]/g)) {
+        tokens.add(match[1]);
+    }
+    for (const match of conditionText.matchAll(/\b[A-Za-z_][A-Za-z0-9_]*\b/g)) {
+        const token = match[0];
+        if (RESERVED.has(token)) {
+            continue;
+        }
+        if (token.length < 3 && !/^[A-Z0-9_]+$/.test(token)) {
+            continue;
+        }
+        tokens.add(token);
+    }
+    return [...tokens];
+}
+export function collectTestTokens(contents) {
+    const stripped = contents
+        .replace(/\/\*[\s\S]*?\*\//g, " ")
+        .replace(/\/\/.*$/gm, " ");
+    const tokens = new Set();
+    for (const match of stripped.matchAll(/["'`]([^"'`]{2,})["'`]/g)) {
+        tokens.add(match[1]);
+    }
+    for (const match of stripped.matchAll(/\b[A-Za-z_][A-Za-z0-9_]*\b/g)) {
+        const token = match[0];
+        if (RESERVED.has(token)) {
+            continue;
+        }
+        tokens.add(token);
+    }
+    return tokens;
+}
+export async function loadTestFiles(testDir) {
+    const absoluteDir = path.resolve(testDir);
+    const files = await glob(FILE_GLOB, {
+        absolute: true,
+        cwd: absoluteDir,
+        nodir: true,
+        ignore: ["**/*.d.ts"]
+    });
+    const entries = await Promise.all(files.map(async (file) => {
+        const contents = await readFile(file, "utf8");
+        return [
+            path.relative(process.cwd(), file),
+            {
+                contents,
+                tokens: collectTestTokens(contents)
+            }
+        ];
+    }));
+    return new Map(entries);
+}
+export function matchBranchesToTests(branches, testFiles) {
+    return branches.map((branch) => {
+        const tokens = extractConditionTokens(branch.conditionText);
+        const matchedTokens = new Set();
+        const matchedTestFiles = new Set();
+        for (const [file, record] of testFiles.entries()) {
+            const testTokens = typeof record === "string" ? collectTestTokens(record) : record.tokens;
+            for (const token of tokens) {
+                if (testTokens.has(token)) {
+                    matchedTokens.add(token);
+                    matchedTestFiles.add(file);
+                }
+            }
+        }
+        return {
+            ...branch,
+            covered: matchedTokens.size > 0,
+            matchedTokens: [...matchedTokens],
+            matchedTestFiles: [...matchedTestFiles],
+            tokens
+        };
+    });
+}
+//# sourceMappingURL=matcher.js.map

package/dist/matcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matcher.js","sourceRoot":"","sources":["../src/matcher.ts"],"names":[],"mappings":"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"}

package/dist/scorer.d.ts

@@ -0,0 +1,10 @@
+import type { BranchCoverage } from "./matcher.js";
+export interface CoverageSummary {
+    coveredCount: number;
+    uncoveredCount: number;
+    total: number;
+    coveragePercent: number;
+}
+export type Severity = "low" | "medium" | "high";
+export declare function calculateCoverage(results: BranchCoverage[]): CoverageSummary;
+export declare function branchSeverity(result: BranchCoverage): Severity;

package/dist/scorer.js

@@ -0,0 +1,26 @@
+export function calculateCoverage(results) {
+    const total = results.length;
+    const coveredCount = results.filter((result) => result.covered).length;
+    const uncoveredCount = total - coveredCount;
+    const coveragePercent = total === 0 ? 100 : Math.round((coveredCount / total) * 100);
+    return {
+        coveredCount,
+        uncoveredCount,
+        total,
+        coveragePercent
+    };
+}
+export function branchSeverity(result) {
+    switch (result.pattern) {
+        case "env":
+        case "error":
+            return "high";
+        case "retry":
+            return "medium";
+        case "feature":
+            return "low";
+        default:
+            return "medium";
+    }
+}
+//# sourceMappingURL=scorer.js.map

package/dist/scorer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scorer.js","sourceRoot":"","sources":["../src/scorer.ts"],"names":[],"mappings":"AAWA,MAAM,UAAU,iBAAiB,CAAC,OAAyB;IACzD,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC;IAC7B,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;IACvE,MAAM,cAAc,GAAG,KAAK,GAAG,YAAY,CAAC;IAC5C,MAAM,eAAe,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,YAAY,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC;IAErF,OAAO;QACL,YAAY;QACZ,cAAc;QACd,KAAK;QACL,eAAe;KAChB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAsB;IACnD,QAAQ,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,KAAK,KAAK,CAAC;QACX,KAAK,OAAO;YACV,OAAO,MAAM,CAAC;QAChB,KAAK,OAAO;YACV,OAAO,QAAQ,CAAC;QAClB,KAAK,SAAS;YACZ,OAAO,KAAK,CAAC;QACf;YACE,OAAO,QAAQ,CAAC;IACpB,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "branch-never",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "branch-never": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "test": "node --import tsx/esm --test test/*.test.ts"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^14.0.0",
+    "glob": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^6.0.0"
+  }
+}