@workit-dev/core 0.0.1 → 1.0.0

package/src/core/policy/attributes.ts

@@ -0,0 +1,97 @@
+// `linguist-generated` from the `.gitattributes` files of one tree (#333,
+// review finding mvkcoxgb). The review lane reads them from the base
+// revision only: never `.git/info/attributes`, a global attributes file or
+// the working tree, so a change cannot mark its own code generated. What this
+// parser does not understand (quoted patterns, macros, directory patterns)
+// marks nothing generated, which only raises a lane.
+
+type Rule = { regex: RegExp; generated: boolean };
+
+/** A gitattributes pattern relative to `dir` ("" for the root) as a regex over repo paths. */
+function patternRegex(dir: string, pattern: string): RegExp | null {
+  if (!pattern || pattern.endsWith("/") || pattern.startsWith('"') || pattern.startsWith("!"))
+    return null;
+  const anchored = pattern.includes("/");
+  const body = pattern.replace(/^\//u, "");
+  let source = "";
+  for (let index = 0; index < body.length; index += 1) {
+    const char = body[index];
+    if (char === "*" && body[index + 1] === "*") {
+      const slash = body[index + 2] === "/";
+      source += slash ? "(?:.*/)?" : ".*";
+      index += slash ? 2 : 1;
+    } else if (char === "*") source += "[^/]*";
+    else if (char === "?") source += "[^/]";
+    else if (char === "[") {
+      const end = body.indexOf("]", index + 2);
+      if (end < 0) return null;
+      const set = body
+        .slice(index + 1, end)
+        .replace(/^!/u, "^")
+        .replace(/\\/gu, "\\\\");
+      source += `[${set}]`;
+      index = end;
+    } else if (char === "\\" && index + 1 < body.length) {
+      source += body[index + 1].replace(/[.*+?^${}()|[\]\\/]/gu, "\\$&");
+      index += 1;
+    } else source += char.replace(/[.*+?^${}()|[\]\\/]/gu, "\\$&");
+  }
+  const prefix = dir ? `${dir.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}/` : "";
+  try {
+    return new RegExp(anchored ? `^${prefix}${source}$` : `^${prefix}(?:.*/)?${source}$`, "u");
+  } catch {
+    return null;
+  }
+}
+
+/** The `linguist-generated` rules of one `.gitattributes` file in `dir`. */
+function rulesOf(dir: string, text: string): Rule[] {
+  const out: Rule[] = [];
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#") || line.startsWith("[attr]")) continue;
+    const [pattern, ...attributes] = line.split(/\s+/u);
+    let generated: boolean | null = null;
+    for (const attribute of attributes) {
+      if (attribute === "linguist-generated" || attribute === "linguist-generated=true")
+        generated = true;
+      else if (
+        attribute === "-linguist-generated" ||
+        attribute === "!linguist-generated" ||
+        attribute.startsWith("linguist-generated=")
+      )
+        generated = false;
+    }
+    if (generated === null) continue;
+    const regex = patternRegex(dir, pattern);
+    if (regex) out.push({ regex, generated });
+  }
+  return out;
+}
+
+/**
+ * Of `paths`, those the `.gitattributes` files of one tree mark
+ * `linguist-generated` (`files`: each file's repo path and text). A deeper
+ * file overrides a shallower one, and a later line an earlier one.
+ */
+export function generatedByAttributes(
+  files: ReadonlyMap<string, string>,
+  paths: readonly string[],
+): Set<string> {
+  const rules = [...files]
+    .map(([file, text]) => {
+      const dir = file.includes("/") ? file.slice(0, file.lastIndexOf("/")) : "";
+      return {
+        depth: dir ? dir.split("/").length : 0,
+        rules: rulesOf(dir, text),
+      };
+    })
+    .toSorted((left, right) => left.depth - right.depth)
+    .flatMap((entry) => entry.rules);
+  const out = new Set<string>();
+  for (const file of paths) {
+    const last = rules.findLast((rule) => rule.regex.test(file));
+    if (last?.generated) out.add(file);
+  }
+  return out;
+}

package/src/core/policy/bookkeeping.ts

