swarmdo 1.37.0 → 1.50.0

package/v3/@swarmdo/cli/dist/src/mcp-tools/task-deps.d.ts

@@ -42,6 +42,41 @@ export declare function readyTasks(store: TaskStore): TaskRecord[];
 export declare function blockedTasks(store: TaskStore): BlockedInfo[];
 /** Tasks that became ready exactly because `completedTaskId` completed. */
 export declare function unblockedBy(store: TaskStore, completedTaskId: string): TaskRecord[];
+export interface DeadBlock {
+    task: TaskRecord;
+    /**
+     * The terminal-dead dependency ids in this task's dependency closure — the
+     * failed, cancelled, or missing tasks that make it permanently unreachable
+     * until a human retries/cancels/creates them. Deterministic (sorted).
+     */
+    rootCause: string[];
+}
+export interface TaskDagHealth {
+    /** pending tasks whose unmet deps can STILL complete — a transient wait */
+    liveBlocked: TaskRecord[];
+    /** pending tasks that can NEVER become ready without human intervention */
+    deadBlocked: DeadBlock[];
+    /**
+     * true when pending work exists but nothing is ready AND nothing is
+     * in_progress — the DAG cannot advance on its own. A coordinator looping on
+     * `task dispatch` would otherwise spin forever doing nothing.
+     */
+    deadlocked: boolean;
+}
+/**
+ * Classify every blocked task as live- vs dead-blocked and report a global
+ * deadlock verdict. Pure.
+ *
+ * This is Apache Airflow's `upstream_failed` state + DAG-deadlock detection,
+ * ported onto the beads-style task DAG (see the module header): a dependency
+ * that failed / was cancelled / is missing NEVER satisfies (only 'completed'
+ * does), so every task transitively downstream is permanently stuck until a
+ * human intervenes. `blockedTasks()` reports the wait but can't tell a
+ * transient wait from a permanent one — the dispatcher then skips a
+ * failed-dep block every pass, indistinguishable from a normal wait, and the
+ * DAG quietly wedges. This turns that silent stall into a named diagnostic.
+ */
+export declare function taskDagHealth(store: TaskStore): TaskDagHealth;
 /**
  * Flat dependency view: one line per task, dependencies inline with their
  * states. A DAG has no single tree; a flat annotated list stays honest for

package/v3/@swarmdo/cli/dist/src/mcp-tools/task-deps.js

@@ -94,6 +94,93 @@ export function blockedTasks(store) {
 export function unblockedBy(store, completedTaskId) {
     return Object.values(store.tasks).filter((t) => t.status === 'pending' && (t.dependsOn ?? []).includes(completedTaskId) && isReady(store, t));
 }
+/**
+ * Classify every blocked task as live- vs dead-blocked and report a global
+ * deadlock verdict. Pure.
+ *
+ * This is Apache Airflow's `upstream_failed` state + DAG-deadlock detection,
+ * ported onto the beads-style task DAG (see the module header): a dependency
+ * that failed / was cancelled / is missing NEVER satisfies (only 'completed'
+ * does), so every task transitively downstream is permanently stuck until a
+ * human intervenes. `blockedTasks()` reports the wait but can't tell a
+ * transient wait from a permanent one — the dispatcher then skips a
+ * failed-dep block every pass, indistinguishable from a normal wait, and the
+ * DAG quietly wedges. This turns that silent stall into a named diagnostic.
+ */
+export function taskDagHealth(store) {
+    // canComplete(id): can this task ever reach status 'completed'?
+    //   completed → yes; failed/cancelled/missing → no; pending/in_progress →
+    //   only if EVERY dependency can complete. Memoized; a cycle (the store is
+    //   acyclic by invariant, but guard anyway) resolves to false.
+    const memo = new Map();
+    const visiting = new Set();
+    const canComplete = (id) => {
+        const cached = memo.get(id);
+        if (cached !== undefined)
+            return cached;
+        const task = store.tasks[id];
+        if (!task)
+            return false; // missing id — blocks forever
+        if (task.status === 'completed')
+            return true;
+        if (task.status === 'failed' || task.status === 'cancelled')
+            return false;
+        if (visiting.has(id))
+            return false; // cycle guard
+        visiting.add(id);
+        const ok = (task.dependsOn ?? []).every((d) => canComplete(d));
+        visiting.delete(id);
+        memo.set(id, ok);
+        return ok;
+    };
+    // The terminal-dead ids (failed/cancelled/missing) reachable from a task,
+    // descending THROUGH still-pending intermediates to name the real culprit.
+    const deadRoots = (task) => {
+        const found = new Set();
+        const seen = new Set();
+        const stack = [...(task.dependsOn ?? [])];
+        while (stack.length) {
+            const id = stack.pop();
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            const dep = store.tasks[id];
+            if (!dep) {
+                found.add(id);
+                continue;
+            } // missing
+            if (dep.status === 'failed' || dep.status === 'cancelled') {
+                found.add(id);
+                continue;
+            }
+            if (dep.status === 'completed')
+                continue; // satisfied — not a culprit
+            for (const d of dep.dependsOn ?? [])
+                stack.push(d); // pending/in_progress → descend
+        }
+        return [...found].sort();
+    };
+    const liveBlocked = [];
+    const deadBlocked = [];
+    for (const task of Object.values(store.tasks)) {
+        if (task.status !== 'pending')
+            continue;
+        const deps = task.dependsOn ?? [];
+        if (deps.length === 0)
+            continue; // ready (dep-free), not blocked
+        if (deps.every((id) => satisfies(store.tasks[id])))
+            continue; // ready, not blocked
+        if (deps.every((id) => canComplete(id)))
+            liveBlocked.push(task);
+        else
+            deadBlocked.push({ task, rootCause: deadRoots(task) });
+    }
+    const all = Object.values(store.tasks);
+    const anyPending = all.some((t) => t.status === 'pending');
+    const anyInProgress = all.some((t) => t.status === 'in_progress');
+    const deadlocked = anyPending && readyTasks(store).length === 0 && !anyInProgress;
+    return { liveBlocked, deadBlocked, deadlocked };
+}
 const STATUS_MARK = {
     completed: '✔',
     in_progress: '▶',

package/v3/@swarmdo/cli/dist/src/ownership/ownership.d.ts

@@ -0,0 +1,61 @@
+/**
+ * ownership.ts — per-file authorship concentration + BUS FACTOR from git history.
+ *
+ * "Who owns this file, and what breaks if they leave?" answered from data. For
+ * every file we compute the dominant author (main-dev), how concentrated the
+ * churn is in that one person (ownership share), how many hands have touched it,
+ * and its bus factor — the smallest set of top authors whose combined churn
+ * clears half the file. A bus factor of 1 is a key-person risk: one departure
+ * orphans the file. A repo-level "truck factor" answers the same question for
+ * the whole codebase.
+ *
+ * This is the code-maat `main-dev` / `entity-ownership` analysis (Tornhill,
+ * *Your Code as a Crime Scene*), surfaced as CodeScene's "Knowledge Map" and
+ * "Bus Factor". The scoring core is a pure fold over the SAME `git log --numstat`
+ * dump `hotspots`/`coupling` already parse — it reuses that Commit type +
+ * parseGitLog and is unit-tested without a repo. `%aN` (mailmap-folded author)
+ * means name/email variants of one person count as one owner.
+ */
+import type { Commit } from '../hotspots/hotspots.js';
+export interface FileOwnership {
+    path: string;
+    /** dominant author: most churn, tie → most commits, tie → name ascending */
+    owner: string;
+    /** owner churn / total file churn ∈ (0,1]; 1.0 = a single hand */
+    ownership: number;
+    /** distinct authors who touched the file */
+    authors: number;
+    /** total added+deleted across all commits */
+    churn: number;
+    /** commits touching the file */
+    commits: number;
+    /** smallest # of top-churn authors whose cumulative churn EXCEEDS 50% */
+    busFactor: number;
+    /** busFactor === 1 — a single point of knowledge (one departure orphans it) */
+    keyPersonRisk: boolean;
+}
+export interface RepoBusFactor {
+    /** the covering set: fewest top authors whose cumulative churn exceeds 50% */
+    authors: string[];
+    /** authors.length — the repo "truck factor" */
+    factor: number;
+}
+export interface OwnershipOptions {
+    /** drop files with total churn below this (default 1 → skips pure-binary edits) */
+    minChurn?: number;
+    /** keep only the top N files after ranking (default: all) */
+    top?: number;
+}
+/** Aggregate commits into per-file ownership, scored and ranked. Pure. */
+export declare function computeOwnership(commits: Commit[], opts?: OwnershipOptions): FileOwnership[];
+/**
+ * Repo-level truck factor: the fewest top authors whose combined churn across
+ * the WHOLE history exceeds half the total. If that set is one person, a single
+ * departure takes the majority of the codebase's institutional knowledge. Pure.
+ */
+export declare function repoBusFactor(commits: Commit[]): RepoBusFactor;
+/** Export the knowledge map as CSV for spreadsheets / staffing review. Pure. */
+export declare function ownershipToCsv(files: FileOwnership[]): string;
+/** Human-readable knowledge map. Pure. */
+export declare function formatOwnership(files: FileOwnership[]): string;
+//# sourceMappingURL=ownership.d.ts.map

package/v3/@swarmdo/cli/dist/src/ownership/ownership.js

@@ -0,0 +1,151 @@
+/**
+ * ownership.ts — per-file authorship concentration + BUS FACTOR from git history.
+ *
+ * "Who owns this file, and what breaks if they leave?" answered from data. For
+ * every file we compute the dominant author (main-dev), how concentrated the
+ * churn is in that one person (ownership share), how many hands have touched it,
+ * and its bus factor — the smallest set of top authors whose combined churn
+ * clears half the file. A bus factor of 1 is a key-person risk: one departure
+ * orphans the file. A repo-level "truck factor" answers the same question for
+ * the whole codebase.
+ *
+ * This is the code-maat `main-dev` / `entity-ownership` analysis (Tornhill,
+ * *Your Code as a Crime Scene*), surfaced as CodeScene's "Knowledge Map" and
+ * "Bus Factor". The scoring core is a pure fold over the SAME `git log --numstat`
+ * dump `hotspots`/`coupling` already parse — it reuses that Commit type +
+ * parseGitLog and is unit-tested without a repo. `%aN` (mailmap-folded author)
+ * means name/email variants of one person count as one owner.
+ */
+import { toCsv } from '../util/csv.js';
+/**
+ * Bus factor of a churn distribution: the smallest number of top-churn authors
+ * whose cumulative churn STRICTLY exceeds half the total. An author sitting at
+ * exactly 50% is not enough on their own (you'd need one more), which is what
+ * makes an even two-way split a bus factor of 2. Pure.
+ */
+function busFactorOf(authors, total) {
+    const byChurn = authors.slice().sort((x, y) => y.churn - x.churn || (x.name < y.name ? -1 : x.name > y.name ? 1 : 0));
+    const threshold = total / 2;
+    let cum = 0;
+    let k = 0;
+    for (const a of byChurn) {
+        cum += a.churn;
+        k++;
+        if (cum > threshold)
+            break;
+    }
+    return Math.max(1, k);
+}
+/** Aggregate commits into per-file ownership, scored and ranked. Pure. */
+export function computeOwnership(commits, opts = {}) {
+    const minChurn = opts.minChurn ?? 1;
+    const acc = new Map();
+    for (const c of commits) {
+        // Fold this commit's numstat lines into per-path churn first, so a path that
+        // appears twice in one commit (rename collisions) counts as ONE commit.
+        const perPath = new Map();
+        for (const f of c.files) {
+            if (!f.path)
+                continue;
+            perPath.set(f.path, (perPath.get(f.path) ?? 0) + f.added + f.deleted);
+        }
+        for (const [path, churn] of perPath) {
+            let fa = acc.get(path);
+            if (!fa) {
+                fa = { churn: 0, commits: 0, byAuthor: new Map() };
+                acc.set(path, fa);
+            }
+            fa.churn += churn;
+            fa.commits += 1;
+            let a = fa.byAuthor.get(c.author);
+            if (!a) {
+                a = { name: c.author, churn: 0, commits: 0 };
+                fa.byAuthor.set(c.author, a);
+            }
+            a.churn += churn;
+            a.commits += 1;
+        }
+    }
+    const out = [];
+    for (const [path, fa] of acc) {
+        if (fa.churn < minChurn)
+            continue;
+        const authors = [...fa.byAuthor.values()];
+        // owner: most churn, tie → most commits (sustained involvement), tie → name asc
+        const owner = authors
+            .slice()
+            .sort((x, y) => y.churn - x.churn || y.commits - x.commits || (x.name < y.name ? -1 : x.name > y.name ? 1 : 0))[0];
+        const ownership = fa.churn > 0 ? Math.round((owner.churn / fa.churn) * 100) / 100 : 0;
+        const busFactor = busFactorOf(authors, fa.churn);
+        out.push({
+            path,
+            owner: owner.name,
+            ownership,
+            authors: authors.length,
+            churn: fa.churn,
+            commits: fa.commits,
+            busFactor,
+            keyPersonRisk: busFactor === 1,
+        });
+    }
+    // Deterministic ranking: most fragile first — lowest bus factor, then most
+    // concentrated (ownership desc), then most churn, then path asc for stable ties.
+    out.sort((x, y) => x.busFactor - y.busFactor ||
+        y.ownership - x.ownership ||
+        y.churn - x.churn ||
+        (x.path < y.path ? -1 : x.path > y.path ? 1 : 0));
+    return opts.top && opts.top > 0 ? out.slice(0, opts.top) : out;
+}
+/**
+ * Repo-level truck factor: the fewest top authors whose combined churn across
+ * the WHOLE history exceeds half the total. If that set is one person, a single
+ * departure takes the majority of the codebase's institutional knowledge. Pure.
+ */
+export function repoBusFactor(commits) {
+    const byAuthor = new Map();
+    let total = 0;
+    for (const c of commits) {
+        for (const f of c.files) {
+            const ch = f.added + f.deleted;
+            byAuthor.set(c.author, (byAuthor.get(c.author) ?? 0) + ch);
+            total += ch;
+        }
+    }
+    const sorted = [...byAuthor.entries()].sort((x, y) => y[1] - x[1] || (x[0] < y[0] ? -1 : x[0] > y[0] ? 1 : 0));
+    const threshold = total / 2;
+    const authors = [];
+    let cum = 0;
+    for (const [name, ch] of sorted) {
+        authors.push(name);
+        cum += ch;
+        if (cum > threshold)
+            break;
+    }
+    return { authors, factor: authors.length };
+}
+/** Export the knowledge map as CSV for spreadsheets / staffing review. Pure. */
+export function ownershipToCsv(files) {
+    const headers = ['path', 'owner', 'ownership', 'busFactor', 'authors', 'churn', 'commits', 'keyPersonRisk'];
+    const rows = files.map((f) => [f.path, f.owner, f.ownership, f.busFactor, f.authors, f.churn, f.commits, f.keyPersonRisk]);
+    return toCsv(headers, rows);
+}
+/** Human-readable knowledge map. Pure. */
+export function formatOwnership(files) {
+    if (files.length === 0)
+        return 'no ownership data found (no matching history)';
+    const lines = [];
+    lines.push('rank  bus  own%   authors  churn   commits  owner                 file');
+    files.forEach((f, i) => {
+        const rank = String(i + 1).padStart(4);
+        const bus = String(f.busFactor).padStart(3);
+        const own = `${Math.round(f.ownership * 100)}%`.padStart(5);
+        const authors = String(f.authors).padStart(7);
+        const churn = String(f.churn).padStart(6);
+        const commits = String(f.commits).padStart(7);
+        const owner = (f.owner.length > 20 ? f.owner.slice(0, 19) + '…' : f.owner).padEnd(20);
+        const risk = f.keyPersonRisk ? '  ⚠ key-person' : '';
+        lines.push(`${rank}  ${bus}  ${own}  ${authors}  ${churn}  ${commits}  ${owner}  ${f.path}${risk}`);
+    });
+    return lines.join('\n');
+}
+//# sourceMappingURL=ownership.js.map

package/v3/@swarmdo/cli/dist/src/pack/pack.d.ts

@@ -54,5 +54,5 @@ export declare function packFiles(input: PackFile[], opts?: PackOptions): PackRe
  * `dir/`, `*.ext` globs, `**` depth globs (gitignore(5) semantics), leading `/`
  * anchors, and `!` negation. Not the full spec (no nested ignore files).
  */
-export declare function makeIgnoreMatcher(patterns: string[]): (relPath: string) => boolean;
+export declare function makeIgnoreMatcher(patterns: string[]): (relPath: string, isDir?: boolean) => boolean;
 //# sourceMappingURL=pack.d.ts.map

package/v3/@swarmdo/cli/dist/src/pack/pack.js

@@ -201,19 +201,24 @@ export function makeIgnoreMatcher(patterns) {
         // Only a slash-free pattern (`dir`, `*.ext`) matches at any depth.
         const anchored = leadingSlash || body.includes('/');
         const re = new RegExp('^' + globToRegExp(body) + (dirOnly ? '(/|$)' : '($|/)'));
-        return { negate, anchored, re };
+        return { negate, anchored, dirOnly, re };
     });
     // Ignored status of a single path (last-match-wins over the ordered rules).
