dsh-perm-gate 2.1.0 → 2.6.1

package/lib/dry-run.d.ts

@@ -0,0 +1,87 @@
+import type { RuleAction } from './rule.js';
+import { PermGateRuntime } from './runtime.js';
+export interface DryRunInput {
+    /** Tool name to evaluate, e.g. `shell`, `read`, `write`. */
+    readonly tool: string;
+    /** The tool call's arguments; `command` is what the shell dimensions read. */
+    readonly args?: Record<string, unknown>;
+    /** Rules file to load. Unset = the default chain (cwd upward, then the data home). */
+    readonly rulesFile?: string;
+    /** Working directory the call is evaluated in. Defaults to `process.cwd()`. */
+    readonly cwd?: string;
+    /** Evaluate with the independent Permissive tier on. */
+    readonly permissive?: boolean;
+    /**
+     * Also run the **host-facing** decision path and report its own view.
+     *
+     * That path appends audit entries, records decision events, tracks asks and
+     * clears call clearances — so it is opt-in, and a read-only caller must never
+     * request it against a live runtime. Only the CLI asks for it, to keep its
+     * historic output byte for byte.
+     */
+    readonly hostView?: boolean;
+}
+/** The host-facing decision path's own view (`decideExecution`) and its audit count. */
+export interface DryRunHostView {
+    readonly verdict: RuleAction;
+    /** The waterfall's reason, or the historic `(default/passthrough)` placeholder. */
+    readonly reason: string;
+    readonly audited: number;
+}
+/** The P2 rule chain's own verdict, with the rule that produced it. */
+export interface DryRunRuleLayer {
+    readonly action: RuleAction;
+    readonly reason: string;
+    readonly ruleIndex?: number;
+    /**
+     * The dimensions the matched rule *constrains* — not "the dimension that
+     * caused the match". Dimensions are ANDed and an empty one is no constraint at
+     * all, so a multi-dimension rule cannot be attributed to a single dimension
+     * without lying about which one did the work.
+     */
+    readonly matchedDimensions: readonly string[];
+    /** The raw rule entry as written in the YAML, for display. */
+    readonly source?: Record<string, unknown>;
+}
+export interface DryRunResult {
+    readonly tool: string;
+    readonly rulesFile?: string;
+    /**
+     * The **policy** verdict: what the chain decides for this call, independent of
+     * the session a caller does not have. See {@link PermGateRuntime.explainCall}
+     * for why the session layers are excluded rather than guessed.
+     */
+    readonly verdict: RuleAction;
+    /** Why, in the chain's own words — never a bare placeholder. */
+    readonly reason: string;
+    /** Which layer produced `verdict`. */
+    readonly source: string;
+    readonly defaultAction: RuleAction;
+    readonly ruleCount: number;
+    readonly permissive: boolean;
+    readonly ruleLayer: DryRunRuleLayer;
+    /** Present only when `input.hostView` was set. */
+    readonly host?: DryRunHostView;
+}
+export interface DryRunOptions {
+    readonly rulesFile?: string;
+    readonly permissive?: boolean;
+    /**
+     * Workspace root for the rule CHAIN resolution (cwd upward, then the data
+     * home). `undefined` keeps the runtime default (`process.cwd()`).
+     *
+     * The CLI deliberately does not pass its `--cwd` here: that flag scopes the
+     * evaluated call, and feeding it into chain resolution as well would change
+     * what an existing `--cwd` invocation resolves. A host caller (the rule-test
+     * route) does pass its session workspace, because for a live session "which
+     * rules file applies" is exactly the question being asked.
+     */
+    readonly cwd?: string;
+}
+/**
+ * Build the standalone runtime a dry-run evaluates against. Exported because
+ * `--list` needs the loaded ruleset without deciding anything.
+ */
+export declare function createDryRunRuntime(options?: DryRunOptions): PermGateRuntime;
+/** Evaluate one call against a rules file and report the verdict. */
+export declare function runDryRun(input: DryRunInput, runtime?: PermGateRuntime): DryRunResult;

package/lib/dry-run.js

