@attalabs/vinaya 0.22.0 → 0.24.0

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/consumer-enumeration.ts

@@ -0,0 +1,75 @@
+/**
+ * `checkConsumerTests`'s consumer enumeration (`brief-validation.ts`, task 10,
+ * Issue #385; corrected by the round-2 ruling item 3) — every workspace
+ * member whose own `package.json` depends on `@attalabs/<pkg>`, for "every
+ * workspace package depending on `@attalabs/<pkg>`" to mean what it says.
+ *
+ * The first cut reused `deriveWorkspacePackageDomains` (`blast-radius-domains.ts`),
+ * which deliberately collapses to `packages/*` members only — correct for
+ * that module's own collision-domain purpose, wrong here: it silently
+ * exempted `apps/cli`, a real `@attalabs/aeg-core` consumer, from a rule
+ * that promises "every workspace package" (found live reviewing this PR's
+ * own diff). This module resolves every workspace glob instead —
+ * `apps/*` and `packages/*` alike — via `resolveWorkspaceEntry`, the same
+ * glob grammar `deriveWorkspacePackageDomains` uses, reused rather than
+ * re-derived a second time.
+ *
+ * Zero I/O: `listDirs`/`readManifest` are injected by each of the two real
+ * entry points — `packages/aeg-core/bin/verify-brief.ts` (authoring-time,
+ * pre-dispatch) and `apps/cli`'s `check-brief-shape.ts` (CI) — so both share
+ * ONE enumeration rather than two independently-maintained copies that can
+ * silently diverge (round-2 ruling item 4).
+ */
+
+import { resolveWorkspaceEntry } from './blast-radius-domains'
+
+export type PackageManifest = { dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+
+/**
+ * Every workspace member directory (`apps/cli`, `packages/aeg-core`, …),
+ * resolved from `workspaces` (positive entries minus any `!`-negated ones,
+ * same semantics as `deriveWorkspacePackageDomains`) — but NOT collapsed to
+ * `packages/*` only, since a real consumer can live anywhere in the
+ * workspace.
+ */
+export function deriveWorkspaceMemberDirs(workspaces: string[], listDirs: (dir: string) => string[]): string[] {
+  const positive = workspaces.filter((entry) => !entry.startsWith('!'))
+  const negative = workspaces.filter((entry) => entry.startsWith('!')).map((entry) => entry.slice(1))
+
+  const excluded = new Set<string>()
+  for (const entry of negative) {
+    for (const member of resolveWorkspaceEntry(entry, listDirs)) excluded.add(member)
+  }
+
+  const members = new Set<string>()
+  for (const entry of positive) {
+    for (const member of resolveWorkspaceEntry(entry, listDirs)) {
+      if (!excluded.has(member)) members.add(member)
+    }
+  }
+  return [...members].sort()
+}
+
+/**
+ * Builds `checkConsumerTests`'s `consumersOf` callback: for a package `pkg`
+ * (as named in a brief's `§4`, e.g. `packages/aeg-core/` → `'aeg-core'`),
+ * every workspace member directory (self excluded) whose own manifest lists
+ * `@attalabs/<pkg>` in `dependencies` or `devDependencies`.
+ */
+export function buildConsumersOf(
+  workspaces: string[],
+  listDirs: (dir: string) => string[],
+  readManifest: (dir: string) => PackageManifest | null
+): (pkg: string) => string[] {
+  const members = deriveWorkspaceMemberDirs(workspaces, listDirs)
+
+  return (pkg: string): string[] => {
+    const target = `@attalabs/${pkg}`
+    return members.filter((dir) => {
+      if (dir === `packages/${pkg}`) return false
+      const manifest = readManifest(dir)
+      if (!manifest) return false
+      return target in (manifest.dependencies ?? {}) || target in (manifest.devDependencies ?? {})
+    })
+  }
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/dead-branch-push-audit.ts

@@ -0,0 +1,55 @@
+/**
+ * Dead-branch-push AUDIT (aeg-governance-hardening task 24, #364, Part 4 —
+ * item 2). Distinct from the ring-0 `dead-branch-push-guard.ts` (task 18):
+ * that predicate answers "should THIS push be allowed right now?" at push
+ * time; this one answers "did commits land on a branch AFTER its PR already
+ * resolved?" retrospectively, across every remote `task/*` branch — the
+ * ring-2 backstop for the class the ring-0 hook is fail-open/hook-dependent
+ * against (a writer without the hook installed, or a hook bypass). Pure —
+ * no `fs`, no `gh`/`git` shell-outs. The CLI shim (`bin/dead-branch-audit.ts`,
+ * joining task 23's `daily-drift` job) gathers each branch's most recent
+ * PR (any state) plus its resolution/latest-commit timestamps and passes
+ * them in here.
+ *
+ * Exists to catch the "six topology rows landed on a merged plan PR's
+ * branch" incident class (2026-07-03) server-side, within a day, instead of
+ * never — never-red discipline: `daily-drift` (the CI job that calls this)
+ * must never fail red.
+ */
+
+export type DeadBranchFact = {
+  branch: string
+  prNumber: number
+  prState: 'MERGED' | 'CLOSED'
+  /** ISO timestamp the branch's PR was merged (MERGED) or closed (CLOSED). */
+  resolvedAt: string
+  /** ISO commit date of the branch's current remote tip. */
+  latestCommitAt: string
+}
+
+export type DeadBranchPush = {
+  branch: string
+  prNumber: number
+  prState: 'MERGED' | 'CLOSED'
+  resolvedAt: string
+  latestCommitAt: string
+}
+
+/**
+ * Flags a branch whose current tip commit is strictly newer than its own
+ * PR's resolution time — i.e. commits kept landing on a branch after the
+ * forge already considered its work done. A branch whose tip predates (or
+ * exactly matches) its PR's resolution is normal: the branch simply hasn't
+ * been deleted yet, which is not itself a violation.
+ */
+export function findDeadBranchPushes(facts: DeadBranchFact[]): DeadBranchPush[] {
+  return facts
+    .filter((f) => new Date(f.latestCommitAt).getTime() > new Date(f.resolvedAt).getTime())
+    .map(({ branch, prNumber, prState, resolvedAt, latestCommitAt }) => ({
+      branch,
+      prNumber,
+      prState,
+      resolvedAt,
+      latestCommitAt
+    }))
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/dead-branch-push-guard.ts

@@ -0,0 +1,77 @@
+/**
+ * Dead-branch push guard (aeg-governance-hardening task 18, #335). Pure — no
+ * `fs`, no `gh`/`git` shell-outs. The CLI shim (`bin/check-push-target.ts`)
+ * makes the one batched forge call (`gh pr list --head <branch> --state all
+ * --json number,state --limit 1`), maps its result to a `PrStateFact`, and
+ * passes it in here.
+ *
+ * Exists to answer, deterministically, "is it safe to push more commits to
+ * this `task/<tranche>/<n>` branch?" — closing the live-fire incident
+ * class where stale local work landed on a branch whose PR had already
+ * merged, silently reopening/confusing forge state with no push-time signal.
+ *
+ * `UNKNOWN` (forge unreachable — network flake, auth issue, rate limit) maps
+ * to `allow`, the same as `NONE` (no PR exists yet — a brand-new branch
+ * legitimately has none). This is a deliberate fail-open choice: a guard
+ * that can block *all* pushes on a transient forge-reachability issue is
+ * worse than the bug it fixes. See `aeg-root/enforcement.md`.
+ */
+
+export type PrStateFact = 'MERGED' | 'CLOSED' | 'OPEN' | 'NONE' | 'UNKNOWN'
+
+export type DeadBranchPushInput = {
+  /** The `task/<tranche>/<n>` branch being pushed. */
+  branch: string
+  /** State of the branch's most recent PR (any state), or the fact that none/forge-unreachable applies. */
+  prState: PrStateFact
+  /** The PR number that `prState` refers to, or `null` when no PR exists / could not be determined. */
+  prNumber: number | null
+}
+
+export type DeadBranchPushVerdict = 'allow' | 'refuse'
+
+export type DeadBranchPushResult = { verdict: DeadBranchPushVerdict; reason: string }
+
+/**
+ * `allow`  — `OPEN`/`NONE`/`UNKNOWN`: an in-flight PR, no PR yet, or the
+ *            forge couldn't be reached — all legitimate reasons to push.
+ * `refuse` — `MERGED`/`CLOSED`: the branch's most recent PR is already
+ *            resolved. Pushing here would silently resurrect resolved forge
+ *            state instead of starting a fresh branch.
+ */
+export function checkDeadBranchPush(input: DeadBranchPushInput): DeadBranchPushResult {
+  const { branch, prState, prNumber } = input
+
+  if (prState === 'MERGED') {
+    return {
+      verdict: 'refuse',
+      reason: `Branch \`${branch}\` already has a MERGED PR (#${prNumber}) — this branch's work is done. Push a new task branch instead of pushing onto an already-resolved one.`
+    }
+  }
+
+  if (prState === 'CLOSED') {
+    return {
+      verdict: 'refuse',
+      reason: `Branch \`${branch}\` has a CLOSED PR (#${prNumber}) that was never merged — pushing here would resurrect abandoned/rejected work. Open a new task branch instead.`
+    }
+  }
+
+  if (prState === 'OPEN') {
+    return {
+      verdict: 'allow',
+      reason: `Branch \`${branch}\` has an OPEN PR (#${prNumber}) — pushing more commits to it is normal.`
+    }
+  }
+
+  if (prState === 'NONE') {
+    return {
+      verdict: 'allow',
+      reason: `Branch \`${branch}\` has no PR yet — a brand-new task branch legitimately has none.`
+    }
+  }
+
+  return {
+    verdict: 'allow',
+    reason: `Could not determine \`${branch}\`'s PR state (forge unreachable) — failing open rather than blocking the push on a transient issue.`
+  }
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/derive-section7.ts

@@ -0,0 +1,66 @@
+/**
+ * Derive the floor of a task's §7 doc-update list by matching its intended
+ * surface globs against `.vinaya/doc-owners` bindings (state-machine.md
+ * Section 15). Pure — parses doc-owners content via `parseDocOwners` (no
+ * second parser) and does segment-wise glob overlap between each intended
+ * surface and each binding's code glob. A Planner/Brief-Author aid only —
+ * not wired into any CI gate.
+ */
+
+import { parseDocOwners } from './doc-owners'
+
+export type Section7Match = { surface: string; glob: string; pointer: string; lineNum: number }
+
+export function deriveSection7(
+  intendedSurfaces: string[],
+  docOwnersContent: string
+): { pointers: string[]; matches: Section7Match[]; errors: string[] } {
+  const { bindings, errors } = parseDocOwners(docOwnersContent)
+  const matches: Section7Match[] = []
+  for (const surface of intendedSurfaces) {
+    for (const binding of bindings) {
+      if (globsOverlap(binding.glob, surface)) {
+        matches.push({ surface, glob: binding.glob, pointer: binding.pointer, lineNum: binding.lineNum })
+      }
+    }
+  }
+
+  const pointers: string[] = []
+  for (const m of matches) {
+    if (!pointers.includes(m.pointer)) pointers.push(m.pointer)
+  }
+
+  return { pointers, matches, errors }
+}
+
+/**
+ * True if two doc-owners-grammar globs can match at least one common path,
+ * compared segment-by-segment (split on `/`). `**` absorbs zero or more
+ * remaining segments on either side — checked at each step, even once one
+ * side has run out of segments, so a trailing `**` still absorbs. `*`
+ * matches exactly one segment regardless of the other side's literal/`*`.
+ * Two literal segments must be byte-equal. If one side runs out of segments
+ * before the other and the next pending segment on either side isn't `**`,
+ * there is no overlap.
+ */
+export function globsOverlap(a: string, b: string): boolean {
+  const segsA = a.split('/')
+  const segsB = b.split('/')
+  let i = 0
+  let j = 0
+  while (i < segsA.length || j < segsB.length) {
+    const sa = i < segsA.length ? segsA[i] : undefined
+    const sb = j < segsB.length ? segsB[j] : undefined
+    if (sa === '**' || sb === '**') return true
+    if (sa === undefined || sb === undefined) return false
+    if (sa === '*' || sb === '*') {
+      i++
+      j++
+      continue
+    }
+    if (sa !== sb) return false
+    i++
+    j++
+  }
+  return true
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/derive-tranche.ts

@@ -0,0 +1,94 @@
+import { deriveStatusFromModel } from './state-machine-model'
+import type { DerivedTranche, DerivedStatus, DerivedTask, ForgeFacts, Tranche, Task, UnknownEdge } from './types'
+
+/**
+ * Compute each task's derived status, the resolved depends-on / conflicts-with
+ * graph, and dispatch-eligibility per `tranche-model.md` §3 (status table)
+ * and §8 (dispatch gates).
+ *
+ * The function is pure: `tranche` + `forgeFacts` in, `DerivedTranche` out.
+ * Edges referencing task ids not present in this tranche's table are
+ * reported via `unknownEdges` rather than throwing — see §4 traps in the brief
+ * (real files reference dropped/prose-only ids in narrative).
+ */
+export function deriveTranche(tranche: Tranche, forgeFacts: Map<string, ForgeFacts>): DerivedTranche {
+  const byId = new Map<string, Task>()
+  for (const task of tranche.tasks) byId.set(task.id, task)
+
+  // First pass: derive each task's own status.
+  const statuses = new Map<string, DerivedStatus>()
+  for (const task of tranche.tasks) {
+    statuses.set(task.id, deriveStatus(forgeFacts.get(task.id)))
+  }
+
+  // Second pass: dispatch eligibility, which references siblings' derived
+  // statuses (so it must come after the first pass).
+  const unknownEdges: UnknownEdge[] = []
+  const derived: DerivedTask[] = []
+  for (const task of tranche.tasks) {
+    const status = statuses.get(task.id) ?? 'todo'
+    const dependsOnNotMerged: string[] = []
+    for (const dep of task.dependsOn) {
+      if (!byId.has(dep)) {
+        unknownEdges.push({ from: task.id, to: dep, kind: 'depends-on' })
+        continue
+      }
+      if (statuses.get(dep) !== 'merged') dependsOnNotMerged.push(dep)
+    }
+    const conflictsWithOpenOrInFlight: string[] = []
+    for (const sib of task.conflictsWith) {
+      if (!byId.has(sib)) {
+        unknownEdges.push({ from: task.id, to: sib, kind: 'conflicts-with' })
+        continue
+      }
+      const sibStatus = statuses.get(sib)
+      if (sibStatus === 'in-flight' || sibStatus === 'in-review' || sibStatus === 'changes-requested') {
+        conflictsWithOpenOrInFlight.push(sib)
+      }
+    }
+    derived.push({
+      task,
+      status,
+      dispatchable: dependsOnNotMerged.length === 0 && conflictsWithOpenOrInFlight.length === 0,
+      blockers: { dependsOnNotMerged, conflictsWithOpenOrInFlight }
+    })
+  }
+
+  return { tranche, tasks: derived, unknownEdges }
+}
+
+/**
+ * Map a single task's forge facts to its derived status. Mirrors the §3 table
+ *: `blocked` wins over everything else, then `merged`, then
+ * `changes-requested`, then `in-review`, then `in-flight`, then `todo` for the
+ * open-issue cases (assigned or not — both are `todo` inside a tranche per
+ *), then the honest terminal cases for a closed-without-merge Issue.
+ *
+ * Reopened-after-merge exception: a reopened Issue can carry a stale
+ * `prState: 'merged'` fact from a closing PR that predates the reopen —
+ * `issueState` and `prState` are independently sourced, and GitHub does not
+ * retract a PR's merge history just because the Issue reopened. Without this
+ * check, such a task would permanently display `merged` even though the work
+ * it names was never actually done. Checked before the `prState === 'merged'`
+ * branch below so a currently-open Issue always wins over a historical merge.
+ *
+ * Honest terminal derivation: a closed Issue with no merged PR must
+ * never resolve to `todo` (which would imply not-started — a lie). It reads
+ * GitHub's native `stateReason`: closed `NOT_PLANNED` → `dropped` (legitimately
+ * abandoned); anything else (closed `COMPLETED` or no reason recorded) →
+ * `incoherent` (genuinely done but unprovable, or a broken close that the
+ * `Closes #N` law was built to surface).
+ *
+ * A missing `forgeFacts` entry → `todo`. Tranche tasks are committed work;
+ * `backlog` is a project-level concept only and is never emitted here.
+ *
+ * The rules themselves are no longer written here. They live as an ordered,
+ * pure-data list in `state-machine-model.ts` (the `actions.ts`
+ * discipline): one list, executed by this function and rendered by the docs,
+ * so the two cannot drift. Each rule carries the prose and the reason its
+ * position matters — change the order there, and this function's behavior
+ * changes with it.
+ */
+function deriveStatus(facts: ForgeFacts | undefined): DerivedStatus {
+  return deriveStatusFromModel(facts)
+}