-    const ruleVerdict = (path) => {
+    // `isDirComponent` is whether the entry named by the path's LAST segment is a
+    // directory: a trailing-slash (dir-only) pattern matches directories ONLY per
+    // gitignore(5), so `build/` must NOT fire on a regular file named `build`.
+    const ruleVerdict = (path, isDirComponent) => {
         let ignored = false;
         for (const r of rules) {
+            if (r.dirOnly && !isDirComponent)
+                continue; // dir-only pattern can't match a file
             const candidates = r.anchored ? [path] : [path, ...path.split('/').map((_, i, a) => a.slice(i).join('/'))];
             if (candidates.some((c) => r.re.test(c)))
                 ignored = !r.negate;
         }
         return ignored;
     };
-    return (relPath) => {
+    return (relPath, isDir = false) => {
         // Walk ancestor dirs top-down: once a parent directory is excluded, the file
         // stays excluded — a negation cannot re-include under an excluded parent
         // (gitignore(5): "not possible to re-include a file if a parent directory of
@@ -227,7 +232,10 @@ export function makeIgnoreMatcher(patterns) {
                     return true;
                 continue; // excluded ancestor carries down
             }
-            const verdict = ruleVerdict(parts.slice(0, i + 1).join('/'));
+            // Ancestor prefixes are directories by construction; only the final entry's
+            // type comes from the caller (a filesystem walker knows dir vs file).
+            const componentIsDir = isLast ? isDir : true;
+            const verdict = ruleVerdict(parts.slice(0, i + 1).join('/'), componentIsDir);
             if (isLast)
                 return verdict;
             parentIgnored = verdict; // this directory prefix carries forward

package/v3/@swarmdo/cli/dist/src/redact/redact.js

@@ -44,25 +44,39 @@ export const RULES = [
  * Keyword set mirrors gitleaks' reference `generic-api-key` rule (adds bare
  * `key`, `credential`, `creds` so `PRIVATE_KEY=`/`ENCRYPTION_KEY=`/`DB_CREDENTIAL=`
  * secrets reach the entropy check). The `[:=]` immediately after the keyword
- * anchors it, so `keyboard=`/`monkey_val=` don't match; the entropy + length
- * gates keep low-entropy values (paths, short flags) from being flagged. The
- * value class also stops at the URL/query delimiters `&`, `?`, `#` (absent from
- * base64/base64url/hex token alphabets): otherwise a query-string secret like
- * `client_secret=…&api_key=…` over-captures past the `&` into the next secret,
- * and that inflated span — overlapping a range the high-confidence RULES pass
- * already claimed — gets dropped entirely, leaving the first secret unredacted.
+ * anchors it, so `keyboard=`/`monkey_val=` don't match. A `(?<![A-Za-z])` guard
+ * requires the keyword NOT be glued to a preceding letter, so a common word that
+ * merely ENDS in a keyword — `monkey=`/`donkey=`/`whiskey=`/`turkey=` (end in
+ * `key`), `compass=`/`bypass=` (end in `pass`) — is no longer flagged as a
+ * secret, while a `_`/`-`-separated name (`PRIVATE_KEY`, `x-api-key`) still
+ * matches (`_`/`-` aren't letters). The entropy + length gates keep low-entropy
+ * values (paths, short flags) out. The value class also stops at the URL/query
+ * delimiters `&`, `?`, `#` (absent from base64/base64url/hex token alphabets):
+ * otherwise a query-string secret like `client_secret=…&api_key=…` over-captures
+ * past the `&` into the next secret. It CANNOT stop at `/ : . = + ~`, though —
+ * base64/base64url/connection-string secrets contain those — so a recognized
+ * token glued on by one of them still over-captures; the entropy pass in
+ * `collectHits` handles that by CLIPPING the span at the claimed range rather
+ * than dropping the finding (which would leak the leading secret, #100).
  */
-const ASSIGNMENT_RE = /(?:pass(?:word|phrase|wd)?|pwd|secret|token|api[_-]?key|apikey|access[_-]?key|auth[_-]?token|client[_-]?secret|credential|creds|key)["']?\s*[:=]\s*["']?([^\s"'`,;&?#]{8,})/gi;
+const ASSIGNMENT_RE = /(?<![A-Za-z])(?:pass(?:word|phrase|wd)?|pwd|secret|token|api[_-]?key|apikey|access[_-]?key|auth[_-]?token|client[_-]?secret|credential|creds|key)["']?\s*[:=]\s*["']?([^\s"'`,;&?#]{8,})/gi;
 /** Shannon entropy in bits/char. Pure; used by the assignment fallback. */
 export function shannonEntropy(s) {
     if (!s)
         return 0;
+    // Iterate AND normalize by code points, not UTF-16 code units. `for..of` /
+    // spread yield one symbol per code point, but `s.length` counts an astral
+    // char (emoji, CJK Ext-B, math alphanumerics) as 2 units — so dividing the
+    // per-symbol counts by s.length made the probabilities sum to <1 and
+    // under-counted entropy up to ~2×, letting a high-entropy secret with astral
+    // chars fall under the threshold and pass through UN-redacted (#95).
+    const cps = [...s];
     const freq = new Map();
-    for (const ch of s)
+    for (const ch of cps)
         freq.set(ch, (freq.get(ch) ?? 0) + 1);
     let bits = 0;
     for (const n of freq.values()) {
-        const p = n / s.length;
+        const p = n / cps.length;
         bits -= p * Math.log2(p);
     }
     return bits;
@@ -109,15 +123,32 @@ function collectHits(text, opts) {
         while ((m = ASSIGNMENT_RE.exec(text)) !== null) {
             const value = m[1];
             const start = m.index + m[0].indexOf(value);
-            const end = start + value.length;
-            if (overlaps(start, end))
-                continue;
-            if (isAllowlisted(value, opts.allowlist))
+            let end = start + value.length;
+            let match = value;
+            // The value class must include `/ : . = + ~` for base64/base64url/conn-string
+            // secrets, so a recognized RULES token (GitHub PAT, AWS key, …) glued on by
+            // one of those separators gets over-captured into this span. When that
+            // happens, DON'T drop the finding on overlap — the leading high-entropy
+            // secret would leak in cleartext (only the trailing token got masked, #100).
+            // Instead clip the span to end at the earliest claimed range within it and
+            // re-gate the leading fragment; the trailing token keeps its RULES redaction.
+            const overlapping = claimed.filter(([s, e]) => start < e && end > s);
+            if (overlapping.length > 0) {
+                // value's own start already sits inside a claimed secret → fully covered
+                if (overlapping.some(([s, e]) => s <= start && start < e))
+                    continue;
+                const clipTo = Math.min(...overlapping.map(([s]) => s));
+                match = text.slice(start, clipTo).replace(/[^A-Za-z0-9]+$/, ''); // drop the trailing separator
+                end = start + match.length;
+                if (match.length < 8)
+                    continue; // clipped leading fragment too short to be a secret
+            }
+            if (isAllowlisted(match, opts.allowlist))
                 continue;
-            if (shannonEntropy(value) < threshold)
+            if (shannonEntropy(match) < threshold)
                 continue;
             claimed.push([start, end]);
-            hits.push({ ruleId: 'high-entropy-assignment', description: 'High-entropy secret assignment', index: start, match: value });
+            hits.push({ ruleId: 'high-entropy-assignment', description: 'High-entropy secret assignment', index: start, match });
         }
     }
     return hits.sort((a, b) => a.index - b.index);

package/v3/@swarmdo/cli/dist/src/redact/sarif.d.ts

@@ -0,0 +1,28 @@
+/**
+ * sarif.ts — render redact secret-scan findings as a SARIF 2.1.0 document.
+ *
+ * SARIF (Static Analysis Results Interchange Format) is a ratified OASIS
+ * standard that GitHub code-scanning ingests via `github/codeql-action/
+ * upload-sarif`. Emit it from `redact --scan` in CI and leaked-secret findings
+ * surface as alerts in the Security tab + PR annotations instead of dying in
+ * the build log — the same thing gitleaks/trufflehog/ggshield do with their
+ * `--report-format sarif`.
+ *
+ * Pure + deterministic: findings in, JSON string out. No fs/network.
+ */
+import type { Finding } from './redact.js';
+export interface SarifOptions {
+    /** SARIF tool.driver.name (default 'swarmdo-redact') */
+    toolName?: string;
+    /** SARIF tool.driver.version — omitted from the document when not given */
+    toolVersion?: string;
+    /**
+     * URI for the artifact each finding lives in. `redact --scan` reads a STREAM
+     * (stdin / wrapped output), so there is no committed file by default; pass
+     * this (e.g. from `--source <path>`) to anchor the alerts onto a repo path.
+     */
+    artifactUri?: string;
+}
+/** Render `findings` as a SARIF 2.1.0 document string. Pure + deterministic. */
+export declare function toSarif(findings: Finding[], opts?: SarifOptions): string;
+//# sourceMappingURL=sarif.d.ts.map

package/v3/@swarmdo/cli/dist/src/redact/sarif.js

@@ -0,0 +1,53 @@
+/**
+ * sarif.ts — render redact secret-scan findings as a SARIF 2.1.0 document.
+ *
+ * SARIF (Static Analysis Results Interchange Format) is a ratified OASIS
+ * standard that GitHub code-scanning ingests via `github/codeql-action/
+ * upload-sarif`. Emit it from `redact --scan` in CI and leaked-secret findings
+ * surface as alerts in the Security tab + PR annotations instead of dying in
+ * the build log — the same thing gitleaks/trufflehog/ggshield do with their
+ * `--report-format sarif`.
+ *
+ * Pure + deterministic: findings in, JSON string out. No fs/network.
+ */
+const SARIF_SCHEMA = 'https://json.schemastore.org/sarif-2.1.0.json';
+const INFO_URI = 'the upstream project (see NOTICE)';
+/** Render `findings` as a SARIF 2.1.0 document string. Pure + deterministic. */
+export function toSarif(findings, opts = {}) {
+    const toolName = opts.toolName ?? 'swarmdo-redact';
+    // One rule descriptor per distinct ruleId, in first-seen order. Findings
+    // carry their own description, so the entropy fallback (not in RULES) is
+    // covered too — every result.ruleId is guaranteed to appear in rules[].
+    const ruleIndex = new Map();
+    const rules = [];
+    for (const f of findings) {
+        if (ruleIndex.has(f.ruleId))
+            continue;
+        ruleIndex.set(f.ruleId, rules.length);
+        rules.push({ id: f.ruleId, name: f.ruleId, shortDescription: { text: f.description } });
+    }
+    const results = findings.map((f) => {
+        const physicalLocation = {
+            region: { startLine: f.line, startColumn: f.column },
+        };
+        if (opts.artifactUri)
+            physicalLocation.artifactLocation = { uri: opts.artifactUri };
+        return {
+            ruleId: f.ruleId,
+            ruleIndex: ruleIndex.get(f.ruleId),
+            level: 'error',
+            message: { text: `Possible secret: ${f.description}` },
+            locations: [{ physicalLocation }],
+        };
+    });
+    const driver = { name: toolName, informationUri: INFO_URI, rules };
+    if (opts.toolVersion)
+        driver.version = opts.toolVersion;
+    const doc = {
+        $schema: SARIF_SCHEMA,
+        version: '2.1.0',
+        runs: [{ tool: { driver }, results }],
+    };
+    return JSON.stringify(doc, null, 2);
+}
+//# sourceMappingURL=sarif.js.map

package/v3/@swarmdo/cli/dist/src/release/release.d.ts

@@ -69,4 +69,23 @@ export declare const DOC_FILES: string[];
 export declare function planRelease(input: ReleaseInput): ReleasePlan;
 /** One-line human rendering of a step (for the dry-run plan). */
 export declare function renderStep(s: ReleaseStep): string;
+export interface SiteIdentity {
+    name: string;
+    email: string;
+}
+/**
+ * Resolve the committer identity for the throwaway swarmdo.com clone. That
+ * clone inherits no identity, and a machine may have only a *local* (per-repo)
+ * git user — so `git commit` there dies with "Author identity unknown" unless
+ * we inject one. Prefer the operator's configured identity; fall back to the
+ * Swarmdo bot so the site deploy never fails on a missing global git config.
+ * `readConfig` is injected (real: `git -C <root> config <key>`) so this stays
+ * pure and unit-testable.
+ */
+export declare function resolveSiteIdentity(readConfig: (key: string) => string | undefined): SiteIdentity;
+/**
+ * `git commit` argv for the site sync — injects the identity via `-c` so the
+ * commit succeeds without a global git user, and keeps the bot co-author trailer.
+ */
+export declare function siteCommitArgs(version: string, id: SiteIdentity): string[];
 //# sourceMappingURL=release.d.ts.map

package/v3/@swarmdo/cli/dist/src/release/release.js

@@ -83,4 +83,32 @@ export function renderStep(s) {
         case 'deploy-site': return `deploy website → SwarmDo/swarmdo.com (copy working copy, push, curl-verify swarmdo.com serves ${s.version})`;
     }
 }
+/**
+ * Resolve the committer identity for the throwaway swarmdo.com clone. That
+ * clone inherits no identity, and a machine may have only a *local* (per-repo)
+ * git user — so `git commit` there dies with "Author identity unknown" unless
+ * we inject one. Prefer the operator's configured identity; fall back to the
+ * Swarmdo bot so the site deploy never fails on a missing global git config.
+ * `readConfig` is injected (real: `git -C <root> config <key>`) so this stays
+ * pure and unit-testable.
+ */
+export function resolveSiteIdentity(readConfig) {
+    const name = (readConfig('user.name') || '').trim();
+    const email = (readConfig('user.email') || '').trim();
+    return {
+        name: name || 'Swarmdo',
+        email: email || 'maintainers@swarmdo.com',
+    };
+}
+/**
+ * `git commit` argv for the site sync — injects the identity via `-c` so the
+ * commit succeeds without a global git user, and keeps the bot co-author trailer.
+ */
+export function siteCommitArgs(version, id) {
+    return [
+        '-c', `user.name=${id.name}`,
+        '-c', `user.email=${id.email}`,
+        'commit', '-m', `release: sync site for v${version}\n\nCo-Authored-By: Swarmdo <maintainers@swarmdo.com>`,
+    ];
+}
 //# sourceMappingURL=release.js.map

package/v3/@swarmdo/cli/dist/src/usage/reflect.d.ts

@@ -90,7 +90,15 @@ export declare function nextDay(iso: string): string;
  * Pure. Used to derive a `--period 1m|3m|…` window start from today.
  */
 export declare function monthsBefore(iso: string, n: number): string;
-/** Inclusive whole-day span between two ISO dates (from <= to). Pure. */
+/**
+ * Inclusive whole-day span between two ISO dates (from <= to). Pure.
+ *
+ * Counts on the UTC timeline (`Date.UTC`), NOT local midnights: a local
+ * `new Date('…T00:00:00')` is DST-sensitive, so a range crossing a spring-forward
+ * day (only 23h long) would floor-divide to one day short — e.g. under
+ * TZ=America/New_York a full March would read 30. UTC calendar midnights are
+ * always an exact 86.4M ms apart, so this is correct in every process timezone.
+ */
 export declare function spanDays(from: string, to: string): number;
 /** Longest run of consecutive calendar days present in the set. Pure. */
 export declare function longestStreakOf(days: string[]): number;