@@ -0,0 +1,110 @@
+/**
+ * Rule dry-run: evaluate one would-be tool call against a rules file and report
+ * the verdict in a shape both the CLI and the settings-card "rule test" panel can
+ * use.
+ *
+ * The evaluator itself lives in {@link PermGateRuntime}; this module only owns
+ * the standalone construction (no session, no audit feed, no event log, no
+ * persistence paths) and the reporting shape. Nothing here writes to disk or to
+ * the live gate — the runtime it builds is thrown away when the call returns.
+ *
+ * Two verdicts are reported, and they are not the same thing:
+ *
+ * - `verdict` is the *effective* result of the whole chain the live gate runs
+ *   (P0 hard-deny → P1 grant → P2 rules → P3 classifier → P4 ask), minus the
+ *   session-scoped state a dry-run has none of. This is what the user sees.
+ * - `ruleLayer` is what the `permissions` chain decides *on its own*. Only this
+ *   layer can name a rule, so `ruleIndex` belongs to it. A P0 hard-deny or a
+ *   preset deny-keyword fires before it and reports no index; when the two
+ *   differ, that difference is the answer, not an error.
+ */
+import { resolve } from 'node:path';
+import { PermGateRuntime } from './runtime.js';
+/**
+ * The eleven match dimensions, in the order `docs/rules-format.md` documents
+ * them. Used purely for reporting which dimensions a matched rule constrains.
+ */
+const DIMENSION_KEYS = [
+    'tools',
+    'command',
+    'args',
+    'paths',
+    'params',
+    'absent',
+    'agents',
+    'when',
+    'argv',
+    'network',
+    'branch',
+];
+/**
+ * Build the standalone runtime a dry-run evaluates against. Exported because
+ * `--list` needs the loaded ruleset without deciding anything.
+ */
+export function createDryRunRuntime(options = {}) {
+    return new PermGateRuntime({
+        rulesFile: options.rulesFile,
+        cwd: options.cwd,
+        caseInsensitivePaths: true,
+        permissive: options.permissive || undefined,
+    });
+}
+/** Which of the eleven dimensions this rule actually constrains. */
+function constrainedDimensions(source) {
+    return DIMENSION_KEYS.filter((key) => isConstrained(source[key]));
+}
+/**
+ * A dimension constrains when it carries at least one condition. Every shape the
+ * parser produces is covered: pattern lists, key→value maps, condition objects.
+ */
+function isConstrained(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (typeof value === 'object')
+        return Object.keys(value).length > 0;
+    return true;
+}
+/** Evaluate one call against a rules file and report the verdict. */
+export function runDryRun(input, runtime) {
+    const rulesFile = input.rulesFile ? resolve(input.rulesFile) : undefined;
+    const gate = runtime ?? createDryRunRuntime({ rulesFile, permissive: input.permissive, cwd: input.cwd });
+    const exec = {
+        name: input.tool,
+        arguments: input.args ?? {},
+        cwd: input.cwd ? resolve(input.cwd) : process.cwd(),
+    };
+    // Pure policy first (the panel's answer); the side-effecting host view only
+    // when explicitly asked for, and it must run last so its audit count is its own.
+    const policy = gate.explainCall(exec);
+    const layer = gate.explainRules(exec);
+    const source = layer.rule?.source;
+    let host;
+    if (input.hostView === true) {
+        const decision = gate.decideExecution(exec);
+        host = {
+            verdict: decision === undefined ? 'allow' : decision.kind,
+            reason: decision?.reason ?? '(default/passthrough)',
+            audited: gate.auditEntries.length,
+        };
+    }
+    return {
+        tool: input.tool,
+        rulesFile,
+        verdict: policy.action,
+        reason: policy.reason,
+        source: policy.source,
+        defaultAction: layer.defaultAction,
+        ruleCount: gate.ruleCount(),
+        permissive: gate.permissive,
+        ruleLayer: {
+            action: layer.action,
+            reason: layer.reason,
+            ruleIndex: layer.ruleIndex,
+            matchedDimensions: source === undefined ? [] : constrainedDimensions(source),
+            source,
+        },
+        ...(host !== undefined ? { host } : {}),
+    };
+}

package/lib/engine.js

@@ -9,7 +9,14 @@
  * Strictly fail-closed: P0 wins over every later stage.
  */
 import { isProtectedDestructiveTarget, isSensitivePath, isWithin } from './path.js';