@@ -0,0 +1,119 @@
+// What a verdict carry may leave out of the branch's own change (#334 follow-up):
+//
+//   trunk-only   after a rebase, the judged head replayed onto the new fork
+//                point (replayTree: a 3-way merge anchored at the old fork).
+//                What the current head changes against that replay is the
+//                branch's own change; the rest came from trunk.
+//   bookkeeping  a JSON manifest whose only change is its top-level `version`
+//                string (a release sync), or a non-code file that a root
+//                package.json `write:*` script regenerates (read at the base
+//                revision, so a branch cannot name its own file). Changelogs
+//                are docs already (lane.ts).
+//
+// Both fail closed: a file git cannot read stays in the change.
+import { spawnSync } from "node:child_process";
+import { fileAt, GIT_TIMEOUTS } from "../../git/rev";
+
+const OID = /^[0-9a-f]{40,64}$/u;
+const safe = (value: string): boolean => value.length > 0 && !value.startsWith("-");
+
+/**
+ * The tree of the judged head `from` replayed onto `toFork`, anchored at
+ * `fromFork`, conflicts included (conflicted files hold markers, so they
+ * never equal a resolved file). Null when git cannot build it (before 2.40).
+ */
+export function replayTree(
+  cwd: string,
+  from: string,
+  fromFork: string,
+  toFork: string,
+): string | null {
+  if (![from, fromFork, toFork].every(safe)) return null;
+  const run = spawnSync(
+    "git",
+    ["merge-tree", "--write-tree", "--no-messages", `--merge-base=${fromFork}`, toFork, from],
+    {
+      cwd,
+      encoding: "utf8",
+      timeout: GIT_TIMEOUTS.worktree,
+      killSignal: "SIGKILL",
+      windowsHide: true,
+    },
+  );
+  // 0: clean, 1: conflicts (the tree is still written); anything else failed.
+  if (run.status !== 0 && run.status !== 1) return null;
+  const tree = (run.stdout ?? "").split("\n")[0]?.trim() ?? "";
+  return OID.test(tree) ? tree : null;
+}
+
+const SEMVER = /^v?\d+\.\d+\.\d+(?:[-+][\w.+-]*)?$/u;
+
+const parseObject = (text: string | null): Record<string, unknown> | null => {
+  if (text === null) return null;
+  try {
+    const value: unknown = JSON.parse(text);
+    return value && typeof value === "object" && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+};
+
+/** Both sides are JSON objects that differ only in a top-level semver `version` string. */
+export function versionOnlyChange(before: string | null, after: string | null): boolean {
+  const a = parseObject(before);
+  const b = parseObject(after);
+  if (!a || !b) return false;
+  const { version: va, ...restA } = a;
+  const { version: vb, ...restB } = b;
+  if (typeof va !== "string" || typeof vb !== "string") return false;
+  if (!SEMVER.test(va) || !SEMVER.test(vb)) return false;
+  return JSON.stringify(restA) === JSON.stringify(restB);
+}
+
+const CODE = /\.(?:[cm]?[jt]sx?)$/u;
+const SCRIPT_FILE = /[\w./-]+\.[cm]?[jt]s\b/gu;
+
+/**
+ * Of `paths`, the non-code files a root package.json `write:*` script at
+ * `rev` regenerates: the script's source names the path (fanout.ts
+ * regeneratedFiles reads the working tree; this reads one revision).
+ */
+function regeneratedAt(cwd: string, rev: string, paths: readonly string[]): Set<string> {
+  const found = new Set<string>();
+  const outputs = paths.filter((file) => !CODE.test(file));
+  if (!outputs.length) return found;
+  const manifest = parseObject(fileAt(cwd, rev, "package.json"));
+  const scripts = manifest?.scripts;
+  if (!scripts || typeof scripts !== "object") return found;
+  for (const [name, command] of Object.entries(scripts as Record<string, unknown>)) {
+    if (!name.startsWith("write:") || typeof command !== "string") continue;
+    for (const file of command.match(SCRIPT_FILE) ?? []) {
+      const source = fileAt(cwd, rev, file.replace(/^\.\//u, ""));
+      if (source === null) continue;
+      for (const output of outputs) if (source.includes(output)) found.add(output);
+    }
+  }
+  return found;
+}
+
+/**
+ * Of `paths` changed between the judged `from` and the current `to`, the
+ * bookkeeping ones: a version-only manifest change, or a file a `write:*`
+ * script at `base` regenerates.
+ */
+export function bookkeepingPaths(
+  cwd: string,
+  input: { from: string; to: string; base: string; paths: readonly string[] },
+): Set<string> {
+  const found = regeneratedAt(cwd, input.base, input.paths);
+  for (const file of input.paths)
+    if (
+      !found.has(file) &&
+      file.endsWith(".json") &&
+      versionOnlyChange(fileAt(cwd, input.from, file), fileAt(cwd, input.to, file))
+    )
+      found.add(file);
+  return found;
+}

package/src/core/policy/carry.ts

@@ -0,0 +1,122 @@
+// Verdict carry-over across a follow-up change (#334, decision mvk5q3io): a
+// verdict judged head H; the branch is now at H'. The branch's own change
+// since H (what came from the base left out, see lane.ts driftFiles) is
+// classified with the review lane, and the verdict still applies when:
+//
+//   rebase      the branch was rebased and every file it touches is exactly
+//               the judged change replayed onto the new fork point: only
+//               trunk's commits differ (bookkeeping.ts replayTree);
+//   lane-none   that change is lane `none`: docs (a changelog included),
+//               comment or formatting-only edits, generated copies (by the
+//               base's .gitattributes), bookkeeping (a version-only manifest
+//               change, a file a `write:*` script regenerates), or nothing at
+//               all (an empty commit);
+//   tests-only  the verdict is kind `unit` and every changed file is a test
+//               file proper (`*.test.*`, `*.spec.*`, `*_test.*`; not a helper,
+//               fixture or config under a test folder), docs or bookkeeping,
+//               off risk paths, with no lockfile and no binary, whatever its
+//               size and whatever the PR's own lane.
+//
+// After a rebase, a file whose current content is the judged change replayed
+// onto the new fork is left out before the lane is read: a trunk edit in a
+// branch file never counts as the branch's change, and a file whose result
+// differs (a hand-resolved conflict, an amend, even whitespace) always does.
+//
+// Everything else is stale, failing closed: a behavior or risk-path change,
+// an opaque file, an unreadable diff, a judged head git no longer has. A
+// stale verdict whose change is lane `self` (small, no risk path, nothing
+// opaque) asks only a focused re-verify of the changed files.
+import { mergeBase, fileAt } from "../../git/rev";
+import { bookkeepingPaths, replayTree } from "./bookkeeping";
+import {
+  computeLane,
+  driftFiles,
+  kindOf,
+  laneFiles,
+  parseRiskPaths,
+  type ChangedFile,
+  RISK_PATHS_FILE,
+} from "./lane";
+
+/** `rebase`: the same patch on a moved base (ledger.ts exact carry, or every branch file replays). */
+export type CarryRule = "lane-none" | "tests-only" | "rebase";
+
+export type Drift =
+  | { carries: true; rule: CarryRule; since: string; files: string[] }
+  | {
+      carries: false;
+      since: string;
+      /** The changed files, or null when they cannot be read. */
+      files: string[] | null;
+      /** A focused re-verify of `files` is enough (lane self). */
+      focused: boolean;
+      reason: string;
+    };
+
+const TEST_ONLY_KINDS: ReadonlySet<string> = new Set(["doc", "cosmetic", "generated"]);
+/**
+ * A test file proper, by name (`*.test.ts`, `*.spec.js` and the other JS/TS
+ * extensions, Go's `*_test.go`). A helper, fixture, setup or config file is
+ * not one, even with `.test.` mid-name (`foo.test.helper.ts`, `a.test.json`):
+ * product scripts import such helpers and test runners preload them.
+ */
+const TEST_FILE = /\.(?:test|spec)\.[cm]?[jt]sx?$|_test\.[^./]+$/iu;
+const testOnly = (file: ChangedFile): boolean => {
+  const kind = kindOf(file);
+  return TEST_ONLY_KINDS.has(kind) || (kind === "test" && TEST_FILE.test(file.path));
+};
+
+/**
+ * Whether a `kind` verdict at `from` (keyed against `fromBase`, a commit)
+ * still applies at `to` (against `toBase`).
+ */
+export function verdictDrift(
+  cwd: string,
+  input: { from: string; to: string; fromBase: string; toBase: string; kind: string },
+): Drift {
+  const since = input.from;
+  const stale = (reason: string, files: string[] | null = null, focused = false): Drift => ({
+    carries: false,
+    since,
+    files,
+    focused,
+    reason,
+  });
+  const fromFork = mergeBase(cwd, input.fromBase, input.from);
+  const toFork = mergeBase(cwd, input.toBase, input.to);
+  const range = fromFork && toFork ? { from: input.from, to: input.to, fromFork, toFork } : null;
+  const drifted = range ? driftFiles(cwd, range) : null;
+  if (!range || !drifted) return stale(`the change since ${since.slice(0, 12)} cannot be read`);
+  let files = drifted;
+  if (range.fromFork !== range.toFork) {
+    // A rebase: the branch's own change is what the head changes against the
+    // judged head replayed onto the new fork (trunk's lines left out; a
+    // conflict holds markers, so its resolution counts). Unreadable: every
+    // drifted file stays, none cosmetic (fail closed).
+    const tree = replayTree(cwd, range.from, range.fromFork, range.toFork);
+    const own = tree ? laneFiles(cwd, tree, range.to, range.toFork) : null;
+    if (own && !own.length) return { carries: true, rule: "rebase", since, files: [] };
+    // Across a moved fork no edit counts as cosmetic (#334): only an exact
+    // replay is left out.
+    if (own) files = own.map((file) => ({ ...file, cosmetic: false }));
+  }
+  const bookkeeping = bookkeepingPaths(cwd, {
+    from: input.from,
+    to: input.to,
+    base: range.toFork,
+    paths: files.map((file) => file.path),
+  });
+  files = files.map((file) => (bookkeeping.has(file.path) ? { ...file, generated: true } : file));
+  // Repo risk paths from both base revisions: they only tighten.
+  const riskPaths = [range.fromFork, range.toFork].flatMap((fork) =>
+    parseRiskPaths(fileAt(cwd, fork, RISK_PATHS_FILE) ?? ""),
+  );
+  const lane = computeLane({ files, riskPaths });
+  const paths = files.map((file) => file.path);
+  if (lane.lane === "none") return { carries: true, rule: "lane-none", since, files: paths };
+  // Tests cannot change what the code does: a unit verdict keeps any size
+  // of test-only follow-up, off risk paths, with nothing opaque.
+  if (input.kind === "unit" && lane.riskFiles.length === 0 && files.every(testOnly))
+    return { carries: true, rule: "tests-only", since, files: paths };
+  return stale(lane.reasons[0] ?? `lane ${lane.lane}`, paths, lane.lane === "self");
+}

package/src/core/policy/check-evidence.ts

@@ -0,0 +1,115 @@
+// Which configured checks a verdict needs on a head, and whether each has
+// fresh evidence there (#509): a local `workit check` run on that exact
+// commit, or (where the lane lets CI cover it) a green CI check of that name.
+// A focused lane lets CI cover a check; a full lane needs a local run.
+import { gateCheckNames, loadCheckConfig } from "../../check-config";
+import { branchLane, type ReviewLane } from "./lane";
+
+export type CheckEvidenceStatus = "fresh" | "failing" | "missing";
+
+export type CheckEvidence = {
+  name: string;
+  status: CheckEvidenceStatus;
+  /** Where the fresh (or failing) evidence came from. */
+  via: "local" | "ci" | null;
+  /** Whether green CI may stand in for a local run at this lane. */
+  ciCovers: boolean;
+};
+
+export type CheckEvidenceDoc = {
+  lane: ReviewLane;
+  head: string;
+  /** Every configured check the verdict needs; empty for a lane without a verdict. */
+  needed: CheckEvidence[];
+  /** True when every needed check has fresh evidence (vacuously true when none is needed). */
+  satisfied: boolean;
+};
+
+export type LocalCheckRow = { name: string; head: string; dirty: boolean; passed: boolean };
+export type CiCheck = { name: string; state: "passing" | "failing" | "pending" };
+
+/** The aggregate `check` script repeats the others; it is never asked for on its own. */
+const AGGREGATE = "check";
+
+/** The checks a lane's verdict needs, from the configured gate names. */
+export function neededChecks(lane: ReviewLane, configured: readonly string[]): string[] {
+  if (lane !== "focused" && lane !== "full") return [];
+  const names = configured.filter((name) => name !== AGGREGATE);
+  return names.length ? names : [...configured];
+}
+
+/** The check name as a whole word of the CI job name: `lint` is not `(commitlint)`. */
+const ciMatch = (ci: CiCheck, name: string): boolean =>
+  new RegExp(
+    `(^|[^a-z0-9])${name.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}([^a-z0-9]|$)`,
+    "iu",
+  ).test(ci.name);
+
+/** The observed `workit check` rows of a ledger, as evidence input. */
+export function localCheckRows(rows: readonly Record<string, unknown>[]): LocalCheckRow[] {
+  return rows
+    .filter((row) => row.type === "check" && row.observer === "workit_cli")
+    .map((row) => ({
+      name: String(row.name ?? ""),
+      head: String(row.head ?? ""),
+      dirty: row.dirty === true,
+      passed: row.result === "passed",
+    }));
+}
+
+/** The evidence of `head` on `branch` (local runs only; CI is read by `pr status`). */
+export function verdictEvidence(
+  cwd: string,
+  input: { head: string; base?: string | null; rows: readonly Record<string, unknown>[] },
+): CheckEvidenceDoc {
+  const lane = branchLane(cwd, { base: input.base ?? null, head: input.head });
+  return checkEvidence({
+    lane: lane.lane,
+    head: input.head,
+    configured: gateCheckNames(loadCheckConfig(cwd), "verification"),
+    local: localCheckRows(input.rows),
+    ci: [],
+  });
+}
+
+export function checkEvidence(input: {
+  lane: ReviewLane;
+  head: string;
+  configured: readonly string[];
+  /** Observed `workit check` runs, oldest first. */
+  local: readonly LocalCheckRow[];
+  ci: readonly CiCheck[];
+}): CheckEvidenceDoc {
+  const ciCovers = input.lane === "focused";
+  const needed = neededChecks(input.lane, input.configured).map((name): CheckEvidence => {
+    const last = input.local.findLast(
+      (row) => row.name === name && row.head === input.head && !row.dirty,
+    );
+    if (last?.passed) return { name, status: "fresh", via: "local", ciCovers };
+    const ci = input.ci.filter((check) => ciMatch(check, name));
+    if (ci.some((check) => check.state === "failing"))
+      return { name, status: "failing", via: "ci", ciCovers };
+    if (last) return { name, status: "failing", via: "local", ciCovers };
+    if (ciCovers && ci.some((check) => check.state === "passing"))
+      return { name, status: "fresh", via: "ci", ciCovers };
+    return { name, status: "missing", via: null, ciCovers };
+  });
+  return {
+    lane: input.lane,
+    head: input.head,
+    needed,
+    satisfied: needed.every((item) => item.status === "fresh"),
+  };
+}
+
+/** One line per check for a status render. */
+export function evidenceLines(doc: CheckEvidenceDoc): string[] {
+  if (!doc.needed.length) return [`evidence: lane ${doc.lane} needs no check run`];
+  return [
+    `evidence for lane ${doc.lane} on ${doc.head.slice(0, 7)}: ${doc.satisfied ? "complete" : "incomplete"}`,
+    ...doc.needed.map(
+      (item) =>
+        `  ${item.status === "fresh" ? "ok" : "x"} ${item.name}: ${item.status}${item.via ? ` (${item.via})` : item.ciCovers ? " (run it, or green CI covers it)" : " (run workit check " + item.name + " on this head)"}`,
+    ),
+  ];
+}

package/src/core/policy/current-judgment.ts

@@ -0,0 +1,20 @@
+import type { Judgment } from "../task-contract";
+import { TaskStore } from "../task-store";
+import { latestJudgment } from "./derive";
+
+/** The open task's latest judgment (the one policy/derive.ts reads), or null when none is recorded. Never throws. */
+export function currentJudgment(cwd: string): Judgment | null {
+  try {
+    const store = new TaskStore(cwd);
+    const listed = store.listTaskIndex();
+    const key = store.currentKey();
+    if (!listed.ok || !key.ok) return null;
+    const entry = listed.data
+      .filter((item) => item.key === key.data.key && item.status !== "closed")
+      .toSorted((left, right) => right.updatedAt.localeCompare(left.updatedAt))[0];
+    const task = entry ? store.readTask(entry.id) : null;
+    return task?.ok === true ? latestJudgment(task.data) : null;
+  } catch {
+    return null;
+  }
+}