@bookedsolid/rea 0.22.0 → 0.23.0

package/dist/hooks/bash-scanner/parser.js

@@ -0,0 +1,92 @@
+/**
+ * Thin wrapper around `mvdan-sh` — the GopherJS-compiled JS port of
+ * the upstream Go bash parser at `mvdan.cc/sh/v3/syntax`.
+ *
+ * Why a wrapper:
+ *   1. The parser instance is mutable (it tracks state across calls
+ *      to `Parse`). Construct once per process; serialize all parses
+ *      through it. Multiple concurrent Node CLI invocations get one
+ *      parser each — fine, it's cheap.
+ *   2. The library throws Go-style error objects with `.Error()`
+ *      methods, not native JS Errors. Normalize them to native Error
+ *      with a clean message.
+ *   3. Callers care only about three outcomes: parsed, parse-failed,
+ *      or unexpected JS-level throw. Collapse the Go-vs-JS-error
+ *      ambiguity to a single discriminated union.
+ *
+ * 0.23.0 — first release of this module. Pinned to mvdan-sh@0.10.1
+ * (deprecated upstream but functionally complete; see issue 1145).
+ * If we ever migrate to `sh-syntax` (the WASM successor), this
+ * wrapper is the only file that changes — everything downstream
+ * works against `BashFile`/`BashNode` from our local d.ts shim.
+ */
+import mvdanSh from 'mvdan-sh';
+/**
+ * Singleton parser. mvdan-sh's `NewParser` is documented as reusable
+ * across calls; spinning up a fresh one per scan adds 1-2ms with no
+ * correctness benefit.
+ *
+ * Imported via the default export — the package ships CommonJS with
+ * a single `module.exports = { syntax: ... }` shape; under ESM the
+ * named-export `{ syntax }` form fails because the property is
+ * dynamically assigned in the GopherJS-generated body and Node's
+ * named-exports synthesis cannot see it.
+ */
+const parser = mvdanSh.syntax.NewParser();
+/**
+ * Parse a bash command string into an AST. Returns a tagged union so
+ * the caller never has to wrap this in try/catch — every failure mode
+ * (Go parse error, JS throw, weird native return) is collapsed to
+ * `{ ok: false, error }`.
+ *
+ * Empty / whitespace-only input is a no-op success — the parser
+ * returns a `File` with zero `Stmts`, which the walker will yield
+ * zero detections for. Equivalent to the bash gates' `[[ -z "$CMD" ]]
+ * && exit 0` guard.
+ */
+export function parseBashCommand(src) {
+    try {
+        const file = parser.Parse(src, 'rea-bash-scanner.sh');
+        // Defensive: GopherJS sometimes returns a node missing the Stmts
+        // field on certain edge-case inputs (we have not reproduced one,
+        // but the file-IO layer the original Go uses is mocked out and
+        // failure modes are not perfectly characterized). Treat that as
+        // "parse failure" rather than "empty file" so we fail closed.
+        if (file === null || file === undefined) {
+            return { ok: false, error: 'parser returned null file' };
+        }
+        return { ok: true, file };
+    }
+    catch (e) {
+        // Go errors come through as objects with `.Error()` methods. Native
+        // JS errors have `.message`. Anything else gets stringified.
+        const error = goErrorMessage(e) ?? jsErrorMessage(e) ?? String(e);
+        return { ok: false, error };
+    }
+}
+function goErrorMessage(e) {
+    if (typeof e === 'object' && e !== null && 'Error' in e) {
+        const fn = e.Error;
+        if (typeof fn === 'function') {
+            try {
+                const msg = fn.call(e);
+                if (typeof msg === 'string')
+                    return msg;
+            }
+            catch {
+                // Fall through to other strategies.
+            }
+        }
+    }
+    return null;
+}
+function jsErrorMessage(e) {
+    if (e instanceof Error)
+        return e.message;
+    if (typeof e === 'object' && e !== null && 'message' in e) {
+        const m = e.message;
+        if (typeof m === 'string')
+            return m;
+    }
+    return null;
+}

package/dist/hooks/bash-scanner/protected-scan.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Protected-paths policy composition. Mirrors the bash semantics in
+ * `hooks/_lib/protected-paths.sh` byte-for-byte:
+ *
+ *   1. Build the effective protected set:
+ *      - If policy.protected_writes is set: that list, plus kill-switch
+ *        invariants always added.
+ *      - Else: the historical default (REA_PROTECTED_PATTERNS_FULL).
+ *      Then subtract policy.protected_paths_relax — but kill-switch
+ *      invariants in the relax list are silently dropped from the
+ *      relax set with a stderr advisory (not from the protected set).
+ *
+ *   2. The match check:
+ *      a. Explicit `protected_writes` overrides win FIRST (helix-020 G2).
+ *         Matched against the path BEFORE the extension-surface check.
+ *      b. Extension-surface paths (`.husky/{commit-msg,pre-push,
+ *         pre-commit}.d/<fragment>`) are NOT protected by default
+ *         (helix-018 Option B / 0.16.4).
+ *      c. Default protected list applies, with kill-switch invariants
+ *         always enforced.
+ *
+ *   3. Pattern matching:
+ *      - case-insensitive (macOS APFS — helix-015 #2)
+ *      - trailing `/` is a prefix-match
+ *      - everything else is exact-match
+ *
+ *   4. Path normalization runs BEFORE matching:
+ *      - URL decode, backslash → slash, leading `./` strip
+ *      - `..` walk-up via the parser-friendly equivalent of
+ *        `cd -P / pwd -P` (we rely on `node:fs.realpathSync` for the
+ *        symlink resolution; non-existent parents walk up to the
+ *        nearest existing ancestor — helix-022 #1)
+ *      - case-insensitive lowercase comparison
+ *      - sentinel `__rea_unresolved_expansion__` for $-substitution
+ *      - sentinel `__rea_outside_root__` for paths escaping REA_ROOT
+ */
+import type { Policy } from '../../policy/types.js';
+import type { DetectedWrite } from './walker.js';
+import { type Verdict } from './verdict.js';
+/**
+ * Inputs the protected-scan composer needs. The caller collects these
+ * from the environment + policy file once and passes them in. Keeps
+ * the scanner function pure / testable.
+ */
+export interface ProtectedScanContext {
+    reaRoot: string;
+    policy: Pick<Policy, 'protected_writes' | 'protected_paths_relax'>;
+    /**
+     * Stderr sink for advisory messages (e.g. "kill-switch invariant in
+     * protected_paths_relax"). Defaults to no-op so unit tests don't
+     * pollute stdout.
+     */
+    stderr?: (line: string) => void;
+}
+interface EffectivePatterns {
+    /** Full effective protected set (default OR override + invariants − relax). */
+    full: string[];
+    /** Subset that came from explicit `protected_writes` (overrides the extension-surface allow-list). */
+    override: string[];
+}
+/**
+ * Compute the effective protected pattern sets from policy. Pure — no
+ * filesystem access.
+ */
+export declare function computeEffectivePatterns(ctx: ProtectedScanContext): EffectivePatterns;
+/**
+ * Run a list of detected writes against the protected-paths policy.
+ * Returns the FIRST blocking verdict, or allow if every detection is
+ * clean.
+ *
+ * Order: walk detections in order of appearance. The walker emits
+ * them in source order, so the operator sees the EARLIEST violation
+ * in the error message.
+ */
+export declare function scanForProtectedViolations(ctx: ProtectedScanContext, detections: readonly DetectedWrite[]): Verdict;
+export {};