+// SHELL_TOOLS 是**值的导入**：这份名单必须与 evaluate.ts / runtime.ts 共用同一个
+// 事实源。此处曾经自带一份 `/(?:bash|pwsh|sh|cmd)$/` 正则，漏掉了 `shell` /
+// `terminal` / `powershell`——于是 P0 的 shell 检查对 DSH 的**主 shell 工具**
+// 完全失效（实测：同一句 `echo x > /etc/passwd`，bash 被拦截，shell 放行）。
+// 同名事实的第二份副本必然腐烂，这里不再保留副本。
+import { SHELL_TOOLS } from './evaluate.js';
 import { isForceDeletion, isRecursiveDeletion, decomposeShellCommand } from './shell.js';
+import { dispatchCommand } from './command-dispatcher.js';
 const DESTRUCTIVE_TOOL = /(?:^|[_-])(?:delete|remove|rm|destroy|erase|purge|wipe|unlink|rmdir|reset)(?:$|[_-]|recursive)/i;
 /**
  * Read-only tools that can never modify the workspace or execute anything. P0
@@ -19,8 +26,13 @@ const DESTRUCTIVE_TOOL = /(?:^|[_-])(?:delete|remove|rm|destroy|erase|purge|wipe
  */
 const READ_TOOLS = new Set([
     'read', 'read_image', 'grep', 'glob', 'ls', 'lsp',
-    // Read-only network / media queries: no write, no exec.
+    // Search / lookup: every one of these only READS. `web_search` and
+    // `modlens_read_image` also reach the network, but through DSH's own client
+    // rather than a subprocess — see the network note below.
     'web_search', 'modlens_read_image',
+    'advanced_search', 'platform_search', 'free_search_test',
+    // Session-scoped reads: they disclose already-recorded state, never mutate.
+    'context_compression_retrieve', 'memory_search_graph', 'memory_expand_graph_node',
 ]);
 /** DSH internal coordination / management tools — not workspace-modifying. */
 const INTERNAL_TOOLS = new Set([
@@ -31,9 +43,11 @@ const INTERNAL_TOOLS = new Set([
     'agent_teams_approve', 'agent_teams_resume',
     // AgentTeams status reads
     'agent_teams_status', 'agent_teams_update_task',
-    // DSH session/memory/goal/taskboard management
+    // DSH session/memory/goal/taskboard management. The memory store is the
+    // agent's own state, not the workspace: writing it is not a workspace write.
     'conversation_search',
     'memory_add', 'memory_delete', 'memory_read_scene', 'memory_search',
+    'memory_import', 'memory_ruminate', 'memory_ruminate_cancel', 'memory_ruminate_status',
     'get_goal', 'update_goal', 'create_goal',
     'taskboard_get', 'taskboard_list', 'taskboard_claim', 'taskboard_block',
     'taskboard_comment', 'taskboard_release_claim', 'taskboard_submit_review',
@@ -100,6 +114,42 @@ function pathArgument(args) {
     }
     return undefined;
 }
+/** 廉价前缀过滤：绝大多数 shell 调用不是 push，先过一遍正则再动用解析器。 */
+const GIT_PUSH_TEXT = /\bgit\s+push\b/;
+/**
+ * 远端历史改写：`git push` 强制覆盖或删除**保护分支**。
+ *
+ * **「只升不降」是形状约束，不是口头约定**：返回值只有 `string | undefined`，
+ * 调用方把 `string` 读作 deny、`undefined` 读作「继续走后面的阶段」。本函数
+ * 结构上**无法**产生 allow，所以挂在 P0 上永远不会放宽门的判定。
+ *
+ * 刻意**不**覆盖（仍交给关键词层 / 规则层 / LLM 层）：
+ * - 非保护分支上的 force push（如 `origin feat/x`）——P0 不可撤销，得给工作流留口子；
+ * - 没写分支名的 `git push --force`——解析不出目标就不做断言；
+ * - 普通 push。
+ *
+ * 这正是本插件补不上的那一段：`DEFAULT_DENY_KEYWORDS` 里的 `'push --force'` 是
+ * **扁平的、可被命名空间覆盖掉**的，且完全不看分支；P0 这一层则是不可协商的底。
+ */
+function gitRemoteRewriteReason(segments) {
+    for (const seg of segments) {
+        const text = [seg.command, ...seg.args].join(' ');
+        if (!GIT_PUSH_TEXT.test(text))
+            continue;
+        const result = dispatchCommand(text);
+        if (result === null)
+            continue;
+        const s = result.semantics;
+        if (s.operation !== 'force-push' && s.operation !== 'push-delete')
+            continue;
+        if (!s.targetsSharedBranch)
+            continue;
+        const what = s.operation === 'push-delete' ? 'delete' : 'force-overwrite';
+        const remote = s.remote === undefined ? '' : ` (remote ${s.remote})`;
+        return `git push would ${what} protected branch: ${s.branch}${remote}`;
+    }
+    return undefined;
+}
 /**
  * Deterministic P0 hard-deny reason, or undefined when the call may proceed to
  * later stages.
@@ -108,8 +158,7 @@ export function hardDenyReason(ctx) {
     const args = ctx.args;
     if (containsCredentialMaterial(args))
         return 'call contains credential or private-key material';
-    const shell = /^(?:bash|pwsh|sh|cmd)$/.test(ctx.tool);
-    if (shell && typeof args.command === 'string') {
+    if (SHELL_TOOLS.has(ctx.tool) && typeof args.command === 'string') {
         let commands = [];
         try {
             commands = decomposeShellCommand(args.command).commands;
@@ -126,8 +175,16 @@ export function hardDenyReason(ctx) {
             if (redir !== undefined)
                 return `shell redirect targets protected path: ${redir}`;
         }
+        const rewrite = gitRemoteRewriteReason(commands);
+        if (rewrite !== undefined)
+            return rewrite;
     }
     const path = pathArgument(args);
+    // 注意：这里**刻意不**用 SHELL_TOOLS。本判据读的是 `pathArgument`（file_path /
+    // path / cwd / **workdir**），它是"被改写的路径"而不是"要执行的命令"。shell 工具的
+    // 真目标在 command 里，由上面的命令级检查负责；若把 shell 工具也塞进来，
+    // `shell({ command: 'ls', workdir: '/etc' })` 这种纯读操作会因为 workdir 落在受保护
+    // 前缀而被 P0 永久挡住——那是过度拦截，而且 P0 撤销不了。
     if (path !== undefined && (DESTRUCTIVE_TOOL.test(ctx.tool) || ctx.tool === 'bash' || ctx.tool === 'pwsh' || ctx.tool === 'write' || ctx.tool === 'edit')) {
         if (isProtectedDestructiveTarget(path, ctx.dshHome))
             return `mutation targets protected path: ${path}`;

package/lib/evaluate.d.ts

@@ -9,6 +9,15 @@ export interface ToolCallContext {
     readonly home?: string;
     readonly dshHome?: string;
     readonly caseInsensitive?: boolean;
+    /** Agent identity candidates from session context. */
+    readonly agentCandidates?: readonly string[];
+    /** Network request info (for network dimension matching). */
+    readonly network?: {
+        readonly domain?: string;
+        readonly ip?: string;
+        readonly port?: number;
+        readonly scheme?: string;
+    };
 }
 export interface Decision {
     readonly action: RuleAction;

package/lib/evaluate.js

@@ -5,7 +5,9 @@
  */
 import { normalizeWorkspacePath } from './path.js';
 import { extractPathCandidates, extractUrlCandidates, } from './rule.js';
-import { decomposeShellCommand, isForceDeletion, isRecursiveDeletion } from './shell.js';
+import { commandArgv, decomposeShellCommand, isForceDeletion, isRecursiveDeletion } from './shell.js';
+import { compileCidr, compilePortSpec, compileDomainPattern } from './compiler.js';
+import { dispatchCommand } from './command-dispatcher.js';
 /**
  * Tool names that execute a shell command string. `shell` and `terminal` are
  * DSH's own names (the shipped tool roster uses `shell`; `terminal` is the
@@ -64,6 +66,56 @@ export function ruleMatches(rule, ctx, commands, pathCands, urlCands) {
         if (!rel.some((p) => rule.paths.some((g) => g.re.test(p))))
             return false;
     }
+    // ─── New dimensions ────────────────────────────────────────────────────
+    // params dimension: AND over keys; each key's value must match at least one pattern (OR).
+    if (rule.params.length > 0) {
+        if (!matchParams(rule.params, ctx.args))
+            return false;
+    }
+    // absent dimension: all listed keys must be absent from args.
+    if (rule.absent.length > 0) {
+        for (const key of rule.absent) {
+            if (key in ctx.args)
+                return false;
+        }
+    }
+    // agents dimension: at least one candidate must match an entry.
+    if (rule.agents.length > 0) {
+        const candidates = ctx.agentCandidates ?? [];
+        if (candidates.length === 0)
+            return false; // fail-closed
+        if (!candidates.some((c) => rule.agents.some((a) => a === c || matchAgentPattern(a, c))))
+            return false;
+    }
+    // when dimension: all conditions must be satisfied.
+    if (rule.when !== undefined) {
+        if (!matchWhen(rule.when))
+            return false;
+    }
+    // argv dimension: pipeline patterns.
+    if (rule.argv?.pipeline !== undefined && rule.argv.pipeline.length > 0) {
+        if (commands.length === 0)
+            return false;
+        // Join the FULL argv of each simple command: `c.command` alone is just the
+        // command word, so `curl https://x | sh` would read as `curl|sh` and the
+        // documented `curl|sh` pattern could never see its own subject.
+        const pipelineText = commands.map((c) => commandArgv(c)).join('|');
+        const compiled = rule.argv.pipeline.map((p) => compileGlobForMatch(p));
+        if (!compiled.some((g) => g.test(pipelineText)))
+            return false;
+    }
+    // network dimension: all present sub-dimensions must match.
+    if (rule.network !== undefined) {
+        if (!matchNetwork(rule.network, ctx.network))
+            return false;
+    }
+    // branch dimension: git semantics only; non-git commands satisfy no branch
+    // dimension (per sub-dimension above). Never throws — a parser is pure, and
+    // the dispatcher falls back to `family: 'unknown'` rather than raising.
+    if (rule.branch !== undefined) {
+        if (!matchBranch(rule.branch, commands))
+            return false;
+    }
     return true;
 }
 const WRITE_TOOLS = new Set(['write', 'edit']);
@@ -182,3 +234,214 @@ function decomposeSafe(text) {
         return [];
     }
 }
+// ─── New dimension matchers ────────────────────────────────────────────────
+/** Import compileGlob locally to avoid circular dependency with compiler.ts. */
+import { compileGlob } from './compiler.js';
+/** Compile a glob pattern to a RegExp for ad-hoc matching. */
+function compileGlobForMatch(pattern) {
+    return compileGlob(pattern, { segments: false }).re;
+}
+/**
+ * Match the params dimension: AND over keys, OR within each key's patterns.
+ * A negated pattern means the value must NOT match.
+ */
+function matchParams(params, args) {
+    for (const cond of params) {
+        const value = resolveNestedKey(args, cond.key);
+        if (cond.patterns.length === 0) {
+            // No patterns → key must exist (any value).
+            if (value === undefined)
+                return false;
+            continue;
+        }
+        if (value === undefined)
+            return false;
+        const strValue = typeof value === 'string' ? value : JSON.stringify(value);
+        const compiled = cond.patterns.map((p) => {
+            if (p.startsWith('!') && p.length > 1) {
+                return { negated: true, re: compileGlobForMatch(p.slice(1)) };
+            }
+            return { negated: false, re: compileGlobForMatch(p) };
+        });
+        if (cond.negated) {
+            // Negated: value must NOT match the sole pattern.
+            if (compiled[0].re.test(strValue))
+                return false;
+        }
+        else {
+            // Normal: value must match at least one pattern (OR).
+            if (!compiled.some((c) => !c.negated && c.re.test(strValue)))
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * Resolve a dotted key path from a nested object.
+ * e.g. `resolveNestedKey({flags: {mode: 'prod'}}, 'flags.mode')` → `'prod'`
+ */
+function resolveNestedKey(obj, key) {
+    const parts = key.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined || typeof current !== 'object')
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Match an agent pattern against an identity candidate.
+ * Supports exact match and glob patterns.
+ */
+function matchAgentPattern(pattern, candidate) {
+    if (pattern === candidate)
+        return true;
+    // Glob patterns: compile and test.
+    if (/[*?[\]]/.test(pattern)) {
+        return compileGlobForMatch(pattern).test(candidate);
+    }
+    return false;
+}
+/**
+ * Match the when dimension: all conditions must be satisfied.
+ */
+function matchWhen(when) {
+    // Platform check.
+    if (when.platform !== undefined && when.platform.length > 0) {
+        if (!when.platform.includes(process.platform))
+            return false;
+    }
+    // Env var checks.
+    if (when.env !== undefined) {
+        for (const [varName, allowed] of Object.entries(when.env)) {
+            const actual = process.env[varName];
+            if (actual === undefined)
+                return false;
+            if (!allowed.includes(actual))
+                return false;
+        }
+    }
+    // Node version (reserved — skip for now).
+    return true;
+}
+/**
+ * Match the network dimension: all present sub-dimensions must match.
+ * Within a sub-dimension, entries are OR.
+ */
+function matchNetwork(network, ctx) {
+    if (ctx === undefined)
+        return false;
+    // domains
+    if (network.domains !== undefined && network.domains.length > 0) {
+        if (ctx.domain === undefined)
+            return false;
+        const matchers = network.domains.map((d) => compileDomainPattern(d));
+        if (!matchers.some((m) => m.re.test(ctx.domain)))
+            return false;
+    }
+    // ips
+    if (network.ips !== undefined && network.ips.length > 0) {
+        if (ctx.ip === undefined)
+            return false;
+        const isCidr = (s) => s.includes('/');
+        const cidrs = network.ips.filter(isCidr);
+        const literals = network.ips.filter((s) => !isCidr(s));
+        const ipMatch = literals.includes(ctx.ip) || cidrs.some((c) => {
+            try {
+                return compileCidr(c)(ctx.ip);
+            }
+            catch {
+                return false;
+            }
+        });
+        if (!ipMatch)
+            return false;
+    }
+    // ports
+    if (network.ports !== undefined && network.ports.length > 0) {
+        if (ctx.port === undefined)
+            return false;
+        const matchers = network.ports.map((p) => {
+            try {
+                return compilePortSpec(p);
+            }
+            catch {
+                return (_) => false;
+            }
+        });
+        if (!matchers.some((m) => m(ctx.port)))
+            return false;
+    }
+    // schemes
+    if (network.schemes !== undefined && network.schemes.length > 0) {
+        if (ctx.scheme === undefined)
+            return false;
+        if (!network.schemes.includes(ctx.scheme))
+            return false;
+    }
+    return true;
+}
+/**
+ * Per-call memo for command classification.
+ *
+ * `ruleMatches` runs once per rule, so a rule chain with several `branch`
+ * rules would otherwise re-parse the same command each time. `dispatchCommand`
+ * is pure, so caching its result per `SimpleCommand` object is safe; the
+ * WeakMap keeps no references once the command array is dropped.
+ */
+const commandSemanticsCache = new WeakMap();
+function semanticsOf(cmd) {
+    const cached = commandSemanticsCache.get(cmd);
+    if (cached !== undefined)
+        return cached;
+    // The parser needs the WHOLE argv: `cmd.command` carries only the command
+    // word, so `git push --force origin main` would arrive as `git` and classify
+    // as `family: unknown` (no branch, no remote, no flags).
+    const result = dispatchCommand(commandArgv(cmd));
+    commandSemanticsCache.set(cmd, result);
+    return result;
+}
+/**
+ * Branch dimension matching (git semantics only).
+ *
+ * Candidates come from the shared command dispatcher, so `refspec` forms
+ * (`HEAD:main`) are already split and a remote name is never mistaken for a
+ * branch name. Sub-dimensions are AND (each present one must match); within a
+ * sub-dimension the entries are OR.
+ *
+ * **Non-git commands satisfy no branch dimension**: `dispatchCommand` reports
+ * `family: 'unknown'` for them rather than throwing, so a rule that names a
+ * branch simply does not match `rm -rf`, `npm install` and friends. That is
+ * deliberate — the write-path/blacklist layers cover non-git commands.
+ *
+ * `shared` is the parser's STATIC protected-branch rule (main / master /
+ * production / release / stable, see `src/parsers/git.ts`). No git subprocess
+ * ever runs on the decision path.
+ */
+function matchBranch(branch, commands) {
+    if (commands.length === 0)
+        return false;
+    const branches = [];
+    const remotes = [];
+    let anyShared = false;
+    for (const cmd of commands) {
+        const result = semanticsOf(cmd);
+        if (result === null || result.semantics.family !== 'git')
+            continue;
+        const { branch: name, remote, targetsSharedBranch } = result.semantics;
+        if (targetsSharedBranch)
+            anyShared = true;
+        if (typeof name === 'string' && name.length > 0)
+            branches.push(name);
+        if (typeof remote === 'string' && remote.length > 0)
+            remotes.push(remote);
+    }
+    if (branch.shared && !anyShared)
+        return false;
+    if (branch.target.length > 0 && !branches.some((b) => branch.target.some((g) => g.re.test(b))))
+        return false;
+    if (branch.remote.length > 0 && !remotes.some((r) => branch.remote.some((g) => g.re.test(r))))
+        return false;
+    return true;
+}